Claude Code 的 token 用量详解

为什么您的一次编程会话会是这个价钱

每一份 Claude 账单，无论是 API 发票还是订阅额度，最终都归结为一块表：输入的 token 与输出的 token。定价页面看起来很简单：每百万输入 token 多少钱，每百万输出 token 多少钱。它没有告诉您的是，在一次智能体（agentic）编程会话中，输入这一侧的表转得远比直觉预想的要快，因为每一轮都会把整段对话重新发送一遍。我做计量型基础设施的销售已经十五年了，而 token 是我见过的第一块表，多数客户是真的说不清楚是什么在让它转。这就是这堂读表课要讲的：token 是什么，在智能体会话里什么算输入、什么算输出，为什么提示词缓存会改写这套算术，以及哪些调节手段真的能改变这个数字。

token 是什么，以及为什么代码比散文更贵

token 是模型读取和写出的单位，是一段文本片段，通常是一个词的一部分。Anthropic 自己的术语表把一个 Claude token 定为大约 3.5 个英文字符，这样算下来，一旦把空格和标点也计入，每个单词就远不止一个 token，一千个单词的散文轻松超过 1,300 个 token。代码按行算更重：花括号、运算符、下划线和缩进，每个字符切分出的 token 比英文更多，一个几百行的源文件通常就有好几千个 token。一个智能体决定要读取的 2,000 行文件，在任何人写下一行新代码之前，就已经是一笔五位数的 token 采购了。

关于分词器（tokenizer），有两点常常把人绊倒。第一，它是与模型绑定的：截至 2026 年 7 月，Opus 4.7 及更新版本、Sonnet 5 和 Fable 5 使用了一款更新的分词器，对同一段文本产生的 token 数比早期 Claude 模型大约多 30%（具体增幅随内容而异），这会让您以 token 为单位做的任何预算都随之变动，尽管单位 token 的价格并没有跟着上涨。第二，tiktoken，也就是每篇博客文章都会顺手拿来用的那个库，是 OpenAI 的分词器，对 Claude 的计数在普通文本上会低估大约 15–20%，在代码上更多。唯一可信的计数来自 count_tokens 端点，下文会讲到。

一切都是输入：这块表实际在数什么

人们以为自己付的是 Claude 写出来的代码钱。在一次智能体会话里，那只是一个小小的条目。输入 token（费率更便宜，但用量高得多）包括：

• 系统提示词。 Claude Code 自己的框架指令，加上您的 CLAUDE.md 和记忆文件，在会话开始时加载，此后每一次请求都会带上。
• 工具定义。 智能体可能调用的每一个工具的 schema。您接入的每一个 MCP 服务器 都会叠加到这份固定开销上，不过 Claude Code 现在默认会延迟加载完整的 MCP 工具定义，因此在某个工具首次被使用之前，上下文里只放工具名称，这缓和了成本但并没有消除它。
• 智能体读取的每一个文件。 对源文件的一次 Read 会把整个文件放进上下文，而且会一直留在那里。
• 每一个工具结果。 测试运行、grep 输出、终端刷屏、构建日志，全都作为输入 token 返回。一个打印了 8,000 行的失败测试套件，刚刚就为一本小书向您收了费。
• 到目前为止的整段对话，每一轮都重新发送。 这一点值得单独用一节来讲。

没人算进去的那次重发

Claude API 是无状态的。它不会在请求之间记住您的会话，任何东西都不会记。所以到第 2 轮，客户端会发送第 1 轮加上它的回复加上您的新消息。到第 50 轮，它会重新发送第 1 到 49 轮，每一次文件读取、每一个工具结果、每一个 diff，再加上第 50 轮。模型每一次都重新读一遍整段记录，而这些被重读的每一个 token 都按输入计费。

后果是：每轮的成本大致随会话长度线性增长，而整场会话的总成本大致按平方增长。一条在第 3 轮花了半美分的消息，到第 60 轮同样是一句一行的问题，却可能花上二十倍，因为它扛着六十轮的货。这一个事实就能解释大多数“为什么我的账单这么高”的工单，而且这并不是 Claude 的怪癖：每一个用起来像有状态的 LLM 产品，底层都是一个无状态 API 加一个重发循环。

输出：您看得见的，加上您看不见的思考

输出 token 是贵的那一类，在当前整条产品线上都是输入费率的五倍（截至 2026 年 7 月，Opus 4.8 为 $5/$25，Sonnet 5 标价 $3/$15，Haiku 4.5 为 $1/$5）。输出包括 Claude 生成的文本和代码，以及 思考 token：模型在回答之前所做的内部推理。这里有两点很重要。思考按输出费率计费，并计入 max_tokens，一个以 stop_reason: "max_tokens" 结束、答案被截断的 API 响应，往往意味着思考在答案之前就把预算耗光了。而在当前模型上，推理摘要可能根本不会显示出来，Opus 4.8、Sonnet 5 和 Fable 5 默认就不显示它，但思考仍然发生了，也仍然在计费。看不见不等于免费。

Claude Code 默认启用扩展思考，因为它能切实改善多步骤工作，而默认预算每次请求可以高达几万个 token。在较简单的任务上，您可以把它调低：用 /effort 或在 /model 里降低努力级别，或者在 /config 里调整思考设置。这是一个货真价实的成本调节手段，不是迷信。

提示词缓存改写了这套算术

提示词缓存是那个重发循环没有把所有人拖垮的原因。API 可以缓存您提示词中一段稳定的前缀，包括系统提示词、工具定义、对话历史，并在下一次请求时以极小的代价把它取回来。截至 2026 年 7 月，倍率是这样的：一次缓存 写入 的成本是基础输入费率的 1.25 倍（1 小时版本为 2 倍），而一次缓存 读取 是 0.1 倍。写入是溢价，读取是九折之外再打一折的九成折扣。单单一次读取，就已经把 5 分钟版本写入的溢价挣了回来还有余。

Claude Code 会替您管理缓存，在一场健康的会话里，那笔庞大的重发几乎全部由缓存供应。但默认缓存自上次使用起只存活 五分钟。去倒杯咖啡、这一走走久了、回来发一条消息，缓存就过期了，整段累积起来的前缀会以 1.25 倍被重新写入，而不是以 0.1 倍被读取。在一场 15 万 token 的会话上，那一次冷启动的轮次，比十几次热轮加起来还贵。这就是那个值得内化的、与直觉相反的结论：先闲置再恢复的节奏，可能比持续工作还贵，因为每一段超过 TTL 的闲置间隙，都会把您的下一轮从便宜的读取变成昂贵的重写。要成段地工作，别把一场庞大的会话拆成每十分钟一条消息去滴灌。

如果您是从 自己部署在 VPS 上的应用 调用 API，这些好处一样都不会白送给您，而经典的自伤是把一个时间戳或请求 ID 插进系统提示词里，这会让每次请求的前缀字节都发生变化，从而悄无声息地让缓存失效。判断的迹象就是 usage.cache_read_input_tokens 在一连串看起来完全相同的调用里始终为零。

公式，配一个算过的例子

对任何报出一句“一场会话花 $X”的固定价，都别理会。会话之间差着两个数量级。真正成立的是这个公式：

turn cost = (uncached input      x base input price)
          + (cache writes        x 1.25 x base input price)
          + (cache reads         x 0.10 x base input price)
          + (output incl. thinking x output price)

session cost = sum over all turns

以 Claude Opus 4.8 为例来算，截至 2026 年 7 月它是每百万输入 token $5、每百万输出 $25。一次携带 80,000 个累积上下文 token 的会话中段轮次：其中 75,000 个从缓存读取，3,000 个是新写入，2,000 个是未缓存的新鲜输入，1,500 个输出 token（含思考）。

• 缓存读取：75,000 × $0.50/M = $0.0375
• 缓存写入：3,000 × $6.25/M = $0.019
• 未缓存输入：2,000 × $5/M = $0.010
• 输出：1,500 × $25/M = $0.0375

这一轮大约 $0.10；像这样五十轮，大约 $5。现在看缓存过期之后的同一轮：完整的 80,000 个 token 以 $6.25/M 全部重写就是 $0.50，还没算输出，大约是整个热轮的五倍，做的却是完全相同的活。那道差距，就是整个缓存故事浓缩成的一个数字。

用来校准而非预测：Anthropic 公布的企业级 Claude Code 部署数据，截至 2026 年 7 月，平均每位开发者每个活跃日约 $13，也就是每月 $150–250，其中 90% 的用户每天保持在 $30 以下。您的实际情况取决于模型选择、会话卫生和代码库规模，而这正是下文那些调节手段之所以重要的原因。

查看您自己的用量

在 Claude Code 里，命令是 /usage（/cost 仍然可用，它是一个别名）。顶部的 Session 区块显示当前会话的 token 统计和一个本地计算的成本估算；在订阅套餐上，同一屏还会显示您的套餐额度条，以及把近期用量归因到技能（skill）、子智能体（subagent）、插件和各个 MCP 服务器的明细。对于 API 账户的权威账单，Claude 控制台里的用量页面才是准绳，CLI 上的数字只是估算。/context 会画出一张彩色网格，展示是什么占据了上下文窗口，包括系统提示词、工具、MCP 定义、文件、历史，是发现臃肿的 CLAUDE.md 或话痨式 MCP 服务器最快的办法；传入 all 可展开完整的逐项明细。

从 API 侧，每一个响应都会精确告诉您发生了什么：

response = client.messages.create(model="claude-sonnet-5", max_tokens=2048,
                                  messages=messages)
u = response.usage
total_prompt = u.input_tokens + u.cache_creation_input_tokens + u.cache_read_input_tokens
print(f"uncached={u.input_tokens} written={u.cache_creation_input_tokens} "
      f"read={u.cache_read_input_tokens} output={u.output_tokens}")

请注意，input_tokens 只是未缓存的余量，真实的提示词大小是全部三个输入字段之和。一个跑了一小时、显示 input_tokens: 4000 的智能体并不便宜，另外那 200,000 个 token 是从缓存供应的。要在发送之前先估算，就用计数端点，它调用免费、有自己独立的速率限制，并会用您所指定模型的分词器来计数（把结果当作一个接近的估算，账单以真实请求为准）：

count = client.messages.count_tokens(model="claude-sonnet-5",
                                     messages=[{"role": "user", "content": big_file}])
print(count.input_tokens)

绝不要用 tiktoken，原因见上文。

订阅套餐与按量付费的对比

本指南里的机制在任何地方都完全相同，不同的只是结算方式。用 API 密钥时，Anthropic 按量付费、按 token、按公布费率计费，上面每一个数字都是真金白银。在 Claude 订阅（Pro、Max、Team、Enterprise）上，Claude Code 的用量改为从您套餐的包含额度里扣：截至 2026 年 7 月，那是一个滚动的五小时会话窗口，外加一个每周窗口，跨模型共享，并且与 claude.ai 聊天共用，而 /usage 里的美元数字是参考信息而非账单。用尽一个窗口，您会看到 “You've hit your session limit” 或 “You've hit your weekly limit” 并附带重置时间，而用 /model 切换模型并不会恢复访问，因为这些窗口是跨模型共享的。套餐可以选择性地启用使用额度（usage credits），用 /usage-credits 管理，以便在上限之外购买用量。我特意不去印出套餐配额：它们是整个话题里最易变的数字，所以请去 claude.com/pricing 和您自己的 /usage 额度条上查看。在订阅上，token 机制依然重要，一场浪费的会话烧掉您窗口的方式，和它烧掉美元的方式一模一样。关于订阅这一侧，参见 哪一款 Claude 套餐适合您。

真正有效的调节手段

• 限定智能体读取的范围。 “修复 auth.py 里的校验 bug”只读一个文件；“改进这个代码库”会读四十个。让 CLAUDE.md 保持精简，它会被加载进每一场会话，所以只留必要内容，把特定工作流的指令挪进按需加载的技能里。
• 清理与压缩。 在不相关的任务之间用 /clear，陈旧的上下文会在此后每一条消息里被重发、被重新计费。在一个长任务内部，/compact Focus on the failing tests and the diff 会把历史概括压缩下来，让您远离那条平方增长的曲线。
• 给模型选对尺寸。 截至 2026 年 7 月，Sonnet 以入门定价每百万 token $2/$10（标价 $3/$15，相对 Opus 的 $5/$25）就能应付大多数编程；而 $1/$5 的 Haiku 是日志分拣这类机械性子智能体工作的合适工具。/model 可以在会话中途切换。
• 预先过滤啰嗦的输出。 一个在 Claude 看到之前就把测试运行 grep 成只剩失败项的钩子，能把 20,000 个 token 的工具结果变成 300 个，而且在那一轮以后每一次重发里都这么做。
• 把非交互的活批量处理。 对于您自己的 API 流水线（分类、批量审阅、夜间任务），Batches API 以异步交付为代价，用相同的模型打五折运行。
• 尊重缓存的时钟。 成段地连续工作。一个挂在 VPS 上 tmux 里的 Claude Code 会话 在闲置时不花一分钱，token 只在某一轮运行时才花掉，但闲置时间丢掉的正是那份热缓存，而下一轮要为重写买单。

FAQ

Claude Code 里一场编程会话用多少 token？

没有固定数字：一旦文件和历史累积起来，一次会话中段的轮次通常就携带几万个提示词 token，而一场工作会话会用到数百万个，其中大部分以基础费率的十分之一从缓存供应。用来校准的话，Anthropic 公布的企业数据截至 2026 年 7 月平均每位开发者每个活跃日约 $13，90% 的用户在 $30 以下。请在您自己的会话里跑 /usage；盯着它看五分钟，胜过任何公布的平均值。

就算我看不见，思考 token 也要花钱吗？

要。思考 token 按输出 token 计费，也就是那个贵的费率，并计入 max_tokens，而当前模型即便界面在显示时省略了推理摘要，也照样对它们计费。如果一个响应在可见答案写完之前就以 stop_reason: "max_tokens" 截断，那很可能是思考耗光了预算。在 Claude Code 里，对不需要深度推理的任务，用 /effort 把努力级别调低。

为什么一场很长的 Claude Code 会话，每条消息会越来越贵？

因为 API 是无状态的：每一轮都会把整段对话（每一次文件读取、工具结果和之前的往来）作为计费输入重新发送，所以第 50 轮把第 1 到 49 轮当作货物扛着。提示词缓存以大约基础输入价的十分之一供应重复的前缀，但这个前缀本身在不断增长，而任何超过缓存 TTL 的闲置间隙，都会把下一轮变成全价重写。/compact 会缩小历史；/clear 会重置它。

我要怎么查看自己的 Claude token 用量和成本？

在 Claude Code 里，/usage 显示会话 token 统计、一个本地成本估算，以及订阅上的套餐额度条（/cost 是别名）；/context 显示是什么在填满窗口。对于权威的 API 账单，用 Claude 控制台里的用量页面。在您自己的代码里，读取 response.usage，把 input_tokens、cache_creation_input_tokens 和 cache_read_input_tokens 相加就得到真实的提示词大小，并用 count_tokens 端点提前估算，绝不要用 tiktoken。