6.28 发现与传输

Gateway 发现机制使客户端能够自动定位并连接到 Gateway,支持局域网和跨网络场景。

概述

OpenClaw 支持三种 Gateway 发现机制:

• Bonjour/mDNS - 局域网自动发现
• Tailnet - 跨网络安全连接
• 手动/SSH - 后备连接方式

Bonjour/mDNS 发现

Gateway 通过 Bonjour 在局域网内广播其 WebSocket 端点。

服务类型

Gateway 使用服务类型 _openclaw-gw._tcp 进行广播。

TXT 记录

Bonjour 广播包含以下 TXT 键值对:

• role=gateway - 标识为 Gateway 服务
• lanHost=.local - 本地主机名
• sshPort=22 - SSH 端口(如果可用)
• gatewayPort=18789 - Gateway WebSocket 端口

配置示例

{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "discovery": {
      "bonjour": {
        "enabled": true,
        "name": "OpenClaw Gateway"  // 可选,自定义服务名称
      }
    }
  }
}

Tailnet 发现

通过 Tailscale 实现跨网络的安全连接,无需公网 IP 或端口转发。

MagicDNS

Tailnet 使用 MagicDNS 或稳定 IP 进行寻址。Gateway 检测到 Tailscale 时会自动发布 tailnetDns 提示。

配置示例

{
  "gateway": {
    "mode": "local",
    "tailscale": {
      "mode": "serve",  // 仅 Tailnet 内访问
      "hostname": "my-gateway"  // 可选,指定主机名
    }
  }
}

Funnel 模式

Funnel 模式允许公网访问(需谨慎使用):

{
  "gateway": {
    "tailscale": {
      "mode": "funnel"  // 开放公网访问
    },
    "auth": {
      "token": "强密码-token"  // 必须配置认证
    }
  }
}

手动/SSH 连接

作为后备方案,客户端可以通过 SSH 端口转发连接 Gateway。

SSH 隧道

建立 SSH 隧道转发 Gateway 端口:

# 本地端口转发
ssh -L 18789:localhost:18789 user@gateway-host

# 后台运行
ssh -fN -L 18789:localhost:18789 user@gateway-host

客户端配置

# 通过 SSH 隧道连接
openclaw connect --gateway localhost:18789

# 或设置环境变量
export OPENCLAW_GATEWAY_URL=ws://localhost:18789
openclaw tui

连接优先级

客户端按以下优先级尝试连接:

1. 直接端点 - 配置文件中明确指定的地址
2. Bonjour - 局域网自动发现
3. Tailnet - Tailscale 网络
4. SSH - SSH 隧道转发

测试发现

查看广播状态

# 查看 Bonjour 服务
dns-sd -B _openclaw-gw._tcp

# 解析服务详情
dns-sd -L "OpenClaw Gateway" _openclaw-gw._tcp

# 在 Linux 上使用 avahi
avahi-browse -a

测试 Tailscale 连接

# 检查 Tailscale 状态
tailscale status

# 测试连接
curl http://gateway-name.tailnet.ts.net:18789/health

# Gateway RPC 查询
openclaw gateway call tailscale.status

故障排查

Bonjour 无法发现

• 确认防火墙允许 mDNS (UDP 5353)
• 检查是否在同一局域网
• 某些企业网络可能阻止 mDNS

Tailscale 连接失败

• 确认两端都已加入同一 Tailnet
• 检查 MagicDNS 是否启用
• 验证防火墙规则

配置示例

完整发现配置

{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "discovery": {
      "bonjour": {
        "enabled": true,
        "name": "My Gateway"
      }
    },
    "tailscale": {
      "mode": "serve",
      "hostname": "my-gateway"
    },
    "auth": {
      "token": "secure-token-here"
    }
  }
}