发现与传输

客户端需要先"发现"Gateway 的地址和端口，才能建立连接。OpenClaw 支持多种发现（Discovery）和传输（Transport）机制。

发现机制概览

方式	适用场景	自动化程度
Bonjour / mDNS	局域网内自动发现	⭐⭐⭐ 全自动
手动配置	已知地址直连	⭐ 手动
Tailscale	VPN 隧道跨网络	⭐⭐ 半自动
远程网关	公网部署	⭐ 手动

Bonjour / mDNS 自动发现

Gateway 启动后会通过 Bonjour（也称 mDNS，多播域名系统）在局域网内广播自身存在。

┌──────────┐      mDNS Query       ┌──────────┐
│  Client  │ ───────────────────▶  │  Gateway  │
│          │ ◀───────────────────  │          │
│          │      mDNS Response    │          │
│          │      _openclaw._tcp   │          │
│          │      192.168.1.10     │          │
│          │      port: 18789      │          │
└──────────┘                       └──────────┘

同一局域网内的客户端会自动发现并连接 Gateway，无需任何手动配置。

零配置

在家庭或办公室网络中，Bonjour 发现通常开箱即用。客户端启动时会自动扫描局域网内的 Gateway 实例。

配置 Bonjour

{
  "gateway": {
    "discovery": {
      "bonjour": {
        "enabled": true,              // 默认启用
        "serviceName": "OpenClaw",     // 广播的服务名称
        "serviceType": "_openclaw._tcp"
      }
    }
  }
}

禁用 Bonjour

某些安全敏感环境可能需要禁用自动发现：

openclaw config set gateway.discovery.bonjour.enabled false

企业网络

某些企业网络可能会过滤 mDNS 流量。如果自动发现不工作，请联系网络管理员或使用手动连接。

手动连接

直接指定 Gateway 地址和端口：

# CLI 手动连接
openclaw connect --host 192.168.1.10 --port 18789

# 保存连接配置
openclaw connect --host 192.168.1.10 --port 18789 --save

保存后的连接信息存储在客户端配置中：

{
  "connections": [
    {
      "name": "home-gateway",
      "host": "192.168.1.10",
      "port": 18789,
      "token": "${GATEWAY_TOKEN}"
    }
  ]
}

传输协议

Gateway 使用以下传输协议（Transport Protocol）：

WebSocket（主要）

所有实时通信通过 WebSocket 进行：

ws://127.0.0.1:18789/ws    (本地)
wss://gateway.example.com/ws (远程，TLS 加密)

• 双向实时通信
• 支持流式（Streaming）响应
• 自动重连机制

HTTP（补充）

REST API 通过 HTTP 提供：

http://127.0.0.1:18789/v1/chat/completions   (本地)
https://gateway.example.com/v1/chat/completions (远程)

• OpenAI 兼容接口
• 适合一次性请求
• 支持标准 HTTP 客户端

协议选择

交互式会话推荐 WebSocket，单次 API 调用推荐 HTTP。两者共享同一端口。

发现优先级

当多种发现方式同时可用时，客户端按以下优先级连接：

1. 手动保存的连接（最高优先）
2. Tailscale 网络内的 Gateway
3. Bonjour 局域网发现
4. 默认 localhost:18789

多 Gateway 发现

如果局域网内存在多个 Gateway 实例，客户端会列出所有发现的实例供用户选择：

Discovered Gateways:
  1. home-office (192.168.1.10:18789) - 2 channels
  2. dev-server  (192.168.1.20:18789) - 5 channels

Select gateway [1]:

相关文档

• Bonjour 发现 — mDNS 详细配置
• Tailscale — VPN 隧道接入
• 远程访问 — 外部连接配置
• 网关协议 — WebSocket 通信规范