OpenClaw 设备发现机制指南：Bonjour/mDNS 与 Tailscale 集成

在分布式 AI 网关架构中，如何让用户在局域网或虚拟网络中零配置地发现可用网关，是提升用户体验的关键。OpenClaw 采用 Bonjour (mDNS/DNS-SD) 作为核心发现协议，并深度集成 Tailscale 以实现跨网络的广域发现。

核心设计原则

• 便利性优先：自动发现减少手动 IP 配置。
• 安全不妥协：发现信息仅用于 UI 提示，绝不作为权威路由或信任依据。
• 尽力而为 (Best Effort)：mDNS 受网络环境影响大，始终提供手动连接/Tailnet 作为备用方案。
• 无状态发现：TXT 记录不包含敏感认证信息。

1. 核心机制：服务广播与 TXT 记录

OpenClaw 网关通过 _openclaw-gw._tcp 服务类型进行广播。客户端通过解析 SRV 记录 获取连接端点，通过 TXT 记录 获取辅助提示信息。

TXT 记录详解

image

关键安全警示

1. TXT 记录不可信：mDNS/TXT 记录未经过加密或签名，极易被中间人伪造。
   • 正确做法：客户端必须使用 DNS-SD 解析出的 SRV + A/AAAA 记录 进行实际连接。
   • 错误做法：直接信任 lanHost 或 gatewayPort 进行路由。
2. TLS 指纹固定 (Pinning)：
   • 广告的 gatewayTlsSha256 绝不能 自动覆盖客户端已存储的信任指纹。
   • iOS/Android 客户端在首次连接基于发现的网关时，必须强制用户手动确认证书指纹。

2. 配置实战：从最小化到全功能

在 openclaw.json 中控制发现行为。

模式一：最小化暴露 (推荐生产环境)

仅广播必要信息，隐藏 SSH/CLI 路径等细节。

{
  discovery: {
    mdns: { mode: "minimal" } 
  }
}

模式二：完全功能 (家庭/开发环境)

广播所有辅助信息，方便多设备无缝连接。

{
  discovery: {
    mdns: { mode: "full" },
    wideArea: { enabled: true } // 启用广域 DNS-SD
  },
  gateway: {
    bind: "tailnet" // 推荐：仅监听 Tailscale 接口
  }
}

模式三：完全禁用

适用于纯公网反向代理或高安全隔离环境。

{
  discovery: {
    mdns: { mode: "off" }
  }
}

环境变量覆盖

无需修改配置文件，临时调整行为：

• OPENCLAW_DISABLE_BONJOUR=1: 强制禁用广播。
• OPENCLAW_SSH_PORT: 覆盖广告的 SSH 端口。
• OPENCLAW_TAILNET_DNS: 强制发布 MagicDNS 提示。

3. 广域发现：跨越网络边界 (Wide-Area Bonjour)

标准 mDNS 无法跨越路由器。OpenClaw 通过 单播 DNS-SD (Unicast DNS-SD) 结合 Tailscale Split-DNS 实现跨网络发现。

架构原理

1. 网关侧：运行内置/CoreDNS 服务器，监听 Tailscale 接口 (UDP/TCP 53)。
2. 记录发布：在专用域 (如 openclaw.internal) 下发布 _openclaw-gw._tcp 记录。
3. 客户端侧：配置 Tailscale Split-DNS，将该域解析请求转发至网关 DNS。

 一键部署

在网关主机执行：

openclaw dns setup --apply

自动安装 CoreDNS，配置监听，并生成区域文件 ~/.openclaw/dns/<domain>.db。

验证步骤

在任意 Tailscale 节点验证：

# 1. 浏览服务 (macOS/Linux)
dns-sd -B _openclaw-gw._tcp openclaw.internal.

# 2. 直接 DNS 查询
dig @<GATEWAY_TAILNET_IP> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

Tailscale 控制台配置

1. Nameservers: 添加网关的 Tailnet IP (端口 53)。
2. Split DNS: 添加规则 openclaw.internal -> 指向上述 Nameserver。 配置生效后，iOS/Android 即可在无多播环境下自动发现网关。

4. 故障排查指南

常用调试命令

image

常见问题矩阵

image

iOS 节点调试

1. 进入 设置 → 网关 → 高级。
2. 开启 Discovery Debug Logs。
3. 复现问题后，点击 Copy Logs 分析浏览器状态机。

5. 典型部署场景

场景 A：家庭多设备 (LAN)

目标：手机、平板、电脑自动发现。

{
  discovery: { mdns: { mode: "full" } },
  gateway: { bind: "lan", auth: { mode: "token" } }
}

场景 B：企业团队共享 (Tailnet)

目标：分布在不同地点的团队成员安全访问。

{
  discovery: { 
    mdns: { mode: "minimal" }, 
    wideArea: { enabled: true } 
  },
  gateway: { 
    bind: "tailnet", 
    auth: { mode: "password" } 
  }
}

场景 C：远程 VPS (公网代理)

目标：通过域名访问，无需内部发现。

{
  discovery: { mdns: { mode: "off" } },
  gateway: { 
    bind: "loopback", 
    remote: { url: "wss://api.example.com" } 
  }
}

6. 安全加固最佳实践

Do's (推荐)

1. 优先 Tailnet 绑定：bind: "tailnet" 可天然隔离公网扫描。
2. 最小化信息：生产环境使用 mode: "minimal"，避免泄露 CLI 路径或 SSH 端口。
3. 强制 TLS 验证：客户端必须校验证书指纹，严禁静默信任广播指纹。
4. 简化主机名：使用 hostname.local 格式，避免 Emoji 或特殊符号。

Don'ts (避免)

1. 依赖发现作为唯一入口：始终保留手动 IP/域名连接方式。
2. 在公网接口广播 mDNS：切勿在 0.0.0.0 或非受信 LAN 开启 mode: "full"。
3. 自动更新信任锚：绝不允许广播的 SHA256 覆盖本地已固定的证书指纹。

结语

OpenClaw 的发现机制在极致便利与严格安全之间取得了平衡。

• 在局域网内，它利用成熟的 Bonjour 协议实现“零配置”体验。
• 在广域网中，它借助 Tailscale 的单播 DNS-SD 打破网络边界。

记住：发现只是引路人，连接必须验明正身。 合理配置 mdns.mode 并结合 Tailscale 的安全隧道，你将拥有一个既易用又坚固的 AI 网关网络。