OpenClaw Bridge Protocol：舊版傳輸協議解析

寫過分散式系統的人都知道，最頭痛的往往不是開發新功能，而是處理那些為了相容性而存在的舊版連線協議。當初為了效能或特定環境選了 TCP，後來發現維護起來成本越來越高，甚至需要一套完全不同的安全性邏輯。

如果你正在維護舊有的節點，或者在研究 OpenClaw 的演進過程，這篇關於 Bridge protocol 的紀錄能幫你理清那些已經被 Gateway WebSocket 取代的舊邏輯。

需要準備的東西

• 舊版 OpenClaw 建置：目前的版本已經不再內建 TCP bridge listener。
• 設定檔權限：需要存取 ~/.openclaw/openclaw.json。
• 網路基礎知識：了解 TCP 與 JSONL 格式。

快速開始

雖然 Bridge protocol 已經是 legacy 狀態，但如果你需要與舊系統溝通，這是最快的握手路徑：

1. 建立 TCP 連線：連線至預設 Port 18790。
2. 發送 Hello：傳送包含 node metadata 與 token 的 JSON 物件。
3. 請求配對：如果收到 NOT_PAIRED 錯誤，發送 pair-request。
4. 完成握手：等待 Gateway 回傳 pair-ok 與 hello-ok。

協議核心設計

為什麼當初有兩套協議？

OpenClaw 早期同時保留 Bridge 與 Gateway 協議，主要是基於以下考量：

• Security boundary：Bridge 只會開放一組特定的 allowlist，而不是暴露整個 Gateway API。
• 節點身份識別：節點的准入由 Gateway 統一管理，並與每個節點專屬的 token 綁定。
• 探索體驗：節點可以在區域網路 (LAN) 透過 Bonjour 自動發現 Gateway，或透過 Tailnet 直接連線。
• Loopback WS：完整的 WebSocket 控制平面會保留在本地，除非你透過 SSH tunnel 轉發。

Transport 傳輸層

Bridge 採用 TCP 傳輸，格式為每一行一個 JSON 物件 (JSONL)。

• 支援選配的 TLS 加密（當 bridge.tls.enabled 為 true 時）。
• 當啟用 TLS 時，Bonjour 的 TXT 紀錄會包含 bridgeTls=1 與 bridgeTlsSha256，方便節點進行證書釘選 (Certificate Pinning)。

訊息框架 (Frames)

Client → Gateway

節點會向 Gateway 發送以下請求：

• req / res：針對 Gateway 的 RPC 調用，例如 chat, sessions, config, health, voicewake, skills.bins。
• event：節點發出的訊號，包括語音逐字稿 (voice transcript)、agent 請求、訂閱聊天或執行生命週期 (exec lifecycle)。

Gateway → Client

Gateway 會主動控制節點：

• invoke / invoke-res：執行節點指令，例如 canvas.*, camera.*, screen.record, location.get, sms.send。
• event：已訂閱工作階段的聊天更新。
• ping / pong：維持連線活性。

Exec Lifecycle 事件

節點可以發送 exec.finished 或 exec.denied 事件來回報 system.run 的活動狀態。這些事件會被映射到 Gateway 的系統事件中。

Payload 欄位說明：

• sessionKey (必填)：接收系統事件的 agent session。
• runId：用於分組的唯一執行 ID。
• command：原始或格式化後的指令字串。
• exitCode, timedOut, success, output：僅在 finished 時提供的執行細節。
• reason：僅在 denied 時提供的拒絕原因。

Tailnet 整合

如果你在跨網路環境下使用，可以將 Bridge 綁定到 Tailscale 的 IP：

在 ~/.openclaw/openclaw.json 中設定：

{
  "bridge": {
    "bind": "tailnet"
  }
}

注意，Bonjour 廣播無法跨越子網，因此在 Tailnet 環境下，你需要使用 MagicDNS 名稱或手動指定 IP 與 Port。

疑難排解

• 收到 NOT_PAIRED 或 UNAUTHORIZED 錯誤：這代表你的節點尚未通過認證。請發送 pair-request 並在 Gateway 端點擊確認。
• 找不到 Gateway 服務：檢查 bridge.tls.enabled 設定是否與客戶端匹配。在非區域網路環境下，Bonjour 會失效，請改用手動連線。

想要了解如何設定最新的節點連線？請諮詢 AI Setup Assistant。

下一步

• Gateway protocol：了解目前推薦使用的 WebSocket 協議。
• Node.js SDK：查看如何實作現代化的節點客戶端。