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

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

所有三个成本数字均以基础输入 token 为单位（token 数量已按其缓存乘数加权）。要将 net_savings 换算为美元，请将其乘以模型每个输入 token 的价格。

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

字段	含义
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

观察。该代理监控 /v1/messages 流量，并将其分组为会话和谱系，一个谱系即一个缓存前缀，由模型 + 工具集 + 系统文本共同键控。第一个携带工具的谱系是主智能体；其余的是子智能体。
检测危险窗口。当主谱系进入空闲状态而某个子智能体正在活跃运行时，主前缀面临过期风险。
预热。在 5 分钟 TTL 内的某个时间间隔，它会将主智能体的最后一个真实请求作为预热请求重放：相同的可缓存前缀，但 max_tokens 设为 1 且不启用流式传输。这单个 token 会被丢弃；关键在于预填充，它会读取并刷新完整的缓存前缀。预热请求直接发送至 API，从不经过代理，因此不会干扰真实流量。
结果。当子智能体完成时，主智能体的缓存仍然处于预热状态。它只需支付一次廉价的读取成本，而非一次完整的重写。

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

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

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

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

使用方法

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

工作原理

dollars saved ≈ net_savings × (input token price)

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

就这样。预热操作会在后台自动运行。如果想在单次运行中禁用它，又不想更改命令，可以设置 `CLAUDE_WARMER_DISABLE=1`。

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

参数	默认值	含义
–idle	270	主智能体必须空闲的秒数，之后才会触发预热
–interval	270	预热周期之间的间隔秒数
–max-cycles	4	每次空闲时段的最大预热次数（设为 auto 表示无限制）
–subagent-window	540	子智能体被视为“仍处于活跃状态”的秒数

每个会话写入以下内容：

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

每次预热消耗一次缓存读取（0.1 倍成本）；而每次它所避免的重写，本需在更大的前缀上支付一次写入成本（1.25 倍），因此这种权衡对你极为有利。

事件日志与节省

别再为重建 Claude Code 缓存付费了。当你的主智能体等待子智能体超过 5 分钟时，它的提示词缓存会悄然过期，下一轮交互就会以写入费率重新编码你的整个对话历史，而不是以低价读取缓存。在涉及多个子智能体的长会话中，这大约会占到你账单的 20%。claude-thermos 能让缓存保持活跃，让你永远不必支付这笔额外费用。

调优参数（均为可选）：

需要 Python 3.11+ 以及 PATH 环境变量中的 claude CLI。