🍃作者介绍：AI 应用负责人 / AI产品架构师，阿里云专家博主。专注 LLM 应用开发、Agent 系统设计、具身智能与工业 AI 落地。日常在大模型训练、Coding Agent 工具链、AI 产品商业化等方向持续输出实战内容。
🦅个人主页：@逐梦苍穹
🐼GitHub主页：https://github.com/XZL-CODE
✈ 您的一键三连，是我创作的最大动力🌹

1、前言

用 Claude Code 写代码很爽，但你知道自己每天烧了多少钱吗？

不管你是 MAX 订阅用户还是 API 按量付费用户，都需要一个工具来回答这些问题：今天花了多少？哪次对话最贵？5 小时窗口的配额还剩多少？Opus 和 Sonnet 各占多少费用？

ccusage 就是为此而生的工具。它是目前 Claude Code 社区最主流的用量统计方案，GitHub 上已有 11,400+ Stars，由开发者 ryoppippi 维护，完全开源。

一句话概括：ccusage 读取 Claude Code 本地日志，计算并展示你的 token 消耗和费用。

本文先带你 3 分钟上手，再逐一展开每个功能的用法和原理。

---

2、3 分钟快速上手

2.1、安装

# 安装
npm install -g ccusage

# 更新到最新版
npm install -g ccusage@latest

# 查看当前版本
ccusage --version

也可以不全局安装，用 npx ccusage 或 bunx ccusage 临时运行（推荐 bun，速度更快）。
定价数据内嵌在 ccusage 中，Anthropic 调价后记得及时更新。

2.2、五条最常用命令

安装完直接复制运行，立刻看到效果：

# 1. 查看今日用量和费用
ccusage daily -s 20260411

# 2. 查看今日费用，按模型拆分（Opus / Sonnet / Haiku 各多少）
ccusage daily -s 20260411 -b

# 3. 查看每次对话的费用，最新的排最前
ccusage session -o desc

# 4. 查看本月每天的用量汇总
ccusage daily -s 20260401

# 5. 查看当前 5 小时计费窗口的用量（MAX 订阅用户必看）
ccusage blocks -o desc

把日期换成你自己需要的即可，格式统一为 YYYYMMDD。

2.3、一键配置状态栏（推荐）

让费用信息实时显示在 Claude Code 底部状态栏：

# 方式一：编辑配置文件
# 在 ~/.claude/settings.json 中添加：

{
  "statusLine": {
    "type": "command",
    "command": "bunx ccusage statusline",
    "padding": 0
  }
}

配置后效果如下图：

状态栏会实时显示：当前模型、会话费用、今日总费用、5h 窗口费用及剩余时间、烧钱速率、上下文占比。

---

3、六大报告命令详解

ccusage 提供六个子命令，对应六种不同的统计维度。下面逐一说明。

3.1、daily —— 按天汇总

最常用的命令，查看每天的 token 消耗和费用。

# 基础用法：查看所有历史数据
ccusage daily

# 查看某天的数据
ccusage daily -s 20260411

# 查看某个时间段
ccusage daily -s 20260401 -u 20260410

# 按模型拆分费用
ccusage daily -s 20260401 -b

# 按项目分别显示
ccusage daily -s 20260401 -i

3.2、weekly —— 按周汇总

适合做周度复盘，了解每周的使用趋势。

# 查看本周
ccusage weekly -s 20260406

# 按模型拆分
ccusage weekly -s 20260406 -b

3.3、monthly —— 按月汇总

适合做月度预算管理，尤其是 API 按量付费用户。

# 查看本月
ccusage monthly -s 20260401

# 对比多月趋势
ccusage monthly -s 20260101

3.4、session —— 按对话汇总

每次启动 Claude Code 的一轮对话就是一个 session。这个命令能精准定位"哪次对话最烧钱"。

# 最近对话排在最前
ccusage session -o desc

# 按模型拆分，看 Opus 和 Sonnet 各花了多少
ccusage session -o desc -b

# 只看某个项目的对话
ccusage session -p myproject -o desc

这是排查异常费用的利器：如果某天费用突然飙升，用 session 命令找到那次对话即可。

3.5、blocks —— 按 5 小时计费窗口汇总

Claude Code 对 MAX 订阅用户使用5 小时滚动窗口进行配额管理。blocks 命令专门用来监控这个窗口。

# 查看计费块，最新的在前
ccusage blocks -o desc

# 按模型拆分
ccusage blocks -o desc -b

MAX 订阅用户务必掌握这个命令，它直接关系到你的配额剩余。

3.6、statusline —— 状态栏输出

输出精简的一行文本，配合 Claude Code 的 statusLine 配置使用（配置方式见 2.3 节）。

# 直接运行看效果
ccusage statusline

statusline 支持多种显示选项：

选项	说明
--cost-source auto	智能选择费用来源（默认）
--cost-source cc	只用 Claude Code 记录的 costUSD
--cost-source ccusage	只用 token 重新计算
--cost-source both	两种方式都显示
--visual-burn-rate emoji	用表情符号显示烧钱速率级别
--context-low-threshold 50	上下文用量低警戒线（百分比）
--context-medium-threshold 80	上下文用量中警戒线（百分比）

---

4、通用选项速查表

以下选项适用于所有子命令，按使用频率排列。

4.1、时间筛选

选项	说明	示例
-s, --since <YYYYMMDD>	只看该日期之后的数据	-s 20260401
-u, --until <YYYYMMDD>	只看该日期之前的数据	-u 20260410

4.2、显示控制

选项	说明
-b, --breakdown	按模型拆分费用明细
-i, --instances	按项目/实例分别显示
-p, --project <name>	只看指定项目
--project-aliases	项目别名映射，格式：'ccusage=Usage Tracker,myproject=My Project'
-o, --order <desc|asc>	排序方向，desc 最新在前，asc 最早在前（默认）
--compact	紧凑模式，适合窄屏或截图

4.3、输出格式

选项	说明
-j, --json	输出 JSON 格式，便于程序处理
-q, --jq <expression>	JSON 输出后用 jq 处理（需系统已安装 jq）
--color / --no-color	强制启用/禁用彩色输出

4.4、费用计算模式

选项	说明	适用场景
-m auto	优先用日志中的 costUSD，没有则自行计算	日常使用（默认）
-m calculate	始终根据 token 数重新计算	跨时期一致性对比
-m display	始终用日志中的 costUSD	对齐 Claude 官方账单
-O, --offline	使用本地缓存的定价数据（默认）	离线环境
--no-offline	联网获取最新定价	价格变动后

4.5、本地化

选项	说明	示例
-z, --timezone <tz>	指定时区	-z Asia/Shanghai
-l, --locale <locale>	日期格式本地化	-l zh-CN

---

5、实战场景：常用命令组合

以下是日常使用中最高频的几个场景，命令可以直接复制运行。

5.1、日常看板：今天花了多少

ccusage daily -s 20260411 -b -z Asia/Shanghai

一条命令看到：今日总费用 + Opus/Sonnet/Haiku 各自占比 + 上海时区。

5.2、费用排查：哪次对话最贵

ccusage session -o desc -b -s 20260401

按费用从高到低排列本月每次对话，配合 -b 看到是 Opus 贵还是 Sonnet 贵。

5.3、预算管理：本月花了多少

ccusage monthly -s 20260101 -b

看到每月的费用走势，评估是否需要调整使用习惯或切换订阅方案。

5.4、配额监控：5h 窗口还剩多少（MAX 用户）

ccusage blocks -o desc

MAX 用户的核心命令。查看当前 5 小时窗口内的 token 消耗，判断是否需要控制节奏。

5.5、按项目统计：多项目费用分摊

ccusage daily -s 20260401 -i --project-aliases 'work=公司项目,side=个人项目'

多项目并行时，用项目别名让报告更清晰。

5.6、数据导出：对接自动化流程

# 导出 JSON
ccusage daily -s 20260401 --json > usage.json

# 用 jq 提取每天的费用
ccusage daily -s 20260401 -q '.[] | {date: .date, cost: .cost}'

5.7、截图分享：紧凑模式

ccusage daily -s 20260401 --compact --no-color

去掉颜色、压缩宽度，适合截图发到群里或文档中。

---

6、MAX 订阅 vs API 计费：ccusage 显示的钱数到底是什么

这是最容易混淆的一点，值得单独说清楚。

6.1、MAX 订阅用户

如果你使用的是 $100/月（Max 5x）或 $200/月（Max 20x）的订阅：

• ccusage 显示的 $XX.XX 不是你实际支付的钱
• 它是"如果你按 API 按量付费，这些 token 要花多少钱"
• 相当于你通过订阅省下的钱

有用户实测：$100/月的 MAX 计划，ccusage 显示等效 API 费用 $600-800/月——说明订阅的性价比极高。

MAX 用户真正该关注的是 5 小时窗口的 token 配额，而不是美元金额。用 ccusage blocks 或 statusline 来监控。

各档位的 5 小时窗口 token 配额参考：

订阅档位	月费	5h 窗口 token 配额（约）
Pro	$20	~44,000
Max 5x	$100	~88,000
Max 20x	$200	~220,000

6.2、API 按量付费用户

如果你使用的是 API Key 直接计费：

• ccusage 显示的 $XX.XX 就是你的真实消费
• 直接对应 Anthropic 的 API 账单
• 重点关注 daily -b 和 monthly 命令做预算管理

---

7、工作原理简述

了解原理有助于理解 ccusage 的能力边界和数据来源。

7.1、数据从哪来

Claude Code 每次对话都会自动将使用数据写入本地 JSONL 日志文件：

~/.claude/projects/<project-name>/<conversation-id>.jsonl
~/.config/claude/projects/<project-name>/<conversation-id>.jsonl

ccusage 会自动检查上述两个路径（兼容新旧版 Claude Code），逐行解析 JSON 记录。

每条记录包含的关键字段：

字段	说明
inputTokens	输入 token 数
outputTokens	输出 token 数
cacheCreationTokens	缓存写入 token 数
cacheReadTokens	缓存读取 token 数
costUSD	Claude Code 预计算的费用
model	使用的模型名称

7.2、费用怎么算

ccusage 的费用计算公式：

totalCost = inputTokens × inputPrice
          + outputTokens × outputPrice
          + cacheCreationTokens × cacheCreatePrice
          + cacheReadTokens × cacheReadPrice

定价数据来源于 LiteLLM 定价数据库：

• 离线模式（默认）：使用 ccusage 构建时内嵌的定价快照，速度快、不依赖网络
• 在线模式（--no-offline）：实时从 LiteLLM API 获取最新定价

如果 Anthropic 调整了模型定价，升级 ccusage 到最新版即可获得更新的定价快照：npm install -g ccusage@latest

7.3、三种费用计算模式

模式	行为	使用场景
auto（默认）	优先用日志中的 costUSD，没有则用 token 计算	日常使用
calculate	始终用 token × 单价 重新计算，忽略 costUSD	跨时期数据对比
display	只显示日志中的 costUSD，没有则显示 $0	验证官方账单

---

8、进阶：MCP 服务器集成

ccusage 还提供独立的 MCP 服务器包，可以让 Claude Desktop 或其他支持 MCP 的工具直接查询用量数据。

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "ccusage": {
      "command": "bunx",
      "args": ["@ccusage/mcp@latest"]
    }
  }
}

配置后，你可以在 Claude Desktop 中直接用自然语言查询用量，比如"我今天花了多少钱"。

---

9、常见问题

Q：更新到最新版后定价数据不对怎么办？

# 强制在线获取最新定价
ccusage daily -s 20260411 --no-offline

Q：statusline 响应太慢？

用 bun 替代 npx，速度会显著提升：

{
  "statusLine": {
    "type": "command",
    "command": "bun x ccusage statusline",
    "padding": 0
  }
}

Q：ccusage 支持其他 AI 编程助手吗？

支持。从 v17 开始，ccusage 重构为 monorepo，除了 Claude Code，还支持 OpenAI Codex CLI（npx @ccusage/codex）、OpenCode、Amp 等。

Q：费用和 Anthropic 官方账单对不上？

用 -d 开启调试模式查看差异原因：

ccusage daily -s 20260411 -d

常见原因包括：定价快照版本差异、阶梯定价触发（超过 200k token 的请求）。

---

10、总结

ccusage 是 Claude Code 用户的必备工具，核心价值在于让你对 AI 编程的消费心中有数。

回顾全文要点：

你的身份	核心命令	关注指标
MAX 订阅用户	ccusage blocks -o desc	5h 窗口 token 配额剩余
API 付费用户	ccusage daily -b	每日/每月真实费用
所有用户	ccusage session -o desc	哪次对话最贵
所有用户	配置 statusline	实时感知费用

最后再贴一次最常用的命令，复制即用：

# 安装
npm install -g ccusage

# 今日费用 + 模型拆分
ccusage daily -s 20260411 -b

# 最贵的对话
ccusage session -o desc

# 5h 窗口配额（MAX 用户）
ccusage blocks -o desc

# 本月汇总
ccusage monthly -s 20260401

# 状态栏配置命令
bunx ccusage statusline

项目地址：https://github.com/ryoppippi/ccusage
官方文档：https://ccusage.com