How It Works

Claw Insights is a read-only sidecar that watches your OpenClaw gateway's data and presents it through a real-time web dashboard. Here's the data flow:

OpenClaw Gateway ──→ [Files / CLI] ──→ claw-insights server ──→ [GraphQL / SSE] ──→ Web Dashboard

Three Data Sources

Claw Insights collects data from three categories of sources — all read-only, no modifications to your gateway:

1. File System

• sessions.json — Active and recent sessions with status, model, channel, and parent/child relationships
• transcripts/*.jsonl — Full conversation history for each session (messages, tool calls, token usage)
• Gateway logs (openclaw-YYYY-MM-DD.log) — Structured log entries for errors, warnings, restarts, and tool invocations

2. CLI

• openclaw status --json — Gateway runtime status including version, uptime, connected channels, and health checks

3. SQLite

The server aggregates raw data into a local SQLite database for time-series queries:

• Token usage events (per-model, per-session)
• System samples (CPU, memory, active session count)
• Metric events (errors, warnings, API calls)

Real-Time Updates

The server exposes a GraphQL API with SSE (Server-Sent Events) subscriptions. When underlying data changes — a new session starts, a message arrives, metrics update — the server pushes a change notification over SSE. The web dashboard receives it and automatically refetches the affected data.

This means the dashboard stays current without polling: sessions appear instantly, token counts update live, and errors surface in real time.

Server-Side Rendering

Snapshots bypass the browser entirely. The server uses Satori (JSX → SVG) and resvg (SVG → PNG) to render dashboard images server-side in ~200ms — no headless browser required.

Want to go deeper?

See Architecture Overview for the full system design, pipeline architecture, and design decisions.