Session 裁剪（Session Pruning）

概述

Session Pruning（会话裁剪）在每次 LLM 调用前从上下文中裁剪旧工具结果，减少因累积工具输出（exec 结果、文件读取、搜索结果）导致的上下文膨胀，但不重写普通对话文本。裁剪仅在内存中进行，不修改磁盘上的 session transcript。

核心要点

工作流程：

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

对 Anthropic prompt caching 的价值：cache TTL 过期后下次请求会重新缓存完整 prompt，裁剪减少 cache-write 大小，直接降低成本。

自动启用规则：

Profile 类型	是否启用	Heartbeat
Anthropic OAuth/token	是	1 小时
API key	是	30 分钟

非 Anthropic provider 默认关闭。

与 Compaction 的区别：

	Pruning	Compaction
做什么	裁剪工具结果	摘要整个对话
是否保存	否（per-request）	是（写入 transcript）
范围	仅工具结果	整个对话

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

遗留图片清理（独立于 cache-TTL pruning）：

针对 session 历史中残留的原始图片块或媒体标记，OpenClaw 构建一个独立的幂等重放视图：

• 保留最近 3 个已完成 turn 的原始字节（保持 prompt cache 前缀稳定）
• 旧的 user/toolResult 中已处理的图片块替换为 [image data removed - already processed by model]
• 旧的文本媒体引用（[media attached: ...]、[Image: source: ...]、media://inbound/...）替换为 [media reference removed - already processed by model]
• 当前 turn 的附件标记保持完整（视觉模型仍可处理新图片）
• 原始 session transcript 不被重写，历史查看器仍可渲染原始图片

配置/使用

手动启用（非 Anthropic provider）：

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

禁用：设置 mode: "off"。

相关页面

• compaction - 对话摘要压缩（更重量级的补充）
• context-engine - 上下文引擎与 token 管理
• session - 会话管理
• memory - Memory 持久化