name: dashboard-api description: OpenClaw Gateway WebSocket API reference for building custom dashboards and control UIs. Use when creating, debugging, or extending browser-based dashboards that connect to the OpenClaw Gateway. Covers all RPC methods including undocumented file APIs, session management, cron jobs, logs, chat, and config.

OpenClaw Dashboard API Reference

Complete Gateway WebSocket RPC reference for custom dashboard development.

Connection

Connect via WebSocket to the gateway port (default 18789). First message must be a connect request.

ws://127.0.0.1:18789

Frame Format

All messages are JSON with three frame types:

• Request: { type: "req", id, method, params }
• Response: { type: "res", id, ok, payload | error }
• Event: { type: "event", event, payload }

Authentication

{
  "type": "req", "id": "c1", "method": "connect",
  "params": {
    "minProtocol": 3, "maxProtocol": 3,
    "client": { "id": "my-dashboard", "version": "1.0.0", "platform": "web", "mode": "ui" },
    "role": "operator",
    "scopes": ["operator.read", "operator.write", "operator.admin"],
    "auth": { "token": "<gateway-token>" }
  }
}

RPC Methods

Chat

| Method | Params | Description | |--------|--------|-------------| | chat.history | { sessionKey, limit } | Load history (max 1000). Content is array of typed blocks. | | chat.send | { sessionKey, message, deliver?, idempotencyKey } | Send message. Non-blocking; response streams via chat events. | | chat.abort | { sessionKey } | Abort active run. | | chat.inject | { sessionKey, content } | Append assistant note (no agent run). |

Chat history content blocks: Messages return content as an array:

• { type: "text", text: "..." } — display text
• { type: "toolCall", name, id, arguments } — tool invocation
• { type: "thinking", thinking } — model reasoning (usually hidden)
• Role toolResult messages contain tool outputs (usually hidden in UI)

Sessions

| Method | Params | Returns | |--------|--------|---------| | sessions.list | {} | { sessions, defaults, count } | | sessions.patch | { sessionKey, thinking?, verbose?, sendPolicy? } | Updated session | | sessions.delete | { sessionKey } | — |

Session entries include: key, kind, label, displayName, channel, model, modelProvider, inputTokens, outputTokens, totalTokens, contextTokens, updatedAt, origin.

Cron Jobs

| Method | Params | Returns | |--------|--------|---------| | cron.list | { includeDisabled? } | { jobs } | | cron.add | { job } | Created job | | cron.update | { jobId, patch } | Updated job | | cron.remove | { jobId } | — | | cron.run | { jobId } | Triggers immediate run | | cron.runs | { jobId } | { entries } — run history with status/summary/duration |

Job object shape: See references/cron-schema.md.

Files (Undocumented)

These methods are used by the built-in OpenClaw Control UI but not documented in official docs. They provide workspace file access with no config changes needed.

| Method | Params | Returns | |--------|--------|---------| | agents.files.list | { agentId } | { workspace, files: [{ name, path, missing, size, updatedAtMs }] } | | agents.files.get | { agentId, name } | { file: { name, path, content, size, updatedAtMs } } | | agents.files.set | { agentId, name, content } | { file } |

• agentId is typically "main".
• Returns workspace bootstrap files: SOUL.md, USER.md, MEMORY.md, AGENTS.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md, etc.
• Discovered by reverse-engineering dist/control-ui/assets/index-*.js.

Logs

| Method | Params | Returns | |--------|--------|---------| | logs.tail | { limit?, cursor? } | { file, cursor, size, lines, truncated, reset } |

Lines are JSON (tslog format). Use cursor for incremental polling. If reset is true, the log file rotated.

Config

| Method | Params | Returns | |--------|--------|---------| | config.get | {} | Full config with hash | | config.schema | {} | JSON Schema + UI hints | | config.patch | { raw, baseHash? } | Validate + write + restart |

System

| Method | Params | Returns | |--------|--------|---------| | health | {} | Health check | | status | {} | Full system status |

Events

| Event | Payload Fields | Description | |-------|---------------|-------------| | chat | state, message, sessionKey, runId, name, phase, args, result | Streaming: delta, tool, thinking, final, error, aborted | | tick | ts | Periodic gateway heartbeat |

Implementation Notes

• Singleton WebSocket: Create one connection, share across all components. Multiple connections cause reconnect loops.
• History limit: Gateway caps chat.history at 1000 messages. Use localStorage cache for continuity.
• Content parsing: Always handle content as array of typed blocks, not raw strings.
• Session key: Use "main" for the primary session. Full format is agent:<agentId>:<key>.
• Reconnect: Use exponential backoff. Auth failures (codes 4001/4003/1008) should not auto-reconnect.