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#

FieldDefault (REST / CLI)OptionsDescriptiondetail``standard``compact / standard / fullDetail levelformat``png``png / svg / jsonOutput formatrange``24h (REST) / 6h (CLI)30m / 1h / 6h / 12h / 24hTime range for metricstheme``dark``dark / lightColor themelang``en``en / zhLanguage

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

Error Handling#

StatusCauseFix401Missing or invalid tokenCheck Bearer token, or use --no-auth mode502OpenClaw gateway not runningopenclaw gateway start``500Internal server errorCheck logs: ~/.claw-insights/logs/Connection refusedclaw-insights not runningclaw-insights start