OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

探索與傳輸方式

OpenClaw 有兩個彼此相關但不同的探索問題：

  1. 操作員遠端控制：macOS 選單列應用程式控制在其他位置執行的閘道。
  2. 節點配對：iOS/Android（及未來的節點）尋找閘道並進行安全配對。

所有網路探索／廣告功能都位於節點閘道 （openclaw gateway）；用戶端（Mac 應用程式、iOS）只負責使用這些資訊。

術語

  • 閘道：單一長時間執行的程序，負責管理狀態（工作階段、 配對、節點登錄檔）並執行頻道。大多數設定會在每部主機上使用一個； 也可以設定彼此隔離的多個閘道。
  • 閘道 WS（控制平面）：預設位於 127.0.0.1:18789 的 WebSocket 端點；透過 gateway.bind 將其繫結至區域網路／tailnet。
  • 直接 WS 傳輸：面向區域網路／tailnet 的閘道 WS 端點（不使用 SSH）。
  • SSH 傳輸（備援）：透過 SSH 轉送 127.0.0.1:18789 來進行遠端控制。
  • 舊版 TCP 橋接器（已移除）：較舊的節點傳輸方式（請參閱 橋接器通訊協定）；探索功能不再廣告此方式， 目前的建置版本也不再包含此方式。

通訊協定詳細資料：閘道通訊協定、 橋接器通訊協定（舊版）。

為何直接連線和 SSH 會同時存在

  • 直接 WS 在相同網路及 tailnet 內可提供最佳使用者體驗：透過 Bonjour 在區域網路上自動探索、由閘道管理配對權杖與 ACL， 而且不需要 Shell 存取權。
  • SSH 是通用的備援方式：只要能透過 SSH 存取，無論位於何處皆可使用， 即使跨越互不相關的網路也可以運作，且不受多播／mDNS 問題影響， 除了 SSH 之外不需要新的傳入連接埠。

探索輸入

1) Bonjour / DNS-SD

多播 Bonjour 是盡力而為的機制，無法跨越網路。OpenClaw 也支援透過已設定的廣域 DNS-SD 網域瀏覽相同的閘道信標，因此探索範圍可以同時涵蓋相同區域網路上的 local.，以及用於跨網路探索的已設定單播 DNS-SD 網域。

啟用隨附的 bonjour 外掛時，閘道會透過 Bonjour 廣告其 WS 端點； 用戶端會瀏覽並顯示「選擇閘道」清單，然後儲存所選端點。

疑難排解與信標詳細資料：Bonjour。

服務信標詳細資料

  • 服務類型：_openclaw-gw._tcp（閘道傳輸信標）。

  • TXT 鍵（非機密）：

    鍵 備註
    role=gateway 一律存在。
    transport=gateway 一律存在。
    displayName=<name> 由操作員設定的顯示名稱。
    lanHost=<hostname>.local 僅限區域網路 mDNS 廣告器；不由廣域 DNS-SD 寫入。
    gatewayPort=18789 閘道 WS + HTTP 連接埠。
    gatewayTls=1 僅在啟用 TLS 時存在。
    gatewayTlsSha256=<sha256> 僅在啟用 TLS 且可取得指紋時存在。
    tailnetDns=<magicdns> 選用提示；可使用 Tailscale 時會自動偵測。
    sshPort=<port> 僅在 discovery.mdns.mode="full" 時存在；在預設 "minimal" 模式中會省略（SSH 預設為 22），區域網路廣告器與廣域 DNS-SD 皆是如此。
    cliPath=<path> 使用與 sshPort 相同的 discovery.mdns.mode="full" 閘門；供命令列介面路徑使用的遠端安裝提示。

    外掛探索合約中定義了 canvasPort TXT 鍵，供未來的畫布主機連接埠使用， 但目前沒有任何程式碼路徑設定其值，因此現今絕不會發出此鍵。

安全性注意事項：

  • Bonjour/mDNS TXT 記錄未經驗證。用戶端必須僅將 TXT 值視為使用者體驗提示。
  • 路由（主機／連接埠）應優先採用解析後的服務端點 （SRV + A/AAAA），而非 TXT 提供的 lanHost、tailnetDns 或 gatewayPort。
  • TLS 釘選絕不可讓廣告的 gatewayTlsSha256 覆寫 先前儲存的釘選。
  • 只要選擇的路由是安全／以 TLS 為基礎，iOS/Android 節點在儲存首次使用的釘選前， 應要求明確確認「信任此指紋」（頻外驗證）。

啟用、停用及覆寫：

  • openclaw plugins enable bonjour 會啟用區域網路多播廣告。
  • openclaw.json 中的 discovery.mdns.mode 控制 mDNS 廣播： "minimal"（預設）、"full"（將 cliPath/sshPort 同時加入區域網路 信標與任何廣域 DNS-SD 區域），或 "off"（停用 mDNS）。
  • OPENCLAW_DISABLE_BONJOUR=1 會強制停用廣告；discovery.mdns.mode="off" 則會獨立停用廣告。OPENCLAW_DISABLE_BONJOUR=0 是明確的選擇加入設定， 可覆寫外掛在偵測到容器（Docker、containerd、Kubernetes、LXC）內時的自動停用行為； 但不會覆寫 discovery.mdns.mode="off"。隨附的 bonjour 外掛會在 macOS 主機（enabledByDefaultOnPlatforms: ["darwin"]）上自動啟動，並在偵測到容器內時自動停用； Linux、Windows 及其他容器化部署需要明確設定 plugins enable bonjour。
  • ~/.openclaw/openclaw.json 中的 gateway.bind 控制閘道繫結模式。
  • OPENCLAW_SSH_PORT 會覆寫廣告的 SSH 連接埠（僅在 discovery.mdns.mode="full" 時生效）。
  • OPENCLAW_TAILNET_DNS 會發布 tailnetDns 提示（MagicDNS）。
  • OPENCLAW_CLI_PATH 會覆寫廣告的命令列介面路徑。

2) Tailnet（跨網路）

對位於不同實體網路上的閘道而言，Bonjour 無法提供協助。建議的直接目標是 Tailscale MagicDNS 名稱（優先）或穩定的 tailnet IP。

如果閘道偵測到自己在 Tailscale 下執行，便會發布 tailnetDns 作為用戶端的選用提示（包括廣域信標）。 macOS 應用程式在探索閘道時，會優先採用 MagicDNS 名稱而非原始 Tailscale IP； 因此當 tailnet IP 因節點重新啟動或 CGNAT 重新指派而變更時，仍可維持可靠性， 因為 MagicDNS 會自動解析至目前的 IP。

對於行動節點配對，探索提示絕不會放寬 tailnet／公用路由上的傳輸安全性：

  • iOS/Android 仍需要安全的首次 tailnet／公用連線路徑 （wss:// 或 Tailscale Serve/Funnel）。
  • 探索到的原始 tailnet IP 是路由提示，並非使用 明文遠端 ws:// 的許可。
  • 仍支援私人區域網路直接連線 ws://。
  • 若要在行動節點上使用最簡單的 Tailscale 路徑，請使用 Tailscale Serve， 讓探索與設定都解析至相同的安全 MagicDNS 端點。

3) 手動／SSH 目標

沒有直接路由（或直接連線已停用）時，用戶端仍可透過 SSH 轉送 迴路閘道連接埠來連線。請參閱遠端存取。

傳輸選擇（用戶端政策）

  1. 如果已設定配對的直接端點且可以連線，則使用該端點。
  2. 否則，如果探索功能在 local. 或已設定的廣域 網域中找到閘道，請提供一鍵「使用此閘道」選項，並將其儲存為 直接端點。
  3. 否則，如果已設定 tailnet DNS/IP，則嘗試直接連線。對使用 tailnet／公用路由的行動節點而言，直接連線表示安全端點，而非明文 遠端 ws://。
  4. 否則，回退至 SSH。

配對與驗證（直接傳輸）

閘道是節點／用戶端准入的真實資料來源：

  • 配對要求會在閘道中建立／核准／拒絕（請參閱 閘道配對）。
  • 閘道會強制執行驗證（權杖／金鑰組）、範圍／ACL（並非 對所有方法提供原始代理），以及速率限制。

各元件的責任

  • 閘道：廣告探索信標、負責配對決策，並託管 WS 端點。
  • macOS 應用程式：協助你選擇閘道、顯示配對提示，且僅將 SSH 作為備援方式。
  • iOS/Android 節點：為了便利性而瀏覽 Bonjour，並連線至 已配對的閘道 WS。

相關內容

Was this useful?
On this page

On this page