6.29 Bonjour发现

OpenClaw 使用 Bonjour（mDNS/DNS-SD）协议在局域网内实现网关的自动发现。本文档介绍 Bonjour 服务发现的工作原理、配置方法和调试技巧。

什么是 Bonjour

Bonjour 是 Apple 开发的零配置网络服务发现协议，基于多播 DNS（mDNS）和基于 DNS 的服务发现（DNS-SD）。OpenClaw 使用 Bonjour 让客户端能够自动发现局域网内的网关，无需手动配置 IP 地址。

服务类型

OpenClaw 网关通过以下服务类型进行广播：

_openclaw-gw._tcp

TXT 记录字段

网关在 Bonjour 广播中包含以下 TXT 记录信息：

字段名	说明	示例
role	角色标识	gateway
displayName	显示名称	My Gateway
lanHost	局域网主机名	gateway.local
gatewayPort	网关端口	3000
gatewayTls	是否启用 TLS	1
canvasPort	Canvas 端口	3001
sshPort	SSH 端口	22
transport	传输方式	gateway
cliPath	CLI 路径	/usr/local/bin/openclaw
tailnetDns	Tailscale DNS	gateway.tailnet-name.ts.net

网络范围限制

广域网支持

对于跨网络场景，OpenClaw 支持通过 Tailscale 进行单播 DNS-SD 服务发现：

• 使用 Tailscale 的 DNS 服务
• 支持跨 Tailnet 的服务发现
• 无需配置端口转发或 VPN

调试方法

使用 dns-sd 命令

在 macOS 或 Linux 上，可以使用 dns-sd 命令浏览 Bonjour 服务：

# 浏览 OpenClaw 网关服务
dns-sd -B _openclaw-gw._tcp

# 解析特定服务实例
dns-sd -L "My Gateway" _openclaw-gw._tcp

查看网关日志

检查网关日志中的 Bonjour 相关信息：

# 查看包含 bonjour 的日志行
openclaw logs | grep "bonjour:"

iOS 发现调试日志

在 iOS 客户端上启用发现调试日志：

1. 打开 OpenClaw iOS 应用
2. 进入设置
3. 启用"Discovery Debug Logs"
4. 查看发现过程的详细日志

配置选项

禁用 Bonjour

如果不需要局域网自动发现，可以禁用 Bonjour：

# 设置环境变量
export OPENCLAW_DISABLE_BONJOUR=1

# 启动网关
openclaw gateway start

自定义显示名称

在配置文件中设置网关的显示名称：

{
  "gateway": {
    "displayName": "开发环境网关",
    "bonjour": {
      "enabled": true
    }
  }
}

常见问题

客户端无法发现网关

可能的原因和解决方法：

• 防火墙阻止：确保防火墙允许 UDP 5353 端口（mDNS）
• 不在同一网络：确认客户端和网关在同一局域网内
• Bonjour 被禁用：检查 OPENCLAW_DISABLE_BONJOUR 环境变量
• 服务未启动：确认网关服务正在运行

多个网关冲突

当局域网内有多个网关时：

• 每个网关使用不同的显示名称
• 客户端会列出所有发现的网关
• 用户可以选择要连接的网关

安全考虑

与其他发现机制的对比

发现方式	适用场景	优点	缺点
Bonjour	局域网	零配置、自动发现	仅限局域网
Tailscale DNS-SD	跨网络	安全、可跨网络	需要 Tailscale
手动配置	所有场景	完全控制	需要手动维护

完整示例

在局域网内启用 Bonjour 发现：

# 1. 确保 Bonjour 未被禁用
unset OPENCLAW_DISABLE_BONJOUR

# 2. 配置网关（config.json）
{
  "gateway": {
    "displayName": "我的 OpenClaw 网关",
    "port": 3000,
    "bonjour": {
      "enabled": true
    }
  }
}

# 3. 启动网关
openclaw gateway start

# 4. 在另一台设备上浏览服务
dns-sd -B _openclaw-gw._tcp

# 5. 解析特定网关
dns-sd -L "我的 OpenClaw 网关" _openclaw-gw._tcp