prompt cache 到底存在哪、活多久？拆解 promptCacheTtl 與它的帳單

補寫於 2026 年 9 月 2 日，發文日期掛回原本該發的那天。文中的版本號與價格以撰寫當日的官方文件為準。

你去泡個咖啡回來，Claude Code 再跑一次同樣的任務，為什麼有時候第一個回應快得像它從沒忘記，有時候又慢得像重新讀了一次整包專案？

中間差的那件事叫 prompt cache，而它活多久，從 8 月底開始是你可以決定的。

先把黑盒打開：快取到底在快取什麼

要理解這個設定，得先接受一件反直覺的事：模型不記得任何東西。

每一次你按下 enter，送出去的不是你剛打的那句話，是整段對話。系統提示、CLAUDE.md、工具定義、之前所有來回、你剛剛貼的那段錯誤訊息，全部重新送一次。模型每一輪都是從零開始讀完這一整疊，然後才吐出第一個 token。

這就是為什麼 context 越長、第一個字越慢。它不是在思考，它是在讀。

prompt cache 做的事，是把「讀完前面這一大疊之後的中間狀態」存起來。下一次如果你送來的前綴一模一樣，那段不用重讀，直接從存好的狀態接下去。所以快取的單位不是「你的問題」，是對話的前綴；也所以只要前綴中間有任何一個位元變了，後面全部作廢，這就是為什麼中途改 CLAUDE.md、中途換掉一個工具名，整條快取會塌掉。

但那是「怎麼弄壞它」。這篇要拆的是另一件事：你沒弄壞它，它自己什麼時候會死。

那個中間狀態存在誰家、放多久

它不在你的機器上。那疊中間狀態放在 API 端，而放著是要成本的，所以它有存活時間。預設是五分鐘。

五分鐘的意思是：你送出一輪、拿到回應、開始看程式碼、想了一下、去回了封信、倒了杯水，回來再送第二輪，這中間只要超過五分鐘，前面那疊就已經被清掉了。下一輪從冷的開始，整包 context 重讀一次。

用置物櫃想這件事最清楚。五分鐘制是投一次幣、走開太久東西就被清掉，回來得重新整理一遍。一小時制是投幣的時候就貴一點，但你中午吃飯回來東西還在。判準從來不是哪個貴，是你平均離開多久。

兩個鍵，切的是兩條完全不同的路徑

Claude Code 現在有兩個設定鍵在管這件事，型別都是字串，合法值都是 "5m" 或 "1h"。

promptCacheTtl 管的是主對話。官方 settings reference 的原文是「Choose how long the prompt cache holds the main conversation. This key applies to your interactive, -p, and Agent SDK turns, together with the helpers Claude Code runs inline with them.」你在終端機裡打字的那條、-p 一次性跑的那條、Agent SDK 的 turn，加上跟它們同一條路徑上跑的 helper，都吃這個鍵。

subagentPromptCacheTtl 管的是主對話以外的請求。原文：「…holds the requests Claude Code makes outside the main conversation. This key applies to subagents, workflows, and Claude Code’s own background and helper requests, such as compaction and session titles.」subagent、workflow、還有 Claude Code 自己在背景跑的東西，壓縮、session 標題那些，全部走這條。

為什麼要拆兩個？把兩條路徑的行為攤開來看就很明顯了。

主對話是你在用，節奏由人決定，中間充滿了看程式碼、回訊息、開會這種空檔。subagent 不是，它被派出去之後一路跑到底，中間沒有人類在思考，前後兩次請求之間的間隔是機器的間隔。你要一個為人的節奏調的存活時間，跟一個為機器節奏調的存活時間，本來就不該是同一個數字。

所以最實用的組合是主對話 1h、subagent 5m，這也正是 CHANGELOG 描述的使用情境。

一小時不是免費的，貴的地方在寫入

快取有兩種收費動作：寫進去（cache write）和讀出來（cache read）。文件明講的是 API 對每一次 cache write 收取比五分鐘制更高的費率（bills each cache write at a higher rate than at the five-minute lifetime）。貴的是寫，不是讀，也不是「放著」。

我得在這裡誠實停一下：具體貴多少倍，我沒有查證到數字。素材只給到「文件說較貴」這個方向，我沒有去 pricing 頁把倍數抓下來核對，所以這篇不給倍數，也不自己推估一個。要拿去算成本的話，請自己開官方的 prompt caching 定價頁對一次。

不過即使沒有那個倍數，判準的形狀已經很清楚了。既然貴的是寫入、而每一輪對話都會寫入，那麼一小時制划不划算就完全取決於一件事：你的空檔有多常超過五分鐘。

空檔常常超過五分鐘，一小時制讓你少掉大量的冷啟動重讀，多付的寫入費有東西可換。空檔很少超過五分鐘，你只是在為一個從來不會用到的續命時間付錢，每一輪都付。

這也是為什麼 subagent 那條建議留在 5m。一個被派出去連續跑的 subagent，請求之間根本沒有人在發呆，一小時的存活時間對它沒有意義，但寫入的加價它一次都不會少付。

第三層：藏在 experimental 底下的 per-agent 設定

上面兩個鍵是 settings 層級的。還有第三個地方可以設。

subagent 的 frontmatter 裡可以放 cacheTtl，值一樣是 5m 或 1h。它只從 subagent 檔案讀這個欄位，放在別的地方沒用；填了合法值以外的東西不會報錯，就是被忽略；而且它必須寫在 experimental 這個 map 裡面，不是頂層。最後這條文件特地補了一句提醒（Write cacheTtl inside the experimental map, not at the top level），會被特地寫進文件的提醒，通常代表很多人踩過。

還有一條更容易讓人困惑的：當你的 Claude 訂閱正在使用 usage credits 時，1h 會被忽略。文件原文是 ignores 1h while your Claude subscription is using usage credits。這條一定要知道，不然你設了 1h、觀察不到任何差別，會以為是自己設錯位置，然後開始亂改。

三層攤平放在一起是這樣：

三個的合法值都是 5m 或 1h。

至於這三層的優先順序，CHANGELOG 的說法是 frontmatter 那個是「a per-agent prompt cache TTL used when no subagent TTL setting is configured」，也就是沒設 subagentPromptCacheTtl 的時候才輪到它。這句話我只在 CHANGELOG 看到，沒有跟 settings reference 的正式描述交叉比對過，如果你要靠這個優先序做決策，建議自己回官方文件確認一次。

版本門檻

agent frontmatter 的 experimental.cacheTtl 需要 v2.1.248 或以上，這一版在 npm 上的發布時間是 2026 年 8 月 27 日。

沒有量測就不要調參

2.1.251 這一版（npm 發布時間 2026 年 8 月 28 日）在 /cost 裡加了一行 per-session 的 prompt cache 資訊，內容包含 hit ratio、misses、re-cached tokens，以及 warm/cold。同一版也給 status line 腳本開了一個對應的 prompt_cache 物件，想把它掛在狀態列上隨時看的話，資料在那裡。

先看幾天的 hit ratio 再決定要不要開 1h，比直接照抄別人的設定值有用得多。你的空檔分布是你的，不是別人的。

我沒有實際設過這兩個鍵，沒有跑過 /cost 看那一行快取資訊，也沒有做過開關前後的成本對照。這篇能給你的是這個機制的形狀，不是我的實測數字。

這個形狀在別的地方也長一樣

任何一個「把昂貴的中間狀態存起來，之後可能會用到」的系統，都會撞上同一個三角：存越久命中率越高，存越久成本越高，而你不知道下一次請求什麼時候來。CDN 的 TTL、資料庫的查詢快取、你自己寫的那層 Redis，全部都在這條線上找位置。

而所有這類系統的正確調法都一樣：先量到達間隔的分布，再選存活時間。不是先選一個聽起來合理的數字，然後希望它剛好對。

回到置物櫃。你要決定買五分鐘制還是一小時制之前，唯一該做的事，是先算清楚你平常到底離開多久。