TypeBox 协议真理源

最后更新：2026-01-10

TypeBox 是 TypeScript 优先的 Schema 库。OpenClaw 用它定义 Gateway WebSocket 协议（握手、请求/响应、服务端事件）。这些 Schema 驱动运行时验证、JSON Schema 导出和面向 macOS 应用的 Swift 代码生成。一个真理源，其余全部生成。

更高层次的协议背景请先看 Gateway 架构。

30 秒心智模型

每条 Gateway WS 消息是以下三种帧之一：

• Request：{ type: "req", id, method, params }
• Response：{ type: "res", id, ok, payload | error }
• Event：{ type: "event", event, payload, seq?, stateVersion? }

第一帧必须是 connect Request。之后客户端可以调用方法（如 health、send、chat.send）并订阅事件（如 presence、tick、agent）。

连接流程（最简）：

Client                    Gateway
  |---- req:connect -------->|
  |<---- res:hello-ok --------|
  |<---- event:tick ----------|
  |---- req:health ---------->|
  |<---- res:health ----------|

常用方法 + 事件：

分类	示例	说明
核心	connect、health、status	connect 必须是第一条
消息	send、agent、agent.wait、system-event、logs.tail	有副作用的需要 idempotencyKey
Chat	chat.history、chat.send、chat.abort	WebChat 用这些
Sessions	sessions.list、sessions.patch、sessions.delete	会话管理
自动化	wake、cron.list、cron.run、cron.runs	wake + cron 控制
Nodes	node.list、node.invoke、node.pair.*	Gateway WS + Node 动作
事件	tick、presence、agent、chat、health、shutdown	服务端推送

权威的发现清单在 src/gateway/server-methods-list.ts（listGatewayMethods、GATEWAY_EVENTS）。

Schema 文件位置

文件	说明
src/gateway/protocol/schema.ts	源 Schema
src/gateway/protocol/index.ts	运行时 AJV 验证器
src/gateway/server-methods-list.ts	已通告特性/发现注册表
src/gateway/server.impl.ts	服务端握手 + 方法分发
src/gateway/client.ts	Node 客户端
dist/protocol.schema.json	生成的 JSON Schema
apps/macos/.../GatewayModels.swift	生成的 Swift 模型

代码生成管道

pnpm protocol:gen         # 输出 JSON Schema (draft-07) 到 dist/protocol.schema.json
pnpm protocol:gen:swift   # 生成 Swift Gateway 模型
pnpm protocol:check       # 运行两个生成器并验证输出已提交

帧格式示例

connect（第一条消息）：

{
  "type": "req",
  "id": "c1",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 3,
    "client": {
      "id": "openclaw-macos",
      "displayName": "macos",
      "version": "1.0.0",
      "platform": "macos 15.1",
      "mode": "ui",
      "instanceId": "A1B2"
    }
  }
}

hello-ok 响应：

{
  "type": "res",
  "id": "c1",
  "ok": true,
  "payload": {
    "type": "hello-ok",
    "protocol": 3,
    "server": { "version": "dev", "connId": "ws-1" },
    "features": { "methods": ["health"], "events": ["tick"] }
  }
}

最小客户端示例（Node.js）

import { WebSocket } from "ws";

const ws = new WebSocket("ws://127.0.0.1:18789");

ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "req", id: "c1", method: "connect",
    params: { minProtocol: 3, maxProtocol: 3, client: { id: "cli", displayName: "example", version: "dev", platform: "node", mode: "cli" } },
  }));
});

ws.on("message", (data) => {
  const msg = JSON.parse(String(data));
  if (msg.type === "res" && msg.id === "c1" && msg.ok) {
    ws.send(JSON.stringify({ type: "req", id: "h1", method: "health" }));
  }
  if (msg.type === "res" && msg.id === "h1") {
    console.log("health:", msg.payload);
    ws.close();
  }
});

新增方法完整步骤

以新增 system.echo 方法为例：

1. 更新 Schema（src/gateway/protocol/schema.ts）：

export const SystemEchoParamsSchema = Type.Object(
  { text: NonEmptyString },
  { additionalProperties: false },
);
export const SystemEchoResultSchema = Type.Object(
  { ok: Type.Boolean(), text: NonEmptyString },
  { additionalProperties: false },
);

2. 添加验证器（src/gateway/protocol/index.ts）：

export const validateSystemEchoParams = ajv.compile<SystemEchoParams>(SystemEchoParamsSchema);

3. 添加服务端处理器（src/gateway/server-methods/system.ts）：

export const systemHandlers: GatewayRequestHandlers = {
  "system.echo": ({ params, respond }) => {
    respond(true, { ok: true, text: String(params.text ?? "") });
  },
};

注册到 src/gateway/server-methods-list.ts，并在 src/gateway/method-scopes.ts 按需分类作用域。

4. 重新生成并验证：

pnpm protocol:check

FAQ

Q：客户端怎么知道 Gateway 支持哪些方法？ 连接成功后，hello-ok 响应的 features.methods 和 features.events 字段列出了已通告的方法和事件。

Q：为什么有些方法没出现在 features 列表里？ 部分辅助 RPC 实现在 server-methods/*.ts 中但未列入通告特性清单，这是设计决策（内部 API 面）。

延伸阅读

• Gateway 架构
• Gateway 配置参考