tokentab命令行7大用法全解析：快速查看Claude Code、Codex和Gemini CLI的Token用量与成本

tokentab 是一款完全本地运行的命令行工具，它直接读取 Claude Code、Codex 和 Gemini CLI 留在磁盘上的会话日志，自动汇总你的 Token 用量与美元成本，并按模型、项目、日期和活动类型分组展示——无需注册账号、无需 API Key，数据永不离开你的电脑。

1 分钟快速安装：一条命令跑起来

tokentab 用 Python 编写（需 Python 3.10+），唯一的第三方依赖是 rich（用于终端表格），Web 仪表盘则完全基于 Python 标准库，没有任何额外框架。

git clone https://gitcode.com/gh_mirrors/toke/tokentab
cd tokentab
pip install .

安装完成后，tokentab 命令就会出现在你的 PATH 中，随时可用。

用法一：直接运行，30 秒看本周花费

不带任何参数直接运行，默认展示最近 7 天全部工具的汇总报告：

tokentab

终端里会依次输出：总成本、总 Token 数、调用次数、缓存命中率，以及按工具、按模型、按项目、按活动、按天数的分组表格。没装的工具会被自动跳过，你只会看到自己真正在用的那几项。

它读取的日志位置如下：

工具	日志位置
Claude Code	~/.claude/projects/**/*.jsonl
Codex	~/.codex/sessions/**/rollout-*.jsonl
Gemini CLI	~/.gemini/tmp/**/session-*.json

用法二：按时间段过滤——今天、本月还是全部历史

最常用的时间参数（参数定义见 tokentab/report/aggregate.py）：

tokentab -today          # 只看今天
tokentab -month          # 本月（自然月）
tokentab -p all          # 全部历史用量

用法三：锁定单一工具或单个项目

tokentab --provider claude      # 只看 Claude Code 的花费
tokentab --project myapp        # 只看 myapp 这一个项目

--project 支持模糊匹配项目路径，适合回答"这个项目这个月烧了多少钱"这类问题。

用法四：自定义日期区间

想对比某两周或某个迭代的开销？用 --from / --to 圈定任意时间窗口：

tokentab --from 2026-06-01 --to 2026-06-15

用法五：导出 JSON，喂给下游工具

加上 JSON 输出参数后，报告以机器可读格式打印，可以随意管道处理，例如 tokentab --json | jq .。输出结构与 Web 仪表盘 /api/report 接口完全一致（序列化逻辑见 tokentab/report/serialize.py），方便写自动化脚本或接入自己的报表系统。

一个贴心细节：输出被管道时颜色码会自动剥离，直接粘贴进 PR 或聊天窗口不会带出一堆转义字符。

用法六：-web 一键启动本地仪表盘

tokentab -web

命令会启动一个本地 Web 服务并自动打开 http://localhost:4747，把同样的数据渲染成一张"月度账单"：总额在顶部，按工具、模型、项目、活动和日期逐项列出。几个值得知道的点：

• 只绑定 localhost：服务仅监听本机，不会对外暴露，数据同样不会上传
• 每次请求都从磁盘重读：数据量很小，不缓存就不会有"看到旧数据"的风险
• 完全离线可用：不拉取 CDN 字体，断网也能打开
• 零框架：基于 Python 标准库 http.server 实现，没有 Flask 之类的依赖（实现在 tokentab/web/server.py）

可选参数：--port 指定端口，--no-open 不自动弹出浏览器。

用法七：看懂成本口径，数字才可信

tokentab 的数字不是估算，而是逐条来自日志记录的真实 token 数，计价逻辑集中在两个文件：

• 价格表：tokentab/pricing/prices.py——手工维护的美元/百万 token 表，刻意不联网查价，宁可数字稍旧也不会在厂商改名模型时崩溃；匹配是模糊的，claude-opus-4-6-20260514 也能对上 claude-opus-4-6
• 缓存去重：Claude 的缓存读/写被单独计价，Gemini 的 input 含缓存部分，tokentab 会在计价前把缓存 token 剥离，避免同一批 token 被收两次钱

如果某个模型显示 $0.00，说明名称没匹配上价格表（而不是免费），在表里加一行即可修复。

另外，报告里的"活动类型"（coding / debugging / refactor / testing 等）是基于工具调用和首条消息关键词的规则推断（tokentab/classify.py），不调用任何模型——它是个提示，不是定论。

看懂输出：3 个值得留意的信号 📌

跑几次之后，可以关注这些模式（这也是 tokentab 输出真正有价值的地方）：

1. 缓存命中率持续低于 80%：上下文可能在调用之间不稳定，或缓存没开
2. 大模型吃掉大量小调用的成本：也许便宜模型一次就能搞定这些活
3. "chat / exploring" 占比过高：钱花在闲聊和读代码上，有时是正常，有时是会话跑偏了

写在最后

三个解析器（Claude / Codex / Gemini）都遵循同一套接口：把各自的日志格式转成统一的 UsageRecord，下游的计价、分组、仪表盘全部复用，因此想支持新工具只需在 tokentab/providers/ 里写一个模块。对于每天用 AI 编码工具的人来说，花 1 分钟跑一次 tokentab，比月底看到账单账单时"哇"出来要健康得多。