詳細なトラブルシューティング
正確なコマンド手順とログシグネチャによる、症状優先の診断。
設定
タスク指向のセットアップガイドと完全な設定リファレンス。
シークレット管理
SecretRef コントラクト、ランタイムスナップショットの動作、移行/リロード操作。
シークレット計画コントラクト
正確な
secrets apply のターゲット/パス規則と、参照のみの認証プロファイル動作。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。 - 認証はデフォルトで必須です。共有シークレットのセットアップでは
gateway.auth.token/gateway.auth.password（またはOPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORD）を使用し、非 local loopback の リバースプロキシセットアップでは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を使用します。それ以外の場合は、選択されたエージェントの通常のモデルと埋め込み設定が制御を維持します。
POST /api/v1/admin/rpc）は、WebSocket RPC を使用できないホストツール向けの、別個のデフォルトオフ Plugin ルートです。管理用 HTTP RPC を参照してください。
ポートとバインドの優先順位
| 設定 | 解決順序 |
|---|---|
| Gateway ポート | --port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789 |
| バインドモード | CLI/オーバーライド → gateway.bind → loopback |
--port をスーパーバイザーメタデータに記録します。gateway.port を変更した後は、launchd/systemd/schtasks が新しいポートでプロセスを起動するように、openclaw doctor --fix または openclaw gateway install --force を実行します。
Gateway 起動時は、非 local loopback バインド用にローカルの
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 ユーザー）
- 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 はサービス設定のずれを監査し、修復します。開発プロファイルのクイックパス
19001 が含まれます。
プロトコルのクイックリファレンス（オペレーター視点）
- 最初のクライアントフレームは
connectである必要があります。 - Gateway は
hello-okスナップショット（presence、health、stateVersion、uptimeMs、制限/ポリシー）を返します。 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イベントがストリーミングされます。
運用チェック
Liveness
- WS を開き、
connectを送信します。 - スナップショット付きの
hello-okレスポンスを期待します。
Readiness
ギャップ復旧
イベントは再生されません。シーケンスギャップがある場合は、続行する前に状態（health、system-presence）を更新します。
一般的な失敗シグネチャ
| シグネチャ | 想定される問題 |
|---|---|
refusing to bind gateway ... without auth | 有効な Gateway 認証パスなしでの非ループバックバインド |
another gateway instance is already listening / EADDRINUSE | ポート競合 |
Gateway start blocked: set gateway.mode=local | 設定がリモートモードになっている、または破損した設定からローカルモードスタンプが欠落している |
unauthorized during connect | クライアントと Gateway の認証不一致 |
安全性の保証
- Gateway プロトコルクライアントは、Gateway が利用できない場合に即座に失敗します（暗黙の直接チャネルフォールバックはありません）。
- 無効な、または接続ではない最初のフレームは拒否され、閉じられます。
- 正常なシャットダウンでは、ソケットを閉じる前に
shutdownイベントが発行されます。
関連: