ccusage安装配置指南：轻松统计Claude Code使用量与成本

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阶段半天没动静，这时候别急着 Ctrl+C，先等一等，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 Code：

claude

随便聊一句话，比如让它帮忙写个正则表达式，然后正常退出会话。退出后，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 核心参数速查表

先把常用参数列出来，后面逐一拆解：

默认执行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 数据不对怎么办

还有一种更隐蔽的情况：日志里面有数据，但数字明显不对。比如说我明明今天消耗了很多 token，ccusage --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，优化就有方向了。

安装的部分我讲得很细，是因为我觉得一个新工具能不能留住人，往往就从第一次跑通数据开始。如果第一步就卡半天，可能后面就不会再用了。你只要按这篇的步骤走一遍，从零到看到数据，十分钟之内应该能完成。数据跑通之后，后面怎么玩就看你的想象力了。