Bonjour / mDNS 发现

OpenClaw 使用 Bonjour（mDNS / DNS-SD）作为 局域网专属的便捷手段 来发现活跃的 Gateway（WebSocket 端点）。它是尽力而为的，不能替代 SSH 或 Tailnet 连接。

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

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

大致步骤：

在 Gateway 主机上运行 DNS 服务器（通过 Tailnet 可达）。
在专用域名下发布 _openclaw-gw._tcp 的 DNS-SD 记录（示例：openclaw.internal.）。
配置 Tailscale 分离 DNS，让客户端（包括 iOS）通过该 DNS 服务器解析你选定的域名。

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）的名称服务器。
添加分离 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=<友好名称>
lanHost=<hostname>.local
gatewayPort=<port>（Gateway WS + HTTP）
gatewayTls=1（仅 TLS 启用时）
gatewayTlsSha256=<sha256>（仅 TLS 启用且指纹可用时）
canvasPort=<port>（仅 canvas 主机启用时；目前与 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 → 复现问题 → 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）。