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
CODEBLOCK0
No-auth mode: start with claw-insights start --no-auth, then omit the Authorization header.
Response includes Content-Disposition header with timestamped filename.
CLI
CODEBLOCK1
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 |
|---|
| INLINECODE13 | INLINECODE14 | INLINECODE15 / standard / INLINECODE17 | Detail level |
| INLINECODE18 |
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.
CODEBLOCK2
Tips:
- -
compact — best for chat messages (summary numbers only, small image) - INLINECODE43 — best for daily check-ins (session list + charts)
- INLINECODE44 — best for reports and archival
Scheduled status report
CODEBLOCK3
Programmatic metrics extraction
CODEBLOCK4
JSON schema: See references/json-schema.md
Error Handling
| Status | Cause | Fix |
|---|
| INLINECODE45 | Missing or invalid token | Check Bearer token, or use --no-auth mode |
| INLINECODE47 |
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 |
快照状态卡片
启动时提示：我正在为您的 OpenClaw 代理生成可视化状态卡片。
什么是快照？
快照是服务端渲染的可视化状态卡片——而非浏览器截图。基于 Satori 技术，无需浏览器依赖，约 200 毫秒即可完成渲染。
输出结果专为聊天场景优化：紧凑布局、移动端可读性强、视觉美观便于分享。可一目了然地展示令牌用量、会话活动、错误计数和网关健康状态。
支持格式：PNG（默认）、SVG 或用于程序化调用的原始 JSON。
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
无认证模式：使用 claw-insights start --no-auth 启动，然后省略 Authorization 请求头。
响应中包含带时间戳文件名的 Content-Disposition 响应头。
CLI 命令行
bash
claw-insights snapshot # 保存至 ~/.claw-insights/snapshots/
claw-insights snapshot --quick -o status.png # 紧凑型移动端快照
claw-insights snapshot --format json | jq . # JSON 输出至标准输出
claw-insights snapshot --dry-run # 仅预览参数
CLI 标志：--format、--detail、--range、--theme、--lang、-o <路径>、-t <令牌>、--port、--quick、--dry-run。运行 claw-insights snapshot --help 查看完整用法。
参数
| 字段 | 默认值（REST / CLI） | 可选值 | 描述 |
|---|
| detail | standard | compact / standard / full | 详细程度 |
| format |
png | png / svg / json | 输出格式 |
| range | 24h（REST）/ 6h（CLI） | 30m / 1h / 6h / 12h / 24h | 指标时间范围 |
| theme | dark | dark / light | 颜色主题 |
| lang | en | en / zh | 语言 |
注意： REST API 和 CLI 的默认 range 值不同。REST 默认为 24h（全天概览），CLI 默认为 6h（快速状态检查）。两者均接受相同的可选值。
如何选择详细程度？
- - compact — 仅显示摘要数字（会话数、总令牌数、错误数）。最适合嵌入聊天消息。
- standard — 会话列表 + 指标图表。大多数场景的默认选项。
- full — 完整内容：会话列表、所有图表、事件日志。最适合报告和归档。
常见工作流程
推送状态卡片到频道
适用于任何消息频道——Slack、Telegram、Discord、WhatsApp 等。
bash
1. 生成紧凑型状态卡片
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. 通过频道工具或 API 发送
紧凑型详细程度针对移动端聊天气泡进行了优化。
提示：
- - compact — 最适合聊天消息（仅摘要数字，图片小巧）
- standard — 最适合日常检查（会话列表 + 图表）
- full — 最适合报告和归档
定时状态报告
bash
24小时范围的完整快照
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
程序化指标提取
bash
以 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 架构：参见 references/json-schema.md
错误处理
| 状态码 | 原因 | 解决方法 |
|---|
| 401 | 令牌缺失或无效 | 检查 Bearer 令牌，或使用 --no-auth 模式 |
| 502 |
OpenClaw 网关未运行 | 执行 openclaw gateway start |
| 500 | 服务器内部错误 | 检查日志：~/.claw-insights/logs/ |
| 连接被拒绝 | claw-insights 未运行 | 执行 claw-insights start |
