このページは、Gatewayサービスの1日目の起動と2日目以降の運用に使用します。Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
詳細なトラブルシューティング
正確なコマンド手順とログシグネチャを使った、症状起点の診断。
設定
タスク指向のセットアップガイドと完全な設定リファレンス。
シークレット管理
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、OpenAI互換（
/v1/models、/v1/embeddings、/v1/chat/completions、/v1/responses、/tools/invoke） - コントロールUIとフック
- デフォルトのバインドモード:
loopback。 - 認証はデフォルトで必須です。共有シークレットのセットアップでは
gateway.auth.token/gateway.auth.password（またはOPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORD）を使用し、非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を使用します。それ以外の場合は、選択されたエージェントの通常のモデルと埋め込み設定が制御を維持します。
ポートとバインドの優先順位
| 設定 | 解決順序 |
|---|---|
| Gatewayポート | --port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789 |
| バインドモード | CLI/override → gateway.bind → loopback |
--portをスーパーバイザーメタデータに記録します。gateway.portを変更した後は、launchd/systemd/schtasksが新しいポートでプロセスを起動するように、openclaw doctor --fixまたはopenclaw gateway install --forceを実行します。
Gateway起動では、非loopbackバインド用のローカル
コントロール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台のマシンにつき1つのGatewayを実行するべきです。単一のGatewayで複数の エージェントとチャネルをホストできます。 意図的に分離やレスキューボットが必要な場合にのみ、複数のGatewayが必要です。 有用な確認:gateway status --deepは、古いlaunchd/systemd/schtasksインストールがまだ残っている場合にOther gateway-like services detected (best effort)を報告し、クリーンアップのヒントを出力できます。- 複数のターゲットが応答する場合、
gateway probeはmultiple reachable gatewaysについて警告できます。 - それが意図したものである場合は、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.tool、sessions.changed、presence、tick、health、heartbeat、ペアリング/承認ライフサイクルイベント、shutdownが含まれます。
- 即時の受理確認（
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イベントが発行されます。
関連: