ccusage 配置文件完全指南：defaults、commands 与 pricingOverrides 的深度解析

AI 应用CLI开发工具【免费下载链接】ccusagenpx ccusage项目地址https://gitcode.com/gh_mirrors/cc/ccusage点击查看免费下载本文以 ccusage 的 JSON 配置文件为核心系统讲解配置文件的存放位置、查找优先级、defaults/commands/数据源命名空间三层结构、各命令专属选项、--config自定义配置文件以及pricingOverrides定价覆盖机制。读完本文你将能独立完成把重复 CLI 参数收敛为团队可共享的配置文件、按命令与按数据源差异化配置以及为私有模型补录价格三类实战任务并掌握用--debug定位配置问题的排查方法。文中所有行为说明均有仓库源码佐证可对照 配置加载实现 与 JSON Schema 继续深入。快速上手4 步让配置立即生效ccusage 使用 JSON 配置文件承载持久化设置既能为所有命令提供默认选项也能针对具体命令定制行为免去每次敲命令时重复携带参数。1. 使用 Schema 获得 IDE 支持始终在配置文件中引入 JSON Schema以获得自动补全与校验{ $schema: https://ccusage.com/config-schema.json }仓库中内置的完整 Schema 位于 apps/ccusage/config-schema.json它定义了全部可配置项及其类型、默认值与取值范围例如mode只能取auto/calculate/displayorder只能取asc/desc且默认均为false/auto/asc这类保守值是所有 IDE 提示能力的来源。2. 设置通用默认值把高频使用的选项放进defaults{ $schema: https://ccusage.com/config-schema.json, defaults: { timezone: UTC, breakdown: true } }3. 为特定命令覆盖用commands覆盖某个命令的默认行为{ $schema: https://ccusage.com/config-schema.json, defaults: { breakdown: false }, commands: { daily: { breakdown: true // 只有 daily 需要 breakdown } } }4. 把重复的 CLI 参数收敛进配置文件如果你发现自己总在重复敲同一组 CLI 参数# 之前反复携带 CLI 参数 ccusage daily --breakdown --instances --timezone UTC ccusage monthly --breakdown --timezone UTC把它们转换成配置文件// ccusage.json { $schema: https://ccusage.com/config-schema.json, defaults: { breakdown: true, timezone: UTC }, commands: { daily: { instances: true } } }之后命令变得简洁ccusage daily ccusage monthly配置文件存放位置与查找顺序ccusage 按以下优先级搜索配置文件项目本地配置.ccusage/ccusage.json更高优先级用户级配置~/.claude/ccusage.json或~/.config/claude/ccusage.json较低优先级配置文件按优先级顺序合并项目本地设置覆盖用户设置若通过--config显式指定自定义配置文件则它同时覆盖本地与用户配置。配置文件并非必需——若一个都找不到ccusage 会回退到内置默认值。同时需要注意如果存在多个配置文件只会使用第一个找到的那个。这段行为在源码中有精确对应。配置加载实现 中的discover_config_paths()依次构造.ccusage/ccusage.json与两个 Claude 配置目录下的ccusage.json而claude_config_dirs()会优先读取CLAUDE_CONFIG_DIR环境变量支持逗号分隔多个目录未设置时才回落到~/.config/claude与~/.claudeload_config_value()则按列表顺序取第一个能成功解析且为 JSON 对象的文件——这正对应只使用第一个找到的配置文件这一规则。--config的解析由scan_config_path()config.rs完成它同时支持--config ./my-config.json与--config./my-config.json两种写法。基本配置示例创建一个ccusage.json并写入常用默认值{ $schema: https://ccusage.com/config-schema.json, defaults: { json: false, mode: auto, offline: false, noCost: false, timezone: Asia/Tokyo, breakdown: true } }其中mode控制成本计算方式auto自动、calculate计算、display仅展示、offline决定是否跳过联网刷新而使用内置定价快照、timezone采用 IANA 时区名如Asia/Tokyo、Europe/London用于日期分组、noCost为true时默认隐藏表格中的成本列并从 JSON 输出中移除成本字段。这些选项的合法取值与默认值均记录在 config-schema.json 中如json默认false、mode默认auto、debugSamples默认5。配置结构详解Schema 支持远程与本地添加$schema属性即可获得 IDE 的 IntelliSense 与校验{ $schema: https://ccusage.com/config-schema.json }安装 ccusage 后也可以引用本地 Schema 文件{ $schema: ./node_modules/ccusage/config-schema.json }全局 defaultsdefaults段为统一报告unified reports与遗留 Claude 命令提供共享默认值{ $schema: https://ccusage.com/config-schema.json, defaults: { since: 20260101, until: 20260531, json: false, mode: auto, debug: false, debugSamples: 5, order: asc, breakdown: false, offline: false, noCost: false, timezone: UTC } }把noCost设为true即可默认隐藏表格中的成本列并移除 JSON 输出中的成本字段。since/until是日期过滤边界支持YYYYMMDD与YYYY-MM-DD两种写法——源码中的normalize_date_bound经 config.rs 的detect_date_bound_error统一校验会拒绝格式非法的值并给出 Expected YYYYMMDD or YYYY-MM-DD 之类的报错提示。commands命令级覆盖用commands段覆盖指定统一报告或遗留 Claude 命令的共享默认值{ $schema: https://ccusage.com/config-schema.json, defaults: { mode: auto, offline: false }, commands: { daily: { instances: true, breakdown: true }, blocks: { active: true, tokenLimit: 500000 } } }从源码结构看commands下既支持裸报告名如daily也支持agent:report复合键如codex:dailyoption_maps()config.rs会按报告名、agent:report名逐层收集配置对象并依次应用这为后续的数据源命名空间机制提供了统一底座。数据源命名空间Source-Specific Configuration数据源命名空间用于为单个 AI 数据源设置默认值与报告覆盖。当前支持 19 个命名空间claude、codex、opencode、amp、droid、codebuff、hermes、pi、goose、openclaw、kilo、kimi、qwen、copilot、gemini、antigravity、grok、zcode其余命名空间与全部数据源的完整适配器实现位于 rust/adapters 目录下每个适配器都包含独立的 loader/parser/paths/report 模块。{ $schema: https://ccusage.com/config-schema.json, defaults: { json: false, timezone: UTC }, codex: { defaults: { json: true, offline: true }, commands: { daily: { since: 20260101, until: 20260131 } } }, opencode: { commands: { weekly: { timezone: Europe/London } } }, droid: { defaults: { offline: true } }, codebuff: { commands: { daily: { json: true } } }, pi: { stores: [ { name: omp, path: ~/.omp/agent/sessions } ], defaults: { piPath: /path/to/pi/sessions,/archive/pi/sessions } }, openclaw: { defaults: { openClawPath: /path/to/openclaw,/archive/openclaw } }, kilo: { defaults: { offline: true } }, kimi: { defaults: { offline: true } }, qwen: { defaults: { offline: true } }, copilot: { defaults: { offline: true } }, gemini: { defaults: { offline: true } }, zcode: { defaults: { offline: true } } }该配置作用于数据源导向的命令例如ccusage codex daily ccusage opencode weekly ccusage droid daily ccusage codebuff daily ccusage pi daily ccusage openclaw daily ccusage kilo daily ccusage kimi daily ccusage qwen daily ccusage copilot monthly ccusage gemini daily ccusage antigravity daily ccusage zcode daily运行统一报告如ccusage daily时数据源专属设置同样生效在加载数据前每个数据源都会先拿到自己合并后的选项。pi.stores用于注册额外的 pi 格式会话存储目录适合那些把会话写到~/.pi/agent/sessions之外的第三方工具或 fork。命名 store 在统一报告中叠加在默认piagent 之上使用独立的 agent 名称出现在 JSON 与表格中模型名以[name]前缀开头。store 命名规则很严格名称必须匹配^[a-z][a-z0-9_-]{0,31}$该常量定义于 config_schema.rs必须唯一且不能与内置 agent 名冲突——源码中reserved_named_pi_store_names()config.rs把内置 agent 名加上all一并列为保留名。每个 store 的 path 可以是单个会话目录或以逗号分隔的多个目录~会被展开不存在的路径视为空目录解析后与默认pistore 或其他命名 store 重叠包括嵌套关系的路径会被拒绝。命名 store 不会生成ccusage omp daily这类聚焦命令PI_AGENT_DIR、--pi-path与pi.defaults.piPath仍然只作用于默认piagent。对于命名空间命令选项按以下顺序应用defaultscommands.reportsource.defaultssource.commands.report命令行参数这一顺序与源码option_maps()的收集逻辑严格对应先推入根defaults再推入commands.report随后是source.defaults与source.commands.report命令行参数最后生效保证配置兜底、CLI 拍板。各命令专属选项Daily 命令{ commands: { daily: { instances: true, project: my-project, breakdown: true, since: 20260101, until: 20260531 } } }instances展示各模型实例数量project限定项目breakdown开启按模型拆分的成本明细。源码中由apply_config_to_daily_args()config.rs负责把这些值写入DailyArgs。Weekly 命令{ commands: { weekly: { startOfWeek: monday, breakdown: true, timezone: Europe/London } } }startOfWeek接受sunday~saturday等星期值Schema 中定义为WeekDay枚举见 config_schema.rs 的ConfigWeekDay决定每周的分组起点。Monthly 命令{ commands: { monthly: { breakdown: true, mode: calculate } } }Session 命令{ commands: { session: { id: abc123-session, project: my-project, json: true } } }id直接指定要查看的会话 ID适合在配置里钉住常用会话。Blocks 命令{ commands: { blocks: { active: true, recent: false, tokenLimit: max, sessionLength: 5, live: false, refreshInterval: 1 } } }tokenLimit可以是max或具体的数字字符串Schema 中该字段同时接受 string 与 number 类型sessionLength以小时为单位live开启实时监控refreshInterval以秒为单位控制刷新频率。对应实现见apply_config_to_blocks_args()config.rs。Statusline{ commands: { statusline: { offline: true, cache: true, refreshInterval: 2, modelLabelAliases: { arn:aws:bedrock:ap-northeast-1:012345678910:application-inference-profile/abcde12345: claude-opus-4-6 } } } }modelLabelAliases把原始模型标识如冗长的 Bedrock ARN映射为易读的展示名offline/cache/refreshInterval控制状态行的定价获取方式与刷新节奏。apply_config_to_statusline_args()config.rs是这一段的落地实现它还会处理contextLowThreshold/contextMediumThreshold上下文占用阈值百分比与visualBurnRate等进阶项。自定义配置文件--config用--config指定自定义配置文件可应用于所有命令# 使用特定配置文件 ccusage daily --config ./my-config.json # 对所有命令生效 ccusage blocks --config /path/to/team-config.json这在团队共享、开发/生产环境差异化等场景下尤其有用。如前文所述--config的两种写法空格分隔与形式都由scan_config_path()解析且其优先级高于本地与用户配置文件。定价覆盖pricingOverridesccusage 从嵌入二进制的 LiteLLM 定价快照中查询 token 成本并可在运行时刷新--offline可跳过刷新。当某个模型在 LiteLLM 中缺失时——比如私有部署、内部包装模型如 Pi 的[pi] gpt-5.4、自定义代理——或者快照价格与你的合同价不一致时可在defaults.pricingOverrides下按模型提供单价{ $schema: https://ccusage.com/config-schema.json, defaults: { pricingOverrides: { [pi] gpt-5.4: { inputCostPerToken: 0.0000025, outputCostPerToken: 0.000015, cacheReadInputTokenCost: 0.00000025 }, my-private-claude: { inputCostPerToken: 0.000003, outputCostPerToken: 0.000015, maxInputTokens: 1000000 } } } }键必须匹配原始模型名pricingOverrides的键必须与源日志中记录的原始模型名完全一致包含适配器前缀适配器前缀示例键Pi[pi][pi] gpt-5.4命名 Pi store[name][omp] gpt-5.4其他Claude、Codex、OpenCode 等无claude-sonnet-4-5、gpt-5.5要拿到准确名称运行ccusage agent daily --json并查看逐行拆分的model字段即可。支持的字段所有字段均可选未指定的字段回退到 LiteLLM 条目若存在或0.0inputCostPerToken、outputCostPerToken— 基础每 token 单价cacheCreationInputTokenCost、cacheReadInputTokenCost— 缓存写入/读取价格inputCostPerTokenAbove200kTokens、outputCostPerTokenAbove200kTokens、cacheCreationInputTokenCostAbove200kTokens、cacheReadInputTokenCostAbove200kTokens— 超过 20 万 token 后的阶梯定价maxInputTokens— 上下文窗口上限Claude statusline hook 使用fastMultiplier— 消息被记录为 fast 模式时应用的倍率这些字段的落地路径很清晰配置层通过merge_pricing_overrides()config.rs把各层的覆盖按模型、按字段逐个合并字段级覆盖而非整条替换运行时则由apply_explicit_pricing_override()rust/crates/ccusage-core/src/pricing.rs将每个字段写入最终价格未提供的字段保持原有值。与离线模式的关系--offline与pricingOverrides相互独立--offline控制数据来源——跳过网络刷新只使用内嵌的 LiteLLM 快照pricingOverrides控制具体条目——为个别模型打补丁或替换价格。覆盖在在线与离线两种模式下都生效。这套机制适用于团队配置—— 在团队成员间共享配置文件环境差异化—— 开发/生产使用不同配置项目级覆盖—— 不同项目使用不同设置完整配置示例ccusage.example.json仓库根目录的 ccusage.example.json 提供了一份覆盖全部要点全局默认值、命令级覆盖、各选项正确类型的完整参考{ $schema: ./apps/ccusage/config-schema.json, defaults: { json: true, mode: auto, timezone: Asia/Tokyo, offline: false, noCost: false, breakdown: false, pricingOverrides: { [pi] gpt-5.4: { inputCostPerToken: 0.0000025, outputCostPerToken: 0.000015, cacheReadInputTokenCost: 0.00000025 } } }, commands: { daily: { instances: true, order: desc, projectAliases: ccusageUsage Tracker,my-long-project-nameProject X }, monthly: { breakdown: true }, weekly: { startOfWeek: monday }, blocks: { tokenLimit: 500000, sessionLength: 5, active: false }, statusline: { offline: true } } }注意其中projectAliases用keydisplay逗号分隔的格式为长项目名设置展示别名是日常美化报告输出的实用技巧。配置优先级总览设置按以下优先级生效从高到低命令行参数如--json、--offline自定义配置文件--config /path/to/config.json指定项目本地配置.ccusage/ccusage.json用户配置~/.config/claude/ccusage.json遗留配置~/.claude/ccusage.json内置默认值示例// .ccusage/ccusage.json { defaults: { mode: calculate } }# 配置文件把 mode 设为 calculate ccusage daily # 使用 mode: calculate # 但 CLI 参数会覆盖它 ccusage daily --mode display # 使用 mode: display用 --debug 排查配置加载--debug标志可输出配置加载细节# 调试配置加载 ccusage daily --debug # 调试自定义配置文件 ccusage daily --debug --config ./my-config.json调试输出包含检查了哪些配置文件、哪些被找到已加载配置的 Schema 与选项详情各来源选项的合并过程每个选项最终采用的值示例输出[ccusage] ℹ Debug mode enabled - showing config loading details [ccusage] ℹ Searching for config files: • Checking: .ccusage/ccusage.json (found ✓) • Checking: ~/.config/claude/ccusage.json (found ✓) • Checking: ~/.claude/ccusage.json (not found) [ccusage] ℹ Loaded config from: .ccusage/ccusage.json • Schema: https://ccusage.com/config-schema.json • Has defaults: yes (3 options) • Has command configs: yes (daily) [ccusage] ℹ Merging options for daily command: • From defaults: modeauto, offlinefalse • From command config: instancestrue • From CLI args: debugtrue • Final merged options: { mode: auto (from defaults), offline: false (from defaults), instances: true (from command config), debug: true (from CLI) }这个输出顺序与源码中option_maps()的defaults → commands → CLI 兜底合并模型完全吻合看到这里即可快速定位为什么某个值不是我设的那个。最佳实践版本控制项目配置应纳入版本控制# 加入 git git add .ccusage/ccusage.json git commit -m Add ccusage configuration为团队配置撰写文档在团队配置旁用 README 解释每一项取舍team-configs/ ├── ccusage.json └── README.md # 解释配置选择故障排除配置未生效检查文件位置是否正确.ccusage/ccusage.json或~/.config/claude/ccusage.json确认 JSON 语法合法用--debug查看加载细节确保选项名与 Schema 完全一致注意驼峰拼写如debugSamples、tokenLimit、refreshIntervalJSON 无效用 JSON 校验器或支持 JSON 的 IDE 检查# 校验 JSON 语法 jq . ccusage.jsonSchema 校验错误确保选项值符合期望类型{ defaults: { tokenLimit: 500000, // ✅ 字符串或数字 active: true, // ✅ 布尔值 refreshInterval: 2 // ✅ 数字 } }相关文档命令行选项 — 全部可用 CLI 参数环境变量 — 环境配置含CLAUDE_CONFIG_DIR等配置总览 — 完整的配置指南赞分享AI 应用CLI开发工具【免费下载链接】ccusagenpx ccusage项目地址https://gitcode.com/gh_mirrors/cc/ccusage点击查看免费下载相关推荐presenterm 配置文件完全指南defaults、bindings、snippet 与 export 全量设置详解presenterm 配置文件完全指南defaults、bindings、snippet 与 export 全量设置详解 本文基于 presenterm 官方CLIFlatpickr默认配置完全指南深度解析Defaults对象与配置优先级规则Flatpickr默认配置完全指南深度解析Defaults对象与配置优先级规则 Flatpickr是一个轻量级、功能强大的JavaScript日期选择器库它前端UI组件Celery 配置指南Configuration and Defaults 完全解析Celery 配置指南Configuration and Defaults 完全解析 导读 本篇文章以 Celery 官方配置文档 docs/usergui任务调度后端消息队列上一篇TiDB分区表实战告别数据膨胀的7个核心技巧下一篇TypeORM事务管理保证数据一致性的高级技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考