Skip to main content
OpenClaw 可以使用 Bonjour（mDNS/DNS-SD）来发现一个活动的 gateway（WebSocket 端点）。多播 local. 浏览是一种 仅限局域网的便利功能：捆绑的 bonjour 插件负责局域网广播，会在 macOS 主机上自动启动，并可在 Linux、Windows 和容器化 gateway 部署中选择启用。同一个信标也可以通过已配置的广域 DNS-SD 域进行发布，以便跨网络发现。发现功能尽力而为，不能替代 SSH 或基于 Tailnet 的连接。

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

如果节点和网关位于不同网络，组播 mDNS 无法跨越边界。可以通过 Tailscale 切换到 单播 DNS-SD（“广域 Bonjour”），以保持相同的发现体验：
  1. 在网关主机上运行一个 DNS 服务器，并可通过 Tailnet 访问。
  2. 在专用区域下发布 _openclaw-gw._tcp 的 DNS-SD 记录（示例：openclaw.internal.）。
  3. 配置 Tailscale 分流 DNS，让你选择的域通过该 DNS 服务器解析给客户端，包括 iOS。
上面的 openclaw.internal. 只是示例——OpenClaw 支持任意发现域。iOS/Android 节点会同时浏览 local. 和你配置的广域域。

​
网关配置

设置 discovery.wideArea.domain 会启用广域发现。未设置该配置项时，OpenClaw 也接受 OPENCLAW_WIDE_AREA_DOMAIN 环境变量作为后备项。

​
一次性 DNS 服务器设置（网关主机，仅 macOS）

此命令仅适用于 macOS，并且需要 Homebrew 以及正在运行的 Tailscale 连接。它会安装 CoreDNS（brew install coredns），并将其配置为：
  • 仅在 Gateway 的 Tailscale 接口上监听 53 端口
  • 从 ~/.openclaw/dns/<domain>.db 提供你选择的域（示例：openclaw.internal.）
先不带 --apply 运行，以便在不安装任何内容的情况下预览计划（域名、区域文件路径、检测到的 Tailnet IP、推荐配置）。 从连接到 Tailnet 的机器上验证：

​
Tailscale DNS 设置

在 Tailscale 管理控制台中：
  • 添加一个指向网关 Tailnet IP 的名称服务器（UDP/TCP 53）。
  • 添加分流 DNS，使你的发现域使用该名称服务器。
一旦客户端接受 Tailnet DNS，iOS 节点和 CLI 发现就可以在你的发现域中浏览 _openclaw-gw._tcp，而无需组播。

​
网关监听器安全性

网关 WS 端口（默认 18789）默认绑定到本地回环接口。对于 LAN/Tailnet 访问，请显式绑定并保持认证开启。对于仅限 Tailnet 的设置，请在 ~/.openclaw/openclaw.json 中设置 gateway.bind: "tailnet"，然后重启网关（或 macOS 菜单栏应用）。

​
谁会进行广播

只有网关会发布 _openclaw-gw._tcp。启用后，局域网组播广播由内置的 bonjour 插件提供；广域 DNS-SD 发布仍由网关负责。

​
服务类型

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

​
TXT 键（非秘密提示）

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

​
在 macOS 上调试

内置工具：
如果浏览可以但解析失败，通常是遇到了 LAN 策略或 mDNS 解析器问题。

​
在 Gateway 日志中调试

网关会写入一个滚动日志文件（启动时会打印为 gateway log file: ...）。请查找 bonjour: 行，尤其是：
  • bonjour: advertise failed ...
  • bonjour: suppressing ciao netmask assertion ...
  • bonjour: ... name conflict resolved / hostname conflict resolved
OpenClaw 会为每个 Bonjour 服务仅启动一次，并将探测、重试、名称冲突解决以及接口变更后的重新发布交给 mDNS 响应器处理。这样可以避免在正常网络波动期间出现重叠的发布尝试。重复的内部自探测消息会被抑制，因此不会淹没网关日志。 当多个 OpenClaw 网关从同一主机进行广播时，Bonjour 可能会追加诸如（2）或（3）之类的后缀，以保持服务实例名称唯一。这些后缀属于正常的冲突解决行为，不表示存在重复的 OCM 监督。 当系统主机名是有效的 DNS 标签时，Bonjour 会使用它作为已广播的 .local 主机名。如果系统主机名包含空格、下划线或其他无效的 DNS 标签字符，OpenClaw 会回退到 openclaw.local。在需要显式主机标签时，请在启动网关之前设置 OPENCLAW_MDNS_HOSTNAME=<name>。

​
在 iOS 节点上调试

iOS 节点使用 NWBrowser 发现 _openclaw-gw._tcp。 要捕获日志：设置 → 网关 → 高级 → 发现调试日志，然后 设置 → 网关 → 高级 → 发现日志 → 复现 → 复制。日志包括浏览器状态转换和结果集变化。

​
何时启用 Bonjour

Bonjour 会在 macOS 主机上针对空配置网关启动时自动启动，因为本地应用和附近的 iOS/Android 节点通常依赖同一局域网内的发现。 当在 Linux、Windows 或其他非 macOS 主机上，局域网内自动发现有用时，请显式启用它：
启用后，Bonjour 会使用 discovery.mdns.mode 来决定要发布多少 TXT 元数据；同样的模式也会控制广域 DNS-SD 记录中的可选 TXT 提示。模式如下：

​
何时禁用 Bonjour

当 LAN 多播广播不必要、不可用或有害时，请保持 Bonjour 处于禁用状态——常见情况包括非 macOS 服务器、Docker 桥接网络、WSL，或会丢弃 mDNS 多播的网络策略。网关仍可通过其已发布的 URL、SSH、Tailnet 或广域 DNS-SD 访问；只是 LAN 自动发现不可靠。 当问题仅限于某次部署范围时，请使用环境变量覆盖（适用于 Docker 镜像、服务文件、启动脚本、一次性调试——它会在环境消失时一并失效）：
当你有意要为该 OpenClaw 配置关闭内置的 LAN 发现插件时，请使用插件配置：

​
Docker 注意事项

捆绑的 Bonjour 插件在检测到容器且 OPENCLAW_DISABLE_BONJOUR 未设置时，会自动禁用 LAN 多播广播。Docker bridge 网络通常不会在容器和 LAN 之间转发 mDNS 多播（224.0.0.251:5353），因此从容器进行广播很少能让发现正常工作。 注意事项：
  • Bonjour 会在 macOS 主机上自动启动，在其他环境中则可选择启用。保持其禁用不会停止网关——只会跳过 LAN 多播广播。
  • 禁用 Bonjour 不会改变 gateway.bind；Docker 仍然默认使用 OPENCLAW_GATEWAY_BIND=lan，因此已发布的主机端口仍可正常工作。
  • 禁用 Bonjour 不会禁用广域 DNS-SD。当网关和节点不在同一 LAN 上时，请使用广域发现或 Tailnet。
  • 在 Docker 外部重用相同的 OPENCLAW_CONFIG_DIR 不会保留容器的自动禁用策略。
  • 仅在 host networking、macvlan 或其他已知 mDNS 多播可以通过的网络中将 OPENCLAW_DISABLE_BONJOUR=0；将其设置为 1 可强制禁用。

​
排查已禁用的 Bonjour

如果某个节点在 Docker 设置后不再自动发现网关：
  1. 确认网关当前是自动、强制开启，还是强制关闭模式：
  2. 确认网关本身是否可通过已发布端口访问：
  3. 在禁用 Bonjour 时使用直接目标：
    • 控制 UI 或本地工具：http://127.0.0.1:18789
    • 局域网客户端：http://<gateway-host>:18789
    • 跨网络客户端：Tailnet MagicDNS、Tailnet IP、SSH 隧道，或广域 DNS-SD
  4. 如果你在 Docker 中特意启用了 Bonjour 插件，并通过 OPENCLAW_DISABLE_BONJOUR=0 强制广播，请在主机上测试多播：
    如果浏览结果为空，或者网关日志显示 ciao 探测失败反复出现，请恢复 OPENCLAW_DISABLE_BONJOUR=1，并改用直接或 Tailnet 路由。

​
常见故障模式

  • Bonjour 不会跨网络传递：请使用 Tailnet 或 SSH。
  • 多播被阻止：某些 Wi-Fi 网络会禁用 mDNS。
  • 广告器卡在 probing/announcing 状态：如果主机的多播被阻止、使用容器桥接、WSL，或接口频繁变动，responder 可能会保持在未发布状态。网关仍可通过 direct、SSH、Tailnet 或广域 DNS-SD 路径访问；当多播不可用时，请通过 discovery.mdns.mode: "off" 或 OPENCLAW_DISABLE_BONJOUR=1 禁用 LAN Bonjour。
  • Docker 桥接网络：在检测到的容器中，Bonjour 会自动禁用。仅在主机、macvlan 或其他支持 mDNS 的网络上设置 OPENCLAW_DISABLE_BONJOUR=0。
  • 睡眠/接口变动：macOS 可能会暂时丢失 mDNS 结果；请重试。
  • 浏览正常但解析失败：请保持机器名简单（避免表情符号或标点），然后重启网关。服务实例名来自主机名，因此过于复杂的名称可能会让某些解析器出错。

​
转义的实例名（\032）

Bonjour/DNS-SD 通常会在服务实例名中将字节转义为十进制的 \DDD 序列（空格会变成 \032）。这在协议层面是正常的；用户界面应在显示时进行解码（iOS 使用 BonjourEscapes.decode）。

​
启用 / 禁用 / 配置

macOS 主机会默认自动启动捆绑的 LAN 发现插件。启用 Bonjour 插件且未设置 OPENCLAW_DISABLE_BONJOUR 时，Bonjour 会在普通主机上进行广播，并在检测到的容器内自动禁用（Docker、Fly.io machines 以及常见容器运行时）。

​
相关文档