Claude Code token 消耗统计与成本监控：ccusage 工具实战指南

1. 为什么你需要 ccusageClaude Code 的 token 账单是个黑盒用过 Claude Code 的朋友应该都有这种感觉代码倒是写得飞起但 token 消耗就像流水一样哗哗往外淌你根本不知道钱花哪了。官方后台的 Usage 页面数据延迟严重而且只显示总量不告诉你具体是哪个项目、哪次会话烧掉了 80% 的额度。等你发现时候往往已经超预算了。我一开始也以为“反正 CLI 工具嘛省不了几个 token”直到某个月账单出来才发现自己用 Claude Code 重构一个老模块光是一次失败的会话就白烧了两万多 token。从那之后我就意识到在 CLI 工具上跑大模型成本可视化和代码可视化一样重要。而 ccusage 就是目前我在用的专门针对 Claude Code 的本地 token 统计工具开源、免费、直接解析本地日志不用往第三方传任何数据。这个工具能干什么说简单点就是三件事统计你每天/每项目/每模型的 token 消耗算出对应的美元成本再用终端图表直观展示出来。它不依赖云端 API不需要额外配置装完就能用。适合谁如果你是 Claude Code 的重度用户、用 API 按量付费的开发者、或者团队里需要统计 AI 编码成本的同学这工具基本属于刚需。2. 核心逻辑拆解ccusage 是拿什么数据算账的2.1 数据来源Claude Code 的 JSONL 会话日志ccusage 不拦截网络请求也不 hook 模型调用它干的事情其实很朴素读 Claude Code 写在本地的日志文件。Claude Code 每次会话都会在~/.claude/projects/目录下按项目名生成文件夹里面存着完整的 JSONL 会话记录。每一行是一个事件包含消息类型、模型名称、token 用量、时间戳等原始字段。我之前一直没注意这个目录的存在直到有次想排查一次“上下文被截断”的问题翻到~/.claude/projects/才发现里面早就把每次请求的 input_tokens、output_tokens 记得明明白白。ccusage 就是把这些散落在本地各个项目目录里的 JSONL 文件汇总起来统一解析、聚合、展示。注意ccusage 统计的 token 数据是“Claude Code 实际上报到日志里的用量”理论上和 Anthropic 后台的计费用量是一致的数据源。但因为本地日志有清理周期如果你手动删过~/.claude/projects/里的文件统计数据就会缺失。2.2 token 分类input、output、cache 各算各的账光看“token 总数”其实不够Claude 的计费是分类型的。ccusage 的输出里会把 token 拆成几类input tokens你发给模型的上下文内容折算的 token 数包括系统提示词、工具定义、对话历史、代码片段。output tokens模型生成的回复内容折算的 token 数包括代码、解释、工具调用请求。cache creation input tokens第一次写入缓存时消耗的输入 token写缓存按输入价格计费。cache read input tokens命中缓存时读取的输入 token价格只有普通输入的十分之一左右。这个分类太关键了。因为 Claude Code 默认会启用 prompt caching你在一个会话里反复让 AI 修改同一个文件时大部分历史上下文其实是从缓存里读的计费价格远低于普通输入。如果只看总 token 数你可能会误判某个长会话“烧钱太狠”但看分类后会发现 cache read 占了大头实际成本并没那么夸张。ccusage 在计算成本时会在内部套用当前模型对应的价格表再分别计算各类 token 的费用并求和。所以它的成本估算比你自己拿总数乘以单价准确得多。2.3 输出指标从 token 到美元账单ccusage 跑完后会在终端里打印一张汇总表字段大概长这样指标含义tokens总 token 数所有类型相加input_tokens普通输入 token 数output_tokens输出 token 数cache_creation_input_tokens写入缓存的输入 token 数cache_read_input_tokens读取缓存的输入 token 数cost估算成本美元total_cost_usd累计估算成本用--json参数还能输出结构化数据方便你自己接脚本做二次处理。我通常会在月底跑一条ccusage --json | jq .total_cost_usd直接把当月 CLI 编码成本填进报销单省得自己对着官网后台一个个加。3. 实操从安装到日常看板3.1 安装Brew 和 npm 两条路ccusage 的安装在 macOS 上最简单官方推荐用 Homebrewbrew install ccusage装完直接跑ccusage就能看到默认输出。如果你用的是 npm 环境比如你本来就装了 Node.js也可以走 npmnpm install -g ccusage注意npm 版的更新可能比 brew 版慢半拍。ccusage 的迭代速度不慢我建议两个渠道都留意一下如果 brew 版出现奇怪的解析报错可以先升级 npm 版试试。Windows 用户我试过 WSL2 里装 brew能跑但步骤稍繁琐。如果你只是在 Windows 上用 Claude Code也可以考虑直接跑npx ccusage只要 Node 环境在就行。3.2 基础用法先跑通默认统计装好后不需要任何配置直接执行ccusage输出会按“天”维度汇总最近一段时间的 token 和成本桌面上能看到一张柱状图对应每天的消耗量。柱状图的长度对应成本大小颜色区分不同的 token 类型。我第一次跑的时候最直观的感受是柱状图里成本最高的那天不是代码写得最多的一天而是我在同一个会话里反复让 AI 调试一个诡异 bug 的那天。这也验证了 ccusage 的价值——它能让你把“高消耗”和“具体行为”对上号。3.3 按项目统计精确定位烧钱大户日常我用的最多的参数是--projectccusage --project这会按项目目录名分组统计每个项目的 token 消耗和估算成本。输出会列出项目名、token 总量、成本金额按成本降序排列。这个命令对我意义很大。因为我经常在多个仓库之间切来切去有些项目只是临时查个文档有些项目是持续一周的重构。跑一次--project谁是“吞 token 怪兽”一目了然。比如我有次发现一个项目的成本占比高达 60%原因是我一直在那个仓库里开了好几个长会话每个会话都带着巨大的上下文导致重复输入 token 爆炸。3.4 时间范围过滤只看某一天或某一周如果你想精确看某一天的数据ccusage --day 2025-05-20或者看某一天到某一天ccusage --start-date 2025-05-01 --end-date 2025-05-31我自己的习惯是每周五下午跑一次ccusage --start-date 本周一 --end-date 本周五把周报里的“本周 AI 辅助开发成本”填上。以前这个是拍脑袋估的现在有数据支撑说话都硬气一点。3.5 详细日志与 JSON 输出二次处理和排查--log参数会打印出每一条会话事件级别的 token 明细非常啰嗦但排查问题时有奇效。比如你想知道某一天到底哪次调用的 output token 特别大就可以用--log配合日期过滤来看。--json是给脚本用的ccusage --json ccusage_report.json输出 JSON 里每个项目、每天的 token 分类和成本都是结构化字段方便你用 jq、Python 脚本做聚合、出图表、甚至接进内部监控系统。4. 进阶玩法把 ccusage 变成自己的成本监控台4.1 按模型维度分析哪个模型在吃预算Claude Code 支持切换不同模型Opus、Sonnet 等不同模型单价差别巨大。ccusage 支持按模型名过滤统计命令是ccusage --model claude-sonnet-4-20250514我只在“某个模型疑似异常消耗”的时候才用这个参数。比如有次发现某天成本异常高用--model过滤后确认是 Sonnet 跑了一个超长重构而不是 Opus 被误用心里踏实不少。4.2 配合 shell 别名一键看账单ccusage 的参数有点多每次打全称不现实。我在~/.zshrc里加了几个别名alias ccuccusage alias ccudccusage --day $(date %Y-%m-%d) alias ccumccusage --start-date $(date -v1d %Y-%m-%d) --end-date $(date %Y-%m-%d)这样我每天下班前敲ccud看当天消耗每月底敲ccum看整月汇总基本十秒钟完成成本复盘。4.3 写个简单的 Python 脚本做趋势图ccusage 的--json输出可以直接喂给 Python。我写过一个不超过 30 行的小脚本用 matplotlib 画每天成本趋势折线图每周自动跑一次截图发到团队群里作为共享信息。脚本逻辑很简单把 JSON 里的 daily 数据解析成日期-成本序列然后绘图。这就让 ccusage 从“个人工具”变成了“团队透明化工具”leader 不用再单独问每个人“你这周 AI 编码花了多少”。4.4 与官方 Usage 页面配合使用ccusage 统计的是本地日志官方后台统计的是服务端计费。两者偶尔对不上原因可能是本地日志清理、批量请求合并等。我的经验是以官方后台为最终账单依据ccusage 为过程分析和行为优化依据。哪怕数字差一点ccusage 的价值也在于帮你找出“哪个项目哪类操作在烧钱”官方后台给不了这种细化视角。5. 常见问题与排查技巧实录5.1 安装失败brew 找不到 formula如果你用brew install ccusage报错找不到包先执行brew update刷新一下仓库索引。ccusage 进 Homebrew 官方仓库的时间不算早老索引里没有很正常。如果 update 完还是找不到可以去 GitHub Releases 页面下载对应平台的二进制文件手动放到 PATH 里。5.2 解析报错日志文件格式变了ccusage 依赖 Claude Code 日志的 JSON 结构Claude Code 版本升级后偶尔会调整字段格式导致 ccusage 旧版本解析失败或数值为 0。这时候直接升级 ccusage 最新版基本能解决。如果升级后仍然报错可以去 GitHub Issues 搜关键词这种问题通常修复很快。5.3 统计缺失日志文件被清理如果你发现 ccusage 统计的 token 总量明显小于官方后台的数据先检查~/.claude/projects/里的文件数量和日期范围。Claude Code 可能会在会话关闭后一段时间自动清理旧日志或者你手动清理过。ccusage 只能统计“现在还存在的日志”所以历史缺失是正常的不代表工具坏了。5.4 登录报错与 ccusage 无关最近很多人在热搜里反馈“sign-in could not be completed token exchange failed”或“token endpoint returned 403 status: country”之类的报错这种通常是 Claude Code 登录阶段的问题和 ccusage 没有任何关系。ccusage 只是读本地日志不触发登录也不发网络请求。如果你遇到这类登录失败先检查账号区域、订阅状态、网络环境不要误以为是 ccusage 引起的。5.5 成本估算感觉不准ccusage 的成本估算是基于内置价格表如果 Claude 调整了定价而 ccusage 还没更新估算就会偏。另外 Anthropic 的计费规则有阶梯和折扣比如批量 API、承诺用量折扣这些 ccusage 不会考虑所以它给出的 cost 只能当成“估算参考”不能当发票金额。我一般会在心里给 ccusage 的成本乘以一个 1.2 的安全系数。6. 省 token 的几个实战建议配合 ccusage 使用效果更佳ccusage 帮你“看清”消耗之后下一步就是“省”。我自己实践下来这几个习惯最有效长会话及时刹车。如果 ccusage 显示某个项目本周成本暴涨八成是你长时间保持一个会话反复让 AI 读取大文件。claude code 的/compact可以压缩上下文但更好的做法是每个功能点开一个新会话不要一个会话干三天。缓存命中率是省钱的钥匙。Claude Code 自带 prompt caching你要做的就是尽量让系统提示词和常用上下文放在会话早期这样后续请求的 cache read 占比高单价低。ccusage 的分类输出里如果 cache_read_input_tokens 占比特别低说明你的会话结构有优化空间。区分重活和轻活。简单问题用默认模型就够了大规模重构再切到更强的模型。ccusage 按模型统计的功能能帮你复盘到底在哪些场景用了高单价模型值不值。别自动接受工具链的无脑操作。CLI 里 AI 经常会把大目录的读取、搜索、文件列表反复执行每次都计入 input tokens。配合--permission-mode限制工具权限能明显减少无效 token 消耗。7. 其他统计工具对比ccusage vs 官方 vs 自建市面上的 Claude Code 用量统计方案大概有三种方案优点缺点ccusage本地解析、免费、维度全、有图表依赖日志文件、成本是估算值官方 Usage 页面数据准确、无延迟只给总量、不给项目/会话粒度、到账有延迟自建脚本完全自定义维护成本高、容易漏字段如果你只是偶尔看一眼消费“官方后台就够了”这句话没毛病。但如果你和我一样天天用 Claude Code 写代码、甚至团队里多个人共用账号那 ccusage 这种本地粒度工具就是刚需。它给你的是“可行动的信息”——知道哪类工作烧钱才能决定怎么调整工作方式。8. 写在最后的经验心得ccusage 这个工具本身不复杂第一次跑出报表可能也就十分钟的事。但它带来的观念转变是真切的在 AI 编码时代“代码效率”不再是唯一指标“token 效率”同样重要。你写一段代码可能只花了两分钟但如果上下文管理不当这两分钟可能烧掉了相当于十几分钟人工成本的 token。我现在的固定流程很简单每天下班前ccud扫一眼当日消耗每周五ccum看整周趋势每月底导出 JSON 存档。出现异常波动时先用--project定位项目再用--log看具体会话。这套流程撑起我对 AI 编码成本的掌控力没有一次超预算事故。当然我踩过的坑你也可能踩到——安装路径、版本不匹配、日志被清理、价格波动——文章里都提到了提前避开就行。如果你有更骚的玩法比如把 ccusage 接到企业监控平台欢迎去项目仓库交流这类工具的价值往往是在用户分享中逐渐长出来的。