Messages上下文管理

上下文編輯

隨著對話上下文增長，使用上下文編輯自動管理對話內容。

此功能符合「Zero Data Retention」（零資料保留），即 ZDR 的資格。當您的組織具有 ZDR 安排時，透過此功能傳送的資料在 API 回應返回後不會被儲存。

概述

對於大多數使用情境，伺服器端壓縮是管理長時間對話上下文的主要策略。本頁面介紹的策略適用於需要更精細控制清除哪些內容的特定場景。

「Context editing」（上下文編輯）讓您能夠在對話歷史增長時選擇性地清除特定內容。除了優化成本和保持在限制範圍內之外，這更是關於主動策劃 Claude 所看到的內容：上下文是一種報酬遞減的有限資源，不相關的內容會降低模型的專注度。上下文編輯讓您能在執行時對這種策劃進行精細控制。關於上下文管理背後更廣泛的原則，請參閱 Effective context engineering。本頁面涵蓋：

工具結果清除 — 最適合大量使用工具的代理式工作流程，其中舊的工具結果已不再需要
思考區塊清除 — 用於在使用擴展思考時管理思考區塊，並提供保留近期思考以維持上下文連續性的選項
用戶端 SDK 壓縮 — 一種基於 SDK 的摘要式上下文管理替代方案（通常建議優先使用伺服器端壓縮）

方法	執行位置	策略	運作方式
伺服器端	API	工具結果清除（`clear_tool_uses_20250919`）思考區塊清除（`clear_thinking_20251015`）	在提示到達 Claude 之前套用。從對話歷史中清除特定內容。每個策略可以獨立設定。
用戶端	SDK	壓縮	在使用 `tool_runner` 時，可於 Python、TypeScript 和 Ruby SDK 中使用。生成摘要並取代完整的對話歷史。請參閱用戶端壓縮。

伺服器端策略

上下文編輯目前處於測試階段，支援工具結果清除和思考區塊清除。若要啟用此功能，請在您的 API 請求中使用測試版標頭 context-management-2025-06-27。

請透過意見回饋表單分享您對此功能的意見。

工具結果清除

clear_tool_uses_20250919 策略會在對話上下文增長超過您設定的閾值時清除工具結果。這對於大量使用工具的代理式工作流程特別有用。一旦 Claude 處理完舊的工具結果（例如檔案內容或搜尋結果），這些結果就不再需要了。

啟動後，API 會自動按時間順序清除最舊的工具結果。API 會用預留位置文字取代每個被清除的結果，讓 Claude 知道該結果已被移除。預設情況下，只會清除工具結果。您可以選擇將 clear_tool_inputs 設為 true，同時清除工具結果和工具呼叫（即工具使用參數）。

思考區塊清除

clear_thinking_20251015 策略用於在啟用擴展思考時管理對話中的 thinking 區塊。此策略讓您能控制思考內容的保留方式：您可以選擇保留更多思考區塊以維持推理連續性，或更積極地清除它們以節省上下文空間。

預設行為： 預設值因模型類別而異。

模型類別	保留所有先前的思考	僅保留最後一輪的思考
Opus	Claude Opus 4.5 及更新版本	Claude Opus 4.1（已棄用）及更早版本
Sonnet	Claude Sonnet 4.6 及更新版本	Claude Sonnet 4.5 及更早版本
Haiku	（無）	截至 Claude Haiku 4.5 的所有模型

使用此策略可覆寫預設值。如果您的程式碼會在多個模型層級上執行，請明確設定 keep，而不要依賴各模型的預設值。

一個助理對話回合可能包含多個內容區塊（例如使用工具時）和多個思考區塊（例如使用交錯思考時）。

上下文編輯在伺服器端進行

上下文編輯會在提示到達 Claude 之前於伺服器端套用。您的用戶端應用程式會維護完整、未修改的對話歷史。您不需要將用戶端狀態與編輯後的版本同步。請繼續像平常一樣在本機管理您的完整對話歷史。

上下文編輯與提示快取

上下文編輯與提示快取的互動方式因策略而異：

工具結果清除：當內容被清除時，會使快取的提示前綴失效。為了因應這一點，請清除足夠的 token 數量，使快取失效變得值得。使用 clear_at_least 參數可確保每次至少清除最低數量的 token。每次清除內容時，您都會產生快取寫入成本，但後續請求可以重複使用新快取的前綴。
思考區塊清除：當思考區塊被保留在上下文中（未被清除）時，提示快取會被保留，從而實現快取命中並降低輸入 token 成本。當思考區塊被清除時，快取會在清除發生的位置失效。請根據您想優先考慮快取效能還是上下文視窗可用空間來設定 keep 參數。

支援的模型

上下文編輯可在所有支援的 Claude 模型上使用。

工具結果清除的使用方式

啟用工具結果清除最簡單的方式是僅指定策略類型。所有其他設定選項都會使用其預設值：

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Search for recent developments in AI"}],
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

進階設定

您可以使用額外的參數自訂工具結果清除行為：

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Create a simple command line calculator app using Python",
        }
    ],
    tools=[
        {
            "type": "text_editor_20250728",
            "name": "str_replace_based_edit_tool",
            "max_characters": 10000,
        },
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                # 超過閾值時觸發清除
                "trigger": {"type": "input_tokens", "value": 30000},
                # 清除後要保留的工具使用次數
                "keep": {"type": "tool_uses", "value": 3},
                # 選用：至少清除這麼多 token
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # 排除這些工具不被清除
                "exclude_tools": ["web_search"],
            }
        ]
    },
)

思考區塊清除的使用方式

啟用思考區塊清除，以便在啟用擴展思考時有效管理上下文和提示快取：

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    thinking={"type": "adaptive"},
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            }
        ]
    },
)

思考區塊清除的設定選項

clear_thinking_20251015 策略支援以下設定：

設定選項	預設值	說明
`keep`	依模型而定	定義要保留多少個最近含有思考區塊的助理回合。使用 `{type: "thinking_turns", value: N}`（其中 N 必須 > 0）來保留最後 N 個回合，或使用 `"all"` 來保留所有思考區塊。Opus 4.5+ 和 Sonnet 4.6+：所有回合。較早的 Opus/Sonnet 和所有 Haiku：僅最後一個回合。

設定範例：

保留最後 3 個助理回合的思考區塊：

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    thinking={"type": "adaptive"},
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 3},
            }
        ]
    },
)

保留所有思考區塊（最大化快取命中率）：

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    thinking={"type": "adaptive"},
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": "all",
            }
        ]
    },
)

組合策略

您可以同時使用思考區塊清除和工具結果清除：

使用多個策略時，clear_thinking_20251015 策略必須列在 edits 陣列的第一位。

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[
        {
            "role": "user",
            "content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
        }
    ],
    thinking={"type": "adaptive"},
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5,
        }
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            },
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 50000},
                "keep": {"type": "tool_uses", "value": 5},
            },
        ]
    },
)

print(response)

工具結果清除的設定選項

設定選項	預設值	說明
`trigger`	100,000 個輸入 token	定義上下文編輯策略何時啟動。一旦提示超過此閾值，就會開始清除。您可以用 `input_tokens` 或 `tool_uses` 來指定此值。
`keep`	3 個工具使用	定義清除發生後要保留多少個最近的工具使用/結果配對。API 會先移除最舊的工具互動，保留最近的互動。
`clear_at_least`	無	確保每次策略啟動時至少清除最低數量的 token。如果 API 無法清除至少指定的數量，則不會套用該策略。這有助於判斷上下文清除是否值得破壞您的提示快取。
`exclude_tools`	無	其工具使用和結果永遠不應被清除的工具名稱清單。適用於保留重要的上下文。
`clear_tool_inputs`	`false`	控制是否將工具呼叫參數與工具結果一起清除。預設情況下，只會清除工具結果，同時保持 Claude 原始的工具呼叫可見。

上下文編輯回應

您可以使用 context_management 回應欄位查看哪些上下文編輯已套用到您的請求，以及有關已清除內容和輸入 token 的實用統計資料。

Output

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // When using `clear_thinking_20251015`
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // When using `clear_tool_uses_20250919`
      {
        "type": "clear_tool_uses_20250919",
        "cleared_tool_uses": 8,
        "cleared_input_tokens": 50000
      }
    ]
  }
}

對於串流回應，上下文編輯會包含在最後的 message_delta 事件中：

Streaming Response

{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "stop_sequence": null
  },
  "usage": {
    "output_tokens": 1024
  },
  "context_management": {
    "applied_edits": [
      // ...
    ]
  }
}

Token 計數

Token 計數端點支援上下文管理，讓您能預覽套用上下文編輯後您的提示將使用多少 token。

response = client.beta.messages.count_tokens(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 5},
            }
        ]
    },
)

print(f"Original tokens: {response.context_management.original_input_tokens}")
print(f"After clearing: {response.input_tokens}")
print(
    f"Savings: {response.context_management.original_input_tokens - response.input_tokens} tokens"
)

Output

{
  "input_tokens": 25000,
  "context_management": {
    "original_input_tokens": 70000
  }
}

回應會同時顯示套用上下文管理後的最終 token 數（input_tokens）以及任何清除發生前的原始 token 數（original_input_tokens）。

與記憶工具搭配使用

上下文編輯可以與記憶工具結合使用。當您的對話上下文接近設定的清除閾值時，Claude 會收到自動警告以保留重要資訊。這使 Claude 能夠在工具結果或上下文從對話歷史中被清除之前，將其儲存到記憶檔案中。

這種組合讓您能夠：

保留重要上下文： Claude 可以在工具結果被清除之前，將其中的重要資訊寫入記憶檔案
維持長時間執行的工作流程： 透過將資訊卸載到持久性儲存，實現原本會超出上下文限制的代理式工作流程
按需存取資訊： Claude 可以在需要時從記憶檔案中查詢先前被清除的資訊，而不必將所有內容都保留在作用中的上下文視窗內

例如，在 Claude 執行許多操作的檔案編輯工作流程中，隨著上下文增長，Claude 可以將已完成的變更摘要寫入記憶檔案。當工具結果被清除時，Claude 仍可透過其記憶系統存取該資訊，並繼續有效地工作。

若要同時使用這兩個功能，請在您的 API 請求中啟用它們：

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Hello"}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

如需完整的記憶工具參考資料（包括指令和範例），請參閱記憶工具。

用戶端壓縮（SDK）

Anthropic 建議使用伺服器端壓縮而非 SDK 壓縮。 伺服器端壓縮會自動處理上下文管理，整合複雜度更低、token 使用量計算更準確，且沒有用戶端的限制。僅當您特別需要在用戶端控制摘要生成過程時，才使用 SDK 壓縮。

compaction_control 參數在 Python、TypeScript 和 Ruby SDK 中已被棄用，並將在未來版本中移除。啟用此參數時，SDK 會發出棄用警告。若要搭配 tool runner 使用伺服器端壓縮，請在請求的 context_management 參數中傳遞 compact_20260112 編輯。

壓縮功能在使用 tool_runner 方法時，可於 Python、TypeScript 和 Ruby SDK 中使用。

「Compaction」（壓縮）是一項 SDK 功能，當 token 使用量增長過大時，會透過生成摘要來自動管理對話上下文。與清除內容的伺服器端上下文編輯策略不同，壓縮會指示 Claude 對對話歷史進行摘要，然後用該摘要取代完整的歷史記錄。這讓 Claude 能夠繼續處理原本會超出上下文視窗的長時間執行任務。

壓縮的運作方式

啟用壓縮後，SDK 會在每次模型回應後監控 token 使用量：

閾值檢查： SDK 將總 token 數計算為 input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens。
摘要生成： 當超過閾值時，會以使用者回合的形式注入摘要提示，Claude 會生成一個包裹在 <summary></summary> 標籤中的結構化摘要。
上下文取代： SDK 會擷取該摘要並用它取代整個訊息歷史。
繼續執行： 對話從摘要處繼續，Claude 會從中斷的地方接續進行。

使用壓縮

在您的 tool_runner 呼叫中加入 compaction_control，以便在 token 使用量超過閾值時啟用自動摘要。

壓縮期間發生的情況

隨著對話增長，訊息歷史會不斷累積：

壓縮前（接近 100k token）：

[
  { "role": "user", "content": "Analyze all files and write a report..." },
  { "role": "assistant", "content": "I'll help. Let me start by reading..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "Based on file1.txt, I see..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "After analyzing file2.txt..." }
  // ... 50 more exchanges like this ...
]

當 token 超過閾值時，SDK 會注入摘要請求，Claude 會生成摘要。然後整個歷史記錄會被取代：

壓縮後（回到約 2–3k token）：

[
  {
    "role": "assistant",
    "content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
  }
]

Claude 會從此摘要繼續工作，就像它是原始的對話歷史一樣。

設定選項

參數	類型	必填	預設值	說明
`enabled`	boolean	是	-	是否啟用自動壓縮
`context_token_threshold`	number	否	100,000	觸發壓縮的 token 數量
`model`	string	否	與主模型相同	用於生成摘要的模型
`summary_prompt`	string	否	請參閱預設摘要提示	用於生成摘要的自訂提示

選擇 token 閾值

閾值決定壓縮何時發生。較低的閾值意味著更頻繁的壓縮和較小的上下文視窗。較高的閾值允許更多上下文，但有達到限制的風險。

使用不同的模型生成摘要

您可以使用更快或更便宜的模型來生成摘要：

自訂摘要提示

您可以針對特定領域的需求提供自訂提示。您的提示應指示 Claude 將其摘要包裹在 <summary></summary> 標籤中。

預設摘要提示

內建的摘要提示會指示 Claude 建立結構化的接續摘要，包括：

任務概述： 使用者的核心請求、成功標準和限制條件。
目前狀態： 已完成的內容、已修改的檔案和已產生的成果。
重要發現： 技術限制、已做出的決策、已解決的錯誤和失敗的方法。
後續步驟： 需要執行的具體動作、阻礙因素和優先順序。
需保留的上下文： 使用者偏好、特定領域的細節和已做出的承諾。

此結構使 Claude 能夠有效率地恢復工作，而不會遺失重要上下文或重複犯錯。

限制

伺服器端工具

使用伺服器端工具（例如網頁搜尋或網頁擷取）時，壓縮需要特別考量。

使用伺服器端工具時，SDK 可能會錯誤計算 token 使用量，導致壓縮在錯誤的時機觸發。

例如，在網頁搜尋操作之後，API 回應可能顯示：

Output

{
  "usage": {
    "input_tokens": 63000,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

SDK 將總使用量計算為 63,000 + 0 + 270,000 + 1,400 = 334,400 個 token。然而，cache_read_input_tokens 的值包含了伺服器端工具進行的多次內部 API 呼叫所累積的讀取量，而非您實際的對話上下文。您實際的上下文長度可能只有 63,000 個 input_tokens，但 SDK 看到的是 334k，因而過早觸發壓縮。

解決方法：

使用 token 計數端點取得準確的上下文長度
大量使用伺服器端工具時避免使用壓縮

工具使用的邊緣情況

當 SDK 在工具使用回應待處理期間觸發壓縮時，它會在生成摘要之前從訊息歷史中移除該工具使用區塊。如果仍然需要，Claude 會在從摘要恢復後重新發出該工具呼叫。

監控壓縮

了解壓縮何時觸發有助於您調整閾值並驗證預期行為。

何時使用壓縮

適合的使用情境：

處理許多檔案或資料來源的長時間執行代理任務
累積大量資訊的研究工作流程
具有明確、可衡量進度的多步驟任務
產生在對話之外持續存在的成果（檔案、報告）的任務

較不理想的使用情境：

需要精確回憶早期對話細節的任務
大量使用伺服器端工具的工作流程
需要在許多變數之間維持精確狀態的任務

後續步驟

壓縮

使用伺服器端壓縮管理長對話，這是大多數使用情境的建議策略。

提示快取

透過快取提示前綴來降低成本和延遲，並了解上下文編輯如何與快取互動。

Was this page helpful?

Messages上下文管理

上下文編輯

隨著對話上下文增長，使用上下文編輯自動管理對話內容。

此功能符合「Zero Data Retention」（零資料保留），即 ZDR 的資格。當您的組織具有 ZDR 安排時，透過此功能傳送的資料在 API 回應返回後不會被儲存。

概述

對於大多數使用情境，伺服器端壓縮是管理長時間對話上下文的主要策略。本頁面介紹的策略適用於需要更精細控制清除哪些內容的特定場景。

工具結果清除 — 最適合大量使用工具的代理式工作流程，其中舊的工具結果已不再需要
思考區塊清除 — 用於在使用擴展思考時管理思考區塊，並提供保留近期思考以維持上下文連續性的選項
用戶端 SDK 壓縮 — 一種基於 SDK 的摘要式上下文管理替代方案（通常建議優先使用伺服器端壓縮）

方法	執行位置	策略	運作方式
伺服器端	API	工具結果清除（`clear_tool_uses_20250919`）思考區塊清除（`clear_thinking_20251015`）	在提示到達 Claude 之前套用。從對話歷史中清除特定內容。每個策略可以獨立設定。
用戶端	SDK	壓縮	在使用 `tool_runner` 時，可於 Python、TypeScript 和 Ruby SDK 中使用。生成摘要並取代完整的對話歷史。請參閱用戶端壓縮。

伺服器端策略

上下文編輯目前處於測試階段，支援工具結果清除和思考區塊清除。若要啟用此功能，請在您的 API 請求中使用測試版標頭 context-management-2025-06-27。

請透過意見回饋表單分享您對此功能的意見。

工具結果清除

思考區塊清除

預設行為： 預設值因模型類別而異。

模型類別	保留所有先前的思考	僅保留最後一輪的思考
Opus	Claude Opus 4.5 及更新版本	Claude Opus 4.1（已棄用）及更早版本
Sonnet	Claude Sonnet 4.6 及更新版本	Claude Sonnet 4.5 及更早版本
Haiku	（無）	截至 Claude Haiku 4.5 的所有模型

使用此策略可覆寫預設值。如果您的程式碼會在多個模型層級上執行，請明確設定 keep，而不要依賴各模型的預設值。

一個助理對話回合可能包含多個內容區塊（例如使用工具時）和多個思考區塊（例如使用交錯思考時）。

上下文編輯在伺服器端進行

上下文編輯與提示快取

上下文編輯與提示快取的互動方式因策略而異：

工具結果清除：當內容被清除時，會使快取的提示前綴失效。為了因應這一點，請清除足夠的 token 數量，使快取失效變得值得。使用 clear_at_least 參數可確保每次至少清除最低數量的 token。每次清除內容時，您都會產生快取寫入成本，但後續請求可以重複使用新快取的前綴。
思考區塊清除：當思考區塊被保留在上下文中（未被清除）時，提示快取會被保留，從而實現快取命中並降低輸入 token 成本。當思考區塊被清除時，快取會在清除發生的位置失效。請根據您想優先考慮快取效能還是上下文視窗可用空間來設定 keep 參數。

支援的模型

上下文編輯可在所有支援的 Claude 模型上使用。

工具結果清除的使用方式

啟用工具結果清除最簡單的方式是僅指定策略類型。所有其他設定選項都會使用其預設值：

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Search for recent developments in AI"}],
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

進階設定

您可以使用額外的參數自訂工具結果清除行為：

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Create a simple command line calculator app using Python",
        }
    ],
    tools=[
        {
            "type": "text_editor_20250728",
            "name": "str_replace_based_edit_tool",
            "max_characters": 10000,
        },
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                # 超過閾值時觸發清除
                "trigger": {"type": "input_tokens", "value": 30000},
                # 清除後要保留的工具使用次數
                "keep": {"type": "tool_uses", "value": 3},
                # 選用：至少清除這麼多 token
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # 排除這些工具不被清除
                "exclude_tools": ["web_search"],
            }
        ]
    },
)

思考區塊清除的使用方式

啟用思考區塊清除，以便在啟用擴展思考時有效管理上下文和提示快取：

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    thinking={"type": "adaptive"},
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            }
        ]
    },
)

思考區塊清除的設定選項

clear_thinking_20251015 策略支援以下設定：

設定選項	預設值	說明
`keep`	依模型而定	定義要保留多少個最近含有思考區塊的助理回合。使用 `{type: "thinking_turns", value: N}`（其中 N 必須 > 0）來保留最後 N 個回合，或使用 `"all"` 來保留所有思考區塊。Opus 4.5+ 和 Sonnet 4.6+：所有回合。較早的 Opus/Sonnet 和所有 Haiku：僅最後一個回合。

設定範例：

保留最後 3 個助理回合的思考區塊：

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    thinking={"type": "adaptive"},
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 3},
            }
        ]
    },
)

保留所有思考區塊（最大化快取命中率）：

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    thinking={"type": "adaptive"},
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": "all",
            }
        ]
    },
)

組合策略

您可以同時使用思考區塊清除和工具結果清除：

使用多個策略時，clear_thinking_20251015 策略必須列在 edits 陣列的第一位。

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[
        {
            "role": "user",
            "content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
        }
    ],
    thinking={"type": "adaptive"},
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5,
        }
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            },
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 50000},
                "keep": {"type": "tool_uses", "value": 5},
            },
        ]
    },
)

print(response)

工具結果清除的設定選項

設定選項	預設值	說明
`trigger`	100,000 個輸入 token	定義上下文編輯策略何時啟動。一旦提示超過此閾值，就會開始清除。您可以用 `input_tokens` 或 `tool_uses` 來指定此值。
`keep`	3 個工具使用	定義清除發生後要保留多少個最近的工具使用/結果配對。API 會先移除最舊的工具互動，保留最近的互動。
`clear_at_least`	無	確保每次策略啟動時至少清除最低數量的 token。如果 API 無法清除至少指定的數量，則不會套用該策略。這有助於判斷上下文清除是否值得破壞您的提示快取。
`exclude_tools`	無	其工具使用和結果永遠不應被清除的工具名稱清單。適用於保留重要的上下文。
`clear_tool_inputs`	`false`	控制是否將工具呼叫參數與工具結果一起清除。預設情況下，只會清除工具結果，同時保持 Claude 原始的工具呼叫可見。

上下文編輯回應

您可以使用 context_management 回應欄位查看哪些上下文編輯已套用到您的請求，以及有關已清除內容和輸入 token 的實用統計資料。

Output

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // When using `clear_thinking_20251015`
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // When using `clear_tool_uses_20250919`
      {
        "type": "clear_tool_uses_20250919",
        "cleared_tool_uses": 8,
        "cleared_input_tokens": 50000
      }
    ]
  }
}

對於串流回應，上下文編輯會包含在最後的 message_delta 事件中：

Streaming Response

{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "stop_sequence": null
  },
  "usage": {
    "output_tokens": 1024
  },
  "context_management": {
    "applied_edits": [
      // ...
    ]
  }
}

Token 計數

Token 計數端點支援上下文管理，讓您能預覽套用上下文編輯後您的提示將使用多少 token。

response = client.beta.messages.count_tokens(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 5},
            }
        ]
    },
)

print(f"Original tokens: {response.context_management.original_input_tokens}")
print(f"After clearing: {response.input_tokens}")
print(
    f"Savings: {response.context_management.original_input_tokens - response.input_tokens} tokens"
)

Output

{
  "input_tokens": 25000,
  "context_management": {
    "original_input_tokens": 70000
  }
}

回應會同時顯示套用上下文管理後的最終 token 數（input_tokens）以及任何清除發生前的原始 token 數（original_input_tokens）。

與記憶工具搭配使用

這種組合讓您能夠：

保留重要上下文： Claude 可以在工具結果被清除之前，將其中的重要資訊寫入記憶檔案
維持長時間執行的工作流程： 透過將資訊卸載到持久性儲存，實現原本會超出上下文限制的代理式工作流程
按需存取資訊： Claude 可以在需要時從記憶檔案中查詢先前被清除的資訊，而不必將所有內容都保留在作用中的上下文視窗內

若要同時使用這兩個功能，請在您的 API 請求中啟用它們：

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Hello"}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

如需完整的記憶工具參考資料（包括指令和範例），請參閱記憶工具。

用戶端壓縮（SDK）

壓縮功能在使用 tool_runner 方法時，可於 Python、TypeScript 和 Ruby SDK 中使用。

壓縮的運作方式

啟用壓縮後，SDK 會在每次模型回應後監控 token 使用量：

閾值檢查： SDK 將總 token 數計算為 input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens。
摘要生成： 當超過閾值時，會以使用者回合的形式注入摘要提示，Claude 會生成一個包裹在 <summary></summary> 標籤中的結構化摘要。
上下文取代： SDK 會擷取該摘要並用它取代整個訊息歷史。
繼續執行： 對話從摘要處繼續，Claude 會從中斷的地方接續進行。

使用壓縮

在您的 tool_runner 呼叫中加入 compaction_control，以便在 token 使用量超過閾值時啟用自動摘要。

壓縮期間發生的情況

隨著對話增長，訊息歷史會不斷累積：

壓縮前（接近 100k token）：

[
  { "role": "user", "content": "Analyze all files and write a report..." },
  { "role": "assistant", "content": "I'll help. Let me start by reading..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "Based on file1.txt, I see..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "After analyzing file2.txt..." }
  // ... 50 more exchanges like this ...
]

當 token 超過閾值時，SDK 會注入摘要請求，Claude 會生成摘要。然後整個歷史記錄會被取代：

壓縮後（回到約 2–3k token）：

[
  {
    "role": "assistant",
    "content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
  }
]

Claude 會從此摘要繼續工作，就像它是原始的對話歷史一樣。

設定選項

參數	類型	必填	預設值	說明
`enabled`	boolean	是	-	是否啟用自動壓縮
`context_token_threshold`	number	否	100,000	觸發壓縮的 token 數量
`model`	string	否	與主模型相同	用於生成摘要的模型
`summary_prompt`	string	否	請參閱預設摘要提示	用於生成摘要的自訂提示

選擇 token 閾值

閾值決定壓縮何時發生。較低的閾值意味著更頻繁的壓縮和較小的上下文視窗。較高的閾值允許更多上下文，但有達到限制的風險。

使用不同的模型生成摘要

您可以使用更快或更便宜的模型來生成摘要：

自訂摘要提示

您可以針對特定領域的需求提供自訂提示。您的提示應指示 Claude 將其摘要包裹在 <summary></summary> 標籤中。

預設摘要提示

內建的摘要提示會指示 Claude 建立結構化的接續摘要，包括：

任務概述： 使用者的核心請求、成功標準和限制條件。
目前狀態： 已完成的內容、已修改的檔案和已產生的成果。
重要發現： 技術限制、已做出的決策、已解決的錯誤和失敗的方法。
後續步驟： 需要執行的具體動作、阻礙因素和優先順序。
需保留的上下文： 使用者偏好、特定領域的細節和已做出的承諾。

此結構使 Claude 能夠有效率地恢復工作，而不會遺失重要上下文或重複犯錯。

限制

伺服器端工具

使用伺服器端工具（例如網頁搜尋或網頁擷取）時，壓縮需要特別考量。

使用伺服器端工具時，SDK 可能會錯誤計算 token 使用量，導致壓縮在錯誤的時機觸發。

例如，在網頁搜尋操作之後，API 回應可能顯示：

Output

{
  "usage": {
    "input_tokens": 63000,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

解決方法：

使用 token 計數端點取得準確的上下文長度
大量使用伺服器端工具時避免使用壓縮

工具使用的邊緣情況

監控壓縮

了解壓縮何時觸發有助於您調整閾值並驗證預期行為。

何時使用壓縮

適合的使用情境：

處理許多檔案或資料來源的長時間執行代理任務
累積大量資訊的研究工作流程
具有明確、可衡量進度的多步驟任務
產生在對話之外持續存在的成果（檔案、報告）的任務

較不理想的使用情境：

需要精確回憶早期對話細節的任務
大量使用伺服器端工具的工作流程
需要在許多變數之間維持精確狀態的任務

後續步驟

壓縮

使用伺服器端壓縮管理長對話，這是大多數使用情境的建議策略。

提示快取

透過快取提示前綴來降低成本和延遲，並了解上下文編輯如何與快取互動。

Was this page helpful?

概述

伺服器端策略

工具結果清除

思考區塊清除

上下文編輯在伺服器端進行

上下文編輯與提示快取

支援的模型

工具結果清除的使用方式

進階設定

思考區塊清除的使用方式

思考區塊清除的設定選項

組合策略

工具結果清除的設定選項

上下文編輯回應

Token 計數

與記憶工具搭配使用

用戶端壓縮（SDK）

壓縮的運作方式

使用壓縮

壓縮期間發生的情況

設定選項

選擇 token 閾值

使用不同的模型生成摘要

自訂摘要提示

預設摘要提示

檢視完整的預設提示

限制

伺服器端工具

工具使用的邊緣情況

監控壓縮

何時使用壓縮

後續步驟

概述

伺服器端策略

工具結果清除

思考區塊清除

上下文編輯在伺服器端進行

上下文編輯與提示快取

支援的模型

工具結果清除的使用方式

進階設定

思考區塊清除的使用方式

思考區塊清除的設定選項

組合策略

工具結果清除的設定選項

上下文編輯回應

Token 計數

與記憶工具搭配使用

用戶端壓縮（SDK）

壓縮的運作方式

使用壓縮

壓縮期間發生的情況

設定選項

選擇 token 閾值

使用不同的模型生成摘要

自訂摘要提示

預設摘要提示

檢視完整的預設提示

限制

伺服器端工具

工具使用的邊緣情況

監控壓縮

何時使用壓縮

後續步驟

概述

伺服器端策略

工具結果清除

思考區塊清除

上下文編輯在伺服器端進行

上下文編輯與提示快取

支援的模型

工具結果清除的使用方式

進階設定

思考區塊清除的使用方式

思考區塊清除的設定選項

組合策略

工具結果清除的設定選項

上下文編輯回應

Token 計數

與記憶工具搭配使用

用戶端壓縮（SDK）

壓縮的運作方式

使用壓縮

壓縮期間發生的情況

設定選項

選擇 token 閾值

使用不同的模型生成摘要

自訂摘要提示

預設摘要提示

限制

伺服器端工具

工具使用的邊緣情況

監控壓縮

何時使用壓縮

後續步驟

概述

伺服器端策略

工具結果清除

思考區塊清除

上下文編輯在伺服器端進行

上下文編輯與提示快取

支援的模型

工具結果清除的使用方式

進階設定

思考區塊清除的使用方式

思考區塊清除的設定選項

組合策略

工具結果清除的設定選項

上下文編輯回應

Token 計數

與記憶工具搭配使用

用戶端壓縮（SDK）

壓縮的運作方式

使用壓縮

壓縮期間發生的情況

設定選項

選擇 token 閾值

使用不同的模型生成摘要

自訂摘要提示

預設摘要提示

限制

伺服器端工具

工具使用的邊緣情況

監控壓縮

何時使用壓縮

後續步驟