上下文管理

上下文編輯

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

概覽

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

上下文編輯允許您在對話歷史增長時選擇性地清除特定內容。除了優化成本和保持在限制範圍內之外，這還涉及主動管理 Claude 所看到的內容：上下文是一種有限資源，邊際效益遞減，不相關的內容會降低模型的專注度。上下文編輯讓您在運行時對該管理過程擁有精細控制。有關上下文管理背後的更廣泛原則，請參閱有效的上下文工程。本頁面涵蓋：

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

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

伺服器端策略

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

請通過反饋表單分享對此功能的反饋。

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

工具結果清除

clear_tool_uses_20250919 策略在對話上下文超過您配置的閾值時清除工具結果。這對於大量使用工具的代理工作流程特別有用。一旦 Claude 處理了舊的工具結果（如文件內容或搜索結果），就不再需要它們了。

激活後，API 會按時間順序自動清除最舊的工具結果。每個被清除的結果都會被佔位符文本替換，以便 Claude 知道它已被移除。默認情況下，只清除工具結果。您可以通過將 clear_tool_inputs 設置為 true 來選擇同時清除工具結果和工具調用（工具使用參數）。

思考區塊清除

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

默認行為： 當啟用擴展思考但未配置 clear_thinking_20251015 策略時，API 會自動只保留最後一個助手輪次的思考區塊（相當於 keep: {type: "thinking_turns", value: 1}）。

要最大化緩存命中率，請通過設置 keep: "all" 來保留所有思考區塊。

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

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

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

上下文編輯與提示緩存

上下文編輯與提示緩存的交互因策略而異：

工具結果清除：清除內容時會使緩存的提示前綴失效。為了應對這種情況，請清除足夠多的 token 以使緩存失效值得。使用 clear_at_least 參數確保每次清除最少數量的 token。每次清除內容時您都會產生緩存寫入成本，但後續請求可以重用新緩存的前綴。
思考區塊清除：當思考區塊被保留在上下文中（未被清除）時，提示緩存得以保留，從而實現緩存命中並降低輸入 token 成本。當思考區塊被清除時，緩存在清除發生的位置失效。根據您是否希望優先考慮緩存性能或上下文窗口可用性來配置 keep 參數。

支援的模型

上下文編輯可在以下模型上使用：

Claude Opus 4.6 (claude-opus-4-6)
Claude Opus 4.5 (claude-opus-4-5-20251101)
Claude Opus 4.1 (claude-opus-4-1-20250805)
Claude Opus 4 (claude-opus-4-20250514)
Claude Sonnet 4.6 (claude-sonnet-4-6)
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Haiku 4.5 (claude-haiku-4-5-20251001)

工具結果清除使用方法

啟用工具結果清除的最簡單方法是只指定策略類型。所有其他配置選項使用其默認值：

進階配置

您可以使用其他參數自定義工具結果清除行為：

思考區塊清除使用方法

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

思考區塊清除的配置選項

clear_thinking_20251015 策略支援以下配置：

配置選項	默認值	描述
`keep`	`{type: "thinking_turns", value: 1}`	定義要保留多少個最近的含有思考區塊的助手輪次。使用 `{type: "thinking_turns", value: N}`（其中 N 必須 > 0）來保留最後 N 個輪次，或使用 `"all"` 保留所有思考區塊。

配置示例：

保留最後 3 個助手輪次的思考區塊：

{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

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

{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

組合策略

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

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

工具結果清除的配置選項

配置選項	默認值	描述
`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 的有用統計信息。

Response

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // 使用 `clear_thinking_20251015` 時
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // 使用 `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

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

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

與記憶工具配合使用

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

這種組合允許您：

保留重要上下文：Claude 可以在工具結果被清除之前將其中的重要信息寫入記憶文件
維持長期工作流程：通過將信息卸載到持久存儲，啟用否則會超出上下文限制的代理工作流程
按需訪問信息：Claude 可以在需要時從記憶文件中查找之前被清除的信息，而不是將所有內容保留在活躍的上下文窗口中

例如，在 Claude 執行許多操作的文件編輯工作流程中，Claude 可以在上下文增長時將已完成的更改摘要寫入記憶文件。當工具結果被清除時，Claude 通過其記憶系統保留對該信息的訪問，並可以繼續有效工作。

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

客戶端壓縮（SDK）

建議使用伺服器端壓縮而非 SDK 壓縮。 伺服器端壓縮以更少的集成複雜性、更好的 token 使用計算和無客戶端限制自動處理上下文管理。僅在您特別需要對摘要過程進行客戶端控制時才使用 SDK 壓縮。

壓縮在使用 tool_runner 方法時可在 Python 和 TypeScript SDK 中使用。

壓縮是一個 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 從中斷處繼續。

使用壓縮

將 compaction_control 添加到您的 tool_runner 調用中：

壓縮期間發生的事情

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

壓縮前（接近 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 個類似的交換 ...
]

當 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 閾值

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

# 記憶受限場景下更頻繁的壓縮
compaction_control = {"enabled": True, "context_token_threshold": 50000}

# 需要更多上下文時較少頻繁的壓縮
compaction_control = {"enabled": True, "context_token_threshold": 150000}

使用不同的模型生成摘要

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

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "model": "claude-haiku-4-5",
}

自定義摘要提示

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

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "summary_prompt": """Summarize the research conducted so far, including:
- Sources consulted and key findings
- Questions answered and remaining unknowns
- Recommended next steps

Wrap your summary in <summary></summary> tags.""",
}

預設摘要提示

內建的摘要提示會指示 Claude 建立一個結構化的延續摘要，包含：

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

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

限制

伺服器端工具

當使用伺服器端工具（例如網路搜尋或網路擷取）時，壓縮需要特別注意。

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

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

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

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

解決方法：

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

工具使用的邊緣情況

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

監控壓縮

啟用日誌記錄以追蹤壓縮發生的時機：

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("anthropic.lib.tools").setLevel(logging.INFO)

# 日誌將顯示：
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500

何時使用壓縮

適合的使用情境：

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

較不理想的使用情境：

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

Was this page helpful?

上下文管理

上下文編輯

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

概覽

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

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

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

伺服器端策略

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

請通過反饋表單分享對此功能的反饋。

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

工具結果清除

思考區塊清除

要最大化緩存命中率，請通過設置 keep: "all" 來保留所有思考區塊。

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

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

上下文編輯與提示緩存

上下文編輯與提示緩存的交互因策略而異：

工具結果清除：清除內容時會使緩存的提示前綴失效。為了應對這種情況，請清除足夠多的 token 以使緩存失效值得。使用 clear_at_least 參數確保每次清除最少數量的 token。每次清除內容時您都會產生緩存寫入成本，但後續請求可以重用新緩存的前綴。
思考區塊清除：當思考區塊被保留在上下文中（未被清除）時，提示緩存得以保留，從而實現緩存命中並降低輸入 token 成本。當思考區塊被清除時，緩存在清除發生的位置失效。根據您是否希望優先考慮緩存性能或上下文窗口可用性來配置 keep 參數。

支援的模型

上下文編輯可在以下模型上使用：

Claude Opus 4.6 (claude-opus-4-6)
Claude Opus 4.5 (claude-opus-4-5-20251101)
Claude Opus 4.1 (claude-opus-4-1-20250805)
Claude Opus 4 (claude-opus-4-20250514)
Claude Sonnet 4.6 (claude-sonnet-4-6)
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Haiku 4.5 (claude-haiku-4-5-20251001)

工具結果清除使用方法

啟用工具結果清除的最簡單方法是只指定策略類型。所有其他配置選項使用其默認值：

進階配置

您可以使用其他參數自定義工具結果清除行為：

思考區塊清除使用方法

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

思考區塊清除的配置選項

clear_thinking_20251015 策略支援以下配置：

配置選項	默認值	描述
`keep`	`{type: "thinking_turns", value: 1}`	定義要保留多少個最近的含有思考區塊的助手輪次。使用 `{type: "thinking_turns", value: N}`（其中 N 必須 > 0）來保留最後 N 個輪次，或使用 `"all"` 保留所有思考區塊。

配置示例：

保留最後 3 個助手輪次的思考區塊：

{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

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

{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

組合策略

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

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

工具結果清除的配置選項

配置選項	默認值	描述
`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 的有用統計信息。

Response

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // 使用 `clear_thinking_20251015` 時
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // 使用 `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

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

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

與記憶工具配合使用

這種組合允許您：

保留重要上下文：Claude 可以在工具結果被清除之前將其中的重要信息寫入記憶文件
維持長期工作流程：通過將信息卸載到持久存儲，啟用否則會超出上下文限制的代理工作流程
按需訪問信息：Claude 可以在需要時從記憶文件中查找之前被清除的信息，而不是將所有內容保留在活躍的上下文窗口中

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

客戶端壓縮（SDK）

壓縮在使用 tool_runner 方法時可在 Python 和 TypeScript SDK 中使用。

壓縮的工作原理

啟用壓縮後，SDK 在每次模型響應後監控 token 使用情況：

閾值檢查： SDK 將總 token 計算為 input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens。
摘要生成： 當超過閾值時，摘要提示作為用戶輪次注入，Claude 生成包裹在 <summary></summary> 標籤中的結構化摘要。
上下文替換： SDK 提取摘要並用它替換整個消息歷史。
繼續： 對話從摘要恢復，Claude 從中斷處繼續。

使用壓縮

將 compaction_control 添加到您的 tool_runner 調用中：

壓縮期間發生的事情

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

壓縮前（接近 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 個類似的交換 ...
]

當 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 閾值

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

# 記憶受限場景下更頻繁的壓縮
compaction_control = {"enabled": True, "context_token_threshold": 50000}

# 需要更多上下文時較少頻繁的壓縮
compaction_control = {"enabled": True, "context_token_threshold": 150000}

使用不同的模型生成摘要

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

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "model": "claude-haiku-4-5",
}

自定義摘要提示

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

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "summary_prompt": """Summarize the research conducted so far, including:
- Sources consulted and key findings
- Questions answered and remaining unknowns
- Recommended next steps

Wrap your summary in <summary></summary> tags.""",
}

預設摘要提示

內建的摘要提示會指示 Claude 建立一個結構化的延續摘要，包含：

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

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

限制

伺服器端工具

當使用伺服器端工具（例如網路搜尋或網路擷取）時，壓縮需要特別注意。

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

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

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

解決方法：

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

工具使用的邊緣情況

監控壓縮

啟用日誌記錄以追蹤壓縮發生的時機：

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("anthropic.lib.tools").setLevel(logging.INFO)

# 日誌將顯示：
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500

何時使用壓縮

適合的使用情境：

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

較不理想的使用情境：

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

Was this page helpful?

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Search for recent developments in AI"
            }
        ],
        "tools": [
            {
                "type": "web_search_20250305",
                "name": "web_search"
            }
        ],
        "context_management": {
            "edits": [
                {"type": "clear_tool_uses_20250919"}
            ]
        }
    }'

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "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
            }
        ],
        "context_management": {
            "edits": [
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {
                        "type": "input_tokens",
                        "value": 30000
                    },
                    "keep": {
                        "type": "tool_uses",
                        "value": 3
                    },
                    "clear_at_least": {
                        "type": "input_tokens",
                        "value": 5000
                    },
                    "exclude_tools": ["web_search"]
                }
            ]
        }
    }'

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 1024,
        "messages": [/* ... */],
        "thinking": {
            "type": "enabled",
            "budget_tokens": 10000
        },
        "context_management": {
            "edits": [
                {
                    "type": "clear_thinking_20251015",
                    "keep": {
                        "type": "thinking_turns",
                        "value": 2
                    }
                }
            ]
        }
    }'

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[...],
    thinking={"type": "enabled", "budget_tokens": 10000},
    tools=[...],
    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},
            },
        ]
    },
)

curl https://api.anthropic.com/v1/messages/count_tokens \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "messages": [
            {
                "role": "user",
                "content": "Continue our conversation..."
            }
        ],
        "tools": [...],
        "context_management": {
            "edits": [
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {
                        "type": "input_tokens",
                        "value": 30000
                    },
                    "keep": {
                        "type": "tool_uses",
                        "value": 5
                    }
                }
            ]
        }
    }'

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[...],
    tools=[
        {"type": "memory_20250818", "name": "memory"},
        # 您的其他工具
    ],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

import anthropic

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-6",
    max_tokens=4096,
    tools=[...],
    messages=[
        {
            "role": "user",
            "content": "Analyze all the files in this directory and write a summary report.",
        }
    ],
    compaction_control={"enabled": True, "context_token_threshold": 100000},
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")

final = runner.until_done()

概覽

伺服器端策略

工具結果清除

思考區塊清除

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

上下文編輯與提示緩存

支援的模型

工具結果清除使用方法

進階配置

思考區塊清除使用方法

思考區塊清除的配置選項

組合策略

工具結果清除的配置選項

上下文編輯響應

Token 計數

與記憶工具配合使用

客戶端壓縮（SDK）

壓縮的工作原理

使用壓縮

壓縮期間發生的事情

配置選項

選擇 token 閾值

使用不同的模型生成摘要

自定義摘要提示

預設摘要提示

查看完整預設提示

限制

伺服器端工具

工具使用的邊緣情況

監控壓縮

何時使用壓縮

概覽

伺服器端策略

工具結果清除

思考區塊清除

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

上下文編輯與提示緩存

支援的模型

工具結果清除使用方法

進階配置

思考區塊清除使用方法

思考區塊清除的配置選項

組合策略

工具結果清除的配置選項

上下文編輯響應

Token 計數

與記憶工具配合使用

客戶端壓縮（SDK）

壓縮的工作原理

使用壓縮

壓縮期間發生的事情

配置選項

選擇 token 閾值

使用不同的模型生成摘要

自定義摘要提示

預設摘要提示

查看完整預設提示

限制

伺服器端工具

工具使用的邊緣情況

監控壓縮

何時使用壓縮