TypeBox
TypeBox 是一个以 TypeScript 为先的 schema 库。OpenClaw 使用它来定义 网关 WebSocket 协议(握手、请求/响应、服务器事件)。这些 schema 驱动 运行时校验(TypeBox Compile)、JSON Schema 导出,以及 macOS 应用的 Swift 代码生成。单一事实来源;其他一切都是生成的。
如需了解更上层的协议上下文,请从网关架构开始。
心智模型(30 秒)¶
每条网关 WS 消息都是以下三种帧之一:
- 请求:
{ type: "req", id, method, params } - 响应:
{ type: "res", id, ok, payload | error } - 事件:
{ 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, status |
connect 必须放在第一位 |
| 消息 | send, agent, agent.wait, system-event, logs.tail |
有副作用的方法需要 idempotencyKey |
| 聊天 | chat.history, chat.send, chat.abort |
WebChat 使用这些 |
| 会话 | sessions.list, sessions.patch, sessions.delete |
会话管理 |
| 自动化 | wake, cron.list, cron.run, cron.runs |
wake 与 cron 控制 |
| 节点 | node.list, node.invoke, node.pair.* |
网关 WS 加上节点操作 |
| 事件 | tick, presence, agent, chat, health, shutdown |
服务器推送 |
权威且对外公布的 发现(discovery) 清单位于 src/gateway/server-methods-list.ts(listGatewayMethods、GATEWAY_EVENTS)。
Schema 存放位置¶
- 源桶文件:
packages/gateway-protocol/src/schema-modules.ts持有规范的领域模块列表,而公开的schema.ts包装器还暴露ProtocolSchemas。 - 生成器选择:
packages/gateway-protocol/src/schema/protocol-schema-selection.ts从规范桶文件的*Schema导出和显式的skill-library.ts导入中派生注册表名称,并移除Schema后缀。EXCLUDED_SCHEMA_EXPORTS将辅助程序以及具有补充注册表所有者的 schema 排除在此派生选择之外。 - 生成器注册表:
protocol-schemas.ts组合派生选择、MigrationProtocolSchemas和SessionPlacementProtocolSchemas,拒绝重复键并保留规范的 TypeBox 对象。protocol-schema-types.ts保留每个成员的 schema 类型,以及公开的 readonly/writable 修饰符。 - 运行时校验器:
packages/gateway-protocol/src/validator-registry.ts,使用protocol-validator.ts中的惰性 TypeBox Compile 所有者。 - 对外公布的功能/发现注册表:
src/gateway/server-methods-list.ts - 服务器握手与方法分发:
src/gateway/server-core-runtime.ts - 节点客户端:
src/gateway/client.ts - 生成的 JSON Schema:
dist/protocol.schema.json(构建产物,不提交) - 生成的 Swift 模型:SwiftPM/Xcode 插件输出,或供仓库工具链使用的
apps/shared/OpenClawKit/.build/protocol/GatewayModels.swift
派生选择使用完整源码导出名称的字典序,并且是在移除 Schema 后缀之前。迁移映射和会话放置映射以各自的插入顺序紧随其后。这取代了之前手动排序的注册片段;JSON 定义顺序和 Swift 声明位置可以改变,而不会改变 schema 数据或原生声明体。
对于符合条件的源码导出,成员资格现在是默认纳入、可退出(opt-out)的:规范桶文件中的新 *Schema 导出会进入生成器注册表,除非被显式排除。请审查每个新导出,以确定其是否应属于生成的协议,并将仅作辅助用途的导出添加到 EXCLUDED_SCHEMA_EXPORTS。注册表守卫会检查选择一致性、规范对象、排除项和组合方式;它无法独立判断新导出的 schema 是否属于公开的生成协议。
当前流水线¶
pnpm protocol:gen将 JSON Schema(draft-07)写入dist/protocol.schema.json。pnpm install和pnpm build会自动准备原生协议模型。SwiftPM/Xcode 和 Gradle 也会生成各自的构建自有源文件,并跳过未变更的生成。全新的完整仓库源码归档使用这些相同的入口点。pnpm protocol:gen:swift在共享包中受忽略的.build/protocol目录下生成 Swift 模型。pnpm protocol:gen:kotlin在apps/android/app/build/generated/openclaw-protocol下生成 Android 模型和常量。pnpm protocol:check:swift和pnpm protocol:check:kotlin绕过缓存,检查 schema/版本契约,并生成两次以验证确定性。pnpm protocol:check检查注册表结构和所有生成产物。输出是受忽略的构建产物,而非已提交的基线。JSON Schema 校验检查必需的帧定义、帧顺序、type判别映射以及非空的方法元数据。原生校验对照 schema 注册表检查协议版本和 Swift 模型/枚举的成员资格;原生兼容性测试保护解码和初始化器契约。
请将 schema 与生成器变更一起提交;原生输出从不提交。scripts/native-protocol-inputs.json 拥有由仓库工具和两个原生构建系统共享的源输入。生成过程会将其导入图与该清单进行核对,因此未声明的依赖会导致失败,而不会留下过时的模型。稳定的解码行为应放在专项的 GatewayModelsCompatibilityTests.swift 回归测试中,而不是手写模型副本中。
运行时如何使用模式¶
- 服务端:每个入站帧都会使用 TypeBox Compile 进行验证。握手仅接受
connect请求,且其参数必须匹配ConnectParams。 - 客户端:JS 客户端在使用事件帧和响应帧之前会先验证它们。
- 功能发现:Gateway 会在
hello-ok中发送保守的features.methods和features.events列表,分别来自listGatewayMethods()和GATEWAY_EVENTS。 - 该发现列表并不是
coreGatewayHandlers中所有可调用辅助函数的生成转储;一些辅助 RPC 在src/gateway/server-methods/*.ts中实现,但未在公开的功能列表中列出。
示例帧¶
连接(第一条消息):
{
"type": "req",
"id": "c1",
"method": "connect",
"params": {
"minProtocol": 3,
"maxProtocol": 4,
"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": 4,
"server": { "version": "dev", "connId": "ws-1" },
"features": { "methods": ["health"], "events": ["tick"] },
"snapshot": {
"presence": [],
"health": {},
"stateVersion": { "presence": 0, "health": 0 },
"uptimeMs": 0
},
"auth": { "role": "operator", "scopes": ["operator.read"] },
"policy": { "maxPayload": 1048576, "maxBufferedBytes": 1048576, "tickIntervalMs": 30000 }
}
}
请求和响应:
事件:
最小客户端(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: 4,
maxProtocol: 4,
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 }。
- 模式(事实来源)
添加到 packages/gateway-protocol/src/schema/system-info.ts(或最接近的功能模块):
export const SystemEchoParamsSchema = Type.Object(
{ text: NonEmptyString },
{ additionalProperties: false },
);
export const SystemEchoResultSchema = Type.Object(
{ ok: Type.Boolean(), text: NonEmptyString },
{ additionalProperties: false },
);
system-info.ts 已由 packages/gateway-protocol/src/schema-modules.ts 导出,因此这两个模式会自动以 SystemEchoParams 和 SystemEchoResult 进入 ProtocolSchemas。对于新的所有者模块,请将其导出添加到该规范 barrel 中。审查它引入的其他任何 *Schema 导出,并在 protocol-schema-selection.ts 中排除仅辅助用的模式。将迁移或会话放置映射所拥有的模式保留在这些映射中,并排除在派生选择之外。
从所有者模块导出对应的静态类型:
export type SystemEchoParams = Static<typeof SystemEchoParamsSchema>;
export type SystemEchoResult = Static<typeof SystemEchoResultSchema>;
- 验证
在 packages/gateway-protocol/src/validator-registry.ts 中,使用其现有的懒加载编译器导出一个验证器:
- 服务端行为
在 src/gateway/server-methods/system.ts 中添加一个处理器:
export const systemHandlers: GatewayRequestHandlers = {
"system.echo": ({ params, respond }) => {
const text = String(params.text ?? "");
respond(true, { ok: true, text });
},
};
在 src/gateway/server-methods.ts 中注册它(该文件已经合并 systemHandlers),然后在 src/gateway/server-methods-list.ts 中的 listGatewayMethods 输入里添加 "system.echo"。
如果该方法可由 operator 或 node 客户端调用,还请将其分类到 src/gateway/method-scopes.ts 中,以便范围强制和 hello-ok 功能通告保持一致。
- 重新生成
- 测试和文档
在 src/gateway/server.*.test.ts 中添加一个服务端测试,并在文档中注明该方法。
Swift 代码生成行为¶
Swift 生成器会输出:
- 一个
GatewayFrame枚举,包含req、res、event和unknown情况 - 强类型的 payload 结构体/枚举
ErrorCode值、GATEWAY_PROTOCOL_VERSION和GATEWAY_MIN_PROTOCOL_VERSION
未知帧类型会作为原始 payload 保留,以实现向前兼容。
某些注册表名称是同一规范模式对象的别名。scripts/protocol-gen-swift.ts 中显式的规范别名偏好会在注册表枚举变化时保留现有的公开 Swift 类型名称。审查生成的声明主体,包括字段类型、初始化器以及编码/解码行为;移动声明时不得静默选择不同的名义类型。
已发布的 JSON Schema 的 oneOf 帧顺序是另一份契约:req、res,然后是 event,并带有匹配的 type 判别映射。scripts/lib/protocol-schema-document.mts 独立于注册表定义顺序来负责并检查该顺序。
版本控制与兼容性¶
PROTOCOL_VERSION位于packages/gateway-protocol/src/version.ts(当前值:4)。- 客户端发送
minProtocol和maxProtocol;服务端会拒绝不包含其当前协议的版本范围。 - Swift 模型会保留未知帧类型,以避免破坏旧客户端。
模式约定与规范¶
- 大多数对象使用
additionalProperties: false以实现严格负载。 NonEmptyString(Type.String({ minLength: 1 }))是 ID 和方法/事件名称的默认值。- 顶层
GatewayFrame在type上使用判别器。 - 具有副作用的方法通常要求在参数中包含
idempotencyKey(例如:send、poll、agent、chat.send)。 agent接受可选的internalEvents,用于运行时生成的编排上下文(例如子代理/定时任务完成交接);请将其视为内部 API 接口面。
实时模式 JSON¶
生成的 JSON Schema 是构建产物,不会提交到仓库。在包发布期间,当前 beta 模式可在以下位置获取:
更改模式时¶
- 更新所属
packages/gateway-protocol/src/schema/*.ts模块中的 TypeBox 模式。确保新模块由schema-modules.ts导出,检查其自动*Schema成员资格,并根据需要更新辅助排除项或现有补充所有者映射。 - 在
src/gateway/server-methods-list.ts中注册方法/事件。 - 当新 RPC 需要操作员或节点范围分类时,更新
src/gateway/method-scopes.ts。 - 运行
pnpm protocol:check。 - 提交重新生成的 Swift 模型。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw