会话修剪¶

会话修剪会从模型上下文中裁剪旧的工具结果。它减少因累积工具输出（执行结果、文件读取、搜索结果）导致的上下文膨胀，而不会重写正常的对话文本。

为何重要¶

长时间会话会累积工具输出，使上下文窗口膨胀。这会增加成本，并可能迫使 压缩 提前发生。

修剪对 Anthropic 提示缓存 尤其有价值。它减少了必须缓存的工具内容，并使后续请求保持在缩减后的前缀上。直接的 Anthropic API 密钥请求使用服务端清理；其他符合条件的路由会在缓存 TTL 过期后在本地进行修剪。

工作原理¶

将 agents.defaults.contextPruning.mode 设置为 "cache-ttl" 即可启用修剪。请求的提供方、端点和认证方式决定了它在何处运行。

直接使用 Anthropic API 密钥的请求¶

对于使用 anthropic-messages API、API 密钥认证以及默认端点或 api.anthropic.com 的 anthropic 提供方，OpenClaw 会将修剪委托给 Anthropic 的 服务端工具结果清理。OpenClaw 不会开启新的客户端修剪轮次，服务端会在模型看到结果之前清理旧结果。同一会话中更早生成的投影（例如在代理路由上生成的，或从转录标记恢复的）仍会原样重放。完整的本地历史记录会被保留。ttl 不限制此路径。

OpenClaw 在不增加配置选项的情况下派生请求参数：

请求包含 clear_tool_uses_20250919 编辑和 context-management-2025-06-27 beta 标头。如果启用了服务端压缩，清理编辑会先于压缩编辑。调用方显式提供的 context_management 保持不变。客户端的软修剪和 hardClear 设置不会改变服务端的清理策略。

清理会使从第一个被清理结果开始的提示缓存失效；clear_at_least 可防止出现因清除 token 过少而不值得写入新缓存的清理事件。当发生清理时，OpenClaw 会记录以下信息行：

[anthropic] server-side context edit: cleared N tool results (M input tokens)

客户端修剪¶

Amazon Bedrock、Google、Microsoft Foundry、OAuth、代理、Vertex 以及其他符合缓存 TTL 条件的路由会保留客户端修剪。新的修剪轮次同时受时间检查和上下文大小检查约束：

1. 等待缓存 TTL 过期。当你开启 cache-ttl 模式且未设置 ttl 时，TTL 为 5 分钟。内置的 Anthropic 插件会改为预置 1h，参见 智能默认值。每次成功的模型请求都会将内存中的时钟刷新为其请求开始时间，包括回合结算前的工具循环请求。失败的请求不会刷新它。在 TTL 到期之前，不会发生新的修剪。现有投影仍会原样重放。
2. TTL 过期后，根据模型的上下文窗口估算总上下文大小。当使用量低于约 30% 时，跳过修剪，TTL 时钟继续运行。
3. 软修剪过大的工具结果：超过 4,000 字符的结果保留其开头和结尾各 1,500 字符，中间用 ... 代替。
4. 如果上下文使用量仍然达到或超过约 50%，且剩余至少 50,000 字符可修剪的工具内容，则硬清除这些结果。硬清除会将每个结果的内容替换为占位符。默认占位符是 [Old tool result content cleared]，可通过 agents.defaults.contextPruning.hardClear.placeholder 更改。设置 hardClear.enabled: false 可跳过此步骤。
5. 将每个更改后的结果记录为会话投影，并重置修剪 TTL 时钟。后续请求会复用相同的投影字节，包括工具循环的延续和后续回合。

TTL 限制的是新的修剪轮次，而不是先前投影的重放。投影通过转录标记在 Gateway 重启和内存会话缓存驱逐后依然存在。即使 TTL 修剪关闭，当投影发生变化时，普通的工具结果修剪和已发送边界也会在模型请求之前保存。未变化的投影不会添加新标记；重启时会恢复活动分支上的最新标记。旧结果在工具循环和重启期间保留其投影字节。原始文本和非文本内容保留在转录中。压缩会丢弃不再处于活动历史中的结果的投影；/new 和会话重置会在没有旧会话投影的情况下启动。缓存 TTL 标记的时间戳仍然支持现有的缓存和心跳记账。

无论阈值如何，都有两条安全规则适用：最后三个 assistant 回合永远不会被修剪，会话第一条用户消息之前的任何内容也永远不会被修剪（可保护 SOUL.md/USER.md 等引导读取）。上述大小阈值和修剪窗口是内置行为，不是配置键；可配置范围是 agents.defaults.contextPruning（mode、ttl、tools、hardClear）。

只有 toolResult 消息符合修剪条件；普通对话文本不会被触碰。使用 agents.defaults.contextPruning.tools.{allow,deny} 来限定任一路径上哪些工具名称可被修剪。

旧版图像清理¶

OpenClaw 还会为在历史记录中持久化原始图像块或提示注入媒体标记的会话构建一个独立的幂等回放视图。

• 它会逐字节保留最近 3 个已完成的回合，以便近期后续问题的提示缓存前缀保持稳定。此计数包含所有已完成的回合，而不仅仅是包含图像的回合，因此纯文本回合也会占用该窗口。
• 窗口仅在新的用户回合开始时前进，绝不会在工具循环内前进。
• 在回放视图中，来自 user 或 toolResult 历史记录中较早且已被处理的图像块会被替换为 [image data removed - already processed by model]。
• 较早的文本媒体引用（例如 [media attached: ...]、[Image: source: ...] 和 media://inbound/...）会被替换为 [media reference removed - already processed by model]。当前回合的附件标记保持完整，以便视觉模型仍然可以注入新图像。
• 原始会话记录不会被重写，因此历史记录查看器仍然可以渲染原始消息条目及其图像。
• 这与上面提到的常规缓存 TTL 修剪是分开的。它的存在是为了防止重复的图像负载或过时的媒体引用在后续回合中破坏提示缓存。

智能默认值¶

内置的 Anthropic 插件在首次解析 Anthropic（或 Claude CLI）认证配置文件时会自动配置修剪和心跳节奏，但仅针对你尚未显式设置的字段：

如果你自行设置了 agents.defaults.contextPruning.mode 或 agents.defaults.heartbeat.every，OpenClaw 不会覆盖它们。此自动默认值仅对 Anthropic 系列认证生效；除非你自行配置，否则其他提供商的修剪默认为 off。

预设的 ttl 适用于客户端修剪。直接使用 Anthropic API 密钥的请求采用上述令牌阈值，同时保留相同的心跳默认值。

启用或禁用¶

对于非 Anthropic 提供商，修剪默认处于关闭状态。要启用：

{
  agents: {
    defaults: {
      contextPruning: { mode: "cache-ttl", ttl: "5m" },
    },
  },
}

要停止新的修剪，请设置 mode: "off"。现有的客户端投影会继续回放，包括在 Gateway 重启之后，直到压缩移除其结果或会话被重置。

修剪与压缩¶

它们相辅相成——修剪可在压缩周期之间保持工具输出的精简。

延伸阅读¶

• 压缩：基于摘要的上下文缩减
• agents.defaults.contextPruning：所有修剪配置项（contextPruning.*）

相关文档¶

• 会话管理
• 会话工具
• 上下文引擎
• 会话记录卫生 - 运行前应用的内存中、提供商特有的会话记录净化