探索與傳輸方式

OpenClaw 有兩個看起來相似但本質不同的問題：

  1. Operator 遠端控制：macOS 選單列程式控制在其他地方運行的 Gateway。
  2. 節點配對：iOS/Android（以及未來的節點）找到 Gateway 並安全配對。

設計目標是把所有的網路探索和廣播都放在 Node Gateway（openclaw gateway），讓客戶端（Mac 程式、iOS）純粹作為消費者。

名詞說明

  • Gateway：一個長期運行的 gateway 程序，擁有狀態（sessions、配對、節點註冊）並運行頻道。多數情況下每台主機跑一個就好；獨立的多 gateway 部署也是可行的。
  • Gateway WS（控制平面）：預設位於 127.0.0.1:18789 的 WebSocket 端點，可透過 gateway.bind 繫結到區網或 Tailnet。
  • 直連 WS 傳輸：面向區網/Tailnet 的 Gateway WS 端點（不經過 SSH）。
  • SSH 傳輸（備援）：透過 SSH 轉發 127.0.0.1:18789 進行遠端控制。
  • 舊版 TCP bridge（已棄用/移除）：舊的節點傳輸方式（參閱 Bridge 協定）；不再用於探索廣播。

協定細節：

為什麼同時保留「直連」和 SSH

  • 直連 WS 在同網路和 Tailnet 內體驗最好：
    • 區網上透過 Bonjour 自動探索
    • 配對 token 和 ACL 由 gateway 管理
    • 不需要 shell 存取權限；協定面可以保持精簡且可審計
  • SSH 仍然是萬用的備援方式：
    • 只要有 SSH 存取就能用（即使跨不相關的網路）
    • 不受多播/mDNS 問題影響
    • 除了 SSH 埠以外不需要開其他入站埠

探索輸入（客戶端如何知道 Gateway 在哪裡）

1) Bonjour / mDNS（僅區網）

Bonjour 是盡力而為的，無法跨網路。只用於「同一區網」的便利場景。

方向：

  • Gateway 透過 Bonjour 廣播自己的 WS 端點。
  • 客戶端瀏覽並顯示「選擇 gateway」清單，然後儲存選中的端點。

除錯與信標細節：Bonjour。

服務信標細節

  • 服務類型：
    • _openclaw-gw._tcp（gateway 傳輸信標）
  • TXT 鍵值（非機密）：
    • role=gateway
    • lanHost=<hostname>.local
    • sshPort=22（或實際廣播的值）
    • gatewayPort=18789（Gateway WS + HTTP）
    • gatewayTls=1（僅在啟用 TLS 時）
    • gatewayTlsSha256=<sha256>（僅在啟用 TLS 且有指紋時）
    • canvasPort=<port>（canvas host 埠；啟用時目前與 gatewayPort 相同）
    • cliPath=<path>（可選；openclaw 可執行進入點或二進位檔的絕對路徑）
    • tailnetDns=<magicdns>（可選提示；Tailscale 可用時自動偵測）

安全注意事項：

  • Bonjour/mDNS TXT 記錄是未經驗證的。客戶端應將 TXT 值僅作為 UX 提示。
  • 路由（host/port）應優先使用解析後的服務端點（SRV + A/AAAA），而非 TXT 中的 lanHost、tailnetDns 或 gatewayPort。
  • TLS 釘選不可讓廣播中的 gatewayTlsSha256 覆蓋先前已儲存的釘選值。
  • iOS/Android 節點應將探索式直連視為僅限 TLS，並在儲存首次釘選值前要求明確的「信任此指紋」確認（帶外驗證）。

停用/覆寫：

  • OPENCLAW_DISABLE_BONJOUR=1 停用廣播。
  • ~/.openclaw/openclaw.json 中的 gateway.bind 控制 Gateway 繫結模式。
  • OPENCLAW_SSH_PORT 覆寫 TXT 中廣播的 SSH 埠（預設為 22）。
  • OPENCLAW_TAILNET_DNS 發布 tailnetDns 提示（MagicDNS）。
  • OPENCLAW_CLI_PATH 覆寫廣播的 CLI 路徑。

2) Tailnet（跨網路）

如果是倫敦/維也納那種跨地域部署，Bonjour 幫不上忙。建議的「直連」目標是：

  • Tailscale MagicDNS 名稱（首選）或穩定的 Tailnet IP。

如果 Gateway 偵測到自己在 Tailscale 環境下運行，會發布 tailnetDns 作為客戶端的可選提示（包括廣域信標）。

3) 手動指定 / SSH

沒有直連路由（或直連被停用）時，客戶端永遠可以透過 SSH 轉發 loopback gateway 埠來連線。

參閱 遠端存取。

傳輸選擇（客戶端策略）

建議的客戶端行為：

  1. 如果已配對的直連端點已設定且可達，直接使用。
  2. 否則，如果 Bonjour 在區網找到 gateway，提供一鍵「使用此 gateway」選項並儲存為直連端點。
  3. 否則，如果有設定 Tailnet DNS/IP，嘗試直連。
  4. 否則，退回到 SSH。

配對 + 驗證（直連傳輸）

Gateway 是節點/客戶端准入的唯一權威。

  • 配對請求在 gateway 中建立/核准/拒絕（參閱 Gateway 配對）。
  • Gateway 負責強制執行：
    • 驗證（token / 金鑰對）
    • 範圍/ACL（gateway 不是對所有方法的原始代理）
    • 速率限制

各元件的職責

  • Gateway：廣播探索信標、擁有配對決策權、託管 WS 端點。
  • macOS 程式：幫你選擇 gateway、顯示配對提示，SSH 只作為備援。
  • iOS/Android 節點：將 Bonjour 作為便利的瀏覽方式，連線到已配對的 Gateway WS。
arrow_back
上一頁
Pairing
下一頁
Bonjour
arrow_forward