TypeBox

TypeBox is a TypeScript-first schema library. OpenClaw uses it to define the Gateway WebSocket protocol (handshake, request/response, server events). Those schemas drive runtime validation (TypeBox Compile), JSON Schema export, and Swift codegen for the macOS app. One source of truth; everything else is generated. For the higher-level protocol context, start with Gateway architecture.

Mental model (30 seconds)

Every Gateway WS message is one of three frames:

Request: { type: "req", id, method, params }
Response: { type: "res", id, ok, payload | error }
Event: { type: "event", event, payload, seq?, stateVersion? }

The first frame must be a connect request. After that, clients call methods (e.g. health, send, chat.send) and subscribe to events (e.g. presence, tick, agent). Connection flow (minimal):

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

Common methods and events:

Category	Examples	Notes
Core	`connect`, `health`, `status`	`connect` must be first
Messaging	`send`, `agent`, `agent.wait`, `system-event`, `logs.tail`	side-effecting methods need `idempotencyKey`
Chat	`chat.history`, `chat.send`, `chat.abort`	WebChat uses these
Sessions	`sessions.list`, `sessions.patch`, `sessions.delete`	session admin
Automation	`wake`, `cron.list`, `cron.run`, `cron.runs`	wake and cron control
Nodes	`node.list`, `node.invoke`, `node.pair.*`	Gateway WS plus node actions
Events	`tick`, `presence`, `agent`, `chat`, `health`, `shutdown`	server push

The authoritative advertised discovery inventory lives in src/gateway/server-methods-list.ts (listGatewayMethods, GATEWAY_EVENTS).

Where the schemas live

Source barrels: packages/gateway-protocol/src/schema-modules.ts owns the canonical domain-module list, while the public schema.ts wrapper also exposes ProtocolSchemas.
Generator selection: packages/gateway-protocol/src/schema/protocol-schema-selection.ts derives registry names from the canonical barrel’s *Schema exports and explicit skill-library.ts imports, removing the Schema suffix. EXCLUDED_SCHEMA_EXPORTS keeps helpers and schemas with supplemental registry owners out of this derived selection.
Generator registry: protocol-schemas.ts composes the derived selection, MigrationProtocolSchemas, and SessionPlacementProtocolSchemas, rejecting duplicate keys and retaining the canonical TypeBox objects. protocol-schema-types.ts preserves each member’s schema type and public readonly/writable modifiers.
Runtime validators: packages/gateway-protocol/src/validator-registry.ts, using the lazy TypeBox Compile owner in protocol-validator.ts
Advertised feature/discovery registry: src/gateway/server-methods-list.ts
Server handshake and method dispatch: src/gateway/server-core-runtime.ts
Node client: src/gateway/client.ts
Generated JSON Schema: dist/protocol.schema.json (build output, not committed)
Generated Swift models: apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift

The derived selection uses lexical order of the full source export names before removing the Schema suffix. The migration and session-placement maps follow it in their own insertion order. This replaces the former manually ordered registration fragments; JSON definition order and Swift declaration placement can change without changing schema data or native declaration bodies. Membership is now opt-out for eligible source exports: a new *Schema export in the canonical barrel enters the generator registry unless explicitly excluded. Review each new export for intended generated-protocol membership, and add helper-only exports to EXCLUDED_SCHEMA_EXPORTS. The registry guard checks selection consistency, canonical objects, exclusions, and composition; it cannot independently determine whether a newly exported schema belongs in the public generated protocol.

Current pipeline

pnpm protocol:gen writes JSON Schema (draft-07) to dist/protocol.schema.json.
pnpm protocol:gen:swift generates the Swift gateway models.
pnpm protocol:check:swift verifies the committed Swift models without rewriting them.
pnpm protocol:gen:kotlin generates the Android protocol models and constants.
pnpm protocol:check checks the registry structure, runs all three generators, and verifies the committed Swift and Kotlin output. The JSON Schema output is a gitignored build artifact with no committed baseline to diff against, so pnpm protocol:gen instead asserts the published-document contract (required frame definitions, frame ordering, type discriminator mapping, non-empty method metadata) and fails the check when the generated schema drifts from it.

When a gateway schema affects native clients, run pnpm protocol:gen:swift, review the generated diff, then run pnpm protocol:check:swift. Commit the schema and GatewayModels.swift update together. Stable decoding behavior belongs in the focused GatewayModelsCompatibilityTests.swift regressions rather than in handwritten model copies.

How the schemas are used at runtime

Server side: every inbound frame is validated with TypeBox Compile. The handshake only accepts a connect request whose params match ConnectParams.
Client side: the JS client validates event and response frames before using them.
Feature discovery: the Gateway sends a conservative features.methods and features.events list in hello-ok, from listGatewayMethods() and GATEWAY_EVENTS.
That discovery list is not a generated dump of every callable helper in coreGatewayHandlers; some helper RPCs are implemented in src/gateway/server-methods/*.ts without being enumerated in the advertised feature list.

Example frames

Connect (first message):

{
  "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 response:

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

Request and response:

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

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

Event:

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

Minimal client (Node.js)

Smallest useful flow: connect + health.

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

Worked example: add a method end-to-end

Example: add a new system.echo request that returns { ok: true, text }.

Schema (source of truth)

Add to packages/gateway-protocol/src/schema/system-info.ts (or the closest matching feature module):

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

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

system-info.ts is already exported by packages/gateway-protocol/src/schema-modules.ts, so both schemas enter ProtocolSchemas automatically as SystemEchoParams and SystemEchoResult. For a new owner module, add its export to that canonical barrel. Review any other *Schema exports it introduces and exclude helper-only schemas in protocol-schema-selection.ts. Keep schemas owned by the migration or session-placement maps in those maps and excluded from the derived selection. Export the corresponding static types from the owner module:

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

Validation

In packages/gateway-protocol/src/validator-registry.ts, export a validator using its existing lazy compiler:

export const validateSystemEchoParams = compile(S.SystemEchoParamsSchema);

Server behavior

Add a handler in src/gateway/server-methods/system.ts:

export const systemHandlers: GatewayRequestHandlers = {
  "system.echo": ({ params, respond }) => {
    const text = String(params.text ?? "");
    respond(true, { ok: true, text });
  },
};

Register it in src/gateway/server-methods.ts (already merges systemHandlers), then add "system.echo" to the listGatewayMethods input in src/gateway/server-methods-list.ts. If the method is callable by operator or node clients, also classify it in src/gateway/method-scopes.ts so scope enforcement and hello-ok feature advertising stay aligned.

Regenerate

pnpm protocol:check

Tests and docs

Add a server test in src/gateway/server.*.test.ts and note the method in docs.

Swift codegen behavior

The Swift generator emits:

a GatewayFrame enum with req, res, event, and unknown cases
strongly typed payload structs/enums
ErrorCode values, GATEWAY_PROTOCOL_VERSION, and GATEWAY_MIN_PROTOCOL_VERSION

Unknown frame types are preserved as raw payloads for forward compatibility. Some registry names alias the same canonical schema object. The explicit canonical alias preferences in scripts/protocol-gen-swift.ts preserve the existing public Swift type names when registry enumeration changes. Review generated declaration bodies, including field types, initializers, and encoding/decoding behavior; moving declarations must not silently select different nominal types. The published JSON Schema’s oneOf frame order is a separate contract: req, res, then event, with the matching type discriminator mapping. scripts/lib/protocol-schema-document.mts owns and checks that order independently of registry definition order.

Versioning and compatibility

PROTOCOL_VERSION lives in packages/gateway-protocol/src/version.ts (current value: 4).
Clients send minProtocol and maxProtocol; the server rejects ranges that do not include its current protocol.
The Swift models keep unknown frame types to avoid breaking older clients.

Schema patterns and conventions

Most objects use additionalProperties: false for strict payloads.
NonEmptyString (Type.String({ minLength: 1 })) is the default for IDs and method/event names.
The top-level GatewayFrame uses a discriminator on type.
Methods with side effects usually require an idempotencyKey in params (example: send, poll, agent, chat.send).
agent accepts optional internalEvents for runtime-generated orchestration context (for example subagent/cron task completion handoff); treat this as internal API surface.

Live schema JSON

Generated JSON Schema is a build artifact, not committed to the repo. During the package rollout, the current beta schema is available at:

protocol.schema.json

When you change schemas

Update the TypeBox schemas in the owning packages/gateway-protocol/src/schema/*.ts module. Ensure a new module is exported by schema-modules.ts, review its automatic *Schema membership, and update helper exclusions or existing supplemental owner maps as needed.
Register the method/event in src/gateway/server-methods-list.ts.
Update src/gateway/method-scopes.ts when the new RPC needs operator or node scope classification.
Run pnpm protocol:check.
Commit the regenerated Swift models.

CLI commands

RPC and API

Codex runtime reference

Plugin reference

Plugin SDK reference

Plugin internals

Templates

Technical reference

Schemas and formatting

Project and contributing

Mental model (30 seconds)

Where the schemas live

Current pipeline

How the schemas are used at runtime

Example frames

Minimal client (Node.js)

Worked example: add a method end-to-end

Swift codegen behavior

Versioning and compatibility

Schema patterns and conventions

Live schema JSON

When you change schemas

​Mental model (30 seconds)

​Where the schemas live

​Current pipeline

​How the schemas are used at runtime

​Example frames

​Minimal client (Node.js)

​Worked example: add a method end-to-end

​Swift codegen behavior

​Versioning and compatibility

​Schema patterns and conventions

​Live schema JSON

​When you change schemas

​Related

Mental model (30 seconds)

Where the schemas live

Current pipeline

How the schemas are used at runtime

Example frames

Minimal client (Node.js)

Worked example: add a method end-to-end

Swift codegen behavior

Versioning and compatibility

Schema patterns and conventions

Live schema JSON

When you change schemas

Related