npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@openclaw/gateway-protocol

v2026.11.6

Published

Typed schemas and runtime validators for the OpenClaw Gateway WebSocket protocol

Readme

@openclaw/gateway-protocol

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 connectivity checks may use the N-1 window during rolling upgrades. See the Gateway protocol specification for transport, authentication, roles, scopes, and complete frame examples.

Versioning

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 for the wire and schema history.

Install

Use the verified stable release with an exact pin:

npm install --save-exact @openclaw/[email protected]

This release declares Node.js >=22.19.0. See the installation guide for the matching client package, package/wire-version rules, and recovery from reserved 0.0.0 artifacts. Test it with the Gateway version you deploy; the root openclaw CLI has its own package versions and dist-tags.

Entry points

  • @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 loading the full schema and diagnostic graph. The root and schema entry points provide the full validation surface and depend on TypeBox; their fixed validators do not require string code generation.

Validate an inbound frame

The compiled validators are callable type guards. Their errors property contains the most recent validation errors.

Fixed protocol checks are generated from their canonical schemas during development and shipped as JavaScript; starting a client or validating its first request does not compile validator source. Invalid input still receives the same schema-based diagnostics, and each validator exposes its original schema. After changing a protocol schema, run pnpm gateway:validators:gen from the workspace root; pnpm gateway:validators:check verifies that the checked-in validators are current.

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.

External lifecycle controllers can validate suspension responses with validateGatewaySuspendPrepareResult and validateGatewaySuspendStatusResult. These use the shared result schemas without changing the payload. Preserve optional writeCustody: absence means unknown custody, not an empty list. Phase names are open strings; consumers must not discard an unfamiliar owner phase. Validation does not authorize a stop or replace lease, process-identity, and readiness checks owned by the controller.

Leave includeLifecycle unset when using older published status validators. Request includeLifecycle: true only with a validator that supports ownerId and phase.

Guard an event without TypeBox

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

Build handshake version and capability fields

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 diagnostic clients use MIN_NODE_PROTOCOL_VERSION and MIN_PROBE_PROTOCOL_VERSION, respectively. A capability advertises client support; it does not grant authorization.

Contract notes

Retired worker tool imports

The WorkerSessionsSpawn*, WorkerSessionsSend*, WorkerSessionTool*, WorkerPortal*, and WorkerPresence* schemas, types, root validators, and associated feature/limit constants published in 2026.9.6 and 2026.9.7 remain available for decoding older data. They do not register or advertise the retired worker RPCs. Current workers use the prepared tool surface and worker.gatewayTool transport; migrate integrations to WorkerGatewayTool*. These imports can be removed only in an explicitly announced breaking package API release after consumer migration.

Session identifiers

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, Control UI short ID, or parent/agent scope.

Intentionally open fields

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.

Machine-readable schema

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. Download it as a file; @openclaw/gateway-protocol/protocol.schema.json is not an exported package import subpath.

Method discovery

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.