Bonjour / mDNS 发现

OpenClaw 使用 Bonjour（mDNS / DNS-SD）作为仅限局域网的便捷方式来发现活跃的 Gateway（WebSocket 端点）。这是尽力而为的机制，不能替代 SSH 或 Tailnet 连接。

广域 Bonjour（单播 DNS-SD）over Tailscale

如果节点和 Gateway 在不同网络，组播 mDNS 无法跨越网络边界。你可以通过切换到 单播 DNS-SD（"Wide-Area Bonjour"）over Tailscale 来保持相同的发现体验。

高层步骤：

1. 在 Gateway 主机上运行 DNS 服务器（可通过 Tailnet 访问）。
2. 在专用区域下（例如 openclaw.internal.）为 _openclaw-gw._tcp 发布 DNS-SD 记录。
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 管理控制台中：

• 添加指向 Gateway tailnet IP 的名称服务器（UDP/TCP 53）。
• 添加 split DNS，使你的发现域使用该名称服务器。

客户端接受 tailnet DNS 后，iOS 节点就可以在你的发现域中浏览 _openclaw-gw._tcp，无需组播。

Gateway 监听器安全（推荐）

Gateway WS 端口（默认 18789）默认绑定到 loopback。对于 LAN/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=<端口>（Gateway WS + HTTP）
• gatewayTls=1（仅在 TLS 启用时）
• gatewayTlsSha256=<sha256>（仅在 TLS 启用且指纹可用时）
• canvasPort=<端口>（仅在 canvas host 启用时；目前与 gatewayPort 相同）
• sshPort=<端口>（未覆盖时默认为 22）
• transport=gateway
• cliPath=<路径>（可选；可运行的 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.

如果浏览成功但解析失败，通常是 LAN 策略或 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 → 复现 → Copy

日志包含浏览器状态转换和结果集变更。

常见失败模式

• 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）。

相关文档

• 发现策略和传输选择：发现与传输
• 节点配对 + 审批：Gateway 配对