探索與傳輸方式

OpenClaw 有兩個表面上看起來相似、但實際上不同的問題：

1. 操作員遠端控制：由 macOS 選單列應用程式控制執行在其他地方的 Gateway。
2. Node 配對：iOS/Android（以及未來的 nodes）尋找 Gateway 並安全配對。

設計目標是將所有網路探索/廣播保留在 Node Gateway（openclaw gateway）中，並讓用戶端（Mac 應用程式、iOS）作為消費者。

# 術語

• Gateway：單一長時間執行的 Gateway 程序，擁有狀態（工作階段、配對、node 登錄）並執行通道。多數設定每台主機使用一個；也可以採用隔離的多 Gateway 設定。
• Gateway WS（控制平面）：預設位於 127.0.0.1:18789 的 WebSocket 端點；可透過 gateway.bind 綁定到 LAN/tailnet。
• Direct WS 傳輸：面向 LAN/tailnet 的 Gateway WS 端點（沒有 SSH）。
• SSH 傳輸（備援）：透過 SSH 轉送 127.0.0.1:18789 來進行遠端控制。
• 舊版 TCP bridge（已移除）：較舊的 node 傳輸（請參閱 Bridge 協定）；不再為了 探索而廣播，也不再是目前建置的一部分。

協定詳細資訊：

• Gateway 協定
• Bridge 協定（舊版）

# 為什麼我們同時保留 direct 和 SSH

• Direct WS 在同一個網路與 tailnet 內提供最佳使用者體驗：
  • 透過 Bonjour 在 LAN 上自動探索
  • 配對 token + ACL 由 Gateway 擁有
  • 不需要 shell 存取權；協定表面可以維持緊湊且可稽核
• SSH 仍然是通用備援：
  • 只要有 SSH 存取權，任何地方都可運作（即使跨越不相關的網路）
  • 能承受 multicast/mDNS 問題
  • 除了 SSH 之外不需要新的入站連接埠

# 探索輸入（用戶端如何得知 Gateway 位置）

# 1) Bonjour / DNS-SD 探索

Multicast Bonjour 是盡力而為，且不會跨越網路。OpenClaw 也可以透過已設定的廣域 DNS-SD 網域瀏覽同一個 Gateway beacon，因此探索可以涵蓋：

• 同一個 LAN 上的 local.
• 用於跨網路探索的已設定 unicast DNS-SD 網域

目標方向：

• 啟用隨附的 bonjour Plugin 時，Gateway 會透過 Bonjour 廣播其 WS 端點。該 Plugin 會在 macOS 主機上自動啟動，在其他地方則為選擇性啟用。
• 用戶端會瀏覽並顯示「選擇 Gateway」清單，然後儲存所選端點。

疑難排解與 beacon 詳細資訊：Bonjour。

# 服務 beacon 詳細資訊

• 服務類型：
  • _openclaw-gw._tcp（Gateway 傳輸 beacon）
• TXT keys（非機密）：
  • role=gateway
  • transport=gateway
  • displayName=<friendly name>（由操作員設定的顯示名稱）
  • lanHost=<hostname>.local
  • gatewayPort=18789（Gateway WS + HTTP）
  • gatewayTls=1（僅在啟用 TLS 時）
  • gatewayTlsSha256=<sha256>（僅在啟用 TLS 且 fingerprint 可用時）
  • canvasPort=<port>（canvas 主機連接埠；目前在啟用 canvas 主機時與 gatewayPort 相同）
  • tailnetDns=<magicdns>（選用提示；Tailscale 可用時自動偵測）
  • sshPort=<port>（僅限 mDNS full mode；廣域 DNS-SD 可能會省略它，此時 SSH 預設值維持在 22）
  • cliPath=<path>（僅限 mDNS full mode；廣域 DNS-SD 仍會將其寫入為遠端安裝提示）

安全性注意事項：

• Bonjour/mDNS TXT records 未經驗證。用戶端必須只將 TXT 值視為使用者體驗提示。
• 路由（host/port）應優先使用解析後的服務端點（SRV + A/AAAA），而不是 TXT 提供的 lanHost、tailnetDns 或 gatewayPort。
• TLS pinning 絕不能允許廣播的 gatewayTlsSha256 覆寫先前儲存的 pin。
• 每當所選路由是安全/TLS-based 時，iOS/Android nodes 應要求明確「信任此 fingerprint」確認後，才儲存首次 pin（頻外驗證）。

啟用/停用/覆寫：

• openclaw plugins enable bonjour 會啟用 LAN multicast 廣播。
• OPENCLAW_DISABLE_BONJOUR=1 會停用廣播。
• 啟用 Bonjour Plugin 且未設定 OPENCLAW_DISABLE_BONJOUR 時， Bonjour 會在一般主機上廣播，並在偵測到容器內部時自動停用。 空設定的 macOS Gateway 啟動會自動啟用該 Plugin；Linux、 Windows 與容器化部署需要明確啟用。 只有在主機、macvlan 或其他支援 mDNS 的網路上使用 0；使用 1 強制停用。
• ~/.openclaw/openclaw.json 中的 gateway.bind 控制 Gateway 綁定模式。
• 發出 sshPort 時，OPENCLAW_SSH_PORT 會覆寫廣播的 SSH 連接埠。
• OPENCLAW_TAILNET_DNS 會發布 tailnetDns 提示（MagicDNS）。
• OPENCLAW_CLI_PATH 會覆寫廣播的 CLI 路徑。

# 2) Tailnet（跨網路）

對於 London/Vienna 類型的設定，Bonjour 幫不上忙。建議的「direct」目標是：

• Tailscale MagicDNS 名稱（偏好）或穩定的 tailnet IP。

如果 Gateway 可以偵測到自己正在 Tailscale 下執行，它會將 tailnetDns 發布為用戶端的選用提示（包括廣域 beacon）。

macOS 應用程式現在會在 Gateway 探索時優先使用 MagicDNS 名稱，而不是原始 Tailscale IP。這能提升 tailnet IP 變更時的可靠性（例如 node 重新啟動或 CGNAT 重新指派之後），因為 MagicDNS 名稱會自動解析到目前的 IP。

對於 mobile node 配對，探索提示不會放寬 tailnet/public 路由上的傳輸安全性：

• iOS/Android 仍然需要安全的首次 tailnet/public 連線路徑（wss:// 或 Tailscale Serve/Funnel）。
• 探索到的原始 tailnet IP 是路由提示，不是允許使用 plaintext remote ws:// 的權限。
• 仍支援私有 LAN direct-connect ws://。
• 如果你想要最簡單的 Tailscale mobile nodes 路徑，請使用 Tailscale Serve，讓探索與設定碼都解析到相同的安全 MagicDNS 端點。

# 3) 手動 / SSH 目標

沒有 direct route（或 direct 已停用）時，用戶端永遠可以透過 SSH 轉送 loopback Gateway 連接埠來連線。

請參閱遠端存取。

# 傳輸選擇（用戶端原則）

建議的用戶端行為：

1. 如果已設定且可連線至已配對的 direct 端點，請使用它。
2. 否則，如果探索在 local. 或已設定的廣域網域上找到 Gateway，提供一鍵式「使用此 Gateway」選擇，並將其儲存為 direct 端點。
3. 否則，如果已設定 tailnet DNS/IP，請嘗試 direct。 對於 tailnet/public 路由上的 mobile nodes，direct 表示安全端點，而不是 plaintext remote ws://。
4. 否則，回退到 SSH。

# 配對 + auth（direct 傳輸）

Gateway 是 node/用戶端准入的事實來源。

• 配對請求會在 Gateway 中建立/核准/拒絕（請參閱 Gateway 配對）。
• Gateway 會強制執行：
  • auth（token / keypair）
  • scopes/ACLs（Gateway 不是每個方法的 raw proxy）
  • rate limits

# 各元件職責

• Gateway：廣播探索 beacon、擁有配對決策，並託管 WS 端點。
• macOS 應用程式：協助你選擇 Gateway、顯示配對提示，並只將 SSH 作為備援。
• iOS/Android nodes：為方便起見瀏覽 Bonjour，並連線到已配對的 Gateway WS。

# 相關

• 遠端存取
• Tailscale
• Bonjour 探索