Claude-thermos：防止 Claude Code 中的 Prompt Cache 過期

Claude-thermos：防止 Claude Code 中的 Prompt Cache 過期

Claude-thermos 透過維持 Prompt Cache 熱度來降低 API 成本

claude-thermos 是一個旨在消除 Claude Code 會話中「快取稅」的工具。當主代理（main agent）被子代理（subagent）阻塞超過五分鐘時，它能防止 Prompt Cache 靜默過期，否則這可能會佔據用戶總 API 帳單的約 20%。

問題所在：子代理執行期間的快取過期

Claude Code 的 Prompt Cache 有 5 分鐘的生存時間（TTL）。雖然快取後的歷史紀錄以 0.1x 的輸入價格提供服務，但快取缺失（cache miss）會迫使對話歷史以 1.25x 的寫入率進行完整的重新編碼。在長對話會話中，這會變得非常昂貴，因為單次崩潰（collapse）可能會重新寫入 200K 到 500K 個 token。

快取過期的主要觸發因素不是用戶閒置，而是子代理的行為。由於子代理使用不同的系統提示詞（system prompts）和工具集，它們會創建不同的快取前綴（cache prefixes）。當子代理正在運行時，主代理的快取前綴保持不變。如果子代理的任務執行時間超過五分鐘，主代理的快取就會過期。當子代理將控制權交還給主代理時，主代理必須重新編碼整個歷史紀錄，導致高昂的成本。

claude-thermos 如何維持快取

claude-thermos 通過將 ANTHROPIC_BASE_URL 指向回環端口（loopback port）來作為本地反向代理運行。它通過四個步驟來管理快取：

  1. 觀察 (Observation)：代理監控 /v1/messages 流量，將請求分組為會話（sessions）和「譜系」（lineages，由模型、工具集和系統文本定義）。它將第一個帶有工具的譜系識別為主代理。
  2. 檢測 (Detection)：它識別出當主譜系處於閒置狀態而子代理正在積極運行時的「危險窗口」。
  3. 加熱 (Warming)：在 5 分鐘的 TTL 過期之前，代理會直接向 Anthropic API 發送一個「加熱請求」。此請求使用完全相同的可快取前綴，但設置 max_tokens: 1 並禁用串流（streaming）。
  4. 刷新 (Refresh)：單個 token 會被捨棄；其目的是預填充（prefill），這會以便宜的讀取率 (0.1x) 刷新完整的快取前綴，從而避免昂貴的重寫 (1.25x)。

安裝與使用

claude-thermos 需要 Python 3.11+，且系統 PATH 中必須安裝 claude CLI。可以使用 uvx 執行：

  • 標準運行：uvx claude-thermos（取代 claude 命令）
  • 帶參數運行：uvx claude-thermos -p "fix the bug"（參數會直接傳遞給 Claude CLI）

配置微調

用戶可以調整以下可選標誌來微調加熱行為：

標誌 預設值 意義
--idle 270 開始加熱前，主代理必須閒置的秒數
--interval 270 意義：加熱週期之間的秒數
--max-cycles 4 每個閒置階段的最大加熱次數 (auto 為無限)
--subagent-window 540 子代理被視為「仍處於活動狀態」的秒數

若要在不更改命令的情況下禁用特定運行的加熱，請設置環境變量 CLAUDE_WARMER_DISABLE=1。

追蹤節省的成本

每個會話都會在 ~/.claude-thermos/logs/<session_id>/ 中生成日誌，包含一個 events.jsonl 串流和一個 summary.json 匯總。summary.json 文件提供以下指標：

  • warms_fired：發送的加熱請求總數。
  • cache_read_total：加熱期間讀取的 token 數量。
  • rewrite_avoided_tokens：如果快取過期，原本會被重新寫入的 token 數量。
  • net_savings：避免重寫的成本 (1.25x) 與加熱成本 (0.1x) 之間的差值，以基礎輸入 token 單位衡量。

要計算實際節省的金額，請將 net_savings 值乘以模型的每個輸入 token 價格。

社群討論與反對意見

社群對該工具的反饋集中在快取 TTL 的爭議以及「加熱」請求的倫理問題上。

快取 TTL 差異

幾位用戶指出，對於 Pro 和 Max 方案，快取過期時間可能是 1 小時而非 5 分鐘。

"我直接檢查了 pro/Max 方案的調用，截至今天它們有 1 小時的快取過期時間... 如果你支付的是 API 費率，你可以自己選擇 5 分鐘或 1 小時。"

如果某些層級的快取 TTL 確實是一小時，那麼 claude-thermos 使用的 5 分鐘加熱間隔對這些特定用戶來說可能是多餘或浪費的。

資源使用與倫理

一些用戶表示擔心自動加熱請求可能會導致「公地悲劇」，在不提供功能性輸出的情況下增加 Anthropic 基礎設施的負擔。

"這只是讓其他人的成本變得更高，對吧？... 我也不會要求自己始終排在隊伍的最前面。"

相反地，其他用戶認為，這個工具迫使供應商解決有缺陷的快取機制，該機制懲罰了那些在需要子代理的代理工作流（agentic workflows）中使用功能的用戶。

Sources