上下文编辑目前处于测试阶段，支持工具结果清理。要启用它，请在您的API请求中使用测试版头部 context-management-2025-06-27。未来版本将添加其他上下文编辑策略。请通过我们的反馈表单联系我们，分享您对此功能的反馈。

​
工作原理

clear_tool_uses_20250919 策略在对话上下文超出您配置的阈值时清理工具结果。激活时，API会按时间顺序自动清理最旧的工具结果，用占位符文本替换它们，让Claude知道工具结果已被移除。默认情况下，只清理工具结果。您可以通过将 clear_tool_inputs 设置为true来选择性地清理工具结果和工具调用（工具使用参数）。 上下文编辑会使缓存的提示前缀失效，因为清理内容会修改提示结构，破坏缓存命中的匹配要求。为了解决这个问题，我们建议清理足够的令牌，使缓存失效变得值得。使用 clear_at_least 参数确保每次清理最少数量的令牌。当将提示缓存与上下文编辑一起使用时，每次清理内容时都会产生缓存写入成本，但后续请求可以重用新缓存的前缀。

​
支持的模型

上下文编辑可用于：
  • 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)

​
基本用法

启用上下文编辑的最简单方法是仅指定策略类型，因为所有其他配置选项都将使用其默认值： 
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": "搜索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-sonnet-4-5",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "使用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"]
                }
            ]
        }
    }'

​
配置选项

配置选项默认值描述
trigger100,000个输入令牌定义上下文编辑策略何时激活。一旦提示超过此阈值，就会开始清理。您可以用 input_tokens 或 tool_uses 指定此值。
keep3个工具使用定义清理发生后保留多少个最近的工具使用/结果对。API首先移除最旧的工具交互，保留最近的。
clear_at_least无确保每次策略激活时清理最少数量的令牌。如果API无法清理至少指定的数量，则不会应用该策略。这有助于确定上下文清理是否值得破坏您的提示缓存。
exclude_tools无永远不应清理其工具使用和结果的工具名称列表。对于保留重要上下文很有用。
clear_tool_inputsfalse控制是否与工具结果一起清理工具调用参数。默认情况下，只清理工具结果，同时保持Claude的原始工具调用可见。

​
响应格式

您可以使用 context_management 响应字段查看哪些上下文编辑应用于您的请求，以及关于清理的内容和输入令牌的有用统计信息。
Response
{
    "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
    "type": "message",
    "role": "assistant",
    "content": [...],
    "usage": {...},
    "context_management": {
        "applied_edits": [
            {
                "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": [...]
    }
}

​
令牌计数

/v1/messages/count_tokens 端点支持上下文管理，允许您预览应用上下文编辑后您的提示将使用多少令牌。 
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": "继续我们的对话..."
            }
        ],
        "tools": [...],
        "context_management": {
            "edits": [
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {
                        "type": "input_tokens",
                        "value": 30000
                    },
                    "keep": {
                        "type": "tool_uses",
                        "value": 5
                    }
                }
            ]
        }
    }'
Response
{
    "input_tokens": 25000,
    "context_management": {
        "original_input_tokens": 70000
    }
}
响应显示应用上下文管理后的最终令牌计数（input_tokens）和发生任何清理之前的原始令牌计数（original_input_tokens）。