上下文編輯
上下文編輯目前處於測試版，支持工具結果清除和思考區塊清除。要啟用它，請在您的 API 請求中使用測試版標頭 context-management-2025-06-27。
請通過我們的反饋表單分享您對此功能的反饋。
概述
上下文編輯允許您在對話上下文增長時自動管理它，幫助您優化成本並保持在上下文窗口限制內。API 提供了不同的上下文管理策略：
- 工具結果清除 (
clear_tool_uses_20250919)：當對話上下文超過您配置的閾值時，自動清除工具使用/結果對 - 思考區塊清除 (
clear_thinking_20251015)：通過清除先前輪次的舊思考區塊來管理思考區塊
每個策略可以獨立配置並一起應用以優化您的特定用例。
上下文編輯策略
工具結果清除
clear_tool_uses_20250919 策略在對話上下文超過您配置的閾值時清除工具結果。激活後，API 會按時間順序自動清除最舊的工具結果，用佔位符文本替換它們以讓 Claude 知道工具結果已被移除。默認情況下，只清除工具結果。您可以通過將 clear_tool_inputs 設置為 true 來選擇清除工具結果和工具調用（工具使用參數）。
思考區塊清除
clear_thinking_20251015 策略在啟用擴展思考時管理對話中的 thinking 區塊。此策略自動清除先前輪次的舊思考區塊。
默認行為：當啟用擴展思考而不配置 clear_thinking_20251015 策略時，API 自動只保留最後一個助手輪次的思考區塊（等同於 keep: {type: "thinking_turns", value: 1}）。
要最大化緩存命中，通過設置 keep: "all" 來保留所有思考區塊。
助手對話輪次可能包括多個內容區塊（例如使用工具時）和多個思考區塊（例如使用交錯思考時）。
上下文編輯在伺服器端進行
上下文編輯在提示到達 Claude 之前在伺服器端應用。您的客戶端應用程序維護完整的、未修改的對話歷史記錄——您不需要將客戶端狀態與編輯版本同步。繼續像往常一樣在本地管理您的完整對話歷史記錄。
上下文編輯和提示緩存
上下文編輯與提示緩存的交互因策略而異：
-
工具結果清除：清除內容時使緩存的提示前綴失效。為了解決這個問題，我們建議清除足夠的令牌以使緩存失效值得。使用
clear_at_least參數確保每次清除時至少清除最少數量的令牌。每次清除內容時您都會產生緩存寫入成本，但後續請求可以重用新緩存的前綴。 -
思考區塊清除：當思考區塊保留在上下文中（未被清除）時，提示緩存被保留，啟用緩存命中並減少輸入令牌成本。當思考區塊被清除時，緩存在清除發生的位置失效。根據您是否想優先考慮緩存性能或上下文窗口可用性來配置
keep參數。
支持的模型
上下文編輯可用於：
- 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)
工具結果清除使用
啟用工具結果清除的最簡單方法是只指定策略類型，因為所有其他配置選項將使用其默認值：
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-sonnet-4-5",
"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"}
]
}
}'response = client.beta.messages.create(
model="claude-sonnet-4-5",
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"}
]
}
)import Anthropic from '@anthropic-ai/sdk';
const anthropic = new Anthropic({
apiKey: process.env.ANTHROPIC_API_KEY,
});
const response = await anthropic.beta.messages.create({
model: "claude-sonnet-4-5",
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" }
]
},
betas: ["context-management-2025-06-27"]
});進階配置
您可以使用其他參數自訂工具結果清除行為：
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-sonnet-4-5",
"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-sonnet-4-5-20250929",
"max_tokens": 1024,
"messages": [...],
"thinking": {
"type": "enabled",
"budget_tokens": 10000
},
"context_management": {
"edits": [
{
"type": "clear_thinking_20251015",
"keep": {
"type": "thinking_turns",
"value": 2
}
}
]
}
}'思考區塊清除的配置選項
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 陣列中首先列出。
response = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
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
}
}
]
}
)工具結果清除的配置選項
| 配置選項 | 默認值 | 描述 |
|---|---|---|
trigger | 100,000 個輸入令牌 | 定義上下文編輯策略何時激活。一旦提示超過此閾值，清除將開始。您可以在 input_tokens 或 tool_uses 中指定此值。 |
keep | 3 個工具使用 | 定義清除發生後要保留多少個最近的工具使用/結果對。API 首先移除最舊的工具交互，保留最新的。 |
clear_at_least | 無 | 確保每次策略激活時至少清除最少數量的令牌。如果 API 無法清除至少指定的數量，該策略將不被應用。這有助於確定上下文清除是否值得破壞您的提示緩存。 |
exclude_tools | 無 | 工具名稱列表，其工具使用和結果永遠不應被清除。對於保留重要上下文很有用。 |
clear_tool_inputs | false | 控制是否連同工具結果一起清除工具調用參數。默認情況下，只清除工具結果，同時保持 Claude 的原始工具調用可見。 |
上下文編輯回應
您可以使用 context_management 回應欄位查看哪些上下文編輯已應用於您的請求，以及有關清除的內容和輸入令牌的有用統計信息。
{
"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 事件中：
{
"type": "message_delta",
"delta": {
"stop_reason": "end_turn",
"stop_sequence": null
},
"usage": {
"output_tokens": 1024
},
"context_management": {
"applied_edits": [...]
}
}令牌計數
令牌計數端點支持上下文管理，允許您預覽應用上下文編輯後您的提示將使用多少令牌。
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-sonnet-4-5",
"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
}
}
]
}
}'{
"input_tokens": 25000,
"context_management": {
"original_input_tokens": 70000
}
}回應顯示應用上下文管理後的最終令牌計數（input_tokens）和任何清除發生之前的原始令牌計數（original_input_tokens）。
與記憶工具一起使用
上下文編輯可以與記憶工具結合使用。當您的對話上下文接近配置的清除閾值時，Claude 會收到自動警告以保留重要信息。這使 Claude 能夠在工具結果從對話歷史記錄中清除之前將工具結果或上下文保存到其記憶文件中。
此組合允許您：
- 保留重要上下文：Claude 可以在清除這些結果之前將工具結果中的必要信息寫入記憶文件
- 維護長期運行的工作流程：通過將信息卸載到持久存儲，啟用否則會超過上下文限制的代理工作流程
- 按需訪問信息：Claude 可以從記憶文件中查找先前清除的信息，而不是將所有內容保留在活動上下文窗口中
例如，在 Claude 執行許多操作的文件編輯工作流程中，Claude 可以在上下文增長時將已完成的更改總結到記憶文件中。當工具結果被清除時，Claude 通過其記憶系統保留對該信息的訪問權限，並可以繼續有效地工作。
要同時使用這兩個功能，請在您的 API 請求中啟用它們：
response = client.beta.messages.create(
model="claude-sonnet-4-5",
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"}
]
}
)