Skip to main content

​
Gateway サービスランブック

このページは、Gateway サービスの day-1 起動および day-2 運用に使用してください。

Deep troubleshooting

症状別の診断ガイド（正確なコマンド手順およびログシグネチャ付き）。

Configuration

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

​
5分でローカル起動

1

Start the Gateway

2

Verify service health

正常なベースライン: Runtime: running および RPC probe: ok。
3

Validate channel readiness

Gateway の設定リロードは、アクティブな設定ファイルパス（profile/state のデフォルトから解決、または OPENCLAW_CONFIG_PATH が設定されている場合はそれ）を監視します。 デフォルトモード: gateway.reload.mode="hybrid"（安全な変更はホット適用、重大な変更は再起動）。

​
ランタイムモデル

  • ルーティング、コントロールプレーン、およびチャネル接続のための常時稼働プロセス。
  • 以下のための単一の多重化ポート:
    • WebSocket コントロール/RPC
    • OpenResponses（HTTP）: /v1/responses。
    • コントロール UI とフック
  • デフォルトのバインドモード: loopback。
  • Gateway の認証はデフォルトで必須です。gateway.auth.token（または OPENCLAW_GATEWAY_TOKEN）もしくは gateway.auth.password を設定してください。Tailscale Serve のアイデンティティを使用しない限り、クライアントは connect.params.auth.token/password を送信する必要があります。 クライアントは Tailscale Serve ID を使用しない限り、connect.params.auth.token/password を送信する必要があります。

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

​
ホットリロードモード

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

​
リモートアクセス

推奨: Tailscale/VPN。 フォールバック: SSHトンネル。
クライアントはトンネル経由で ws://127.0.0.1:18789 に接続します。
トークンが設定されている場合、トンネル経由であってもクライアントは connect.params.auth.token にトークンを含める必要があります。
参照: Remote Gateway, Authentication, Tailscale。

​
監視およびサービスライフサイクル

本番相当の信頼性を確保するには supervised 実行を使用してください。
LaunchAgent のラベルは ai.openclaw.gateway（デフォルト）または ai.openclaw.<profile>``（名前付きプロファイル）。 openclaw doctor` はサービス設定のドリフトを監査し、修復します。

​
複数 Gateway（同一ホスト）

ほとんどのセットアップでは 1つ の Gateway を実行するべきです。 厳密な分離や冗長性が必要な場合（例: レスキュープロファイル）のみ複数を使用してください。 インスタンスごとのチェックリスト:
  • 一意の gateway.port
  • 一意の OPENCLAW_CONFIG_PATH
  • 一意の OPENCLAW_STATE_DIR
  • 一意の agents.defaults.workspace
例:
参照: Multiple gateways。

​
Dev プロファイル（--dev）

デフォルトでは分離された state/config とベース Gateway ポート 19001 が含まれます。

​
プロトコル（オペレーター視点）

  • 最初のクライアントフレームは connect である必要があります。
  • Gateway は hello-ok スナップショット（presence, health, stateVersion, uptimeMs, limits/policy）を返します。
  • リクエスト: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
  • 一般的なイベント: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown。
Agent の実行は2段階です:
  1. 即時の受理 ack（status:"accepted"）
  2. agent のレスポンスは 2 段階です。まず res の ack {runId,status:"accepted"}、次に実行完了後の最終 res {runId,status:"ok"|"error",summary}。ストリーミング出力は event:"agent" として到着します。
完全なドキュメント: Gateway protocol および Bridge protocol（レガシー）。

​
運用チェック

​
稼働確認

  • WS を開いて connect を送信します。
  • スナップショット付きの hello-ok レスポンスが返ることを確認してください。

​
準備状況

​
ギャップリカバリー

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

​
一般的な障害シグネチャ

Gatewayが利用できない場合、Gatewayプロトコルクライアントは即座に失敗します（暗黙のダイレクトチャネルフォールバックはありません）。

​
安全性の保証

  • 正常終了時には、ソケットが閉じられる前に shutdown イベントが送出されます。
  • 接続以外の最初のフレームや不正な JSON は拒否され、ソケットはクローズされます。
  • 関連:
Troubleshooting