OpenClaw从入门到应用——Agent：TypeBox

姚思瀚

2026-06-28 • 👁 0人浏览过

通过OpenClaw实现副业收入：《OpenClaw赚钱实录：从“养龙虾“到可持续变现的实践指南》 TypeBox TypeBox 作为协议真实来源最后更新：2026-01-10 TypeBox 是一个优先支持 TypeScript 的 schema 库。

我们使用它来定义 Gateway WebSocket 协议（握手、请求/响应、服务器事件）。

这些 schemas 驱动运行时验证、 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

请求。

之后，客户端可以调用方法（例如

health

，

send

chat.send

）并订阅事件（例如

presence

tick

agent

）。

连接流程（最小示例）：

Client                    Gateway

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

常用方法 + 事件：类别示例说明核心connect,health,statusconnect必须是第一个消息传递send,poll,agent,agent.wait副作用需要idempotencyKey聊天chat.history,chat.send,chat.abort,chat.injectWebChat 使用这些会话sessions.list,sessions.patch,sessions.delete会话管理节点node.list,node.invoke,node.pair.*Gateway WS + 节点操作事件tick,presence,agent,chat,health,shutdown服务器推送权威列表位于

src/gateway/server.ts

(

METHODS

EVENTS

)。

Schemas 所在位置源文件：

src/gateway/protocol/schema.ts

运行时验证器（AJV）：

src/gateway/protocol/index.ts

服务器握手 + 方法分发：

src/gateway/server.ts

节点客户端：

src/gateway/client.ts

生成的 JSON Schema：

dist/protocol.schema.json

生成的 Swift 模型：

apps/macos/Sources/OpenClawProtocol/GatewayModels.swift

当前流程

pnpm protocol:gen

将 JSON Schema（draft-07）写入

dist/protocol.schema.json pnpm protocol:gen:swift

生成 Swift gateway 模型

pnpm protocol:check

运行两个生成器并验证输出已被提交如何在运行时使用 Schemas 服务端：每个入站帧都使用 AJV 进行验证。

握手只接受一个其参数匹配

ConnectParams

的

connect

请求。

客户端：JS 客户端在使用事件和响应帧之前对其进行验证。

方法表面：Gateway 在

hello-ok

中通告支持的

methods

和

events

。

示例帧连接（第一条消息）：

{

"type": "req",
"id": "c1",
"method": "connect",
"params": {
"minProtocol": 2,
"maxProtocol": 2,
"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": 2,
"server": { "version": "dev", "connId": "ws-1" },
"features": { "methods": ["health"], "events": ["tick"] },
"snapshot": {
"presence": [],
"health": {},
"stateVersion": { "presence": 0, "health": 0 },
"uptimeMs": 0
},
"policy": { "maxPayload": 1048576, "maxBufferedBytes": 1048576, "tickIntervalMs": 30000 }
}
}

请求 + 响应：

{ "type": "req", "id": "r1", "method": "health" }

{ "type": "res", "id": "r1", "ok": true, "payload": { "ok": true } }

事件：

{ "type": "event", "event": "tick", "payload": { "ts": 1730000000 }, "seq": 12 }

最小客户端（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

请求，返回

{ ok: true, text }

。

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 },
);

将两者添加到

ProtocolSchemas

并导出类型：

  SystemEchoParams: SystemEchoParamsSchema,

SystemEchoResult: SystemEchoResultSchema,

export type SystemEchoParams = Static;

export type SystemEchoResult = Static;

验证在

src/gateway/protocol/index.ts

中，导出一个 AJV 验证器：

export const validateSystemEchoParams = ajv.compile(SystemEchoParamsSchema);

服务端行为在

src/gateway/server-methods/system.ts

中添加一个处理器：

export const systemHandlers: GatewayRequestHandlers = {

"system.echo": ({ params, respond }) => {
// 注意：此处对 params.text 进行了类型断言，实际应用应使用验证器
const text = String(params.text ?? "");
respond(true, { ok: true, text });
},
};

在

src/gateway/server-methods.ts

中注册它（通常会合并

systemHandlers

），然后在

src/gateway/server.ts

中将

"system.echo"

添加到

METHODS

。

重新生成

pnpm protocol:check

测试 + 文档在

src/gateway/server.*.test.ts

中添加一个服务端测试，并在文档中注明该方法。

Swift 代码生成行为 Swift 生成器会输出：

GatewayFrame

枚举，包含

req

res

event

和

unknown

等情况强类型的 payload 结构体/枚举

ErrorCode

值和

GATEWAY_PROTOCOL_VERSION

未知的帧类型会作为原始 payload 保留，以实现向前兼容。

版本控制 + 兼容性

PROTOCOL_VERSION

位于

src/gateway/protocol/schema.ts

。

客户端发送

minProtocol

maxProtocol

；服务器会拒绝不匹配的请求。

Swift 模型保留未知的帧类型，以避免破坏旧客户端。

Schema 模式与约定大多数对象使用

additionalProperties: false

以确保严格的 payload。

NonEmptyString

是 ID 和方法/事件名称的默认类型。

顶层

GatewayFrame

在

type

字段上使用判别器。

具有副作用的方法通常需要在参数中包含一个

idempotencyKey

（例如

send

poll

agent

chat.send

）。

agent

接受可选的

internalEvents

，用于运行时生成编排上下文（例如子代理/cron 任务完成交接）；请将其视为内部 API 表面。

在线 Schema JSON 生成的 JSON Schema 在仓库的

dist/protocol.schema.json

中。

发布的原始文件通常可在以下地址获得： https://raw.githubusercontent.com/openclaw/openclaw/main/dist/protocol.schema.json 当你更改 schemas 时更新 TypeBox schemas。

运行

pnpm protocol:check

。

提交重新生成的 schema 和 Swift 模型。

相关文章