Claude Code 的 Prompt Caching 到底能不能在换掉底层 API 之后继续命中这个问题我在原文 3.5 节和总结里反复卡住Anthropic 侧的 cache_control 一旦被兼容 API 忽略前面辛苦排好的稳定前缀就白搭。与其猜不如量一次。这篇就是那轮排障记录——先到 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建一把 Key再把 Claude Code 的 Base URL 指向 https://taotoken.net/api末尾不带 /v1最后在同一个工程里跑长上下文请求只盯 usage 里那几个和缓存有关的字段。原文讲的是 Claude Code 怎么把静态的 system prompt、工具定义、CLAUDE.md 放到稳定前缀把动态内容后置到 message 或 tool_result甚至 compaction 也尽量复用父会话前缀它留下来的悬念是换模型、换 API 之后这套编排还认不认。这轮验证只做后半段通道怎么接、请求怎么发、字段怎么读、没命中时先查哪三个地方。1. 从原文 3.5 节的疑问开始换了底层 APIcache_control 还算数吗原文整篇其实在讲一件事Claude Code 不是每条消息都把全部上下文重算一遍而是把一大坨不会变的东西放在最前面让它变成一个可复用的前缀。system prompt、工具定义、CLAUDE.md 这三样属于典型的不动资产用户这句追问、命令抛出的那段报错、工具返回的那段日志才属于每次都会变的部分。顺序一旦被打乱缓存基本就废了。但 3.5 节留了个尾巴总结里又提了一次换底层模型或者把请求打到兼容 API 上cache_control 标记有可能被上游直接忽略。潜台词是——你的编排可能完全正确可缓存有没有生效不是靠我写了就能确定的。所以判断标准不能停留在请求体里有没有那个字段而得看响应 usage 里有没有对应的计数。1.1 Claude Code 把什么放在稳定前缀里以一次真实会话为例打开一个工程目录第一轮请求里 Claude Code 会把系统提示词、工具清单读文件、写文件、执行命令这些定义、以及项目根目录下的 CLAUDE.md 拼到最前面。这部分在同一轮会话里高度恒定最适合被标成缓存断点断点之后才是你敲进去的那句话。注意同一轮会话这个限定。换工程目录、改 CLAUDE.md、新装一个 MCP 让工具清单多出几项前面那一大坨就变了。前缀变了缓存自然对不上。很多人以为只有换 Base URL 才会出问题其实在工程里随手加一段约定、顺手装个 Skill同样会让前缀作废。1.2 兼容通道最容易被忽略的那一层cache_control 是 Anthropic Messages API 请求结构里的字段含义是从这一段开始可以缓存。请求经过兼容通道转发时这层标记能不能被完整理解取决于上游实现。原文担心的被忽略就是标记发出去了上游当没看见于是每次请求都按全新输入计费。这也解释了为什么很多人换完通道感觉变贵了却没报错。功能全在只是缓存那部分没省下来。要确认到底有没有省只能回到 usage。2. 在动配置之前先把前缀顺序摆正先说清一件事TaoToken 在这里只负责给你一把 Key 和一条 Base URL 通道它不会替你重排 prompt。缓存命不命中八成取决于你自己怎么组织上下文。配置写错了可以马上改前缀排错了得靠习惯慢慢纠。2.1 system prompt、工具定义、CLAUDE.md 的先后稳定前缀内部也有次序讲究。可以把它想成一个书架半年不会动的书放最里层每天新贴的便签贴最外层。system prompt 是最里层工具定义紧跟着它CLAUDE.md 属于随工程走的一层通常贴在工具定义之后。项目约定、目录说明、构建命令这类低频变动的内容放这里很合适因为它们在一轮会话里基本不动。真正该警惕的是临时加戏比如会话跑到一半你往 CLAUDE.md 里补了一段新的规范再继续问问题。前一轮建立起来的缓存前缀立刻作废后面每一次请求都要重新写一遍缓存。频繁这么干长会话的成本曲线会很难看。2.2 动态内容下沉到 message 与 tool_result反过来每次都不一样的东西必须往后放。有人习惯把一整段几十行的日志贴在提问的最开头看着像给足上下文实际是让前缀第一句就变成一次性内容后面再稳也没用。更合理的做法是把日志作为一次 tool_result 或者一条追加的 user message 送进去让前面那层结构原封不动。这条习惯和缓存是强绑定的。你把变动内容下沉一层前缀就多稳一层你把它提到最前面整条链路的复用机会就归零。2.3 compaction 也要顺着父会话前缀走上下文太长会触发 compaction把前面的对话压成摘要。原文特别提到压缩之后的请求最好还能复用父会话的前缀否则每压缩一次缓存就断一次会话越长越贵。你能做的是压缩之后不要手动重排整个上下文也不要在那个节点上顺手改工具清单或者换模型让摘要作为新的动态内容追加即可。3. settings.json 里把 Claude Code 的 Base URL 指到 TaoToken3.1 先拿一把 Key顺便抄下模型 ID打开 TaoToken注册后进控制台创建 API Key同时看模型广场里当时可用的模型 ID抄下来备用。本文统一用 YOUR_API_KEY 当占位符真实 Key 不要出现在截图、文档或者提交记录里。顺手把模型 ID 抄准很重要。这个值以 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 模型广场的当时列表为准不要凭印象拼一个名字也别自己加日期后缀。3.2 环境变量写法一次验证最快只想先跑通一轮用环境变量最省事。开一个新终端export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_API_KEY export ANTHROPIC_MODELYOUR_MODEL_ID claude两个坑要避开Base URL 结尾不带 /v1也不要填官网那个带参数的落地页地址那是给人点的不是接口ANTHROPIC_MODEL 必须是模型广场里真实存在的 ID写成想当然的字符串只会换来一个找不到模型的报错。3.3 ~/.claude/settings.json 的 env 写法准备长期用就落进配置文件编辑~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: YOUR_MODEL_ID } }保存后重开一个会话用/status看一下当前的 Base URL 和模型是不是和你填的一致。如果你平时用 CC Switch 这类切换工具那边的自定义供应商也是同一套三件套Base URL 填https://taotoken.net/apiKey 填YOUR_API_KEY模型 ID 从模型广场抄。三处保持一致后面读 usage 才有意义。4. 跑两轮长上下文去 usage 里读缓存命中4.1 构造一个足够长、足够稳的前缀验证缓存最忌讳边跑边改。先把变量冻结同一个工程目录、同一份 CLAUDE.md、同一套工具清单、同一个模型 ID中途不要装新 MCP、不要改配置、不要/clear之后换目录重来。然后造一段够长的稳定前缀。最简单的办法是打开一个文件量正常的工程让 Claude Code 先把 CLAUDE.md 和工具定义吃进去第一轮问一个需要读几个文件才能答的问题。等它答完紧接着用几乎相同的前缀再问一个同类型的问题——注意是紧接着缓存有存活时间间隔拉太长前一层的写入就过期了。4.2 cache_creation_input_tokens 与 cache_read_input_tokens 怎么读响应 usage 里和缓存直接相关的通常有两个字段cache_creation_input_tokens表示这次请求往缓存里写了多少 tokencache_read_input_tokens表示这次从缓存里读出了多少 token。加上常规的input_tokens和output_tokens就够判断一次请求的形态了。对照着看观察到的形态说明什么下一步第一轮 cache_creation 大第二轮 cache_read 明显大于 0前缀被复用了保持当前的内容顺序每一轮 cache_creation 都很大cache_read 始终为 0缓存没被用上先怀疑前缀变了再怀疑通道是否透传usage 里压根没有这两个字段上游没返回缓存计数只能靠 input_tokens 总量间接估算第二行是最需要区分的场景。同样是缓存没生效前缀自己变掉和上游忽略标记是两回事前者改习惯就能救后者改不动。4.3 从 transcript 里把 usage 抽出来Claude Code 会把会话记录写在本地的项目目录下每条 assistant 消息自带 usage。想批量看先列出工程目录ls ~/.claude/projects/找到当前工程对应的那个目录再用 jq 把 usage 抽出来看最后若干条jq .message.usage ~/.claude/projects/你的工程目录/会话文件.jsonl | tail -n 20没装 jq 就直接在编辑器里搜cache_read_input_tokens效果一样。把两轮请求的这几个数并排抄下来比在终端里凭感觉猜靠谱得多。5. 缓存没按预期命中时的排查顺序5.1 Base URL 多写 /v1、填成落地页会报什么第一步永远是核对 Base URL。正确值是https://taotoken.net/api。写成https://taotoken.net/api/v1等于多套了一层路径常见表现是 404 或者找不到对应模型把落地页那串带参数的链接填进去更不行那是页面地址。第二步核对认证。401 通常意味着 Key 没带上或者复制时夹了空格检查ANTHROPIC_AUTH_TOKEN是不是YOUR_API_KEY那个位置没被替换。这两个错和缓存无关但会伪装成通道有问题先排掉再谈命中。5.2 会话中途换模型、增删工具的前缀代价缓存是按模型分开的。会话跑到一半切到另一个模型等于换了一本书架前面的缓存全不认只能重建。同理新装一个 MCP、临时禁用某个工具工具定义这一段就变了前缀跟着变。所以验证期间要克制想测缓存就别在同一轮会话里做这三件事——换模型、增删工具、改 CLAUDE.md。真要改改完重新起一轮把新的一轮当基线重新数。5.3 上游没透传 cache_control 时怎么判断如果前缀确实一字未改、两轮间隔很短第二轮cache_read_input_tokens仍然是 0而cache_creation_input_tokens每轮都在涨那大概率就是这层标记没有被上游使用。此时功能不受影响只是省不下缓存那部分开销要不要继续用取决于你的调用量。认下这个结论也有好处至少知道瓶颈在结构而不是在配置。能优化的地方就只剩把稳定前缀压得更短更整齐这件事——比如精简 CLAUDE.md 里那些其实用不上的段落把真正高频的约定放前面。6. 验证完之后把这轮调用对回控制台字段读完了把配置固化下来再对一次账。用同一把 Key 在 TaoToken 模型对话 里发一条测试消息确认模型 ID 和通道都没填错如果你打算长期用它写代码可以打开 Coding Plan 看套餐够不够用Key 的创建和轮换在 控制台 API Keys环境变量和配置文件细节对照 Claude Code 接入文档。最后一件事是回 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 的控制台把这次调用的 token 量和你从 transcript 里读到的数对比一下。量级对得上说明通道这层没问题后面所有的优化空间都在你自己的 prompt 结构里稳定前缀再整齐一点、动态内容再往下沉一层、别在会话中途动工具和模型。还有一条边界要记住——Claude Code 能读懂你贴进去的代码和 SQL但真正的诊断语句、编译命令、库表操作得由你在本地或者测试环境里执行再把结果贴回对话别把会话指向生产库。