> ## Documentation Index
> Fetch the complete documentation index at: https://openclawdoc.org/llms.txt
> Use this file to discover all available pages before exploring further.

> 旧式ノード向け TCP JSONL ブリッジの通信方式、ペアリング、フレーム、exec イベント、Tailnet 利用時の注意を整理します。

# ブリッジプロトコル

ブリッジ（Bridge）プロトコルは、**レガシー（旧式）** なノード通信路 (TCP JSONL) です。新しいノードクライアントを開発する場合は、代わりに統合されたゲートウェイ WebSocket プロトコルを使用してください。

オペレーター用またはノード用のクライアントを構築する場合は、[ゲートウェイプロトコル](/gateway/protocol) を参照してください。

**注意:** 現在の OpenClaw ビルドには TCP ブリッジリスナーは同梱されていません。本ドキュメントは歴史的なリファレンスとして残されています。レガシーな `bridge.*` 構成キーは、現在の構成スキーマからは削除されています。

## なぜ 2 つのプロトコルがあるのか

* **セキュリティ境界**: ブリッジは、ゲートウェイの全 API ではなく、許可リスト（allowlist）に基づいた最小限の機能のみを公開します。
* **ペアリングとノード識別**: ノードの参加許可はゲートウェイが管理し、ノードごとのトークンに紐付けられます。
* **検出体験 (UX)**: ノードは LAN 上の Bonjour 経由でゲートウェイを自動検出したり、Tailnet 経由で直接接続したりできます。
* **ループバック WS**: 完全な WebSocket コントロールプレーンは、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 (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`: グループ化のための一意の実行 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** です（最小/最大バージョンの交渉機能はありません）。後方互換性が期待されます。破壊的な変更を行う前に、ブリッジプロトコルのバージョンフィールドを追加する必要があります。