1. 为什么每个 Claude Code 重度用户都需要 ccusage
先说说我自己的情况。大概从 Claude Code 正式对外开放后，我就把它接进了日常的编码流程里，写脚本、重构老项目、写测试用例，甚至排查线上问题都会丢给它。一开始用得确实爽，但两周后看到账单时，人直接麻了——我完全不知道这些 token 到底花在了哪里，哪些会话吃掉了大部分额度，是某个长时间挂着的重构任务，还是某次没注意上下文长度的闲聊式调试。
Claude Code 本身在终端里会展示单次请求的 token 用量，也会在会话结束时给一个大概的统计，但这些都是“当下”的、碎片化的。我想要的是一个能汇总、能按天/按会话/按项目维度查看全局消耗的工具，最好还能看到成本。这时候我找到了 ccusage，一个专门为 Claude Code 设计的 token 用量统计工具。它通过解析 Claude Code 在本地留下的会话日志文件，把所有请求的 token 消耗、成本、耗时、模型信息、会话标题全部整理成一张表，直接在终端里展示出来。
ccusage 对我这种需要控制预算、给团队做用量归因、又不想自己写脚本解析 jsonl 的人来说是刚需。它解决的问题很明确：你不知道自己的 Claude Code 额度花在哪、花了多少、什么时候花的。如果你是 Claude Code 的重度用户，或者你所在的小团队正在评估是否要批量使用 Claude Code，这个工具一定要先装一个。下面我会从安装、日常使用、核心原理、常见报错排查到进阶玩法完整过一遍，尽量把我踩过的坑也一起说清楚。
2. 安装与环境准备：三分钟跑起来
2.1 前提条件：Node.js 版本别太老
ccusage 是用 Node.js 写的命令行工具，通过 npm 分发，所以装它之前你得先确认本机有 Node.js 环境。我建议 Node.js 版本至少 18 以上，npm 9 以上，太低容易出现依赖安装失败或者某些语法不支持的情况。
node -v npm -v如果你还没装 Node.js，去官网下载 LTS 版本装好就行，或者用 nvm 管理版本。这里有个小建议：如果你的机器上同时有好几个 Node.js 项目，尽量用 nvm，避免全局包权限和版本冲突的问题，后面装 ccusage 时能省不少麻烦。
2.2 全局安装 ccusage
ccusage 直接通过 npm 全局安装：
npm install -g ccusage装完以后执行：
ccusage --version如果能看到版本号，说明安装成功。如果你使用的是 macOS 或 Linux，npm 全局安装目录可能不在当前用户的 PATH 里，装了之后提示command not found，这时候需要把 npm 的全局 bin 目录加进 PATH。用下面的命令查看：
npm bin -g把输出的目录加进 shell 配置文件里，比如~/.zshrc或~/.bashrc。
注意：如果你是用 sudo 安装的，文件权限可能会乱。我踩过这个坑：后面升级 ccusage 时总提示 EACCES 权限错误，后来干脆把全局 node_modules 目录的属主改回当前用户，才解决了。具体操作是用
sudo chown -R $(whoami) $(npm prefix -g)修复。
2.3 确认 Claude Code 的日志目录存在
ccusage 的原理是解析 Claude Code 的会话日志，所以你的机器上必须先装好 Claude Code，并且至少跑过一次会话，让日志文件生成出来。Claude Code 的日志默认存放在：
- Linux / macOS：
~/.claude/projects/ - Windows：
%USERPROFILE%\.claude\projects\
你可以手动看一下：
ls ~/.claude/projects/如果这个目录不存在，说明你还没有创建过任何会话，或者 Claude Code 版本太老，先跑一次对话再回来。
进入项目目录后，你会看到一堆以项目路径编码后的名称命名的文件夹，比如-Users-admin-test-project这样的名字。里面是*.jsonl文件，每个文件对应一个会话的全部消息记录。ccusage 就是靠读取这些 jsonl 里的 token 使用字段来统计的。
3. 日常使用与命令速查：终端里的用量报表
3.1 第一次运行
安装完成后，直接在任意目录下执行：
ccusage它会扫描默认的~/.claude/projects目录，然后把最近一段时间的会话用量列出来，默认大概是最近 30 天（具体默认窗口看版本，建议用参数显式指定）。输出的每一行就是一个会话记录，包含会话标题、模型、日期、输入 token、输出 token、成本、耗时这些信息。
第一次看到这张表的时候，我最大的感受是“原来钱都花在这些地方了”。有一次我发现某个会话成本到了十几美元，点开一看是当时让 Claude Code 帮我重构一个 8000 多行的旧模块，中间连续对话了快一百轮，缓存没怎么利用起来，全在硬算。
3.2 核心参数：按天、按会话、按成本
ccusage 的命令行参数不多，但每一个都好用，我整理了一张速查表：
| 命令/参数 | 作用说明 | 例子 |
|---|---|---|
/today | 只看当天的用量 | ccusage /today |
/days N | 只看最近 N 天的用量 | ccusage /days 7 |
/all | 看全部历史会话 | ccusage /all |
--limit N | 限制输出条数 | ccusage --limit 20 |
--cost | 显示会话对应成本 | ccusage /today --cost |
--match 关键词 | 筛选标题含关键词的会话 | ccusage --match "重构" |
--sort | 按指定字段排序（如 cost） | ccusage --sort cost |
--json | 输出 JSON 格式，方便脚本处理 | ccusage /days 7 --json |
其中--json是我最推荐重度用户研究的。因为纯看终端列表，你只能做“看”这个动作，但把数据导出成 JSON 后，你可以自己写脚本做每日推送、自动周报、甚至是异常预警——比如某天 token 用量突增，自动给你发个提醒。
3.3 一个完整的工作流示例
我每天下班前会跑这么一条命令：
ccusage /today --cost --sort cost它会列出今天所有会话，成本最高的排在最前面。看到某条成本异常高的记录，我会当场点进去看看是不是有会话还在后台挂着没关，或者是不是某次任务上下文撑得太长。
每周五我再跑：
ccusage /days 7 --cost --json > ~/daily-notes/ccusage-weekly.json把这个 JSON 当作原始数据，简单用脚本统计一下本周总成本、按项目路径聚合的成本，手动维护一份周度预算表。如果你的机器上有 crontab，甚至可以做成定时任务，每天自动生成用量快照。
4. 核心原理拆解：ccusage 是怎么算出 token 的
4.1 它的数据源：本地 jsonl 日志
很多人用 ccusage 时有个疑问：它自己并没有发起任何一次 API 请求，为什么能知道 token 用了多少？答案在前面提到过，它读取的是 Claude Code 的本地会话日志，这些 jsonl 文件里每一行是一条消息记录。在这个记录里，Claude Code 会附带模型返回的 usage 信息，结构类似这样：
{ "message": { "usage": { "input_tokens": 1520, "output_tokens": 643, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 892 } } }这几个字段在 Anthropic API 的官方文档里都有定义：
input_tokens：本次请求中输入给模型的 token 数量，包含系统提示词和对话历史。output_tokens：模型本次生成的 token 数量。cache_creation_input_tokens：本次请求中，用于写入/创建 prompt 缓存的 token 数量。cache_read_input_tokens：本次请求中，直接从 prompt 缓存读取命中的 token 数量，这部分费用远低于普通输入。
ccusage 做的事情，就是把你可能已经忽略的这堆记录逐行读出来，把message.usage做累加，再根据模型类型和官方价格表换算成成本，最后在终端里渲染成表格。
4.2 成本计算的逻辑
ccusage 内置了一张模型价格表，会识别 jsonl 记录中的模型名称（比如claude-sonnet-4-20250514、claude-opus-4-20250514），然后按对应的单价算成本。
这里我单独提醒一句：不同模型的输入输出单价差异非常大。如果你在同一个会话里切换过模型，成本统计会按每条消息各自的模型来算，不会算错。但如果 ccusage 版本落后于 Claude 新发布的模型，它可能不认识新的模型 ID，这时候成本会显示为 0 或者按默认模型估算，遇到这种情况升级 ccusage 到最新版基本都能解决。
4.3 为什么比聊天窗口里的数字更可靠
不知道你有没有注意过，在 Claude Code 的交互界面里，每次回复下面都会显示一个 token 和耗时统计。那个数字是当下这一轮的用量，但如果你想统计一次完整任务消耗了多少，对话窗口里没有直接汇总。此外，Claude Code 历史上曾经有过一些版本在 UI 统计上把缓存的 token 合并显示，导致用户在主观上低估了成本。
ccusage 因为是基于 jsonl 逐行计算的，所以在“完整”和“可回溯”这两个维度上比 UI 展示更可靠。它统计的是真实落盘的数据。对于要写报销明细、给团队做成本归因的人来说，这个差别很重要。
4.4 我实际验证过它的准确性
为了放心，我做过一次对比测试：开一个新会话，跟 Claude Code 连续对话 10 轮，期间记录界面给到每一轮的 token 数字，结束后手动累加，再和 ccusage 对这个会话的统计做对比。数字基本对得上，误差主要来自服务端和本地记录之间的编码方式差异，但也就在几十个 token 之内，对成本估算没有任何实际影响。
注意：ccusage 统计的是 token 用量，不是额度扣减量。如果你用的订阅套餐，费用不会因为本地统计的数值而改变，最终以官方账户后台为准。但对绝大多数人来说，ccusage 已经足够用来做预算控制和用量监控了。
5. 常见报错与排查技巧实录
这部分我想重点讲一下，因为根据我看到的反馈，很多人在使用 Claude Code 过程中遇到的报错，都被误以为是 ccusage 引起的，其实 ccusage 本身几乎不太会触发认证相关的错误。但为了让大家少走弯路，我把常见的报错整理成了一张速查表，并附上我自己的排查过程。
5.1 报错速查表
| 报错信息 | 常见原因 | 解决办法 |
|---|---|---|
sign-in could not be completed token exchange failed: token endpoint returned | 登录时 OAuth token 交换失败，通常是网络环境或区域限制 | 检查网络出口区域是否在官方支持范围内，校准系统时间，清理认证缓存后重新登录 |
token exchange failed: token endpoint returned status 403 forbidden: country | 官方对部分地区限制访问，当前网络出口区域不受支持 | 确认网络环境是否满足官方要求，切换到官方支持的区域 |
your access token could not be refreshed. please log out and sign in again | access token 刷新失败，可能是订阅过期或本地认证缓存损坏 | 执行claude /logout，或手动删除~/.claude/.credentials.json后重新登录 |
login failed. check api token or gitlab version | 与 GitLab 相关，和 Claude Code 无关 | 如果你在配置 GitLab 类工具时看到这个报错，去检查 GitLab 的 Access Token 和版本兼容性 |
已达到输出 token 上限回答被截断 | 单次对话的输出 token 达到模型最大限制 | 拆分子任务，或使用 summary 压缩上下文，或调整max_tokens参数 |
error code token_exchange_failed | 认证流程中 token 交换失败，和上面的原因类似 | 和 5.1 第二/第三条相同，重置登录态后重试 |
5.2 登录态失效问题
我最常遇到的是第二种，也就是区域限制导致的 403。Claude Code 登录时会向认证服务器发起 token 交换请求，如果服务端判定你的请求来源区域不受支持，会直接返回 403。这个过程中最迷惑的地方在于，你第一次登录可能没问题，但过几天 access token 需要 refresh 时，同样的限制又会冒出来，表现形式就是那句your access token could not be refreshed。
我试过的有效解决办法是：先确认当前网络环境在官方支持范围内，然后清掉本地认证缓存重新登录一次。具体操作如下：
claude /logout rm -f ~/.claude/.credentials.json claude重新执行claude命令后，终端会引导你走一遍登录流程，新生成的凭证一般就正常了。
注意：删除
.credentials.json会使本机所有 Claude Code 会话的登录状态失效，你需要重新登录，这是安全的，不会影响云端已保存的会话历史。但如果你有多个账号在同一机器上切换，删除前记得先确认当前账号名。
5.3 ccusage 自身可能出现的两个小问题
ccusage 本身的报错不多，但有两个我在使用中遇到过：
一是版本太旧导致 JSON 解析失败。Claude Code 更新后，jsonl 文件里的消息结构偶尔会加点新字段，老版本的 ccusage 读取时可能报错或统计不准。解决办法很简单：npm update -g ccusage。
二是并发会话导致日志写入时序问题。如果你同时开多个 Claude Code 会话，某一个会话的日志可能还没 flush 到磁盘，这时候 ccusage 统计到的数字可能偏小。解决办法是等几秒再跑统计，或者用--json输出后重跑一次。
5.4 关于 credits 和 token 换算的常见疑问
很多人问“2500 credits 相当于多少 token”，这个问题没法直接回答，因为 credits 到 token 的兑换比例取决于模型和当前价格体系，而且不同档次的订阅计划计费逻辑也不一样。
但可以给大家一个粗略感受：如果你的订阅套餐附带一定量的 usage allowance，那么开通之后跑两三次ccusage --cost，对比官方后台显示的剩余额度变化，基本就能推算出自己一个请求大概的单价水平。我自己更建议的做法是：不必纠结单个 token 的单价，把它当成一个“总量/总成本”的黑盒，用 ccusage 看相对趋势和异常峰值，这才是统计工具的真正的价值。
6. 进阶玩法：把 ccusage 变成你的预算监控台
6.1 用 Bash 脚本生成每日用量日报
我写了一个简单的脚本，每天 22:00 自动汇总当天用量，并追加到一个 CSV 文件里：
#!/bin/bash cd ~/daily-notes date_str=$(date +%Y-%m-%d) ccusage /today --cost --json > "ccusage-${date_str}.json" # 用 jq 提取总成本 total_cost=$(jq '.total_cost // 0' "ccusage-${date_str}.json") session_count=$(jq '.sessions | length' "ccusage-${date_str}.json") echo "${date_str},${session_count},${total_cost}" >> ccusage-daily.csv如果你还没装 jq，先装一下，这个小小的命令行 JSON 解析工具在写这种脚本时几乎是必需品。比如在 macOS 上：
brew install jq这个脚本配合 crontab 每天自动执行，你就拥有了一份专属的 Claude Code 用量日历，月底做复盘时数据全在手边。
6.2 与 cc-switch 配合，实现多账号场景下的成本归因
如果你关注过 Claude Code 生态，应该知道 cc-switch 这个工具，它用来快速切换不同供应商或账号的配置。ccusage 和它其实不冲突，因为 ccusage 读的是日志目录，而 cc-switch 改的是配置文件。我个人的用法是：在切换账号后，用ccusage --json对比切换前后的用量变化，快速确认哪个账号、哪个配置在消耗额度。
6.3 异常用量检测的思路
另外一个进阶玩法是拿 ccusage 的输出来做异常检测。比如你给自己设定规则：单日成本超过 5 美元就算异常。那你完全可以写个脚本，定时调 ccusage 判断是否超过阈值，超过了就发个通知到手机。
daily_cost=$(ccusage /today --cost --json | jq '.total_cost') if (( $(echo "$daily_cost > 5.0" | bc -l) )); then # 触发你自己的通知逻辑 osascript -e 'display notification "今日 Claude Code 成本异常，请检查"' fi这个能力对做 AI 编码工具落地的小团队特别有用。因为只要有人开着长时间任务、或者写了个死循环让 Agent 持续迭代，成本就可能悄悄飙升。有监控总比月底看账单吓一跳要好。
6.4 个人经验：我如何用它守住预算
最后分享一点个人经验。自从用了 ccusage，我给自己定了三条规矩：
- 每周五查看一次周报（
ccusage /days 7 --cost），把超预算的项目记下来。 - 每个新任务开始前，先估一个预期的 token 量级，跑完后对比实际值。
- 如果某个会话成本超过 3 美元，我会主动复盘一下是不是上下文没控制好、缓存没利用上，还是任务拆分有问题。
一段时间下来，我对 Claude Code 的成本感知能力提高了很多，现在基本能预估一个任务大概要花多少钱，而不是每次都凭感觉开干。这种“心里有数”的状态，是我愿意把 ccusage 推荐给所有人的核心原因。
