Bonjour / mDNS 发现

OpenClaw 使用 Bonjour（mDNS / DNS‑SD）作为仅 LAN 的便利方式来发现活动的网关（WebSocket 端点）。它是尽力而为的，不取代基于 SSH 或 Tailnet 的连接。

通过 Tailscale 的广域 Bonjour（单播 DNS‑SD）

如果节点和网关在不同网络上，多播 mDNS 不会跨越边界。你可以通过切换到单播 DNS‑SD（"广域 Bonjour"）来保持相同的发现体验。

高级步骤：

1. 在网关主机上运行 DNS 服务器（可通过 Tailnet 访问）。
2. 为专用区域发布 _openclaw-gw._tcp 的 DNS‑SD 记录（例如：openclaw.internal.）。
3. 配置 Tailscale 分割 DNS，以便 openclaw.internal 由该 DNS 服务器解析（包括 iOS）。

OpenClaw 标准化此模式使用 openclaw.internal.。iOS/Android 节点自动浏览 local. 和 openclaw.internal.。

网关配置（推荐）

{
  gateway: { bind: "tailnet" }, // 仅 tailnet（推荐）
  discovery: { wideArea: { enabled: true } } // 启用 openclaw.internal DNS-SD 发布
}

一次性 DNS 服务器设置（网关主机）

openclaw dns setup --apply

这会安装 CoreDNS 并配置它：

• 仅在网关的 Tailscale 接口上监听端口 53
• 从 ~/.openclaw/dns/openclaw.internal.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 管理控制台中：

• 添加指向网关的 tailnet IP 的名称服务器（UDP/TCP 53）。
• 添加分割 DNS 以便域名 openclaw.internal 使用该名称服务器。

一旦客户端接受 tailnet DNS，iOS 节点就可以浏览 openclaw.internal. 中的 _openclaw-gw._tcp，无需多播。

网关监听器安全性（推荐）

网关 WS 端口（默认 18789）默认绑定到 loopback。对于 LAN/tailnet 访问，显式绑定并保持认证启用。

对于仅 tailnet 的设置：

• 在 ~/.openclaw/openclaw.json 中设置 gateway.bind: "tailnet"。
• 重启网关（或重启 macOS 菜单栏应用）。

广告内容

只有网关广告 _openclaw-gw._tcp。

服务类型

• _openclaw-gw._tcp — 网关传输信标（由 macOS/iOS/Android 节点使用）。

TXT 键（非机密提示）

网关广告小的非机密提示以使 UI 流程方便：

• role=gateway
• displayName=<friendly name>
• lanHost=<hostname>.local
• gatewayPort=<port>（网关 WS + HTTP）
• gatewayTls=1（仅在启用 TLS 时）
• gatewayTlsSha256=<sha256>（仅在启用 TLS 且指纹可用时）
• canvasPort=<port>（仅在画布主机启用时；默认 18793）
• sshPort=<port>（未覆盖时默认为 22）
• transport=gateway
• cliPath=<path>（可选；可运行 openclaw 入口点的绝对路径）
• tailnetDns=<magicdns>（Tailnet 可用时的可选提示）

在 macOS 上调试

有用的内置工具：

• 浏览实例：

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

• 解析一个实例（替换 <instance>）：

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

如果浏览工作但解析失败，你通常会遇到 LAN 策略或 mDNS 解析器问题。

在网关日志中调试

网关写入滚动日志文件（在启动时打印为 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。

要捕获日志：

• 设置 → 网关 → 高级 → 发现调试日志
• 设置 → 网关 → 高级 → 发现日志 → 重现 → 复制

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

常见故障模式

• Bonjour 不跨网络：使用 Tailnet 或 SSH。
• 多播被阻止：一些 Wi‑Fi 网络禁用 mDNS。
• 睡眠 / 接口变化：macOS 可能暂时丢失 mDNS 结果；重试。
• 浏览工作但解析失败：保持机器名称简单（避免表情符号或标点符号），然后重启网关。服务实例名称源自主机名，因此过于复杂的名称可能会混淆一些解析器。

转义的实例名称（\032）

Bonjour/DNS‑SD 通常将服务实例名称中的字节转义为十进制 \DDD 序列（例如空格变成 \032）。

• 这在协议层面是正常的。
• UI 应该解码以显示（iOS 使用 BonjourEscapes.decode）。

禁用 / 配置

• OPENCLAW_DISABLE_BONJOUR=1 禁用广告。
• ~/.openclaw/openclaw.json 中的 gateway.bind 控制网关绑定模式。
• OPENCLAW_SSH_PORT 覆盖 TXT 中广告的 SSH 端口。
• OPENCLAW_TAILNET_DNS 在 TXT 中发布 MagicDNS 提示。
• OPENCLAW_CLI_PATH 覆盖广告的 CLI 路径。

相关文档

• 发现策略和传输选择：发现
• 节点配对 + 批准：网关配对