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 等）
• 数据范围：仅统计 main agent 的会话，子 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