修剪仅在内存中进行——它不会修改磁盘上的会话记录。你的完整历史始终会被保留。
为什么它很重要
长时间会话会累积工具输出，从而膨胀上下文窗口。这会增加成本，并可能比必要时更早地强制进行压缩。 修剪对于 Anthropic 提示缓存 尤其有价值。缓存 TTL 过期后，下一次请求会重新缓存完整提示。修剪会减少缓存写入大小，从而直接降低成本。工作原理
Pruning 在cache-ttl 模式下运行，同时受时间检查和上下文大小检查的约束：
- 等待缓存 TTL 过期（手动设置时默认为 5 分钟；有关 Anthropic 的自动默认值，请参阅智能默认值）。在 TTL 结束前，将完全跳过清理，以保留相邻轮次的提示缓存复用。
- TTL 结束后，根据模型的上下文窗口估算总上下文大小。使用率低于约 30% 时，将跳过清理，并让 TTL 时钟继续运行。
- 软裁剪过大的工具结果：超过 4,000 个字符的结果将保留开头和结尾各 1,500 个字符，并在中间添加
...。 - 如果上下文使用率仍处于约 50% 或更高，且至少还剩 50,000 个字符的可清理工具内容，则对这些结果执行硬清除：将其内容替换为占位符（默认为
[Old tool result content cleared]，可通过agents.defaults.contextPruning.hardClear.placeholder配置；设置hardClear.enabled: false可跳过此步骤）。 - 仅当清理实际改变了上下文时，才会重置 TTL 时钟，以便后续请求复用新鲜缓存。
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 剪枝，除非你进行配置。
启用或禁用
对于非 Anthropic 提供商，修剪默认关闭。要启用：mode: "off"。
修剪 vs 压缩
它们相辅相成——修剪在每次压缩周期之间保持工具输出精简。