Skip to main content

​
Gateway protocol (WebSocket)

The Gateway WS protocol is the full control plane for Clawdbot. It is loopback-only by default and is intended for local clients (CLI, web UI, automations). If you are building a node client (iOS/Android/macOS node mode), use the Bridge protocol instead.

​
Transport

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

​
Handshake (connect)

Client → Gateway: 
{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 3,
    "client": {
      "id": "cli",
      "version": "1.2.3",
      "platform": "macos",
      "mode": "operator"
    },
    "caps": [],
    "auth": { "token": "…" },
    "locale": "en-US",
    "userAgent": "clawdbot-cli/1.2.3"
  }
}
Gateway → Client: 
{
  "type": "res",
  "id": "…",
  "ok": true,
  "payload": { "type": "hello-ok", "protocol": 3, "policy": { "tickIntervalMs": 15000 } }
}

​
Framing

  • Request: {type:"req", id, method, params}
  • Response: {type:"res", id, ok, payload|error}
  • Event: {type:"event", event, payload, seq?, stateVersion?}
Side-effecting methods require idempotency keys (see schema).

​
Versioning

  • PROTOCOL_VERSION lives in src/gateway/protocol/schema.ts.
  • Clients send minProtocol + maxProtocol; the server rejects mismatches.
  • Schemas + models are generated from TypeBox definitions:
    • pnpm protocol:gen
    • pnpm protocol:gen:swift
    • pnpm protocol:check

​
Auth

  • If CLAWDBOT_GATEWAY_TOKEN (or --token) is set, connect.params.auth.token must match or the socket is closed.

​
Scope

This protocol exposes the full gateway API (status, providers, models, chat, agent, sessions, nodes, etc.). The exact surface is defined by the TypeBox schemas in src/gateway/protocol/schema.ts.