Bonjour 发现

​

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

1. 在 Gateway 主机上运行一个 DNS 服务器（可通过 Tailnet 访问）。
2. 在专用区域下为 _openclaw-gw._tcp 发布 DNS-SD 记录 （示例：openclaw.internal.）。
3. 配置 Tailscale 分割 DNS，使你选择的域通过该 DNS 服务器为客户端（包括 iOS）解析。

​

Gateway 配置（推荐）

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

​

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

openclaw dns setup --apply

• 仅在 Gateway 的 Tailscale 接口上监听 53 端口
• 从 ~/.openclaw/dns/<domain>.db 提供你选择的域（示例：openclaw.internal.）

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

​

Tailscale DNS 设置

• 添加一个指向 Gateway 的 tailnet IP 的 nameserver（UDP/TCP 53）。
• 添加 split DNS，使你的发现域使用该 nameserver。

​

Gateway 监听器安全性（推荐）

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

​

谁会进行广播

​

服务类型

• _openclaw-gw._tcp - gateway 传输信标（供 macOS/iOS/Android 节点使用）。

​

TXT 键（非秘密提示）

• role=gateway
• displayName=<friendly name>
• lanHost=<hostname>.local
• gatewayPort=<port>（Gateway WS + HTTP）
• gatewayTls=1（仅在启用 TLS 时）
• gatewayTlsSha256=<sha256>（仅在启用 TLS 且指纹可用时）
• canvasPort=<port>（仅在启用 canvas host 时；当前与 gatewayPort 相同）
• transport=gateway
• tailnetDns=<magicdns> （仅 mDNS 完整模式；当 Tailnet 可用时的可选提示）
• sshPort=<port> （仅完整模式；在最小模式和关闭模式中省略）
• cliPath=<path> （仅完整模式；在最小模式和关闭模式中省略）

• Bonjour/mDNS TXT 记录是未经认证的。客户端不得将 TXT 视为权威路由信息。
• 客户端应使用解析得到的服务端点（SRV + A/AAAA）进行路由。将 lanHost、tailnetDns、gatewayPort 和 gatewayTlsSha256 仅视为提示。
• SSH 自动目标选择同样应使用解析得到的服务主机，而不是仅依赖 TXT 提示。
• TLS pinning 绝不能允许广告中的 gatewayTlsSha256 覆盖之前存储的 pin。
• iOS/Android 节点应将基于发现的直接连接视为 仅 TLS，并且在首次信任指纹前需要显式用户确认。

​

在 macOS 上调试

• 浏览实例：
  dns-sd -B _openclaw-gw._tcp local.
  
• 解析一个实例（替换 <instance>）：
  dns-sd -L "<instance>" _openclaw-gw._tcp local.
  

​

在 Gateway 日志中调试

• bonjour: advertise failed ...
• bonjour: suppressing ciao cancellation ...
• bonjour: ... name conflict resolved / hostname conflict resolved
• bonjour: watchdog detected non-announced service ...
• bonjour: disabling advertiser after ... failed restarts ...

​

在 iOS 节点上调试

• Settings → Gateway → Advanced → Discovery Debug Logs
• Settings → Gateway → Advanced → Discovery Logs → 复现 → Copy

​

何时启用 Bonjour

openclaw plugins enable bonjour

​

何时禁用 Bonjour

OPENCLAW_DISABLE_BONJOUR=1

openclaw plugins disable bonjour

​

Docker 注意事项

• Bonjour 会在 macOS 主机上自动启动，在其他地方则需要显式启用。保持其 禁用不会停止 Gateway；它只会跳过 LAN 多播广播。
• 禁用 Bonjour 不会更改 gateway.bind；Docker 仍然默认 OPENCLAW_GATEWAY_BIND=lan，因此已发布的主机端口可以工作。
• 禁用 Bonjour 不会禁用广域 DNS-SD。当 Gateway 和节点不在同一 LAN 上时，请使用广域发现 或 Tailnet。
• 在 Docker 外部重用相同的 OPENCLAW_CONFIG_DIR 不会保留 容器自动禁用策略。
• 仅在 host networking、macvlan 或其他已知支持 mDNS 多播的 网络中将 OPENCLAW_DISABLE_BONJOUR=0；将其设为 1 可强制禁用。

​

排查已禁用的 Bonjour

1. 确认 Gateway 运行在自动、强制开启或强制关闭模式：
   docker compose config | grep OPENCLAW_DISABLE_BONJOUR
   
2. 确认 Gateway 本身可通过发布的端口访问：
   curl -fsS http://127.0.0.1:18789/healthz
   
3. 当 Bonjour 被禁用时，使用直接目标：
   • 控制 UI 或本地工具：http://127.0.0.1:18789
   • LAN 客户端：http://<gateway-host>:18789
   • 跨网络客户端：Tailnet MagicDNS、Tailnet IP、SSH 隧道，或 广域 DNS-SD
4. 如果你在 Docker 中有意启用了 Bonjour 插件并使用 OPENCLAW_DISABLE_BONJOUR=0 强制广播，请从主机测试多播：
   dns-sd -B _openclaw-gw._tcp local.
   
   如果浏览为空，或者 Gateway 日志显示反复的 ciao 看门狗 取消，请恢复 OPENCLAW_DISABLE_BONJOUR=1 并使用直接路由或 Tailnet 路由。

​

常见故障模式

• Bonjour 不跨网络：请使用 Tailnet 或 SSH。
• 多播被阻止：某些 Wi-Fi 网络会禁用 mDNS。
• 广告器卡在 probing/announcing：主机上被阻止的多播、 容器桥接、WSL 或接口频繁变动都可能让 ciao 广播器处于 未宣布状态。OpenClaw 会重试几次，然后为当前 Gateway 进程 禁用 Bonjour，而不是无限重启广告器。
• Docker bridge 网络：Bonjour 会在检测到的容器中自动禁用。 仅在 host、macvlan 或其他已知支持 mDNS 的网络中将 OPENCLAW_DISABLE_BONJOUR=0。
• 睡眠 / 接口频繁变动：macOS 可能会暂时丢失 mDNS 结果；请重试。
• 浏览正常但解析失败：保持机器名简洁（避免 emoji 或 标点），然后重启 Gateway。服务实例名来源于 主机名，因此过于复杂的名称可能会让某些解析器感到困惑。

​

转义的实例名（\032）

• 这是协议层面的正常现象。
• UI 应在显示时进行解码（iOS 使用 BonjourEscapes.decode）。

​

启用 / 禁用 / 配置

• macOS 主机会默认自动启动捆绑的 LAN 发现插件。
• openclaw plugins enable bonjour 会在未默认启用的主机上启用捆绑的 LAN 发现插件。
• openclaw plugins disable bonjour 会通过禁用捆绑插件来禁用 LAN 多播广播。
• OPENCLAW_DISABLE_BONJOUR=1 会在不更改插件配置的情况下禁用 LAN 多播广播；可接受的真值为 1、true、yes 和 on（旧式：OPENCLAW_DISABLE_BONJOUR）。
• OPENCLAW_DISABLE_BONJOUR=0 会强制开启 LAN 多播广播，包括在检测到的容器内；可接受的假值为 0、false、no 和 off。
• 当 Bonjour 插件已启用且 OPENCLAW_DISABLE_BONJOUR 未设置时，Bonjour 会在正常主机上广播，并在检测到的容器内自动禁用。
• ~/.openclaw/openclaw.json 中的 gateway.bind 控制 Gateway 的绑定模式。
• 当 sshPort 被广播时，OPENCLAW_SSH_PORT 会覆盖 SSH 端口（旧式：OPENCLAW_SSH_PORT）。
• 当启用 mDNS 完整模式时，OPENCLAW_TAILNET_DNS 会在 TXT 中发布 MagicDNS 提示（旧式：OPENCLAW_TAILNET_DNS）。
• OPENCLAW_CLI_PATH 会覆盖广播的 CLI 路径（旧式：OPENCLAW_CLI_PATH）。

​

相关文档

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