Gateway 運用手順書

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

# 5分でのローカル起動

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

openclaw gateway status
openclaw status
openclaw logs --follow

openclaw channels status --probe

# ランタイムモデル

• ルーティング、コントロールプレーン、チャンネル接続のための常時稼働プロセス1つ。
• 単一の多重化ポート:
  • WebSocket コントロール/RPC
  • HTTP API、OpenAI 互換（/v1/models、/v1/embeddings、/v1/chat/completions、/v1/responses、/tools/invoke）
  • コントロール UI とフック
• デフォルトのバインドモード: loopback。
• Auth はデフォルトで必須です。共有シークレットのセットアップでは 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 は、常に設定済みのデフォルトエージェントにマップされる安定したエイリアスです。
• バックエンド provider/model の上書きが必要な場合は x-openclaw-model を使用します。それ以外の場合、選択されたエージェントの通常のモデルと埋め込み設定が制御を維持します。

これらはすべてメインの Gateway ポートで実行され、Gateway HTTP API の残りと同じ信頼済みオペレーター auth 境界を使用します。

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

インストール済みの gateway サービスは、解決済みの --port を supervisor メタデータに記録します。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 status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

gateway status --deep は追加のサービス検出（LaunchDaemons/systemd system units/schtasks）用であり、より深い RPC ヘルスプローブではありません。

# 複数の gateway（同一ホスト）

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

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

有用なチェック:

openclaw gateway status --deep
openclaw gateway probe

想定される内容:

• 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

例:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_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 に接続します。

参照: Remote Gateway、Authentication、Tailscale。

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

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

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

sudo loginctl enable-linger <user>

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop

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

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

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

デフォルトには、分離された状態/設定とベース gateway ポート 19001 が含まれます。

# プロトコルクイックリファレンス（オペレーター視点）

• 最初のクライアントフレームは connect である必要があります。
• Gateway は hello-ok スナップショット（presence、health、stateVersion、uptimeMs、limits/policy）を返します。
• 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、pairing/approval ライフサイクルイベント、shutdown が含まれます。

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

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

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

# 運用チェック

# Liveness

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

# Readiness

openclaw gateway status
openclaw channels status --probe
openclaw health

# ギャップリカバリ

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

# 一般的な失敗シグネチャ

完全な診断手順については、Gateway Troubleshooting を使用してください。

# 安全性保証

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

関連:

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

# 関連

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