上下文編輯

概述

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

上下文編輯允許您在對話歷史增長時選擇性地清除特定內容。這有助於您優化成本並保持在上下文視窗限制內。本頁面涵蓋：

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

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

伺服器端策略

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

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

工具結果清除

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

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

# More frequent compaction for memory-constrained scenarios
compaction_control={
    "enabled": True,
    "context_token_threshold": 50000
}

# Less frequent compaction when you need more context
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 能夠高效地恢復工作，而不會遺失重要上下文或重複錯誤。

限制

伺服器端工具

使用伺服器端工具（例如 web search 或 web fetch）時，壓縮需要特別考量。

使用伺服器端工具時，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)

# Logs will show:
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500

何時使用壓縮

適合的使用場景：

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

較不理想的使用場景：

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

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"
        },
        # Your other tools
    ],
    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 閾值

使用不同模型生成摘要

自訂摘要提示

預設摘要提示

查看完整預設提示

限制

伺服器端工具

工具使用的邊界情況

監控壓縮

何時使用壓縮