token-counter

核心用法

Token Counter 是一款专为 OpenClaw 生态设计的本地 Token 使用分析工具。用户通过命令行调用主脚本，可生成多维度 Token 消耗报告。基础用法为指定时间周期（如 --period 7d）生成周报，支持按工具、类别、客户端、模型等维度细分统计。高级功能包括单会话深度钻取（--session 参数）、JSON 格式导出（--format json）以及每日快照持久化（--save）。数据源完全本地化，读取会话转录文件（.jsonl）、会话索引（sessions.json）及定时任务配置（jobs.json），无需任何外部 API 连接。

显著优点

极致轻量与零依赖：仅依赖 Python 标准库（argparse、json、pathlib 等），无第三方包引入，部署零摩擦，长期维护成本极低。隐私优先设计：所有数据处理均在本地完成，无网络传输，敏感业务数据不出境，满足企业合规要求。灵活多维分析：支持 5 种细分维度（category/client/model/tool/top consumers）自由组合，既可宏观把握周度趋势，也能微观定位单会话异常。自动化友好：JSON 输出与每日快照功能便于接入数据管道，与 BI 工具或监控系统集成。透明可审计：分类规则文档化（classification-rules.md），客户端检测逻辑（personal/bonsai/mixed/unknown）清晰可追溯。

潜在缺点与局限性

工具 Token 归因采用启发式算法：助手消息中的 Token 按工具调用数均摊，非精确计量，可能存在统计偏差。客户端识别依赖规则匹配：基于路径/域名/邮箱等标记推断，边缘场景可能误判为 unknown。无实时能力：仅支持离线分析历史转录文件，无法监控正在进行的会话。输出格式单一：除文本表格与 JSON 外，不支持 Excel、可视化图表等商务友好格式。大规模数据处理性能待验证：长期运行环境下，累积的 GB 级 .jsonl 文件可能带来内存压力。

适合的目标群体

OpenClaw 平台运营者：需要量化 AI 成本、向团队或客户出具用量证明的运维人员。多项目/多客户端管理者：通过 client 维度区分个人使用与企业项目消耗，实现成本分摊。AI 成本优化工程师：基于 category/tool 维度识别高消耗环节，制定模型降级或缓存策略。合规审计人员：需本地化、可审计的 Token 使用记录以满足财务或安全审计要求。自动化运维开发者：将每日快照接入 Prometheus/Grafana 或内部成本中心系统。

使用风险

性能风险：处理 30 天以上历史数据时，全量加载大文件可能导致内存峰值，建议在容器或 CI 环境中设置资源限制。路径配置风险：依赖 $OPENCLAW_DATA_DIR 等环境变量，若配置错误将导致数据读取失败，需确保 OpenClaw 环境正确初始化。归因理解风险：用户可能误将启发式工具 Token 分配当作精确值用于财务结算，需在报告中明确标注算法局限性。快照累积风险：长期启用 --save 会产生大量日度 JSON 文件，需配套磁盘清理策略避免存储膨胀。