Skip to main content

​
API Overview

SimpleClaw’s Gateway provides a WebSocket-based API for real-time communication between clients, agents, and channels. The API uses a binary framing protocol with JSON-RPC style request/response patterns.

​
Architecture

The Gateway API is the central control plane for SimpleClaw, managing:
  • Session Management - Agent sessions, context, and state
  • Channel Connections - Messaging platform integrations (WhatsApp, Telegram, Slack, Discord, etc.)
  • Agent Routing - Message routing to appropriate agents based on channel, account, and peer
  • Tool Execution - Browser control, system commands, cron jobs, and custom tools
  • Configuration - Dynamic config updates and schema validation
  • Device Pairing - Secure device-to-gateway authentication

​
Core Concepts

WebSocket Protocol

Binary frame-based protocol for real-time bidirectional communication

Protocol Schema

TypeBox schemas for all request/response/event types

Plugin SDK

Build custom channel and provider plugins

Channel Plugins

Implement messaging platform integrations

​
Protocol Layers

​
1. Transport Layer

The Gateway uses WebSocket (ws://) for local connections and WSS (wss://) for remote/Tailscale connections. Default bind: ws://127.0.0.1:18789

​
2. Framing Layer

All messages use a discriminated union frame format:
  • Request Frame (type: "req") - Client sends method call
  • Response Frame (type: "res") - Server returns result or error
  • Event Frame (type: "event") - Server pushes state changes

​
3. Method Layer

JSON-RPC style methods organized by domain:
DomainMethodsPurpose
agent.*agent.identity, agent.waitAgent identification and control
agents.*agents.list, agents.create, agents.updateMulti-agent management
chat.*chat.send, chat.abort, chat.injectConversation control
channels.*channels.status, channels.logoutChannel lifecycle
config.*config.get, config.set, config.patchConfiguration management
sessions.*sessions.list, sessions.patch, sessions.resetSession control
cron.*cron.list, cron.add, cron.updateScheduled tasks
nodes.*node.list, node.invokeDevice node execution

​
Event Streams

The Gateway pushes real-time events to connected clients:
  • chat - Agent responses, tool execution, thinking updates
  • agent - Agent state changes (model, thinking level, etc.)
  • tick - Periodic heartbeat (default 30s interval)
  • shutdown - Gateway restart notification

​
Authentication

1

Connect Phase

Client sends ConnectParams with protocol version, client info, and optional device auth.
2

Hello Response

Server responds with HelloOk containing protocol version, available methods/events, and snapshot.
3

Authenticated Session

All subsequent frames are authenticated. Device tokens enable multi-device access.

​
Client Libraries

The Gateway protocol is designed for:
  • macOS app - Swift/SwiftUI native client
  • iOS/Android apps - Mobile nodes with device-specific tools
  • CLI - TypeScript client using the same protocol
  • Web UI - React/WebSocket dashboard and WebChat

​
Rate Limits

{
  "policy": {
    "maxPayload": 10485760,       // 10MB per message
    "maxBufferedBytes": 52428800, // 50MB total buffer
    "tickIntervalMs": 30000       // 30s heartbeat
  }
}

​
Error Handling

All errors use the ErrorShape schema: 
interface ErrorShape {
  code: string;          // Error code (e.g., "INVALID_PARAMS")
  message: string;       // Human-readable message
  details?: unknown;     // Optional error context
  retryable?: boolean;   // Whether retry is recommended
  retryAfterMs?: number; // Suggested retry delay
}

​
Next Steps

WebSocket Reference

Deep dive into connection flow and frame types

Build a Plugin

Create custom channel or provider plugins

Build docs developers (and LLMs) love

Get started for freeTalk to us