Gateway ランブック

このページは、Gateway サービスの初日立ち上げと 2日目以降の運用に使用します。

5分でのローカル起動

openclaw gateway --port 18789# debug/trace mirrored to stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

ランタイムモデル

• ルーティング、コントロールプレーン、チャネル接続のための常時稼働プロセスが 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/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/chat/completions
• POST /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 の残りと同じ信頼済みオペレーター認証境界を使用します。

管理用 HTTP RPC（POST /api/v1/admin/rpc）は、WebSocket RPC を使用できないホストツール向けの、別個のデフォルトオフ Plugin ルートです。管理用 HTTP RPC を参照してください。

ポートとバインドの優先順位

インストール済みの Gateway サービスは、解決された --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 に明示的に追加してください。

ホットリロードモード

オペレーターコマンドセット

openclaw gateway statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep は追加のサービス検出（LaunchDaemons/systemd システム ユニット/schtasks）用であり、より深い RPC 健全性プローブではありません。

複数の Gateway（同一ホスト）

ほとんどのインストールでは、マシンごとに 1つの Gateway を実行すべきです。単一の Gateway で複数の エージェントとチャネルをホストできます。

意図的に分離したい場合、またはレスキューボットが必要な場合にのみ、複数の Gateway が必要です。

有用なチェック:

openclaw gateway status --deepopenclaw gateway probe

想定される内容:

• 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

例:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

詳細なセットアップ: /gateway/multiple-gateways。

リモートアクセス

推奨: Tailscale/VPN。 フォールバック: SSH トンネル。

ssh -N -L 18789:127.0.0.1:18789 user@host

その後、クライアントをローカルで ws://127.0.0.1:18789 に接続します。

参照: リモート Gateway、認証、Tailscale。

監視とサービスライフサイクル

本番に近い信頼性のために、監視付き実行を使用します。

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

sudo systemctl daemon-reloadsudo systemctl enable --now openclaw-gateway[-<profile>].service

開発プロファイルのクイックパス

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

デフォルトには、分離された状態/設定とベース Gateway ポート 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 が含まれます。

エージェント実行は 2段階です。

1. 即時の受理 ack（status:"accepted"）
2. 最終完了レスポンス（status:"ok"|"error"）。その間に agent イベントがストリーミングされます。

完全なプロトコルドキュメントを参照: Gateway プロトコル。

運用チェック

Liveness

• WS を開き、connect を送信します。
• スナップショット付きの hello-ok レスポンスを期待します。

Readiness

openclaw gateway statusopenclaw channels status --probeopenclaw health

ギャップ復旧

イベントは再生されません。シーケンスギャップがある場合は、続行する前に状態（health、system-presence）を更新します。

一般的な失敗シグネチャ

完全な診断手順については、Gateway トラブルシューティングを使用してください。

安全性の保証

• Gateway プロトコルクライアントは、Gateway が利用できない場合に即座に失敗します（暗黙の直接チャネルフォールバックはありません）。
• 無効な、または接続ではない最初のフレームは拒否され、閉じられます。
• 正常なシャットダウンでは、ソケットを閉じる前に shutdown イベントが発行されます。

関連:

• トラブルシューティング
• バックグラウンドプロセス
• 設定
• ヘルス
• ドクター
• 認証

関連

• 設定
• Gateway トラブルシューティング
• リモートアクセス
• シークレット管理