tokentab

这是什么？适合谁？

TokenTab（damejan80/tokentab）是一个读取 AI 编程 Agent 本地会话日志、统计 token 成本的命令行工具。它针对的是「Agent 用量失控」这个日益普遍的问题：Claude Code、OpenAI Codex、Gemini CLI 这些编码 Agent 在你本地硬盘上留下了大量会话日志，但没人把它们变成「钱」。

核心价值：把散落在本地日志里的 token 消耗，聚合成按模型、项目、天三个维度的成本报表，回答「这个月 Agent 到底花了我多少钱、花在哪个项目、哪个模型最烧钱」。

适合人群：

• 个人开发者：想知道自己一个月在 Agent 上的真实 API 开销
• 团队负责人 / 成本管控：需要按项目、按成员审计 Agent 用量
• 在多个 Agent（Claude Code / Codex / Gemini CLI）之间切换、想统一看账单的人

使用前提：本机已使用过上述任一 CLI Agent（有日志可读）；Python 环境；理解「读取本地日志」意味着数据只在你机器上处理。

准备工作

1. Python 3.10+：工具主体用 Python 编写（GitHub API 实测语言 Python）。
2. 已产生的 Agent 会话：先跑过 Claude Code / Codex / Gemini CLI，本地存在 .claude、.codex、.gemini 等日志目录。
3. 成本：MIT 开源，完全免费，本地运行、无云端上传。
4. 时间预算：安装 + 首次统计约 10 分钟。
5. 心智准备：它只做「统计与汇总」，不做 token 限额、不做自动断网；如需限流需另配网关。

快速上手（3 步）

第一步：安装

git clone https://github.com/damejan80/tokentab
cd tokentab
pip install -r requirements.txt   # 具体依赖以 README 为准

第二步：扫描会话日志

python tokentab.py scan --days 30

工具会自动发现本机各 Agent 的日志目录，逐条解析会话记录。

第三步：查看成本报表

python tokentab.py report

成功判定：终端输出一张按模型 / 项目 / 天分组的 token 与预估成本表；你能立刻说出「上个月在哪个项目花了最多钱」。

初级用法

三个统计维度

• 按模型：对比 Claude Sonnet / Opus、GPT-5、Gemini 各自的 token 与成本占比
• 按项目：把日志按仓库 / 工作目录归组，定位「哪个项目最烧钱」
• 按天：看趋势曲线，发现「哪几天 Agent 空转」或「哪几天在跑大重构」

成本估算口径

工具把 token 用量乘以各模型的公开定价得到估算成本。注意这是估算值——输入/输出 token 价差、缓存命中（cache hit）折扣、批量折扣都可能影响真实账单，建议与供应商账单对账后校准。

高级玩法

多 Agent 统一视图

在 Claude Code、Codex、Gemini CLI 之间切换的人，可以用一个命令拿到跨 Agent 的统一账单——不再需要分别去各家控制台翻用量页。

团队成本审计

把日志目录指向共享盘 / CI 机器的日志，就能做团队级汇总：谁的项目、谁的 Agent 会话消耗最多。适合需要「用量审计 + 成本分摊」的小团队。

与限流网关组合

TokenTab 负责「看见」，限流网关负责「控制」。先用它找出失控的模型或项目，再在网关层针对性设限。

小技巧

1. 先 scan 后 report：scan 解析日志、report 汇总展示，两步分开便于增量扫描。
2. 限定时间窗：--days 参数控制回溯范围，避免初次扫描把半年日志全部拖进来。
3. 对账校准：首次跑完拿结果和供应商账单比对，修正定价口径后再长期使用。
4. 数据只在本机：解析全部本地完成，敏感会话不上传。
5. 定期跑：设一个 cron 每周跑一次，用量失控时能第一时间发现。

常见踩坑

踩坑 1：scan 找不到日志

• 现象：运行后输出为空或报「未发现会话」。
• 原因：Agent 日志目录不在默认路径，或你还没用 CLI Agent 跑过任务。
• 解决：先确认各 Agent 日志目录存在；自定义路径时按 README 传入 --log-dir。

踩坑 2：把估算成本当真账单

• 现象：统计数字和供应商账单对不上。
• 原因：缓存命中、批量折扣、输入/输出价差都会造成偏差。
• 解决：把 TokenTab 结果当「量级参考」，真实成本以供应商账单为准并定期校准。

踩坑 3：日志格式变更后解析失败

• 现象：Agent 升级后某些会话解析不出或字段错位。
• 原因：各家 CLI 日志格式不保证稳定，可能随版本变化。
• 解决：跟进仓库 issue / 更新，遇到解析异常回退到上一版本日志格式。

踩坑 4：跨模型定价口径不同

• 现象：同一 token 数在不同模型下成本差异巨大。
• 原因：模型单价本身差异大（如 Opus vs Haiku）。
• 解决：报表必须按模型拆分看，不要只看总量。

踩坑 5：误以为它有实时拦截能力

• 现象：期待它能自动限制或阻止超支。
• 原因：它是离线统计工具，不参与运行时调用链。
• 解决：需要硬性限额请另配网关 / 平台配额。

常见问题 FAQ

Q1: 支持哪些 Agent？

A: 面向 Claude Code、OpenAI Codex、Gemini CLI 的本地会话日志；具体支持矩阵以仓库 README 为准，新增 Agent 支持通常以解析器插件方式加入。

Q2: 数据会上传到云端吗？

A: 不会。工具在本地解析日志、本地汇总，无云端服务。

Q3: 成本数字准吗？

A: 是「估算」而非「账单」——按公开定价 × token 用量计算，未计入缓存折扣与批量价，建议与供应商账单对账校准。

Q4: 适合团队用吗？

A: 适合小团队做用量审计；把各成员日志汇总到一处即可看团队级视图，但涉及隐私与合规时需自行控制访问。

Q5: 和平台自带的用量面板有什么区别？

A: 平台面板只能看单一产品的用量；TokenTab 把多个 Agent 的本地日志统一成一个视图，并按项目维度归组。

进阶学习建议

掌握基础后，建议深入：

1. 成本基线 + 告警：用 TokenTab 每周报表建立「人均 / 项目 Agent 成本基线」，偏离超过阈值再人工介入。
2. 多 Agent 选型决策：用按模型拆分的数据，判断「换更便宜的模型」或「换 Agent」能省多少，让选型有数据支撑。
3. 日志归档审计：把关键时段的报表归档，作为团队成本追溯与预算申报的依据。

参考链接

• 官方仓库

最后更新：2026-08-28 · 作者：MagicNetWorld · 基于公开资料整理，关键数据经 GitHub API 独立实测核验，AI 辅助生成