TypeBox

TypeBox 是一个 TypeScript 优先的模式库。OpenClaw 使用它定义 Gateway 网关 WebSocket 协议（握手、请求/响应、服务器事件）。这些模式用于驱动运行时验证（AJV）、JSON Schema 导出以及 macOS 应用的 Swift 代码生成。它是唯一的事实来源；其他所有内容均由此生成。有关更高层级的协议背景，请先阅读 Gateway 网关架构。

心智模型（30 秒）

每条 Gateway 网关 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）。连接流程（最简）：

客户端                    Gateway 网关
  |---- 请求：connect ------->|
  |<---- 响应：hello-ok -------|
  |<---- 事件：tick -----------|
  |---- 请求：health -------->|
  |<---- 响应：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`	唤醒和定时任务控制
节点	`node.list`、`node.invoke`、`node.pair.*`	Gateway 网关 WS 加节点操作
事件	`tick`、`presence`、`agent`、`chat`、`health`、`shutdown`	服务器推送

权威的已公布设备发现清单位于 src/gateway/server-methods-list.ts（listGatewayMethods、GATEWAY_EVENTS）。

模式所在位置

源导出入口：packages/gateway-protocol/src/schema.ts 重新导出 packages/gateway-protocol/src/schema/*.ts 下的领域模块（frames.ts 用于顶层信封和握手，agent.ts、sessions.ts、cron.ts 等分别对应各功能领域）。protocol-schemas.ts 是中央 ProtocolSchemas 注册表，将模式名称映射到相应的 TypeBox 定义。
运行时验证器（AJV）：packages/gateway-protocol/src/index.ts
已公布的功能/设备发现注册表：src/gateway/server-methods-list.ts
服务器握手和方法分发：src/gateway/server.impl.ts
节点客户端：src/gateway/client.ts
生成的 JSON Schema：dist/protocol.schema.json（构建输出，不提交）
生成的 Swift 模型：apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift

当前流水线

pnpm protocol:gen 将 JSON Schema（draft-07）写入 dist/protocol.schema.json。
pnpm protocol:gen:swift 生成 Swift Gateway 网关模型。
pnpm protocol:check 运行两个生成器，并验证 Swift 输出已提交（JSON Schema 输出是被 git 忽略的构建工件）。

模式在运行时的使用方式

服务器端：每个入站帧都使用 AJV 进行验证。握手仅接受参数符合 ConnectParams 的 connect 请求。
客户端：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 }。

模式（事实来源）

添加到 packages/gateway-protocol/src/schema/system.ts（或最匹配的功能模块）：

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

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

将二者导入 packages/gateway-protocol/src/schema/protocol-schemas.ts，添加到 ProtocolSchemas 注册表，并导出派生类型：

  SystemEchoParams: SystemEchoParamsSchema,
  SystemEchoResult: SystemEchoResultSchema,

export type SystemEchoParams = Static<typeof SystemEchoParamsSchema>;
export type SystemEchoResult = Static<typeof SystemEchoResultSchema>;

验证

在 packages/gateway-protocol/src/index.ts 中导出 AJV 验证器：

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

服务器行为

在 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 中将 "system.echo" 添加到 listGatewayMethods 输入。如果操作员或节点客户端可以调用该方法，还需要在 src/gateway/method-scopes.ts 中对它进行分类，使权限范围强制执行与 hello-ok 功能公布保持一致。

重新生成

pnpm protocol:check

测试和文档

在 src/gateway/server.*.test.ts 中添加服务器测试，并在文档中注明该方法。

Swift 代码生成行为

Swift 生成器会生成：

一个 GatewayFrame 枚举，包含 req、res、event 和 unknown 分支
强类型负载结构体/枚举
ErrorCode 值、GATEWAY_PROTOCOL_VERSION 和 GATEWAY_MIN_PROTOCOL_VERSION

未知帧类型会保留为原始负载，以便向前兼容。

版本控制和兼容性

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 是构建工件，不提交到仓库。发布的原始文件通常位于：

https://raw.githubusercontent.com/openclaw/openclaw/main/dist/protocol.schema.json

更改模式时

更新所属 packages/gateway-protocol/src/schema/*.ts 模块中的 TypeBox 模式，并在 protocol-schemas.ts 中注册。
在 src/gateway/server-methods-list.ts 中注册方法/事件。
当新 RPC 需要操作员或节点权限范围分类时，更新 src/gateway/method-scopes.ts。
运行 pnpm protocol:check。
提交重新生成的 Swift 模型。

CLI 命令

RPC 与 API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

模板

技术参考

概念内部机制

项目

Contributing

心智模型（30 秒）

模式所在位置

当前流水线

模式在运行时的使用方式

帧示例

最简客户端（Node.js）

完整示例：端到端添加一个方法

Swift 代码生成行为

版本控制和兼容性

模式范式和约定

实时模式 JSON

更改模式时

相关内容

​心智模型（30 秒）

​模式所在位置

​当前流水线

​模式在运行时的使用方式

​帧示例

​最简客户端（Node.js）

​完整示例：端到端添加一个方法

​Swift 代码生成行为

​版本控制和兼容性

​模式范式和约定

​实时模式 JSON

​更改模式时

​相关内容

心智模型（30 秒）

模式所在位置

当前流水线

模式在运行时的使用方式

帧示例

最简客户端（Node.js）

完整示例：端到端添加一个方法

Swift 代码生成行为

版本控制和兼容性

模式范式和约定

实时模式 JSON

更改模式时

相关内容