openclaw 文档

简体中文

English

简体中文

English

Appearance

Bonjour / mDNS discovery ​

OpenClaw 使用 Bonjour（mDNS / DNS‑SD）作为一种 仅限局域网（LAN） 的便利手段，用于发现一个正在运行的 Gateway（WebSocket 端点）。它是 best‑effort，并 不能 替代基于 SSH 或 Tailnet 的连通性。

通过 Tailscale 在广域使用 Bonjour（Unicast DNS‑SD） ​

如果 node 与 gateway 不在同一网络，多播 mDNS 无法跨越网络边界。你可以通过在 Tailscale 上切换到 unicast DNS‑SD（“Wide‑Area Bonjour”）来保持相同的 discovery 体验。

高层步骤：

  1. 在 gateway host 上运行一个 DNS server（需可通过 Tailnet 访问）。
  2. 在一个专用 zone 下发布 _openclaw-gw._tcp 的 DNS‑SD 记录（例：openclaw.internal.）。
  3. 配置 Tailscale 的 split DNS，让你的 discovery 域在客户端（包括 iOS）上通过该 DNS server 解析。

OpenClaw 支持任意 discovery domain；openclaw.internal. 只是示例。 iOS/Android nodes 会同时浏览 local. 与你配置的 wide‑area domain。

Gateway 配置（推荐） ​

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

一次性的 DNS server 设置（gateway host） ​

bash
openclaw dns setup --apply

该命令会安装 CoreDNS 并配置它：

  • 只在 gateway 的 Tailscale 网卡上监听 53 端口
  • 从 ~/.openclaw/dns/<domain>.db 为你选择的域（例：openclaw.internal.）提供解析

在一台已连接 tailnet 的机器上验证：

bash
dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

Tailscale DNS 设置 ​

在 Tailscale 管理控制台中：

  • 添加一个 nameserver，指向 gateway 的 tailnet IP（UDP/TCP 53）。
  • 添加 split DNS，使你的 discovery domain 使用该 nameserver。

当客户端接受 tailnet DNS 后，iOS nodes 就可以在你的 discovery domain 中浏览 _openclaw-gw._tcp，无需多播。

Gateway listener 安全（推荐） ​

Gateway 的 WS 端口（默认 18789）默认绑定到 loopback。若要提供 LAN/tailnet 访问，请显式 bind，并保持 auth 开启。

对于仅 tailnet 的部署：

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

谁会广播 ​

只有 Gateway 会广播 _openclaw-gw._tcp。

Service types ​

  • _openclaw-gw._tcp — gateway transport beacon（由 macOS/iOS/Android nodes 使用）。

TXT keys（非敏感提示） ​

Gateway 会广播一些非敏感的小提示，以便 UI 流程更顺滑：

  • role=gateway
  • displayName=<friendly name>
  • lanHost=<hostname>.local
  • gatewayPort=<port>（Gateway WS + HTTP）
  • gatewayTls=1（仅当启用 TLS）
  • gatewayTlsSha256=<sha256>（仅当启用 TLS 且提供 fingerprint）
  • canvasPort=<port>（仅当启用 canvas host；默认 18793）
  • sshPort=<port>（未覆盖时默认 22）
  • transport=gateway
  • cliPath=<path>（可选；可运行 openclaw 入口的绝对路径）
  • tailnetDns=<magicdns>（可选；当 Tailnet 可用时的提示）

在 macOS 上排障 ​

一些有用的内置工具：

  • 浏览实例：
    bash
    dns-sd -B _openclaw-gw._tcp local.
  • 解析一个实例（替换 <instance>）：
    bash
    dns-sd -L "<instance>" _openclaw-gw._tcp local.

如果浏览能看到但解析失败，通常是 LAN 策略或 mDNS resolver 的问题。

在 Gateway 日志中排障 ​

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

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

在 iOS node 上排障 ​

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

采集日志：

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

日志包含 browser 状态流转与 result-set 变化。

常见故障模式 ​

  • Bonjour 无法跨网络：使用 Tailnet 或 SSH。
  • 多播被屏蔽：部分 Wi‑Fi 网络会禁用 mDNS。
  • 休眠 / 网卡抖动：macOS 可能短暂丢失 mDNS 结果；重试即可。
  • Browse 正常但 resolve 失败：保持机器名简单（避免 emoji 或标点），然后重启 Gateway。service instance name 来自主机名，过于复杂的名字会让一些 resolver 出问题。

转义的 instance 名（\032） ​

Bonjour/DNS‑SD 常常会把 service instance name 中的字节转义为十进制 \DDD 序列（例如空格会变成 \032）。

  • 这是协议层面的正常行为。
  • UI 应当解码后展示（iOS 使用 BonjourEscapes.decode）。

禁用 / 配置 ​

  • OPENCLAW_DISABLE_BONJOUR=1 禁用广播（legacy: OPENCLAW_DISABLE_BONJOUR）。
  • ~/.openclaw/openclaw.json 中的 gateway.bind 控制 Gateway bind 模式。
  • OPENCLAW_SSH_PORT 覆盖 TXT 中广播的 SSH 端口（legacy: OPENCLAW_SSH_PORT）。
  • OPENCLAW_TAILNET_DNS 在 TXT 中发布 MagicDNS 提示（legacy: OPENCLAW_TAILNET_DNS）。
  • OPENCLAW_CLI_PATH 覆盖广播的 CLI path（legacy: OPENCLAW_CLI_PATH）。

相关文档 ​