Claude Code 费用跟踪工具对比：日志、用量页与 OTel

Claude Code 费用跟踪器实际读取的内容

每个 Claude Code 费用跟踪器都会读取三类数据源之一，而数据源决定了它能回答什么问题。日志解析器读取您本地磁盘上的会话记录文件。仪表板读取 Anthropic 为您的账户或组织保留的使用记录。指标后端读取 Claude Code 在启用后发出的 OpenTelemetry（OTel）数据流。这三类工具可能同时正确，但结果仍然不一致，因为它们统计的是不同内容。

本指南不再解释 token。Claude Code 如何统计 token 使用量介绍输入、输出、缓存写入和缓存读取；只有先理解这些内容，仪表板数据才有意义。这里讨论的问题更具体：对于每种工具类型，它能看到什么，以及永远无法看到什么。

为什么同一天出现了 3 个 Claude Code 支出跟踪器

同一天发布了 3 个独立的 Claude Code 支出跟踪器。它们不是同一工具的 3 个版本，这一点很有价值。其中一个解析本地会话文件。一个封装账户用量页面。另一个是由您自行运行的托管式追踪后端。

它们同时出现，是因为代理会话的成本不再直观。聊天的成本大致相当于屏幕上显示的金额。代理会读取 20 个文件、运行测试套件，并在每轮请求中重新发送整个对话，因此账单取决于您从未输入的上下文。对于订阅用户，Claude Code 显示的会话金额只是估算值，Anthropic 表示该金额与计费无关；真正重要的是用量条，而它在某些日期会比其他日期消耗得更快。这 3 种工具分别弥补了这一缺口的不同部分。

形态 1：本地日志解析器告诉您今天花了多少

Claude Code 会将每段对话以 JSON Lines（JSONL）格式存储在 ~/.claude/projects/<project>/<session-id>.jsonl 中，其中 <project> 是您的工作目录路径，非字母数字字符会替换为 -。该文件中的每次 assistant 回复都包含本次请求的 token 数量。日志解析器会汇总这些数量并计算价格。

ccusage 是大多数人首先使用的工具。它无需安装：

npx ccusage@latest daily
npx ccusage@latest daily --breakdown
npx ccusage@latest blocks
npx ccusage@latest session --json

daily 按日期汇总。--breakdown 按模型拆分每一行，这可以帮助您找出某个使用 Opus 的下午是否占了一周用量的大部分。blocks 按订阅重置所依据的五小时窗口分组。session 按对话汇总，daily --instances 按项目分组，以便查看哪个代码仓库成本较高。添加 --since 和 --until 可以限定日期范围；运行 npx ccusage@latest daily --help 可查看您的版本所需的日期格式。截至 October 2026，它还可以读取其他 agent CLI 的数据，包括 Codex 和 OpenCode。如果您要比较这些工具，这一点很重要。

价格来自模型价格表，该工具提供三种成本模式。--mode auto 会在文件中存在 costUSD 值时使用 Claude Code 写入的该值；没有该值时，则根据 token 数量计算。--mode calculate 始终根据 token 数量计算，并忽略任何已记录的成本。--mode display 只显示已记录的成本；对于没有记录成本的行，则输出 $0.00。如果总数看起来不正确，请先使用 calculate 运行相同的报告，再使用 display 运行一次。两者差距较大，表示大多数条目没有记录成本，因此您看到的全部都是估算值。如果您使用合同价格，请在 defaults 下的 ccusage.json 配置文件中设置 pricingOverrides，以替换各个模型的价格。

同一份数据也可以用于提示信息。ccusage statusline 会为 Claude Code 状态栏输出一行简要信息，并像其他状态栏命令一样接入 ~/.claude/settings.json。有关设置块及其接收字段，请参阅构建 Claude Code 状态栏。

日志解析器无法看到未在本机发生的活动。另一台笔记本电脑上的活动、claude.ai 中的会话以及团队成员的工作，都位于对应设备的磁盘上。旧数据也可能缺失，因为在 cleanupPeriodDays 设置下，transcript 默认会在 30 天后清理。因此，除非您已将其归档，否则上个季度的数据已经不存在。

还有一个风险，这与文件结构有关。Anthropic 的文档说明，条目格式属于 Claude Code 的内部格式，并且会随版本变化。因此，直接解析这些文件的脚本可能在任何版本发布后失效。所有此类工具都存在这个问题。这也是手写一个针对 JSONL 的 jq 单行命令并不像看起来那么可靠的原因：维护中的解析器会为您跟进格式变化，而字段重命名后，您的单行命令可能会输出一个看似准确但实际错误的数字。

最后，订阅场景下的美元金额需要加以说明。Pro 或 Max 计划额度内的使用量不会按 token 计费，因此该数字表示按 API 标准价格计算时这些 token 的成本。它衡量的是使用量大小，不是您的账单。例外是 usage credits：如果您启用该功能，超过计划额度的使用量会按标准 API 价格单独计费；claude.ai 会在 Settings > Usage 下显示当月支出。如果您真正想了解的是应该选择哪个计划，该比较需要单独进行：请参阅API 计费与 Claude 订阅的比较。

形态 2：内置用量界面会告诉您哪个模型消耗了预算

Claude Code 自带报告功能，但大多数人从未打开过。请在会话中运行 /usage。顶部的 Session 区块会显示各模型的 token 用量，以及当前会话的美元金额。除非管理员在托管设置中配置了 modelPricing 表，否则该金额会根据 token 数量和标准目录价格在本地计算；如果配置了该表，Total cost 行会显示 at your organization's configured rates。无论哪种情况，该金额都只是估算值，可能与账单不同。对于 Pro 或 Max，Anthropic 表示该金额与计费无关，因为相关用量已包含在套餐中。/clear 开始新对话时，总量会重置。

在 Pro、Max、Team 或按席位计费的 Enterprise 套餐中，同一界面还会显示您已使用的套餐限额。按用量计费的 Enterprise 没有可耗尽的包含额度，因为每个 token 都按 API 费率计费。在这些套餐中，该界面还会按总量百分比显示近期用量分别来自 skills、subagents、plugins 和各个 MCP 服务器的比例。它会标记占近期用量 10% 或以上的行为，例如较长的上下文或缓存未命中。按 d 或 w 可在最近 24 小时和最近 7 天之间切换。这些数值是近似值，由本机的本地会话历史计算得出，因此不会统计第二台设备的用量。当该进度条为空而不只是数值较低时，界面会提示该窗口已关闭，但不会告诉您如何继续工作；而达到限额后该怎么做，则是关于模型、上下文和套餐的另一项决策。

当开发者数量超过 1 人后，数据会转移到帐户级别。API 组织可使用 Console 的 usage 页面、Claude Code 仪表板，以及 Claude Code Analytics API。仪表板显示各成员的支出和已接受的代码行数；Analytics API 使用管理员密钥返回相同的每日用户指标。Teams 和 Enterprise 套餐可在管理控制台中查看支出报告并导出 CSV。该报告每天更新，但只涵盖 usage credit 支出：席位额度内的用量不会按美元计量。Enterprise 还提供 analytics API。您能看到哪些数据取决于每名开发者的登录方式，因此混合组织需要查看两份报告，再手动相加。

用于规划预算时，截至 2026 年 10 月，Anthropic 成本文档公布的数字是：每名开发者每个活跃日平均约 $13，每名开发者每月 $150 至 $250，且 90% 的用户每个活跃日支出低于 $30。请将其视为企业部署中的公开基准，而不是对您团队的预测。先运行一组试点，再进行测量，然后再外推。

仪表板无法查看低于“天”和“人员”这两个粒度的详细信息。它们可以告诉您 Opus 占用了星期二的大部分用量，但不会告诉您具体是哪个提示词、哪个代码仓库或哪个 CI 作业造成的。它们还存在延迟，因为组织级报告每天更新。因此，仪表板适合复盘，不适合用来捕获当天失控的 agent。要捕获失控的 agent，需要设置限制，而不是查看报告；这正是在 VPS 上限制 agent 成本所讨论的内容。

方案 3：使用您自己的 OpenTelemetry 堆栈，找出哪个提示词发生了回归

设置一个环境变量后，Claude Code 会发送 OpenTelemetry 指标和事件。这是唯一一种能将每个用户的 token 和成本数据近乎实时地传输到您控制的系统中的方案。指标包括 claude_code.cost.usage（以 USD 计）、claude_code.token.usage（以 token 计）、claude_code.session.count 和 claude_code.active_time.total。

token 指标最有价值，因为它包含属性。每个数据点都包含 type，其值为 input、output、cacheRead 或 cacheCreation，还包含 model 和 query_source，其值为 main、subagent 或 auxiliary。它还包含 agent.name、skill.name、mcp_server.name 和 mcp_tool.name。您自行配置的 MCP 服务器名称以及自定义 subagent 的名称会以 custom 的形式发送，除非您设置 OTEL_LOG_TOOL_DETAILS=1；该设置还会将 Bash 命令和工具输入加入工具事件。这样就能回答仪表板无法回答的问题：账单中有多少来自 subagent，而不是您自己的交互；某个 MCP 服务器是否使输入 token 翻倍；有人修改 CLAUDE.md 后，缓存读取是否骤降。缓存行为通常是意外情况的来源，提示词缓存何时能够收回成本会解释应如何查看这些数据。

这里需要更正一点，因为相关讨论中总会出现这个问题。Langfuse 是很好的自托管追踪后端，在 VPS 上运行 Langfuse 的方法参见为 agent 追踪自托管 Langfuse。它的 OTLP 端点只接受追踪数据。Claude Code 默认导出指标和日志事件，而不是 span，因此将 OTEL_EXPORTER_OTLP_ENDPOINT 指向 Langfuse 后，项目会保持为空，也不会产生任何有用的错误信息。导出 span 的功能确实存在，但目前处于 beta 状态，只有设置 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 和 OTEL_TRACES_EXPORTER 后才会启用。Langfuse 自带的 Claude Code 集成采用不同方式：Stop hook 或安装该 hook 的插件会在每次响应后读取会话记录，并将其转换为追踪数据，因此同样受限于本地日志解析器。对于您自行构建的 API agent，Langfuse 是合适的工具，因为您自己的代码会为每个 span 创建提示词、模型和成本信息。若要统计 Claude Code CLI 的支出总额，应使用指标存储系统。

在自有 VPS 上设置 Claude Code 支出跟踪

只需两个服务：一个用于接收指标的 collector，以及用于存储指标的 Prometheus。两者都不要暴露到公网，因为开放的 OTLP 端口会接受任何发现该端口的人的写入请求。写入 /opt/ccmetrics/compose.yaml：

services:
  collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel/config.yaml"]
    volumes:
      - ./collector.yaml:/etc/otel/config.yaml:ro
    ports:
      - "10.8.0.1:4318:4318"
    restart: unless-stopped
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prom-data:/prometheus
    ports:
      - "127.0.0.1:9090:9090"
    restart: unless-stopped

volumes:
  prom-data:

10.8.0.1 是服务器在 WireGuard 隧道内的地址，因此 collector 只能从您的计算机访问，其他来源均无法访问。端口前的地址在这里确实发挥作用，因为 Docker 发布的端口不会受到 ufw 过滤：请参阅Docker 发布的端口为何绕过 ufw。隧道本身的配置方法请参阅在自有 VPS 上配置 WireGuard VPN。

/opt/ccmetrics/collector.yaml：

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  prometheus:
    endpoint: 0.0.0.0:8889

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus]

/opt/ccmetrics/prometheus.yml。8889 端口不会发布到主机，因为 Prometheus 通过 Compose 网络中的服务名称访问 collector：

global:
  scrape_interval: 30s

scrape_configs:
  - job_name: claude-code
    static_configs:
      - targets: ["collector:8889"]

cd /opt/ccmetrics
docker compose up -d
docker compose logs collector

collector 日志的末尾应为 Everything is ready. Begin running and processing data.。如果日志因配置错误而停止，说明 YAML 解析失败，容器会不断重启。

现在将 Claude Code 指向该 collector。在每台运行 Claude Code 的计算机上，将以下内容添加到 ~/.claude/settings.json：

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "none",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://10.8.0.1:4318",
    "OTEL_METRIC_EXPORT_INTERVAL": "10000"
  }
}

启动一个会话，发送一条提示，等待导出间隔（此处为 10 秒，默认值为 60 秒），然后让 Prometheus 查询已获取的指标：

curl -s http://localhost:9090/api/v1/label/__name__/values | grep -o 'claude_code[a-z_]*'

您应看到几个以 claude_code_ 开头的名称。导出器会将点替换为下划线，并追加单位，因此具体字符串取决于您的 collector 版本。结果为空表示没有数据到达。请检查协议和端口是否匹配，因为 http/protobuf 使用 4318 端口，而 grpc 使用 4317 端口；两者不匹配时通常不会显示明显错误。运行 claude --debug-file /tmp/claude-debug.log，然后在该文件中查找 [3P telemetry] 行；Claude Code 会在这些行中报告 OTel 导出错误。

如果只有一台计算机且不需要服务器，可以跳过上述全部步骤。设置 OTEL_METRICS_EXPORTER=prometheus 后，Claude Code 自身会在 http://localhost:9464/metrics 暴露抓取端点。当 prometheus 是唯一列出的导出器时，Claude Code 会从导出指标中省略 USD、tokens 和 s 单位，以保持抓取结果符合 Prometheus 文本格式。指标名称不会改变；组合多个导出器的设置（例如 otlp,prometheus）会保留这些单位。

这种部署方式还涉及一项隐私决策。默认情况下，只有计数和元数据会离开计算机，不包括提示文本和工具输出。OTEL_LOG_USER_PROMPTS=1 会将提示文本添加到导出事件中，OTEL_LOG_TOOL_CONTENT=1 会将工具输出添加到跟踪 span 中。因此，只要导出其中任一信号，您的遥测服务器就会保存源代码以及上下文中的其他内容。请谨慎启用这些设置，并先阅读避免将机密信息放入 agent 上下文。

跟踪脚本运行和 CI 运行的开支

非交互式运行最容易造成意外开支，因为没有人监控屏幕。使用 claude -p 和 --output-format json 后，运行结果负载会报告本次运行的成本：

claude -p "summarise the failing tests" --output-format json | jq '.total_cost_usd'

该负载包含 total_cost_usd 以及按模型划分的明细，因此 CI 作业无需使用控制面板即可记录自身开支。与所有本地数据一样，这只是客户端估算值。如果运行使用 --continue 或 --resume 继续某个对话，报告的将是整个对话的总成本，其中包括之前的运行。您可以将该值追加到文件，或将其作为指标推送到上面的采集器。这是当前成本最低且实用的开支跟踪方式；每次运行只需调用一次 jq。

故障模式及现象

报告为空。 npx ccusage@latest daily 如果没有打印任何行，说明程序未读取 Claude Code 的写入位置。CLAUDE_CONFIG_DIR 用于更改该位置，此时必须告知解析器新的路径。如果存在数据行但仅显示到一个月前，这是 cleanupPeriodDays 的预期行为：默认情况下，会话记录会在 30 天后被移除。

两台机器报告的总量不一致。 这是预期情况，并非错误。/usage 分解和任何日志解析器都仅读取本地会话历史，因此来自其他设备或 claude.ai 的使用量在两者中均不存在。

本地统计总量与账单不符。 除非配置了合同费率，否则本地数据会根据 token 数量和标准目录费率计算：在托管设置中为 /usage 配置 modelPricing 表，或为 ccusage 配置 pricingOverrides。在订阅模式下，计划额度内的使用量不会按 token 收费，仅消耗使用额度。控制台的使用情况页面是 API 计费的权威来源。

工作量未变但成本上升。 首先检查缓存列。长会话在每一轮对话中都会重新发送全部历史记录；当缓存有效时按缓存费率计费，缓存失效后则按完整输入费率计费，因此一次长时间的停顿会导致整个对话被重新处理。这表现为输入 token 数量巨大而输出 token 数量较小，输入与输出 token 定价 解释了两者为何独立变动。

包含子代理的一天看起来数据异常。 每个子代理都运行各自的上下文窗口，因此 token 使用量会随着运行的子代理数量及其持续时间而增加。在订阅计划中，/usage 归因会以百分比形式给出该机器上子代理的份额。若需查看单次请求的详细信息，OTel 数据会通过 claude_code.token.usage 上的 query_source 属性将它们区分开来。仅使用日志解析器只能看到总数，无法获知具体细节。

FAQ

ccusage 是否会显示 Max 计划下实际计费的金额？

不会。订阅计划额度内的使用量不会按 token 计费，因此日志解析器会按标准 API 列表价格计算 token 费用，显示相同工作通过 API 完成时的成本。这适合相对衡量某一天的使用量，也便于比较不同项目或模型的使用情况。要查看实际应付金额，API 费用请查看 Console 的 usage 页面，订阅费用请查看计划计费页面。如果启用了使用量额度，超出额度的部分会按标准 API 价格计费，claude.ai 会在 Settings > Usage 下显示这部分费用。

Claude Code 将这些工具读取的会话文件存储在哪里？

存储在 ~/.claude/projects/<project>/<session-id>.jsonl 中，其中 <project> 是工作目录路径，非字母数字字符会替换为 -。每行都是一个 JSON 对象，表示一条消息、一次工具调用或一项元数据。CLAUDE_CONFIG_DIR 会移动整个目录，settings.json 中的 cleanupPeriodDays 控制 30 天的保留期限。Anthropic 将条目格式定义为内部格式，版本之间可能发生变化。因此，应使用持续维护的工具解析，而不是编写自己的脚本。

可以将 Claude Code 遥测数据发送到 Langfuse 吗？

使用默认遥测配置不可以。Langfuse OTLP 端点接受 trace，但 Claude Code 默认导出的是 metrics 和日志事件，而不是 span，因此没有对应的数据接收位置。你必须手动启用 span 导出，而该功能仍处于 beta 阶段。Langfuse 自带的 Claude Code 集成则使用 Stop hook，将会话记录转换为 trace。要统计费用总额，请将 Claude Code metrics 发送到 OpenTelemetry collector，并存储在 Prometheus 中。对于通过 API 自行构建的 agent，可以使用 Langfuse；此时由你自己的代码生成包含 prompt、模型和费用的 span。

为什么本地统计值与 Console usage 页面不一致？

因为计算方式不同。/usage 和日志解析器会汇总当前计算机上的会话文件中的 token 数量，然后按标准列表价格计算费用，除非配置了合同价格；托管设置中的 /usage 通过 modelPricing 配置价格，ccusage 则通过 pricingOverrides 配置价格。Console 会汇报组织实际支付的金额，覆盖所有计算机和所有密钥，并计入任何折扣。出现差异是正常的。差异非常大时，通常表示还有第二台设备、CI runner 或其他团队成员在使用同一账户计费。

如何在 CI 中跟踪 claude -p 运行的费用？

使用 --output-format json 运行，并从结果中读取 total_cost_usd，例如使用 claude -p "..." --output-format json | jq '.total_cost_usd'。同一载荷还包含按模型划分的明细和会话 ID。按作业记录该数值，即可获得每条流水线的费用，无需 agent、仪表板或其他服务。