ccusage 使用指南：本地分析 Claude Code、Codex 等 18 种编码 Agent CLI 的 Token 用量与成本
ccusage 使用指南：本地分析 Claude Code、Codex 等 18 种编码 Agent CLI 的 Token 用量与成本
ccusage 是一款完全本地运行的命令行工具，用于统一查看 Claude Code、Codex、OpenCode、Gemini CLI、GitHub Copilot CLI、ZCode 等 18 种编码（Agent）CLI 的 Token 用量与预估成本。本文以 docs/guide/index.md 为主体，结合仓库源码与配套文档，讲解它的设计动机、工作原理、支持的 18 种数据源、四种报告视图、成本分析机制、配置体系与隐私安全边界，帮助你在一台机器上回答“我到底用了多少 Token、花了多少钱、哪些会话最贵”这类问题。
它要解决的问题
现代编码 Agent CLI 的本地数据格式各不相同，Claude Code 写在 ~/.config/claude/projects/ 下的 JSONL 里，Codex 写在 ~/.codex，Copilot CLI 写在 ~/.copilot 的 session-state 与 otel 导出中……当这些工具同时进入日常开发流程时，几个基础问题变得很难回答：
- 每个编码 CLI 我到底用了多少？
- 哪些对话（会话）最贵？
- 如果按用量付费（pay-per-use），我要付多少钱？
- 是哪些项目、会话或周在推高用量？
ccusage 的解法不是接入各家云端账单，而是直接读取这些 CLI 在本地已经生成的用量文件，统一聚合、换算成本并输出报告。
工作原理：从本地文件到报表
docs/guide/index.md 将 ccusage 的处理流程概括为五步：
- 编码 CLI 生成本地用量文件（JSONL、SQLite、结构化遥测导出等）；
- ccusage 从本机读取这些文件；
- 按日期、会话或时间块聚合数据；
- 借助模型定价信息计算预估成本；
- 以表格或 JSON 形式呈现结果。
从源码结构看，这一流程在 Rust 侧由清晰的分层模块支撑：rust/crates/ccusage/src/main.rs 是命令入口，根据子命令把请求分发到统一报告（adapter::all）或 18 个独立的数据源适配器（adapter::codex、adapter::opencode、adapter::claude……）；统一报告模块 rust/crates/ccusage-adapter-all/src/lib.rs 会加载各适配器的行数据（rows），再按报告类型输出表格或 JSON。
一个值得注意的实现细节是：npm 包只是一个薄启动器。apps/ccusage/src/cli.js 会根据平台与架构解析 @ccusage/ccusage-<platform>-<arch> 可选依赖中的原生二进制（如 bin/ccusage），随后用 spawn 以 stdio: 'inherit' 方式把参数转发给 Rust 程序（apps/ccusage/src/cli.js）。因此 npx ccusage、bunx ccusage 最终执行的其实是同一个编译好的原生二进制。
核心能力总览
docs/guide/index.md 归纳的解决方案要点如下：
| 能力 | 说明 |
|---|---|
| All Sources by Default | 默认聚合 Claude Code、Codex、OpenCode、Amp、Droid、Codebuff、Hermes Agent、pi-agent、Goose、OpenClaw、Kilo、Kimi、Qwen、Copilot CLI、Gemini CLI、Antigravity、Grok Build CLI、ZCode 共 18 个来源 |
| Usage Views | 按日（daily）、周（weekly）、月（monthly）、会话（session）四种维度拆解 |
| Cost Analysis | 基于 Token 用量与模型定价的预估成本 |
| Focused Data Source Views | 先用统一视图看到全部来源，需要时把同一套视图收窄到单一来源 |
| Data Source Pages | 每个数据源的专属设置与额外特性独立成页 |
| Multiple Formats | 漂亮的表格或结构化 JSON |
使用视图（Usage Views）
- All Sources（默认）：聚合所有检测到的受支持来源；
- Daily Usage：按自然日聚合；
- Weekly Usage：按周聚合，周起始日可配置；
- Monthly Usage：月度汇总，带趋势；
- Session Usage：逐会话分析。
成本分析（Cost Analysis）
- 基于 Token 数量与模型定价的预估成本；
- 支持多种成本计算模式（
auto/calculate/display）； - 覆盖多提供方的模型级定价；
- 单独计算缓存 Token（cache create / cache read）成本。
从源码看，成本计算核心位于 rust/crates/ccusage-core/src/pricing.rs：ccusage 内置一份 LiteLLM 定价快照（PricingMap），运行时可以联网刷新，--offline 则跳过刷新直接使用内嵌快照（对应离线/隔离网络环境）；rust/crates/ccusage-core/src/cost.rs 中的 tiered_cost 实现了 20 万 Token 以上的分级计价（main.rs 测试 calculates_tiered_cost 验证了分档阈值的行为）。模型名缺失时会在报告中标记，便于排查定价缺口。
数据源页面（Data Source Pages）
每个数据源页面只讲该来源特有的内容，包括自定义目录、定价说明、来源专属命令。例如 Claude Code 专属的 blocks（5 小时计费窗口）与 statusline 集成见 docs/guide/claude/index.md。
灵活配置（Flexible Configuration）
- JSON 配置文件：为所有命令设置默认值，或按命令定制；
- IDE 支持：通过 JSON Schema 提供自动补全与校验（schema 见 config-schema.json）；
- 优先级体系：CLI 参数 > 本地配置 > 用户配置 > 默认值；
- 环境变量：传统配置方式；
- 自定义日期过滤：灵活的时间范围选择与排序；
- 离线模式：为隔离网络环境缓存定价数据。
支持的 18 种数据源与默认位置
ccusage 从各编码 CLI 的本地数据目录读取用量，下表是 docs/guide/index.md 中的完整清单：
| Agent | ID | 默认数据位置 |
|---|---|---|
| Claude Code | claude |
~/.config/claude/projects/、~/.claude/ |
| Codex | codex |
${CODEX_HOME:-~/.codex} |
| OpenCode | opencode |
${OPENCODE_DATA_DIR-${XDG_DATA_HOME:-$HOME/.local/share}/opencode} |
| Amp | amp |
${AMP_DATA_DIR:-~/.local/share/amp} |
| Droid | droid |
${DROID_SESSIONS_DIR:-~/.factory/sessions} |
| Codebuff | codebuff |
${CODEBUFF_DATA_DIR:-~/.config/manicode} |
| Hermes Agent | hermes |
${HERMES_HOME:-~/.hermes}/state.db |
| pi-agent | pi |
${PI_AGENT_DIR:-~/.pi/agent/sessions} |
| Goose | goose |
标准 Goose 数据根目录或 GOOSE_PATH_ROOT |
| OpenClaw | openclaw |
${OPENCLAW_DIR:-~/.openclaw} |
| Kilo | kilo |
${KILO_DATA_DIR:-~/.local/share/kilo} |
| Kimi | kimi |
${KIMI_DATA_DIR:-~/.kimi}（同时扫描 ~/.kimi-code） |
| Qwen | qwen |
${QWEN_DATA_DIR:-~/.qwen} |
| Copilot CLI | copilot |
${COPILOT_HOME:-~/.copilot}/session-state/*/events.jsonl、${COPILOT_HOME:-~/.copilot}/otel/**/*.jsonl |
| Gemini CLI | gemini |
${GEMINI_DATA_DIR:-~/.gemini/tmp} |
| Antigravity | antigravity |
${ANTIGRAVITY_DATA_DIR:-~/.gemini/antigravity*} 或 ~/.config/antigravity |
| Grok Build CLI | grok |
${GROK_HOME:-~/.grok} |
| ZCode | zcode |
${ZCODE_HOME:-~/.zcode} |
几个需要留意的细节：
- OpenCode 回退路径：
${XDG_DATA_HOME:-$HOME/.local/share}/opencode只是默认路径回退；一旦设置OPENCODE_DATA_DIR即覆盖该路径，显式设置为空值则禁用回退发现。 - 多根目录：支持多根目录的来源环境变量可以写逗号分隔的多个目录，从而让统一报告把当前 profile 与历史归档合并统计（例如
CODEX_HOME="/path/to/codex,/archive/codex"）。 - 自动检测：工具默认自动检测可用数据并聚合所有受支持编码 CLI。
哪些 Agent 不支持及原因
部分编码 Agent 经调研后未被支持，因为其本地文件不包含可靠的 Token 用量数据。ccusage 的支持门槛是：至少要有本地时间戳、会话标识、模型标识，以及可映射为 Token 用量的 Token 计数或已记录成本。仅凭对话文本（transcript）无法推断 Token 化行为、隐藏系统上下文、缓存输入、工具调用开销与提供方侧的记账，因此 ccusage 不会用文本长度估算 Token。相关调研结论见 docs/guide/source-support-qa.md，其中记录了历史遗留 Grok CLI SQLite 数据与 Devin CLI 的现状（如 Devin 的用量数据在云端，本地无可读历史用量日志；Grok Build CLI 则已转为受支持来源，读取 ~/.grok/sessions/**/updates.jsonl 中 turn_completed 的 usage/modelUsage，成本优先用 Grok 自带的 costUsdTicks，LiteLLM 估算作为回退）。
报告形态：统一视图与聚焦视图
不指定来源名运行 ccusage，即聚合所有检测到的来源：
ccusage daily
ccusage weekly
ccusage monthly
ccusage session
想让同一份报告聚焦单一来源时，在命令后加上数据源命名空间：
ccusage claude daily
ccusage codex daily --speed fast
ccusage opencode weekly
ccusage amp session
ccusage droid daily
ccusage codebuff daily
ccusage hermes daily
ccusage pi monthly
ccusage goose daily
ccusage openclaw daily
ccusage kilo daily
ccusage kimi daily
ccusage qwen daily
ccusage copilot daily
ccusage gemini daily
ccusage antigravity daily
ccusage grok daily
ccusage zcode daily
ccusage <source> <report> 只在你需要把报告收窄到单一来源时使用。统一表格带 Agent 列以便横向比较各来源；聚焦视图去掉这一层比较，在适用时展示该来源的更细粒度信息。
Claude Code 的专属设置与特性（blocks、statusline 等）从 docs/guide/claude/index.md 开始阅读。
首次报告长什么样
docs/guide/getting-started.md 给出了首次运行 daily 报告的示例输出：
╭──────────────────────────────────────────╮
│ │
│ Coding (Agent) CLI Usage Report - Daily │
│ │
╰──────────────────────────────────────────╯
┌────────────┬────────┬────────────────┬────────┬────────┬────────────┐
│ Date │ Agent │ Models │ Input │ Output │ Cost (USD) │
├────────────┼────────┼────────────────┼────────┼────────┼────────────┤
│ 2026-05-16 │ Claude │ • sonnet-4-5 │ 1,234 │ 15,678 │ $12.34 │
│ 2026-05-16 │ Codex │ • gpt-5.5 │ 890 │ 12,345 │ $18.92 │
└────────────┴────────┴────────────────┴────────┴────────┴────────────┘
列含义：Date 使用日期；Agent 产生用量的编码 CLI；Models 使用的模型（宽终端下以项目符号列表展示多个模型）；Input / Output 输入/输出 Token 数；Cost (USD) 基于模型定价的预估成本。在足够宽的终端里还会出现缓存列：Cache Create（创建缓存条目消耗的 Token）与 Cache Read（读缓存的 Token，通常更便宜）。
终端自适应表格
ccusage 会根据终端宽度自动调整表格布局，无需配置：
- 宽终端（≥100 字符）：完整表格，含缓存指标、模型名与详细拆解；
- 窄终端（<100 字符）：紧凑视图，仅保留核心列（Date、Models、Input、Output、Cost）；
- 另可用
--compact强制紧凑模式，适合截图分享（对应 README 中的特性说明）。
颜色输出会自动适配终端能力：--no-color 禁用颜色，--color 强制开启。
深入源码：命令分发与参数校验
在 rust/crates/ccusage/src/main.rs 中，main 先设置定价 JSON 获取器（pricing::set_json_fetcher），随后调用 cli::parse()，再按 cli.command 分发到统一报告或各来源适配器；当没有任何子命令时，默认以 AgentReportKind::Daily 走 adapter::all::run——这正是“默认展示全部来源的日报告”的源码实现。
rust/crates/ccusage/src/cli.rs 展示了参数层的严谨性：解析前先做 UTF-8 校验，随后通过 ccusage_cli_parser::Cli::parse_from_with_config 结合配置上下文解析（参数定义与帮助文本由 rust/crates/ccusage-cli-parser 维护），之后还要依次通过 timezone 校验（timezone::validate）与 最近周期解析（last_window::resolve，负责把 --last 1 这类参数换算成具体日期窗口）。任何错误都会打印用法提示并以退出码 2 结束。
值得注意的校验行为（见 docs/guide/cli-options.md）：
--since/--until接受YYYY-MM-DD或YYYYMMDD，双边界均含；非法拼写或非真实日历日期（如2026-02-30）会以非零退出码报错，而不是静默改变保留行；--since晚于--until的窗口同样被拒绝（无论边界来自命令行、配置文件还是两者混合）。--timezone必须是UTC、其他 IANA 时区名或local；未知名称（如Not/AZone）会以非零退出码报错，而不是静默回退到系统时区导致日期错位。--last在 daily/weekly/monthly 报告上可用（含各 agent 的聚焦版本），在session、blocks、statusline上不可用，且不能与--since、--until、--sections组合。计数含当前周期，所以 daily 报告上--last 2覆盖昨天与今天。
时区如何影响日期分组
main.rs 的测试 formats_dates_with_timezone 给出了具体例证：2024-08-04T23:30:00.000Z 在 UTC 下归为 2024-08-04，在 Asia/Tokyo 下归为 2024-08-05。docs/guide/cli-options.md 的示例是：UTC 1 月 1 日 23 点的用量，在 UTC 与 America/New_York（当地 18 点）下显示为 1 月 1 日，在 Asia/Tokyo（次日 8 点 JST）下显示为 1 月 2 日。对跨时区团队，建议统一用 --timezone UTC。
常用命令速查
以下来自 docs/guide/cli-options.md 与 docs/guide/getting-started.md：
# 日期过滤（双边界含）
ccusage daily --since 2026-01-01 --until 2026-05-16
ccusage monthly --since 20260101
ccusage session --until 20260531
# 最近周期
ccusage daily --last 1 # 今天
ccusage weekly --last 1 # 本周
ccusage monthly --last 3 # 最近三个月
# 输出格式
ccusage daily --json # 或 -j
ccusage daily --breakdown # 或 -b，按模型拆解
ccusage daily --no-cost # 隐藏成本列与 JSON 成本字段
ccusage daily --json | jq ".data[]"
# 成本模式
ccusage daily --mode auto # 默认，有 costUSD 时优先使用
ccusage daily --mode calculate # 总是由 Token 计算
ccusage daily --mode display # 只用已记录的 costUSD
# 排序、离线、时区
ccusage daily --order desc # 默认：最新在前
ccusage daily --offline # 或 -O，使用缓存的定价数据
ccusage daily --timezone UTC # 或 -z Asia/Tokyo
# 项目分析（daily）
ccusage daily --instances # 或 -i，按项目分组
ccusage daily --project myapp # 或 -p，过滤特定项目
ccusage daily --instances --project myapp --json
# 统一报告扩展
ccusage daily --sections daily,monthly,session --json # 一次加载输出多个 JSON 段
ccusage daily --by-agent --json # 每行附加 agents 数组
# 调试
ccusage daily --debug --debug-samples 10 # 显示定价不匹配与配置加载
常用短别名：-j(json)、-b(breakdown)、-O(offline)、-z(timezone)、-i(instances)、-p(project)、-a(active)、-r(recent)。
配置体系：文件、环境变量与优先级
ccusage 支持四种配置方式，按优先级从高到低（docs/guide/configuration.md）：
- 命令行参数（如
--json、--offline）； - 自定义配置文件（
--config指定）； - 环境变量（如
CODEX_HOME、LOG_LEVEL）； - 本地项目配置
.ccusage/ccusage.json> 用户配置~/.config/claude/ccusage.json> 遗留用户配置~/.claude/ccusage.json> 内置默认值。
注意 docs/guide/cli-options.md 中的优先级顺序略有差异（把自定义配置放在命令行之后、本地项目配置之前），两者的共同点是命令行参数始终最高、内置默认值始终最低。
典型示例——配置文件设置默认 mode 与 timezone，命令行参数最终覆盖：
{
"$schema": "https://ccusage.com/config-schema.json",
"defaults": {
"mode": "calculate",
"timezone": "Asia/Tokyo",
"breakdown": true
}
}
ccusage daily --mode display --timezone UTC
# 结果：mode=display（CLI），timezone=UTC（CLI）
配置文件的核心结构（详见 docs/guide/config-files.md）：
defaults：所有命令共享的默认值，可设置since、until、json、mode、debug、debugSamples、order、breakdown、offline、noCost、timezone等；commands.<report>：针对daily/weekly/monthly/session/blocks/statusline的覆盖；<source>.*：18 个数据源命名空间（claude、codex、opencode、amp、droid、codebuff、hermes、pi、goose、openclaw、kilo、kimi、qwen、copilot、gemini、antigravity、grok、zcode）各自的defaults与commands；pricingOverrides：按原始模型名（含适配器前缀，如[pi] gpt-5.4）覆盖单价，字段包括inputCostPerToken、outputCostPerToken、cacheCreationInputTokenCost、cacheReadInputTokenCost、20 万 Token 以上的分级价格、maxInputTokens与fastMultiplier。--offline控制定价数据来源（跳过联网刷新），pricingOverrides控制具体条目的价格补丁，两者互相独立且可在离线模式同时生效。
命名空间命令的选项应用顺序为：defaults → commands.<report> → <source>.defaults → <source>.commands.<report> → 命令行参数。ccusage daily --debug 可以打印配置文件的查找、加载、合并与最终取值全过程，便于排查“配置没生效”的问题。
自定义数据目录通过环境变量设置（完整清单见 docs/guide/getting-started.md 的故障排查小节），例如：
export CLAUDE_CONFIG_DIR="/path/to/your/claude/data"
export CODEX_HOME="/path/to/codex,/archive/codex"
export OPENCODE_DATA_DIR="/path/to/opencode,/archive/opencode"
export COPILOT_HOME="/path/to/copilot"
export COPILOT_OTEL_FILE_EXPORTER_PATH="/path/to/copilot-otel.jsonl"
export ZCODE_HOME="/path/to/zcode,/archive/zcode"
export GROK_HOME="/path/to/grok-home"
目录类变量可用逗号分隔多目录（COPILOT_HOME 与 GROK_HOME 例外，只接受单一根目录）；COPILOT_OTEL_FILE_EXPORTER_PATH 指向单个 JSONL 文件；ZCODE_HOME 支持多根目录并去重。
隐私与安全
- 100% 本地：所有分析都在你的机器上完成；
- 不传输数据：用量数据不会离开你的计算机；
- 只读：ccusage 只读取文件，从不修改它们；
- 开源：数据处理逻辑完全透明（本仓库即源码所在地，如 rust/crates/ccusage/src/main.rs 及各适配器目录）。
已知限制
docs/guide/index.md 明确标注了三项限制：
- 仅限本地文件：只分析当前机器上的数据；
- 不含语言模型之外的 API 调用：如 Web Search 等工具调用的 Token 不计入；
- 成本是估算值：可能不完全等于实际账单金额。
从实现角度看，定价依赖内嵌的 LiteLLM 快照与运行时刷新（rust/crates/ccusage-core/src/pricing.rs），因此价格滞后或模型缺失时，报告中的成本仅应视为参考。
快速开始
前置条件：至少安装并使用过一个受支持的编码 CLI；直接执行推荐 Bun 1.3+。
# 直接执行（推荐，无需全局安装，首次后 bunx 有缓存）
bunx ccusage
# 其他包管理器
npx ccusage@latest
pnpm dlx ccusage
# Nix
nix run github:ccusage/ccusage -- daily
# 全局安装（可选）
npm install -g ccusage
# bun install -g ccusage / yarn global add ccusage / pnpm add -g ccusage
# 验证
ccusage --version
ccusage --help
ccusage daily
运行 bunx ccusage 即默认展示所有检测到来源的日报告。之后可以按 docs/guide/getting-started.md 的路线继续：理解默认统一行为（docs/guide/all-reports.md）、周报（docs/guide/weekly-reports.md）、月报（docs/guide/monthly-reports.md）、会话报告（docs/guide/session-reports.md）、配置（docs/guide/configuration.md）以及 Claude Code 专属特性（docs/guide/claude/index.md）。
如果报告显示无数据，按 docs/guide/getting-started.md 排查三步：确认安装了受支持编码 CLI 并实际使用过、确认数据目录存在（默认位置见上文表格）、必要时通过环境变量指向自定义目录。ccusage --help 可随时查看全部命令选项。