WebSocket Protocol

Overview

xCloud communicates with the OpenClaw engine via WebSocket with JSON text frames on port 18789 (default). The protocol supports TLS with optional certificate pinning.

Three-Phase Handshake

Phase 1: Challenge

Server sends a challenge immediately on connection:

{
  "type": "event",
  "event": "connect.challenge",
  "payload": {
    "nonce": "504c5a0a-...",
    "ts": 1737264000000
  }
}

Phase 2: Connect Request

Client responds with authentication and device identity:

{
  "type": "req",
  "id": "unique-id",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 3,
    "client": {
      "id": "xcloud",
      "version": "0.1.0",
      "platform": "macos",
      "mode": "operator"
    },
    "role": "operator",
    "scopes": ["operator.read", "operator.write"],
    "auth": { "token": "..." },
    "device": {
      "id": "device_fingerprint",
      "publicKey": "...",
      "signature": "...",
      "signedAt": 1737264000000,
      "nonce": "..."
    }
  }
}

Phase 3: Hello-OK

Server confirms connection with capabilities:

{
  "type": "res",
  "id": "...",
  "ok": true,
  "payload": {
    "type": "hello-ok",
    "protocol": 3,
    "features": {
      "methods": ["sessions.send", "chat.send", "..."],
      "events": ["agent", "chat", "session.message", "..."]
    }
  }
}

Frame Types

Type	Direction	Structure
`req`	Client → Server	`{ type, id, method, params }`
`res`	Server → Client	`{ type, id, ok, payload/error }`
`event`	Server → Client	`{ type, event, payload, seq? }`

Key RPC Methods

Messaging

Method	Description
`sessions.send`	Send message to agent
`sessions.abort`	Abort current generation
`chat.send`	Send chat message
`chat.history`	Get chat history

Sessions

Method	Description
`sessions.create`	Create new session
`sessions.list`	List all sessions
`sessions.subscribe`	Subscribe to session events
`sessions.reset`	Reset session context

Agents

Method	Description
`agents.list`	List all agents
`agents.create`	Create new agent
`agents.update`	Update agent config
`agents.files.*`	Manage agent files

Configuration

Method	Description
`config.get`	Get current config
`config.patch`	Update config
`config.apply`	Apply config changes

Streaming Events

Agent Response Streaming

{
  "type": "event",
  "event": "agent",
  "payload": {
    "stream": "assistant",
    "data": {
      "text": "Hello! I can help you with that.",
      "delta": " with that."
    }
  }
}

data.delta = new incremental text
data.text = accumulated text so far

Lifecycle Events

{
  "event": "agent",
  "payload": {
    "stream": "lifecycle",
    "data": { "phase": "end" }
  }
}

Tool Calls

{
  "event": "session.tool",
  "payload": {
    "tool": { "name": "exec", "input": { "command": "ls -la" } },
    "status": "running"
  }
}

Constants

Parameter	Value
Protocol version	3
Default port	18789
RPC timeout	30,000 ms
Tick interval	15,000 ms
Max payload	~25 MB

WebSocket Protocol

On this page