Gateway protocol

​

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.

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

​

Handshake

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

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

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

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

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

​

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": "…"
    }
  }
}

• 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).

​

Roles and scopes

• operator: control-plane client (CLI/UI/automation).
• node: capability host (camera/screen/canvas/system.run).

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

​

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

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

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

​

Broadcast event scoping

• 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.

​

RPC method families

​

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

​

Audit ledger RPC

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

​

Task ledger RPCs

• 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.

​

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

• 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.
• "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

​

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

• 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

​

Related

• Bridge protocol
• Gateway runbook