Skip to main content

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us