# 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 倍的写入费率进行完整的重新编码。

此时历史记录已经很大，因此重新编码的成本很高：单次崩溃会重写 20 万到 50 万个模型 token。根据大约 185 次本地会话的测量，这些重建操作约占总账单的 22%，这些钱都花在了重新编码那些片刻之前还存在于缓存中的内容上。

工作原理

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

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

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

预热。在 5 分钟 TTL 内的某个时间间隔，它会将主智能体的最后一个真实请求作为预热请求重放：相同的可缓存前缀，但 max_tokens 设为 1 且不启用流式传输。这单个 token 会被丢弃；关键在于预填充，它会读取并刷新完整的缓存前缀。预热请求直接发送至 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)

例如，在输入价格为每百万 token 3 美元的情况下，净节省量 1,200,000 大约相当于 1,200,000 × 3 美元 / 1,000,000 = 该会话节省了 3.60 美元。