Skip to content

API.md

Latest commit

 

History

History
427 lines (353 loc) · 7.1 KB

API.md

File metadata and controls

427 lines (353 loc) · 7.1 KB

OpenClaw Gateway Protocol

This document describes the WebSocket protocol used between iOSLobster and the OpenClaw Gateway.

Pairing

Pairing uses an HTTPS endpoint derived from the gateway WebSocket URL:

https://<gateway-host>/pair

Request

{
  "device_id": "uuid",
  "public_key": "base64-encoded-Ed25519-public-key",
  "challenge": "nonce",
  "app_version": "1.0.0",
  "platform": "ios"
}

Response

{
  "device_token": "opaque-device-token",
  "gateway_name": "My Gateway",
  "fingerprint": "SHA256:...",
  "gateway_public_key": "<base64-encoded-ed25519-public-key>"
}

Connection

Endpoint

wss://<gateway-host>/ws

Authentication

The client connects with a device token in the Authorization header:

Authorization: Bearer <device-token>

Connection Flow

  1. Client connects with device token
  2. Gateway validates token and sends connected message
  3. Client receives session ID
  4. Bidirectional messaging begins

Message Format

All messages are JSON-encoded.

Common Fields

Field Type Description
type string Message type
timestamp int64 Unix timestamp in milliseconds

Client → Gateway Messages

Text Message

{
  "type": "text",
  "session_id": "abc123",
  "timestamp": 1706745600000,
  "payload": {
    "text": "Hello, world!"
  }
}

Voice Message

{
  "type": "voice",
  "session_id": "abc123",
  "timestamp": 1706745600000,
  "payload": {
    "transcription": "What's the weather like?",
    "language": "en-US"
  }
}

Canvas Event

{
  "type": "canvas_event",
  "session_id": "abc123",
  "timestamp": 1706745600000,
  "payload": {
    "element_id": "button-1",
    "action": "tap",
    "position": { "x": 100, "y": 200 }
  }
}

Capability Response

{
  "type": "capability_response",
  "session_id": "abc123",
  "timestamp": 1706745600000,
  "payload": {
    "request_id": "req-456",
    "granted": true,
    "capability": "mic.foreground.60s",
    "token": {
      "expires_at": "2026-02-01T12:05:00Z",
      "nonce": "random123"
    }
  }
}

Image Message

{
  "type": "image",
  "session_id": "abc123",
  "timestamp": 1706745600000,
  "payload": {
    "data": "<base64>",
    "mime_type": "image/jpeg"
  }
}

Canvas Drawing Message

{
  "type": "canvas_drawing",
  "session_id": "abc123",
  "timestamp": 1706745600000,
  "payload": {
    "data": "<base64>",
    "mime_type": "image/png"
  }
}

Panic Abort

{
  "type": "panic_abort",
  "session_id": "abc123",
  "timestamp": 1706745600000,
  "payload": {
    "reason": "user_abort"
  }
}

Agent Selection

{
  "type": "agent_selection",
  "session_id": "abc123",
  "timestamp": 1706745600000,
  "payload": {
    "agent_id": "claude-main"
  }
}

Heartbeat

{
  "type": "heartbeat",
  "session_id": "abc123",
  "timestamp": 1706745600000,
  "payload": {}
}

Signature Fields

When message signing is enabled, an Ed25519 signature is attached to the payload:

{
  "payload": {
    "sig": "<base64 signature>",
    "kid": "device-id",
    "...": "payload"
  }
}

Gateway → Client Messages

Connected

{
  "type": "connected",
  "agent_id": null,
  "attention_level": null,
  "timestamp": 1706745600000,
  "payload": {
    "session_id": "abc123",
    "gateway_version": "1.0.0"
  }
}

Text Message

{
  "type": "text",
  "agent_id": "claude-main",
  "attention_level": "active",
  "timestamp": 1706745600000,
  "payload": {
    "text": "Hello from the agent!"
  }
}

Canvas Update

{
  "type": "canvas_update",
  "agent_id": "claude-main",
  "attention_level": "passive",
  "timestamp": 1706745600000,
  "payload": {
    "action": "draw",
    "elements": [
      {
        "id": "text-1",
        "type": "text",
        "bounds": { "x": 10, "y": 20, "width": 200, "height": 50 },
        "content": "Hello, Canvas!",
        "interactive": false
      }
    ],
    "transition": "fade"
  }
}

Capability Request

{
  "type": "capability_request",
  "agent_id": "claude-main",
  "attention_level": "interrupt",
  "timestamp": 1706745600000,
  "payload": {
    "request_id": "req-456",
    "capability": "mic.foreground.60s",
    "duration": 60,
    "purpose": "Voice transcription"
  }
}

Capability Granted

{
  "type": "capability_granted",
  "agent_id": "claude-main",
  "attention_level": "notify",
  "timestamp": 1706745600000,
  "payload": {
    "request_id": "req-456",
    "token": {
      "capability": "mic.foreground.60s",
      "granted_at": "2026-02-01T12:00:00Z",
      "expires_at": "2026-02-01T12:05:00Z",
      "session_id": "abc123",
      "nonce": "random_bytes",
      "signature": "gateway_signature"
    }
  }
}

Attention

{
  "type": "attention",
  "agent_id": "claude-main",
  "attention_level": "urgent",
  "timestamp": 1706745600000,
  "payload": {
    "reason": "Timer completed"
  }
}

Status

{
  "type": "status",
  "agent_id": "claude-main",
  "attention_level": "passive",
  "timestamp": 1706745600000,
  "payload": {
    "status": "thinking",
    "progress": 0.5
  }
}

Error

{
  "type": "error",
  "agent_id": null,
  "attention_level": null,
  "timestamp": 1706745600000,
  "payload": {
    "code": "INVALID_SESSION",
    "message": "Session expired"
  }
}

Attention Levels

Level Description Client Behavior
passive Background update No notification
notify Worth noting Badge/subtle indicator
active Needs attention Visual highlight
interrupt Requires action Modal/sheet
urgent Time-sensitive Haptic + sound

Capability Tokens

Capabilities are time-boxed permissions granted by the user.

Format

{
  "capability": "mic.foreground.60s",
  "granted_at": "2026-02-01T12:00:00Z",
  "expires_at": "2026-02-01T12:01:00Z",
  "session_id": "abc123",
  "nonce": "random_bytes",
  "signature": "gateway_signature"
}

Common Capabilities

Capability Duration Description
mic.foreground.60s 60s Microphone access
camera.front.once 5s Single photo
location.precise.5min 300s GPS location
canvas.control.90s 90s Canvas interaction

Canvas Elements

Element Types

Type Description
text Text block
image Raster image (base64 or URL)
shape Vector shape
video Video player
highlight Overlay highlight

Element Structure

{
  "id": "unique-id",
  "type": "text",
  "bounds": {
    "x": 0,
    "y": 0,
    "width": 100,
    "height": 50
  },
  "content": "Text or base64 data",
  "style": {
    "color": "#000000",
    "fontSize": 16
  },
  "interactive": true
}

Error Codes

Code Description
INVALID_TOKEN Device token invalid
INVALID_SESSION Session expired
RATE_LIMITED Too many requests
CAPABILITY_DENIED Capability not granted
INTERNAL_ERROR Server error