vrr/openclaw
2
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-10-03 17:53:39 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 31
openclaw/docs/gateway/protocol.md
Peter Steinberger 3d926b2f7f
fix: avoid disconnects and delays during hosted tool calls (#146369) 
* fix(gateway): avoid self-connections for hosted operations

* fix(doctor): dispatch hosted diagnostic reads directly

* test(doctor): preserve the asynchronous findings contract

* refactor(gateway): finish the internal transport cutover

* fix: preserve inherited Gateway binding during subagent cleanup

* test(gateway): avoid ephemeral ports during capability startup
2026-09-12 14:48:21 -07:00

8 KiB
Raw Blame History

summary read_when title doc-schema-version
Gateway WebSocket protocol: handshake, frames, versioning
Implementing or updating gateway WS clients
Debugging protocol mismatches or connect failures
Regenerating protocol schema/models
Gateway protocol 1

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.

Related