Prompt 缓存

Claude Code 会自动使用 prompt caching。你通常不需要手写 cache_control,但需要知道哪些操作会让下一轮变慢、变贵,以及 5 分钟和 1 小时缓存到底差在哪。

逐命令缓存影响已经单独整理到 命令与缓存影响。这页解释底层规则和排查方法。

#一句话理解

每一轮请求都会把系统提示、项目上下文、历史对话、工具结果和新消息重新发送给模型。缓存命中时,上游不再重新处理相同前缀,只处理新追加的部分。

#Claude Code 的上下文层

越靠前的层越重要。System prompt 变了,后面全部失效。Conversation 只是在末尾追加,通常最容易命中缓存。

缓存 key 还包含:

• 模型:换模型会全量 miss
• effort level:换 /effort 会全量 miss
• fast mode header:首次开启可能重新建缓存

/advisor 是一个特别例子:官方说明 advisor tool 定义位于缓存断点之后,开关它通常不会破坏已有缓存前缀。

#5 分钟 vs 1 小时

命中缓存会刷新 TTL。也就是说,5 分钟不是总时长,而是“多久没用就过期”。

#会让缓存失效的操作

MCP 是否影响缓存,取决于工具定义是否 deferred。支持 tool search 时,工具通常延迟加载,对缓存更友好。自定义网关、Vertex 或不支持 tool search 的模型上,工具可能全部进入前缀,连接变化就更容易 miss。

#不会立即失效,但也不立即生效

根级 CLAUDE.md 和 outputStyle 的新内容会在 /clear、/compact 或重启后加载。

#/compact 的成本

/compact 会发一次摘要请求。这个摘要请求通常能读取现有缓存,因为它是在当前历史后追加一条“请总结”的指令。

真正变化发生在摘要完成后:旧历史被短摘要替换,下一轮会为这个更短的新 conversation 重建缓存。正确用法是:

• 在任务自然结束时 compact
• 不要等自动 compact 在关键步骤中间触发
• 想放弃错误方向时优先 /rewind,不是 /compact

#子代理与 fork

子代理 会启动自己的对话,拥有独立上下文和独立缓存。它第一次调用通常没有缓存命中,之后在自己的多轮任务中逐步变暖。官方说明里,子代理使用 5 分钟 TTL,即使主会话在 Claude subscription 下自动使用 1 小时 TTL。

从主会话角度看,子代理调用和最终结果只是追加到 conversation 末尾,不会破坏主会话旧前缀。

/fork 或 /branch 更接近复制当前对话。fork 继承父会话已有系统提示、工具和历史,如果还在 TTL 内,第一轮更容易读到父会话缓存。--worktree 主要隔离文件系统和 Git 分支,详见 Worktrees 并行工作区。

#观测字段

Claude API usage 里有两个关键字段:

读写比越高,缓存越健康。如果 creation 每轮都高,说明前缀在变。优先检查模型、effort、output style、MCP、工具 deny、/compact 和 CLI 升级。

在 Passion8 或其他 ANTHROPIC_BASE_URL 网关下,还要确认网关是否原样转发 anthropic-beta、工具 schema、output_config、context_management、cache 字段和 usage 字段。详见 网关与协议。

#禁用或强制 TTL

# 禁用全部 prompt caching
export DISABLE_PROMPT_CACHING=1

# 只禁用某类模型
export DISABLE_PROMPT_CACHING_SONNET=1
export DISABLE_PROMPT_CACHING_OPUS=1
export DISABLE_PROMPT_CACHING_HAIKU=1
export DISABLE_PROMPT_CACHING_FABLE=1

# 可选:API/provider 场景请求 1 小时 TTL
export ENABLE_PROMPT_CACHING_1H=1

# 强制 5 分钟 TTL,覆盖 1 小时设置
export FORCE_PROMPT_CACHING_5M=1

正常使用不要禁用缓存。禁用只适合排错。

#缓存友好工作流

先用 /model 和 /effort 定好本次任务配置。
任务中途不要频繁切。

#官方参考

• How Claude Code uses prompt caching
• Commands
• Model configuration
• Gateway protocol reference
• Claude API prompt caching
• Output styles
• Status line
• Manage costs effectively