Gateway API reference

The WednesdayAI gateway exposes:

WebSocket control plane - all clients (CLI, web UI, mobile apps, nodes) connect here
HTTP tools endpoint - invoke agent tools directly without a full agent run
OpenAI-compatible endpoints - POST /v1/chat/completions and POST /v1/responses

All endpoints share the same port (18789 by default) via HTTP/WebSocket multiplexing.

Authentication

All endpoints use the gateway auth configuration:

Auth mode	How to authenticate
`token` (default)	`Authorization: Bearer <OPENCLAW_GATEWAY_TOKEN>`
`password`	`Authorization: Bearer <OPENCLAW_GATEWAY_PASSWORD>`
`trusted-proxy`	Delegated to upstream proxy via the configured user header
`none`	No auth (loopback-only setups)

Too many failed auth attempts returns HTTP 429 with a Retry-After header (tunable via gateway.auth.rateLimit).

WebSocket protocol

The WebSocket control plane is the primary integration surface. All CLI commands, the web control panel, and mobile nodes use this protocol. Connection: ws://localhost:18789 (or wss:// with TLS)

Handshake

The gateway sends a challenge before accepting the connection: Gateway -> Client (challenge):

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

Client -> Gateway (connect request):

{
  "type": "req",
  "id": "req-1",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 3,
    "client": { "id": "my-client", "version": "1.0.0", "platform": "linux", "mode": "operator" },
    "role": "operator",
    "scopes": ["operator.read", "operator.write"],
    "auth": { "token": "your-gateway-token" },
    "locale": "en-US"
  }
}

Gateway -> Client (success):

{
  "type": "res",
  "id": "req-1",
  "ok": true,
  "payload": {
    "type": "hello-ok",
    "protocol": 3,
    "policy": { "tickIntervalMs": 15000 },
    "auth": { "deviceToken": "...", "role": "operator", "scopes": ["operator.read", "operator.write"] }
  }
}

The deviceToken in the response can be saved and passed as auth.token on subsequent connections to skip full re-authentication. The protocol version is currently 3.

Request/response pattern

After handshake, all communication uses type: "req" with an id for correlation and type: "res" responses:

{ "type": "req", "id": "req-2", "method": "sessions.list", "params": {} }

{ "type": "res", "id": "req-2", "ok": true, "payload": { "sessions": [] } }

On error, ok is false and error is set:

{ "type": "res", "id": "req-2", "ok": false, "error": { "code": "NOT_FOUND", "message": "Session not found" } }

Server-push events

The gateway pushes events to all connected clients in this frame shape:

{ "type": "event", "event": "<name>", "payload": { }, "seq": 42, "stateVersion": { "presence": 7, "health": 3 } }

seq is a monotonically increasing broadcast sequence; stateVersion is present on state-snapshot events (presence, health). Slow consumers that cannot keep up are disconnected (close code 1008); discardable events are dropped instead.

Event	Payload	Emitted when
`connect.challenge`	`{ nonce, ts }`	Immediately on connection (see handshake above)
`agent`	`{ runId, seq, stream, ts, sessionKey?, data }`	Agent run streaming updates (assistant deltas, tool events, lifecycle phases)
`chat`	`{ runId, sessionKey, seq, state, message?, errorMessage? }` where `state` is `delta` \| `final` \| `error`	Webchat run progress and final messages
`presence`	`{ presence: [...] }`	System presence snapshot changes
`tick`	`{ ts }`	Periodic keepalive
`health`	Health summary snapshot	Health refresh; sensitive fields are redacted unless the client has admin scope
`heartbeat`	Heartbeat event	After each heartbeat run; redacted unless admin scope
`cron`	Cron job lifecycle event (e.g. `{ action: "finished", jobId }`)	Cron job state changes
`talk.mode`	`{ enabled, phase, ts }`	Voice talk mode changes
`talk.realtime.relay`	Realtime voice relay frames	During realtime voice sessions
`shutdown`	`{ reason, restartExpectedMs }`	Gateway is shutting down
`node.pair.requested`	Pairing request	A node requests pairing (requires the pairing scope)
`node.pair.resolved`	Pairing resolution	A node pairing request is approved/rejected (pairing scope)
`node.invoke.request`	Invocation request	The gateway dispatches a command to a connected node
`device.pair.requested`	Device pairing request	A device requests pairing (pairing scope)
`device.pair.resolved`	Device pairing resolution	A device pairing request is approved/rejected (pairing scope)
`voicewake.changed`	`{ triggers }`	Voice wake-word triggers change
`exec.approval.requested`	Approval request	An exec approval is requested (approvals scope)
`exec.approval.resolved`	Approval resolution	An exec approval decision is made (approvals scope)
`sessions.runsUpdate`	`{ runs, capturedAt, stuckThresholdMs }`	Active session run state changes
`update.available`	`{ updateAvailable: { currentVersion, latestVersion, channel } \| null }`	Gateway update availability changes

Pairing and exec-approval events are only delivered to operator connections holding the matching scope (or admin). Plugins and channel extensions can register additional methods and events beyond this table.

RPC methods

The table below is not exhaustive. The gateway registers dozens of methods and plugins can add more. To enumerate or call any method from the CLI, use openclaw gateway call <method> --params '<json>'. There is no public “list methods” RPC - the authoritative surface is the gateway source and the gateway call helper.

Common methods, grouped by namespace:

Namespace	Methods
Handshake	`connect` (must be first)
Config	`config.get`, `config.set`, `config.patch`, `config.apply`, `config.schema`
Sessions	`sessions.list`, `sessions.preview`, `sessions.patch`, `sessions.reset`, `sessions.delete`, `sessions.compact`, `sessions.thresholds`, `sessions.interrupt`, `sessions.claims.status`
Chat	`chat.send`, `chat.history`, `chat.inject`, `chat.abort`
Channels	`channels.status`, `channels.logout`
Logs / health	`logs.tail`, `usage.status`, `usage.cost`
Cron	`cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs`
System / update	`update.run`
System state	`last-heartbeat`, `set-heartbeats`, `system-presence`, `system-event` — heartbeat and presence RPCs behind the `openclaw system` CLI (flat method names; there is no `system.*` prefix)
Plugins	`plugins/health` — current plugin health report (status, per-plugin diagnostics)
Pairing (devices)	`device.pair.list`, `device.pair.approve`, `device.pair.reject`, `device.pair.remove`, `device.token.rotate`, `device.token.revoke`
Nodes	`node.list`, `node.describe`, `node.invoke`, `node.event`, `node.rename`, `node.pair.list`, `node.pair.approve`, `node.pair.reject`, `node.pair.request`, `node.pair.verify`
Models	`models.list`
Memory	`doctor.memory.status`
Browser	`browser.request`
Approvals	`exec.approvals.get`, `exec.approvals.set`, `exec.approval.request`, `exec.approval.resolve`
Secrets	`secrets.reload`, `secrets.resolve`
Skills	`skills.status`, `skills.install`, `skills.update`, `skills.bins`
Voice / TTS	`tts.status`, `tts.enable`, `tts.disable`, `tts.providers`, `tts.setProvider`, `tts.convert`, `talk.config`, `talk.mode`
Wizard	`wizard.start`, `wizard.next`, `wizard.status`, `wizard.cancel`

openclaw gateway status, openclaw gateway health, and openclaw gateway probe are CLI helpers that establish a connection and read the handshake/health payload - they are not single RPC method names. Likewise tools.invoke is exposed over HTTP (POST /tools/invoke), not as a control-plane method. Hooks have no RPC namespace either - manage them with the openclaw hooks CLI and the hooks.* config keys.

Config RPC rate limiting

config.apply and config.patch are rate-limited to 3 requests per 60 seconds per deviceId+clientIp. When limited, the call returns UNAVAILABLE with retryAfterMs. Both require a baseHash (from config.get) to prevent concurrent conflicting writes. Restarts are coalesced with a 30-second cooldown.

HTTP: Tool invocation

POST /tools/invoke - invoke a single agent tool directly. Always enabled; gated by gateway auth and tool policy. Maximum payload size: 2 MB

curl -X POST http://localhost:18789/tools/invoke \
  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tool": "sessions_list", "args": {}, "sessionKey": "main" }'

Field	Type	Required	Description
`tool`	string	Yes	Tool name to invoke
`action`	string	No	Shorthand mapped into args if the tool supports `action`
`args`	object	No	Tool-specific arguments
`sessionKey`	string	No	Target session key (defaults to main session)

Tool availability is filtered through the tool policy chain (tools.*, agents.<id>.tools.*, and the HTTP-specific gateway.tools.deny/gateway.tools.allow overrides). If a tool is not allowed, the endpoint returns HTTP 404.

HTTP: OpenAI-compatible Chat Completions

POST /v1/chat/completions - drop-in replacement for the OpenAI Chat Completions API. Runs a full gateway agent turn. Disabled by default. Enable with gateway.http.endpoints.chatCompletions.enabled: true.

curl -X POST http://localhost:18789/v1/chat/completions \
  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openclaw:main",
    "messages": [ { "role": "user", "content": "What is the current time?" } ],
    "stream": false
  }'

Target a specific agent via the model string (openclaw:<agentId>) or headers:

x-openclaw-agent-id: main
x-openclaw-session-key: agent:main:whatsapp:dm:+15555550123

Tool calls, streaming (stream: true), and multi-turn conversations are supported.

HTTP: OpenAI-compatible Responses

POST /v1/responses - implements the OpenAI Responses API shape. Runs a full gateway agent turn and supports URL/file/image inputs. Disabled by default. Enable with gateway.http.endpoints.responses.enabled: true.

curl -X POST http://localhost:18789/v1/responses \
  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openclaw:main",
    "input": "Summarise https://example.com/report.pdf"
  }'

URL-input fetching is hardened via config. Set allowlists and limits before enabling URL fetch:

{
  gateway: {
    http: {
      endpoints: {
        responses: {
          enabled: true,
          maxUrlParts: 16,
          files: {
            allowUrl: true,
            urlAllowlist: ["https://example.com"],
            maxBytes: 10485760,
            pdf: { maxPages: 50, minTextChars: 16 },
          },
          images: { allowUrl: true, urlAllowlist: ["https://example.com"], maxBytes: 10485760 },
        },
      },
    },
  },
}

Both /v1/chat/completions and /v1/responses have full operator access to the gateway. A valid token here is equivalent to owner/operator credentials. Keep them on loopback or a private network - do not expose them to the public internet.

Control-UI HTTP surface and security headers

When gateway.controlUi.enabled is true, the gateway also serves the control panel and its assets over HTTP on the same port. Browser access is gated by the same auth modes plus device authorisation and origin checks (gateway.controlUi.allowedOrigins). For HTTPS deployments behind a reverse proxy you control, add HSTS:

{
  gateway: {
    http: {
      securityHeaders: { strictTransportSecurity: "max-age=63072000; includeSubDomains" },
    },
  },
}

Set strictTransportSecurity: false to omit the header. See Trusted proxy auth for TLS termination guidance.

Node connection (mobile/desktop nodes)

Nodes (iOS, Android, macOS app in node mode) connect with role: "node" and advertise their capabilities:

{
  "type": "req",
  "id": "req-1",
  "method": "connect",
  "params": {
    "role": "node",
    "caps": ["camera", "canvas", "screen", "location", "voice"],
    "commands": ["camera.snap", "canvas.navigate"],
    "auth": { "token": "node-device-token" }
  }
}

After connecting, the node listens for node.* RPC calls dispatched by the gateway agent and returns results. Approve pending nodes with openclaw nodes approve <requestId> (RPC: node.pair.approve).

Reference

Gateway API reference

Gateway API reference

Authentication

WebSocket protocol

Handshake

Request/response pattern

Server-push events

RPC methods

Config RPC rate limiting

HTTP: Tool invocation

HTTP: OpenAI-compatible Chat Completions

HTTP: OpenAI-compatible Responses

Control-UI HTTP surface and security headers

Node connection (mobile/desktop nodes)

See also

​Gateway API reference

​Authentication

​WebSocket protocol

​Handshake

​Request/response pattern

​Server-push events

​RPC methods

​Config RPC rate limiting

​HTTP: Tool invocation

​HTTP: OpenAI-compatible Chat Completions

​HTTP: OpenAI-compatible Responses

​Control-UI HTTP surface and security headers

​Node connection (mobile/desktop nodes)

​See also

Gateway API reference

Authentication

WebSocket protocol

Handshake

Request/response pattern

Server-push events

RPC methods

Config RPC rate limiting

HTTP: Tool invocation

HTTP: OpenAI-compatible Chat Completions

HTTP: OpenAI-compatible Responses

Control-UI HTTP surface and security headers

Node connection (mobile/desktop nodes)

See also