詳細なトラブルシューティング
症状起点の診断、正確なコマンド手順、ログシグネチャ。
設定
タスク指向のセットアップガイドと完全な設定リファレンス。
シークレット管理
SecretRef コントラクト、実行時スナップショットの挙動、移行/再読み込み操作。
シークレット計画コントラクト
正確な
secrets apply ターゲット/パス規則と参照専用 auth-profile の挙動。5分でのローカル起動
サービスのヘルスを検証する
Runtime: running、Connectivity probe: ok、そして期待内容に一致する Capability 行です。単なる到達可能性ではなく、読み取りスコープの RPC 証明には openclaw gateway status --require-rpc を使用します。Gateway 設定の再読み込みは、アクティブな設定ファイルパス（プロファイル/状態のデフォルトから解決、または
OPENCLAW_CONFIG_PATH が設定されている場合はそれ）を監視します。デフォルトモードは gateway.reload.mode="hybrid" です。最初の読み込み成功後、実行中のプロセスはアクティブなメモリ内設定スナップショットを提供し、再読み込みが成功するとそのスナップショットをアトミックに差し替えます。実行時モデル
- ルーティング、制御プレーン、チャネル接続のための常時稼働プロセス1つ。
- 次のための単一の多重化ポート:
- WebSocket 制御/RPC
- HTTP API（
/v1/models、/v1/embeddings、/v1/chat/completions、/v1/responses、/tools/invoke） - 任意の
/api/v1/admin/rpcなどの Plugin HTTP ルート - Control UI とフック
- デフォルトのバインドモード:
loopback。コンテナ環境が検出された場合、有効なデフォルトはauto（ポートフォワーディング用に0.0.0.0に解決）です。ただし Tailscale serve/funnel がアクティブな場合は常にloopbackが強制されます。 - 認証はデフォルトで必須です。共有シークレットのセットアップでは
gateway.auth.token/gateway.auth.password（またはOPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORD）を使用し、非ループバックのリバースプロキシセットアップではgateway.auth.mode: "trusted-proxy"を使用できます。
OpenAI 互換エンドポイント
OpenClaw の最もレバレッジの高い互換サーフェス:GET /v1/modelsGET /v1/models/{id}POST /v1/embeddingsPOST /v1/chat/completionsPOST /v1/responses
- ほとんどの Open WebUI、LobeChat、LibreChat 連携は最初に
/v1/modelsをプローブします。 - 多くの RAG とメモリパイプラインは
/v1/embeddingsを期待します。 - エージェントネイティブクライアントは、ますます
/v1/responsesを優先しています。
/v1/models はエージェント優先です。設定済みのすべてのエージェントについて、openclaw、openclaw/default、openclaw/<agentId> を返します。openclaw/default は、常に設定済みのデフォルトエージェントにマップされる安定したエイリアスです。バックエンドのプロバイダー/モデルを上書きしたい場合は x-openclaw-model を送信します。そうでない場合は、選択されたエージェントの通常のモデルと埋め込み設定が引き続き制御します。
これらはすべてメインの Gateway ポートで動作し、Gateway HTTP API の他の部分と同じ信頼済みオペレーター認証境界を使用します。
Admin HTTP RPC（POST /api/v1/admin/rpc）は、WebSocket RPC を使用できないホストツール向けの、別個のデフォルトオフの Plugin ルートです。Admin HTTP RPC を参照してください。
ポートとバインドの優先順位
| 設定 | 解決順序 |
|---|---|
| Gateway ポート | --port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789 |
| バインドモード | CLI/override → gateway.bind → loopback（またはコンテナ内では auto） |
--port をスーパーバイザーメタデータに記録します。gateway.port を変更した後は、launchd/systemd/schtasks が新しいポートでプロセスを開始するように、openclaw doctor --fix または openclaw gateway install --force を実行します。
Gateway 起動時は、非ループバックバインド用にローカル Control UI オリジンをシードするときに、同じ有効ポートとバインドを使用します。たとえば、--bind lan --port 3000 は実行時検証が実行される前に http://localhost:3000 と http://127.0.0.1:3000 をシードします。HTTPS プロキシ URL など、リモートブラウザーのオリジンは gateway.controlUi.allowedOrigins に明示的に追加します。
ホットリロードモード
gateway.reload.mode | 挙動 |
|---|---|
off | 設定を再読み込みしない |
hot | ホットセーフな変更のみを適用 |
restart | 再起動が必要な変更で再起動 |
hybrid（デフォルト） | 安全な場合はホット適用し、必要な場合は再起動 |
オペレーターコマンドセット
gateway status --deep は追加のサービス検出（LaunchDaemons/systemd システムユニット/schtasks）用であり、より深い RPC ヘルスプローブではありません。
複数の Gateway（同一ホスト）
ほとんどのインストールでは、マシンごとに1つの Gateway を実行するべきです。単一の Gateway で複数のエージェントとチャネルをホストできます。複数の Gateway が必要なのは、意図的に分離したい場合やレスキューボットが必要な場合だけです。 有用なチェック:gateway status --deepは、古い launchd/systemd/schtasks インストールがまだ残っている場合にOther gateway-like services detected (best effort)を報告し、クリーンアップのヒントを出力することがあります。gateway probeは、別々の Gateway が応答した場合、または OpenClaw が到達可能なターゲットが同じ Gateway であることを証明できない場合に、multiple reachable gateway identitiesについて警告することがあります。同じ Gateway への SSH トンネル、プロキシ URL、または設定済みのリモート URL は、トランスポートポートが異なっていても、複数のトランスポートを持つ1つの Gateway です。- それが意図したものなら、Gateway ごとにポート、設定/状態、ワークスペースルートを分離します。
- 一意の
gateway.port - 一意の
OPENCLAW_CONFIG_PATH - 一意の
OPENCLAW_STATE_DIR - 一意の
agents.defaults.workspace
リモートアクセス
推奨: Tailscale/VPN。 フォールバック: SSH トンネル。ws://127.0.0.1:18789 に接続します。
参照: リモート Gateway、認証、Tailscale。
監視とサービスライフサイクル
本番相当の信頼性には、監視付き実行を使用します。- macOS（launchd）
- Linux（systemd user）
- Windows（ネイティブ）
- Linux（システムサービス）
openclaw gateway restart を使用します。再起動の代替として openclaw gateway stop と openclaw gateway start を連鎖させないでください。macOS では、gateway stop はデフォルトで launchctl bootout を使用します。これは無効化を永続化せずに現在のブートセッションから LaunchAgent を削除するため、予期しないクラッシュ後も KeepAlive による自動復旧が機能し、gateway start でクリーンに再有効化できます。再起動をまたいで自動再生成を永続的に抑制するには、--disable を渡します: openclaw gateway stop --disable。LaunchAgent ラベルは ai.openclaw.gateway（デフォルト）または ai.openclaw.<profile>（名前付きプロファイル）です。openclaw doctor はサービス設定のドリフトを監査して修復します。78 で終了します。Linux systemd ユニットは、設定が修正されるまで再起動を停止するために RestartPreventExitStatus=78 を使用します。launchd と Windows Task Scheduler には同等の終了コードごとの停止ルールがないため、Gateway は急速な異常ブート履歴も永続化し、起動失敗が繰り返された後はチャネル/プロバイダーアカウントの自動開始を抑制します。そのセーフモードでは、検査と修復のために制御プレーンは引き続き起動し、設定のホットリロードと secrets.reload は自動チャネル再起動を拒否し、明示的なオペレーターの channels.start リクエストで抑制を上書きできます。
開発プロファイルのクイックパス
19001 が含まれます。
プロトコルクイックリファレンス（オペレーター視点）
- 最初のクライアントフレームは
connectでなければなりません。 - Gateway は
snapshot（presence、health、stateVersion、uptimeMs）とpolicy制限（maxPayload、maxBufferedBytes、tickIntervalMs）を含むhello-okフレームを返します。 hello-ok.features.methods/eventsは保守的な検出リストであり、呼び出し可能なすべてのヘルパールートを 生成して列挙したものではありません。- リクエスト:
req(method, params)→res(ok/payload|error)。 - 一般的なイベントには、
connect.challenge、agent、chat、session.message、session.operation、session.tool、sessions.changed、presence、tick、health、heartbeat、ペアリング/承認ライフサイクルイベント、 およびshutdownが含まれます。
- 即時の受諾 ack（
status:"accepted"） - 最終完了レスポンス（
status:"ok"|"error"）。その間にagentイベントがストリーミングされます。
運用チェック
ライブネス
- WS を開き、
connectを送信します。 - スナップショット付きの
hello-okレスポンスを期待します。
レディネス
ギャップ復旧
イベントは再生されません。シーケンスの欠落がある場合は、続行する前に状態（health、system-presence）を更新してください。
一般的な失敗シグネチャ
| シグネチャ | 考えられる問題 |
|---|---|
refusing to bind gateway ... without auth | 有効な Gateway 認証パスがない非ループバックバインド |
another gateway instance is already listening / EADDRINUSE | ポート競合 |
Gateway start blocked: set gateway.mode=local | 設定がリモートモードになっている、または破損した設定に gateway.mode がない |
unauthorized during connect | クライアントと Gateway の間の認証不一致 |
安全性の保証
- Gateway プロトコルクライアントは、Gateway が利用できない場合に高速に失敗します（暗黙の直接チャネルフォールバックはありません）。
- 無効な、または connect ではない最初のフレームは拒否され、クローズされます。
- 正常なシャットダウンでは、ソケットを閉じる前に
shutdownイベントが送出されます。