packages/gateway-protocol/protocol.schema.json

"version": "2026.7.2",

"pluginApi": ">=2026.7.2"

"openclawVersion": "2026.7.2",

Wire-protocol and schema contracts for the OpenClaw Gateway (WebSocket JSON-RPC-style

frames, handshake, and method/event payload schemas). Protocol version is negotiated

per connection via `minProtocol`/`maxProtocol`. This log covers the wire protocol

version and the additive schema surface. Dates are authoring dates (2026).

- Rename structured-question item `id` to `questionId` and flatten keyed answer arrays.

- Slim worker and session-catalog payloads to the active wire contract.

- Remove dead protocol surfaces and add since-vintage metadata to retained schemas and methods.

Introduced 2026-05-07 (commit `330ba1f`). The stable, current wire version.

Wire contract:

- Frame envelopes: `req` / `res` / `event`, discriminated on `type`.

- Handshake: client sends `ConnectParams` (advertises `minProtocol`/`maxProtocol`,

client identity, `caps`, `commands`, `permissions`, `role`/`scopes`, optional signed

`device` identity, and an `auth` bag: token / bootstrapToken / deviceToken / password /

approvalRuntimeToken / agentRuntimeIdentityToken).

- Server replies `hello-ok` with the negotiated `protocol`, server identity, the live

`features` map (`methods`, `events`, `capabilities`), initial `snapshot`, minted `auth`

device tokens, and connection `policy` (maxPayload / maxBufferedBytes / tickIntervalMs).

- Server events: `tick` heartbeat and `shutdown` notice; event frames may carry `seq`

and `stateVersion` for ordered state sync.

Changed vs v3:

- `hello-ok` handshake replaced the single `canvasHostUrl` string with a

`pluginSurfaceUrls` map (canvas generalized into arbitrary plugin surfaces). This

field change is the breaking bump behind v4.

- Later additively extended (no bump) with `controlUiTabs` (plugin-declared Control UI

tabs) and multi-`deviceTokens` in the handshake auth block.

Compatibility window (`version.ts`):

- `MIN_CLIENT_PROTOCOL_VERSION = 4` — general clients must speak v4.

- `MIN_NODE_PROTOCOL_VERSION = 3` and `MIN_PROBE_PROTOCOL_VERSION = 3` — authenticated

nodes and lightweight probes are accepted at N-1 (v3) to stay manageable during

rolling upgrades. Added 2026-07-06 (#101109).

- A transient v5 (2026-05-16, `07f05e9`) renamed `inboundTurnKind` -> `inboundEventKind`;

it was reverted the next day (2026-05-17, `ad155fb`, "restore v4 message action

protocol"). v5 never shipped as a stable ceiling; v4 remains current.

Baseline wire version. Present since repo genesis (2026-04-21) as an inline literal in

`protocol-schemas.ts`; extracted into `version.ts` unchanged on 2026-05-04 (`2949171`).

The first externally-relevant version — there is no 2->3 bump in tracked history.

Established the still-current shape: `req`/`res`/`event` frame envelopes, the

`ConnectParams` -> `hello-ok` handshake with protocol negotiation, `snapshot` state sync,

and the founding method/event families: sessions, agent chat, cron, devices, nodes,

channels, config, commands, logs-chat, exec-approvals, plugin-approvals, secrets, push,

wizard. (v3 `hello-ok` carried `canvasHostUrl`; v4 replaced it — see above.)

Additive method/event/schema families added over time. Pure refactors, test-only, and

docs commits are omitted. The package was extracted from `src/gateway/protocol` to

`packages/gateway-protocol` on 2026-05-29 (#87797); paths before that date lived under

the old tree.

- Ship baseline families: frames/handshake, sessions, agent chat, cron, devices, nodes,

channels, config, commands, logs-chat, exec-approvals, plugin-approvals, secrets, push,

wizard, snapshot, primitives, agents-models-skills.

- Add WhatsApp `replyToMode` quoting (#62305).

- Add browser realtime Talk and transports — origin of the talk/voice families.

- Add Control UI PWA web push support (#44590).

- Add plugins and artifacts schema modules.

- Add OpenClaw SDK package and authenticated iOS background presence beacon (#73330).

- Add environments discovery RPCs (#74867) and task-ledger RPCs (#74847) — tasks family.

- Add unified Talk gateway sessions, realtime active-run control, and typed `sessionKey`

on the wake protocol.

- Add SDK `tools.invoke` RPC; extend cron with agentId filtering (#77602), run

diagnostics (#75928), and direct job lookup.

- Add Skill Workshop gateway methods: proposal files, revision requests, persisted origin.

- Add core session goals (#87469).

- Add heartbeat flag on agent event broadcast (#80610), warm-MCP effective inventory, and

plugin approval action metadata.

- Harden auth/device identity: bind approval access to requester metadata (#81380);

require approval for setup-code device pairing (#81292); scope Talk session to resolver.

- Introduce and revert transient protocol v5 (`07f05e9` / `ad155fb`).

Enhancement-only month (no new schema modules):

- Extend cron with command jobs, compact list responses (#93395), and an on-exit

schedule kind that fires when a watched command exits.

- Forward-port fast-Talks auto mode (#85104); add session workspace rail (#92856).

- Add terminal family: `terminal.*` RPC methods/events, detach/reattach with output

replay, `terminal.list`/`terminal.text`, and file uploads into terminals (#107364).

- Add managed git worktrees: lifecycle create/provision/snapshot/restore/GC (#100535),

new-session-in-worktree (#100788), session worktree targeting and branch listing

(#103432); add read-only `agents.workspace` browsing RPCs (#100738).

- Add audit family: metadata-only message audit events (#103903), native-search audit

correlation (#98704), and audit-activity schema.

- Add `tts.speak` returning synthesized audio inline (#100770).

- Add cooperative host suspension / gateway-suspend prepare/status/resume RPCs (#103618).

- Add durable approvals: persisted operator approvals (#103579), typed cross-surface

approval actions (#103679), approval-id, and the durable-approvals stack (#104837).

- Add cloud-workers stack: durable environments + lifecycle RPCs (#104401), worker bundle

+ SSH bootstrap + admission handshake (#104532), authenticated worker protocol with

minted credentials (#104688), durable transcript commit (#104809), live-event streaming

(#105275), inference proxy (#105719), and session placement/dispatch (#106332).

- Add session catalog: sessions-catalog + sessions-create with external-session

pagination unification (#104717).

- Add fs family: `sessions.files.set` hash-CAS writes (#104757) and gateway/node folder

browsing (#105114).

- Add node-hosted plugins — dynamic tools, MCP servers, skills (#90431) — plus node

invoke/presence protocol schemas.

- Add migrations family: log-migration protocol schemas and Codex/Claude memory import

(#106406).

- Add durable device rename for human-friendly device names (#94517).

- Add follow-up task suggestions (#102422) and task-suggestions schema.

- Add cron event triggers via polled condition-watcher scripts (#101195) and native

mobile Automations parity (#106355).

- Add system-agent conversational onboarding (#99935); rename `crestodian.*` methods to

`openclaw.chat` / `openclaw.setup.*` (2026-07-14, `a6a0716`).

- Add typed structured questions / `ask_user` with live option cards (#109922, #110242)

and the questions schema module.

- Add ui-command / screen-tool Control UI layout control and capability-gated

`show_widget` inline web chat widgets (#101840).

- Add direct watch/watchOS node connect to Gateway (#102893); widen node/probe protocol

acceptance to N-1 (#101109).

- Post-v4 changes are additive except: the transient v5 rename (reverted, net-zero) and

the 2026-07-14 `crestodian.*` -> `openclaw.*` method rename. The renamed feature was

introduced only 9 days earlier (2026-07-05, #99935), never left the v4 window, and

predates public publish, so no released method name changed under v4.

- `schema/types.ts` was removed 2026-07-11 (#103679); it re-exported compile-time type

aliases only and has no wire impact.

MIT License

Copyright (c) 2026 OpenClaw Foundation

Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal

in the Software without restriction, including without limitation the rights

to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all

copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

SOFTWARE.

Typed schemas, inferred TypeScript types, and runtime validators for the OpenClaw

Gateway WebSocket protocol.

The current wire protocol is version 4. General clients must use v4; authenticated

node clients and lightweight probes may use the N-1 window during rolling upgrades.

See the [Gateway protocol specification](https://docs.openclaw.ai/gateway/protocol)

for transport, authentication, roles, scopes, and complete frame examples.

Package versions follow the OpenClaw calendar release train:

`YYYY.M.PATCH`, with the same prerelease suffix when applicable. A package version

therefore identifies the OpenClaw source release that produced the schemas; it is

not the wire protocol number.

The wire protocol integer is versioned separately. Its current value is exported

as `PROTOCOL_VERSION` from `@openclaw/gateway-protocol/version`. Gateway protocol

changes are additive first. An incompatible wire change requires an explicit

protocol-version decision and coordinated client follow-through. See

[`CHANGELOG.md`](./CHANGELOG.md) for the wire and schema history.

npm install @openclaw/gateway-protocol

- `@openclaw/gateway-protocol` exports runtime validators, selected schemas, error

formatting, and their TypeScript types. This is the main TypeBox-backed entry.

- `@openclaw/gateway-protocol/schema` exports the TypeBox schema graph, including

the `ProtocolSchemas` registry used by generators.

- `@openclaw/gateway-protocol/frame-guards` exports dependency-free structural

guards for gateway event and response envelopes.

- `@openclaw/gateway-protocol/client-info` exports client ID, mode, and capability

registries plus normalization helpers.

- `@openclaw/gateway-protocol/connect-error-details` exports structured connect

error readers and recovery metadata.

- `@openclaw/gateway-protocol/gateway-error-details` exports helpers for reading

structured details from general gateway errors.

- `@openclaw/gateway-protocol/startup-unavailable` exports startup retry constants

and helpers.

- `@openclaw/gateway-protocol/version` exports the current and minimum accepted

protocol versions.

The `frame-guards`, `client-info`, `connect-error-details`, `gateway-error-details`,

`startup-unavailable`, and `version` entry points are TypeBox-free. Prefer them when

a browser bundle only needs envelope dispatch, handshake constants, or reconnect

policy. This also avoids runtime compilation in CSP-sensitive consumers. The root

and `schema` entry points provide the full validation surface and depend on TypeBox.

The compiled validators are callable type guards. Their `errors` property contains

the most recent validation errors.

import { formatValidationErrors, validateRequestFrame } from "@openclaw/gateway-protocol";

const frame: unknown = JSON.parse(inboundText);

if (!validateRequestFrame(frame)) {

throw new Error(formatValidationErrors(validateRequestFrame.errors));

}

console.log(frame.id, frame.method);

`validateRequestFrame` validates the request envelope. Dispatch code must also use

the validator for the selected method's `params`; the root entry point exports those

validators as `validate*Params` functions.

Use the lightweight guards when code only needs safe frame discrimination. They

check dispatch-critical envelope fields and intentionally allow additive payload

fields.

import { isGatewayEventFrame } from "@openclaw/gateway-protocol/frame-guards";

const frame: unknown = JSON.parse(inboundText);

if (isGatewayEventFrame(frame)) {

console.log(frame.event, frame.seq);

}

Protocol levels and client capabilities live in TypeBox-free entry points.

import { GATEWAY_CLIENT_CAPS } from "@openclaw/gateway-protocol/client-info";

import { MIN_CLIENT_PROTOCOL_VERSION, PROTOCOL_VERSION } from "@openclaw/gateway-protocol/version";

const handshake = {

minProtocol: MIN_CLIENT_PROTOCOL_VERSION,

maxProtocol: PROTOCOL_VERSION,

caps: [GATEWAY_CLIENT_CAPS.TOOL_EVENTS],

};

Nodes and probes use `MIN_NODE_PROTOCOL_VERSION` and

`MIN_PROBE_PROTOCOL_VERSION`, respectively. A capability advertises client support;

it does not grant authorization.

Several identifier names coexist because they identify different things:

- `key` is the established logical session selector used by most `sessions.*`

CRUD, send, subscription, patch, reset, delete, compaction, and usage methods.

A key can be canonicalized or resolved within an agent's session store.

- `sessionKey` names the same logical routing identity where the contract needs to

make that meaning explicit. `chat.*`, session file and diff APIs, transcript

branch/rewind/fork APIs, agent events, and channel delivery payloads use this

spelling.

- `sessionId` is the opaque stored transcript or runtime instance ID. Session

results may return it beside a key. Talk, terminal, worker, and selected channel

protocols also use `sessionId` for their own concrete session instances; do not

substitute a logical session key there.

Follow each method schema rather than converting fields based on their spelling.

`sessions.resolve` is the explicit bridge when a caller has a key, raw session ID,

label, or parent/agent scope.

The schema graph is strict by default, but roughly 60 fields intentionally use

`Type.Unknown()` passthroughs. The main clusters are transport-owned channel

payloads, logs-chat message and attachment passthrough, worker and node tool

arguments/results, and the dynamic `config.schema` response. Frame `params`,

`payload`, and error `details` are also open at the envelope layer because the

selected method, event, or error code owns their concrete shape.

Do not treat these fields as validated domain objects. Narrow them at their owner

boundary before reading nested values.

`protocol.schema.json` ships in the npm tarball as the generated machine-readable

contract. It contains the frame union, named schema definitions, and core method

metadata. It is generated during `prepack` and is not committed to the repository.

The `hello-ok.features.methods` list is conservative discovery, not a complete

enumeration of every callable method. It reflects the methods the connected

Gateway intentionally advertises. Core-internal, role-specific, plugin-provided,

or otherwise non-advertised methods can have valid schemas without appearing in

that list. Clients should use discovery to enable optional UI, not to reject an

otherwise documented method contract.