Bonjour / mDNS 发现

Moltbot 使用 Bonjour（mDNS / DNS-SD）作为仅 LAN 的便利发现活跃网关（WebSocket 端点）。这是尽力而为，不能替代 SSH 或基于 Tailnet 的连接。

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

若节点与网关在不同网络，组播 mDNS 无法跨边界。可通过在 Tailscale 上使用单播 DNS-SD（「广域 Bonjour」）保持相同的发现体验。概要步骤：

在网关主机上运行 DNS 服务器（经 Tailnet 可达）。
在专用区域（例如 moltbot.internal.）发布 _moltbot-gw._tcp 的 DNS-SD 记录。
配置 Tailscale split DNS，使 moltbot.internal 经该 DNS 服务器解析给客户端（含 iOS）。

Moltbot 在此模式下统一使用 moltbot.internal.。iOS/Android 节点会自动浏览 local. 与 moltbot.internal.。

网关配置（推荐）


{
  gateway: { bind: "tailnet" }, // 仅 Tailnet（推荐）
  discovery: { wideArea: { enabled: true } } // 启用 moltbot.internal DNS-SD 发布
}

一次性 DNS 服务器设置（网关主机）


moltbot dns setup --apply

会安装 CoreDNS 并配置为：

仅在网关的 Tailscale 接口上监听 53 端口
从 ~/.clawdbot/dns/moltbot.internal.db 提供 moltbot.internal.

在已接入 tailnet 的机器上验证：


dns-sd -B _moltbot-gw._tcp moltbot.internal.
dig @<TAILNET_IPV4> -p 53 _moltbot-gw._tcp.clawdbot.internal PTR +short

Tailscale DNS 设置

在 Tailscale 管理控制台：

添加指向网关 tailnet IP 的 nameserver（UDP/TCP 53）。
添加 split DNS，使域名 moltbot.internal 使用该 nameserver。

客户端接受 tailnet DNS 后，iOS 节点即可在 moltbot.internal. 中浏览 _moltbot-gw._tcp，无需组播。

网关监听安全（推荐）

网关 WS 端口（默认 18789）默认绑定 loopback。要经 LAN/tailnet 访问，需显式绑定并保持认证启用。仅 Tailnet 时：

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

谁在发布

只有网关会发布 _moltbot-gw._tcp。

服务类型

_moltbot-gw._tcp — 网关传输信标（供 macOS/iOS/Android 节点使用）。

TXT 键（非密提示）

网关发布少量非密提示以方便 UI 流程：

role=gateway
displayName=<友好名称>
lanHost=<hostname>.local
gatewayPort=<port>（网关 WS + HTTP）
gatewayTls=1（仅当启用 TLS 时）
gatewayTlsSha256=<sha256>（仅当启用 TLS 且可获取指纹时）
canvasPort=<port>（仅当启用 canvas host 时；默认 18793）
sshPort=<port>（未覆盖时默认 22）
transport=gateway
cliPath=<path>（可选；可执行 moltbot 入口的绝对路径）
tailnetDns=<magicdns>（Tailnet 可用时的可选提示）

在 macOS 上调试

可用内置工具：

浏览实例：


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

解析单个实例（将 <instance> 替换为实际实例名）：


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

若浏览正常但解析失败，通常是 LAN 策略或 mDNS 解析器问题。

在网关日志中调试

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

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

在 iOS 节点上调试

iOS 节点使用 NWBrowser 发现 _moltbot-gw._tcp。抓取日志：

设置 → 网关 → 高级 → Discovery Debug Logs
设置 → 网关 → 高级 → Discovery Logs → 复现问题 → Copy

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

常见失败情况

Bonjour 不跨网络：使用 Tailnet 或 SSH。
组播被阻断：部分 Wi‑Fi 会禁用 mDNS。
休眠 / 接口变化：macOS 可能暂时丢掉 mDNS 结果；重试即可。
浏览成功但解析失败：保持机器名简单（避免 emoji 或标点），然后重启网关。服务实例名来自主机名，过于复杂的名称可能导致部分解析器异常。

转义实例名（`\032`）

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

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

禁用与配置

CLAWDBOT_DISABLE_BONJOUR=1 关闭发布。
~/.clawdbot/moltbot.json 中的 gateway.bind 控制网关绑定模式。
CLAWDBOT_SSH_PORT 覆盖 TXT 中发布的 SSH 端口。
CLAWDBOT_TAILNET_DNS 在 TXT 中发布 MagicDNS 提示。
CLAWDBOT_CLI_PATH 覆盖发布的 CLI 路径。