Gateway 协议详解

协议概述

OpenClaw Gateway 使用多种通信协议与不同的客户端和服务进行交互：

HTTP REST API：用于管理操作和同步请求
WebSocket：用于实时双向通信
Server-Sent Events (SSE)：用于流式响应
Webhook HTTP POST：用于接收频道平台的消息推送

HTTP REST API

基础端点

GET    /health              健康检查
GET    /api/status           服务状态
POST   /api/chat             发送消息
GET    /api/models           获取模型列表
GET    /api/channels         获取频道列表
GET    /api/sessions         获取会话列表
POST   /api/sessions/:id     操作会话

请求格式

所有 API 请求使用 JSON 格式：

curl -X POST https://gateway.example.com/api/chat \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "api",
    "message": "你好",
    "sessionId": "session-123",
    "stream": false
  }'

响应格式

{
  "success": true,
  "data": {
    "message": "你好！有什么可以帮你的吗？",
    "sessionId": "session-123",
    "model": "gpt-4o",
    "usage": {
      "promptTokens": 15,
      "completionTokens": 12,
      "totalTokens": 27
    }
  },
  "timestamp": "2026-03-10T08:30:00Z"
}

错误响应

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests, please try again later",
    "retryAfter": 30
  }
}

流式响应（SSE）

当 stream: true 时，Gateway 使用 Server-Sent Events 返回流式响应：

curl -X POST https://gateway.example.com/api/chat \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"channel": "api", "message": "写一首诗", "stream": true}'

SSE 事件流格式：

event: message
data: {"type": "chunk", "content": "春"}

event: message
data: {"type": "chunk", "content": "风"}

event: message
data: {"type": "chunk", "content": "拂面"}

event: message
data: {"type": "done", "usage": {"totalTokens": 50}}

WebSocket 协议

WebSocket 连接用于实时双向通信：

const ws = new WebSocket('wss://gateway.example.com/ws');

ws.onopen = () => {
  // 认证
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'your-api-key'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data);
};

WebSocket 消息类型

客户端 → 服务端：

{"type": "auth", "token": "api-key"}
{"type": "message", "channel": "api", "content": "你好", "sessionId": "s1"}
{"type": "ping"}
{"type": "subscribe", "events": ["message", "status"]}

服务端 → 客户端：

{"type": "auth_ok", "user": "admin"}
{"type": "message", "content": "你好！", "sessionId": "s1"}
{"type": "chunk", "content": "部分", "sessionId": "s1"}
{"type": "done", "sessionId": "s1", "usage": {}}
{"type": "pong"}
{"type": "error", "code": "INVALID_SESSION", "message": "..."}

Webhook 协议

频道平台（Telegram、Discord 等）通过 Webhook 向 Gateway 推送消息：

POST /webhook/telegram
POST /webhook/discord
POST /webhook/slack

Gateway 验证 Webhook 签名后处理消息：

{
  "gateway": {
    "webhooks": {
      "verifySignature": true,
      "timeout": 5000,
      "retryOnFailure": true
    }
  }
}

健康检查协议

# 基础健康检查
GET /health
# 返回: {"status": "ok"}

# 详细健康检查
GET /health/detailed
# 返回:
{
  "status": "ok",
  "uptime": 86400,
  "version": "1.2.3",
  "providers": {
    "openai": "connected",
    "anthropic": "connected"
  },
  "channels": {
    "telegram": "active",
    "discord": "active"
  },
  "memory": {
    "used": "128MB",
    "total": "512MB"
  }
}

协议版本控制

API 使用 URL 路径版本控制：

/api/v1/chat    ← 当前稳定版本
/api/v2/chat    ← 新版本（如果可用）

请求头中也可以指定版本：

X-API-Version: 2026-03-01

速率限制头

Gateway 在响应中包含速率限制信息：

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709020800

总结

理解 Gateway 的通信协议对于开发自定义集成和排查问题至关重要。HTTP REST API 适合简单集成，WebSocket 适合需要实时交互的场景，SSE 则是流式输出的标准选择。所有协议都支持认证和速率限制。