OpenClaw 实现原理详解（六）：WebSocket Gateway 详解

6.1 Gateway 的角色：消息中枢

WebSocket Gateway 是 OpenClaw 的消息中枢，负责：

• 维护平台连接：管理 WhatsApp、T@elegrimm、Discord 等渠道的长连接
• 客户端通信：为 UI 客户端、CLI、远程节点提供 WebSocket API
• 会话管理：维护多渠道、多用户的会话状态
• 认证授权：验证客户端身份，控制访问权限

┌─────────────────────────────────────────────────────────────┐
│                      WebSocket Gateway                       │
│                                                             │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐         │
│  │WhatsApp │  │T@elegrimm │  │Discord  │  │  微信   │  ...    │
│  │ Provider│  │ Provider│  │ Provider│  │ Provider│         │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘         │
│       │            │            │            │              │
│       └────────────┴─────┬──────┴────────────┘              │
│                          │                                   │
│                    ┌─────▼─────┐                             │
│                    │  Router   │  消息路由                   │
│                    └─────┬─────┘                             │
│                          │                                   │
│       ┌──────────────────┼──────────────────┐               │
│       │                  │                  │               │
│  ┌────▼────┐       ┌─────▼─────┐      ┌─────▼─────┐         │
│  │   CLI   │       │ WebChat   │      │ macOS App │  ...    │
│  └─────────┘       └───────────┘      └───────────┘         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

6.2 协议设计

消息帧格式

所有 WebSocket 通信使用 JSON 格式，分为三种帧类型：

// 请求帧
interface Request {
  type: "req";
  id: string;        // 唯一标识，用于匹配响应
  method: string;    // 方法名
  params: object;    // 参数
}

// 响应帧
interface Response {
  type: "res";
  id: string;        // 对应请求的 id
  ok: boolean;       // 是否成功
  payload?: object;  // 成功时的数据
  error?: string;    // 失败时的错误信息
}

// 事件帧
interface Event {
  type: "event";
  event: string;     // 事件名
  payload: object;   // 事件数据
  seq?: number;      // 序列号（可选）
}

示例交互

Client                          Gateway
  │                                │
  │──── req:connect ──────────────>│  首帧必须是 connect
  │<──── res (ok) ─────────────────│  或 res error + close
  │                                │
  │<──── event:tick ───────────────│  心跳
  │<──── event:presence ───────────│  状态同步
  │                                │
  │──── req:agent ────────────────>│  发起 AI 请求
  │<──── res:agent ────────────────│  确认接受
  │<──── event:agent ──────────────│  流式输出
  │<──── res:agent ────────────────│  完成
  │                                │

6.3 连接生命周期

1. 连接建立

客户端连接 Gateway 时，首帧必须是 connect 请求：

{
  "type": "req",
  "id": "conn_001",
  "method": "connect",
  "params": {
    "token": "your-gateway-token",
    "clientId": "my-client",
    "version": "1.0.0"
  }
}

2. 认证

Gateway 验证 token：

// 成功
{
  "type": "res",
  "id": "conn_001",
  "ok": true,
  "payload": {
    "serverVersion": "1.2.3",
    "agents": ["main"]
  }
}

// 失败
{
  "type": "res",
  "id": "conn_001",
  "ok": false,
  "error": "Invalid token"
}

3. 心跳

Gateway 定期发送 tick 事件：

{
  "type": "event",
  "event": "tick",
  "payload": {
    "ts": 1704067200000
  }
}

4. 断开连接

客户端或服务器可以随时关闭连接。Gateway 会：

• 清理会话状态
• 通知其他客户端（如果需要）
• 释放资源

6.4 认证与授权

Token 认证

Gateway 使用 token 进行认证：

{
  gateway: {
    token: "your-secret-token",  // 或从环境变量读取
  }
}

# 环境变量
OPENCLAW_GATEWAY_TOKEN=your-secret-token

设备配对

远程节点需要先配对：

# 生成配对码
openclaw pair generate

# 输出
Pairing code: ABCD-EFGH
Expires in: 5 minutes

客户端使用配对码连接：

{
  "type": "req",
  "method": "connect",
  "params": {
    "pairCode": "ABCD-EFGH"
  }
}

6.5 常用 RPC 方法

agent

调用 Agent 进行推理：

{
  "type": "req",
  "id": "agent_001",
  "method": "agent",
  "params": {
    "sessionKey": "agent:main:main",
    "message": "帮我整理文件",
    "model": "claude-3-5-sonnet"
  }
}

send

发送消息到渠道：

{
  "type": "req",
  "id": "send_001",
  "method": "send",
  "params": {
    "channel": "telegram",
    "target": "123456789",
    "message": {
      "text": "你好！"
    }
  }
}

health

健康检查：

{
  "type": "req",
  "id": "health_001",
  "method": "health",
  "params": {}
}

status

获取状态：

{
  "type": "req",
  "id": "status_001",
  "method": "status",
  "params": {}
}

6.6 常用事件

tick

心跳事件，定期发送。

agent

Agent 状态变更：

{
  "type": "event",
  "event": "agent",
  "payload": {
    "stream": "assistant",
    "delta": "你好！有什么可以帮你的？"
  }
}

presence

用户在线状态变更：

{
  "type": "event",
  "event": "presence",
  "payload": {
    "channel": "whatsapp",
    "userId": "123456789",
    "status": "online"
  }
}

ch@t

收到新消息：

{
  "type": "event",
  "event": "ch@t",
  "payload": {
    "channel": "telegram",
    "sender": {
      "id": "123456789",
      "name": "Alice"
    },
    "message": {
      "text": "你好"
    }
  }
}

shutdown

Gateway 即将关闭：

{
  "type": "event",
  "event": "shutdown",
  "payload": {
    "reason": "maintenance",
    "gracePeriodMs": 30000
  }
}

6.7 连接管理

多客户端

Gateway 支持多个客户端同时连接：

┌─────────────┐
│   Gateway   │
└──────┬──────┘
       │
  ┌────┼────┬────────┐
  │    │    │        │
  ▼    ▼    ▼        ▼
CLI  Web  macOS   iOS App

竞争处理

当多个客户端同时操作同一会话时：

1. 请求排队：请求按到达顺序处理
2. 状态同步：变更通过事件广播给所有客户端
3. 乐观锁：某些操作使用版本号防止冲突

6.8 Gateway 配置

基本配置

{
  gateway: {
    // 地址
    bind: "loopback",  // 只本地
    // bind: "0.0.0.0",  // 所有接口
    
    port: 19000,
    
    // 认证
    token: "your-token",
    
    // 远程访问
    remote: {
      enabled: true,
      url: "https://your-gateway.example.com"
    },
    
    // Tailscale
    tailscale: {
      enabled: true,
      hostname: "openclaw-gateway"
    }
  }
}

安全配置

{
  gateway: {
    // 只允许可信来源
    cors: {
      origins: ["https://your-app.example.com"]
    },
    
    // 速率限制
    rateLimit: {
      windowMs: 60000,
      maxRequests: 100
    },
    
    // 连接超时
    connectionTimeout: 300000,  // 5 分钟
  }
}

6.9 客户端实现示例

JavaScript/TypeScript

import WebSocket from 'ws';

const ws = new WebSocket('ws://localhost:19000');

ws.on('open', () => {
  // 发送连接请求
  ws.send(JSON.stringify({
    type: 'req',
    id: 'conn_001',
    method: 'connect',
    params: { token: 'your-token' }
  }));
});

ws.on('message', (data) => {
  const frame = JSON.parse(data.toString());
  
  if (frame.type === 'res') {
    console.log('Response:', frame);
  } else if (frame.type === 'event') {
    console.log('Event:', frame.event, frame.payload);
  }
});

// 调用 Agent
function callAgent(message: string) {
  ws.send(JSON.stringify({
    type: 'req',
    id: `agent_${Date.now()}`,
    method: 'agent',
    params: {
      sessionKey: 'agent:main:main',
      message
    }
  }));
}

总结

WebSocket Gateway 是 OpenClaw 的核心枢纽：