OpenClaw 🦞

Bonjour 发现

Bonjour / mDNS 发现

OpenClaw 使用 Bonjour（mDNS / DNS‑SD）作为 仅限 LAN 的便利方式 来发现 活动的 Gateway（WebSocket 端点）。这是尽力而为的，不 替代 SSH 或 Tailnet 基础的连接。

通过 Tailscale 的广域 Bonjour（单播 DNS‑SD）

如果节点和 gateway 在不同的网络上，多播 mDNS 不会跨越 边界。你可以通过切换到 单播 DNS‑SD （"广域 Bonjour"）在 Tailscale 上保持相同的发现 UX。

高级步骤：

  1. 在 gateway 主机上运行 DNS 服务器（可通过 Tailnet 访问）。
  2. 为 _openclaw-gw._tcp 发布 DNS‑SD 记录到专用区域 （示例：openclaw.internal.）。
  3. 配置 Tailscale 拆分 DNS，以便你的客户端（包括 iOS）的 所选域名通过该 DNS 服务器解析。

OpenClaw 支持任何发现域；openclaw.internal. 只是一个示例。 iOS/Android 节点浏览 local. 和你配置的广域域。

Gateway 配置（推荐）

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

一次性 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 @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

Tailscale DNS 设置

在 Tailscale 管理控制台中：

  • 添加指向 gateway 的 tailnet IP 的名称服务器（UDP/TCP 53）。
  • 添加拆分 DNS，以便你的发现域使用该名称服务器。

一旦客户端接受 tailnet DNS，iOS 节点就可以在你的发现域中浏览 _openclaw-gw._tcp 而无需多播。

Gateway 监听器安全（推荐）

Gateway WS 端口（默认 18789）默认绑定到环回。对于 LAN/tailnet 访问，显式绑定并保持认证启用。

对于仅限 tailnet 的设置：

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

什么做广告

只有 Gateway 广告 _openclaw-gw._tcp。

服务类型

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

TXT 密钥（非机密提示）

Gateway 广告小的非机密提示，使 UI 流程方便：

  • role=gateway
  • displayName=<友好名称>
  • lanHost=<主机名>.local
  • gatewayPort=<端口>（Gateway WS + HTTP）
  • gatewayTls=1（仅在启用 TLS 时）
  • gatewayTlsSha256=<sha256>（仅在启用 TLS 且指纹可用时）
  • canvasPort=<端口>（仅在启用 canvas 主机时；当前与 gatewayPort 相同）
  • sshPort=<端口>（未覆盖时默认为 22）
  • transport=gateway
  • cliPath=<路径>（可选；可运行的 openclaw 入口点的绝对路径）
  • tailnetDns=<magicdns>（Tailnet 可用时的可选提示）

安全说明：

  • Bonjour/mDNS TXT 记录是 未认证的。客户端不得将 TXT 视为权威路由。
  • 客户端应使用解析的服务端点（SRV + A/AAAA）进行路由。仅将 lanHost、tailnetDns、gatewayPort 和 gatewayTlsSha256 视为提示。
  • TLS 固定绝不能允许广告的 gatewayTlsSha256 覆盖先前存储的固定。
  • iOS/Android 节点应将基于发现的直接连接视为 仅限 TLS，并在信任首次指纹之前需要明确的用户确认。

在 macOS 上调试

有用的内置工具：

  • 浏览实例：

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

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

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

如果浏览有效但解析失败，你通常遇到了 LAN 策略或 mDNS 解析器问题。

在 Gateway 日志中调试

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

  • bonjour: advertise failed ...
  • bonjour: ... name conflict resolved / hostname conflict resolved
  • bonjour: watchdog detected non-announced service ...

在 iOS 节点上调试

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

捕获日志：

  • 设置 → Gateway → 高级 → 发现调试日志
  • 设置 → Gateway → 高级 → 发现日志 → 重现 → 复制

日志包括浏览器状态转换和结果集更改。

常见故障模式

  • Bonjour 不跨越网络：使用 Tailnet 或 SSH。
  • 多播被阻止：一些 Wi-Fi 网络禁用 mDNS。
  • 睡眠/接口变化：macOS 可能暂时丢弃 mDNS 结果；重试。
  • 浏览有效但解析失败：保持机器名称简单（避免表情符号或 标点符号），然后重启 Gateway。服务实例名称源自 主机名，因此过于复杂的名称可能会混淆一些解析器。

转义的实例名称（\032）

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

  • 这在协议级别是正常的。
  • UI 应该解码以进行显示（iOS 使用 BonjourEscapes.decode）。

禁用/配置

  • OPENCLAW_DISABLE_BONJOUR=1 禁用广告（旧版：OPENCLAW_DISABLE_BONJOUR）。
  • ~/.openclaw/openclaw.json 中的 gateway.bind 控制 Gateway 绑定模式。
  • OPENCLAW_SSH_PORT 覆盖 TXT 中广告的 SSH 端口（旧版：OPENCLAW_SSH_PORT）。
  • OPENCLAW_TAILNET_DNS 在 TXT 中发布 MagicDNS 提示（旧版：OPENCLAW_TAILNET_DNS）。
  • OPENCLAW_CLI_PATH 覆盖广告的 CLI 路径（旧版：OPENCLAW_CLI_PATH）。

相关文档