1. 为什么我要装这个统计工具先说个真实场景。我平时重度使用 Claude Code 写代码、改 Bug、做 Code Review每天跟它在终端里闲聊式交互几十次。月初收到账单的时候发现 Api 模式的消费比我预想的高了不少但是具体高在哪、哪几天用量异常、哪个会话烧了最多 token我完全说不出来。官方面板只能看个大概趋势对于我这个靠代码吃饭、想精细控制成本的人来说完全不够。后来在某个技术社群里看到有人提了一嘴 ccusage说是专门用来统计 Claude Code 使用量的开源小工具能从本地日志里把 token 消耗、会话时长、每日请求次数这些数据全部解析出来。我当天就装上了用到现在大半年日常开销控制、月底对账、甚至判断某个功能值不值得继续用 Api 模式全靠它。这篇文章就把安装和配置的完整过程写下来给有同样需求的开发者一条可以直接走的路。先说清楚这个工具适合谁如果你只是偶尔在订阅额度内用 Claude Code不太关心成本那 ccusage 对你的价值不大但如果你经常开着 Claude Code 干活或者走 Api 按量付费又或者你想搞清楚自己的使用习惯到底是怎么分布的那这个工具基本是刚需。它本质上不是提升编码效率的工具而是帮你把 Claude Code 的使用行为数据化、可视化、可审计的工具属于“基础设施”那一层。2. 安装前的环境准备很多人栽在第一步不是命令敲错而是环境本身不过关。ccusage 虽然只是个命令行工具但它的运行依赖 Node.js而且对 Node 版本有最低要求。我先列一下我验证过的环境组合你照着检查一遍再动手比装到一半报错再回头排查要省事得多。2.1 Node.js 版本要求ccusage 在 README 里写的是要求 Node.js 18 及以上。我一开始没注意用的还是系统自带的 Node 16结果 npm 装的时候不报错一运行就提示语法错误查了半天才发现是版本太老。如果你不确定自己的版本终端里跑node -v如果输出是v18.x或更高那就没问题。如果低于 18我建议直接用 nvm 切一个长期支持版本比如 20 LTS因为 ccusage 后续更新基本都会基于新版本 Node 的特性早切早省心。我在 macOS 上用的是 nvm 管理的 Node 20在 Linux 服务器上用的是 Node 22两条路都跑得很稳。2.2 确认 Claude Code 本体可运行这一步看起来很蠢但真的有人忽略。ccusage 读的是 Claude Code 写在本地的日志文件如果 Claude Code 本身没运行过、没产生日志那 ccusage 装得再漂亮也看不到任何数据。你至少要在终端里启动过 Claude Code并且完成过一次真实的对话请求。不一定是正式干活随便问一句“帮我写一个 Python 快排”也行。只要会话正常结束日志文件就会落盘。后面我会讲具体怎么验证日志文件存在。2.3 终端环境与网络要求还有一点容易被忽略npm 安装需要能正常访问 npm 仓库。如果你所在网络环境有代理或镜像设置要先确认 npm 能拉到包。我遇到过一种情况公司内网 npm 镜像同步不及时导致装到的 ccusage 是旧版功能少一大截后来切回官方源重装才解决。如果你平时用 pnpm 或 yarn也可以直接装但我的建议是用 npm 全局安装因为 ccusage 的命令入口和 npm 的全局 bin 目录配合得最顺。后面所有的排查经验我也都是基于 npm 这个路径来讲的。3. 安装 ccusage 全流程安装本身只有一条命令但实际执行过程中有几个细节会影响后续使用体验我按顺序拆开讲。3.1 全局安装命令在终端里执行npm install -g ccusage这条命令会从 npm 官方仓库拉取 ccusage 并将其链接到全局 bin 目录。加-g是必须的如果不加命令只能在当前目录下用换个目录就command not found非常烦人。执行过程中npm 会输出一些进度信息。如果你的网络状况一般可能会看到卡在fetch阶段半天没动静这时候别急着 CtrlC先等一等npm 偶尔会静默重试。我用的是国内网络正常情况下十几秒到半分钟就能装完。3.2 验证安装结果装完之后不要着急去数日志先确认命令本身能跑ccusage --version如果输出类似ccusage/1.8.2 darwin-arm64这样的版本号说明安装成功。如果提示command not found多半是全局 bin 目录不在你的 PATH 环境变量里这个排查方法我在后面的故障章节会细说。还有一种情况版本号能输出来但执行ccusage的时候直接白屏或报错。这大概率是 Node 版本问题或者日志文件路径问题也放到故障章节统一处理。3.3 确认可执行文件位置为了后续排查方便我建议你顺手确认一下 ccusage 被装到哪了which ccusage在 macOS 上通常是/usr/local/bin/ccusage或者 nvm 目录下的某个路径在 Linux 上可能是/usr/bin/ccusage。记住这个路径没坏处因为后面你配置 PATH、做定时任务、或者写自动化脚本的时候都会用到。到这里安装就算完成了。但你别高兴太早我见过太多人装完工具就直接跑结果输出一个空表格然后跑过来问“是不是工具坏了”——其实不是是日志还没生成或者路径没配对。下一节讲的就是怎么让 ccusage 真正“看到”数据。4. 首次运行前的关键配置ccusage 的安装只是把“读日志的管道”接通了但要让管道里有水你得先把水龙头打开。具体来说就是让 Claude Code 先产生一份可用日志并且确保 ccusage 能找到它。4.1 配置 ANTHROPIC_API_KEY这一步不是 ccusage 本身的要求而是 Claude Code 使用 Api 模式的前提。如果你之前用的是订阅账号可能从来没配过环境变量但 ccusage 统计的核心价值恰恰体现在 Api 模式下所以我还是建议你配一下。在终端里执行export ANTHROPIC_API_KEY你的密钥为了不用每次开终端都重复设置建议写进 shell 配置文件。以 zsh 为例echo export ANTHROPIC_API_KEY你的密钥 ~/.zshrc source ~/.zshrc这里提醒一句密钥属于敏感信息别写进任何会被提交到代码仓库的文件里。我见过有人把密钥写进项目里的.env然后不小心推到公开仓库的非常危险务必用系统级的 shell 配置来管理。4.2 生成第一条统计日志配置好密钥后在终端启动 Claude Codeclaude随便聊一句话比如让它帮忙写个正则表达式然后正常退出会话。退出后Claude Code 会在本地日志目录下生成 JSONL 格式的会话记录。在 macOS 上日志目录通常在~/.claude/projects/下面以项目路径的编码形式分目录存放在 Linux 上路径类似。每个会话目录下有以时间戳命名的 JSONL 文件这就是 ccusage 的数据源。你可以快速验证一下日志存不存在ls ~/.claude/projects/如果能看到一堆乱码一样的目录名说明日志已经生成了。那些乱码其实是项目路径的编码ccusage 会自动解析我们不用管。4.3 跑通第一条统计命令万事俱备现在执行ccusage正常情况下你会看到一个终端 UI 界面里面有会话总数、token 消耗总量、平均每次会话 token 数等指标。如果显示的数字是 0 或者直接报错找不到数据先别慌八成是日志路径不对或者你的 Claude Code 版本太新、日志格式发生了变化。这一块我会在踩坑章节展开。首次跑通之后你就有了一份“基线数据”。我建议你拍个照或者截图存一下因为后续所有成本分析、趋势对比都是基于这份基线来展开的。5. 常用参数与高阶玩法ccusage 真正强大的地方不只是显示总数而是能按时间维度做切片。我从最常用的参数开始讲再往深一点讲自动化用法。5.1 核心参数速查表先把常用参数列出来后面逐一拆解参数作用示例--day按天汇总显示ccusage --day--week按周汇总显示ccusage --week--month按月汇总显示ccusage --month--days N显示最近 N 天ccusage --days 7--json以 JSON 格式输出ccusage --json--file 路径指定自定义日志目录ccusage --file ~/custom_logs/--cost估算 API 费用ccusage --cost默认执行ccusage显示的是整体累计数据对日常对账来说不够直观所以按天、按周、按月这些参数才是一般用户真正高频使用的。5.2 按时间窗口查看用量月初的时候我喜欢跑一句ccusage --month它会按月把每个月的 token 消耗、请求数、会话数都拉出来我一眼就能看出哪个月用量异常高然后针对性去翻那个月的会话记录看是不是有什么大任务烧了太多 token。如果我只关心最近一周的情况比如这周写新功能明显感觉 Api 调用变卡了我会用ccusage --days 7这个命令会把最近 7 天按天拆开能看到哪天请求量暴涨、哪天是空档期。这个数据对调整自己的工作节奏很有帮助。比如说我发现每周四下午用量特别大那可能是例行 Code Review 集中处理的时间后面我就把大任务拆到周三做避免撞在一起导致 Api 超时。5.3 JSON 输出与自动化脚本终端 UI 适合人眼阅读但如果你想把它接进自己的监控体系JSON 输出是必须的。举个例子我想每天凌晨自动统计前一天的使用量并追加到一个 CSV 文件里可以这样写脚本ccusage --days 1 --json /tmp/ccusage_daily.json python3 -c import json with open(/tmp/ccusage_daily.json) as f: data json.load(f) print(data[total_cost]) 配合 cron 定时任务就能实现每天自动记录成本。我实际用的脚本比这个复杂一点还加了会话时长分布和请求失败率的统计不过核心逻辑完全一样拿到 JSON解析落库或追加到文件月底统一汇总。5.4 自定义数据集路径如果你像我一样把 Claude Code 的日志目录重定向到了其他位置比如外置硬盘或服务器统一存储那么每次执行 ccusage 都要加--file参数太痛苦了可以直接设置环境变量CCUSAGE_DATA_DIR指向你的日志目录。设置方式和前面配置 API Key 一样写入 shell 配置文件即可export CCUSAGE_DATA_DIR/Volumes/Data/claude_logs这样 ccusage 会自动去这里找数据不再需要手动指定。6. 踩坑实录与排查速查表这部分是我最想写的。ccusage 安装和使用过程中我踩过的坑、以及我在技术社群里帮别人解决的典型问题都在这里基本覆盖了九成以上的异常场景。6.1 常见问题与解决方案先说一个高频问题“为什么提示 command not found”排查路径如下npm config get prefix看输出的路径然后检查这个路径是否在你的 PATH 环境变量里。如果不在你就得把 npm 全局 bin 目录加进 PATH。比如输出是/usr/local那 bin 目录就是/usr/local/bin在 shell 配置里加一行export PATH/usr/local/bin:$PATH如果你是用 nvm 装的 Node那全局 bin 目录通常在~/.nvm/versions/node/版本号/bin也需要加进 PATH。这个坑在 macOS 上特别常见因为系统自带的 Node 版本很老很多人后来用 nvm 装了新版 Node但 PATH 顺序不对导致系统优先找了旧版本。再说第二个高频问题“装好了命令也能跑但是数据全为 0。”这种情况首先要确认日志文件到底生成没有。执行find ~/.claude/projects -name *.jsonl | head -5一条输出都没有的话说明 Claude Code 根本没产生日志。原因可能是你用的 Claude Code 版本太老当时还没有日志功能或者你在没联网的情况下启动了 Claude Code请求根本没发出去又或者你的日志目录不是默认路径被改过了。如果日志文件存在但 ccusage 仍然显示为 0那可能是日志格式兼容性问题。Claude Code 更新很频繁日志格式偶尔会变ccusage 不一定每次都跟上。如果你想用新版本 Claude Code 但又依赖 ccusage我建议只把 Claude Code 锁定在某个已知兼容的版本别天天追新。6.2 数据不对怎么办还有一种更隐蔽的情况日志里面有数据但数字明显不对。比如说我明明今天消耗了很多 tokenccusage --days 1却只显示了几百个明显少了一个量级。我印象最深的一次是我用了多台机器开发公司电脑、家里电脑、还有一台 Linux 服务器。每台机器上 Claude Code 的日志是独立的ccusage 只看本地日志。也就是说我公司在机器上消耗的 token在 Linux 服务器上执行 ccusage 是看不到的。解决思路也很简单要么固定主力机器要么自己搭一个日志同步方案。我后来是在每台机器上配了定时任务把~/.claude/projects/下的 JSONL 文件增量同步到一台固定服务器上然后把CCUSAGE_DATA_DIR指向那台服务器的共享目录。这样所有机器的用量都汇总到了一份数据里。6.3 和 Team/Enterprise 版的差异最后一个要注意的点如果你用的是 Claude Code 的 Team 版或 Enterprise 版ccusage 能统计的数据范围和 Api 模式不一样。它读的还是本地日志但部分会话信息可能因为权限或加密策略被省略了所以统计结果会和官方后台数据存在偏差。我的建议是ccusage 主要用来看趋势、抓异常、做相对比较别把它当成官方计费系统的替代品。真到对账的时候还是以官方后台导出为准。工具的定位是辅助你理解自己的使用行为而不是代替官方做计费裁决。7. 实际使用中的一些体会写了这么多最后回到使用体验这个层面。ccusage 这个工具本身很轻量但也正因为轻量它的功能边界其实取决于你肯不肯自己动脑子去扩展。我已经基于它做了几轮迭代刚开始只是每天看一眼 token 数后来加了 JSON 输出再后来做了自动化统计脚本最后干脆搭了一个完整的用量看板每天自动汇总上一日的请求量、token 消耗、估算成本按天生成折线图放进本地网页。这个看板帮我发现了一个很有意思的现象每次大版本升级后的一周内消耗都会明显升高因为我会把旧代码整体重构一遍。这个规律不看数据根本意识不到。如果你只是装完跑一下看一眼数字就关掉那 ccusage 的价值大概只发挥了百分之十。真正让我受用的是它把“模糊的成本焦虑”变成了“清晰的数据事实”。知道自己每天在什么任务上花了多少 token优化就有方向了。安装的部分我讲得很细是因为我觉得一个新工具能不能留住人往往就从第一次跑通数据开始。如果第一步就卡半天可能后面就不会再用了。你只要按这篇的步骤走一遍从零到看到数据十分钟之内应该能完成。数据跑通之后后面怎么玩就看你的想象力了。