Bonjour 发现
OpenClaw 可以使用 Bonjour(mDNS/DNS-SD)来发现活跃的网关(WebSocket 端点)。组播 local. 浏览是一种仅限局域网的便利功能:随附的 bonjour 插件负责 LAN 通告,在 macOS 主机上自动启动,在 Linux、Windows 和容器化网关部署中为可选启用。同一信标还可以通过配置的广域网 DNS-SD 域发布,以实现跨网络发现。发现是尽力而为的,不能替代基于 SSH 或 Tailnet 的连接。
基于 Tailscale 的广域网 Bonjour(单播 DNS-SD)¶
如果节点和网关位于不同网络,组播 mDNS 无法跨越边界。通过切换到基于 Tailscale 的单播 DNS-SD(“广域网 Bonjour”),可以保持相同的发现体验:
- 在网关主机上运行一个 DNS 服务器,可通过 Tailnet 访问。
- 在专用区域(示例:
openclaw.internal.)下发布_openclaw-gw._tcp的 DNS-SD 记录。 - 配置 Tailscale 拆分 DNS,使您选择的域通过该 DNS 服务器为客户端(包括 iOS)解析。
上面的 openclaw.internal. 只是一个示例——OpenClaw 支持任何发现域。iOS/Android 节点同时浏览 local. 和您配置的广域网域。
网关配置¶
{
gateway: { bind: "tailnet" }, // tailnet-only (recommended)
discovery: { wideArea: { domain: "openclaw.internal" } },
}
设置 discovery.wideArea.domain 可启用网关的广域网发布。OPENCLAW_WIDE_AREA_DOMAIN 环境变量为 CLI 发现和 DNS 设置提供默认值;它本身不会启用网关发布。
一次性 DNS 服务器设置(网关主机,仅限 macOS)¶
此命令仅适用于 macOS,需要 Homebrew 和正在运行的 Tailscale 连接。它会安装 CoreDNS(brew install coredns)并配置为:
- 仅在网关的 Tailscale 接口上监听 53 端口
- 从
~/.openclaw/dns/<domain>.db提供您选择的域(示例:openclaw.internal.)
先不带 --apply 运行,以预览计划(域、区域文件路径、检测到的 Tailnet IP、推荐配置),而无需安装任何内容。
从已连接 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,以便您的发现域使用该名称服务器。
一旦客户端接受 Tailnet DNS,iOS 节点和 CLI 发现便可在没有组播的情况下浏览发现域中的 _openclaw-gw._tcp。
网关监听器安全¶
网关 WS 端口(默认 18789)默认绑定到回环地址。如需 LAN/Tailnet 访问,请显式绑定并保持认证启用。对于仅 Tailnet 的设置,请在 ~/.openclaw/openclaw.json 中设置 gateway.bind: "tailnet",然后重启网关(或 macOS 菜单栏应用)。
通告内容¶
只有网关会通告 _openclaw-gw._tcp。LAN 组播通告在启用时来自随附的 bonjour 插件;广域网 DNS-SD 发布仍由网关负责。
服务类型¶
_openclaw-gw._tcp- 网关传输信标,供 macOS/iOS/Android 节点使用。
TXT 键(非机密提示)¶
| 键 | 何时存在 |
|---|---|
role=gateway |
始终。 |
displayName=<friendly name> |
始终。 |
lanHost=<hostname>.local |
始终。 |
gatewayPort=<port> |
始终(网关 WS + HTTP)。 |
transport=gateway |
始终。 |
gatewayTls=1 |
仅在启用 TLS 时。 |
gatewayTlsSha256=<sha256> |
仅在启用 TLS 且指纹可用时。 |
gatewayDirectReachable=1 |
仅当网关可直接访问时(不只是通过中继/代理路径)。 |
tailnetDns=<magicdns> |
仅限 mDNS 完整模式;当 Tailnet 可用时的可选提示。 |
sshPort=<port> |
仅限完整模式;在精简模式和关闭模式下省略。 |
cliPath=<path> |
仅限完整模式;在精简模式和关闭模式下省略。 |
安全说明:
- Bonjour/mDNS TXT 记录未经认证。客户端不得将 TXT 视为权威路由。
- 提供基于发现的路由的客户端应使用解析后的服务端点(SRV + A/AAAA)。仅将
lanHost、tailnetDns、gatewayPort和gatewayTlsSha256视为提示。 - 在支持的情况下,SSH 自动定向也应使用解析后的服务主机,而不是仅凭 TXT 提示。
- TLS 固定绝不允许通告的
gatewayTlsSha256覆盖先前存储的固定值。 - iOS/Android 节点应将基于发现的直接连接视为仅 TLS,并在信任首次指纹之前要求用户明确确认。
macOS 应用同样将解析后的端点视为提示。选择附近的网关会打开连接编辑器;它不会向通告的目标进行身份验证、更改已保存的路由,或导入 SSH 详细信息或证书固定值。提供受信任的地址、SSH 目标或所有者提供的设置代码,然后保存连接。请参阅在应用中配置。
在 macOS 上调试¶
内置工具:
# Browse instances
dns-sd -B _openclaw-gw._tcp local.
# Resolve one instance (replace <instance>)
dns-sd -L "<instance>" _openclaw-gw._tcp local.
如果浏览正常但解析失败,通常是遇到了 LAN 策略或 mDNS 解析器问题。
在网关日志中调试¶
网关会写入一个滚动日志文件(启动时打印为 gateway log file: ...)。查找 bonjour: 行,尤其是:
bonjour: advertise failed ...bonjour: suppressing ciao netmask assertion ...bonjour: ... name conflict resolved/hostname conflict resolved
OpenClaw 只启动每个 Bonjour 服务一次,并将检查、重试、名称冲突解决以及接口变更后的重新发布交给 mDNS 响应器。这可以避免在正常网络变化期间出现重复的发布尝试。重复的内部自检消息会被抑制,以免刷爆网关日志;当网络接口(例如短生命周期的 Docker 网桥)在响应器的接口轮询之间被移除时,短暂的 ENODEV MDNS 套接字警告也会被抑制。
当多个 OpenClaw 网关从同一主机发布通告时,Bonjour 可能会追加诸如 (2) 或 (3) 的后缀,以保持服务实例名称唯一。这些后缀属于正常的冲突解决。
当系统主机名是有效的 DNS 标签时,Bonjour 会使用系统主机名作为所通告的 .local 主机。如果系统主机名包含空格、下划线或其他无效的 DNS 标签字符,OpenClaw 会回退到 openclaw.local。当需要显式主机标签时,请在启动网关前设置 OPENCLAW_MDNS_HOSTNAME=<name>。
在 iOS 节点上调试¶
iOS 节点使用 NWBrowser 来发现 _openclaw-gw._tcp。
要捕获日志:Settings -> Gateway -> Advanced -> Discovery Debug Logs,然后 Settings -> Gateway -> Advanced -> Discovery Logs -> 复现 -> Copy。日志包括浏览器状态转换和结果集变化。
何时启用 Bonjour¶
在 macOS 主机上,空配置的网关启动时会自动启动 Bonjour,因为本地应用和附近的 iOS/Android 节点通常依赖同一 LAN 的发现。
在 Linux、Windows 或其他非 macOS 主机上,如果同一 LAN 自动发现有用,请显式启用它:
启用后,Bonjour 会使用 discovery.mdns.mode 来决定发布多少 TXT 元数据;同一模式也会控制广域 DNS-SD 记录中的可选 TXT 提示。模式:
| 模式 | 行为 |
|---|---|
minimal(默认) |
仅核心 TXT 键;省略 sshPort、cliPath、tailnetDns。 |
full |
添加 sshPort、cliPath、tailnetDns —— 当客户端需要这些提示时使用。 |
off |
抑制 LAN 多播,但不更改插件启用状态;当设置 discovery.wideArea.domain 时,广域 DNS-SD 仍可以发布。 |
模式更改会热生效,无需重启网关或断开客户端。 发现所有者在发布新模式之前会停止先前的通告。减少披露也会更新任何已配置广域 DNS-SD 区域中的 TXT 提示。更改模式不会启用已禁用的 Bonjour 插件。
何时禁用 Bonjour¶
当 LAN 多播通告没有必要、不可用或有害时,请保持 Bonjour 禁用——常见情况包括非 macOS 服务器、Docker 网桥网络、WSL,或会丢弃 mDNS 多播的网络策略。网关仍可通过其已发布的 URL、SSH、Tailnet 或广域 DNS-SD 访问;只有 LAN 自动发现不可靠。
对于部署范围的问题,请使用环境变量覆盖(对 Docker 镜像、服务文件、启动脚本、一次性调试是安全的——当环境消失时它也会消失):
当你有意要为该 OpenClaw 配置关闭内置的 LAN 发现插件时,请使用插件配置:
Docker 注意事项¶
当 OPENCLAW_DISABLE_BONJOUR 未设置时,内置的 Bonjour 插件会在检测到的容器中自动禁用 LAN 多播通告。Docker 网桥网络通常不会在容器和 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不会持久化容器自动禁用策略。 - 仅在主机网络、macvlan 或其他已知可通过 mDNS 多播的网络中设置
OPENCLAW_DISABLE_BONJOUR=0;设置1可强制禁用。
排查已禁用的 Bonjour¶
如果在 Docker 配置后节点不再自动发现网关:
- 确认网关是否运行在自动、强制开启或强制关闭模式:
- 确认网关本身可通过已发布端口访问:
- 当 Bonjour 被禁用时,使用直接目标:
- 控制 UI 或本地工具:
http://127.0.0.1:18789 - LAN 客户端:
http://<gateway-host>:18789 -
跨网络客户端:Tailnet MagicDNS、Tailnet IP、SSH 隧道或广域 DNS-SD
-
如果你有意在 Docker 中启用了 Bonjour 插件,并使用
OPENCLAW_DISABLE_BONJOUR=0强制通告,请从主机测试多播:
如果浏览结果为空,或 Gateway 日志显示反复出现 ciao 检查失败,请恢复 OPENCLAW_DISABLE_BONJOUR=1,并使用直连或 Tailnet 路由。
常见故障模式¶
- Bonjour 无法跨网络:使用 Tailnet 或 SSH。
- 组播被阻止:某些 Wi-Fi 网络会禁用 mDNS。
- 广播端卡在 checking/announcing:组播被阻止、容器网桥、WSL 或接口频繁变化的主机可能使响应端处于未广播状态。网关仍可通过直连、SSH、Tailnet 或广域 DNS-SD 路由访问;当组播不可用时,使用
discovery.mdns.mode: "off"或OPENCLAW_DISABLE_BONJOUR=1禁用 LAN Bonjour。 - Docker 桥接网络:Bonjour 在检测到的容器中自动禁用。仅在 host、macvlan 或其他支持 mDNS 的网络中设置
OPENCLAW_DISABLE_BONJOUR=0。 - 睡眠/接口频繁变化:macOS 可能暂时丢失 mDNS 结果;请重试。
- 浏览正常但解析失败:保持机器名称简单(避免表情符号或标点符号),然后重启网关。服务实例名称派生自主机名,因此过于复杂的名称可能使某些解析器产生混淆。
转义实例名称(\032)¶
Bonjour/DNS-SD 通常会将服务实例名称中的字节转义为十进制 \DDD 序列(空格变为 \032)。这在协议层面是正常的;UI 应解码后再显示(iOS 使用 BonjourEscapes.decode)。
启用 / 禁用 / 配置¶
| 设置 | 效果 |
|---|---|
openclaw plugins enable bonjour |
在未默认启用的主机上启用捆绑的 LAN 发现插件。 |
openclaw plugins disable bonjour |
通过禁用捆绑插件来禁用 LAN 组播广播。 |
OPENCLAW_DISABLE_BONJOUR=1(或 true/yes/on) |
在不更改插件配置的情况下禁用 LAN 组播广播。 |
OPENCLAW_DISABLE_BONJOUR=0(或 false/no/off) |
强制开启 LAN 组播广播,包括在检测到的容器内部。 |
discovery.mdns.mode |
off | minimal(默认)| full — 参见上述模式。 |
gateway.bind |
控制 ~/.openclaw/openclaw.json 中的网关绑定模式。 |
OPENCLAW_SSH_PORT |
当广播 sshPort 时覆盖 SSH 端口(full 模式)。 |
OPENCLAW_TAILNET_DNS |
当启用 mDNS full 模式时,在 TXT 中发布 MagicDNS 提示。 |
OPENCLAW_CLI_PATH |
覆盖广播的 CLI 路径(full 模式)。 |
macOS 主机默认自动启动捆绑的 LAN 发现插件。当 Bonjour 插件已启用且未设置 OPENCLAW_DISABLE_BONJOUR 时,Bonjour 会在普通主机上广播,并在检测到的容器(Docker、Fly.io 机器以及常见容器运行时)内自动禁用。
相关文档¶
- 发现策略和传输选择:发现
- 节点配对 + 审批:网关配对
- 广域 DNS-SD 设置助手:
openclaw dns
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw