上下文编辑
上下文编辑目前处于测试版，支持工具结果清除和思考块清除。要启用它，请在您的 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": [
// 使用 `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 事件中：
{
"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"}
]
}
)