Claude Code 对我来说不是“又一个能写代码的助手”而是真正会把项目规则、工具说明、历史对话全部按 token 计费的命令行工具。刚开始用的一周我最关注的不是功能列表而是账单同一个项目背景、同一份 CLAUDE.md、同一套工具定义每次启动和每次任务都要重新按普通输入价格计算一遍这就是典型的白烧 token。官方给出的解决办法是提示缓存prompt caching把请求里稳定的前缀缓存起来命中后输入费用约为全价的十分之一。标题里说“省 90%”指的是这个前缀部分能省出来的比例不是所有账单都直接打一折。这篇文章按官方缓存机制的理解拆成 6 个能直接落地的操作点同时把最近大家经常搜到的登录 token 报错、第三方模型接入、免费额度抵扣问题一起理清楚。适合两类人看一是已经跑通 Claude Code、正在关心 token 消耗的开发者二是准备把 Claude Code 接入团队工作流、想知道哪些配置能少烧钱的技术负责人。1. 提示缓存省的是哪部分钱先算清楚1.1 token 是怎么被计费的模型处理文本时并不是按字数或字符数收钱而是按 token 计费。一段代码、一篇日志、一份项目说明都会被切成很多个 token中文通常一个字或者几个字算一个 token英文差不多一个词算一两个 token。Claude Code 这类工具在发起请求时也不是只把你最新一句话发给模型。它内部会拼出一大段上下文大致包含这几部分系统提示包含工具说明、安全规则、技能定义项目记忆文件里的内容也就是 CLAUDE.md当前会话的历史消息你本次输入的问题或操作指令。普通情况下这些内容全部按“输入 token”的价格计费。问题就出在这里如果同一个项目背景、同一份规范文件、同一套工具说明每次请求都重新计算一次那这部分固定内容就会被反复收取输入费用。项目背景越厚、CLAUDE.md 越长这种重复计费越明显。这就是“白烧 token”最常见的来源不是模型变笨了也不是工具出了问题而是你每次都在为完全相同的前缀重复付全价。1.2 缓存命中为什么能把输入成本压到十分之一提示缓存的机制简单说就是给请求里“不变的前缀”做一个复用标记。第一次请求时模型把完整的输入处理一遍并把前缀缓存下来。第二次、第三次请求时只要前缀没有变化模型直接读取缓存结果不再重新计算前面的固定内容。因为计算量大幅下降缓存命中的输入 token 单价也大幅下降常见口径是接近普通输入价格的十分之一。所以“省 90%”这个说法是成立的但有前提省的是输入 token 的费用不是输出 token 的费用只有缓存命中的那部分输入 token 享受折扣缓存是否生效取决于请求前缀是否完全一致以及是否在有效时间窗口内被再次使用。如果一次任务大量输出代码输出 token 仍然按输出单价计算那么总费用并不会降到原来的十分之一。这一点要先说清楚否则很容易产生错误预期。1.3 Claude Code 默认就在做缓存但不代表你会用Claude Code 官方客户端本身已经对系统提示、工具定义、CLAUDE.md 这类固定上下文做了自动缓存处理。也就是说你不需要手动加参数也不需要自己插入缓存标记工具默认会尝试把稳定前缀缓存起来。但“默认在做缓存”不等于“你会用缓存”。实际使用中频繁新建会话、频繁修改系统提示、把动态内容插进固定前缀中间都会让缓存失效。缓存一失效账单就会静悄悄涨回去。很多人看到账单涨了第一反应是怀疑接口出问题、模型换了、账号被扣费了其实大概率只是缓存没命中。后面这 6 招核心都是围绕一件事让前缀保持稳定让缓存能被复用。注意这里说的前缀是请求文本最前面那一大段稳定的 token 序列不是网络层面的“前端”。先把这个概念对齐后面排查才不会跑偏。2. 官方设计的思路落到使用上是 6 招官方关于提示缓存的设计原则其实很直接能不重新计算的就不重新计算。把这条原则落到 Claude Code 使用层面可以拆成 6 招。2.1 第一招把稳定内容全部收进 CLAUDE.mdClaude Code 会把项目里的 CLAUDE.md 作为系统上下文注入。这就是最理想的缓存前缀来源。项目规范、目录结构、常用命令、代码风格、接口文档地址、不要碰的目录这些长期不变的信息应当写进 CLAUDE.md而不是每次打开会话再人工粘贴一次。原因是系统提示里的内容一旦进入缓存后续同一会话内的多次请求都能复用。如果你把背景信息放在对话消息里反复复制等于每次都是新的输入不但增加了输入 token也让原本稳定的前缀被动态内容打断。落地建议一个项目只维护一份 CLAUDE.md放在项目根目录如果多个项目共用一套规范可以把公共部分放到全局配置目录项目级 CLAUDE.md 只放差异内容不要把版本号、当天日期、临时任务说明写进这个文件。我在实际项目里会把“项目根目录结构”“构建命令”“测试命令”“数据库访问约束”写进 CLAUDE.md。这样每次启动这些内容都会进入缓存前缀同一个会话里连续处理多个文件时省的是重复的输入计费。2.2 第二招动态内容不要插到缓存前缀中间缓存命中的单位是“连续前缀”。这句话需要反复理解。请求文本最前面的 token 序列必须先完全一致才能使用缓存。如果你在第 150 个 token 的位置插入了一段当天的日志、随机变量、临时输出那么从第 150 个 token 开始后面所有内容都要重新计算哪怕后面还有 10 万个 token 和上一轮完全一样。这是提示缓存最反直觉的地方你只是改了一小段却导致整个前缀失效。实际操作中动态信息应该尽量放到上下文的靠后位置。比如需要让 Claude Code 分析的文件内容用工具读取让文件内容出现在工具结果里而不是手动粘贴到 CLAUDE.md 后面本次任务的临时说明、时间戳、单次指令放在用户输入里如果确实需要给模型提供变量优先用独立配置文件或环境变量不要在固定规则中间改内容。一个典型坏例子是在 CLAUDE.md 里写“今天是 2025 年某月某日当前分支是 feature-xxx”然后频繁更新这个日期和分支名。每次更新都让前缀从改动点开始失效原本能复用的规则全部重算。2.3 第三招用续会话代替频繁重启Claude Code 支持多会话、多分支也会自动缓存系统提示。但你每次启动一个新的进程或者执行清理命令后不继续原会话系统提示和项目上下文都要重新组装一遍。如果离上次使用超过一定时间缓存也可能过期具体时间窗口要以官方文档为准。所以同一个任务链路里尽量用命令行里的 continue / resume 参数或者交互界面里的“继续最近会话”功能别每次重新开启任务被打断直接在当前会话继续提问不用再把代码背景重新贴一遍需要开多个并行项目时每个项目保持一个长会话而不是在几分钟里开十个新会话。但这里要补一个平衡长会话会积累大量历史消息普通输入 token 也会不断增加。续会话适合“上下文需要连续”的场景。如果一个任务已经彻底结束还挂着一个超长会话继续用代价可能是历史消息拖慢响应、增加输入消耗。这个边界要到验证阶段用日志判断不是永远越长越好。2.4 第四招CLAUDE.md 和系统提示不要频繁改缓存命中的前提是前缀完全相同。CLAUDE.md 只要改动一个字符从改动位置开始缓存全部失效。团队里如果每天都有人顺手往 CLAUDE.md 里加一句临时记录这个文件就基本失去了缓存价值。正确做法CLAUDE.md 的变更走版本管理不要在工具里实时编辑需要临时约束当前这次任务用对话说明或者命令行参数而不是改系统提示文件如果确实要改尽量集中一次改完改完后这一段时间内不要反复微调。这一招看起来最基础但大多数“缓存没生效”的问题都出在这里。尤其团队协作时配置文件的修改往往很随意改的人只想着加一句话没意识到这句话会让后面所有人的缓存前缀一起失效。2.5 第五招打开 verbose 日志盯 cache_read 和 cache_creation不知道缓存是否生效所有省 token 策略都是瞎调。Claude Code 有详细模式会输出每次请求的 token 使用情况。重点看这几个字段cache_creation_input_tokens本次写入缓存的 token 数量cache_read_input_tokens直接命中缓存的 token 数量input_tokens没有命中缓存的普通输入 token 数量。如果cache_read_input_tokens长期是 0说明缓存没有命中。先查 CLAUDE.md 有没有被频繁修改再看会话是不是每次新建再看动态内容是不是塞进了前缀。如果写入了很多缓存但读取很少说明前缀不稳定或者离上次使用时间太长缓存已经过期。这个比例很重要但很多人只看总 token不看这个结构结果就是费用高却不知道高在哪。打开方式不复杂交互模式里使用/verbose命令行启动时带--verbose参数以你当前客户端的帮助信息为准。跑几条简单任务就能在日志里看到 usage 结构。2.6 第六招并行任务和子代理场景要共享同一组稳定上下文Claude Code 支持工具调用、子代理、MCP 这类扩展。复杂任务里主会话和子代理会构造各自的请求但它们通常共享同一套系统上下文。如果你在主会话里把任务规范写得很清楚子代理就能复用同一份缓存前缀如果每个子任务都自己附带一套零散背景相当于每个请求都要重新处理。并行执行多个互不相关的任务时如果各自是独立的新会话缓存也是各自建立的。想真正省 token要关注这几点把公用的项目规范和工具配置收敛到稳定的 CLAUDE.md 和统一配置里避免在子代理提示词里重复粘贴大段规则子代理需要的信息尽量从工具读取如果团队多人都在跑同一个项目优先统一配置而不是靠每个人每次对话补全背景。这 6 招不是一次性全上。更合理的顺序是先看前缀稳不稳再看日志命中率最后调会话和并行策略。一步到位容易把别的问题也改出来。3. 验证缓存是否生效从最小任务开始3.1 最小验证流程不要一上来就开并行、跑批量。先跑一条最简单的任务确认环境、登录、模型、输出目录都正常再考虑优化缓存。我建议的验证流程进入项目目录确认 CLAUDE.md 内容稳定启动 Claude Code执行一个简单任务比如“列出项目目录结构”打开 verbose 日志记录第一次请求的 cache_creation 数值不退出会话再执行一条同类任务看第二次请求的 cache_read 数值应该明显大于 0。如果第二次任务 cache_read 还是 0说明系统前缀没有复用。先查 CLAUDE.md 是否被动过再看会话上下文结构最后看日志里是否有动态内容插入。3.2 成功结果长什么样缓存生效时日志里能看到这样的结构第一次请求有大量cache_creation_input_tokens后续请求里cache_read_input_tokens占输入 token 的大部分普通输入input_tokens只包含真正新说的话。这种结构下输入费用会明显下降因为你没有为重复前缀付全价。如果只看到cache_creation_input_tokens每次都很高cache_read_input_tokens很低说明你的请求前缀不太稳定每次都在重新写缓存但没有复用到。这种情况需要回头检查 CLAUDE.md 和会话使用方式。3.3 验证时的边界判断不是每次请求都能命中缓存。需要满足几个条件前缀完全一致会话仍在缓存有效期内模型版本一致没有动态内容插入前缀。Claude Code 客户端升级后系统提示结构可能变化缓存会重建。多模型切换后不同模型的缓存空间也不一样。所以验证完一轮之后如果升级了客户端建议重新验证一次。还有一点容易被忽略如果缓存命中率正常但总费用还是高那就不是缓存策略的问题而是任务本身输出量大或者单个会话积累了过多历史。这时候应该优化的是任务拆分和会话清理而不是继续压缓存。4. 登录报错里的 token不是计费 token4.1 token exchange failed 卡在哪搜“Claude Code token”相关问题时经常看到sign-in could not be completed token exchange failed这类报错。很多使用者一看到 token 就以为是提示缓存、计费费用出问题其实完全不是一回事。这里的 token 是登录授权流程里的访问令牌发生在 Claude Code 启动登录阶段模型计算还没有开始。常见原因有登录时网络请求不稳定授信端点没有正常返回系统时间与服务器时间偏差过大导致令牌校验失败账号或组织配置了订阅限制当前网络或账号不在官方支持范围内返回带地区代码的错误。排查顺序应该是先确认系统时间自动同步再确认账号有 Claude Code 使用权限重新执行官方登录命令查看官方支持范围最后联系官方支持。不要手动编辑本地登录文件强行绕过校验。那样做会把登录阶段的问题扩大成安全问题而且并不会带来任何缓存优化。4.2 地区不可用和“禁用访问”提示报错里如果出现403 forbidden、country, region, or territory not supported说明当前网络或账号不在官方可用范围内。这种提示只能按官方规则处理去官方支持页面确认支持的国家和账号要求使用官方允许的渠道登录。不要尝试用非官方方式替换网络出口或伪造地区信息。所有绕过验证的操作都不安全也容易违反服务条款。如果业务确实需要应该走正式渠道向官方反馈。另一种常见提示是your organization has disabled claude subscription access for claude code。这是账号权限问题和你的本机配置无关。让组织管理员在管理后台确认 Claude Code 权限是否开通即可。4.3 安装和 VS Code 配置阶段的坑很多用户第一次遇到登录问题其实是安装和配置阶段的顺序不对。Claude Code 的 CLI 和 VS Code 扩展会共用一份登录状态但如果两边版本不一致或者一个登录成功一个登录失败就可能出现反复要求enter authorization token to sign in。建议先安装官方 CLI完成登录再配置 VS Code 扩展不要使用来源不明的“免登录”版本。这类版本可能绕过登录校验但它不会带来任何官方缓存优化还会引入凭据风险卸载重装前先退出登录清理缓存和配置目录再安装新版本避免旧状态干扰新的认证如果你在服务器或远程环境使用不要直接复制本地认证文件到另一台机器。触发安全校验以后登录问题会变得更难排查。有一段搜索热词里还出现了“免费 token”“credits 抵扣”这类说法这些和登录报错是两套体系下一节具体说。5. 免费额度、第三方模型和“超级省 token”的边界5.1 免费 token 和 credits 的抵扣口径不一样有时看到“免费 token”“credits”这类说法。要区分清楚提示缓存带来的折扣是计费规则层面的免费额度、订阅赠送的 credits是账号账户层面的。两者叠加时具体抵扣顺序和单价要看你的订阅计划与账单明细不同计划对 cache_read 的计价可能不同。最稳的方式是看官方费用页面里的 prompt caching 价格说明以及你自己账单里cache_read部分。不要凭第三方的“省 90%”就认为总账单一定降 90%。如果输入 token 占总费用比例不高总账单降幅可能只有 20% 到 30%。所以看到账单变化先拆结构输入费用降了没有缓存命中比例是多少输出费用是不是变高了免费额度是不是已经用完开始走正常计费。不拆结构很难定位问题也容易把免费额度耗尽误判成缓存失效。5.2 第三方模型接入时缓存逻辑可能完全变了Claude Code 可以对接一些 Anthropic 风格兼容接口也有社区方案接入 DeepSeek 等模型。这里有一个重要边界官方提示缓存的折扣只适用于官方计费链路。如果你通过第三方网关、自定义 endpoint 接入模型请求前缀是否缓存、怎么计费、有没有折扣完全取决于网关和服务商的实现与 Claude Code 客户端的提示缓存无关。最近搜索里出现deepseek-v4-pro is not a model this version of claude code recognizes这类报错。这说明 Claude Code 对模型名有识别校验。出现这类提示时先检查模型名是否拼写正确、客户端版本是否支持、网关返回的模型列表是否更新。不要因为同样的命令在官方模型能用就认为换到第三方模型后所有功能都一致。第三方模型环境下即使 verbose 日志里看不到 cache_read 字段也不代表计费出错可能只是网关不透传这些信息。如果你主要目的是省钱用第三方模型时不要以官方缓存折扣作为预期。它省不省钱要看对接的服务商自己的计价方式。5.3 Codex 和 Claude Code 的对比不宜只看“省 90%”有人拿 Codex 和 Claude Code 对比说一个省 token 一个不省。这里建议只把它当作工具差异不要当成绝对结论。两者的计费模型、缓存策略、上下文组装方式都不同甚至不同版本之间也在频繁调整。真正要比较应该放在同一批实测任务里把 verbose 日志、账单明细、输出质量放在一起看。单看一个“缓存价格打九折”的标题容易选错工具。很多插件和 skill 也会宣称“大幅省 token”本质上是精简发送给模型的上下文。这种优化确实有作用但它和官方提示缓存是两条独立路径官方缓存优化的是重复前缀的计费插件优化的是发送内容的体积。两者可以叠加但别把两者混在一起算账。先确认官方缓存命中正常再考虑用插件精简内容。顺序反了排查时会互相干扰。6. 我建议的落地顺序和停止优化信号6.1 稳定起步顺序最后给一个相对保守的落地顺序我自己按这个顺序跑过几轮踩坑最少先把 Claude Code 在本地装好用官方登录方式跑通一条任务把 CLAUDE.md 的结构整理好稳定内容一次写完整动态内容全部靠工具读取打开 verbose连续跑两条相同任务确认 cache_read 不是 0确认缓存正常后再开始批量任务、并行任务、子代理和 MCP 配置定期看账单里的 cache_read 和 input 比例发现比例明显下降优先检查 CLAUDE.md 是否被动过、会话是不是被频繁切换。这个过程看起来慢但能避免两类最典型的问题一开始就追求并行和批量结果缓存命中率极低账单反而涨了把登录 token 报错和提示缓存混在一起排查半天找错方向。6.2 什么时候不用继续扣缓存不是所有项目都需要把缓存优化到极致。如果你的项目很小CLAUDE.md 只有几十行每次会话上下文也不长那么缓存命中省下来的钱可能有限。这时候更值得优化的是任务组织方式而不是缓存参数。判断标准很简单打开 verbose 看一轮如果cache_read_input_tokens本来占比就很高说明工具已经在帮你省了如果占比低再看项目规模。小项目里占比低可能只是因为前缀本身太短不值得继续折腾。反过来如果你每天要跑大量批次或者团队共享一套项目配置那么把这 6 招吃透比到处找“省 token 插件”划算得多。提示缓存的本质很简单让重复的内容只算一次全价其余时间按折扣价复用。把前缀稳住剩下的省多少日志和账单会直接告诉你。