Session Pruning（会话修剪）

Session Pruning 在每次 LLM 调用前，从上下文中修剪旧工具结果，减少因工具输出（exec 结果、文件读取、搜索结果）积累导致的上下文膨胀，且不修改正常对话文本。

注意：Pruning 仅在内存中操作，不修改磁盘上的会话记录。你的完整历史始终保留。

为什么需要它

长时间会话会积累大量工具输出，撑大上下文窗口，增加成本，并迫使 Compaction 比预期更早触发。

对 Anthropic Prompt Cache 尤其有价值：Cache TTL 到期后，下一次请求需要重新缓存完整 prompt。Pruning 减少了缓存写入量，直接降低费用。

工作原理

1. 等待 Cache TTL 到期（默认 5 分钟）
2. 找出旧工具结果（对话文本不动）
3. 软修剪超大结果——保留头尾，中间插入 ...
4. 硬清除其余结果——替换为占位符
5. 重置 TTL，后续请求复用新缓存

历史遗留图片清理

OpenClaw 还会对旧版会话运行一次幂等清理，处理过去将原始图片块持久化到历史中的情况：

• 保留最近 3 个已完成 turn 的原始字节，确保近期追问的 Prompt Cache 前缀稳定
• 较旧的已处理图片块（user 或 toolResult 历史）替换为 [image data removed - already processed by model]
• 与普通 Cache-TTL Pruning 独立运行

默认开关

OpenClaw 为 Anthropic Profile 自动启用 Pruning：

Profile 类型	Pruning	Heartbeat
Anthropic OAuth/Token（含 Claude CLI 复用）	开启	1 小时
API Key	开启	30 分钟

如果你设置了明确的值，OpenClaw 不会覆盖。

手动启用或关闭

非 Anthropic Provider 默认关闭。启用方法：

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

关闭：设置 mode: "off"。

Pruning vs Compaction

	Pruning	Compaction
做什么	修剪工具结果	总结对话
是否保存	否（每次请求临时操作）	是（写入记录）
作用范围	仅工具结果	整个对话

两者互补——Pruning 在 Compaction 周期之间保持工具输出精简。

FAQ

Q：Pruning 会丢失重要信息吗？ 不会。Pruning 只去除旧的工具结果，不动对话文本，且不修改磁盘记录。

Q：如何查看 Pruning 是否在生效？ 在聊天中用 /status 查看上下文使用情况；对比有无 Pruning 时的 token 数。

延伸阅读

• Compaction — 基于摘要的上下文压缩
• Gateway 配置 — 所有 contextPruning.* 配置项