ClawCN - OpenClaw 中文版

主题

Bonjour / mDNS 发现 ​

OpenClaw 使用 Bonjour(mDNS / DNS‑SD)作为仅限局域网的便利功能来发现 活动的 Gateway(WebSocket 端点)。这是尽力而为的,不能替代 SSH 或 基于 Tailnet 的连接。

通过 Tailscale 的广域 Bonjour(单播 DNS‑SD) ​

如果节点和 Gateway 位于不同的网络,多播 mDNS 无法跨越边界。您可以通过切换到 通过 Tailscale 的单播 DNS‑SD(「广域 Bonjour」)来保持相同的发现 UX。

高层步骤:

  1. 在 Gateway 主机上运行 DNS 服务器(可通过 Tailnet 访问)。
  2. 在专用区域下为 _openclaw-gw._tcp 发布 DNS‑SD 记录 (例如:openclaw.internal.)。
  3. 配置 Tailscale 分割 DNS,使您选择的域通过该 DNS 服务器为客户端(包括 iOS)解析。

OpenClaw 支持任何发现域;openclaw.internal. 只是一个示例。 iOS/Android 节点同时浏览 local. 和您配置的广域域。

Gateway 配置(推荐) ​

json5
{
  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
  discovery: { wideArea: { enabled: true } }, // enables wide-area DNS-SD publishing
}

一次性 DNS 服务器设置(Gateway 主机) ​

bash
openclaw dns setup --apply

这将安装 CoreDNS 并配置它:

  • 仅在 Gateway 的 Tailscale 接口上监听端口 53
  • 从 ~/.openclaw/dns/<domain>.db 提供您选择的域(例如:openclaw.internal.)

从连接到 Tailnet 的机器验证:

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

Tailscale DNS 设置 ​

在 Tailscale 管理控制台中:

  • 添加指向 Gateway 的 Tailnet IP(UDP/TCP 53)的名称服务器。
  • 添加分割 DNS,使您的发现域使用该名称服务器。

一旦客户端接受 Tailnet DNS,iOS 节点就可以在您的发现域中浏览 _openclaw-gw._tcp,而无需多播。

Gateway 监听器安全性(推荐) ​

Gateway WS 端口(默认 18789)默认绑定到本地回环。对于局域网/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=<friendly name>
  • lanHost=<hostname>.local
  • gatewayPort=<port>(Gateway WS + HTTP)
  • gatewayTls=1(仅在启用 TLS 时)
  • gatewayTlsSha256=<sha256>(仅在启用 TLS 且指纹可用时)
  • canvasPort=<port>(仅在启用 canvas 主机时;默认 18793)
  • sshPort=<port>(未覆盖时默认为 22)
  • transport=gateway
  • cliPath=<path>(可选;可运行的 openclaw 入口点的绝对路径)
  • tailnetDns=<magicdns>(当 Tailnet 可用时的可选提示)

在 macOS 上调试 ​

有用的内置工具:

  • 浏览实例:
    bash
    dns-sd -B _openclaw-gw._tcp local.
  • 解析一个实例(替换 <instance>):
    bash
    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 结果;请重试。
  • 浏览正常但解析失败:保持机器名称简单(避免表情符号或 标点符号),然后重启 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)。

相关文档 ​