Claude Code 深度学习手册

主题

成本与用量（costs） ​

Claude Code 按 API token 消耗计费，本模块讲如何追踪成本、为团队设支出上限、并通过上下文管理与模型选择降低 token 用量。

你的真实用量 ​

从 ~/.claude/stats-cache.json（截至 2026-05-26）：

  • 主力 Opus 4.7，少量 Haiku 4.5 / Sonnet 4.6。
  • 每日 token（output 量级）：05-21 ~2.8M → 05-25 ~7.9M → 05-26 ~9.2M，写文档/审计这几天明显冲高。
  • 累计 70 个会话、约 1.93 万条消息；缓存帮你把输入侧 ~97% 挡在 0.1× 价（见「提示词缓存」节实测）。

省钱该怎么做（对你） ​

  • 简单活别上 Opus：/model sonnet 或给 subagent 配 model: haiku（你重度用 subagent，这里省得最多）。
  • 长会话及时 /compact、切任务 /clear；/context 看占用。
  • 并行很烧钱：你常并行前后端 + 后台代理，N 个会话 ≈ N 倍，/usage//cost 随时看。
  • 你装了一堆 MCP/插件——工具默认 deferred 不占上下文，不用为省钱关它们。

权威账单看 platform.claude.com/usage；costUSD=0 说明你走订阅额度而非按量计费。

官方文档要点 ​

以下为按官方文档整理的系统性参考。

是什么 ​

Claude Code 按 API token 消耗（API token consumption）计费。订阅套餐（Pro、Max、Team、Enterprise）的定价见 claude.com/pricing。每开发者成本差异很大，取决于模型选择、代码库大小、以及是否同时跑多实例/自动化等用量模式。官方给出企业部署的平均成本约为每开发者每活跃日（active day）13 美元、每开发者每月 150-250 美元，且 90% 的用户每活跃日成本低于 30 美元。本页覆盖三块：追踪成本（track your costs）、为团队管理成本（managing costs for teams）、降低 token 用量（reduce token usage）。

怎么工作 ​

  • 计费基础：按 API token 消耗收费。token 成本随上下文（context）大小线性增长——Claude 处理的上下文越多，消耗 token 越多。
  • 自动降本机制 1——prompt caching（提示缓存）：对系统提示等重复内容降低成本，自动生效。
  • 自动降本机制 2——auto-compaction（自动压缩）：在接近上下文上限时自动把对话历史摘要化。
  • /usage 命令的 Session 区块：展示当前会话详细 token 用量统计。其美元数字是从 token 计数本地估算（locally）得出，可能与实际账单不同；权威账单见 Claude Console 的 Usage 页（platform.claude.com/usage）。
  • /usage 在 Pro/Max/Team/Enterprise 套餐下还展示计入套餐额度的明细：把近期用量归因到 skills、subagents、plugins、各个 MCP server，每项显示为占总量的百分比。按 d 或 w 在 last 24 hours 与 last 7 days 间切换。数据为近似值，从本机本地会话历史计算，不含其他设备或 claude.ai 的用量。
  • 团队支出控制：用 Claude API 时可在 workspace 上设置 spend limit；管理员可在 Console 查看 cost and usage reporting。Pro/Max 套餐可用 /usage-credits 命令对 usage credits 设月度支出上限。
  • 自动创建的 workspace：首次用 Claude Console 账号认证 Claude Code 时，会自动创建名为 "Claude Code" 的 workspace，用于集中追踪管理；该 workspace 不能创建 API key，仅供 Claude Code 认证与用量。其流量计入组织整体 API rate limits。
  • Bedrock/Vertex/Foundry：Claude Code 不会从你的云发送 metrics，要拿成本指标多家大型企业用 LiteLLM（开源、可按 key 追踪 spend，非 Anthropic 出品也未做安全审计）。
  • background token 用量：即使空闲也会消耗少量 token——会话摘要后台任务（为 claude --resume 服务）、以及 /usage 等命令的状态检查请求。

怎么配置 / 用法 ​

追踪用量：在会话内输入 /usage（Session 区块显示 token 统计与本地估算美元；d/w 切换 24h/7d）。Pro/Max 设月度信用额上限：/usage-credits（改额度需账户的 billing access）。API 团队支出上限：在 Claude Console 的 workspace 设 workspace spend limit；对 "Claude Code" workspace 在 Limits 页设 workspace rate limit。降本相关命令/配置：/clear（切换无关任务前清空上下文）、/rename + /resume（清空前重命名以便找回）、/compact Focus on code samples and API usage（自定义压缩保留内容）、/model（中途切模型）、/config（设默认模型/禁用 thinking）、/effort（降 effort level）、/context（看上下文占用）、/mcp（看并禁用未用 server）、/rewind 或双击 Escape（回退检查点）、Shift+Tab（进 plan mode）。在 CLAUDE.md 中自定义压缩指令示例：# Compact instructions 段落写 "When you are using compact, please focus on test output and code changes"。降低 thinking 预算环境变量：MAX_THINKING_TOKENS=8000。开启 agent teams（默认关）：在 settings.json 或环境变量设 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。subagent 指定省钱模型：在 subagent 配置中写 model: haiku。状态栏常驻显示上下文用量见 statusline 配置。PreToolUse hook 过滤测试输出示例（settings.json）：{"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":[{"type":"command","command":"~/.claude/hooks/filter-test-output.sh"}]}]} }。

什么时候用 ​

  • 想知道当前会话花了多少 token / 估算成本时：用 /usage（API 用户看 Session 美元数；订阅用户看套餐额度条与归因明细）。
  • 权威对账时：别信 /usage 的本地估算，去 Claude Console 的 Usage 页（platform.claude.com/usage）看实际账单。
  • 团队铺开前：先用小范围 pilot group + 这些追踪工具建立基线，再大规模推广。
  • 用 API 跑团队、想封顶花费时：设 workspace spend limit；想保护其他生产负载不被 Claude Code 占满速率时：对 "Claude Code" workspace 设 workspace rate limit。
  • 在 Bedrock/Vertex/Foundry 上想要成本指标时：考虑 LiteLLM（但注意未经 Anthropic 安全审计）。
  • 做简单任务时：用 Sonnet 而非 Opus；subagent 用 haiku；降 effort level 或关 thinking——别在简单任务上开 Opus + 高 thinking 预算。
  • 切换到无关新任务时：用 /clear；复杂任务先用 plan mode（Shift+Tab）避免走错方向返工。

限制 / 坑 ​

  • /usage 的美元数字是本地估算（locally computed from token counts），可能与实际账单不同；不是权威账单来源。
  • /usage 套餐归因明细为近似值，仅基于本机本地会话历史，不含其他设备或 claude.ai 的用量。
  • 订阅用户（Claude Max/Pro）：Session 区块的成本数字与账单无关（usage 已含在订阅里），不应据此对账。
  • Pro/Max 用 /usage-credits 改支出上限需要账户的 billing access；到达上限且仍有 usage credits 时会被提示在 CLI 内提高或移除上限。
  • "Claude Code" workspace 不能创建 API key，仅供认证与用量；其流量计入组织整体 API rate limits。
  • Bedrock/Vertex/Foundry 上 Claude Code 不发送 metrics，拿不到原生成本指标。LiteLLM 与 Anthropic 无关联、未做安全审计。
  • rate limit 是组织级（organization level）而非按个人，单个用户在他人不用时可临时超出其计算份额。
  • background 进程即使空闲也消耗 token，通常每会话低于 0.04 美元。
  • agent teams 默认关闭；在 plan mode 下 teammates 大约比标准会话多用约 7x token，每个 teammate 维护独立上下文窗口且作为独立 Claude 实例运行；空闲 teammate 仍持续消耗 token。
  • extended thinking 默认开启，thinking token 按 output token 计费，默认预算视模型可达数万 token/请求。
  • Claude Code 会定期更新，可能改变功能（含成本报告）行为；可用 claude --version 查当前版本。

硬事实速查（28 条） ​

  • 计费方式：按 API token consumption 计费；订阅定价见 claude.com/pricing。
  • 企业部署平均成本：约每开发者每活跃日（active day）$13；每开发者每月 $150-250。
  • 90% 用户每活跃日成本低于 $30。
  • 命令 /usage：显示当前会话 token 统计 + 本地估算美元；Session 区块面向 API 用户。
  • /usage 示例输出字段：Total cost: $0.55 / Total duration (API): 6m 19.7s / Total duration (wall): 6h 33m 10.2s / Total code changes: 0 lines added, 0 lines removed。
  • /usage 按 d 或 w 切换 last 24 hours / last 7 days；归因到 skills、subagents、plugins、MCP servers，各显示为占总量百分比。
  • 权威账单页：Claude Console Usage 页 platform.claude.com/usage。
  • 命令 /usage-credits：Pro/Max 设月度 usage credits 支出上限；改上限需 billing access。
  • API workspace 可设 workspace spend limit（platform.claude.com workspaces 文档）。
  • 首次认证自动创建名为 "Claude Code" 的 workspace；不能创建 API key；流量计入组织 API rate limits；可在其 Limits 页设 workspace rate limit。
  • Bedrock/Vertex/Foundry 不发送 metrics；可用 LiteLLM 按 key 追踪 spend（开源，非 Anthropic，未审计）。
  • Rate limit 建议表（TPM/RPM per user）：1-5 人 200k-300k TPM / 5-7 RPM；5-20 人 100k-150k / 2.5-3.5；20-50 人 50k-75k / 1.25-1.75；50-100 人 25k-35k / 0.62-0.87；100-500 人 15k-20k / 0.37-0.47；500+ 人 10k-15k / 0.25-0.35。
  • 示例：200 用户 × 20k TPM = 4 million 总 TPM。
  • rate limits 在组织级生效，非按个人。
  • agent teams 默认关闭；启用环境变量/设置：CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1（写 settings.json 或环境）。
  • agent teams 在 plan mode 下约用 7x token；建议 teammates 用 Sonnet。
  • 自动降本：prompt caching + auto-compaction。
  • 降本命令：/clear、/rename、/resume、/compact（如 /compact Focus on code samples and API usage）、/model、/config、/effort、/context、/mcp、/rewind、Shift+Tab（plan mode）、Escape（中止）。
  • subagent 省钱模型配置：model: haiku。
  • 降 thinking 预算：MAX_THINKING_TOKENS=8000；thinking token 按 output token 计费，默认预算可达数万 token/请求。
  • extended thinking 默认开启。
  • CLAUDE.md 建议保持在 200 lines 以内，仅放 essentials；专门指令移到 skills（on-demand 加载）。
  • CLAUDE.md 在会话开始时加载进上下文。
  • MCP tool 定义默认 deferred，只有工具名进上下文，直到 Claude 用到具体工具。
  • 更 context 高效的工具：gh、aws、gcloud、sentry-cli（CLI 工具不增加 per-tool listing）。
  • PreToolUse hook 示例：matcher 为 Bash，command 指向 ~/.claude/hooks/filter-test-output.sh，输出 hookSpecificOutput.permissionDecision=allow 并 updatedInput.command 改写命令。
  • background token 用量：会话摘要后台任务（服务 claude --resume）、/usage 等命令状态检查；通常每会话低于 $0.04。
  • 查版本：claude --version；billing 问题通过 Console 账号联系 Anthropic 支持。

官方出处：https://code.claude.com/docs/en/costs