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.

Agent tools running inside a Gateway dispatch requests directly through that Gateway's router. They retain method scopes, agent and approval authority, request deadlines, and cancellation without opening another WebSocket. Explicit Gateway URL or token overrides, standalone agents, and separate client processes continue to use the WebSocket transport.

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.

What each page covers

• Transport and framing — gateway WS transport: packages, frame shapes, limits, and WebRTC Talk control.
• Handshake and roles — connect frame, hello-ok payload, client capabilities, roles, and scopes.
• Presence and events — presence snapshots, node host stats, and broadcast event scoping.
• RPC methods — RPC method families, discovery, session list bootstrap, and event families.
• Ledger RPCs — audit ledger and task ledger RPCs, their scopes, cursors, and payloads.
• Operator methods — operator helper methods, exec approvals, and agent delivery fallback.
• Versioning — protocol version constants, the N-1 node window, and client defaults.
• Auth and device identity — handshake auth paths, device identity, pairing signatures, and TLS pinning.

Where each section moved

Every section heading from the previous single-page version keeps its anchor here, so an existing link to this page with a fragment still resolves. Each entry points at the page that now holds the content.

• npm packages
• Transport and framing
• Gateway-controlled WebRTC Talk
• Handshake
• Worker role and closed protocol
• Client capabilities
• Node connect example
• Roles and scopes
• Caps/commands/permissions (node)
• Caps/commands/permissions (node)
• Presence
• Node host stats
• Node background alive event
• Broadcast event scoping
• RPC method families
• System and identity
• Models and usage
• Channels and login helpers
• Plugin management
• Messaging and logs
• Operator terminal
• 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
• Control UI commands
• Automation, skills, and tools
• Session list bootstrap
• Common event families
• Node helper methods
• Node exec lifecycle events
• Audit ledger RPC
• Task ledger RPCs
• Operator helper methods
• models.list views
• models.list views
• Exec approvals
• Agent delivery fallback
• Versioning
• Client constants
• Auth
• Device identity and pairing
• Device auth migration diagnostics
• TLS and pinning

Related

• Building a Gateway client
• Embedding OpenClaw
• Gateway runbook
• Operator scopes — the scopes protocol methods are authorized against
• Audit history — metadata-only activity history and decision receipts
• Pairing — approve who can DM you and which nodes can join
• Cloud Workers — worker sessions driven over this protocol
• Tools invoke API — invoke a single tool directly via the Gateway HTTP endpoint