TypeBox（协议 Schema）

概述

TypeBox 是 OpenClaw 用于定义 Gateway WebSocket 协议的 TypeScript-first Schema 库。这些 Schema 驱动运行时验证、JSON Schema 导出和 macOS 应用的 Swift 代码生成——一个真相来源，其他一切均由此生成。

核心要点

• 三种帧类型：Request（{type:"req", id, method, params}）、Response（{type:"res", id, ok, payload|error}）、Event（{type:"event", event, payload, seq?, stateVersion?}）
• 连接规则：第一帧必须是 connect 请求，服务端返回 hello-ok 响应
• Schema 位置：源码 src/gateway/protocol/schema.ts，运行时验证 src/gateway/protocol/index.ts，生成 JSON Schema dist/protocol.schema.json，生成 Swift 模型 apps/macos/Sources/OpenClawProtocol/GatewayModels.swift
• 代码生成命令：pnpm protocol:gen（JSON Schema）、pnpm protocol:gen:swift（Swift 模型）、pnpm protocol:check（验证已提交）
• 版本兼容：客户端发送 minProtocol+maxProtocol，服务端拒绝不包含当前版本的范围
• Schema 约定：大多数对象使用 additionalProperties: false；有副作用的方法需要 idempotencyKey

配置/使用

主要方法分类：

类别	示例
核心	connect, health, status
消息	send, agent, agent.wait, logs.tail
聊天	chat.history, chat.send, chat.abort
会话	sessions.list, sessions.patch, sessions.delete
自动化	wake, cron.list, cron.run
节点	node.list, node.invoke, node.pair.*

添加新方法的步骤：

1. 在 schema.ts 中添加 TypeBox Schema
2. 在 protocol/index.ts 中导出 AJV 验证器
3. 在 server-methods/ 中添加处理器
4. 在 server-methods-list.ts 中注册方法
5. 在 method-scopes.ts 中分类作用域
6. 运行 pnpm protocol:check 重新生成

相关页面

• architecture — Gateway 整体架构
• streaming — 流式输出协议
• openclaw-sdk — App SDK（使用此协议的客户端）
• messages — 消息处理流水线