提示缓存

提示缓存让 Claude Code 更快、更省钱。没有缓存，API 每一回合都要重新处理你的完整历史；有了缓存，它复用已处理过的内容，并按缓存 token 的价格计费。除非你禁用它，Claude Code 会自动处理提示缓存。不过了解缓存如何工作仍然有用，因为有些动作会使缓存失效，让下一次响应更慢、更贵。

缓存是怎么组织的

你每在 Claude Code 里发一条消息，它都会发出一个新的 API 请求。模型在请求之间不记得任何东西，所以 Claude Code 会重新发送完整上下文：系统提示、项目上下文、每条之前的消息和工具结果。API 通过把每个请求的开头（称为前缀）与它最近处理过的内容匹配来缓存。在正常回合里，前缀就是整个上一次请求，只有最新的一轮交流是新的。匹配是精确的，所以前缀里任何一处改变都会使它之后的一切失效。

为了最大化前缀匹配，Claude Code 按层排列每个请求，让回合之间很少变化的内容排在最前面：

层	内容	何时变化
系统提示	核心指令、工具定义	加载的工具定义集合变化时
项目上下文	CLAUDE.md、自动记忆、不限定路径的规则	会话开始，或 /clear 或 /compact 之后
对话	你的消息、Claude 的回复、工具结果	每一回合

对话层的变化让系统提示和项目上下文保持缓存；系统提示的变化使一切失效，因为之后的所有内容现在都排在不同的前缀后面。两项设置不在这张层表里，但仍会影响缓存什么：模型（每个模型有自己的缓存，切换模型会重新计算整个请求，哪怕内容相同）和努力等级（在大多数模型上，每个努力等级有自己的缓存，所以会话中途改努力会重新计算整个请求）。

在会话一开始就选好模型和努力等级，把 /compact 留给任务之间的自然间隙。任务中途改动越少，缓存命中率越高。

缓存存在哪里：缓存发生在服务端，在为你的模型提供服务的基础设施里：API Key、Claude 订阅或 Claude Platform on AWS 时，缓存在 Anthropic 的基础设施里；Amazon Bedrock 或 Google Cloud 的 Agent Platform 时，在你的云厂商的服务基础设施里；用自定义 ANTHROPIC_BASE_URL 或 LLM 网关时，缓存在你的请求被转发到的地方，缓存是否有效取决于网关。

会让缓存失效的动作

这些动作会让下一个请求错过部分或全部缓存：你会看到一次性的更慢、更贵的回合，之后新前缀被缓存。一旦知道它们有成本，大多数在任务中途是可以避免的。

• 切换模型：每个模型有自己的缓存。用 /model 切换意味着下一个请求读取整个对话历史而没有任何缓存命中，哪怕内容相同。在终端运行 /model 时，只有缓存还热、且新模型不是产生上一次响应的模型时，Claude Code 才会让你确认切换。opusplan 在计划模式用 Opus、执行时用 Sonnet，所以每次切换计划模式都是一次模型切换。
• 改变努力等级：在大多数模型上，会话中途改努力等级意味着下一个请求没有缓存命中，缓存还热时 Claude Code 会先让你确认。在用 API Key 或 Claude 订阅的 Opus 5.5、Sonnet 5.5 和 Fable 5.1 上，改努力会保留缓存。
• 打开快速模式：启用快速模式会添加一个属于缓存键一部分的请求头，所以带快速模式发出的第一个请求读取整个对话历史而没有缓存命中。这个成本每个对话只出现一次。
• 连接或移除 MCP 服务器：工具定义位于系统提示层，所以回合之间请求里的工具定义集合变化时缓存失效。工具被延迟加载时，Claude Code 在整个对话里保留对话第一个请求的工具列表，所以会话中途服务器连接或断开不会扰动已缓存的内容；工具被预先加载时，添加定义会使缓存失效，有意移除一个也会。
• 启用或禁用插件；完全拒绝某个工具（deny 规则命名整个工具会把它从上下文里移除）；压缩对话；累积很多图片；升级 Claude Code。

不会让缓存失效的动作

编辑你仓库里的文件、会话中途编辑 CLAUDE.md（它在会话开始时才读取，所以中途的编辑不会生效，这也是缓存保持完整的原因）、改变权限模式、改变输出风格（下一条消息起新风格生效，但缓存在对话层之后继续命中）、调用 Skill 和命令、运行 /recap、回退对话，这些都保持缓存。恢复会话时，缓存是否还热取决于距上次活动多久。

缓存生命周期

缓存的前缀在不活动一段时间后过期。每个命中缓存的请求都会重置计时器，所以只要你持续工作，缓存就保持热。间隔足够长之后，下一个请求会重新计算完整输入并重建缓存。在 Pro 或 Max 套餐上，你在长时间休息后恢复大型会话时，Claude Code 会提议从摘要恢复，让之后的请求不携带完整历史。

生存时间（TTL）控制缓存能撑过多长的间隔。API 提供两种：五分钟 TTL，和在较长间隔里保持缓存热的一小时 TTL。Claude Code 按请求决定 TTL，每个请求落在两个固定的桶之一：主对话（你的交互回合、非交互 -p 运行和 Agent SDK 回合，以及与它们一起内联运行的辅助请求）和其他一切（Claude Code 在该对话之外发出的请求，如子智能体、工作流、进程内队友、fork、压缩和会话标题）。

除非你自己选 TTL，Claude Code 只在 Claude 订阅的套餐包含用量内请求一小时 TTL：

请求桶	Claude 订阅，套餐用量内	用量额度、API Key 或云厂商
主对话	一小时	五分钟
其他一切	五分钟（服务端控制的辅助请求除外，它们得到一小时）	五分钟

自己选择 TTL：可以为任一个桶设置 TTL，每个控制项取 5m 或 1h，其他值会被忽略：主对话用 promptCacheTtl 设置或 CLAUDE_CODE_PROMPT_CACHE_TTL 环境变量；其他一切用 subagentPromptCacheTtl 设置或 CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL 环境变量（都需要 v2.1.242 或更新版本）。如果你用 API Key 登录或使用云厂商，把 promptCacheTtl 设为 1h 就能给主对话一小时缓存。多个控制项同时适用时，按这个顺序取第一个匹配：FORCE_PROMPT_CACHING_5M=1（强制两个桶都用五分钟）；该桶的环境变量；该桶的设置；子智能体请求用其 experimental 前置信息里的 cacheTtl；ENABLE_PROMPT_CACHING_1H=1（为两个桶都请求一小时）。官方原文还涵盖如何检查你的缓存命中率，以及禁用提示缓存的变量。