# Claude-thermos：保持 Claude 会话缓存热度，避免重新编码费用

- 来源：Hacker News 热门（buzzing.cc 中文翻译）
- 作者：s0ck_r4w
- 发布时间：2026-07-24 17:47
- AIHOT 分数：79
- AIHOT 标记：精选
- AIHOT 链接：https://aihot.virxact.com/items/cmryrjtlb04ehrolgi1zd6eqv
- 原文链接：https://github.com/izeigerman/claude-thermos

## 精选理由

一个小工具解决了一个被忽视的成本黑洞，Claude Code 的缓存过期，作者自己测了 185 个会话，省下 22% 费用，对于把 Claude 当开发助手的团队来说是个必装工具。

## AI 摘要

Claude-thermos 通过本地反向代理监控 Claude Code 会话，在主智能体因等待子智能体而空闲超过 5 分钟时，自动发送预热请求刷新提示缓存。实测约 185 次本地会话中，缓存过期导致的重新编码占账单约 22%。工具以 uvx 运行，支持自定义空闲阈值和预热间隔。

## 正文

别再花钱重建你的 Claude Code 缓存了。当你的主智能体等待子智能体超过 5 分钟时，它的提示词缓存会悄然过期，下一轮对话就会以写入费率重新编码你的整个对话，而不是以低价读回。在包含许多子智能体的长会话中，这大约占你账单的 20%。claude-thermos 能让缓存保持温热，让你永远不用付这笔冤枉钱。

使用方法

像平常一样运行 Claude Code，但通过 uvx 使用 claude-thermos：

uvx claude-thermos # instead of: claude uvx claude-thermos -p "fix the bug" # any claude args pass straight through

需要 Python 3.11+ 以及 PATH 中的 claude CLI。

就这么简单。预热会在后台自动运行。如果要在某次运行中禁用它而不改变命令，请设置 CLAUDE_WARMER_DISABLE=1。

调优（全部可选）：

标志 默认值 含义

--idle 270 主智能体在预热启动前必须空闲的秒数

--interval 270 预热周期之间的秒数

--max-cycles 4 每次空闲时段的最大预热次数（设为 auto 表示无限）

--subagent-window 540 子智能体被视为“仍处于活动状态”的秒数

为什么你的缓存会不断过期

Claude Code 的提示词缓存使用 5 分钟 TTL。只要缓存保持存活，每一轮对话的整个历史记录都会以输入价格 0.1 倍的费率从缓存中读取，而不是以全价重新发送。

如果同一前缀的请求之间间隔超过 5 分钟，缓存就会过期。造成这种间隔的主要触发因素不是你在思考，而是主智能体被运行超过 5 分钟的子智能体阻塞。子智能体有不同的系统提示词和工具集，因此它的请求有不同的缓存前缀，永远不会刷新主智能体的缓存。在子智能体工作时，主智能体的缓存历史记录会原封不动地老化；超过 5 分钟就消失了。当子智能体返回时，主智能体以字节相同、仅追加的历史记录恢复运行，却发现缓存丢失，被迫以 1.25 倍的写入费率进行完整重新编码。

到那时历史记录已经很大，所以重新编码代价高昂：单次崩溃会重写 200K 到 500K 个 token。根据大约 185 次本地会话的测量，这些重建约占账单总额的 22%，这些钱花在了重新编码片刻之前就已缓存的内容上。

工作原理

claude-thermos 在本地小型反向代理后面启动 Claude Code（它将 ANTHROPIC_BASE_URL 指向一个回环端口；所有流量仍然流向真实的 Anthropic API）。

观察。代理监控 /v1/messages 流量，并将其分组为会话和谱系（lineage），一个谱系即一个缓存前缀，以模型 + 工具集 + 系统文本为键。第一个携带工具的谱系是主智能体；其余的是子智能体。

检测危险窗口。当主谱系进入空闲状态而子智能体正在运行时，主前缀就有过期风险。

预热。在 5 分钟 TTL 之内的一个时间间隔上，它重放主智能体最后一次真实请求作为预热请求：相同的可缓存前缀，但 max_tokens 设为 1 且不启用流式传输。这单个 token 会被丢弃；关键在于预填充（prefill），它会读取并刷新完整的缓存前缀。预热请求直接发送到 API，绝不经过代理，因此不会干扰真实流量。

结果。当子智能体完成时，主智能体的缓存仍然是热的。它只需支付一次廉价的读取，而不是一次完整的重写。

每次预热花费一次缓存读取（0.1 倍）；它每次阻止的重写原本会在大得多的前缀上花费一次写入（1.25 倍），所以这笔交易对你极为有利。

事件日志与节省

每个会话都会写入：

~/.claude-thermos/logs/<session_id>/ ├── events.jsonl # append-only structured event stream └── summary.json # rollup totals, written when the session ends

events.jsonl 记录每个请求/响应的 token 用量以及每一个预热决策（warm_fired、warm_result、cap_reached、resume_detected 等）。summary.json 是你通常会读取的汇总文件：

字段 含义

warms_fired 已发送的预热请求数

cache_read_total 这些预热请求读回的 token 数

episodes 以成功恢复（即实际避免了重写）告终的空闲-带-子智能体事件数

rewrite_avoided_tokens 原本会被重写的 token 数，跨所有事件求和

warm_cost 预热花费了你多少：0.1 × cache_read_total

rewrite_avoided_cost 它节省了多少：1.25 × rewrite_avoided_tokens

net_savings rewrite_avoided_cost − warm_cost

这三个成本数字均以基础输入 token 单位计（token 数已按其缓存倍数加权）。要把 net_savings 换算成美元，乘以你所用模型每输入 token 的价格即可。

dollars saved ≈ net_savings × (input token price)

例如，在输入价格为 $3 / 1M tokens 的情况下，net_savings 为 1_200_000 时，大约相当于 1_200_000 × $3 / 1_000_000 = 该会话节省了 $3.60。