Token Counter

核心用法

Token Counter 是一款面向 OpenClaw 生态的本地令牌追踪与诊断工具。它通过解析本地存储的会话转录文件（.jsonl）、会话元数据以及定时任务定义，生成按类别、客户端、工具、模型及高消耗会话细分的令牌使用报告。

典型使用场景：

• 回答"令牌都花在哪里了"——提供 7 天、30 天等多周期概览
• 日常/周报自动化——支持 --save 持久化每日快照
• 单会话深度剖析——针对特定 agent:main:cron:UUID 钻取详情
• 成本优化决策——基于工具调用归因数据识别高消耗模式

关键命令：

• 基础报告：--period 7d
• 多维度拆分：--breakdown tools,category,client
• 单会话分析：--session <session_id>
• JSON 导出：--format json --output <path>
• 每日快照：--save（写入 $OPENCLAW_WORKSPACE/token-usage/daily/）

显著优点

1. 全本地执行：所有数据源（$OPENCLAW_DATA_DIR、$OPENCLAW_WORKSPACE）均为本地路径，令牌数据不出境
2. 细粒度归因：支持按工具调用、模型类型、客户端标识（personal/bonsai/mixed）分类统计
3. 自动化友好：支持 JSON 输出与定时快照，便于接入工作流
4. 零配置启动：内置默认路径解析，开箱即用

潜在局限

• 启发式归因：工具令牌按助手消息中的工具调用数量均摊，非精确计费级数据
• 客户端检测规则化：基于路径/域名/邮箱关键词的规则匹配，可能存在误判
• 依赖 OpenClaw 生态：需特定目录结构与 .jsonl 格式，通用性受限
• 无实时监控：仅支持事后分析，非流式监控工具

适合人群

• OpenClaw 重度用户需优化 API 成本
• 平台管理员需生成团队/个人令牌消耗报告
• 开发者调试特定会话的异常高消耗行为
• 需满足数据合规要求的本地化审计场景

常规风险

• 数据敏感性：解析的会话内容可能包含敏感信息，输出目录需适当权限控制
• 归因误差：工具令牌分摊机制可能导致成本估算偏差，不宜直接用于财务结算
• 版本兼容性：依赖 OpenClaw 特定的 usage 字段格式，升级后可能需适配

核心用法

Token Counter 是一款专为 OpenClaw 生态设计的本地 Token 用量分析工具。用户通过命令行调用脚本，可指定时间周期（如 1d、7d、30d）生成用量报告，支持按类别（category）、客户端（client）、模型（model）、工具（tool）等多维度拆解数据。高级用法包括：聚焦特定维度组合分析（--breakdown tools,category,client）、单会话深度钻取（--session）、JSON 格式导出（--format json），以及每日快照持久化（--save）用于长期趋势追踪。

数据源自本地 OpenClaw 目录：sessions.json 索引文件、.jsonl 会话转录文本及 cron/jobs.json 定时任务定义。解析器读取助手消息的 usage 字段统计 Token，通过工具调用记录完成归属分配。

显著优点

1. 纯本地隐私安全：全程离线运行，零网络通信，用户敏感会话数据永不外泄，天然符合 GDPR 数据最小化与本地化处理要求。

2. 零依赖轻量部署：仅依赖 Python 标准库，无第三方包安装负担，部署简单，兼容性强，避免因依赖项更新导致的维护风险。

3. 精细化成本归因：支持主会话、定时任务（cron）、子代理三级会话类型识别，结合启发式工具 Token 分摊算法，帮助用户准确定位高消耗环节。

4. 灵活输出与自动化：支持控制台报表、JSON 结构化导出及每日自动快照，便于集成至现有数据 pipeline 或 BI 工具做二次分析。

潜在缺点与局限性

1. 归因算法局限：工具 Token 分配采用启发式均摊（assistant-message tokens 按工具调用数拆分），无法精确到单次工具调用的真实消耗，极端场景下可能存在统计偏差。

2. 客户端识别规则化：personal/bonsai/mixed/unknown 四类客户端判定基于路径、域名、邮箱等规则匹配，对自定义部署或边缘场景的识别准确率受限。

3. 数据源单一：仅支持 OpenClaw 原生数据格式，无法直接接入其他 LLM 平台（如 OpenAI API、Anthropic）的用量数据，跨平台用户需自行转换格式。

4. 无实时监控能力：基于事后分析设计，不支持实时流式统计或阈值告警，需配合外部定时任务实现准实时监控。

适合的目标群体

• OpenClaw 重度用户：日活跃会话多、Token 消耗量大，需定期审计成本结构的个人开发者或小型团队。
• 运维与 SRE 工程师：负责多代理系统资源调度，需通过 cron 任务自动化生成日报/周报的场景。
• 成本敏感型组织：在模型选型与工具调用策略上寻求优化依据，需数据驱动决策的产品经理或技术负责人。
• 合规审计人员：需证明数据处理活动符合隐私法规，依赖纯本地工具的合规证据链。

使用风险

1. 性能风险：长期积累的大量 .jsonl 文件（如 30 天以上的高频会话）可能导致解析耗时增加，建议定期归档历史数据或缩短分析周期。

2. 数据完整性依赖：若 OpenClaw 会话转录文件被手动修改或损坏，统计结果将不准确；--save 持久化功能虽可备份每日快照，但需用户自行管理存储空间。

3. 版本兼容性：OpenClaw 数据格式若在未来版本变更，可能导致解析失败，需关注官方更新并及时升级 Skill 版本。

4. 误删风险：--save 输出目录为 $OPENCLAW_WORKSPACE/token-usage/，若该环境变量未正确设置或指向系统关键目录，可能引发意外覆盖，建议在首次使用前验证路径配置。