Bonjour 发现

Bonjour / mDNS 发现

OpenClaw 使用 Bonjour (mDNS / DNS-SD) 作为一种仅限局域网的便利手段来发现活动的 Gateway(网关) 网关（WebSocket 端点）。它是尽力而为的，并不替代 SSH 或基于 Tailnet 的连接。

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

如果节点和网关位于不同的网络上，组播 mDNS 将无法跨越边界。您可以通过切换到基于 Tailscale 的单播 DNS-SD （“广域 Bonjour”）来保持相同的发现体验。

高级步骤：

在网关主机上运行 DNS 服务器（可通过 Tailnet 访问）。
在专用区域下发布 _openclaw-gw._tcp 的 DNS‑SD 记录（例如：openclaw.internal.）。
配置 Tailscale 分流 DNS，以便为您选择的域通过该 DNS 服务器进行解析（适用于包括 iOS 在内的客户端）。

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

Gateway(网关) 配置（推荐）

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

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

openclaw dns setup --apply

这将安装 CoreDNS 并将其配置为：

仅在网关的 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(网关) listener security (recommended)

Gateway(网关) WS 端口（默认 18789）默认绑定到环回地址。要进行局域网/ tailnet 访问，请显式绑定并保持身份验证已启用。

对于仅 tailnet 的设置：

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

发布广播内容

只有 Gateway(网关) 会通告 _openclaw-gw._tcp。

服务类型

_openclaw-gw._tcp — 网关传输信标（由 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 主机时；当前与 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 上调试

有用的内置工具：

浏览实例：
Terminal window
```
dns-sd -B _openclaw-gw._tcp local.
```
解析一个实例（替换 <instance>）：
Terminal window
```
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。

要捕获日志：

Settings → Gateway(网关) → Advanced → 设备发现 Debug Logs
Settings → Gateway(网关) → Advanced → 设备发现 Logs → reproduce → Copy

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

常见故障模式

Bonjour 无法跨网络：请使用 Tailnet 或 SSH。
组播被阻止：某些 Wi‑Fi 网络会禁用 mDNS。
休眠 / 接口变动：macOS 可能会暂时丢失 mDNS 结果；请重试。
Browse works but resolve fails：保持机器名称简单（避免表情符号或标点符号），然后重启 Gateway(网关)。服务实例名称派生自主机名，因此过于复杂的名称可能会使某些解析器感到困惑。

转义的实例名称 (`\032`)

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

这在协议级别是正常的。
UI 应进行解码以供显示（iOS 使用 BonjourEscapes.decode）。

禁用 / 配置

OPENCLAW_DISABLE_BONJOUR=1 禁用通告（旧版：OPENCLAW_DISABLE_BONJOUR）。
gateway.bind 中的 ~/.openclaw/openclaw.json 控制 Gateway(网关) 绑定模式。
OPENCLAW_SSH_PORT 覆盖 TXT 中通告的 SSH 端口（旧版：OPENCLAW_SSH_PORT）。
OPENCLAW_TAILNET_DNS 在 TXT 中发布 MagicDNS 提示（旧版：OPENCLAW_TAILNET_DNS）。
OPENCLAW_CLI_PATH 会覆盖通告的 CLI 路径（旧版：OPENCLAW_CLI_PATH）。