核心用法
agent-usage-stats（token-stats）是一款跨 Agent 的 Token 消耗监控工具，采用纯 Python 标准库实现，零外部依赖。用户通过交互式菜单或命令行参数选择目标 Agent（Hermes、Claude Code、CodeX、OpenClaw、Reasonix、DeepSeek TUI），工具从各 Agent 的本地数据文件中读取会话级 Token 用量并展示。
显著优点
1. 隐私优先设计：数据完全本地读取，不联网、不上传，敏感用量信息不出境
2. 零依赖部署：单文件 Python 脚本，Python 3.11+ 环境直接运行，无需 pip 安装
3. 多 Agent 统一视角：打破各 Agent 数据孤岛，一个入口查看所有工具消耗
4. 灵活集成：支持 --watch 实时监控、-a 指定 Agent 跳过菜单，可嵌入 Hermes SKILL.md 实现任务后自动输出
5. 开源可审计：MIT 协议，源码公开
潜在局限
- 覆盖范围有限：仅支持声明的 6 款 Agent，新增 Agent 需等待更新或自行适配数据解析逻辑
- 数据格式依赖：若 Agent 更新存储格式（如 Claude Code 的 jsonl 结构变更），工具可能失效
- 无历史趋势分析：当前版本侧重即时查看，缺乏长期统计图表或成本预测功能
- 平台限制：依赖各 Agent 的默认数据路径（
~/.hermes/、~/.claude/等），自定义路径用户需手动适配
适合人群
- 多 Agent 并用的开发者，需要统一追踪各工具消耗
- 关注 API 成本控制的团队，需快速定位高消耗会话
- 隐私敏感用户，拒绝云端用量分析服务
常规风险
| 风险项 | 说明 | 缓解措施 |
|--------|------|----------|
| 数据读取权限 | 需访问各 Agent 的数据库/jsonl 文件 | 以当前用户权限运行，不请求 root |
| 数据解析错误 | Agent 升级可能导致格式不兼容 | 关注版本更新，及时 `git pull` |
| 本地存储占用 | 长期使用可能积累数据文件 | 定期清理或配置日志轮转 |
安装与更新
# 首次安装 python3 token-stats.py setup # 默认安装到 ~/.token-stats/ # 更新（git 用户） cd ~/token-stats && git pull # 更新（ClawHub 用户） token-stats update