Gateway protocol

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

Transport

• WebSocket, text frames with JSON payloads.
• First frame must be a
  text

  Copy

  connect
  request.
• Pre-connect frames are capped at 64 KiB. After a successful handshake, clients should follow the
  text

  Copy

  hello-ok.policy.maxPayload
  and
  text

  Copy

  hello-ok.policy.maxBufferedBytes
  limits. With diagnostics enabled, oversized inbound frames and slow outbound buffers emit
  text

  Copy

  payload.large
  events before the gateway closes or drops the affected frame. These events keep sizes, limits, surfaces, and safe reason codes. They do not keep the message body, attachment contents, raw frame body, tokens, cookies, or secret values.

Handshake (connect)

Gateway → Client (pre-connect challenge):

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

Client → Gateway:

json
Copy
{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 3,
    "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 → Client:

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

While the Gateway is still finishing startup sidecars, the

request can return a retryable error with set to and . Clients should retry that response within their overall connection budget instead of surfacing it as a terminal handshake failure.

, , , and are all required by the schema (). is also required and reports the negotiated role/scopes. is optional.

When no device token is issued,

reports the negotiated permissions without token fields:

json
Copy
{
  "auth": {
    "role": "operator",
    "scopes": ["operator.read", "operator.write"]
  }
}

Trusted same-process backend clients (

, ) may omit on direct loopback connections when they authenticate with the shared gateway token/password. This path is reserved for internal control-plane RPCs and keeps stale CLI/device pairing baselines from blocking local backend work such as subagent session updates. Remote clients, browser-origin clients, node clients, and explicit device-token/device-identity clients still use the normal pairing and scope-upgrade checks.

When a device token is issued,

also includes:

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

During trusted bootstrap handoff,

may also include additional bounded role entries in :

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

For the built-in node/operator bootstrap flow, the primary node token stays

and any handed-off operator token stays bounded to the bootstrap operator allowlist (, , , ). Bootstrap scope checks stay role-prefixed: operator entries only satisfy operator requests, and non-operator roles still need scopes under their own role prefix.

Node example

json
Copy
{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 3,
    "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": "…"
    }
  }
}

Framing

• Request:
  text

  Copy

  {type:"req", id, method, params}
• Response:
  text

  Copy

  {type:"res", id, ok, payload|error}
• Event:
  text

  Copy

  {type:"event", event, payload, seq?, stateVersion?}

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

Roles + scopes

Roles

• text

  Copy

  operator
  = control plane client (CLI/UI/automation).
• text

  Copy

  node
  = capability host (camera/screen/canvas/system.run).

Scopes (operator)

Common scopes:

• text

  Copy

  operator.read
• text

  Copy

  operator.write
• text

  Copy

  operator.admin
• text

  Copy

  operator.approvals
• text

  Copy

  operator.pairing
• text

  Copy

  operator.talk.secrets

with requires (or ).

Plugin-registered gateway RPC methods may request their own operator scope, but reserved core admin prefixes (

, , , ) always resolve to .

Method scope is only the first gate. Some slash commands reached through

apply stricter command-level checks on top. For example, persistent and writes require .

also has an extra approval-time scope check on top of the base method scope:

• commandless requests:
  text

  Copy

  operator.pairing
• requests with non-exec node commands:
  text

  Copy

  operator.pairing
  +
  text

  Copy

  operator.write
• requests that include
  text

  Copy

  system.run
  ,
  text

  Copy

  system.run.prepare
  , or
  text

  Copy

  system.which
  :
  text

  Copy

  operator.pairing
  +
  text

  Copy

  operator.admin

Caps/commands/permissions (node)

Nodes declare capability claims at connect time:

• text

  Copy

  caps
  : high-level capability categories.
• text

  Copy

  commands
  : command allowlist for invoke.
• text

  Copy

  permissions
  : granular toggles (e.g.
  text

  Copy

  screen.record
  ,
  text

  Copy

  camera.capture
  ).

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

Presence

• text

  Copy

  system-presence
  returns entries keyed by device identity.
• Presence entries include
  text

  Copy

  deviceId
  ,
  text

  Copy

  roles
  , and
  text

  Copy

  scopes
  so UIs can show a single row per device even when it connects as both operator and node.
• text

  Copy

  node.list
  includes optional
  text

  Copy

  lastSeenAtMs
  and
  text

  Copy

  lastSeenReason
  fields. Connected nodes report their current connection time as
  text

  Copy

  lastSeenAtMs
  with reason
  text

  Copy

  connect
  ; paired nodes can also report durable background presence when a trusted node event updates their pairing metadata.

Node background alive event

Nodes may call

with to record that a paired node was alive during a background wake without marking it connected.

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

is a closed enum: , , , , , or . Unknown trigger strings are normalized to by the gateway before persistence. The event is durable only for authenticated node device sessions; device-less or unpaired sessions return .

Successful gateways return a structured result:

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

Older gateways may still return

for ; clients should treat that as an acknowledged RPC, not as durable presence persistence.

Broadcast event scoping

Server-pushed WebSocket broadcast events are scope-gated so that pairing-scoped or node-only sessions do not passively receive session content.

• Chat, agent, and tool-result frames (including streamed
  text

  Copy

  agent
  events and tool call results) require at least
  text

  Copy

  operator.read
  . Sessions without
  text

  Copy

  operator.read
  skip these frames entirely.
• Plugin-defined
  text

  Copy

  plugin.*
  broadcasts are gated to
  text

  Copy

  operator.write
  or
  text

  Copy

  operator.admin
  , depending on how the plugin registered them.
• Status and transport events (
  text

  Copy

  heartbeat
  ,
  text

  Copy

  presence
  ,
  text

  Copy

  tick
  , connect/disconnect lifecycle, etc.) remain unrestricted so transport health stays 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 preserve monotonic ordering on that socket even when different clients see different scope-filtered subsets of the event stream.

Common RPC method families

The public WS surface is broader than the handshake/auth examples above. This is not a generated dump —

is a conservative discovery list built from plus loaded plugin/channel method exports. Treat it as feature discovery, not a full enumeration of .

System and identity

Models and usage

Channels and login helpers

Messaging and logs

Talk and TTS

Secrets, config, update, and wizard

Agent and workspace helpers

Session control

Device pairing and device tokens

Node pairing, invoke, and pending work

Approval families

Automation, skills, and tools

Common event families

• text

  Copy

  chat
  : UI chat updates such as
  text

  Copy

  chat.inject
  and other transcript-only chat events.
• text

  Copy

  session.message
  and
  text

  Copy

  session.tool
  : transcript/event-stream updates for a subscribed session.
• text

  Copy

  sessions.changed
  : session index or metadata changed.
• text

  Copy

  presence
  : system presence snapshot updates.
• text

  Copy

  tick
  : periodic keepalive / liveness event.
• text

  Copy

  health
  : gateway health snapshot update.
• text

  Copy

  heartbeat
  : heartbeat event stream update.
• text

  Copy

  cron
  : cron run/job change event.
• text

  Copy

  shutdown
  : gateway shutdown notification.
• text

  Copy

  node.pair.requested
  /
  text

  Copy

  node.pair.resolved
  : node pairing lifecycle.
• text

  Copy

  node.invoke.request
  : node invoke request broadcast.
• text

  Copy

  device.pair.requested
  /
  text

  Copy

  device.pair.resolved
  : paired-device lifecycle.
• text

  Copy

  voicewake.changed
  : wake-word trigger config changed.
• text

  Copy

  exec.approval.requested
  /
  text

  Copy

  exec.approval.resolved
  : exec approval lifecycle.
• text

  Copy

  plugin.approval.requested
  /
  text

  Copy

  plugin.approval.resolved
  : plugin approval lifecycle.

Node helper methods

• Nodes may call
  text

  Copy

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

Operator helper methods

• Operators may call
  text

  Copy

  commands.list
  (
  text

  Copy

  operator.read
  ) to fetch the runtime command inventory for an agent.
  • text

    Copy

    agentId
    is optional; omit it to read the default agent workspace.
  • text

    Copy

    scope
    controls which surface the primary
    text

    Copy

    name
    targets:
    • text

      Copy

      text
      returns the primary text command token without the leading
      text

      Copy

      /
    • text

      Copy

      native
      and the default
      text

      Copy

      both
      path return provider-aware native names when available
  • text

    Copy

    textAliases
    carries exact slash aliases such as
    text

    Copy

    /model
    and
    text

    Copy

    /m
    .
  • text

    Copy

    nativeName
    carries the provider-aware native command name when one exists.
  • text

    Copy

    provider
    is optional and only affects native naming plus native plugin command availability.
  • text

    Copy

    includeArgs=false
    omits serialized argument metadata from the response.
• Operators may call
  text

  Copy

  tools.catalog
  (
  text

  Copy

  operator.read
  ) to fetch the runtime tool catalog for an agent. The response includes grouped tools and provenance metadata:
  • text

    Copy

    source
    :
    text

    Copy

    core
    or
    text

    Copy

    plugin
  • text

    Copy

    pluginId
    : plugin owner when
    text

    Copy

    source="plugin"
  • text

    Copy

    optional
    : whether a plugin tool is optional
• Operators may call
  text

  Copy

  tools.effective
  (
  text

  Copy

  operator.read
  ) to fetch the runtime-effective tool inventory for a session.
  • text

    Copy

    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 session-scoped and reflects what the active conversation can use right now, including core, plugin, and channel tools.
• Operators may call
  text

  Copy

  skills.status
  (
  text

  Copy

  operator.read
  ) to fetch the visible skill inventory for an agent.
  • text

    Copy

    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.
• Operators may call
  text

  Copy

  skills.search
  and
  text

  Copy

  skills.detail
  (
  text

  Copy

  operator.read
  ) for ClawHub discovery metadata.
• Operators may call
  text

  Copy

  skills.install
  (
  text

  Copy

  operator.admin
  ) in two modes:
  • ClawHub mode:
    text

    Copy

    { source: "clawhub", slug, version?, force? }
    installs a skill folder into the default agent workspace
    text

    Copy

    skills/
    directory.
  • Gateway installer mode:
    text

    Copy

    { name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }
    runs a declared
    text

    Copy

    metadata.openclaw.install
    action on the gateway host.
• Operators may call
  text

  Copy

  skills.update
  (
  text

  Copy

  operator.admin
  ) in two modes:
  • ClawHub mode updates one tracked slug or all tracked ClawHub installs in the default agent workspace.
  • Config mode patches
    text

    Copy

    skills.entries.<skillKey>
    values such as
    text

    Copy

    enabled
    ,
    text

    Copy

    apiKey
    , and
    text

    Copy

    env
    .

text

Copy

models.list

views

accepts an optional parameter:

• Omitted or
  text

  Copy

  "default"
  : current runtime behavior. If
  text

  Copy

  agents.defaults.models
  is configured, the response is the allowed catalog; otherwise the response is the full Gateway catalog.
• text

  Copy

  "configured"
  : picker-sized behavior. If
  text

  Copy

  agents.defaults.models
  is configured, it still wins. Otherwise the response uses explicit
  text

  Copy

  models.providers.*.models
  entries, falling back to the full catalog only when no configured model rows exist.
• text

  Copy

  "all"
  : full Gateway catalog, bypassing
  text

  Copy

  agents.defaults.models
  . Use this for diagnostics and discovery UIs, not normal model pickers.

Exec approvals

• When an exec request needs approval, the gateway broadcasts
  text

  Copy

  exec.approval.requested
  .
• Operator clients resolve by calling
  text

  Copy

  exec.approval.resolve
  (requires
  text

  Copy

  operator.approvals
  scope).
• For
  text

  Copy

  host=node
  ,
  text

  Copy

  exec.approval.request
  must include
  text

  Copy

  systemRunPlan
  (canonical
  text

  Copy

  argv
  /
  text

  Copy

  cwd
  /
  text

  Copy

  rawCommand
  /session metadata). Requests missing
  text

  Copy

  systemRunPlan
  are rejected.
• After approval, forwarded
  text

  Copy

  node.invoke system.run
  calls reuse that canonical
  text

  Copy

  systemRunPlan
  as the authoritative command/cwd/session context.
• If a caller mutates
  text

  Copy

  command
  ,
  text

  Copy

  rawCommand
  ,
  text

  Copy

  cwd
  ,
  text

  Copy

  agentId
  , or
  text

  Copy

  sessionKey
  between prepare and the final approved
  text

  Copy

  system.run
  forward, the gateway rejects the run instead of trusting the mutated payload.

Agent delivery fallback

• text

  Copy

  agent
  requests can include
  text

  Copy

  deliver=true
  to request outbound delivery.
• text

  Copy

  bestEffortDeliver=false
  keeps strict behavior: unresolved or internal-only delivery targets return
  text

  Copy

  INVALID_REQUEST
  .
• text

  Copy

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

Versioning

• text

  Copy

  PROTOCOL_VERSION
  lives in
  text

  Copy

  src/gateway/protocol/schema/protocol-schemas.ts
  .
• Clients send
  text

  Copy

  minProtocol
  +
  text

  Copy

  maxProtocol
  ; the server rejects mismatches.
• Schemas + models are generated from TypeBox definitions:
  • text

    Copy

    pnpm protocol:gen
  • text

    Copy

    pnpm protocol:gen:swift
  • text

    Copy

    pnpm protocol:check

Client constants

The reference client in

uses these defaults. Values are stable across protocol v3 and are the expected baseline for third-party clients.

The server advertises the effective

, , and in ; clients should honor those values rather than the pre-handshake defaults.

Auth

• Shared-secret gateway auth uses
  text

  Copy

  connect.params.auth.token
  or
  text

  Copy

  connect.params.auth.password
  , depending on the configured auth mode.
• Identity-bearing modes such as Tailscale Serve (
  text

  Copy

  gateway.auth.allowTailscale: true
  ) or non-loopback
  text

  Copy

  gateway.auth.mode: "trusted-proxy"
  satisfy the connect auth check from request headers instead of
  text

  Copy

  connect.params.auth.*
  .
• Private-ingress
  text

  Copy

  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. It is returned in
  text

  Copy

  hello-ok.auth.deviceToken
  and should be persisted by the client for future connects.
• Clients should persist the primary
  text

  Copy

  hello-ok.auth.deviceToken
  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 that was already granted and avoids silently collapsing reconnects to a narrower implicit admin-only scope.
• Client-side connect auth assembly (
  text

  Copy

  selectConnectAuth
  in
  text

  Copy

  src/gateway/client.ts
  ):
  • text

    Copy

    auth.password
    is orthogonal and is always forwarded when set.
  • text

    Copy

    auth.token
    is populated in priority order: explicit shared token first, then an explicit
    text

    Copy

    deviceToken
    , then a stored per-device token (keyed by
    text

    Copy

    deviceId
    +
    text

    Copy

    role
    ).
  • text

    Copy

    auth.bootstrapToken
    is sent only when none of the above resolved an
    text

    Copy

    auth.token
    . A shared token or any resolved device token suppresses it.
  • Auto-promotion of a stored device token on the one-shot
    text

    Copy

    AUTH_TOKEN_MISMATCH
    retry is gated to trusted endpoints only — loopback, or
    text

    Copy

    wss://
    with a pinned
    text

    Copy

    tlsFingerprint
    . Public
    text

    Copy

    wss://
    without pinning does not qualify.
• Additional
  text

  Copy

  hello-ok.auth.deviceTokens
  entries are bootstrap handoff tokens. Persist them only when the connect used bootstrap auth on a trusted transport such as
  text

  Copy

  wss://
  or loopback/local pairing.
• If a client supplies an explicit
  text

  Copy

  deviceToken
  or explicit
  text

  Copy

  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
  text

  Copy

  device.token.rotate
  and
  text

  Copy

  device.token.revoke
  (requires
  text

  Copy

  operator.pairing
  scope).
• text

  Copy

  device.token.rotate
  returns rotation metadata. It echoes the replacement bearer token only for same-device calls that are 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
  text

  Copy

  operator.admin
  : non-admin callers can remove/revoke/rotate only their own device entry.
• text

  Copy

  device.token.rotate
  and
  text

  Copy

  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
  text

  Copy

  error.details.code
  plus recovery hints:
  • text

    Copy

    error.details.canRetryWithDeviceToken
    (boolean)
  • text

    Copy

    error.details.recommendedNextStep
    (
    text

    Copy

    retry_with_device_token
    ,
    text

    Copy

    update_auth_configuration
    ,
    text

    Copy

    update_auth_credentials
    ,
    text

    Copy

    wait_then_retry
    ,
    text

    Copy

    review_auth_configuration
    )
• Client behavior for
  text

  Copy

  AUTH_TOKEN_MISMATCH
  :
  • Trusted clients may attempt one bounded retry with a cached per-device token.
  • If that retry fails, clients should stop automatic reconnect loops and surface operator action guidance.

Device identity + pairing

• Nodes should include a stable device identity (
  text

  Copy

  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
  text

  Copy

  device
  identity during
  text

  Copy

  connect
  (operator + node). The only device-less operator exceptions are explicit trust paths:
  • text

    Copy

    gateway.controlUi.allowInsecureAuth=true
    for localhost-only insecure HTTP compatibility.
  • successful
    text

    Copy

    gateway.auth.mode: "trusted-proxy"
    operator Control UI auth.
  • text

    Copy

    gateway.controlUi.dangerouslyDisableDeviceAuth=true
    (break-glass, severe security downgrade).
  • direct-loopback
    text

    Copy

    gateway-client
    backend RPCs authenticated with the shared gateway token/password.
• All connections must sign the server-provided
  text

  Copy

  connect.challenge
  nonce.

Device auth migration diagnostics

For legacy clients that still use pre-challenge signing behavior,

now returns detail codes under with a stable .

Common migration failures:

Migration target:

• Always wait for
  text

  Copy

  connect.challenge
  .
• Sign the v2 payload that includes the server nonce.
• Send the same nonce in
  text

  Copy

  connect.params.device.nonce
  .
• Preferred signature payload is
  text

  Copy

  v3
  , which binds
  text

  Copy

  platform
  and
  text

  Copy

  deviceFamily
  in addition to device/client/role/scopes/token/nonce fields.
• Legacy
  text

  Copy

  v2
  signatures remain accepted for compatibility, but paired-device metadata pinning still controls command policy on reconnect.

TLS + pinning

• TLS is supported for WS connections.
• Clients may optionally pin the gateway cert fingerprint (see
  text

  Copy

  gateway.tls
  config plus
  text

  Copy

  gateway.remote.tlsFingerprint
  or CLI
  text

  Copy

  --tls-fingerprint
  ).

Scope

This protocol exposes the full gateway API (status, channels, models, chat, agent, sessions, nodes, approvals, etc.). The exact surface is defined by the TypeBox schemas in

.

Related

• Bridge protocol
• Gateway runbook