会话修剪

会话修剪会在每次 LLM 调用前，从上下文中移除旧工具结果。它无需重写正常对话文本，即可减少累积工具输出（执行结果、文件读取结果、搜索结果）造成的上下文膨胀。

为什么重要

长会话会累积工具输出，使上下文窗口膨胀。这会增加成本，并可能导致系统比必要时间更早执行压缩。

修剪对 Anthropic 提示缓存尤其有价值。缓存 TTL 过期后，下一个请求会重新缓存完整提示。修剪可减少缓存写入量，从而直接降低成本。

工作原理

修剪以 cache-ttl 模式运行，同时受时间检查和上下文大小检查控制：

1. 等待缓存 TTL 过期（手动设置时默认为 5 分钟；Anthropic 的自动默认值请参阅智能默认值）。TTL 到期前会完全跳过修剪，以便相邻轮次继续复用提示缓存。
2. TTL 到期后，根据模型的上下文窗口估算上下文总大小。如果比例低于 softTrimRatio（默认为 0.3），则跳过修剪，并让 TTL 计时继续运行。
3. 对超过该比例的超大工具结果执行软修剪：保留开头和结尾（默认各 1500 个字符，合计最多 4000 个字符），并在中间插入 ...。
4. 如果比例仍达到或超过 hardClearRatio（默认为 0.5），且仍有至少 minPrunableToolChars（默认为 50,000）个字符的可修剪工具内容，则彻底清除这些结果：将其内容替换为占位符（默认为 [旧工具结果内容已清除]）。
5. 仅当修剪确实改变了上下文时才重置 TTL 计时，以便后续请求复用新缓存。

无论阈值如何，都会应用两项安全规则：绝不修剪最近的 keepLastAssistants 个助手轮次（默认为 3 个），也绝不修剪会话第一条用户消息之前的任何内容（用于保护 SOUL.md/USER.md 等启动读取内容）。

只有 toolResult 消息符合修剪条件；正常对话文本不会受到影响。使用 agents.defaults.contextPruning.tools.{allow,deny} 限定哪些工具名称可以被修剪。

旧版图片清理

对于历史记录中持久化了原始图片块或提示注水媒体标记的会话，OpenClaw 还会构建一个独立且幂等的重放视图。

• 它会逐字节保留最近 3 个已完成轮次，以确保近期后续交互的提示缓存前缀保持稳定。此数量包括所有已完成轮次，而不仅是包含图片的轮次，因此纯文本轮次也会占用该窗口。
• 在重放视图中，来自 user 或 toolResult 历史记录中较早且已处理的图片块会被替换为 [图片数据已移除——模型已处理]。
• 较早的文本媒体引用（例如 [media attached: ...]、[Image: source: ...] 和 media://inbound/...）会被替换为 [媒体引用已移除——模型已处理]。当前轮次的附件标记会保持不变，因此视觉模型仍可载入新图片。
• 原始会话记录不会被重写，因此历史记录查看器仍可呈现原始消息条目及其图片。
• 这与上述常规缓存 TTL 修剪相互独立。它用于防止重复图片负载或过时媒体引用导致后续轮次的提示缓存失效。

智能默认值

内置的 Anthropic 插件在首次解析 Anthropic（或 Claude CLI）身份验证配置文件时，会自动配置修剪和 Heartbeat 频率，但仅会配置你尚未显式设置的字段：

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

启用或禁用

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

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

要禁用修剪：将 mode 设置为 "off"。

修剪与压缩对比

两者相辅相成——修剪可在两次压缩周期之间保持工具输出精简。

延伸阅读

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

相关内容

• 会话管理
• 会话工具
• 上下文引擎