Claude 的 message thread 只有几分钟,长会话还得自己保存
Messages API 新增的 thread 能省去重复上传历史,但它会过期、受固定字段约束,也不自动开启缓存。用两轮请求说明创建、续接与 404 后的重建。

一个 Agent 连续调用几十次工具,每轮都把之前的消息重新上传,会重复传输和处理大量相同内容。Claude 在 11 月 2 日推出 beta 的 message threads,让后续请求只发新消息,再引用上一条响应的 ID。
但这份服务端会话只是短期便利:最后一次请求后闲置 5 分钟会过期,最迟在最后一次使用后 1 小时内删除。 应用仍需自己保存完整历史,才能在进程重启、thread 丢失或需要改配置时继续工作。
本文于 2026 年 11 月 16 日核对当前官方文档。下文针对官方 Claude API,beta header 是 message-threads-2026-08-12;它也不同于 Managed Agents 的 session threads。请求样例只做离线语法检查,没有用真实账号执行或验证第三方渠道支持。
创建时给全量,续接时只给新增
第一次请求仍然包含完整的 messages、system 和 tools,额外加上:
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"system": "Use only the public demo policy supplied by the user.",
"messages": [
{"role": "user", "content": "Demo policy: unopened items can be returned within 7 days. Summarize it."}
],
"thread": {"type": "create"}
}
把它作为请求体发往官方 POST https://api.anthropic.com/v1/messages,使用自己的官方凭据与所需版本头,并加上上述 beta header。拿到完整响应后,把原请求与完整 assistant content 保存下来。第二轮只发送新增内容:
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Does that demo policy mention customized items?"}
],
"thread": {
"type": "continue",
"previous_message_id": "REPLACE_WITH_PREVIOUS_RESPONSE_ID"
}
}
演示政策没有提定制商品,预期应说明资料不足;本文没有实际取得该回答。每轮改用最新响应 ID,不能反复引用最初那条。continue 也不能再次夹带上一轮 assistant 响应,它已在服务端历史里。
这减少了上传内容,不代表模型只看新消息。API 会重建完整会话再调用模型;它也不会自动启用 prompt caching。线程复用和缓存分别配置,缓存概念可参照输入缓存与费用说明,具体 Claude 参数仍以本篇官方来源为准。
什么可以改,什么要重开
续接时,system 和 tools 必须省略,连传 null 都会报错。model、thinking、tool_choice、output_config 等属于固定字段,要保持创建时的值;beta header 的集合也属于固定部分。max_tokens、stream 等字段则可以变化。
| 想做的事 | 当前规则 |
|---|---|
| 继续用户提问或回传工具结果 | 只追加新增消息,使用最新响应 ID |
| 调整输出上限或流式开关 | 可以在后续请求调整 |
| 更换模型、初始指令或工具定义 | 用本地全量历史创建新 thread |
| 回到早先一轮分支 | 创建新 thread,不能让同一个响应 ID 续接两次 |
固定字段改变会出现 thread_fingerprint_mismatch。同一个响应 ID 只能续接一次,因此同一 thread 的调用要按顺序执行。若业务需要分支,让每个分支持有自己的历史与新 thread。
修改 system、tools 再重建时,还要处理旧 thinking 的前缀约束,不能只更换 thread ID。Fable 思考块的历史绑定解释了为什么改过的历史可能仍然报 400。
遇到 404,先确认是 thread 丢了
模型不存在也可能返回 404。先检查 error.details.error_code 是否为 thread_not_found,不要把所有 404 都送进“重建历史”的循环。
确认后,用本地副本恢复完整会话,带上原来的 system 与 tools,再发一次 thread.type: create。完整副本包含已经收到的 assistant 内容与工具结果,不需要重新执行已经完成的工具。重建成功后改用新响应 ID。
过期只是原因之一。API 可能没有存下某轮,上一轮仍在生成,或请求身份与工作空间发生了变化;错误本身不会告诉你是哪一种。官方 SDK helper 会在这类 404 后尝试一次全量重建,但它保存的历史只存在 helper 对象内存中,不会替应用持久化。
业务工具还需要独立记录完成状态。模型会话恢复不等于订单、消息或文件写入可以重做,有副作用的工作流恢复给出了这层区分。
收到响应 ID,还不能马上发下一轮
流式响应会在 message_start 中给出 ID,必须等到 message_stop 才从它续接。提前续接可能得到 404。一次正常响应也不保证它已被服务端保存;应用是在下一次续接时才知道能否复用。
最小验收可以分别覆盖:正常两轮、闲置过期后的重建、进程重启后的恢复、固定字段改变、流中断以及已执行工具不重复。只用公开测试数据;敏感正文和可用凭据不进入求助日志。
thread 内容保存在加密内存中、不写入持久存储,但该功能仍标记为不符合 ZDR 资格,不要把“短期内存”直接当作零保留承诺。通过 Nbility 接入时,先按Claude 原生兼容说明确认渠道能处理 thread、beta header 和续接语义;本文未验证该能力,已有 Messages 调用可用不足以证明 threads 可用。同一批发布里还有一条更容易被忽略的变化:受支持的模型会给输出加文字水印,thread 里保存的内容同样由模型生成。


