Gateway 運用手順書

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

5分で行うローカル起動

openclaw gateway --port 18789# デバッグ／トレースを標準入出力にも出力openclaw gateway --port 18789 --verbose# 選択したポートのリスナーを強制終了してから起動openclaw 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 ルート
  • コントロール 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/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 の起動時には、非ループバックバインド用のローカルコントロール 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 を実行します。1つの Gateway で複数のエージェントとチャネルをホストできます。複数の Gateway が必要なのは、意図的に分離する場合やレスキューボットを用意する場合のみです。

便利な確認コマンド：

openclaw gateway status --deepopenclaw gateway probe

想定される動作：

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