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.

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