企业官网建设流程全解析

1. 为什么你需要 ccusage：Claude 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 跑完后会在终端里打印一张汇总表，字段大概长这样：

用--json参数还能输出结构化数据，方便你自己接脚本做二次处理。我通常会在月底跑一条ccusage --json | jq '.total_cost_usd'，直接把当月 CLI 编码成本填进报销单，省得自己对着官网后台一个个加。

3. 实操：从安装到日常看板

3.1 安装：Brew 和 npm 两条路

ccusage 的安装在 macOS 上最简单，官方推荐用 Homebrew：

brew install ccusage

装完直接跑ccusage就能看到默认输出。

如果你用的是 npm 环境（比如你本来就装了 Node.js），也可以走 npm：

npm 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 按项目统计：精确定位烧钱大户

日常我用的最多的参数是--project：

ccusage --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 ccu="ccusage" alias ccud="ccusage --day $(date +%Y-%m-%d)" alias ccum="ccusage --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 用量统计方案大概有三种：

如果你只是偶尔看一眼消费，“官方后台就够了”这句话没毛病。但如果你和我一样，天天用 Claude Code 写代码、甚至团队里多个人共用账号，那 ccusage 这种本地粒度工具就是刚需。它给你的是“可行动的信息”——知道哪类工作烧钱，才能决定怎么调整工作方式。

8. 写在最后的经验心得

ccusage 这个工具本身不复杂，第一次跑出报表可能也就十分钟的事。但它带来的观念转变是真切的：在 AI 编码时代，“代码效率”不再是唯一指标，“token 效率”同样重要。你写一段代码可能只花了两分钟，但如果上下文管理不当，这两分钟可能烧掉了相当于十几分钟人工成本的 token。

我现在的固定流程很简单：每天下班前ccud扫一眼当日消耗，每周五ccum看整周趋势，每月底导出 JSON 存档。出现异常波动时，先用--project定位项目，再用--log看具体会话。这套流程撑起我对 AI 编码成本的掌控力，没有一次超预算事故。当然，我踩过的坑你也可能踩到——安装路径、版本不匹配、日志被清理、价格波动——文章里都提到了，提前避开就行。如果你有更骚的玩法，比如把 ccusage 接到企业监控平台，欢迎去项目仓库交流，这类工具的价值往往是在用户分享中逐渐长出来的。