上下文编辑

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.

概述

对于大多数用例，服务器端压缩是管理长时间运行对话中上下文的主要策略。本页面上的策略对于需要更细粒度控制要清除内容的特定场景很有用。

上下文编辑允许您在对话历史增长时有选择地清除特定内容。除了优化成本和保持在限制范围内，这是关于主动策划 Claude 看到的内容：上下文是一种有限资源，收益递减，无关内容会降低模型的专注力。上下文编辑为您提供对该策划的细粒度运行时控制。有关上下文管理背后的更广泛原则，请参阅有效的上下文工程。本页面涵盖：

工具结果清除 - 最适合具有大量工具使用的代理工作流，其中不再需要旧的工具结果
思考块清除 - 用于在使用扩展思考时管理思考块，可选择保留最近的思考以保持上下文连续性
客户端 SDK 压缩 - 用于基于摘要的上下文管理的基于 SDK 的替代方案（通常首选服务器端压缩）

方法	运行位置	策略	工作原理
服务器端	API	工具结果清除 (`clear_tool_uses_20250919`) 思考块清除 (`clear_thinking_20251015`)	在提示到达 Claude 之前应用。从对话历史中清除特定内容。每个策略可以独立配置。
客户端	SDK	压缩	在使用 `tool_runner` 时在 Python、TypeScript 和 Ruby SDK 中可用。生成摘要并替换完整对话历史。请参阅下面的客户端压缩。

服务器端策略

上下文编辑处于测试版，支持工具结果清除和思考块清除。要启用它，请在 API 请求中使用测试版标头 context-management-2025-06-27。

通过反馈表分享对此功能的反馈。

工具结果清除

clear_tool_uses_20250919 策略在对话上下文增长超过您配置的阈值时清除工具结果。这对于具有大量工具使用的代理工作流特别有用。一旦 Claude 处理了旧的工具结果（如文件内容或搜索结果），就不再需要它们。

激活后，API 会按时间顺序自动清除最旧的工具结果。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 模型上可用。

工具结果清除用法

启用工具结果清除的最简单方法是仅指定策略类型。所有其他配置选项使用其默认值：

高级配置

您可以使用其他参数自定义工具结果清除行为：

思考块清除用法

启用思考块清除以在启用扩展思考时有效管理上下文和提示缓存：

思考块清除的配置选项

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 输入令牌	定义上下文编辑策略何时激活。一旦提示超过此阈值，清除将开始。您可以在 `input_tokens` 或 `tool_uses` 中指定此值。
`keep`	3 个工具使用	定义清除发生后要保留多少个最近的工具使用/结果对。API 首先删除最旧的工具交互，保留最新的交互。
`clear_at_least`	无	确保每次策略激活时至少清除最少数量的令牌。如果 API 无法清除至少指定的数量，则不会应用该策略。这有助于确定上下文清除是否值得破坏您的提示缓存。
`exclude_tools`	无	工具名称列表，其工具使用和结果永远不应被清除。对于保留重要上下文很有用。
`clear_tool_inputs`	`false`	控制是否将工具调用参数与工具结果一起清除。默认情况下，仅清除工具结果，同时保持 Claude 的原始工具调用可见。

上下文编辑响应

您可以使用 context_management 响应字段查看哪些上下文编辑已应用于您的请求，以及有关清除的内容和输入令牌的有用统计信息。

Output

{
  "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": [
      // ...
    ]
  }
}

令牌计数

令牌计数端点支持上下文管理，允许您预览在应用上下文编辑后您的提示将使用多少令牌。

Output

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

响应显示应用上下文管理后的最终令牌计数（input_tokens）和任何清除发生前的原始令牌计数（original_input_tokens）。

与内存工具一起使用

上下文编辑可以与内存工具结合使用。当您的对话上下文接近配置的清除阈值时，Claude 会收到自动警告以保留重要信息。这使 Claude 能够在工具结果从对话历史中清除之前，将工具结果或上下文保存到其内存文件中。

这种组合允许您：

保留重要上下文：Claude 可以在工具结果被清除之前，将工具结果中的重要信息写入内存文件
维护长期运行的工作流：通过将信息卸载到持久存储，启用否则会超过上下文限制的代理工作流
按需访问信息：Claude 可以在需要时从内存文件中查找之前清除的信息，而不是将所有内容保留在活跃的上下文窗口中

例如，在 Claude 执行许多操作的文件编辑工作流中，Claude 可以在上下文增长时将已完成的更改总结到内存文件中。当工具结果被清除时，Claude 通过其内存系统保留对该信息的访问权限，并可以继续有效地工作。

要同时使用这两个功能，请在您的 API 请求中启用它们：

有关内存工具的完整参考（包括命令和示例），请参阅内存工具。

客户端压缩 (SDK)

Anthropic 建议使用服务器端压缩而不是 SDK 压缩。服务器端压缩自动处理上下文管理，集成复杂性更低，令牌使用计算更准确，没有客户端限制。仅当您特别需要对摘要过程进行客户端控制时，才使用 SDK 压缩。

当使用tool_runner 方法时，压缩在 Python、TypeScript 和 Ruby SDK 中可用。

压缩是一个 SDK 功能，通过在令牌使用量增长过大时生成摘要来自动管理对话上下文。与清除内容的服务器端上下文编辑策略不同，压缩指示 Claude 总结对话历史，然后用该摘要替换完整历史。这允许 Claude 继续处理长期运行的任务，否则这些任务会超过上下文窗口。

压缩如何工作

启用压缩后，SDK 在每个模型响应后监控令牌使用情况：

阈值检查： SDK 将总令牌计算为 input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens。
摘要生成： 当超过阈值时，摘要提示被注入为用户回合，Claude 生成包装在 <summary></summary> 标签中的结构化摘要。
上下文替换： SDK 提取摘要并用它替换整个消息历史。
继续： 对话从摘要恢复，Claude 从中断的地方继续。

使用压缩

将 compaction_control 添加到您的 tool_runner 调用中，以在令牌使用超过阈值时启用自动摘要。

压缩期间发生的情况

随着对话的增长，消息历史不断积累：

压缩前（接近 100k 令牌）：

[
  { "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 ...
]

当令牌超过阈值时，SDK 注入摘要请求，Claude 生成摘要。整个历史随后被替换：

压缩后（回到约 2-3k 令牌）：

[
  {
    "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	触发压缩的令牌计数
`model`	string	否	与主模型相同	用于生成摘要的模型
`summary_prompt`	string	否	见下文	摘要生成的自定义提示

选择令牌阈值

阈值决定了压缩发生的时间。较低的阈值意味着更频繁的压缩，上下文窗口更小。较高的阈值允许更多上下文，但有触及限制的风险。

# 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 能够有效地恢复工作，而不会丢失重要上下文或重复错误。

限制

服务器端工具

使用服务器端工具（如网络搜索或网络获取）时，压缩需要特殊考虑。

使用服务器端工具时，SDK 可能会错误地计算令牌使用情况，导致压缩在错误的时间触发。

例如，在网络搜索操作后，API 响应可能显示：

Output

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

SDK 将总使用量计算为 63,000 + 270,000 = 333,000 令牌。但是，cache_read_input_tokens 值包括来自服务器端工具进行的多个内部 API 调用的累积读取，而不是您的实际对话上下文。您的真实上下文长度可能只有 63,000 个 input_tokens，但 SDK 看到 333k 并过早触发压缩。

解决方法：

使用令牌计数端点获取准确的上下文长度
在广泛使用服务器端工具时避免压缩

工具使用边界情况

当 SDK 在工具使用响应待处理时触发压缩时，它会在生成摘要之前从消息历史中删除工具使用块。如果仍然需要，Claude 将在从摘要恢复后重新发出工具调用。

监控压缩

了解压缩何时触发有助于您调整阈值并验证预期行为。

何时使用压缩

良好的使用场景：

处理许多文件或数据源的长期运行代理任务
积累大量信息的研究工作流
具有清晰、可衡量进度的多步骤任务
生成在对话外部持久化的工件（文件、报告）的任务

不太理想的使用场景：

需要精确回忆早期对话细节的任务
广泛使用服务器端工具的工作流
需要在许多变量中维护精确状态的任务

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": 16000,
        "messages": [{"role": "user", "content": "Hello"}],
        "thinking": {
            "type": "enabled",
            "budget_tokens": 10000
        },
        "context_management": {
            "edits": [
                {
                    "type": "clear_thinking_20251015",
                    "keep": {
                        "type": "thinking_turns",
                        "value": 2
                    }
                }
            ]
        }
    }'

ant beta:messages create --beta context-management-2025-06-27 <<'YAML'
model: claude-opus-4-6
max_tokens: 16000
thinking:
  type: enabled
  budget_tokens: 10000
messages:
  - role: user
    content: Hello
tools:
  - type: web_search_20250305
    name: web_search
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
YAML

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
                    }
                }
            ]
        }
    }'

ant beta:messages create --beta context-management-2025-06-27 <<'YAML'
model: claude-opus-4-6
max_tokens: 4096
messages:
  - role: user
    content: Hello
tools:
  - type: memory_20250818
    name: memory
context_management:
  edits:
    - type: clear_tool_uses_20250919
YAML

概述

服务器端策略

工具结果清除

思考块清除

上下文编辑在服务器端进行

上下文编辑和提示缓存

支持的模型

工具结果清除用法

高级配置

思考块清除用法

思考块清除的配置选项

组合策略

工具结果清除的配置选项

上下文编辑响应

令牌计数

与内存工具一起使用

客户端压缩 (SDK)

压缩如何工作

使用压缩

压缩期间发生的情况

配置选项

选择令牌阈值

为摘要使用不同的模型

自定义摘要提示

默认摘要提示

查看完整默认提示

限制

服务器端工具

工具使用边界情况

监控压缩

何时使用压缩