WebSocket RPC

Direct WebSocket Access

For full control over your agent, connect directly to its WebSocket RPC endpoint. This gives you access to the complete OpenClaw protocol — all 90+ methods, real-time events, and bidirectional communication.

Connection URL

wss://app.brainroad.com/gw/YOUR_USER_ID/agent

Find your exact URL on Dashboard → API → Gateway Connection.

Authentication

After connecting, send a connect request with your gateway token:

{
  "type": "req",
  "id": "1",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 3,
    "client": {
      "id": "my-script",
      "mode": "backend",
      "version": "1.0",
      "platform": "node"
    },
    "auth": {
      "token": "YOUR_GATEWAY_TOKEN"
    }
  }
}

The server responds with a connect.challenge event followed by the connect response.

Protocol Format

Request (you send):

{"type": "req", "id": "unique-id", "method": "method.name", "params": { ... }}

Response (you receive):

{"type": "res", "id": "unique-id", "ok": true, "payload": { ... }}

Event (server pushes):

{"type": "event", "event": "event.name", "payload": { ... }}

Each request needs a unique id. The response will echo the same id so you can correlate them.

Example: Python

import asyncio, json, websockets

async def main():
    uri = "wss://app.brainroad.com/gw/YOUR_USER_ID/agent"
    async with websockets.connect(uri) as ws:
        # Authenticate
        await ws.send(json.dumps({
            "type": "req", "id": "1",
            "method": "connect",
            "params": {
                "minProtocol": 3, "maxProtocol": 3,
                "client": {"id": "my-script", "mode": "backend",
                           "version": "1.0", "platform": "python"},
                "auth": {"token": "YOUR_GATEWAY_TOKEN"}
            }
        }))
        print(await ws.recv())

        # Send a message
        await ws.send(json.dumps({
            "type": "req", "id": "2",
            "method": "chat.send",
            "params": {"message": "What's on my schedule today?"}
        }))
        print(await ws.recv())

asyncio.run(main())

Example: Node.js

import WebSocket from "ws";

const ws = new WebSocket("wss://app.brainroad.com/gw/YOUR_USER_ID/agent");

ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "req", id: "1", method: "connect",
    params: {
      minProtocol: 3, maxProtocol: 3,
      client: { id: "my-script", mode: "backend",
                version: "1.0", platform: "node" },
      auth: { token: "YOUR_GATEWAY_TOKEN" }
    }
  }));
});

ws.on("message", (data) => {
  const msg = JSON.parse(data.toString());
  console.log(msg);
  if (msg.id === "1" && msg.ok) {
    ws.send(JSON.stringify({
      type: "req", id: "2", method: "chat.send",
      params: { message: "What's on my schedule today?" }
    }));
  }
});

Available Methods

Methods are organized by category:

• Chat: chat.send, chat.history, chat.inject, chat.abort
• Agents: agents.list, agents.create, agents.update, agents.delete
• Sessions: sessions.list, sessions.preview, sessions.patch, sessions.delete
• Config: config.get, config.set, config.patch, config.apply, config.schema
• Channels: channels.status, channels.logout, web.login.start
• Cron Jobs: cron.list, cron.add, cron.update, cron.remove, cron.run
• Skills: skills.status, skills.install, skills.update, tools.catalog
• Usage: usage.status, usage.cost, models.list
• Utilities: health, logs.tail, doctor.memory.status, wake

Plus 40+ more for device pairing, exec approvals, browser automation, voice, TTS, and more. Call config.schema to discover all available methods and their parameters.

When to Use WebSocket vs. MCP vs. REST API

Use case	Best option
Claude Code / Cursor integration	MCP
Start/stop from CI/CD	REST API
Monitor events externally	SSE
Full agent control from code	WebSocket RPC
Quick status checks	REST API