1. 先把误解掰正Claude Code 的 Prompt Cache 到底缓存了什么很多人第一次接触 Claude Code 的 Prompt Cache会下意识把它当成「文件缓存」以为改了src/auth.tsClaude Code 就只重新处理这个文件以为CLAUDE.md没动这段内容就被单独存起来复用。这个直觉是错的而且错得挺关键。Claude Code 每次发消息都会发起一次全新的 API 请求。模型本身不跨请求保留记忆所以 Claude Code 会把系统提示、工具定义、项目上下文、历史对话、工具调用结果以及你这次的新消息全部重新拼成一段超长文本发出去。Prompt Cache 做的事是让服务端不要重复处理这段文本里「开头没变」的部分。所以缓存的最小单位不是文件而是前缀prefix——请求开头一段连续、逐字节一致的内容。Anthropic 的 API 会拿这次请求的开头去匹配最近处理过的请求开头。开头完全一样就能从缓存读取已处理部分只计算新增的尾巴开头任何位置变了变化点之后全部重算而且没有 per-file 或 per-segment caching。一句话总结缓存命中的关键不是文件有没有变而是请求开头有没有完全一样。这跟 Docker layer cache 的味道很像——Dockerfile 前面某行一改后面 layer 即使内容没动也跟着失效只不过 Claude Code 的粒度更严格它看的是渲染后的请求前缀不是人眼看到的文件结构。这篇就围绕这条「越来越长的前缀链」用 TaoToken 统一 Key 把 Claude Code 接起来配置settings.json骨架然后通过多轮对话观察前缀链增长和缓存命中变化。适合已经在用 Claude Code、想搞清楚为什么长会话有时快有时慢的开发者。2. 用 TaoToken 统一 Key 接入 Claude Code在动手验证缓存之前得先有一条稳定的 API 通道。我这边习惯用 TaoToken 统一管理 Key好处是 Claude Code、脚本、其他工具共用一套凭证切换模型或排查请求时不用到处翻配置。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基地址是 https://taotoken.net/api 这个地址不加 UTM 参数。你需要先在控制台创建一个 API Key然后把它填进 Claude Code 的环境变量或配置文件。这里有个容易踩的点Claude Code 走的是 Anthropic 兼容协议所以配置时要认准ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个变量而不是 OpenAI 那套OPENAI_API_KEY。填错变量名请求会直接 401跟缓存一点关系都没有。创建 Key 的入口在控制台的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。拿到 Key 之后先别急着写进项目建议先用环境变量验证一次确认通道通了再固化到配置文件。注意Key 属于敏感凭证不要提交到 Git 仓库也不要在截图里露出完整字符串。建议放在 shell 的 profile 文件或系统的密钥管理里。3. 可复制的 settings.json 骨架与配置片段Claude Code 的配置分两层一层是环境变量决定请求发往哪里、用哪个 Key另一层是settings.json决定模型、权限、工具等行为。下面这套骨架可以直接抄改掉 Key 就能跑。先看环境变量写进~/.zshrc或~/.bashrcexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥改完记得source ~/.zshrc让配置生效。验证环境变量是否读到echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_AUTH_TOKEN | head -c 8第二条只打印前 8 位避免完整 Key 出现在终端历史里。接着是项目级或用户级的settings.json。Claude Code 会读取~/.claude/settings.json用户级和项目根目录的.claude/settings.json项目级项目级优先级更高。一个够用的骨架长这样{ model: claude-sonnet-4-5, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥 }, permissions: { allow: [ Read, Grep, Glob ], deny: [] } }这里几个字段值得说清楚。model决定用哪个模型它同时是 cache key 的一部分——换模型等于换缓存命名空间内容完全相同的请求也会重新计算。env里放通道配置这样即使 shell 没设环境变量也能跑。permissions里的工具集合会影响 system prompt 层的工具定义中途改 allow/deny 列表很可能把前缀开头改掉导致缓存整体失效。如果你要接 MCP server配置会多一段mcpServers。但请记住MCP 的工具定义如果被加载进 system prompt 前缀那么 server 的连接、断开、工具列表变化都会扰动缓存。所以长任务开工前把需要的 server 准备好任务中间尽量别反复启停。配置写完后用一次最简单的请求确认通道通了claude -p 回复 ok 两个字母即可能正常返回说明 Key 和 Base URL 都对。如果报 401回去检查ANTHROPIC_AUTH_TOKEN有没有拼错如果报连接超时检查ANTHROPIC_BASE_URL是不是写成了带路径的完整地址。4. 验证请求观察前缀链增长与缓存命中通道通了之后重点来了——怎么看到前缀链在增长、缓存有没有命中。Claude Code 本身不直接显示缓存统计但 API 响应里会带两类 token 字段cache_creation_input_tokens表示本轮写入缓存的 token 数cache_read_input_tokens表示本轮从缓存读取的 token 数。read 占比越高缓存状态越好。最直观的验证方式是在同一个 session 里连续发几轮内容相关、前缀稳定的消息然后观察响应耗时和 token 报告。你可以用一个简单的脚本直接打 API把每轮的缓存字段打出来import os import anthropic client anthropic.Anthropic( base_urlos.environ[ANTHROPIC_BASE_URL], api_keyos.environ[ANTHROPIC_AUTH_TOKEN], ) system_prompt 你是一个代码助手回答保持简洁。 # 稳定前缀 history [] for i in range(4): history.append({role: user, content: f第 {i1} 轮请复述你收到的系统提示主题。}) resp client.messages.create( modelclaude-sonnet-4-5, max_tokens128, systemsystem_prompt, messageshistory, ) usage resp.usage print( f轮次 {i1} | fcache_creation{getattr(usage, cache_creation_input_tokens, 0)} | fcache_read{getattr(usage, cache_read_input_tokens, 0)} | finput{usage.input_tokens} ) history.append({role: assistant, content: resp.content[0].text})跑起来你会看到类似这样的趋势第一轮cache_creation较高、cache_read为 0因为还没有可复用的旧请求第二轮开始cache_read明显上升cache_creation只覆盖新增的尾巴第三轮继续复用前面大部分前缀。这就是前缀链在起作用——每轮请求都是「上一轮全部内容 新消息」开头那段没变所以能命中。如果你在第二轮中途改了system_prompt比如加一句「现在请用英文回答」你会看到cache_read骤降、cache_creation重新变高。原因很简单system prompt 在请求最前面它一变后面全部跟着失效。这跟 Docker 改第一行的效果一模一样。提示默认缓存生命周期是 5 分钟每次命中会刷新。所以如果你两轮之间隔太久缓存可能已经过期cache_read会掉下来这是正常的不是配置错了。5. 本篇常见错排查报 401 Unauthorized。九成是 Key 或变量名的问题。确认用的是ANTHROPIC_AUTH_TOKEN而不是OPENAI_API_KEY确认ANTHROPIC_BASE_URL是https://taotoken.net/api且没有多余斜杠或路径。改完环境变量记得重新开终端或source。缓存一直不命中cache_read始终为 0。先检查前缀是不是每轮都在变。常见元凶system prompt 里塞了时间戳、随机 ID、动态路径每轮都改permissions或工具列表中途切了模型或 effort level。这些都会让 cache key 变化。把稳定内容放前面、动态内容追加到 conversation 尾部命中率会明显改善。长会话越跑越慢、越跑越贵。大概率是前缀被反复打断。检查是不是频繁/compact、频繁启停 MCP server、频繁改配置。/compact会重排上下文属于 cache invalidation 动作用一次会有一次全量重算放在任务自然断点用比较划算。换了工作目录后缓存像没了。这是正常的。Claude Code 的 system prompt 里会包含工作目录、平台、shell、OS 版本、auto memory 路径等信息所以缓存近似 scoped 到一台机器加一个目录。同一仓库的不同 worktree因为工作目录不同前缀也不同不会自动共享缓存。MCP 一接上就变慢。工具定义在 system prompt 层属于很靠前的前缀。server 连接、断开或工具列表变化都可能让前缀重算。建议开工前把本次任务需要的连接准备好任务中间尽量只追加 conversation 层信息。排障时如果怀疑是通道问题而不是缓存问题可以先用模型对话页面单独发一条请求确认 Key 和通道本身没问题https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果那边正常、Claude Code 里异常问题多半在本地配置或前缀组织上。6. 把前缀链经营好长任务才顺滑回到最开始那个判断Claude Code 的 Prompt Cache 不是把某个文件、某段代码单独存起来而是一条严格的前缀链。system prompt、project context、conversation 这三层的顺序决定了缓存命中率的上限model、effort level、tool definitions、MCP server、plugin、/compact这些动作决定了这个上限能不能落地。落到日常习惯上其实很朴素CLAUDE.md写长期稳定的项目约定临时状态用普通消息追加model 和 effort level 开局定好别在长任务中途来回切MCP server 和 plugin 开工前准备好/compact留给任务边界。这些看起来是小动作实际直接影响速度和费用。如果你还没把 Claude Code 的通道统一起来可以先用 TaoToken 的 API Key 把环境变量配好再按上面的脚本跑四轮亲眼看一下cache_read怎么涨起来。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 配置细节和字段说明都能对上。长期跑编码任务或 Agent 的话Coding Plan 会更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。把前缀链经营好等到会话跑到几十轮、工具调用堆到上百次时你就能明显感觉到差别。