claw-insights-snapshot

# Snapshot Status Cards **Announce at start:** "I'm generating a visual status card for your OpenClaw agent." ## What is a Snapshot? A snapshot is a server-rendered visual status card — not a browser screenshot. Powered by Satori, it renders in ~200ms with no browser dependency. The output is designed to look great in chat: compact, readable on mobile, and visually appealing enough to share. It shows token usage, session activity, error counts, and gateway health in a single glance. Formats: PNG (default), SVG, or raw JSON for programmatic use. ## REST API ```bash curl -X POST http://127.0.0.1:41041/api/snapshot \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"detail":"standard","range":"6h","theme":"dark"}' \ -o snapshot.png ``` No-auth mode: start with `claw-insights start --no-auth`, then omit the Authorization header. Response includes `Content-Disposition` header with timestamped filename. ## CLI ```bash claw-insights snapshot # Save to ~/.claw-insights/snapshots/ claw-insights snapshot --quick -o status.png # Compact mobile snapshot claw-insights snapshot --format json | jq . # JSON to stdout claw-insights snapshot --dry-run # Preview parameters only ``` CLI flags: `--format`, `--detail`, `--range`, `--theme`, `--lang`, `-o <path>`, `-t <token>`, `--port`, `--quick`, `--dry-run`. Run `claw-insights snapshot --help` for full usage. ## Parameters | Field | Default (REST / CLI) | Options | Description | | -------- | ------------------------- | ----------------------------------- | ---------------------- | | `detail` | `standard` | `compact` / `standard` / `full` | Detail level | | `format` | `png` | `png` / `svg` / `json` | Output format | | `range` | `24h` (REST) / `6h` (CLI) | `30m` / `1h` / `6h` / `12h` / `24h` | Time range for metrics | | `theme` | `dark` | `dark` / `light` | Color theme | | `lang` | `en` | `en` / `zh` | Language | > **Note:** REST API and CLI have different default `range` values. REST defaults to `24h` (full day overview), CLI defaults to `6h` (quick status check). Both accept the same set of values. ### Which detail level? - **compact** — Summary numbers only (session count, total tokens, error count). Best for embedding in chat messages. - **standard** — Session list + metrics charts. Default for most use cases. - **full** — Everything: session list, all charts, event log. Best for reports and archival. ## Common Workflows ### Push status card to a channel Works with any messaging channel — Slack, Telegram, Discord, WhatsApp, etc. ```bash # 1. Generate a compact status card curl -X POST http://127.0.0.1:41041/api/snapshot \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"detail":"compact","range":"6h"}' \ -o /tmp/status.png # 2. Send via your channel's tool or API # The compact detail level is optimized for mobile chat bubbles. ``` **Tips:** - `compact` — best for chat messages (summary numbers only, small image) - `standard` — best for daily check-ins (session list + charts) - `full` — best for reports and archival ### Scheduled status report ```bash # Full snapshot with 24h range curl -X POST http://127.0.0.1:41041/api/snapshot \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"detail":"full","range":"24h"}' \ -o /tmp/daily-report.png ``` ### Programmatic metrics extraction ```bash # Get raw data as JSON curl -X POST http://127.0.0.1:41041/api/snapshot \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"format":"json","range":"6h"}' \ -o metrics.json ``` JSON schema: See [references/json-schema.md](references/json-schema.md) ## Error Handling | Status | Cause | Fix | | ------------------ | ---------------------------- | ------------------------------------------- | | `401` | Missing or invalid token | Check Bearer token, or use `--no-auth` mode | | `502` | OpenClaw gateway not running | `openclaw gateway start` | | `500` | Internal server error | Check logs: `~/.claw-insights/logs/` | | Connection refused | claw-insights not running | `claw-insights start` |