Architecture Overview
Claw Insights is a read-only observability sidecar for OpenClaw agents. It reads existing files and CLI output — no code changes to your agent, no cloud dependency, all data stays local.
System Architecture
┌─────────────────────────────────────────────────────────────┐
│ claw-insights │
│ │
│ External I/O Pipeline API Layer │
│ ───────────── ───────────────── ────────────── │
│ sessions.json → /graphql (query, │
│ transcripts/* → Sources → Ports ───→ mutation, sub) │
│ gateway logs → /api/snapshot │
│ cron.json → ↕ /health │
│ openclaw CLI → Services │
│ (sampling, Web Dashboard │
│ ↕ retention, ←── (React + Vite) │
│ SQLite validation) │
└─────────────────────────────────────────────────────────────┘Data flows left to right: external files and CLI → Sources ingest and parse → Pipeline wires components → Ports expose typed read interfaces → GraphQL resolvers serve queries → Web dashboard (or any API client) consumes data.
SQLite provides persistent storage for time-series metrics, token usage, message events, and system samples.
Monorepo Structure
| Package | Purpose |
|---|---|
packages/server | Express server: data pipeline, GraphQL API, snapshot renderer, SQLite storage |
packages/web | React 19 + Vite dashboard: charts (ECharts), session explorer, log viewer |
packages/shared | Generated TypeScript types from schema.graphql (shared by server and web) |
Pipeline Roles
The Pipeline manages all components through five roles:
| Role | Responsibility |
|---|---|
| Source | Emits events from external data (file watchers, CLI clients) |
| Managed | Lifecycle-only resources with no events (event buses, readers) |
| Processor | Handles events from Sources (e.g., ingesting logs into the database) |
| Service | Background tasks with start/stop lifecycle (sampling, retention, validation) |
| Port | Typed read interface — the public contract consumed by GraphQL resolvers |
Lifecycle: init (register components) → build (bind wiring) → start (launch services) → destroy (teardown in reverse order).
Ports
Ports are the boundary between the pipeline internals and the API layer. Each Port exposes a focused read interface:
| Port | Responsibility |
|---|---|
| sessions | Session list, hierarchy, status, and filtering |
| metrics | Time-bucketed metrics with per-model token breakdown |
| gateway | OpenClaw gateway process status and version |
| cron | Scheduled job definitions |
| logs | Recent structured log entries |
| system | CPU, memory, disk usage, and health checks |
| lifetime | Cumulative statistics across all transcript history |
| transcript | Session transcript file access for replay |
| usage | Token cost summary from gateway |
Next Steps
- Data Pipeline — How data is collected, stored, and aggregated