快照状态卡片

启动时提示： "我正在为您生成 OpenClaw 代理的可视化状态卡片。"

什么是快照？

快照是一种由服务器渲染的可视化状态卡片——不是浏览器截图。基于 Satori 技术，可在约 200 毫秒内完成渲染，无需依赖浏览器。

输出结果专为聊天场景设计：紧凑、移动端可读性强，视觉上足够美观，适合分享。卡片可一次性展示令牌使用量、会话活动、错误计数和网关健康状态。

支持格式：PNG（默认）、SVG 或原始 JSON，适用于程序化使用。

REST API

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 命令

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 <token>、--port、--quick、--dry-run。运行 claw-insights snapshot --help 查看完整用法。

参数说明

注意： REST API 与 CLI 的默认 range 值不同。REST 默认为 24h（全天概览），CLI 默认为 6h（快速状态检查）。两者均接受相同的取值范围。

如何选择详细程度？

• compact — 仅显示摘要数据（会话数量、总令牌数、错误计数）。适合嵌入聊天消息。
• standard — 显示会话列表 + 指标图表。适用于大多数场景。
• full — 包含全部内容：会话列表、所有图表、事件日志。适合报告和归档。

常见工作流

推送状态卡片到频道

适用于任意消息渠道——Slack、Telegram、Discord、WhatsApp 等。

# 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 — 适合报告与存档

定期状态报告

# 生成 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

程序化指标提取

# 获取原始数据为 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：参见 [references/json-schema.md](references/json-schema.md)

错误处理