别再为重建 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 美元。