Bridge protocol（ブリッジプロトコル）（レガシーノードトランスポート）

ブリッジプロトコルは レガシー ノードトランスポート（TCP JSONL）です。新しいノードクライアントは、代わりに統一された Gateway WebSocket プロトコルを使用する必要があります。

オペレーターまたはノードクライアントを構築している場合は、 Gateway protocol を使用してください。

注意： 現在の OpenClaw ビルドは TCP ブリッジリスナーを含まなくなりました。このドキュメントは歴史的な参照のために保持されています。レガシーの bridge.* 設定キーは設定スキーマの一部ではなくなりました。

なぜ両方があるのか

  • セキュリティ境界：ブリッジは、完全なゲートウェイ API サーフェスではなく、小さな許可リストを公開します。
  • ペアリング + ノード ID：ノードの受け入れはゲートウェイが所有し、ノードごとのトークンに結び付けられています。
  • ディスカバリー UX：ノードは LAN 上で Bonjour 経由でゲートウェイを発見するか、Tailnet 経由で直接接続できます。
  • ループバック WS：完全な WS コントロールプレーンは、SSH 経由でトンネリングされない限り、ローカルのままです。

トランスポート

  • TCP、1 行ごとに 1 つの JSON オブジェクト（JSONL）。
  • オプションの TLS（bridge.tls.enabled が true の場合）。
  • レガシーのデフォルトリスナーポートは 18790 でした（現在のビルドは TCP ブリッジを起動しません）。

TLS が有効な場合、ディスカバリー TXT レコードには bridgeTls=1 と bridgeTlsSha256 が含まれ、ノードが証明書をピン留めできます。

ハンドシェイク + ペアリング

  1. クライアントはノードメタデータ + トークン（既にペアリングされている場合）を含む hello を送信します。
  2. ペアリングされていない場合、ゲートウェイは error（NOT_PAIRED/UNAUTHORIZED）を返します。
  3. クライアントは pair-request を送信します。
  4. ゲートウェイは承認を待ち、その後 pair-ok と hello-ok を送信します。

hello-ok は serverName を返し、canvasHostUrl を含む場合があります。

フレーム

クライアント → ゲートウェイ：

  • req / res：スコープ付きゲートウェイ RPC（chat、sessions、config、health、voicewake、skills.bins）
  • event：ノードシグナル（音声トランスクリプト、エージェントリクエスト、チャットサブスクライブ、exec ライフサイクル）

ゲートウェイ → クライアント：

  • invoke / invoke-res：ノードコマンド（canvas.*、camera.*、screen.record、location.get、sms.send）
  • event：サブスクライブされたセッションのチャット更新
  • ping / pong：キープアライブ

レガシーの許可リスト実施は src/gateway/server-bridge.ts にありました（削除済み）。

Exec ライフサイクルイベント

ノードは exec.finished または exec.denied イベントを発行して、system.run アクティビティを表面化できます。これらはゲートウェイ内でシステムイベントにマッピングされます。（レガシーノードは依然として exec.started を発行する可能性があります。）

ペイロードフィールド（特に明記されていない限りすべてオプション）：

  • sessionKey（必須）：システムイベントを受信するエージェントセッション。
  • runId：グループ化のための一意の exec ID。
  • command：生のまたはフォーマットされたコマンド文字列。
  • exitCode、timedOut、success、output：完了詳細（finished のみ）。
  • reason：拒否理由（denied のみ）。

Tailnet の使用

  • ブリッジを Tailnet IP にバインド：~/.openclaw/openclaw.json で bridge.bind: "tailnet"。
  • クライアントは MagicDNS 名または Tailnet IP 経由で接続します。
  • Bonjour はネットワークを 越えられません；必要に応じて手動のホスト/ポートまたは広域 DNS‑SD を使用してください。

バージョニング

ブリッジは現在 暗黙の v1 です（最小/最大交渉なし）。後方互換性が期待されています。破壊的な変更の前にブリッジプロトコルバージョンフィールドを追加してください。

← ドキュメントに戻る