ccusage：从本地数据一键分析 Claude Code、Codex 等 18 种编码 Agent CLI 的 Token 用量与成本

原创2026-09-20 22:38:241,682 阅读

文章标签：CLI开发工具AI 应用LLMOps

ccusage：从本地数据一键分析 Claude Code、Codex 等 18 种编码 Agent CLI 的 Token 用量与成本

ccusage 是一个面向编码 Agent CLI 的本地用量分析工具：它读取 Claude Code、Codex、OpenCode、GitHub Copilot CLI 等 18 种工具留在本机的日志数据，将其汇总为按日、按周、按月、按会话（Session）的结构化报告，并给出按模型拆分的成本。本文以仓库内 apps/ccusage/README.md 为骨架，结合 Rust 源码与配置 Schema，完整讲解安装方式、命令体系、输出选项与底层实现原理，读完后你可以在任何机器上开箱统计自己的 Agent 花费、按项目/时间片做成本审计，并理解该工具“npm 启动器 + Rust 原生二进制”的整体架构。

它解决什么问题

日常使用 Claude Code、Codex 这类编码 Agent 时，token 消耗与美元成本散落在各工具自己的本地会话文件中，缺乏统一的统计视角。ccusage 的核心定位用一句话概括：从本地数据分析编码（Agent）CLI 的 token 用量与成本（Analyze coding (agent) CLI token usage and costs from local data）。

它不联网上传数据，只读取本机日志，因此统计结果完全基于你自己的数据。你可以在不安装任何全局依赖的情况下直接运行：

npx ccusage@latest

第一次运行即可看到所有被检测到的数据源按天聚合的用量报告。

支持的数据源（Supported Sources）

ccusage 从编码 Agent CLI 的本地用量数据出发，生成 daily、weekly、monthly、session 四种报告。当前版本共支持 18 个数据源，每个源都有对应的聚焦命令（focused command），统一形态为 ccusage <source> daily：

数据源	聚焦命令示例
Claude Code	`ccusage claude daily`
Codex	`ccusage codex daily`
OpenCode	`ccusage opencode daily`
Amp	`ccusage amp daily`
Droid	`ccusage droid daily`
Codebuff	`ccusage codebuff daily`
Hermes Agent	`ccusage hermes daily`
pi-agent	`ccusage pi daily`
Goose	`ccusage goose daily`
OpenClaw	`ccusage openclaw daily`
Kilo	`ccusage kilo daily`
Kimi	`ccusage kimi daily`
Qwen	`ccusage qwen daily`
GitHub Copilot CLI	`ccusage copilot daily`
Gemini CLI	`ccusage gemini daily`
Antigravity	`ccusage antigravity daily`
Grok Build CLI	`ccusage grok daily`
ZCode	`ccusage zcode daily`

如果你不想单独指定源，可以使用 ccusage daily、ccusage weekly、ccusage monthly 或 ccusage session，一条命令即可把所有被检测到的数据源合并进同一份报告。

从源码结构看，每个数据源都是一个独立的 Rust adapter crate（位于 rust/adapters/），例如 claude/、codex/、copilot/、gemini/ 等，它们共享 common/ 与 ccusage-core 的聚合逻辑，而每个 adapter 内部通常按 paths.rs（路径发现）、parser.rs（原始记录解析与 token/模型映射）、loader.rs（文件遍历与去重）、report.rs（JSON/表格行整形）划分职责，细节见 rust/adapters/README.md。

安装方式

包运行器（无需全局安装）

ccusage 可以直接通过各类包运行器临时运行，不必全局安装：

# npm
npx ccusage@latest

# Nix
nix run github:ccusage/ccusage -- daily

# 其他包运行器
bunx ccusage
pnpm dlx ccusage
pnpx ccusage

# PR 预览构建（用于尝鲜特定 PR 的构建产物）
bunx -p https://pkg.pr.new/ccusage/ccusage@<pr-number> ccusage --offline

其中 bunx 会缓存下载过的包，因此首次启动之后重复运行会更快。

为什么它这么轻：npm 包只是“启动器”

从 apps/ccusage/package.json 可以看出，npm 包本身几乎不含业务逻辑：bin 字段只声明了 ./src/cli.js，真正的 CLI 是 Rust 编写的原生二进制，通过 optionalDependencies 按平台/架构分发（@ccusage/ccusage-darwin-arm64、@ccusage/ccusage-linux-x64、@ccusage/ccusage-win32-x64 等 6 个平台包）。

apps/ccusage/AGENTS.md 对此做了明确说明：发布到 npm 的 ccusage 包只承载 npm 元数据、src/cli.js 启动器、config-schema.json 以及打包/基准脚本，CLI 本体在 rust/crates/ccusage。bin 启动器的工作是：根据当前 process.platform / process.arch 解析出对应的原生二进制包（如 @ccusage/ccusage-linux-x64/bin/ccusage），用 spawn 以 stdio: 'inherit' 启动它，并把 SIGINT、SIGTERM 等信号转发给子进程；如果找不到匹配平台的原生二进制，则输出错误提示要求重装以安装可选原生依赖。

命令用法（Usage）

基础命令

# 基础用法
bunx ccusage          # 默认：所有被检测到的数据源按天展示
bunx ccusage daily    # 所有数据源按天
bunx ccusage weekly   # 所有数据源按周
bunx ccusage monthly  # 所有数据源按月
bunx ccusage session  # 所有数据源按会话
bunx ccusage blocks   # Claude Code 5 小时计费窗口
bunx ccusage statusline  # Claude Code 状态栏（hooks 用，Beta）

数据源聚焦报告与组合选项

bunx ccusage claude daily --mode display
bunx ccusage codex daily --speed fast
bunx ccusage opencode weekly
bunx ccusage amp session
bunx ccusage droid daily
bunx ccusage codebuff daily
bunx ccusage hermes daily
bunx ccusage goose daily
bunx ccusage openclaw daily
bunx ccusage kilo daily
bunx ccusage kimi daily
bunx ccusage qwen daily
bunx ccusage copilot daily
bunx ccusage gemini daily
bunx ccusage antigravity daily
bunx ccusage grok daily
bunx ccusage zcode daily
bunx ccusage pi daily --pi-path /path/to/sessions
bunx ccusage pi daily --pi-path /path/to/sessions,/archive/pi/sessions

注意 --pi-path 支持用逗号分隔多个目录，从而把多个 profile 或归档目录合并统计。

显式统一报告（Unified Report）

# 显式聚合所有数据源
bunx ccusage daily --all

# 一次加载数据、输出多个 JSON 报告节
bunx ccusage daily --sections daily,monthly,session --json

# 按 Agent 拆分统计
bunx ccusage daily --by-agent --json

其中 --sections 接受 daily,weekly,monthly,session 的逗号分隔列表（被调用的报告节总是包含在内），--by-agent 仅对 JSON 生效，用于给 daily/weekly/monthly 的行追加按 agent 的细分。

过滤与输出选项

# 日期范围过滤（含端点）
bunx ccusage daily --since 2026-04-25 --until 2026-05-16

# 最近时段跳转
bunx ccusage daily --last 1    # 今天
bunx ccusage weekly --last 1   # 本周
bunx ccusage monthly --last 1  # 本月

# 输出格式
bunx ccusage daily --json          # JSON 输出
bunx ccusage daily --no-cost       # 隐藏成本列与 JSON 成本字段
bunx ccusage daily --timezone UTC  # 用 UTC 时区分组

# 项目分析（Claude Code）
bunx ccusage claude daily --instances  # 按项目/实例分组
bunx ccusage claude daily --project myproject  # 过滤到指定项目
bunx ccusage claude daily --instances --project myproject --json  # 组合使用

# 紧凑模式（截图/分享）
bunx ccusage --compact          # 强制紧凑表格
bunx ccusage monthly --compact  # 紧凑月度报告

从 Rust CLI 入口可以看到命令分发逻辑：daily 走 commands::run_daily，weekly/monthly 走 run_bucket/run_weekly，session/blocks/statusline 以及各 agent 子命令（codex、opencode、copilot、gemini……）分别路由到对应 adapter 的 run；当不带任何子命令时，默认执行 adapter::all::run（即所有检测源按天聚合）。日期过滤、--last 窗口解析、时区校验等则在 cli.rs 的 parse() 阶段完成——非法日期或未知时区会直接以非零退出码报错，而不是静默回退。

CLI 选项的更多细节

针对不同命令还有一批专用选项（详见 docs/guide/cli-options.md）：

成本计算模式 --mode：auto（默认，优先使用源数据自带的 costUSD）、calculate（总是按 token 计算）、display（只展示预计算的 costUSD）。
排序 --order desc|asc：默认最新在前。
离线模式 --offline（-O）：使用内置缓存的价格数据，无需网络。
时区 --timezone（-z）：接受 UTC、IANA 时区名或 local。
调试 --debug、--debug-samples N：展示定价不匹配与配置加载信息。
自定义配置文件 --config ./my-config.json。
项目分组 --instances（-i）、--project（-p）。
周起始日 ccusage weekly --start-of-week monday|sunday。
会话过滤 ccusage session --id <id>、ccusage session --project myproject。
Blocks：--active（仅活动窗口）、--recent（最近 3 天）、--token-limit 500000|max（告警阈值）、--live --refresh-interval 2（实时监控）、--session-length 5（会话时长）。
Statusline：--offline、--cache、--refresh-interval 5。
JSON 管道：ccusage daily --json | jq '.data[]'。

常见短别名对照：-j（JSON）、-b（breakdown）、-O（offline）、-z（timezone）、-i（instances）、-p（project）、-a（active）、-r（recent）。

核心特性一览

每日报告：按日期聚合 token 用量与成本。
月度报告：按月聚合。
会话报告：按会话分组展示用量。
统一 CLI 报告：在一个 CLI 里同时查看 Claude Code、Codex、OpenCode、Amp、Droid、Codebuff、Hermes Agent、pi-agent、Goose、OpenClaw、Kilo、Kimi、Qwen、GitHub Copilot CLI、Gemini CLI、Antigravity、Grok Build CLI 与 ZCode 的用量。
5 小时计费块报告：跟踪 Claude 计费窗口内的用量，支持活动块实时监控。
Statusline 集成（Beta）：为 Claude Code 状态栏 hooks 提供紧凑用量显示。
模型追踪：查看各数据源使用了哪些模型。
模型成本拆分：--breakdown 展示按模型的成本明细。
日期过滤：--since / --until 过滤报告区间。
最近时段：任意 daily/weekly/monthly 报告用 --last 1 直达今天/本周/本月。
自定义路径：支持自定义本地数据目录位置。
漂亮输出：彩色表格 + 自适应响应式布局。
智能表格：窄终端（< 100 字符）自动切紧凑模式，只保留核心列。
紧凑模式：--compact 强制紧凑布局，适合截图与分享。
增强模型展示：模型名以项目符号列表呈现，提升可读性。
JSON 输出：--json 导出结构化数据。
成本追踪：按天/月/会话展示美元成本。
成本隐藏：--no-cost 移除成本列与 JSON 成本字段。
缓存 token 支持：分别跟踪展示 cache creation 与 cache read token。
离线模式：--offline 使用预缓存定价数据，无网络也能运行。
自定义定价覆盖：在 ccusage.json 中按原始模型名覆盖 token 单价，无需重新构建。
Claude 实例支持：--instances 按项目分组、--project 过滤指定项目。
时区支持：--timezone 配置日期分组时区。
配置文件：JSON 配置文件设置默认值，带 IDE 自动补全与校验。

配置文件与选项优先级

ccusage 支持通过命令行参数、环境变量、配置文件三种途径组合配置。命令行参数优先级最高，其次是通过 --config 指定的自定义配置文件、环境变量（如 CODEX_HOME、LOG_LEVEL）、本地项目配置 .ccusage/ccusage.json、用户级配置 ~/.config/claude/ccusage.json、旧版用户配置 ~/.claude/ccusage.json，最后是内置默认值。

一份典型的用户配置（配置详解见 docs/guide/configuration.md）：

{
	"$schema": "https://ccusage.com/config-schema.json",
	"defaults": {
		"timezone": "America/New_York",
		"breakdown": true
	},
	"commands": {
		"daily": {
			"instances": true
		}
	}
}

配置项还可以按数据源命名空间拆分（如 claude.commands.daily、codex.defaults），聚焦命令（ccusage codex daily）和统一报告（ccusage daily）都会读取对应源的合并配置。

npm 包内附带了一份完整的 JSON Schema（约 1.4 万行，覆盖所有数据源的命令与选项），它为 IDE 自动补全、校验乃至后续生成 Schema 快照测试提供依据；生成该 Schema 的 Rust 代码位于 ccusage-config crate。Schema 中可以看到诸如 mode 的枚举 ["auto","calculate","display"]、order 的枚举 ["desc","asc"]、compact/json/no-cost 等布尔开关，以及 pricingOverrides（按原始模型名覆盖定价）等字段。

开发与构建（Nix + just）

贡献者环境

仓库为贡献者准备了基于 Nix flake 的开发环境（通过 nix-direnv 固定工具链），日常开发任务用 just 驱动：

# 克隆仓库
git clone https://github.com/ccusage/ccusage.git
cd ccusage

# 允许 direnv 加载 Nix dev shell
direnv allow

dev shell 会提供固定版本的 pnpm、Rust 工具链、GitHub CLI、git hooks、生成的本地 agent skills 以及打包工具；只有任务确实需要 workspace 的 node_modules 时才运行 pnpm install --frozen-lockfile。在 Nix 环境中用 just 执行项目任务（just --list 可查看全部 recipe）：

just fmt
just test
just check

Nix 包与定价数据

flake 将 ccusage 作为默认 package 和 app 暴露：

nix run github:ccusage/ccusage
nix run github:ccusage/ccusage -- codex daily --offline
nix build github:ccusage/ccusage

Nix 构建会把锁定 litellm flake input 中的 LiteLLM 定价文件嵌入二进制，因此沙箱构建无需在构建期联网抓取定价。若要更新锁定的定价快照，运行：

just update-litellm-pricing

仓库中还有定时执行的 update pricing workflow，执行同样的更新与校验，并在定价快照变化时自动打开 PR。非 Nix 的 Cargo 构建则从 flake.lock 读取相同的锁定 LiteLLM revision，并在构建期从该 revision 拉取定价文件。

从源码到命令行：整体架构回顾

把上面各部分串起来，ccusage 的完整链路是：

npm 层（apps/ccusage）：package.json 声明 bin 入口，src/cli.js 解析平台/架构、定位并 spawn 原生二进制，config-schema.json 为配置文件提供 Schema。
CLI 解析层（rust/crates/ccusage/src/cli.rs）：读取参数与环境，结合 ccusage-config 合并配置文件，校验时区与 --last 窗口。
命令分发层（rust/crates/ccusage/src/main.rs）：把 daily/weekly/monthly/session/blocks/statusline 及各 agent 子命令分发给对应实现。
数据源适配层（rust/adapters/）：每个源一个 crate，负责日志发现、解析、token/模型映射与定价，共享逻辑沉淀在 ccusage-core 与 ccusage-adapter-common。

ccusage：从本地数据一键分析 Claude Code、Codex 等 18 种编码 Agent CLI 的 Token 用量与成本

ccusage：从本地数据一键分析 Claude Code、Codex 等 18 种编码 Agent CLI 的 Token 用量与成本

它解决什么问题

支持的数据源（Supported Sources）

安装方式

包运行器（无需全局安装）

为什么它这么轻：npm 包只是“启动器”

命令用法（Usage）

基础命令

数据源聚焦报告与组合选项

显式统一报告（Unified Report）

过滤与输出选项

CLI 选项的更多细节

核心特性一览

配置文件与选项优先级

开发与构建（Nix + just）

贡献者环境

Nix 包与定价数据

从源码到命令行：整体架构回顾

相关文档

热门文章

ccusage：从本地数据一键分析 Claude Code、Codex 等 18 种编码 Agent CLI 的 Token 用量与成本

ccusage：从本地数据一键分析 Claude Code、Codex 等 18 种编码 Agent CLI 的 Token 用量与成本

它解决什么问题

支持的数据源（Supported Sources）

安装方式

包运行器（无需全局安装）

为什么它这么轻：npm 包只是“启动器”

命令用法（Usage）

基础命令

数据源聚焦报告与组合选项

显式统一报告（Unified Report）

过滤与输出选项

CLI 选项的更多细节

核心特性一览

配置文件与选项优先级

开发与构建（Nix + just）

贡献者环境

Nix 包与定价数据

从源码到命令行：整体架构回顾

相关文档

相关推荐

热门文章