Claude Code 如何使用 prompt caching

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Prompt caching 使 Claude Code 更快速且更具成本效益。沒有快取的情況下，API 會在每次轉換時重新處理您的完整歷史記錄。有了快取，它會重複使用已經處理過的內容，只對變更的部分進行新工作。 Claude Code 會為您處理 prompt caching，除非您禁用它。了解 prompt caching 的工作原理仍然很有用，因為某些操作會使快取失效，使下一個回應變得更慢且更昂貴，同時它重新建立快取。本頁涵蓋哪些操作會這樣做、為什麼某些設定需要等待重新啟動才能應用，以及當使用量看起來很高時如何檢查快取效能。

​

快取的組織方式

每次您在 Claude Code 中發送訊息時，它都會發出新的 API 請求。模型在請求之間不記得任何內容，因此 Claude Code 會重新發送完整的上下文：系統提示、您的專案上下文、每個先前的訊息和工具結果，以及您的新訊息。新內容會附加在末尾，這意味著每個請求的大部分內容與前一個請求相同。Prompt caching 是 API 避免重新處理未變更部分的方式。 API 通過將每個請求的開始部分（稱為前綴）與最近處理過的內容進行匹配來進行快取。在正常轉換中，前綴是整個先前的請求，只有最新的交換是新的。匹配是精確的，因此前綴中任何地方的變更都會重新計算其後的所有內容。沒有按檔案或按段的快取。請參閱 API 參考中的prompt caching 如何工作以了解基礎機制。 為了充分利用前綴匹配，Claude Code 會組織每個請求，使轉換之間很少變更的內容首先出現： 對對話層的變更會保留系統提示和專案上下文的快取。對系統提示的變更會使所有內容失效，因為所有後續內容現在位於不同的前綴後面。第三列提供常見觸發器而不是詳盡列表，下面的部分涵蓋完整集合，包括在會話開始時固定的輸出風格等內容。 前綴匹配規則解釋了本頁上的大多數行為。例如，Plan Mode 和技能加載將其指令附加為對話訊息，因此快取的前綴保持完整。 兩個設定根本不是提示文本的一部分，因此它們不會出現在層表中。它們對快取的行為不同：

• Model：快取由模型鍵入，因此每個模型都有自己的快取。切換模型會重新計算整個請求，即使內容相同。請參閱下面的切換模型。
• Effort level：不是快取鍵或提示的一部分，因此在會話中期變更它對快取沒有影響。

​

快取位置

快取發生在伺服器端，在提供您的模型的任何基礎設施中。位置取決於您如何進行身份驗證：

• API 金鑰、Claude 訂閱或 Claude Platform on AWS：快取位於 Anthropic 的基礎設施中，通過 Claude API 訪問
• Bedrock 或 Vertex AI：快取位於您的雲端提供商的服務基礎設施中
• Foundry：請求路由到 Anthropic 的基礎設施
• 自訂 ANTHROPIC_BASE_URL 或 LLM gateway：快取位於您的請求轉發到的位置，快取是否工作取決於閘道

有關每個提供商存儲和處理的內容，請參閱資料使用。無論快取位於何處，條目在一段時間不活動後過期，下面的快取生命週期涵蓋 TTL 以及如何延長它。

​

使快取失效的操作

這些操作會導致下一個請求錯過部分或全部快取。您會看到一次較慢、更昂貴的轉換，之後新的前綴會被快取。一旦您知道它們有成本，大多數都可以在任務中期避免。模型切換或 MCP 重新連接可能看起來是免費的，直到您注意到隨後的較慢轉換。

• 切換模型
• 連接或斷開 MCP 伺服器
• 拒絕整個工具
• 壓縮對話
• 升級 Claude Code

​

切換模型

每個模型都有自己的快取。使用 /model 切換意味著下一個請求讀取整個對話歷史記錄而沒有快取命中，即使內容相同。 opusplan 模型設定在 Plan Mode 期間解析為 Opus，在執行期間解析為 Sonnet，因此每個 Plan Mode 切換都是模型切換並啟動新的快取。

​

連接或斷開 MCP 伺服器

工具定義位於系統提示層中，因此當 Claude 可用的 MCP 工具集在轉換之間變更時，快取會失效。最常見的原因是 MCP 伺服器在會話中期連接或斷開連接，這可能在沒有您採取任何操作的情況下發生：stdio 伺服器的進程退出、HTTP 會話過期，或伺服器在暫時性故障後自動重新連接。連接的伺服器也可以推送動態工具更新來變更其工具列表。 編輯您的 MCP 配置本身不會變更快取。新配置只有在重新啟動後才會生效，這是伺服器連接或斷開連接的時候。 MCP 工具搜尋通過延遲完整工具定義來減少每個工具對前綴的貢獻，但工具名稱集合仍然必須保持穩定，快取才能保持有效。

​

拒絕整個工具

添加裸工具名稱（如 Bash 或 WebFetch）作為拒絕規則會將該工具從 Claude 的上下文中完全移除。工具定義位於系統提示層中，因此在會話中期添加或移除其中一個規則會使快取失效，就像 MCP 伺服器連接或斷開連接一樣。無論您通過 /permissions 添加它還是通過直接編輯設定檔，變更都會在下一個轉換時生效。 只有裸工具名稱或等效的 Bash(*) 形式才有此效果。作用域拒絕規則（如 Bash(rm *)）以及所有允許和詢問規則都不會改變 Claude 看到的工具。Claude Code 在 Claude 嘗試呼叫時檢查它們，保持前綴完整。

​

壓縮對話

壓縮用摘要替換您的訊息歷史記錄。根據設計，這會使對話層失效，因為下一個請求有一個新的、更短的歷史記錄，不與舊的共享前綴。Claude Code 重複使用系統提示層並從磁碟重新加載專案上下文，只有在 CLAUDE.md 和記憶自會話開始以來未變更時才快取命中。 為了生成摘要，Claude Code 發送一個一次性請求，其系統提示、工具和歷史記錄與您的對話相同，加上作為最終使用者訊息附加的摘要指令。因為它共享您的前綴，該請求讀取現有快取而不是重新處理完整歷史記錄。壓縮的大部分時間用於生成摘要，而不是快取未命中。隨後的轉換只為更短的摘要重新建立對話快取，因此壓縮後的轉換不是緩慢的部分。

​

升級 Claude Code

新的 Claude Code 版本通常會更新系統提示或工具定義，因此升級後的第一個請求會從頂部重新建立快取。自動更新在後台下載新版本，但在下次啟動時應用它們，從不在會話中期，因此您會看到這是重新啟動後的未快取第一個轉換，而不是會話期間的驚喜。設定 DISABLE_AUTOUPDATER=1 以控制何時應用升級。

​

保留快取的操作

這些操作要麼附加到對話的末尾，要麼根本不觸及請求。其中一些，例如編輯 CLAUDE.md 或變更輸出風格，也是為什麼設定變更需要等待重新啟動才能應用的原因。

• 編輯您的儲存庫中的檔案
• 在會話中期編輯 CLAUDE.md
• 變更輸出風格
• 變更權限模式
• 調用技能和命令
• 運行 /recap
• 重新開始對話
• 生成子代理

​

編輯您的儲存庫中的檔案

檔案內容只有在 Claude 讀取它們時才進入上下文，讀取會附加到對話。編輯 Claude 之前讀過的檔案不會追溯變更歷史記錄中的較早讀取。相反，Claude Code 附加一個 <system-reminder> 注意到檔案已變更，如果需要，Claude 會重新讀取它。

​

在會話中期編輯 CLAUDE.md

您的專案根目錄和使用者級別 CLAUDE.md 檔案在會話開始時讀取一次並保存在記憶中。在會話中期編輯它們不會使快取失效，但編輯也不會應用。Claude 繼續使用在會話開始時加載的版本。新內容在下一個 /clear、/compact 或重新啟動時加載。 子目錄中的嵌套 CLAUDE.md 檔案和帶有 paths: frontmatter 的規則稍後加載，當 Claude 首次讀取匹配檔案時。在它加載之前編輯一個確實會生效。加載後，內容是對話歷史記錄的一部分，因此會話中期的編輯不會追溯變更它。

​

變更輸出風格

輸出風格是系統提示的一部分，Claude Code 在會話開始時讀取一次。通過 /config 或 outputStyle 設定在會話中期變更它不會使快取失效，但變更也不會應用。Claude 繼續使用在會話開始時加載的風格。新風格在下一個 /clear 或重新啟動時加載。

​

變更權限模式

在權限模式之間切換，例如從預設切換到接受編輯，不會變更系統提示或工具定義，因此模式變更是快取安全的。例外是使用 opusplan 模型設定的 Plan Mode，它在進入或離開 Plan Mode 時在 Opus 和 Sonnet 之間切換模型。這使模式切換成為模型切換。

​

調用技能和命令

技能和命令在調用點將其指令注入為使用者訊息。對話中較早的任何內容都不會變更。

​

運行 /recap

/recap 生成一個摘要以在您的終端中顯示。與 /compact 不同，它將摘要附加為命令輸出而不是替換您的訊息歷史記錄，因此快取的前綴保持完整。

​

重新開始對話

/rewind 將您的對話截斷回到較早的轉換。剩餘的歷史記錄是快取在該點建立時的相同內容，系統提示和專案上下文層未變更，因此下一個請求命中較早的快取條目。自那時以來的每個轉換都通過該前綴讀取，即使原始轉換比 TTL 更久遠，也保持條目溫暖。 恢復檔案檢查點與對話一起對快取沒有單獨的影響。檔案內容只有在 Claude 讀取它們時才進入上下文，與編輯您的儲存庫中的檔案相同。

​

快取生命週期

快取的前綴在一段時間不活動後過期。每個命中快取的請求都會重置計時器，因此只要您繼續工作，快取就會保持溫暖。在足夠長的間隙之後，下一個請求會重新計算完整輸入並重新建立快取，這就是為什麼在步開後回來的第一個轉換可能會明顯變慢。 生存時間 (TTL) 控制快取存活的間隙有多長。API 提供兩個：五分鐘 TTL 和一小時 TTL，它通過更長的中斷保持快取溫暖，但以更高的速率計費快取寫入。Claude Code 根據您如何進行身份驗證為您選擇 TTL，您可以使用環境變數覆蓋它。

​

在 Claude 訂閱上

在 Claude 訂閱上，Claude Code 自動請求一小時 TTL。使用量包含在您的計畫中，而不是按令牌計費，因此更長的 TTL 對您沒有額外成本，只會影響快取保持溫暖的時間。 如果您已超過計畫的使用量限制，Claude Code 正在使用使用額度，您將被計費該使用量，因此 Claude Code 會自動將 TTL 降低到五分鐘。

​

在 API 金鑰或第三方提供商上

在 API 金鑰、Bedrock、Vertex、Foundry 或 Claude Platform on AWS 上，您支付按令牌費率，因此 TTL 預設保持在更便宜的五分鐘。要選擇加入一小時 TTL，設定 ENABLE_PROMPT_CACHING_1H=1。 在 Bedrock 上，prompt caching 支援、最小可快取前綴長度和一小時 TTL 可用性都因模型而異。如果快取令牌計數保持為零，請檢查 Bedrock 文件中的支援的模型、區域和限制。

​

覆蓋 TTL

設定 FORCE_PROMPT_CACHING_5M=1 以強制五分鐘 TTL，無論身份驗證如何。當您調試快取行為、比較兩個 TTL 或覆蓋在受管設定中設定的 ENABLE_PROMPT_CACHING_1H 時，這很有用。

​

快取範圍

在 Claude Code 中，快取有效地限定在一台機器和目錄。系統提示嵌入工作目錄、平台、shell、OS 版本和自動記憶路徑，因此在不同目錄中的兩個會話建立不同的前綴並錯過彼此的快取。這包括同一儲存庫的 worktrees，因為每個 worktree 都有自己的工作目錄。 您在同一目錄中並行運行的會話建立匹配的前綴並讀取彼此的快取。順序會話只有在啟動時的 git 狀態快照匹配時才共享前綴，因為系統提示也捕獲分支和最近的提交。 基礎 API 快取更廣泛。快取在組織之間隔離，在某些提供商上，在組織內的工作區之間隔離。在這些邊界內，任何兩個具有相同模型和前綴的請求讀取相同的快取。對於運行自動化流程艦隊的 Agent SDK 呼叫者，請參閱改進跨使用者和機器的 prompt caching以抑制系統提示的按機器部分並跨機器共享快取。

​

檢查快取效能

快取效能顯示為 API 在每個回應上報告的兩個令牌計數。最直接的方式是觀看它們實時是狀態行指令碼，它讀取 current_usage 物件： 高讀取與建立比率意味著快取工作良好。如果建立在轉換之間保持高位，您的前綴中有些東西在變更。使快取失效的操作部分列出了常見原因。 為了在整個組織中獲得可見性，OpenTelemetry 匯出器報告每個使用者和會話的快取讀取和建立令牌。請參閱監控使用以了解指標和事件屬性參考。

​

子代理和快取

子代理開始自己的對話，具有自己的系統提示和工具集，與父代分開。它建立自己的快取，在第一次呼叫時沒有快取命中，並在自己的轉換中預熱。子代理使用五分鐘 TTL，即使在訂閱上，因為自動一小時 TTL 適用於主對話。 父代的快取不受影響。從父代的角度來看，子代理的呼叫和結果附加到對話，保留父代的前綴完整。 分支相比之下，完全繼承父代的系統提示、工具和對話歷史記錄，因此其第一個請求讀取父代的快取。壓縮對話中描述的壓縮摘要呼叫使用相同的前綴共享方法。

​

禁用 prompt caching

禁用快取在使用特定模型或提供商調試快取行為時偶爾很有用。要關閉它，請將以下環境變數之一設定為 1： 要在整個組織中設定快取策略，請將這些或TTL 變數中的任何一個放在受管設定的 env 區塊中。為了正常使用，請保持快取啟用。

​

相關資源

• 從建立 Claude Code 中學到的課程：Prompt caching 就是一切：Plan Mode、延遲工具加載和壓縮的設計基本原理
• 探索上下文視窗：什麼加載到上下文以及何時加載
• 減少令牌使用：超越快取的策略，用於管理上下文大小
• 追蹤和減少成本：Agent SDK 呼叫者的快取令牌追蹤和 TTL 配置
• Prompt caching：基礎 API 機制、中斷點和定價