Gateway

Gateway ランブック

このページは、Gateway サービスの初回起動（デイ1）および継続運用（デイ2）に使用してください。

詳細トラブルシューティング

症状から始める診断、正確なコマンドラダーとログシグネチャ。

設定

タスク指向のセットアップガイド + 完全な設定リファレンス。

シークレット管理

SecretRef 契約、ランタイムスナップショットの動作、移行/リロード操作。

シークレットプラン契約

正確なシークレット適用ターゲット/パスルールと ref-only auth-profile の動作。

5分でのローカル起動

ステップ 1: Gateway を起動する

openclaw gateway --port 18789
# debug/trace は stdio にもミラーリング
openclaw gateway --port 18789 --verbose
# 選択したポートのリスナーを強制終了してから起動
openclaw gateway --force

ステップ 2: サービスヘルスを確認する

openclaw gateway status
openclaw status
openclaw logs --follow

健全な基準: Runtime: running および RPC probe: ok。

ステップ 3: チャネルの準備状態を検証する

openclaw channels status --probe

ℹ️ Gateway 設定のリロードは、アクティブな設定ファイルパス（プロファイル/状態のデフォルトから解決、または OPENCLAW_CONFIG_PATH が設定されている場合はそれ）を監視します。デフォルトモードは gateway.reload.mode="hybrid" です。

ランタイムモデル

  • ルーティング、コントロールプレーン、チャネル接続用の常時稼働プロセスが1つ。
  • 単一の多重化ポートが以下を提供:
    • WebSocket コントロール/RPC
    • HTTP API (OpenAI互換、Responses、ツール呼び出し)
    • コントロールUIとフック
  • デフォルトバインドモード: loopback。
  • デフォルトでは認証が必要 (gateway.auth.token / gateway.auth.password、または OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD)。

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

設定解決順序
Gateway ポート--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
バインドモードCLI/オーバーライド → gateway.bind → loopback

ホットリロードモード

gateway.reload.mode動作
off設定リロードなし
hotホットセーフな変更のみ適用
restartリロードが必要な変更時に再起動
hybrid (デフォルト)安全な場合はホット適用、必要な場合は再起動

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

openclaw gateway status
openclaw gateway status --deep
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

リモートアクセス

推奨: Tailscale/VPN。代替: SSH トンネル。

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

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

⚠️ ゲートウェイ認証が設定されている場合、クライアントは SSH トンネル経由でも認証 (token/password) を送信する必要があります。

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

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

本番環境に近い信頼性のために、監視付き実行を使用してください。

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

1ホスト上の複数ゲートウェイ

ほとんどのセットアップでは、1つの 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

参照: 複数ゲートウェイ。

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

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

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

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

  • 最初のクライアントフレームは connect でなければならない。
  • Gateway は hello-ok スナップショット (presence, health, stateVersion, uptimeMs, 制限/ポリシー) を返す。
  • リクエスト: req(method, params) → res(ok/payload|error)。
  • 一般的なイベント: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown。

エージェント実行は2段階:

  1. 即時受理応答 (status:"accepted")
  2. 最終完了応答 (status:"ok"|"error")、その間に agent イベントがストリーミングされる。

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

運用チェック

生存性

  • WS を開き、connect を送信。
  • スナップショット付きの hello-ok 応答を期待。

準備完了状態

openclaw gateway status
openclaw channels status --probe
openclaw health

ギャップ回復

イベントは再生されません。シーケンスギャップ発生時は、続行前に状態 (health, system-presence) を更新してください。

一般的な障害シグネチャ

シグネチャ可能性の高い問題
refusing to bind gateway ... without authトークン/パスワードなしでの非ループバックバインド
another gateway instance is already listening / EADDRINUSEポート競合
Gateway start blocked: set gateway.mode=local設定がリモートモードに設定されている
unauthorized (接続中)クライアントとゲートウェイ間の認証不一致

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

安全性の保証

  • Gateway プロトコルクライアントは、Gateway が利用できない場合に高速に失敗する（暗黙的な直接チャネルフォールバックなし）。
  • 無効な/非接続の最初のフレームは拒否され、クローズされる。
  • グレースフルシャットダウンは、ソケットクローズ前に shutdown イベントを発行する。

関連項目:

設定