上下文管理

上下文编辑

通过上下文编辑自动管理不断增长的对话上下文。

概述

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

上下文编辑允许您在对话历史增长时选择性地清除特定内容。这有助于您优化成本并保持在上下文窗口限制内。本页面涵盖：

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

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

服务端策略

上下文编辑目前处于 beta 阶段，支持工具结果清除和思维块清除。要启用它，请在 API 请求中使用 beta 头 context-management-2025-06-27。

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

工具结果清除

clear_tool_uses_20250919 策略在对话上下文超过您配置的阈值时清除工具结果。这对于大量使用工具的智能体工作流特别有用。较旧的工具结果（如文件内容或搜索结果）在 Claude 处理完后就不再需要了。

激活后，API 会自动按时间顺序清除最旧的工具结果。每个被清除的结果都会被替换为占位文本，以便 Claude 知道它已被移除。默认情况下，只清除工具结果。您可以通过将 clear_tool_inputs 设置为 true 来选择同时清除工具结果和工具调用（工具使用参数）。

思维块清除

clear_thinking_20251015 策略在启用扩展思维时管理对话中的 thinking 块。此策略让您可以控制思维保留：您可以选择保留更多思维块以维持推理连续性，或更积极地清除它们以节省上下文空间。

默认行为： 当启用扩展思维但未配置 clear_thinking_20251015 策略时，API 会自动仅保留最后一个助手回合的思维块（等同于 keep: {type: "thinking_turns", value: 1}）。

要最大化缓存命中率，请通过设置 keep: "all" 来保留所有思维块。

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

上下文编辑在服务端执行

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

上下文编辑与提示缓存

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

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

支持的模型

上下文编辑可在以下模型上使用：

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

上下文编辑响应

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

Response

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

Token 计数

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

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

Response

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

响应同时显示应用上下文管理后的最终 token 计数（input_tokens）和清除前的原始 token 计数（original_input_tokens）。

与 Memory 工具配合使用

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

这种组合允许您：

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

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

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

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

客户端压缩（SDK）

推荐使用服务端压缩而非 SDK 压缩。 服务端压缩自动处理上下文管理，集成复杂度更低，token 使用计算更准确，且没有客户端限制。仅在您特别需要客户端控制摘要过程时才使用 SDK 压缩。

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

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

压缩的工作原理

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

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

使用压缩

在您的 tool_runner 调用中添加 compaction_control：

import anthropic

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-6",
    max_tokens=4096,
    tools=[...],
    messages=[
        {
            "role": "user",
            "content": "Analyze all the files in this directory and write a summary report."
        }
    ],
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000
    }
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")

final = runner.until_done()

压缩过程中发生了什么

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

压缩前（接近 100k token）：

[
  { "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 次类似的交互 ...
]

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

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

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

选择 token 阈值

阈值决定何时进行压缩。较低的阈值意味着更频繁的压缩和更小的上下文窗口。较高的阈值允许更多上下文但有超出限制的风险。

# 内存受限场景下更频繁的压缩
compaction_control={
    "enabled": True,
    "context_token_threshold": 50000
}

# 需要更多上下文时减少压缩频率
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 能够高效地恢复工作，而不会丢失重要上下文或重复错误。

限制

服务器端工具

在使用服务器端工具（如 web search 或 web fetch）时，压缩需要特别注意。

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

例如，在执行 web search 操作后，API 响应可能显示：

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

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

解决方法：

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

工具使用的边界情况

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

监控压缩

启用日志记录以跟踪压缩发生的时间：

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("anthropic.lib.tools").setLevel(logging.INFO)

# Logs will show:
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500

何时使用压缩

适合的使用场景：

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

不太理想的使用场景：

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

Was this page helpful?

上下文管理

上下文编辑

通过上下文编辑自动管理不断增长的对话上下文。

概述

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

上下文编辑允许您在对话历史增长时选择性地清除特定内容。这有助于您优化成本并保持在上下文窗口限制内。本页面涵盖：

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

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

服务端策略

上下文编辑目前处于 beta 阶段，支持工具结果清除和思维块清除。要启用它，请在 API 请求中使用 beta 头 context-management-2025-06-27。

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

工具结果清除

思维块清除

要最大化缓存命中率，请通过设置 keep: "all" 来保留所有思维块。

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

上下文编辑在服务端执行

上下文编辑与提示缓存

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

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

支持的模型

上下文编辑可在以下模型上使用：

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

上下文编辑响应

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

Response

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

Token 计数

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

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

Response

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

响应同时显示应用上下文管理后的最终 token 计数（input_tokens）和清除前的原始 token 计数（original_input_tokens）。

与 Memory 工具配合使用

这种组合允许您：

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

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

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

客户端压缩（SDK）

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

压缩的工作原理

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

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

使用压缩

在您的 tool_runner 调用中添加 compaction_control：

import anthropic

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-6",
    max_tokens=4096,
    tools=[...],
    messages=[
        {
            "role": "user",
            "content": "Analyze all the files in this directory and write a summary report."
        }
    ],
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000
    }
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")

final = runner.until_done()

压缩过程中发生了什么

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

压缩前（接近 100k token）：

[
  { "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 次类似的交互 ...
]

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

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

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

选择 token 阈值

阈值决定何时进行压缩。较低的阈值意味着更频繁的压缩和更小的上下文窗口。较高的阈值允许更多上下文但有超出限制的风险。

# 内存受限场景下更频繁的压缩
compaction_control={
    "enabled": True,
    "context_token_threshold": 50000
}

# 需要更多上下文时减少压缩频率
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 能够高效地恢复工作，而不会丢失重要上下文或重复错误。

限制

服务器端工具

在使用服务器端工具（如 web search 或 web fetch）时，压缩需要特别注意。

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

例如，在执行 web search 操作后，API 响应可能显示：

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

解决方法：

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

工具使用的边界情况

监控压缩

启用日志记录以跟踪压缩发生的时间：

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("anthropic.lib.tools").setLevel(logging.INFO)

# Logs will show:
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500

何时使用压缩

适合的使用场景：

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

不太理想的使用场景：

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

Was this page helpful?

概述

服务端策略

工具结果清除

思维块清除

上下文编辑在服务端执行

上下文编辑与提示缓存

支持的模型

工具结果清除用法

高级配置

思维块清除用法

思维块清除的配置选项

组合策略

工具结果清除的配置选项

上下文编辑响应

Token 计数

与 Memory 工具配合使用

客户端压缩（SDK）

压缩的工作原理

使用压缩

压缩过程中发生了什么

配置选项

选择 token 阈值

使用不同的模型生成摘要

自定义摘要提示

默认摘要提示词

查看完整默认提示词

限制

服务器端工具

工具使用的边界情况

监控压缩

何时使用压缩

概述

服务端策略

工具结果清除

思维块清除

上下文编辑在服务端执行

上下文编辑与提示缓存

支持的模型

工具结果清除用法

高级配置

思维块清除用法

思维块清除的配置选项

组合策略

工具结果清除的配置选项

上下文编辑响应

Token 计数

与 Memory 工具配合使用

客户端压缩（SDK）

压缩的工作原理

使用压缩

压缩过程中发生了什么

配置选项

选择 token 阈值

使用不同的模型生成摘要

自定义摘要提示

默认摘要提示词

查看完整默认提示词

限制

服务器端工具

工具使用的边界情况

监控压缩

何时使用压缩