Bridge 協定（舊版節點傳輸）

Bridge 協定是舊版的節點傳輸方式（TCP JSONL）。新的節點客戶端應改用統一的 Gateway WebSocket 協定。

如果你正在開發 operator 或節點客戶端，請使用 Gateway 協定。

**注意：**目前的 OpenClaw 版本已不再內建 TCP bridge 監聽器；本文件僅作歷史參考。 舊版 bridge.* 設定鍵已不屬於設定 schema 的一部分。

為什麼同時存在兩者

• 安全邊界：bridge 只開放一個小型白名單，而非完整的 gateway API 介面。
• 配對 + 節點身份：節點准入由 gateway 管理，綁定到每個節點的 token。
• 探索體驗：節點可以透過區網 Bonjour 發現 gateway，或直接透過 tailnet 連線。
• Loopback WS：完整的 WS 控制平面保持在本地，除非透過 SSH 通道轉發。

傳輸方式

• TCP，每行一個 JSON 物件（JSONL）。
• 可選 TLS（當 bridge.tls.enabled 為 true 時）。
• 舊版預設監聽埠為 18790（目前版本不啟動 TCP bridge）。

啟用 TLS 時，探索 TXT 記錄會包含 bridgeTls=1 和 bridgeTlsSha256 作為非機密提示。需注意 Bonjour/mDNS TXT 記錄未經驗證，客戶端不可在沒有使用者明確意圖或其他帶外驗證的情況下，將廣播的指紋當作權威釘選值。

握手 + 配對

1. 客戶端傳送 hello，附帶節點中繼資料和 token（如果已配對）。
2. 如果未配對，gateway 回覆 error（NOT_PAIRED/UNAUTHORIZED）。
3. 客戶端傳送 pair-request。
4. Gateway 等待核准，然後傳送 pair-ok 和 hello-ok。

hello-ok 會回傳 serverName，也可能包含 canvasHostUrl。

訊框

客戶端 → Gateway：

• req / res：範圍限定的 gateway RPC（chat、sessions、config、health、voicewake、skills.bins）
• event：節點信號（語音轉錄、agent 請求、chat 訂閱、exec 生命週期）

Gateway → 客戶端：

• invoke / invoke-res：節點指令（canvas.*、camera.*、screen.record、 location.get、sms.send）
• event：已訂閱 session 的 chat 更新
• ping / pong：保活

舊版白名單實作位於 src/gateway/server-bridge.ts（已移除）。

Exec 生命週期事件

節點可以發送 exec.finished 或 exec.denied 事件來呈現 system.run 活動。 這些事件會在 gateway 中對應到系統事件。（舊版節點可能仍會發送 exec.started。）

Payload 欄位（除非標註為必填，否則皆為可選）：

• sessionKey（必填）：接收系統事件的 agent session。
• runId：用於分組的唯一 exec id。
• command：原始或格式化的指令字串。
• exitCode、timedOut、success、output：完成細節（僅 finished）。
• reason：拒絕原因（僅 denied）。

Tailnet 使用方式

• 將 bridge 繫結到 Tailnet IP：在 ~/.openclaw/openclaw.json 設定 bridge.bind: "tailnet"。
• 客戶端透過 MagicDNS 名稱或 Tailnet IP 連線。
• Bonjour 無法跨網路；需要時請使用手動指定 host/port 或廣域 DNS-SD。

版本

Bridge 目前是隱含 v1（沒有 min/max 協商機制）。預期向下相容；在任何破壞性變更前，應先加入 bridge 協定版本欄位。