企业官网建设流程全解析

• AI 应用
• CLI
• 开发工具

本文以 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/display，order只能取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 按以下优先级搜索配置文件：

1. 项目本地配置：.ccusage/ccusage.json（更高优先级）
2. 用户级配置：~/.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与~/.claude；load_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" }

全局 defaults

defaults段为统一报告（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:daily），option_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。

对于命名空间命令，选项按以下顺序应用：

1. defaults
2. commands.<report>
3. <source>.defaults
4. <source>.commands.<report>
5. 命令行参数

这一顺序与源码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()解析，且其优先级高于本地与用户配置文件。

定价覆盖：pricingOverrides

ccusage 从嵌入二进制的 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的键必须与源日志中记录的原始模型名完全一致，包含适配器前缀：

要拿到准确名称，运行ccusage <agent> daily --json并查看逐行拆分的model字段即可。

支持的字段

所有字段均可选；未指定的字段回退到 LiteLLM 条目（若存在）或0.0：

• inputCostPerToken、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": "ccusage=Usage Tracker,my-long-project-name=Project X" }, "monthly": { "breakdown": true }, "weekly": { "startOfWeek": "monday" }, "blocks": { "tokenLimit": "500000", "sessionLength": 5, "active": false }, "statusline": { "offline": true } } }

注意其中projectAliases用key=display逗号分隔的格式为长项目名设置展示别名，是日常美化报告输出的实用技巧。

配置优先级总览

设置按以下优先级生效（从高到低）：

1. 命令行参数（如--json、--offline）
2. 自定义配置文件（--config /path/to/config.json指定）
3. 项目本地配置（.ccusage/ccusage.json）
4. 用户配置（~/.config/claude/ccusage.json）
5. 遗留配置（~/.claude/ccusage.json）
6. 内置默认值

示例：

// .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: mode="auto", offline=false • From command config: instances=true • From CLI args: debug=true • 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 # 解释配置选择

故障排除

配置未生效

1. 检查文件位置是否正确（.ccusage/ccusage.json或~/.config/claude/ccusage.json）
2. 确认 JSON 语法合法
3. 用--debug查看加载细节
4. 确保选项名与 Schema 完全一致（注意驼峰拼写，如debugSamples、tokenLimit、refreshInterval）

JSON 无效

用 JSON 校验器或支持 JSON 的 IDE 检查：

# 校验 JSON 语法 jq . < ccusage.json

Schema 校验错误

确保选项值符合期望类型：

{ "defaults": { "tokenLimit": "500000", // ✅ 字符串或数字 "active": true, // ✅ 布尔值 "refreshInterval": 2 // ✅ 数字 } }

相关文档

• 命令行选项 — 全部可用 CLI 参数
• 环境变量 — 环境配置（含CLAUDE_CONFIG_DIR等）
• 配置总览 — 完整的配置指南

• AI 应用
• CLI
• 开发工具