Protocol Reference

Complete schema reference for SimpleClaw Gateway protocol

Protocol Reference

Complete reference for all SimpleClaw Gateway WebSocket protocol types, methods, and events.

Protocol Version

Current protocol version: 1

Clients specify supported range in ConnectParams:

{
  "minProtocol": 1,
  "maxProtocol": 1
}

Base Types

ConnectParams

Client hello message (first frame sent):

interface ConnectParams {
  minProtocol: number;  // Minimum protocol version supported
  maxProtocol: number;  // Maximum protocol version supported
  client: {
    id: string;         // Client type: "web-ui", "macos-app", "cli", etc.
    displayName?: string;
    version: string;    // Client version
    platform: string;   // "macos", "web", "ios", "android", "linux"
    deviceFamily?: string;
    modelIdentifier?: string;
    mode: "interactive" | "node" | "headless";
    instanceId?: string;
  };
  caps?: string[];      // Client capabilities
  commands?: string[];  // Supported commands (for node mode)
  permissions?: Record<string, boolean>;
  pathEnv?: string;
  role?: string;
  scopes?: string[];
  device?: {            // Device pairing auth
    id: string;
    publicKey: string;
    signature: string;
    signedAt: number;
    nonce: string;
  };
  auth?: {
    token?: string;
    deviceToken?: string;
    password?: string;
  };
  locale?: string;
  userAgent?: string;
}

HelloOk

Server hello response:

interface HelloOk {
  type: "hello-ok";
  protocol: number;     // Negotiated protocol version
  server: {
    version: string;
    connId: string;
  };
  features: {
    methods: string[];  // Available methods
    events: string[];   // Available events
  };
  snapshot: Snapshot;   // Initial state snapshot
  canvasHostUrl?: string;
  auth?: {
    deviceToken: string;
    role: string;
    scopes: string[];
    issuedAtMs?: number;
  };
  policy: {
    maxPayload: number;
    maxBufferedBytes: number;
    tickIntervalMs: number;
  };
}

Snapshot

Gateway state snapshot:

interface Snapshot {
  agents: AgentSummary[];
  channels: Record<string, unknown>;
  presence: PresenceEntry[];
  stateVersion: StateVersion;
}

Agent Methods

agent.identity

Get agent identity and configuration:

params · object

agentId · string

Agent ID (default: “main”)

Response:

interface AgentIdentityResult {
  agentId: string;
  model: string;
  workspace?: string;
  identity?: string;
}

agents.list

List all agents:

params · object

includeFiles · boolean

Include workspace files (default: false)

Response:

interface AgentsListResult {
  agents: AgentSummary[];
}

interface AgentSummary {
  id: string;
  name?: string;
  model?: string;
  workspace?: string;
  enabled?: boolean;
}

agents.create

Create a new agent:

params · object · required

id · string · required

Unique agent ID

name · string

Display name

model · string

Model identifier

workspace · string

Workspace path

agents.update

Update agent configuration:

params · object · required

id · string · required

Agent ID

model · string

New model

name · string

New display name

Session Methods

sessions.list

List active sessions:

params · object

agentId · string

Filter by agent ID

limit · number

Max sessions to return

Response:

interface SessionsListResult {
  sessions: {
    sessionKey: string;
    agentId: string;
    model: string;
    thinkingLevel?: string;
    lastActivityAt?: number;
    messageCount?: number;
  }[];
}

sessions.patch

Update session configuration:

params · object · required

sessionKey · string · required

Session key

model · string

Change model

thinkingLevel · string

Change thinking level

verboseLevel · string

Change verbose level

sessions.reset

Clear session history:

params · object · required

sessionKey · string · required

Session key to reset

Channel Methods

channels.status

Get channel status for all configured channels:

params · object

probe · boolean

Perform active probes (default: false)

timeoutMs · number

Probe timeout in milliseconds

Response:

interface ChannelsStatusResult {
  ts: number;
  channelOrder: string[];
  channelLabels: Record<string, string>;
  channels: Record<string, unknown>;
  channelAccounts: Record<string, ChannelAccountSnapshot[]>;
  channelDefaultAccountId: Record<string, string>;
}

interface ChannelAccountSnapshot {
  accountId: string;
  name?: string;
  enabled?: boolean;
  configured?: boolean;
  linked?: boolean;
  running?: boolean;
  connected?: boolean;
  lastConnectedAt?: number;
  lastError?: string;
}

channels.logout

Disconnect and clear channel credentials:

params · object · required

channel · string · required

Channel ID (e.g., “whatsapp”, “telegram”)

accountId · string

Account ID (default: default account)

Configuration Methods

config.get

Read configuration value:

params · object

path · string

Config key path (e.g., “agent.model”)

config.set

Set configuration value:

params · object · required

path · string · required

Config key path

value · unknown · required

New value

config.patch

Partially update configuration:

params · object · required

patches · object[] · required

Array of config patches

Cron Methods

cron.list

List scheduled jobs:

params · object

agentId · string

Filter by agent

cron.add

Schedule a new job:

params · object · required

schedule · string · required

Cron expression

message · string · required

Job message/prompt

name · string

Job name

agentId · string

Target agent

cron.remove

Delete a scheduled job:

params · object · required

id · string · required

Job ID

Node Methods

node.list

List paired device nodes:

Response:

interface NodeListResult {
  nodes: {
    id: string;
    name: string;
    platform: string;
    capabilities: string[];
    permissions: Record<string, boolean>;
    online: boolean;
  }[];
}

node.invoke

Execute command on a device node:

params · object · required

nodeId · string · required

Target node ID

command · string · required

Command name (e.g., “camera.snap”)

args · object

Command arguments

Events

chat Event

Conversation updates:

interface ChatEvent {
  sessionKey: string;
  role: "user" | "assistant" | "system";
  text?: string;
  tool?: string;
  toolInput?: unknown;
  thinking?: string;
  done?: boolean;
  model?: string;
}

agent Event

Agent state changes:

interface AgentEvent {
  agentId: string;
  model?: string;
  thinkingLevel?: string;
  verboseLevel?: string;
}

tick Event

Heartbeat:

interface TickEvent {
  ts: number;
}

Next Steps

WebSocket Guide

Connection flow and client implementation

Plugin SDK

Build custom plugins