跳转至

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 }
  }
}

请求和响应:

{ "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: 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 }。

  1. 模式(事实来源)

添加到 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>;
  1. 验证

在 packages/gateway-protocol/src/validator-registry.ts 中,使用其现有的懒加载编译器导出一个验证器:

export const validateSystemEchoParams = compile(S.SystemEchoParamsSchema);
  1. 服务端行为

在 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 功能通告保持一致。

  1. 重新生成
pnpm protocol:check
  1. 测试和文档

在 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 模式可在以下位置获取:

更改模式时

  1. 更新所属 packages/gateway-protocol/src/schema/*.ts 模块中的 TypeBox 模式。确保新模块由 schema-modules.ts 导出,检查其自动 *Schema 成员资格,并根据需要更新辅助排除项或现有补充所有者映射。
  2. 在 src/gateway/server-methods-list.ts 中注册方法/事件。
  3. 当新 RPC 需要操作员或节点范围分类时,更新 src/gateway/method-scopes.ts。
  4. 运行 pnpm protocol:check。
  5. 提交重新生成的 Swift 模型。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw