プロトコルとAPI

Bridge Protocol

Bridgeプロトコルはレガシーなノードトランスポート（TCP JSONL）です。新しいノードクライアントは、統合されたGateway WebSocketプロトコルを代わりに使用してください。オペレーターやノードクライアントを構築している場合は、Gatewayプロトコルを使用してください。注記: 現在のOpenClawビルドではTCPブリッジリスナーは同梱されていません。このドキュメントは歴史的参照のために残されています。レガシーな bridge.* 設定キーは設定スキーマの一部ではなくなりました。

両方が存在する理由

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

トランスポート

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

TLSが有効な場合、ディスカバリーTXTレコードには bridgeTls=1 と、非秘密のヒントとして bridgeTlsSha256 が含まれます。Bonjour/mDNS TXTレコードは認証されていないことに注意してください。クライアントは、明示的なユーザー意図や他の帯域外検証なしに、アドバタイズされたフィンガープリントを信頼できるピンとして扱ってはいけません。

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

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

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

フレーム

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

  • req / res: スコープ付きゲートウェイRPC（チャット、セッション、設定、ヘルス、voicewake、skills.bins）
  • event: ノードシグナル（音声文字起こし、エージェントリクエスト、チャット購読、実行ライフサイクル）

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

  • invoke / invoke-res: ノードコマンド (canvas.*, camera.*, screen.record, location.get, sms.send)
  • event: 購読済みセッションのチャット更新
  • ping / pong: キープアライブ

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

実行ライフサイクルイベント

ノードは exec.finished または exec.denied イベントを発行して、system.runアクティビティを表面化させることができます。これらはゲートウェイ内のシステムイベントにマッピングされます。（レガシーノードは exec.started を発行する場合があります。）ペイロードフィールド（特に明記されていない限りすべてオプション）:

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

テールネットの使用

  • ブリッジをテールネットIPにバインド: ~/.openclaw/openclaw.json 内で bridge.bind: "tailnet"。
  • クライアントはMagicDNS名またはテールネットIPを介して接続。
  • Bonjourはネットワークをまたぎません。必要な場合は、手動のホスト/ポートまたは広域DNS‑SDを使用してください。

バージョニング

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

Gateway ProtocolOpenAI Chat Completions