Bonjour / mDNS 探索

OpenClaw 使用 Bonjour（mDNS / DNS-SD）作為區域網路的便利探索機制，用來找到正在運行的 Gateway（WebSocket 端點）。這是盡力而為的機制，無法取代 SSH 或 Tailnet 連線。

廣域 Bonjour（Unicast DNS-SD）搭配 Tailscale

如果節點和 Gateway 分屬不同網路，多播 mDNS 無法跨網路。你可以改用單播 DNS-SD（又稱「廣域 Bonjour」），透過 Tailscale 維持相同的探索體驗。

大致步驟：

  1. 在 Gateway 主機上架設 DNS 伺服器（可透過 Tailnet 存取）。
  2. 在專用區域下發布 _openclaw-gw._tcp 的 DNS-SD 記錄 （例如 openclaw.internal.）。
  3. 設定 Tailscale 的 split DNS，讓你選定的網域透過該 DNS 伺服器解析（包括 iOS 裝置）。

OpenClaw 支援任意探索網域，openclaw.internal. 只是範例。 iOS/Android 節點同時瀏覽 local. 和你設定的廣域網域。

Gateway 設定（建議）

{
  gateway: { bind: "tailnet" }, // 僅限 tailnet（建議）
  discovery: { wideArea: { enabled: true } }, // 啟用廣域 DNS-SD 發布
}

一次性 DNS 伺服器設定（Gateway 主機）

openclaw dns setup --apply

這會安裝 CoreDNS 並設定為：

  • 只在 Gateway 的 Tailscale 介面上監聽 53 埠
  • 從 ~/.openclaw/dns/<domain>.db 提供你選定的網域（例如 openclaw.internal.）

從 Tailnet 上的另一台機器驗證：

dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

Tailscale DNS 設定

在 Tailscale 管理控制台中：

  • 新增 nameserver，指向 Gateway 的 Tailnet IP（UDP/TCP 53）。
  • 新增 split DNS，讓你的探索網域使用該 nameserver。

客戶端接受 Tailnet DNS 後，iOS 節點就能在你的探索網域中瀏覽 _openclaw-gw._tcp，不需要多播。

Gateway 監聽器安全（建議）

Gateway WS 埠（預設 18789）預設繫結到 loopback。如果要讓區網或 Tailnet 存取，需明確指定繫結方式並保持驗證啟用。

僅限 Tailnet 的設定：

  • 在 ~/.openclaw/openclaw.json 設定 gateway.bind: "tailnet"。
  • 重啟 Gateway（或重啟 macOS 選單列程式）。

誰在做廣播

只有 Gateway 會廣播 _openclaw-gw._tcp。

服務類型

  • _openclaw-gw._tcp — Gateway 傳輸信標（供 macOS/iOS/Android 節點使用）。

TXT 鍵值（非機密提示）

Gateway 會廣播一些非機密的提示資訊，讓 UI 流程更方便：

  • role=gateway
  • displayName=<易讀名稱>
  • lanHost=<hostname>.local
  • gatewayPort=<port>（Gateway WS + HTTP）
  • gatewayTls=1（僅在啟用 TLS 時）
  • gatewayTlsSha256=<sha256>（僅在啟用 TLS 且有指紋時）
  • canvasPort=<port>（僅在啟用 canvas host 時；目前與 gatewayPort 相同）
  • sshPort=<port>（未覆寫時預設為 22）
  • transport=gateway
  • cliPath=<path>（可選；openclaw 可執行檔的絕對路徑）
  • tailnetDns=<magicdns>（可選提示，Tailnet 可用時）

安全注意事項：

  • Bonjour/mDNS TXT 記錄是未經驗證的。客戶端不可將 TXT 視為具權威性的路由資訊。
  • 客戶端應使用解析後的服務端點（SRV + A/AAAA）來做路由。lanHost、tailnetDns、gatewayPort 和 gatewayTlsSha256 應僅作為參考提示。
  • TLS 釘選不可讓廣播中的 gatewayTlsSha256 覆蓋先前已儲存的釘選值。
  • iOS/Android 節點應將探索式直連視為僅限 TLS，並在首次信任指紋前要求使用者明確確認。

macOS 上的除錯

好用的內建工具：

  • 瀏覽實例：

    dns-sd -B _openclaw-gw._tcp local.

  • 解析單一實例（將 <instance> 替換為實際名稱）：

    dns-sd -L "<instance>" _openclaw-gw._tcp local.

如果瀏覽成功但解析失敗，通常是區網政策或 mDNS 解析器的問題。

Gateway 日誌中的除錯

Gateway 會寫入滾動式日誌檔（啟動時會印出 gateway log file: ...）。搜尋 bonjour: 開頭的行，特別注意：

  • bonjour: advertise failed ...
  • bonjour: ... name conflict resolved / hostname conflict resolved
  • bonjour: watchdog detected non-announced service ...

iOS 節點上的除錯

iOS 節點使用 NWBrowser 來探索 _openclaw-gw._tcp。

擷取日誌方式：

  • 設定 → Gateway → 進階 → Discovery Debug Logs
  • 設定 → Gateway → 進階 → Discovery Logs → 重現問題 → 複製

日誌會包含瀏覽器狀態轉換和結果集變更。

常見失敗情境

  • Bonjour 無法跨網路：請改用 Tailnet 或 SSH。
  • 多播被封鎖：某些 Wi-Fi 網路會停用 mDNS。
  • 休眠/介面切換：macOS 可能暫時丟失 mDNS 結果，重試即可。
  • 瀏覽成功但解析失敗：盡量讓主機名稱簡單（避免 emoji 或 特殊標點），然後重啟 Gateway。服務實例名稱衍生自主機名稱，過於複雜的名稱可能讓部分解析器出錯。

跳脫的實例名稱（\032）

Bonjour/DNS-SD 經常會將服務實例名稱中的位元組以十進位 \DDD 序列跳脫（例如空格變成 \032）。

  • 這在協定層級是正常的。
  • UI 應該解碼後再顯示（iOS 使用 BonjourEscapes.decode）。

停用/設定

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

相關文件

arrow_back
上一頁
Discovery
下一頁
Remote
arrow_forward