6.4 Gateway配对 - OpenClaw中文社区

OpenClaw 节点通过 Gateway 发现和配对机制自动连接到 Gateway 服务。系统支持多种发现方式,可在局域网和跨网络环境中工作。

概述

Gateway 配对是节点(Node)与 Gateway 建立连接的过程。OpenClaw 使用多层发现机制确保节点能够找到并连接到可用的 Gateway,即使在复杂的网络环境中也能正常工作。

发现机制

OpenClaw 按以下优先级顺序尝试多种发现方法:

1. 直接 WebSocket 连接

如果节点可以直接访问 Gateway,会优先使用直接 WebSocket 连接。这是最快速和高效的连接方式。

# 直接连接到本地 Gateway
ws://localhost:18789

# 直接连接到指定 IP
ws://192.168.1.100:18789

2. Bonjour/mDNS 发现 (局域网)

在局域网环境中,Gateway 通过 Bonjour (mDNS) 协议广播其存在。节点自动发现本地网络中的 Gateway。

Bonjour 服务

Gateway 通过 _openclaw-gw._tcp 服务类型广播,包含以下 TXT 记录:

role=gateway - 标识服务角色
lanHost=*.local - 本地主机名
gatewayPort=18789 - Gateway 端口

3. Tailnet DNS/IP (跨网络)

当使用 Tailscale 时,节点可以通过 Tailnet DNS 或 IP 地址发现和连接 Gateway,实现跨网络访问。

# 通过 Tailscale 配置跨网络访问
{
  "gateway": {
    "tailscale": {
      "mode": "serve"  // 或 "funnel" 用于公共访问
    }
  }
}

4. SSH 隧道备用方案

如果上述方法都不可用,可以使用 SSH 隧道作为备用连接方式。

# 建立 SSH 隧道到远程 Gateway
ssh -L 18789:localhost:18789 user@remote-host

# 然后节点连接到本地端口
# Gateway 配置保持 localhost 绑定

配置示例

自动发现配置

默认情况下,节点会自动尝试所有可用的发现方法:

{
  "gateway": {
    "port": 18789,
    "bind": "loopback"  // 默认仅监听 127.0.0.1
  }
}

指定 Gateway 地址

可以显式指定 Gateway 地址,跳过自动发现:

{
  "gateway": {
    "url": "ws://192.168.1.100:18789"
  }
}

Tailnet 配置

{
  "gateway": {
    "tailscale": {
      "mode": "serve",
      "bind": "tailnet"
    }
  }
}

连接流程

节点启动: 节点进程启动并开始 Gateway 发现
尝试发现: 按优先级尝试各种发现方法
建立连接: 找到 Gateway 后建立 WebSocket 连接
认证: 通过 token 或 password 进行身份验证
注册: 节点向 Gateway 注册并开始接收任务

安全考虑

安全最佳实践

保持 loopback 绑定: 默认 Gateway 仅监听 127.0.0.1,这是最安全的配置
使用认证: 始终配置 gateway.auth.token 或 gateway.auth.password
远程访问: 优先使用 SSH 隧道或 Tailscale,避免直接暴露 Gateway 端口
网络隔离: 在生产环境中,将 Gateway 部署在安全的网络区域

故障排查

节点无法找到 Gateway

# 检查 Gateway 是否运行
openclaw status

# 查看 Gateway 监听端口
lsof -i :18789  # Linux/macOS
netstat -an | grep 18789  # Windows

# 测试网络连通性
curl http://localhost:18789
nc -zv localhost 18789

Bonjour 发现失败

检查防火墙是否允许 mDNS (端口 5353 UDP)
确认 Bonjour/Avahi 服务正在运行
验证节点和 Gateway 在同一局域网

认证失败

# 检查配置的认证信息
openclaw config show | grep auth

# 验证节点使用的认证信息与 Gateway 配置匹配

常用命令

# 启动 Gateway
openclaw gateway

# 查看 Gateway 状态
openclaw status

# 查看连接的节点
openclaw gateway list-nodes

# 测试 Gateway 连接
openclaw gateway ping

# 查看发现日志
openclaw --debug gateway

高级配置

多 Gateway 环境

在多 Gateway 部署中,节点会连接到第一个可访问的 Gateway:

{
  "gateway": {
    "discovery": {
      "urls": [
        "ws://gateway1.local:18789",
        "ws://gateway2.local:18789"
      ]
    }
  }
}

自定义发现顺序

{
  "gateway": {
    "discovery": {
      "methods": ["direct", "bonjour", "tailscale", "ssh"],
      "timeout": 5000  // 每种方法的超时时间(毫秒)
    }
  }
}

概述