English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

网关

Bonjour 设备发现

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

Tailscale 上的广域 Bonjour（单播 DNS-SD）

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

高层步骤：

  1. 在 Gateway 网关主机上运行 DNS 服务器（可通过 Tailnet 访问）。
  2. 在专用区域下发布 _openclaw-gw._tcp 的 DNS-SD 记录 （示例：openclaw.internal.）。
  3. 配置 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 服务器设置（Gateway 网关主机）

openclaw dns setup --apply

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

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

从已连接到 Tailnet 的机器验证：

dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @&lt;TAILNET_IPV4&gt; -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

Tailscale DNS 设置

在 Tailscale 管理控制台中：

  • 添加一个指向 Gateway 网关 Tailnet IP 的名称服务器（UDP/TCP 53）。
  • 添加拆分 DNS，让你的发现域使用该名称服务器。

客户端接受 Tailnet DNS 后，iOS 节点和 CLI 发现就可以在你的发现域中浏览 _openclaw-gw._tcp，无需组播。

Gateway 网关监听安全性（推荐）

Gateway 网关 WS 端口（默认 18789）默认绑定到回环地址。对于局域网/Tailnet 访问，请显式绑定并保持身份验证启用。

对于仅 Tailnet 设置：

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

什么会进行通告

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

服务类型

  • _openclaw-gw._tcp - Gateway 网关传输信标（供 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 host 启用时；当前与 gatewayPort 相同）
  • transport=gateway
  • tailnetDns=<magicdns>（仅 mDNS 完整模式；Tailnet 可用时的可选提示）
  • sshPort=<port>（仅 mDNS 完整模式；广域 DNS-SD 可能会省略它）
  • cliPath=<path>（仅 mDNS 完整模式；广域 DNS-SD 仍会将其写入作为远程安装提示）

安全说明：

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

在 macOS 上调试

有用的内置工具：

  • 浏览实例：

    dns-sd -B _openclaw-gw._tcp local.

  • 解析一个实例（替换 <instance>）：

    dns-sd -L "<instance>" _openclaw-gw._tcp local.

如果浏览可用但解析失败，通常是遇到了局域网策略或 mDNS 解析器问题。

在 Gateway 网关日志中调试

Gateway 网关会写入滚动日志文件（启动时打印为 gateway log file: ...）。查找 bonjour: 行，尤其是：

  • 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 ...

当系统主机名是有效 DNS 标签时，Bonjour 会使用系统主机名作为通告的 .local 主机。如果系统主机名包含空格、下划线或其他无效的 DNS 标签字符，OpenClaw 会回退到 openclaw.local。当你需要显式主机标签时，在启动 Gateway 网关前设置 OPENCLAW_MDNS_HOSTNAME=<name>。

在 iOS 节点上调试

iOS 节点使用 NWBrowser 发现 _openclaw-gw._tcp。

捕获日志：

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

日志包含浏览器状态转换和结果集变化。

何时启用 Bonjour

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

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

openclaw plugins enable bonjour

启用后，Bonjour 使用 discovery.mdns.mode 来决定发布多少 TXT 元数据。默认模式为 minimal；仅当本地客户端需要 cliPath 或 sshPort 提示时才使用 full，并使用 off 在不改变插件启用状态的情况下抑制局域网组播。

何时禁用 Bonjour

当局域网组播通告不必要、不可用或有害时，保持 Bonjour 禁用。常见情况包括非 macOS 服务器、Docker 桥接网络、 WSL，或丢弃 mDNS 组播的网络策略。在这些环境中，Gateway 网关仍然可以通过其发布的 URL、SSH、Tailnet 或广域 DNS-SD 访问，但局域网自动发现并不可靠。

当问题属于部署范围时，优先使用现有环境覆盖：

OPENCLAW_DISABLE_BONJOUR=1

这会在不改变插件配置的情况下禁用局域网组播通告。 它适用于 Docker 镜像、服务文件、启动脚本和一次性 调试，因为环境消失后该设置也会消失。

当你确实想为该 OpenClaw 配置关闭内置局域网发现插件时，使用插件配置：

openclaw plugins disable bonjour

Docker 注意事项

在检测到容器且未设置 OPENCLAW_DISABLE_BONJOUR 时，内置 Bonjour 插件会自动禁用局域网组播通告。Docker 桥接网络 通常不会在容器和局域网之间转发 mDNS 组播（224.0.0.251:5353），因此从容器通告很少能让发现正常工作。

重要注意事项：

  • Bonjour 会在 macOS 主机上自动启动，在其他地方需要选择启用。保持它 禁用不会停止 Gateway 网关；它只会跳过局域网组播通告。
  • 禁用 Bonjour 不会改变 gateway.bind；Docker 仍默认使用 OPENCLAW_GATEWAY_BIND=lan，因此发布的主机端口可以工作。
  • 禁用 Bonjour 不会禁用广域 DNS-SD。当 Gateway 网关和节点不在同一局域网时，请使用广域发现 或 Tailnet。
  • 在 Docker 外复用同一个 OPENCLAW_CONFIG_DIR 不会持久化 容器自动禁用策略。
  • 仅在主机网络、macvlan 或其他已知可通过 mDNS 组播的网络中设置 OPENCLAW_DISABLE_BONJOUR=0；设置为 1 可强制禁用。

排查已禁用的 Bonjour

如果 Docker 设置后节点不再自动发现 Gateway 网关：

  1. 确认 Gateway 网关是在自动、强制开启还是强制关闭模式下运行：

    docker compose config | grep OPENCLAW_DISABLE_BONJOUR

  2. 确认 Gateway 网关本身可通过发布的端口访问：

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

  3. 在 Bonjour 禁用时使用直接目标：

    • Control 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 强制通告，请从主机测试组播：

    dns-sd -B _openclaw-gw._tcp local.

    如果浏览结果为空，或 Gateway 网关日志显示重复的 ciao 看门狗 取消，请恢复 OPENCLAW_DISABLE_BONJOUR=1，并使用直接路由或 Tailnet 路由。

常见失败模式

  • Bonjour 不会跨网络：使用 Tailnet 或 SSH。
  • 组播被阻止：某些 Wi-Fi 网络会禁用 mDNS。
  • 通告器卡在探测/通告中：组播被阻止的主机、 容器桥接、WSL 或接口频繁变化，可能会让 ciao 通告器处于 未通告状态。OpenClaw 会重试几次，然后为当前 Gateway 网关进程禁用 Bonjour， 而不是永远重启通告器。
  • Docker 桥接网络：Bonjour 会在检测到的容器中自动禁用。 仅对主机、macvlan 或其他支持 mDNS 的网络设置 OPENCLAW_DISABLE_BONJOUR=0。
  • 睡眠 / 接口变化：macOS 可能会临时丢失 mDNS 结果；请重试。
  • 浏览可用但解析失败：保持机器名称简单（避免表情符号或 标点），然后重启 Gateway 网关。服务实例名来源于 主机名，因此过于复杂的名称可能会使某些解析器混淆。

转义实例名（\032）

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

  • 这在协议层面是正常的。
  • UI 应解码后用于显示（iOS 使用 BonjourEscapes.decode）。

启用 / 禁用 / 配置

  • macOS 主机默认自动启动内置局域网发现插件。
  • openclaw plugins enable bonjour 会在未默认启用的主机上启用内置局域网发现插件。
  • openclaw plugins disable bonjour 通过禁用内置插件来禁用局域网组播通告。
  • OPENCLAW_DISABLE_BONJOUR=1 会在不改变插件配置的情况下禁用局域网组播通告；接受的真值为 1、true、yes 和 on（旧版：OPENCLAW_DISABLE_BONJOUR）。
  • OPENCLAW_DISABLE_BONJOUR=0 会强制开启局域网组播通告，包括在检测到的容器内；接受的假值为 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）。

相关文档