5.13 会话裁剪

会话裁剪是一种智能内存管理策略,在 LLM 调用前自动修剪旧的工具结果,以优化上下文窗口使用和缓存效率。

核心原理

会话裁剪的工作机制:

• 非破坏性: 只修剪传递给 LLM 的内存内容,永不修改磁盘历史记录 (*.jsonl)
• 条件触发: 仅在 Anthropic API 调用时,且模式为 "cache-ttl",距离上次调用超过 TTL 时运行
• 智能保护: 自动跳过图片、用户/助手消息和受保护的助手内容
• 上下文估算: 使用上下文窗口估算 (默认 200k tokens) 来决定裁剪策略

裁剪模式

软修剪 (Soft Trim)

保留工具结果的头部和尾部内容,中间使用省略号:

{
  "softTrim": {
    "maxChars": 4000,     // 保留的最大总字符数
    "headChars": 1500,    // 保留开头的字符数
    "tailChars": 1500     // 保留结尾的字符数
  }
}

当工具输出长度超过阈值时,会保留开头和结尾的关键信息,中间部分用 ... 表示。

硬清除 (Hard Clear)

完全清除工具结果内容,替换为占位符:

{
  "hardClear": {
    "enabled": true,
    "placeholder": "[旧工具结果内容已清除]"
  }
}

这种模式更激进,适用于需要大幅减少上下文的场景。

完整配置

{
  "session": {
    "pruning": {
      // 基础设置
      "mode": "cache-ttl",           // 启用基于缓存 TTL 的裁剪
      "ttl": "5m",                   // 默认5分钟生存时间
      "keepLastAssistants": 3,       // 保留最后3条助手消息不裁剪
      
      // 裁剪阈值
      "softTrimRatio": 0.3,          // 30%上下文使用率时触发软修剪
      "hardClearRatio": 0.5,         // 50%上下文使用率时触发硬清除
      "minPrunableToolChars": 50000, // 最小50000字符才会被裁剪
      
      // 软修剪配置
      "softTrim": {
        "maxChars": 4000,
        "headChars": 1500,
        "tailChars": 1500
      },
      
      // 硬清除配置
      "hardClear": {
        "enabled": true,
        "placeholder": "[旧工具结果内容已清除]"
      },
      
      // 工具过滤器 (支持通配符,不区分大小写)
      "toolFilters": {
        "allow": ["read*", "write*"],  // 白名单:仅裁剪这些工具
        "deny": ["bash", "terminal*"]  // 黑名单:永不裁剪 (优先级更高)
      }
    }
  }
}

配置示例

关闭裁剪

{
  "session": {
    "pruning": {
      "mode": "off"  // 完全禁用会话裁剪
    }
  }
}

基础 TTL 裁剪

{
  "session": {
    "pruning": {
      "mode": "cache-ttl",
      "ttl": "10m",              // 10分钟 TTL
      "keepLastAssistants": 5    // 保留最后5条助手消息
    }
  }
}

限制工具裁剪

{
  "session": {
    "pruning": {
      "mode": "cache-ttl",
      "ttl": "5m",
      "toolFilters": {
        // 只裁剪文件读取工具,保护其他所有工具
        "allow": ["read", "glob"],
        // 永不裁剪 Bash 命令输出 (优先级高于 allow)
        "deny": ["bash"]
      }
    }
  }
}

工作原理

1. 触发检查: 在每次 LLM 调用前,检查距离上次调用是否超过 TTL
2. 上下文评估: 估算当前上下文窗口的使用情况
3. 策略选择:
   • 使用率 < softTrimRatio: 不裁剪
   • softTrimRatio ≤ 使用率 < hardClearRatio: 软修剪
   • 使用率 ≥ hardClearRatio: 硬清除
4. 应用过滤器: 根据 toolFilters 决定哪些工具结果可被裁剪
5. 保护关键内容: 跳过图片、用户/助手消息、最近的助手回复
6. 执行裁剪: 应用软修剪或硬清除策略
7. 重置 TTL: 重置缓存 TTL 窗口,提高后续调用的缓存命中率

优势

• 缓存效率: TTL 到期后重置缓存,减少 cacheWrite 成本
• 上下文优化: 自动清理旧的冗余工具输出,保留关键对话
• 成本控制: 减少超大上下文的 token 消耗和缓存写入费用
• 灵活配置: 支持细粒度的工具级别控制
• 数据安全: 磁盘历史记录始终保持完整,可随时回溯

常用命令

# 查看当前会话的裁剪状态
openclaw status --pruning

# 手动触发会话压缩 (与裁剪不同,这是持久化操作)
/compact

# 查看会话历史 (完整的磁盘记录,未被裁剪影响)
openclaw session history

# 检查 token 使用情况
/status

最佳实践

智能默认值

OpenClaw 根据认证方式自动调整裁剪默认值:

• API Key 认证: 较激进的裁剪策略,帮助控制成本
• OAuth 认证: 较宽松的裁剪策略,提供更好的上下文连续性

相关概念

• 会话管理: 会话的整体管理机制
• 压缩机制: 持久化的会话历史精简
• Token与成本: 理解 token 计算和成本优化
• 上下文管理: 上下文窗口的整体管理