Claude message threads 是什麼，怎麼用

Message threads 是什麼

沒有 thread 時，代理迴圈的每一輪都要重新上傳完整對話，API 也要把這些內容重新驗證、重新分詞。一個程式設計代理在一次工作階段中會送出數百個請求，對話一旦達到數十萬 token，這種重複傳送就會拖慢 Claude 開始回答的時間。有了 thread，API 會在兩輪之間保存對話，大部分工作只需處理新增的這一輪。

• 首個 token 更快：Anthropic 實測，在 50 萬到 100 萬 token 的 Claude Code 請求上，中位耗時下降約 35%。對話越長，效果越明顯。
• 請求更小：每一輪只帶新訊息、工具結果或螢幕截圖。
• token 和價格不變：Claude 每一輪仍會讀完整段對話，定價和速率限制都不變。
• 存活時間短：thread 在最後一次請求 5 分鐘後到期，只保存在記憶體中並加密，不會寫入磁碟。
• 適用範圍：Claude API、AWS 上的 Claude Platform、Google Cloud 上的 Claude Models（由 Anthropic 代管）和 Microsoft Foundry，支援所有模型。

使用 thread 與不使用的差別

如何在自己的代理中使用 message threads

Claude Code 已經替你做好這件事。如果你在 Messages API 上自行打造代理，SDK 的 thread helper 是最短的路徑。

1. 建立 thread helper

   傳入與 Messages 請求相同的欄位。helper 會加上 message-threads-2026-08-12 beta 請求標頭，在第一輪建立 thread，之後只送出新訊息，並把完整對話保存在記憶體裡。

   import anthropic
   
   client = anthropic.Anthropic()
   
   # 建立 helper。這一步不會送出請求。
   thread = client.beta.messages.thread(
       model="claude-opus-5-5",
       max_tokens=1024,
       cache_control={"type": "ephemeral"},
       system="You are a coding agent. Keep replies short.",
   )
   
   # 第 1 輪建立 thread，並送出完整對話
   thread.send({"role": "user", "content": "Read the failing test and explain it."})
   
   # 第 2 輪只送出新訊息
   reply = thread.send({"role": "user", "content": "Now fix it."})

2. 或者自己送出 thread 欄位

   使用 cURL 或一般的 create 呼叫時，在每個請求中加上 thread，並且每次都帶上 beta 請求標頭。一律從最新一次回應的 id 繼續；每個 id 只能繼續一次。

   # 第 1 輪：完整對話，外加
   "thread": {"type": "create"}
   
   # 之後每一輪：只送新訊息，不帶 system 和 tools，外加
   "thread": {"type": "continue", "previous_message_id": "<上一次回應的 id>"}
   
   # thread 的每個請求都要帶
   anthropic-beta: message-threads-2026-08-12

3. 保持模型和設定不變

   system 和 tools 只在第一個請求中送出。model、thinking、tool_choice、頂層的 cache_control 和 beta 請求標頭在每一輪都必須保持一致；一旦更動，會回傳 400 錯誤 thread_fingerprint_mismatch。要更動就另開一個 thread。

4. 自己留一份，遇到 404 就重送

   Thread 只是盡力而為的服務。當 continue 請求回傳 404 和 thread_not_found（thread 已到期、上一輪沒有被保存，或是由備援模型寫入的），請在新的 create 請求中重新送出完整對話。SDK helper 會自動做一次。

5. 開啟 prompt caching

   Thread 不會替你快取 prompt。請在每個請求中送出頂層的 cache_control，讓每一輪都從快取讀取先前的對話；帶 thread 的請求最多只能有 4 個斷點。

來源：Anthropic 的 message threads 文件

限制，以及 thread 不支援什麼

• 不能與 Message Batches、token 計數、依需求壓縮（compaction）或上下文編輯一起使用（keep: "all" 的 clear_thinking_20251015 除外）。
• 啟用 HIPAA readiness 或 Inference hooks 的組織不能使用；這類請求會回傳 400 錯誤 thread_unsupported_request。
• 不符合零資料保留資格：API 把 thread 保存在記憶體中，最後一次使用後最多 1 小時就會刪除。
• 沒有列出、讀取或刪除 thread 的 API，thread 也只能附加。想壓縮的話，用你自己寫的摘要另開一個 thread。
• 遇到拒絕（refusal）後，不要繼續這個 thread：去掉引發拒絕的那一輪，另開一個。
• 同一個 thread 的每個請求都要使用相同的 API key 和 workspace，否則無法繼續。

對 Claude Code 使用者代表什麼

你不需要改任何東西：Anthropic 表示多數 Claude Code 使用者預設已開啟 thread。效益展現在長工作階段中，在很大的對話深處發出一輪時，Claude 會更早開始回答。你的用量不會下降，因為 Claude 每一輪仍會讀完整段對話。

依 API 文件，thread 在最後一次請求 5 分鐘後到期。停頓更久後回到工作階段時，第一個請求會重新送出完整對話，之後的幾輪才會變快。依排程喚醒的主動式 Claude Code 工作階段也是同樣的情況。

讓長時間的 Claude Code 工作階段自己做事

Message threads 讓長工作階段更快，Crewmark 讓它們更主動。它替 Claude Code、Codex、DeepSeek Harness 或 OpenCode 工作階段設定職位、目標和工作時間，並依心跳在同一個對話中喚醒它，所以它能保留上下文，從看板上接手下一個 issue。

1. 把一個工作階段變成員工

   選一個職位，例如軟體工程師或 SEO 專員，把它的目標寫成一個數字，然後在 Claude Code 中執行設定指令。

2. 讓心跳啟動工作

   在工作時間內，員工每 15、30 或 60 分鐘在同一個對話中醒來一次；見如何讓 Claude Code 主動工作。多位員工可以並排執行，如多個 Claude Code 代理。

3. 指派 issue，回覆它的訊息

   把工作放到看板上，員工會接手、邊做邊留言，需要你拍板時傳訊息給你。閱讀什麼是 AI 員工。

Claude message threads 常見問題