上下文编辑

此功能符合零数据保留（ZDR）的条件。当您的组织签订了 ZDR 协议时，通过此功能发送的数据在 API 响应返回后不会被存储。

概述

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

"Context editing"（上下文编辑）允许您在对话历史增长时有选择地清除其中的特定内容。这不仅仅是为了优化成本和保持在限制范围内，更是为了主动管理 Claude 所看到的内容：上下文是一种收益递减的有限资源，不相关的内容会降低模型的专注度。上下文编辑让您能够在运行时对这种内容管理进行精细控制。有关上下文管理背后的更广泛原则，请参阅面向 AI 智能体的高效上下文工程。本页面涵盖以下内容：

工具结果清除 - 最适合大量使用工具的智能体工作流，其中旧的工具结果不再需要
思考块清除 - 用于在使用扩展思考时管理思考块，并提供保留最近思考内容以保持上下文连续性的选项
客户端 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 块。此策略让您可以控制思考内容的保留：您可以选择保留更多思考块以维持推理连续性，或更积极地清除它们以节省上下文空间。

**默认行为：**默认值因模型类别而异。

模型类别	保留所有先前的思考内容	仅保留最后一轮的思考内容
Opus	Claude Opus 4.5 及更高版本	Claude Opus 4.1（已弃用）及更早版本
Sonnet	Claude Sonnet 4.6 及更高版本	Claude Sonnet 4.5 及更早版本
Haiku	（无）	截至 Claude Haiku 4.5 的所有模型

使用此策略可覆盖默认行为。如果您的代码需要在多个模型层级上运行，请显式设置 keep，而不要依赖各模型的默认值。

一个助手对话轮次可能包含多个内容块（例如在使用工具时）和多个思考块（例如在使用交错思考时）。

上下文编辑在服务端进行

上下文编辑在提示到达 Claude 之前在服务端应用。您的客户端应用程序维护完整的、未修改的对话历史。您无需将客户端状态与编辑后的版本同步。请像往常一样继续在本地管理您的完整对话历史。

上下文编辑与提示缓存

上下文编辑与提示缓存的交互因策略而异：

工具结果清除：当内容被清除时，会使已缓存的提示前缀失效。为了应对这一点，请清除足够多的令牌，使缓存失效变得值得。使用 clear_at_least 参数可确保每次至少清除指定数量的令牌。每次清除内容时，您都会产生缓存写入成本，但后续请求可以重用新缓存的前缀。
思考块清除：当思考块被保留在上下文中（未被清除）时，提示缓存会被保留，从而实现缓存命中并降低输入令牌成本。当思考块被清除时，缓存会在清除发生的位置失效。请根据您希望优先考虑缓存性能还是上下文窗口可用性来配置 keep 参数。

支持的模型

上下文编辑在所有受支持的 Claude 模型上均可用。

工具结果清除用法

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

高级配置

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

思考块清除用法

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

思考块清除的配置选项

clear_thinking_20251015 策略支持以下配置：

配置选项	默认值	描述
`keep`	因模型而异	定义要保留多少个最近的包含思考块的助手轮次。使用 `{type: "thinking_turns", value: N}`（其中 N 必须 > 0）来保留最后 N 个轮次，或使用 `"all"` 来保留所有思考块。Opus 4.5+ 和 Sonnet 4.6+：所有轮次。更早的 Opus/Sonnet 以及所有 Haiku：仅最后一个轮次。

配置示例：

保留最后 3 个助手轮次的思考块：

保留所有思考块（最大化缓存命中率）：

组合策略

您可以同时使用思考块清除和工具结果清除：

使用多个策略时，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": [
      // 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 事件中：

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 压缩。

compaction_control 参数在 Python、TypeScript 和 Ruby SDK 中已弃用，并将在未来版本中移除。启用该参数时，SDK 会发出弃用警告。要在工具运行器中使用服务端压缩，请在请求的 context_management 参数中传递 compact_20260112 编辑项。

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

"Compaction"（压缩）是一项 SDK 功能，当令牌使用量增长过大时，通过生成摘要来自动管理对话上下文。与清除内容的服务端上下文编辑策略不同，压缩会指示 Claude 对对话历史进行总结，然后用该摘要替换完整的历史记录。这使 Claude 能够继续处理原本会超出上下文窗口的长时间运行任务。

压缩的工作原理

启用压缩后，SDK 会在每次模型响应后监控令牌使用量：

**阈值检查：**SDK 将总令牌数计算为 input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens。
**摘要生成：**当超过阈值时，会将摘要提示作为用户轮次注入，Claude 会生成一个包裹在 <summary></summary> 标签中的结构化摘要。
**上下文替换：**SDK 提取摘要并用其替换整个消息历史。
**继续执行：**对话从摘要处恢复，Claude 从中断的地方继续工作。

使用压缩

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

压缩期间发生的情况

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

压缩前（接近 10 万令牌）：

[
  { "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–3 千令牌）：

[
  {
    "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	否	参见默认摘要提示	用于生成摘要的自定义提示

选择令牌阈值

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

使用不同的模型生成摘要

您可以使用更快或更便宜的模型来生成摘要：

自定义摘要提示

您可以为特定领域的需求提供自定义提示。您的提示应指示 Claude 将其摘要包裹在 <summary></summary> 标签中。

默认摘要提示

内置的摘要提示指示 Claude 创建一个结构化的延续摘要，包括：

**任务概述：**用户的核心请求、成功标准和约束条件。
**当前状态：**已完成的内容、已修改的文件和已生成的产出物。
**重要发现：**技术约束、已做出的决策、已解决的错误和失败的方法。
**后续步骤：**需要执行的具体操作、阻碍因素和优先级顺序。
**需保留的上下文：**用户偏好、特定领域的细节和已做出的承诺。

这种结构使 Claude 能够高效地恢复工作，而不会丢失重要上下文或重复错误。

限制

服务端工具

在使用网络搜索或网页抓取等服务端工具时，压缩需要特别注意。

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

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

Output

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

SDK 将总使用量计算为 63,000 + 0 + 270,000 + 1,400 = 334,400 个令牌。然而，cache_read_input_tokens 值包含了服务端工具进行的多次内部 API 调用的累积读取量，而不是您实际的对话上下文。您的实际上下文长度可能只有 63,000 个 input_tokens，但 SDK 看到的是 33.4 万，从而过早触发压缩。

解决方法：

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

工具使用边缘情况

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

监控压缩

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

何时使用压缩

适合的用例：

处理大量文件或数据源的长时间运行的智能体任务
积累大量信息的研究工作流
具有清晰、可衡量进度的多步骤任务
生成在对话之外持久存在的产出物（文件、报告）的任务

不太理想的用例：

需要精确回忆早期对话细节的任务
大量使用服务端工具的工作流
需要在许多变量之间维持精确状态的任务

后续步骤

压缩

使用服务端压缩管理长对话，这是大多数用例的推荐策略。

提示缓存

通过缓存提示前缀来降低成本和延迟，并了解上下文编辑如何与缓存交互。

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}]},
)

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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},
    ],
    betas=["context-management-2025-06-27"],
    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"],
            }
        ]
    },
)

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    thinking={"type": "adaptive"},
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            }
        ]
    },
)

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    thinking={"type": "adaptive"},
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 3},
            }
        ]
    },
)

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    thinking={"type": "adaptive"},
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": "all",
            }
        ]
    },
)

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[
        {
            "role": "user",
            "content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
        }
    ],
    thinking={"type": "adaptive"},
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5,
        }
    ],
    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},
            },
        ]
    },
)

print(response)

response = client.beta.messages.count_tokens(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 5},
            }
        ]
    },
)

print(f"Original tokens: {response.context_management.original_input_tokens}")
print(f"After clearing: {response.input_tokens}")
print(
    f"Savings: {response.context_management.original_input_tokens - response.input_tokens} tokens"
)

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Hello"}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

概述

服务端策略

工具结果清除

思考块清除

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

上下文编辑与提示缓存

支持的模型

工具结果清除用法

高级配置

思考块清除用法

思考块清除的配置选项

组合策略

工具结果清除的配置选项

上下文编辑响应

令牌计数

与记忆工具配合使用

客户端压缩（SDK）

压缩的工作原理

使用压缩

压缩期间发生的情况

配置选项

选择令牌阈值

使用不同的模型生成摘要

自定义摘要提示

默认摘要提示

查看完整的默认提示

限制

服务端工具

工具使用边缘情况

监控压缩

何时使用压缩

后续步骤

概述

服务端策略

工具结果清除

思考块清除

上下文编辑在服务端进行

上下文编辑与提示缓存

支持的模型

工具结果清除用法

高级配置

思考块清除用法

思考块清除的配置选项

组合策略

工具结果清除的配置选项

上下文编辑响应

令牌计数

与记忆工具配合使用

客户端压缩（SDK）

压缩的工作原理

使用压缩

压缩期间发生的情况

配置选项

选择令牌阈值

使用不同的模型生成摘要

自定义摘要提示

默认摘要提示

限制

服务端工具

工具使用边缘情况

监控压缩

何时使用压缩

后续步骤