- name
- usage-stats
- description
- |
Usage Stats — OpenClaw 使用统计
概述
解析 ~/.qclaw/agents/main/sessions/ 下的所有会话记录，生成完整的 OpenClaw 使用统计报告，包含 Token 消耗、费用估算、模型分布、工具调用排行、错误分析、时段分布、日趋势等维度。
使用方式： 直接告诉我"跑一下使用统计"或"统计一下我的使用情况"，我调用脚本生成报告。
核心功能
- ✅ Token 统计：input / output / cacheRead / cacheWrite / 总计
- ✅ 费用估算：基于 usage 数据计算总费用
- ✅ 模型分布：各模型的调用次数和 token 消耗
- ✅ 缓存命中率：cacheRead / (cacheRead + cacheWrite)
- ✅ 工具调用排行：所有工具的调用频次（exec / browser / message 等）
- ✅ 错误分析：归类常见错误 + 根因 + 解决方案
- ✅ 会话详情：每个会话的开始时间、时长、token、轮次
- ✅ 日趋势：每日 token/会话/错误量变化
- ✅ 时段分布：24 小时活跃热力图
- ✅ 历史趋势对比：与上次运行的对比
工作流程
步骤 1：运行脚本
执行 scripts/analyze_usage.py，报告输出到： ~/.qclaw/workspace/memory/usage_stats_latest.md
历史快照保存在：~/.qclaw/workspace/memory/usage_stats_history.json
步骤 2：解读报告
| 章节 | 含义 |
|---|---|
| Overall Stats | 整体汇总（总费用、总 token、活跃时长） |
| Model Distribution | 各模型的调用量和费用 |
| Error Analysis | 错误类型排行 + 自动根因分析 |
| Tool Usage | 工具调用频次排行 |
| Exec Performance | 命令执行耗时（P50/P95） |
| Conversation Activity | 消息角色分布 + 会话结束原因 |
| Text Volume | 平均消息长度 |
| Session Detail | 每个会话的详细数据 |
| Daily Trend | 每日 token / 会话量趋势 |
| Hourly Distribution | 24 小时活跃时段热力图 |
| Trend (vs Last Run) | 与上次运行的环比变化 |
| Troubleshooting Guide | 错误知识库（根因 + 修复方案） |
步骤 3：更新记忆
将重要发现写入 memory/YYYY-MM-DD.md（如：发现了某个高频错误、token 消耗异常等）。
数据来源
- 会话记录：
~/.qclaw/agents/main/sessions/*.jsonl - 历史快照：
~/.qclaw/workspace/memory/usage_stats_history.json
数据来自会话消息中的 usage 字段，由 OpenClaw 自动记录，无需手动维护。限制与注意事项
- 缓存命中：仅统计 OpenClaw 明确记录的
cacheRead/cacheWrite，实际缓存效果可能更高 - 费用估算：基于报告数据计算，可能与实际账单有差异，仅供参考
- 错误归类：脚本按错误模式自动归类，部分罕见错误可能归到泛型类型（
exit_code等） - 数据范围：仅统计
mainagent 的会话，子 agent 会话不包含在内 - 历史长度：最多保留 90 条历史快照，超出自动清理旧记录
常见问题
| 问题 | 答案 |
|---|---|
| 报告在哪里？ | ~/.qclaw/workspace/memory/usage_stats_latest.md |
| 历史记录在哪？ | ~/.qclaw/workspace/memory/usage_stats_history.json |
| 如何查看趋势？ | 报告中 "Trend (vs Last Run)" 章节 |
| 发现高频错误怎么办？ | 参见 "Troubleshooting Guide" 章节，按提示修复 |
| 能统计指定时间段吗？ | 目前自动统计全部历史，可手动编辑脚本过滤日期 |
| 缓存命中率 100% 正常吗？ | 正常，说明 AI 回复大量复用上下文缓存 |
输出格式规范
详见 references/output-format.md