Bonjour 发现

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

基于 Tailscale 的广域 Bonjour（单播 DNS-SD）¶

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

在网关主机上运行一个可通过 Tailnet 访问的 DNS 服务器。
在专用区域（例如：openclaw.internal.）下为 _openclaw-gw._tcp 发布 DNS-SD 记录。
配置 Tailscale 拆分 DNS（split 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）¶

openclaw dns setup --apply

此命令仅适用于 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）默认绑定到回环地址（loopback）。对于 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>`	仅限完整模式；在 minimal 和 off 模式下省略。
`cliPath=<path>`	仅限完整模式；在 minimal 和 off 模式下省略。

安全说明：

Bonjour/mDNS TXT 记录是未经认证的。客户端不得将 TXT 视为权威路由。
提供基于发现的路由功能的客户端应使用解析后的服务端点（SRV + A/AAAA）。仅将 lanHost、tailnetDns、gatewayPort 和 gatewayTlsSha256 视为提示。
在支持的情况下，SSH 自动定向也应使用解析后的服务主机，而非仅使用 TXT 提示。
TLS 固定绝不能让通告的 gatewayTlsSha256 覆盖先前存储的 pin。
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.

如果浏览（browsing）正常但解析（resolving）失败，通常是遇到了局域网策略或 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。

要捕获日志：设置 -> 网关 -> 高级 -> 发现调试日志（Discovery Debug Logs），然后设置 -> 网关 -> 高级 -> 发现日志（Discovery Logs） -> 重现问题 -> 复制（Copy）。日志中包含浏览器状态转换和结果集变更。

何时启用 Bonjour¶

Bonjour 会在 macOS 主机的空配置网关启动时自动运行，因为本地应用和附近的 iOS/Android 节点通常依赖同一局域网内的发现机制。

当在 Linux、Windows 或其他非 macOS 主机上需要同一局域网自动发现功能时，请显式启用：

openclaw plugins enable bonjour

启用后，Bonjour 使用 discovery.mdns.mode 来决定发布多少 TXT 元数据；该模式同样控制广域 DNS-SD 记录中的可选 TXT 提示。模式如下：

模式	行为
`minimal`（默认）	仅包含核心 TXT 键；省略 `sshPort`、`cliPath`、`tailnetDns`。
`full`	添加 `sshPort`、`cliPath`、`tailnetDns` —— 当客户端需要这些提示时使用。
`off`	在不改变插件启用状态的情况下抑制局域网多播；当设置了 `discovery.wideArea.domain` 时，广域 DNS-SD 仍可发布。

模式更改会热应用，无需重启网关或断开客户端连接。发现所有者会在发布新模式之前停止先前的广告。减少披露范围也会更新已配置的广域 DNS-SD 区域中的 TXT 提示。更改模式不会启用已禁用的 Bonjour 插件。

何时禁用 Bonjour¶

当局域网多播广告不必要、不可用或有害时，请保持 Bonjour 禁用 —— 常见场景包括非 macOS 服务器、Docker 桥接网络、WSL，或丢弃 mDNS 多播的网络策略。网关仍然可以通过已发布的 URL、SSH、Tailnet 或广域 DNS-SD 访问；只是局域网自动发现不可靠。

对于部署范围内的问题，请使用环境变量覆盖（适用于 Docker 镜像、服务文件、启动脚本、一次性调试 —— 它会随环境消失而消失）：

OPENCLAW_DISABLE_BONJOUR=1

当你有意要为该 OpenClaw 配置关闭自带的局域网发现插件时，请使用插件配置：

openclaw plugins disable bonjour

Docker 注意事项¶

当 OPENCLAW_DISABLE_BONJOUR 未设置时，自带的 Bonjour 插件会在检测到的容器中自动禁用局域网多播广告。Docker 桥接网络通常不会在容器和局域网之间转发 mDNS 多播（224.0.0.251:5353），因此从容器发布广告很少能让发现生效。

注意事项：

Bonjour 在 macOS 主机上自动启动，在其他平台上需手动启用。保持禁用不会阻止网关运行 —— 只是跳过局域网多播广告。
禁用 Bonjour 不会改变 gateway.bind；Docker 仍然默认使用 OPENCLAW_GATEWAY_BIND=lan，因此已发布的主机端口仍然有效。
禁用 Bonjour 不会禁用广域 DNS-SD。当网关和节点不在同一局域网时，请使用广域发现或 Tailnet。
在 Docker 外部复用相同的 OPENCLAW_CONFIG_DIR 不会保留容器自动禁用策略。
仅当使用主机网络、macvlan 或其他已知可以传输 mDNS 多播的网络时，才设置 OPENCLAW_DISABLE_BONJOUR=0；设置为 1 可强制禁用。

排查 Bonjour 被禁用的问题¶

如果在完成 Docker 设置后，节点不再自动发现网关：

确认网关是运行在自动、强制启用还是强制禁用模式：

docker compose config | grep OPENCLAW_DISABLE_BONJOUR

确认网关本身可以通过已发布的端口访问：

curl -fsS http://127.0.0.1:18789/healthz

当 Bonjour 被禁用时，使用直接目标地址：
控制界面或本地工具：http://127.0.0.1:18789
局域网客户端：http://<gateway-host>:18789
跨网络客户端：Tailnet MagicDNS、Tailnet IP、SSH 隧道或广域 DNS-SD
如果你在 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。
通告者卡在探测/通告阶段：组播被阻止、容器网桥、WSL 或接口变动频繁的主机，可能让响应器停留在未通告状态。Gateway 仍可通过直连、SSH、Tailnet 或广域 DNS-SD 路由访问；当组播不可用时，使用 discovery.mdns.mode: "off" 或 OPENCLAW_DISABLE_BONJOUR=1 禁用局域网 Bonjour。
Docker 桥接网络：在检测到的容器中，Bonjour 会自动禁用。仅对 host、macvlan 或其他支持 mDNS 的网络设置 OPENCLAW_DISABLE_BONJOUR=0。
睡眠/接口变动：macOS 可能临时丢弃 mDNS 结果；请重试。
浏览正常但解析失败：保持机器名简单（避免表情符号或标点），然后重启 gateway。服务实例名称由主机名派生，因此过于复杂的名称可能会令某些解析器困惑。

转义实例名称（`\032`）¶

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

启用 / 禁用 / 配置¶

设置	效果
`openclaw plugins enable bonjour`	在未默认启用捆绑局域网发现插件的主机上启用该插件。
`openclaw plugins disable bonjour`	通过禁用捆绑插件来禁用局域网组播通告。
`OPENCLAW_DISABLE_BONJOUR=1`（或 `true`/`yes`/`on`）	在不更改插件配置的情况下禁用局域网组播通告。
`OPENCLAW_DISABLE_BONJOUR=0`（或 `false`/`no`/`off`）	强制启用局域网组播通告，包括在检测到的容器内部。
`discovery.mdns.mode`	`off` \| `minimal`（默认）\| `full` — 参见上文模式。
`gateway.bind`	控制 `~/.openclaw/openclaw.json` 中的 gateway 绑定模式。
`OPENCLAW_SSH_PORT`	在通告 `sshPort` 时覆盖 SSH 端口（full 模式）。
`OPENCLAW_TAILNET_DNS`	当启用 mDNS full 模式时，在 TXT 中发布 MagicDNS 提示。
`OPENCLAW_CLI_PATH`	覆盖所通告的 CLI 路径（full 模式）。

macOS 主机默认会自动启动捆绑的局域网发现插件。当 Bonjour 插件已启用且 OPENCLAW_DISABLE_BONJOUR 未设置时，Bonjour 会在普通主机上通告，并在检测到的容器（Docker、Fly.io 机器和常见容器运行时）内自动禁用。

发现策略与传输选择：发现
节点配对与审批：Gateway 配对
广域 DNS-SD 设置助手：openclaw dns

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw