Bonjour 发现
Bonjour（也称 mDNS / DNS-SD，即多播域名系统 / DNS 服务发现）是一种零配置网络协议，允许局域网内的设备自动发现 Gateway 实例。
工作原理
text
┌─────────────────────────────────────────────┐
│ 局域网 (LAN) │
│ │
│ ┌──────────┐ mDNS 广播 │
│ │ Gateway │ ──────────────────────────▶ │
│ │ :18789 │ _openclaw._tcp.local │
│ └──────────┘ TXT: version=1.0 │
│ │
│ ┌──────────┐ mDNS 查询 │
│ │ Client │ ◀────────────────────────── │
│ │ │ 发现 Gateway │
│ │ │ 192.168.1.10:18789 │
│ └──────────┘ │
│ │
│ ┌──────────┐ 自动连接 │
│ │ Client 2 │ ◀────────────────────────── │
│ └──────────┘ │
└─────────────────────────────────────────────┘mDNS 协议流程
- 广播：Gateway 启动时通过 mDNS 广播服务信息
- 查询：客户端发送 mDNS 查询（Query），搜索
_openclaw._tcp.local - 响应：Gateway 回复自身的 IP 地址、端口和元数据
- 连接：客户端使用发现的信息自动连接
默认行为
Bonjour 发现默认启用。Gateway 启动时会自动注册以下 mDNS 服务：
text
服务类型: _openclaw._tcp.local
端口: 18789
TXT 记录:
version=1.0
name=<gateway-name>
channels=<channel-count>开箱即用
大多数情况下，Bonjour 发现无需任何配置。同一局域网内的客户端会自动发现 Gateway。
配置
查看当前配置
bash
openclaw config get gateway.discovery.bonjour完整配置项
json5
{
"gateway": {
"discovery": {
"bonjour": {
"enabled": true, // 启用/禁用 Bonjour
"serviceName": "OpenClaw Gateway", // 广播的服务名称
"serviceType": "_openclaw._tcp", // mDNS 服务类型
"txtRecords": { // 自定义 TXT 记录
"description": "My Gateway"
}
}
}
}
}自定义服务名称
当局域网内有多个 Gateway 时，自定义名称可帮助客户端区分：
bash
openclaw config set gateway.discovery.bonjour.serviceName "Office Gateway"禁用 Bonjour
在安全敏感环境中，可能需要禁用自动发现：
bash
openclaw config set gateway.discovery.bonjour.enabled false何时禁用
如果你的 Gateway 不应被局域网内其他设备发现（例如公共网络环境），请禁用 Bonjour。
平台兼容性
| 平台 | mDNS 支持 | 备注 |
|---|---|---|
| macOS | ✅ 原生支持 | Bonjour 由 Apple 创建，macOS 内置支持 |
| Windows | ✅ 需安装 | 安装 iTunes 或 Bonjour Print Services |
| Linux | ✅ 需安装 | 安装 avahi-daemon |
| iOS | ✅ 原生支持 | — |
| Android | ⚠️ 部分支持 | NSD (Network Service Discovery) |
bash
# Ubuntu/Debian
sudo apt install avahi-daemon avahi-utils
# 启动服务
sudo systemctl enable avahi-daemon
sudo systemctl start avahi-daemonbash
# 方式 1：安装 Bonjour Print Services
# 下载：https://support.apple.com/kb/DL999
# 方式 2：使用 chocolatey
choco install bonjour诊断与调试
查看 mDNS 广播
bash
dns-sd -B _openclaw._tcp localbash
avahi-browse -r _openclaw._tcp输出示例：
text
+ eth0 IPv4 OpenClaw Gateway _openclaw._tcp local
= eth0 IPv4 OpenClaw Gateway _openclaw._tcp local
hostname = [my-server.local]
address = [192.168.1.10]
port = [18789]
txt = ["version=1.0" "channels=3"]常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 发现不到 Gateway | mDNS 流量被防火墙过滤 | 允许 UDP 5353 端口 |
| 发现不到 Gateway | 设备不在同一子网 | 确保在同一局域网段 |
| 多个 Gateway 同名 | 未自定义服务名称 | 设置不同的 serviceName |
| Windows 无法发现 | 未安装 Bonjour 服务 | 安装 Bonjour Print Services |
bash
# 检查防火墙是否允许 mDNS
sudo ufw allow 5353/udp