OpenClaw 閘道器設定指南：快速連接與節點配對

開發者在處理跨裝置連線時，最頭痛的往往不是功能開發，而是網路通訊。當你想要讓 macOS 的選單列 App 控制遠端的 Gateway，或是想讓手機順利配對到正確的節點時，複雜的網路環境（像是防火牆或動態 IP）總會跳出來搗亂。

OpenClaw 透過一套清晰的探索與傳輸機制解決了這些問題。這篇文章會帶你了解 OpenClaw 如何處理節點發現與安全連線，讓你無論在區域網路還是跨網段環境下，都能順暢地操作你的機器人。

探索與傳輸

OpenClaw 面臨兩個表面上看起來很像，但本質不同的問題：

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

設計目標是將所有的網路探索/廣播功能保留在 Node Gateway (openclaw gateway) 中，並讓客戶端（mac App, iOS）作為消費者。

術語

• Gateway：一個長時間運行的 Gateway process，擁有狀態（sessions, 配對, 節點註冊表）並執行 channels。大多數設定中每個主機使用一個；但也支援隔離的多 Gateway 設定。
• Gateway WS (控制平面)：預設在 127.0.0.1:18789 的 WebSocket endpoint；可以透過 gateway.bind 綁定到 LAN/tailnet。
• Direct WS transport：面向 LAN/tailnet 的 Gateway WS endpoint（不透過 SSH）。
• SSH transport (備援)：透過 SSH 轉發 127.0.0.1:18789 來進行遠端控制。
• Legacy TCP bridge (已棄用/移除)：舊版的節點傳輸（參考 Bridge protocol）；不再用於探索廣播。

協定細節：

• Gateway protocol
• Bridge protocol (legacy)

為什麼我們同時保留「直接連線」與 SSH

• Direct WS 在同一個網路或 tailnet 內提供最佳的 UX：
  • 透過 Bonjour 在區域網路自動探索
  • 配對 token 與 ACL 由 Gateway 擁有
  • 不需要 shell 存取權限；協定表面可以保持精簡且易於審計
• SSH 仍然是萬用的備援方案：
  • 只要你有 SSH 存取權限，在任何地方都能運作（即使是無關的網路）
  • 在 multicast/mDNS 出問題時依然有效
  • 除了 SSH 之外，不需要開啟新的入站連接埠

探索輸入（客戶端如何得知 Gateway 的位置）

1) Bonjour / mDNS (僅限區域網路)

Bonjour 是盡力而為的機制，無法跨越網路。它僅用於「同區域網路」的便利性。

目標方向：

• Gateway 透過 Bonjour 廣播其 WS endpoint。
• 客戶端瀏覽並顯示「選擇 Gateway」列表，然後儲存選定的 endpoint。

故障排除與 beacon 細節：Bonjour。

Service beacon 細節

• Service types:
  • _openclaw-gw._tcp (gateway transport beacon)
• TXT keys (非機密):
  • role=gateway
  • transport=gateway
  • displayName=<friendly name> (operator 設定的顯示名稱)
  • lanHost=<hostname>.local
  • sshPort=22 (或廣播的連接埠)
  • gatewayPort=18789 (Gateway WS + HTTP)
  • gatewayTls=1 (僅在啟用 TLS 時)
  • gatewayTlsSha256=<sha256> (僅在啟用 TLS 且 fingerprint 可用時)
  • canvasPort=<port> (canvas host port；目前在啟用 canvas host 時與 gatewayPort 相同)
  • cliPath=<path> (選填；可執行的 openclaw 入口點或 binary 的絕對路徑)
  • tailnetDns=<magicdns> (選填提示；在 Tailscale 可用時自動偵測)

安全性說明：

• Bonjour/mDNS TXT 紀錄是未經認證的。客戶端必須將 TXT 值僅視為 UX 提示。
• 路由（host/port）應優先使用解析後的 service endpoint (SRV + A/AAAA)，而非 TXT 提供的 lanHost、tailnetDns 或 gatewayPort。
• TLS pinning 絕不允許廣播的 gatewayTlsSha256 覆蓋先前儲存的 pin。
• iOS/Android 節點應將基於探索的直接連線視為僅限 TLS，並在儲存第一次 pin 之前要求明確的「信任此 fingerprint」確認（帶外驗證）。

停用/覆蓋：

• 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 作為客戶端的選填提示（包括廣域 beacons）。

macOS App 現在在 Gateway 探索中偏好使用 MagicDNS 名稱而非原始 Tailscale IP。這提高了 tailnet IP 變更時（例如節點重啟或 CGNAT 重新分配後）的可靠性，因為 MagicDNS 名稱會自動解析為當前的 IP。

3) 手動 / SSH 目標

當沒有直接路由（或直接連線被停用）時，客戶端總是可以透過轉發 loopback gateway port 來經由 SSH 連線。

參考 Remote access。

傳輸選擇（客戶端策略）

建議的客戶端行為：

1. 如果已設定且可連及已配對的直接 endpoint，則使用它。
2. 否則，如果 Bonjour 在區域網路上找到 Gateway，提供一鍵「使用此 Gateway」的選擇並將其儲存為直接 endpoint。
3. 否則，如果已設定 tailnet DNS/IP，嘗試直接連線。
4. 否則，退而求其次使用 SSH。

配對與認證（直接傳輸）

Gateway 是節點/客戶端准入的唯一事實來源。

• 配對請求在 Gateway 中建立/核准/拒絕（參考 Gateway pairing）。
• Gateway 強制執行：
  • 認證 (token / keypair)
  • scopes/ACLs (Gateway 不是所有方法的原始 proxy)
  • 速率限制 (rate limits)

各組件的職責

• Gateway：廣播探索 beacons，擁有配對決策權，並託管 WS endpoint。
• macOS app：幫助你選擇 Gateway，顯示配對提示，並僅將 SSH 作為備援。
• iOS/Android nodes：瀏覽 Bonjour 以提供便利性，並連線到已配對的 Gateway WS。

下一步

• 了解 Gateway 協定 的運作細節
• 設定 遠端存取 以應對複雜網路
• 參考 配對指南 完成裝置綁定

如果你在設定過程中遇到任何連線問題，可以詢問我們的 AI Setup Assistant。