Bonjour / mDNS 发现

OpenClaw 使用 Bonjour（mDNS / DNS‑SD）作�?*仅局域网**的便捷方式，用于发现 活动�?Gateway（WebSocket 端点）。这是尽力而为的服务，不能替代 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（推荐）
  discovery: { wideArea: { enabled: true } }, // 启用广域 DNS-SD 发布
}

一次�?DNS 服务器设置（Gateway 主机�?

openclaw dns setup --apply

这会安装 CoreDNS 并配置它�?

  • 仅在 Gateway �?Tailscale 接口上监听端�?53
  • �?~/.openclaw/dns/<domain>.db 提供您选择的域

�?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=<端口>（仅在画布主机启用时；当前与 gatewayPort 相同�?
  • sshPort=<端口>（默�?22 未覆盖时�?
  • transport=gateway
  • cliPath=<路径>（可选；可运�?openclaw 入口点的绝对路径�?
  • tailnetDns=<magicdns>（Tailnet 可用时的可选提示）

安全说明�?

  • Bonjour/mDNS TXT 记录�?未经身份验证�?。客户端不能�?TXT 作为权威路由�?
  • 客户端应使用解析的服务端点（SRV + A/AAAA）进行路由。将 lanHost、tailnetDns、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）�?

相关文档