橋接協定

# 它存在的原因

• 安全邊界：橋接器公開一個小型允許清單，而不是完整的 Gateway API 表面。
• 配對 + Node 身分：Node 准入由 Gateway 擁有，並繫結至 每個 Node 專屬的權杖。
• 探索使用者體驗：Node 可以透過區域網路上的 Bonjour 探索 Gateway，或 直接透過 tailnet 連線。
• Loopback WS：完整的 WS 控制平面會保持在本機，除非透過 SSH 通道傳輸。

# 傳輸

• TCP，每行一個 JSON 物件 (JSONL)。
• 選用 TLS（當 bridge.tls.enabled 為 true 時）。
• 歷史預設監聽器連接埠是 18790（目前建置不會啟動 TCP 橋接器）。

啟用 TLS 時，探索 TXT 記錄會包含 bridgeTls=1，以及作為非秘密提示的 bridgeTlsSha256。請注意，Bonjour/mDNS TXT 記錄未經驗證；用戶端不得在沒有明確使用者意圖或其他帶外驗證的情況下，將宣告的指紋視為具權威性的釘選。

# 握手 + 配對

1. 用戶端傳送帶有 Node 中繼資料 + 權杖（如果已配對）的 hello。
2. 如果尚未配對，Gateway 會回覆 error (NOT_PAIRED/UNAUTHORIZED)。
3. 用戶端傳送 pair-request。
4. Gateway 等待核准，然後傳送 pair-ok 和 hello-ok。

過去，hello-ok 會傳回 serverName；託管的 Plugin 表面現在會透過 pluginSurfaceUrls 宣告。Canvas/A2UI 使用 pluginSurfaceUrls.canvas；已棄用的 canvasHostUrl 別名不屬於 重構後的通訊協定。

# 框架

用戶端 → Gateway：

• req / res：具範圍的 Gateway RPC（聊天、工作階段、設定、健康狀態、語音喚醒、skills.bins）
• event：Node 訊號（語音轉錄、代理請求、聊天訂閱、執行生命週期）

Gateway → 用戶端：

• invoke / invoke-res：Node 命令（canvas.*、camera.*、screen.record、 location.get、sms.send）
• event：已訂閱工作階段的聊天更新
• ping / pong：保持連線

舊版允許清單強制執行位於 src/gateway/server-bridge.ts（已移除）。

# 執行生命週期事件

Node 可以發出 exec.finished 或 exec.denied 事件，以公開 system.run 活動。 這些事件會在 Gateway 中對應到系統事件。（舊版 Node 可能仍會發出 exec.started。）

酬載欄位（除非註明，否則皆為選用）：

• sessionKey（必填）：接收系統事件的代理工作階段。
• runId：用於分組的唯一執行 ID。
• command：原始或格式化的命令字串。
• exitCode、timedOut、success、output：完成詳細資料（僅 finished）。
• reason：拒絕原因（僅 denied）。

# 歷史 tailnet 用法

• 將橋接器繫結至 tailnet IP：在 ~/.openclaw/openclaw.json 中設定 bridge.bind: "tailnet"（僅供歷史參考；bridge.* 不再有效）。
• 用戶端透過 MagicDNS 名稱或 tailnet IP 連線。
• Bonjour 不會跨網路；需要時請使用手動主機/連接埠或廣域 DNS-SD。

# 版本控制

橋接器是隱含 v1（沒有最小/最大協商）。本節 僅供歷史參考；目前的 Node/操作員用戶端使用 WebSocket Gateway Protocol。

# 相關

• Gateway protocol
• Nodes