Gateway protocol

The Gateway WS protocol is the single control plane and node transport for OpenClaw. Operator and node clients (CLI, web UI, macOS app, iOS/Android nodes, headless nodes) connect over WebSocket and declare a role and scope at handshake time.

Transport and framing

• WebSocket, text frames, JSON payloads.
• First frame must be a connect request.
• Pre-connect frames are capped at 64 KiB (MAX_PREAUTH_PAYLOAD_BYTES). After handshake, follow hello-ok.policy.maxPayload and hello-ok.policy.maxBufferedBytes. With diagnostics enabled, oversized inbound frames and slow outbound buffers emit payload.large events before the gateway closes or drops the frame. These events carry surface, byte sizes, limits, and a safe reason code, never message bodies, attachment contents, raw frame bytes, tokens, cookies, or secrets.

Frame shapes:

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

Side-effecting methods require idempotency keys (see schema).

Handshake

Gateway sends a pre-connect challenge:

{  "type": "event",  "event": "connect.challenge",  "payload": { "nonce": "…", "ts": 1737264000000 }}

Client replies with connect:

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 4,    "maxProtocol": 4,    "client": {      "id": "cli",      "version": "1.2.3",      "platform": "macos",      "mode": "operator"    },    "role": "operator",    "scopes": ["operator.read", "operator.write"],    "caps": [],    "commands": [],    "permissions": {},    "auth": { "token": "…" },    "locale": "en-US",    "userAgent": "openclaw-cli/1.2.3",    "device": {      "id": "device_fingerprint",      "publicKey": "…",      "signature": "…",      "signedAt": 1737264000000,      "nonce": "…"    }  }}

Gateway responds with hello-ok:

{  "type": "res",  "id": "…",  "ok": true,  "payload": {    "type": "hello-ok",    "protocol": 4,    "server": { "version": "…", "connId": "…" },    "features": { "methods": ["…"], "events": ["…"] },    "snapshot": { "…": "…" },    "auth": {      "role": "operator",      "scopes": ["operator.read", "operator.write"]    },    "policy": {      "maxPayload": 26214400,      "maxBufferedBytes": 52428800,      "tickIntervalMs": 15000    }  }}

server, features, snapshot, policy, and auth are all required by HelloOkSchema (packages/gateway-protocol/src/schema/frames.ts). auth reports the negotiated role/scopes even when no device token is issued (shape above). pluginSurfaceUrls is optional and maps plugin surface names (e.g. canvas) to scoped hosted URLs; it may expire, so nodes call node.pluginSurface.refresh with { "surface": "canvas" } for a fresh entry. The deprecated canvasHostUrl / canvasCapability / node.canvas.capability.refresh path is not supported; use plugin surfaces.

While the gateway is still finishing startup sidecars, connect can return a retryable UNAVAILABLE error with details.reason: "startup-sidecars" and retryAfterMs. Retry within your connection budget instead of treating it as a terminal handshake failure.

When a device token is issued, hello-ok.auth adds it:

{  "auth": {    "deviceToken": "…",    "role": "operator",    "scopes": ["operator.read", "operator.write"]  }}

Built-in QR/setup-code bootstrap is a mobile handoff path. A successful baseline setup-code connect returns a primary node token plus one bounded operator token:

{  "auth": {    "deviceToken": "…",    "role": "node",    "scopes": [],    "deviceTokens": [      {        "deviceToken": "…",        "role": "operator",        "scopes": ["operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"]      }    ]  }}

This operator handoff is bounded on purpose: enough to start the mobile operator loop and native setup, including operator.talk.secrets for Talk config reads, but no pairing-mutation scopes and no operator.admin. Broader pairing/admin access needs a separate approved pairing or token flow. Persist hello-ok.auth.deviceTokens only when bootstrap auth ran over a trusted transport (wss:// or loopback/local pairing).

Trusted same-process backend clients (client.id: "gateway-client", client.mode: "backend") may omit device on direct loopback connections when authenticating with the shared gateway token/password. This path is reserved for internal control-plane RPCs (e.g. subagent session updates) and avoids stale CLI/device pairing baselines blocking local backend work. Remote, browser-origin, node, and explicit device-token/device-identity clients still go through normal pairing and scope-upgrade checks.

Worker role and closed protocol

Cloud workers use a dedicated loopback ingress through the gateway-owned, host-key-pinned SSH tunnel. It accepts only worker identity and never dispatches general auth, node events, operator RPCs, or plugin methods. A strict connect verifies a hash-at-rest, short-lived credential bound to the environment, bundle hash, owner epoch, RPC-set version, expiry, and one nullable session; it separately checks the current version and feature set. Success returns minimal worker-hello-ok; feature negotiation is independent of the general protocol version. Frames stay under 64 KiB. The closed allowlist contains worker.heartbeat and worker.transcript.commit for ordered semantic message batches. Transcript commits use owner-epoch fencing, a gateway-owned session binding, base-leaf compare-and-swap, and durable sequence replay; the gateway generates transcript entry and parent IDs through the normal session writer. Ownership and expiry are rechecked on each RPC.

Client capabilities

Operator clients may advertise optional capabilities in connect.params.caps:

• tool-events: accepts structured tool lifecycle events.
• inline-widgets: can render hosted inline widget tool results.

Client capabilities describe the connected client, not authorization. Agent tools may declare required capabilities; the Gateway omits those tools unless every requirement appears in the originating client's caps. Channel-originated runs have no Gateway client capabilities, so capability-gated tools are unavailable even when tool policy explicitly allows them.

Node connect example

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 4,    "maxProtocol": 4,    "client": {      "id": "ios-node",      "version": "1.2.3",      "platform": "ios",      "mode": "node"    },    "role": "node",    "scopes": [],    "caps": ["camera", "canvas", "screen", "location", "voice"],    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],    "permissions": { "camera.capture": true, "screen.record": false },    "auth": { "token": "…" },    "locale": "en-US",    "userAgent": "openclaw-ios/1.2.3",    "device": {      "id": "device_fingerprint",      "publicKey": "…",      "signature": "…",      "signedAt": 1737264000000,      "nonce": "…"    }  }}

Nodes declare capability claims at connect time:

• caps: high-level categories such as camera, canvas, screen, location, voice, talk.
• commands: command allowlist for invoke.
• permissions: granular toggles (e.g. screen.record, camera.capture).

The gateway treats these as claims and enforces server-side allowlists.

Roles and scopes

For the full operator scope model, approval-time checks, and shared-secret semantics, see Operator scopes.

Roles:

• operator: control-plane client (CLI/UI/automation).
• node: capability host (camera/screen/canvas/system.run).
• worker: cloud execution host on the dedicated, closed worker protocol.

Operator scopes (src/gateway/operator-scopes.ts), the full closed set:

• operator.read
• operator.write
• operator.admin
• operator.approvals
• operator.pairing
• operator.talk.secrets

talk.config with includeSecrets: true requires operator.talk.secrets (or operator.admin). When secrets are included, read the active Talk provider credential from talk.resolved.config.apiKey; talk.providers.<id>.apiKey stays source-shaped and may be a SecretRef object or a redacted string.

Plugin-registered gateway RPC methods may request their own operator scope, but these reserved core prefixes always resolve to operator.admin (src/shared/gateway-method-policy.ts): config.*, exec.approvals.*, wizard.*, update.*.

Method scope is only the first gate. Some slash commands reached through chat.send apply stricter command-level checks: persistent /config set and /config unset writes require operator.admin even for gateway clients that already hold a lower operator scope.

node.pair.approve has an extra approval-time scope check on top of the base method scope (operator.pairing), based on the pending request's declared commands (src/infra/node-pairing-authz.ts):

Caps/commands/permissions (node)

Nodes declare capability claims at connect time:

• caps: high-level capability categories such as camera, canvas, screen, location, voice, and talk.
• commands: command allowlist for invoke.
• permissions: granular toggles (e.g. screen.record, camera.capture).

The Gateway treats these as claims and enforces server-side allowlists. Connected nodes can publish optional agent-visible plugin or MCP tool descriptors with node.pluginTools.update after a successful connect or reconnect. Headless node hosts restart to apply declarative MCP inventory changes. This update method is the only publication path; plugin tool descriptors are not accepted in connect params. Each descriptor must use a provider-safe tool name and name a command in the node's current command allowlist. The Gateway trusts descriptor metadata from the paired node, filters descriptors outside the approved command surface, removes them when the node disconnects, and rejects operator attempts to mutate another node's catalog. Set gateway.nodes.pluginTools.enabled: false to ignore node-published descriptors.

Connected node hosts publish their complete skill replacement catalog with node.skills.update. This node-role method is the only node skill publication path; skills are not accepted in connect params. Each descriptor contains a safe name, description, and bounded SKILL.md content. The Gateway parses that content with the normal skills loader, includes it in agent skill snapshots while the node is connected, and removes it on disconnect. Set gateway.nodes.skills.enabled: false to ignore node-published skills.

Presence

• system-presence returns entries keyed by device identity, including deviceId, roles, and scopes, so UIs can show one row per device even when it connects as both operator and node.
• node.list includes optional lastSeenAtMs and lastSeenReason. Connected nodes report current connection time with reason connect; paired nodes can also report durable background presence via a trusted node event.

Node background alive event

Nodes call node.event with event: "node.presence.alive" to record that a paired node was alive during a background wake, without marking it connected:

{  "event": "node.presence.alive",  "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"Peter's iPhone\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}"}

trigger is a closed enum: background, silent_push, bg_app_refresh, significant_location, manual, connect. Unknown values normalize to background (src/shared/node-presence.ts). The event only persists for authenticated node device sessions; device-less or unpaired sessions return handled: false.

Successful gateways return a structured result:

{  "ok": true,  "event": "node.presence.alive",  "handled": true,  "reason": "persisted"}

Older gateways may return only { "ok": true } for node.event; treat that as an acknowledged RPC, not durable presence persistence.

Broadcast event scoping

Server-pushed broadcast events are scope-gated so pairing-scoped or node-only sessions do not passively receive session content (src/gateway/server-broadcast.ts):

• Chat, agent, and tool-result frames (streamed agent events, tool-result events) require at least operator.read. Sessions without it skip these frames entirely.
• Plugin-defined plugin.* broadcasts are gated to operator.write or operator.admin by default; explicit entries such as plugin.approval.requested / plugin.approval.resolved use operator.approvals instead.
• Status/transport events (heartbeat, presence, tick, connect/disconnect lifecycle) stay unrestricted so transport health is observable to every authenticated session.
• Unknown broadcast event families are scope-gated by default (fail-closed) unless a registered handler explicitly relaxes them.

Each client connection keeps its own per-client sequence number, so broadcasts stay monotonically ordered on that socket even when different clients see different scope-filtered subsets of the event stream.

RPC method families

hello-ok.features.methods is a conservative discovery list built from src/gateway/server-methods-list.ts plus loaded plugin/channel method exports — it is not a generated dump of every method, and some methods (for example push.test, web.login.start, web.login.wait, sessions.usage) are intentionally excluded from discovery even though they are real, callable methods. Treat this as feature discovery, not a full enumeration of src/gateway/server-methods/*.ts.

Common event families

• chat: UI chat updates such as chat.inject and other transcript-only chat events. In protocol v4, delta payloads carry deltaText; message remains the cumulative assistant snapshot. Non-prefix replacements set replace=true and use deltaText as the replacement text.
• session.message, session.operation, session.tool: transcript, in-flight session operation, and event-stream updates for a subscribed session.
• sessions.changed: session index or metadata changed.
• presence: system presence snapshot updates.
• tick: periodic keepalive/liveness event.
• health: gateway health snapshot update.
• heartbeat: heartbeat event stream update.
• cron: cron run/job change event.
• shutdown: gateway shutdown notification.
• node.pair.requested / node.pair.resolved: node pairing lifecycle.
• node.invoke.request: node invoke request broadcast.
• device.pair.requested / device.pair.resolved: paired-device lifecycle.
• voicewake.changed: wake-word trigger config changed.
• exec.approval.requested / exec.approval.resolved: exec approval lifecycle.
• plugin.approval.requested / plugin.approval.resolved: plugin approval lifecycle.

Node helper methods

Nodes may call skills.bins to fetch the current list of skill executables for auto-allow checks.

Audit ledger RPC

audit.activity.list gives operator clients a stable newest-first view of agent run, tool action, and opt-in message lifecycle metadata. It requires operator.read. Queries exclude records older than 30 days, and the shared SQLite ledger is capped at 100,000 records. Expired rows are deleted during Gateway startup, hourly maintenance, and later writes. See Audit history for the data model and privacy semantics.

• Params: optional exact agentId, sessionKey, or runId; optional kind ("agent_run", "tool_action", or "message"); optional status ("started", "succeeded", "failed", "cancelled", "timed_out", "blocked", or "unknown"); optional message direction ("inbound" or "outbound") and exact channel; optional inclusive after / before Unix-millisecond bounds; optional limit from 1 to 500; and optional string cursor from the preceding page.
• Result: { "events": AuditActivityEventV1[], "nextCursor"?: string }.

The named V1 result union has separate agent-run, tool-action, inbound-message, and outbound-message schemas. The eventType discriminator is respectively agent_run, tool_action, inbound_message, or outbound_message; kind and message direction remain available for filtering and display. Every event has integer schemaVersion: 1. Message identity references use the exact hmac-sha256:v1:<32 hex key id>:<64 hex digest> format; a channel-sender actor id uses the same format.

All variants require eventType, schemaVersion, eventId, sequence, sourceSequence, occurredAt, kind, action, status, actor, and redaction. Variant fields are:

The closed message enums are:

• conversationKind: direct, group, channel, or unknown.
• Inbound outcome: completed, skipped, or failed; optional reasonCode: duplicate, reply_operation_active, reply_operation_aborted, fast_abort, plugin_bound_handled, plugin_bound_unavailable, plugin_bound_declined, plugin_bound_error, before_dispatch_handled, acp_dispatch_completed, acp_dispatch_failed, acp_dispatch_empty, or acp_dispatch_aborted.
• Outbound outcome: sent, suppressed, failed, or unknown; optional reasonCode: cancelled_by_message_sending_hook, cancelled_by_reply_payload_sending_hook, empty_after_message_sending_hook, empty_after_reply_payload_sending_hook, or no_visible_payload. An adapter that returns no platform identity is unknown, because the external side effect cannot be disproved.
• deliveryKind: text, media, or other; failureStage: platform_send, queue, or unknown.

Terminal fields are correlated, not independently optional:

Each activity event includes a stable event id, monotonic ledger sequence, source event sequence, timestamp, actor, action, status, integer schemaVersion: 1, and redaction: "metadata_only". Run and tool records require agent and run provenance and may include session provenance. Message records may include agent and run ids, but intentionally never include sessionKey or sessionId; the sessionKey query filter therefore applies to run and tool rows only. Tool events may include tool call id and tool name.

Message records use message.inbound.processed or message.outbound.finished and add direction, channel, conversation kind, normalized outcome, and optional delivery kind, failure stage, duration, result count, reason code, and installation-local keyed account/conversation/message/target pseudonyms. These pseudonyms aid correlation but are not anonymization: the state database contains their key, while RPC and CLI exports do not. The ledger does not store prompts, message bodies, tool arguments, tool results, command output, or raw error text. Run/tool sessionKey values remain raw correlation metadata and can embed platform account or peer ids; message records omit session keys.

For inbound rows, durationMs measures core dispatch through its terminal and resultCount counts finalized queued tool, block, and reply payloads. For outbound rows, durationMs spans delivery ownership through acknowledgement, dead letter, or reconciliation (including queued wait time), and resultCount counts identified physical platform sends. deliveryKind, when present, describes the effective payload after hooks and rendering; suppressed or crash-ambiguous rows omit it.

Current message coverage includes accepted inbound messages that reach core dispatch, including core duplicate/terminal outcomes. Outbound coverage writes one terminal row per original logical reply payload that reaches shared durable delivery; chunking and adapter fan-out are aggregated in resultCount. Queued retryable or ambiguous sends are recorded only after acknowledgement, dead letter, or reconciliation. Plugin-local and direct-send paths that bypass those shared boundaries are not yet covered. The bounded worker queue is best-effort and may drop records on failure or saturation, so this surface is not a lossless compliance archive.

Recording is on by default and controlled by audit.enabled. Message recording is separately controlled by audit.messages and defaults to "off". When recording is disabled, audit.activity.list keeps serving records written earlier until they expire.

The shipped audit.list request, result, and AuditEvent schemas remain unchanged and return only agent-run and tool-action records. New operator clients should call audit.activity.list when the Gateway advertises it. Older Gateways may report either unknown method: audit.activity.list or, because authorization preceded method lookup in shipped versions, missing scope: operator.admin to a read-scoped request. Treat the latter as method absence only when the method was not advertised. A client may then retry audit.list only when its filters do not require message kind, direction, or channel support.

Use openclaw audit for text queries and bounded JSON exports.

Task ledger RPCs

Operator clients inspect and cancel gateway background task records through the task ledger RPCs (packages/gateway-protocol/src/schema/tasks.ts). These return sanitized task summaries, not raw runtime state.

• tasks.list requires operator.read.
  • Params: optional status ("queued", "running", "completed", "failed", "cancelled", or "timed_out") or an array of those statuses, optional agentId, optional sessionKey, optional limit from 1 to 500, and optional string cursor.
  • Result: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get requires operator.read.
  • Params: { "taskId": string }.
  • Result: { "task": TaskSummary }.
  • Missing task ids return the gateway not-found error shape.
• tasks.cancel requires operator.write.
  • Params: { "taskId": string, "reason"?: string }.
  • Result: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
  • found reports whether the ledger had a matching task. cancelled reports whether the runtime accepted or recorded cancellation.

TaskSummary includes id, status, and optional metadata: kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, timestamps, progress, terminal summary, and sanitized error text. agentId identifies the agent executing the task; sessionKey and ownerKey preserve requester and control context.

Operator helper methods

• commands.list (operator.read) fetches the runtime command inventory for an agent.
  • agentId is optional; omit it to read the default agent workspace.
  • scope controls which surface the primary name targets: text returns the primary text command token without the leading /; native and the default both path return provider-aware native names when available.
  • textAliases carries exact slash aliases such as /model and /m.
  • nativeName carries the provider-aware native command name when one exists.
  • provider is optional and only affects native naming plus native plugin command availability.
  • includeArgs=false omits serialized argument metadata from the response.
• tools.catalog (operator.read) fetches the runtime tool catalog for an agent. The response includes grouped tools and provenance metadata:
  • source: core or plugin
  • pluginId: plugin owner when source="plugin"
  • optional: whether a plugin tool is optional
• tools.effective (operator.read) fetches the runtime-effective tool inventory for a session.
  • sessionKey is required.
  • The gateway derives trusted runtime context from the session server-side instead of accepting caller-supplied auth or delivery context.
  • The response is a session-scoped server-derived projection of the active inventory, including core, plugin, channel, and already-discovered MCP server tools.
  • tools.effective is read-only for MCP: it may project a warm session MCP catalog through the final tool policy, but does not create MCP runtimes, connect transports, or issue tools/list. If no matching warm catalog exists, the response may include a notice such as mcp-not-yet-connected, mcp-not-yet-listed, or mcp-stale-catalog.
  • Effective tool entries use source="core", source="plugin", source="channel", or source="mcp".
• tools.invoke (operator.write) invokes one available tool through the same gateway policy path as /tools/invoke.
  • name is required. args, sessionKey, agentId, confirm, and idempotencyKey are optional.
  • If both sessionKey and agentId are present, the resolved session agent must match agentId.
  • Owner-only core wrappers such as cron, gateway, and nodes require owner/admin identity (operator.admin) even though tools.invoke itself is operator.write.
  • The response is an SDK-facing envelope with ok, toolName, optional output, and typed error fields. Approval or policy refusals return ok:false in the payload rather than bypassing the gateway tool policy pipeline.
• skills.status (operator.read) fetches the visible skill inventory for an agent.
  • agentId is optional; omit it to read the default agent workspace.
  • The response includes eligibility, missing requirements, config checks, and sanitized install options without exposing raw secret values.
• skills.search and skills.detail (operator.read) return ClawHub discovery metadata.
• skills.upload.begin, skills.upload.chunk, and skills.upload.commit (operator.admin) stage a private skill archive before installing it. This is a separate admin upload path for trusted clients, not the normal ClawHub skill install flow, and is disabled by default unless skills.install.allowUploadedArchives is enabled.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) creates an upload bound to that slug and force value.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) appends bytes at the exact decoded offset.
  • skills.upload.commit({ uploadId, sha256? }) verifies the final size and SHA-256. Commit only finalizes the upload; it does not install the skill.
  • Uploaded skill archives are zip archives containing a SKILL.md root. The archive's internal directory name never selects the install target.
• skills.install (operator.admin) has three modes:
  • ClawHub mode: { source: "clawhub", slug, version?, force? } installs a skill folder into the default agent workspace skills/ directory.
  • Upload mode: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } installs a committed upload into the default agent workspace skills/<slug> directory. The slug and force value must match the original skills.upload.begin request. Rejected unless skills.install.allowUploadedArchives is enabled; the setting does not affect ClawHub installs.
  • Gateway installer mode: { name, installId, timeoutMs? } runs a declared metadata.openclaw.install action on the gateway host. Older clients may still send dangerouslyForceUnsafeInstall; this field is deprecated, accepted only for protocol compatibility, and ignored. Use security.installPolicy for operator-owned install decisions.
• skills.update (operator.admin) has two modes:
  • ClawHub mode updates one tracked slug or all tracked ClawHub installs in the default agent workspace.
  • Config mode patches skills.entries.<skillKey> values such as enabled, apiKey, and env.

models.list views

models.list accepts an optional view parameter (src/agents/model-catalog-visibility.ts):

• Omitted or "default": if agents.defaults.models is configured, the response is the allowed catalog, including dynamically discovered models for provider/* entries. Otherwise the response is the full gateway catalog.
• "configured": picker-sized behavior. If agents.defaults.models is configured, it still wins, including provider-scoped discovery for provider/* entries. Without an allowlist, the response uses explicit models.providers.<provider>.models entries, falling back to the full catalog only when no configured model rows exist.
• "provider-config": source-authored models.providers.*.models inventory, independent of picker allowlists. Rows include public model capabilities and route-aware availability, but omit provider endpoints, auth material, and runtime request configuration.
• "all": full gateway catalog, bypassing agents.defaults.models. Use for diagnostics/discovery UIs, not normal model pickers.

Exec approvals

• When an exec request needs approval, the gateway broadcasts exec.approval.requested.
• Operator clients resolve by calling exec.approval.resolve (requires operator.approvals).
• For host=node, exec.approval.request must include systemRunPlan (canonical argv/cwd/rawCommand/session metadata). Requests missing systemRunPlan are rejected.
• After approval, forwarded node.invoke system.run calls reuse that canonical systemRunPlan as the authoritative command/cwd/session context.
• If a caller mutates command, rawCommand, cwd, agentId, or sessionKey between prepare and the final approved system.run forward, the gateway rejects the run instead of trusting the mutated payload.

Agent delivery fallback

• agent requests can include deliver=true to request outbound delivery.
• bestEffortDeliver=false (the default) keeps strict behavior: unresolved or internal-only delivery targets return INVALID_REQUEST.
• bestEffortDeliver=true allows fallback to session-only execution when no external deliverable route can be resolved (for example internal/webchat sessions or ambiguous multi-channel configs).
• Final agent results may include result.deliveryStatus when delivery was requested, using the same sent, suppressed, partial_failed, and failed statuses documented for openclaw agent --json --deliver.

Versioning

• PROTOCOL_VERSION, MIN_CLIENT_PROTOCOL_VERSION, MIN_NODE_PROTOCOL_VERSION, and MIN_PROBE_PROTOCOL_VERSION live in packages/gateway-protocol/src/version.ts.
• Clients send minProtocol + maxProtocol. Operator and UI clients must include the current protocol in that range; current clients and servers run protocol v4.
• Authenticated clients with both role: "node" and client.mode: "node" may use the N-1 node protocol (currently v3). Lightweight restart probes use the same N-1 window. Device auth, pairing, scopes, command policy, and exec approvals are unchanged by this compatibility window. Plugin-owned node capabilities and commands are withheld until the node upgrades to the current protocol because their hosted surfaces are not part of the N-1 contract.
• Schemas and models are generated from TypeBox definitions:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

Client constants

The reference client implementation lives in packages/gateway-client/src/ (OpenClaw wraps it via the thin src/gateway/client.ts facade). These defaults are stable across protocol v4 and are the expected baseline for third-party clients.

The server advertises the effective policy.tickIntervalMs, policy.maxPayload, and policy.maxBufferedBytes in hello-ok; clients should honor those values rather than the pre-handshake defaults.

The reference client lets finite requests own their configured deadline when every pending request has one. An expectFinal request without a finite timeoutMs, any request with timeoutMs: null, or a mix of finite and unbounded requests keeps the tick watchdog active. If inbound events and responses remain silent past the tick-timeout threshold, the client closes the socket with code 4000, rejects every pending request, and reconnects. It does not replay rejected requests after reconnecting.

Auth

• Shared-secret gateway auth uses connect.params.auth.token or connect.params.auth.password, depending on the configured gateway.auth.mode ("none" | "token" | "password" | "trusted-proxy").
• Identity-bearing modes such as Tailscale Serve (gateway.auth.allowTailscale: true) or non-loopback gateway.auth.mode: "trusted-proxy" satisfy the connect auth check from request headers instead of connect.params.auth.*.
• Private-ingress gateway.auth.mode: "none" skips shared-secret connect auth entirely; do not expose that mode on public/untrusted ingress.
• After pairing, the gateway issues a device token scoped to the connection role + scopes, returned in hello-ok.auth.deviceToken. Clients should persist it after any successful connect.
• Reconnecting with that stored device token should also reuse the stored approved scope set for that token. This preserves read/probe/status access already granted and avoids silently collapsing reconnects to a narrower implicit admin-only scope.
• Client-side connect auth assembly (selectConnectAuth in packages/gateway-client/src/client.ts):
  • auth.password is orthogonal and always forwarded when set.
  • auth.token is populated in priority order: explicit shared token first, then an explicit deviceToken, then a stored per-device token (keyed by deviceId + role).
  • auth.bootstrapToken is sent only when none of the above resolved auth.token. A shared token or any resolved device token suppresses it.
  • Auto-promotion of a stored device token on the one-shot AUTH_TOKEN_MISMATCH retry is gated to trusted endpoints only: loopback, or wss:// with a pinned tlsFingerprint. Public wss:// without pinning does not qualify.
• Built-in setup-code bootstrap returns the primary node hello-ok.auth.deviceToken plus a bounded operator token in hello-ok.auth.deviceTokens for trusted mobile handoff. The operator token includes operator.talk.secrets for native Talk configuration reads, but excludes pairing-mutation scopes and operator.admin.
• While a non-baseline setup-code bootstrap waits for approval, PAIRING_REQUIRED details include recommendedNextStep: "wait_then_retry", retryable: true, and pauseReconnect: false. Keep reconnecting with the same bootstrap token until the request is approved or the token becomes invalid.
• Persist hello-ok.auth.deviceTokens only when the connect used bootstrap auth on a trusted transport such as wss:// or loopback/local pairing.
• If a client supplies an explicit deviceToken or explicit scopes, that caller-requested scope set remains authoritative; cached scopes are only reused when the client is reusing the stored per-device token.
• Device tokens can be rotated/revoked via device.token.rotate and device.token.revoke (requires operator.pairing). Rotating or revoking a node or other non-operator role also requires operator.admin.
• device.token.rotate returns rotation metadata. It echoes the replacement bearer token only for same-device calls already authenticated with that device token, so token-only clients can persist their replacement before reconnecting. Shared/admin rotations do not echo the bearer token.
• Token issuance, rotation, and revocation stay bounded to the approved role set recorded in that device's pairing entry; token mutation cannot expand or target a device role that pairing approval never granted.
• For paired-device token sessions, device management is self-scoped unless the caller also has operator.admin: non-admin callers can manage only the operator token for their own device entry. Node and other non-operator token management is admin-only, even for the caller's own device.
• device.token.rotate and device.token.revoke also check the target operator token scope set against the caller's current session scopes. Non-admin callers cannot rotate or revoke a broader operator token than they already hold.
• Auth failures include error.details.code plus recovery hints:
  • error.details.canRetryWithDeviceToken (boolean)
  • error.details.recommendedNextStep: one of retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration (packages/gateway-protocol/src/connect-error-details.ts).
• Client behavior for AUTH_TOKEN_MISMATCH:
  • Trusted clients may attempt one bounded retry with a cached per-device token.
  • If that retry fails, stop automatic reconnect loops and surface operator action guidance.
• AUTH_SCOPE_MISMATCH means the device token was recognized but does not cover the requested role/scopes. Do not present this as a bad token; prompt the operator to re-pair or approve the narrower/broader scope contract.

Device identity and pairing

• Nodes should include a stable device identity (device.id) derived from a keypair fingerprint.
• Gateways issue tokens per device + role.
• Pairing approvals are required for new device IDs unless local auto-approval is enabled.
• Pairing auto-approval is centered on direct local loopback connects.
• OpenClaw also has a narrow backend/container-local self-connect path for trusted shared-secret helper flows.
• Same-host tailnet or LAN connects are still treated as remote for pairing and require approval.
• WS clients normally include device identity during connect (operator + node). The only device-less operator exceptions are explicit trust paths:
  • gateway.controlUi.allowInsecureAuth=true for localhost-only insecure HTTP compatibility.
  • successful gateway.auth.mode: "trusted-proxy" operator Control UI auth.
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (break-glass, severe security downgrade).
  • direct-loopback gateway-client backend RPCs on the reserved internal helper path.
• Omitting device identity has scope consequences. When a device-less operator connection is allowed through an explicit trust path, OpenClaw still clears self-declared scopes to an empty set unless that path has a named scope-preservation exception. Scope-gated methods then fail with missing scope.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true is a Control UI break-glass scope-preservation path. It does not grant scopes to arbitrary custom backend or CLI-shaped WebSocket clients.
• The reserved direct-loopback gateway-client backend helper path preserves scopes only for internal local control-plane RPCs; custom backend IDs do not receive this exception.
• All connections must sign the server-provided connect.challenge nonce.

Device auth migration diagnostics

For legacy clients that still use pre-challenge signing behavior, connect returns DEVICE_AUTH_* detail codes under error.details.code with a stable error.details.reason.

Common migration failures:

Migration target:

• Always wait for connect.challenge.
• Sign the v2 payload that includes the server nonce.
• Send the same nonce in connect.params.device.nonce.
• Preferred signature payload is v3 (buildDeviceAuthPayloadV3 in packages/gateway-client/src/device-auth.ts), which binds platform and deviceFamily in addition to device/client/role/scopes/token/nonce fields.
• Legacy v2 signatures remain accepted for compatibility, but paired-device metadata pinning still controls command policy on reconnect.

TLS and pinning

• TLS is supported for WS connections (gateway.tls config).
• Clients may optionally pin the gateway cert fingerprint via gateway.remote.tlsFingerprint or CLI --tls-fingerprint.

Scope

This protocol exposes the full gateway API: status, channels, models, chat, agent, sessions, nodes, approvals, and more. The exact surface is defined by the TypeBox schemas re-exported from packages/gateway-protocol/src/schema.ts.

Related

• Bridge protocol
• Gateway runbook