Gateway 運用手順書

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

5分で行うローカル起動

openclaw gateway --port 18789# debug/trace を標準入出力に複製openclaw gateway --port 18789 --verbose# 選択したポートのリスナーを強制終了してから起動openclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

ランタイムモデル

• ルーティング、コントロールプレーン、チャネル接続を担う、常時稼働の単一プロセス。
• 次の用途に使用する単一の多重化ポート：
  • WebSocket コントロール／RPC
  • HTTP API（/v1/models、/v1/embeddings、/v1/chat/completions、/v1/responses、/tools/invoke）
  • 任意の /api/v1/admin/rpc などの Plugin HTTP ルート
  • コントロール UI とフック
• デフォルトのバインドモード：loopback。コンテナ環境が検出された場合、実効デフォルトは auto（ポートフォワーディング用に 0.0.0.0 へ解決）です。ただし、Tailscale serve/funnel がアクティブな場合は、常に loopback が強制されます。
• デフォルトで認証が必要です。共有シークレット構成では gateway.auth.token／gateway.auth.password（または OPENCLAW_GATEWAY_TOKEN／OPENCLAW_GATEWAY_PASSWORD）を使用し、非 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 の起動時には、非 loopback バインド用のローカルなコントロール 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   # システムレベルのサービススキャンを追加openclaw 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

想定される動作：

• 古い launchd/systemd/schtasks インストールが残っている場合、gateway status --deep は Other gateway-like services detected (best effort) を報告し、クリーンアップのヒントを表示することがあります。
• 異なる Gateway が応答する場合、または到達可能なターゲットが同じ Gateway であると OpenClaw が証明できない場合、gateway probe は 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@gateway-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 $(whoami)

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=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

無効な設定エラーは終了コード 78 で終了します。Linux systemd ユニットは RestartPreventExitStatus=78 を使用し、設定が修正されるまで再起動を停止します。launchd と Windows Task Scheduler には終了コードごとに停止する同等のルールがないため、Gateway は短時間に繰り返された異常起動の履歴も永続化し、起動失敗が繰り返された後はチャネル／プロバイダーアカウントの自動起動を抑止します。このセーフモードでもコントロールプレーンは検査と修復のために起動しますが、設定のホットリロードと secrets.reload はチャネルの自動再起動を拒否します。オペレーターが明示的に channels.start を要求すると、この抑止をオーバーライドできます。

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

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

デフォルトには、分離された状態／設定と、Gateway の基本ポート 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、オプトインの session.approval、sessions.changed、presence、tick、health、 heartbeat、ペアリング/承認のライフサイクルイベント、shutdown が含まれます。

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

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

完全なプロトコルドキュメントについては、Gateway プロトコルを参照してください。

運用チェック

稼働確認

• WS を開いて connect を送信します。
• スナップショットを含む hello-ok 応答を確認します。

準備完了確認

openclaw gateway statusopenclaw channels status --probeopenclaw health

ギャップからの復旧

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

よくある障害の兆候

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

安全性の保証

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

関連項目

• 設定
• Gateway のトラブルシューティング
• バックグラウンドプロセス
• ヘルス
• Doctor
• 認証
• リモートアクセス
• シークレット管理