ccusage使用教程:如何分析Claude Code使用情况

15 分钟阅读

用Claude Code写代码越来越多,但你知道自己每天花了多少钱吗?ccusage就是专门解决这个问题的工具。它能读取你本地的Claude Code使用数据,告诉你每天用了多少token、花了多少钱,还能帮你找出哪些对话最"烧钱"。

这篇文章会手把手教你用ccusage,从安装到高级功能都有,让你对自己的AI使用情况心里有数。

引言:为什么需要分析Claude Code使用情况

刚开始用Claude Code的时候,大家通常都没想过成本问题。写代码时随便问,Debug时使劲聊,反正感觉挺好用的。但如果你想深入了解Claude Code的具体计费模式,可以参考我们的Claude Code价格详细指南

但用得多了,一些问题就冒出来了:

常见问题具体困惑为什么头疼
成本不透明要是用付费API,一个月得花多少钱?哪些对话特别费token?心里没底,不敢放开用
使用习惯不清楚不知道什么时候用得多,什么任务最依赖AI想优化都不知道从哪下手
团队管理混乱几个人一起用,怎么分配预算?谁用得多?管理起来一团糟

ccusage就是专门解决这些头疼事的。它能把Claude Code使用数据扒出来,清清楚楚告诉大家花了多少钱、用了多少token,哪些对话最烧钱。有了这些数据,心里就踏实多了。如果你还在纠结要不要选择Claude Code作为主要的AI编程工具,建议先看看Claude Code与Cursor的详细对比

ccusage快速入门:从安装到第一次使用

安装方式选择

ccusage有好几种安装方法,看你的需求选:

安装方式命令速度什么时候用
npx (试试看)npx ccusage daily⭐⭐⭐就想先试试,不想安装
bunx (推荐)bunx ccusage daily⭐⭐⭐⭐⭐经常用,要速度快
全局安装npm install -g ccusage⭐⭐⭐⭐天天用,装一次就行
Bun安装bun install -g ccusage⭐⭐⭐⭐⭐追求极致性能
Denodeno run --allow-read --allow-env npm:ccusage daily⭐⭐⭐权限控制严格的环境

建议用bunx,比npx快2-3倍,特别是数据多的时候差别很明显。

基本配置步骤

好消息是ccusage基本不用配置,装完就能用。它会自动找到Claude Code的数据文件夹:

# 先生成一个日报看看
ccusage daily

# 看看这个月用了多少
ccusage monthly

# 如果有问题,看看帮助
ccusage daily --help

第一个报告生成示例

来试试生成第一份报告:

# 看看最近一周的使用情况
ccusage daily --since 7days

# 详细一点,按模型分开看
ccusage daily --breakdown

# 想要原始数据?导出JSON
ccusage daily --json > usage-report.json

报告里一般会有这些:

  • 每天用了多少token(输入、输出、缓存分别多少)
  • 大概花了多少钱(按不同模型价格算的)
  • 聊了多少次天
  • 总共用了多长时间

核心功能详解:四种报告类型全掌握

ccusage有四种报告,每种都有不同的用处:

报告类型看什么怎么统计什么时候用
日报告每天用了多少按天分组平时看看,了解趋势
月报告长期使用情况按月统计做预算,看投入产出
会话报告哪些对话最费钱按对话分组优化使用方式
计费块报告5小时内的使用效率按计费周期省钱,用得更划算

日报告分析 (ccusage daily)

日报告是用得最多的功能,能看出每天的使用规律:

# 最基本的日报告
ccusage daily

# 最近30天的趋势
ccusage daily --since 30days

# 按模型分开看成本
ccusage daily --breakdown

# 看特定时间段
ccusage daily --since 2024-07-01 --until 2024-07-15
ccusage日报告界面截图,显示每日Claude Code使用统计,包含token消耗量、成本分析、按模型分组的详细数据和使用趋势图表

ccusage日报告界面:清晰展示每日使用统计,包含token消耗、成本分析和趋势变化

什么时候用日报告:

  • 想知道平时AI用得多不多
  • 找出哪些工作日特别烧token
  • 看不同项目阶段的使用差别
  • 给自己定个使用预算

月报告统计 (ccusage monthly)

月报告看的是大趋势,适合做长期规划:

# 看这个月的情况
ccusage monthly

# 看某个月的详细数据
ccusage monthly --since 2024-06-01 --until 2024-06-30

# 整年的使用报告
ccusage monthly --since 12months --breakdown
ccusage月报告界面截图,展示月度Claude Code使用统计汇总,包含累计成本、平均每日使用量、按模型分组的月度趋势分析和预算对比

ccusage月报告界面:提供月度使用趋势分析,助力长期预算规划和成本控制

月报告有什么用:

  • 做预算,预测成本
  • 看看淡季旺季的使用差别
  • 算算AI工具值不值得投入
  • 团队不同月份的对比

会话报告 (ccusage session)

会话报告能找出哪些对话最烧钱:

# 看所有对话的使用情况
ccusage session

# 找出最费钱的对话(取前20个)
ccusage session --breakdown | head -20

# 最近一周的高成本对话
ccusage session --since 7days --json
ccusage会话报告界面截图,显示各个对话会话的详细分析,包含每个会话的token消耗、成本统计、持续时间和会话类型分类,帮助识别高成本对话

ccusage会话报告界面:详细分析每个对话会话的成本构成,轻松识别"烧钱"对话

会话报告能干什么:

  • 找出哪种编程任务最费token
  • 改进和AI聊天的方式
  • 看哪些项目特别依赖AI
  • 比较不同编程语言的AI使用效率

计费块报告 (ccusage blocks)

Claude是按5小时一个计费窗口收费的,blocks报告帮你用得更划算:

# 看5小时计费块的使用情况
ccusage blocks

# 实时看当前计费块的进度
ccusage blocks --live

# 分析计费效率怎么样
ccusage blocks --breakdown --since 7days
ccusage计费块报告界面截图,展示Claude Code 5小时计费窗口的使用效率分析,包含计费块利用率、窗口内token分布、成本优化建议和使用时间规划

ccusage计费块报告界面:分析5小时计费窗口的使用效率,优化成本控制策略

怎么用blocks报告省钱:

  • 集中时间使用,让每个5小时窗口物尽其用
  • 别零零散散地用,跨了好几个窗口就亏了
  • 安排大任务的时间,一口气搞定
  • 团队一起用的时候协调好时间

实时监控与成本控制:时刻掌握花费情况

实时仪表板功能

ccusage能实时显示当前的使用情况,避免不知不觉烧掉太多钱:

# 打开实时监控面板
ccusage blocks --live

# 实时监控 + 成本预警
ccusage blocks --live --breakdown
ccusage实时监控仪表板界面截图,显示当前计费块的实时使用进度、token消耗速度、成本预测和彩色状态指示,提供即时的使用情况反馈和预警功能

ccusage实时监控仪表板:动态显示当前使用状态,实时掌控成本变化

实时面板会显示:

看什么具体内容有什么用
当前计费块进度5小时窗口用了多少看窗口利用率
Token消耗速度每分钟平均用多少token控制使用节奏
成本预测按当前使用情况估算总花费预算控制
进度条和警告彩色的使用量提示一眼看出状态

三种成本计算模式

ccusage有三种计算成本的方式,根据需要选择:

模式命令特点什么时候用
自动模式--cost-mode auto智能选择计算方法平时用,又快又准
计算模式--cost-mode calculate每次都重新算要精确数据的时候
显示模式--cost-mode display直接显示已有数据快速查看,速度最快
# 自动模式(默认)
ccusage daily --cost-mode auto

# 计算模式(最精确)
ccusage daily --cost-mode calculate

# 显示模式(最快)
ccusage daily --cost-mode display

成本预警和优化

可以设置一些自动监控,避免花费超标:

# 设置成本阈值
export CCUSAGE_COST_THRESHOLD=50.00

# 定时检查成本(每6小时一次)
echo "0 */6 * * * ccusage daily --since 1day --json | jq '.totalCost' > /tmp/claude_cost.log" | crontab -

建议设置多个档次的限制:每天多少钱、每周多少钱、每月多少钱,这样比较好控制预算。


高级配置与自定义:适配复杂使用场景

自定义数据路径配置

对于复杂的开发环境,ccusage支持灵活的路径配置:

# 使用环境变量指定Claude配置目录
export CLAUDE_CONFIG_DIR="/custom/path/to/claude"
ccusage daily

# 命令行指定多个数据路径
ccusage daily --instances /path/to/instance1,/path/to/instance2

# 分析特定项目的使用情况
ccusage daily --project "my-project" --custom-path /project/claude/data

多项目和实例管理

企业环境中的多项目分析配置:

# 创建项目配置文件
cat > ~/.ccusage/config.json << EOF
{
  "projects": {
    "frontend": "/Users/dev/projects/frontend/.claude",
    "backend": "/Users/dev/projects/backend/.claude",
    "mobile": "/Users/dev/projects/mobile/.claude"
  },
  "defaultCostMode": "calculate",
  "outputFormat": "table"
}
EOF

# 按项目生成独立报告
ccusage daily --project frontend --output frontend-usage.json
ccusage daily --project backend --output backend-usage.json

JSON输出和数据集成

ccusage的JSON输出功能支持与其他系统的集成:

# 导出详细的JSON报告
ccusage monthly --json --breakdown > monthly-report.json

# 结合jq进行数据处理
ccusage daily --json | jq '.sessions[] | select(.cost > 5.0) | {date, cost, tokens}'

# 集成到监控系统
ccusage daily --json | curl -X POST -H "Content-Type: application/json" -d @- http://monitoring.company.com/api/claude-usage

离线模式使用技巧

当网络受限或需要使用缓存价格数据时:

# 启用离线模式
ccusage daily --offline

# 更新价格缓存(需要网络连接)
ccusage --update-prices

# 查看当前缓存的价格数据
ccusage --show-prices

团队协作与集成应用:MCP服务器和库使用

MCP服务器集成到Claude Desktop

ccusage内置MCP(Model Context Protocol)服务器,可直接集成到Claude Desktop中:

# 启动ccusage MCP服务器
ccusage mcp-server --port 3000
# 在Claude Desktop配置中添加
{
  "mcpServers": {
    "ccusage": {
      "command": "ccusage",
      "args": ["mcp-server"]
    }
  }
}

MCP集成后,你可以在Claude Desktop中直接:

  • 查询当前使用统计
  • 生成实时报告
  • 监控成本变化
  • 获取使用建议

想进一步提升Claude Code的使用效率?了解一下如何使用Claude Code子代理功能,让不同的任务由专门的AI助手处理,既能提高效率,又能更好地控制成本。

作为Node.js库集成到项目中

ccusage也可以作为Node.js库在项目中使用:

// 安装依赖
// npm install ccusage

import { generateDailyReport, getUsageStats } from 'ccusage';

// 生成程序化报告
async function analyzeUsage() {
  const dailyStats = await generateDailyReport({
    since: '7days',
    breakdown: true,
    costMode: 'calculate'
  });
  
  console.log(`本周总成本: $${dailyStats.totalCost}`);
  console.log(`平均每日token: ${dailyStats.avgDailyTokens}`);
  
  // 集成到项目监控
  if (dailyStats.totalCost > 100) {
    await sendCostAlert(dailyStats);
  }
}

// 实时使用统计
const liveStats = getUsageStats({ live: true });
liveStats.on('update', (stats) => {
  updateDashboard(stats);
});

团队使用的最佳实践

制定团队级别的ccusage使用规范:

# 团队共享配置
cat > team-ccusage-config.json << EOF
{
  "costThresholds": {
    "daily": 20.0,
    "weekly": 100.0,
    "monthly": 400.0
  },
  "reportSchedule": {
    "daily": "09:00",
    "weekly": "Monday 10:00",
    "monthly": "1st 14:00"
  },
  "alertWebhook": "https://hooks.slack.com/services/..."
}
EOF
#!/bin/bash
# 自动化团队报告脚本 - team-report.sh
REPORT_DATE=$(date +%Y-%m-%d)
ccusage daily --json --breakdown > "reports/team-daily-${REPORT_DATE}.json"
ccusage monthly --json > "reports/team-monthly-$(date +%Y-%m).json"

# 发送到团队Slack频道
curl -X POST -H 'Content-type: application/json' \
  --data "{\"text\":\"📊 团队Claude使用日报已生成: ${REPORT_DATE}\"}" \
  "${SLACK_WEBHOOK_URL}"

常见问题解答

Q: ccusage找不到Claude数据目录怎么办?

A: 先确认Claude Code装了并且用过。ccusage一般会在这些地方找数据:

  • ~/.config/claude(Linux/Mac)
  • %APPDATA%/claude(Windows)

如果路径不对,手动指定一下:

ccusage daily --custom-path "/your/claude/data/path"

Q: 成本计算怎么感觉不对?

A: 价格数据可能过期了。试试这些:

  1. 确认网络正常,让ccusage能拉取最新价格
  2. --cost-mode calculate模式算得更精确
  3. 跑一下ccusage --update-prices更新价格

Q: ccusage运行太慢怎么办?

A: 几个优化方法:

  • bunx代替npx
  • 大量数据时用--since限制时间范围
  • --offline模式避免网络请求
  • --json输出减少格式化时间

Q: 团队多人使用怎么管理?

A: 可以这样搞:

  • --instances参数合并多个人的数据
  • 建个共享的配置和报告目录
  • 设置定时任务自动生成团队报告
  • 考虑用ccusage的API集成到内部系统

结论:用数据让AI使用更聪明

ccusage是个很实用的工具,能帮程序员把Claude Code的使用情况摸得一清二楚。学完这篇教程,现在应该已经掌握了:

基本技能: 四种报告怎么生成,什么时候用哪种。

高级功能: 实时监控、自定义配置、团队协作这些进阶用法。

省钱策略: 用数据分析优化AI使用习惯,控制成本,提高效率。

别再糊里糊涂地用AI了,数据说话才靠谱。了解自己的使用模式,是优化的第一步。

马上试试

现在就跑一下bunx ccusage daily,看看第一份使用报告,开始更明智的Claude Code之旅吧。

参考资源

官方文档

社区资源

技术文档