会话修剪

Session Pruning（会话修剪）是 OpenClaw 防止上下文溢出（Context Overflow）的核心机制。它在每次 LLM 调用前自动裁剪历史消息，确保上下文窗口不被耗尽。

为什么需要修剪

上下文溢出风险

每个 LLM 都有固定的上下文窗口（Context Window）。当对话历史积累过多 Token 时，新消息将无法被处理。修剪通过移除最旧的消息来为新内容腾出空间。

未修剪的上下文：
┌─────────────────────────────┐
│ System Prompt (10K tokens)  │
│ Message 1 (很久之前)        │
│ Message 2                   │
│ ...                         │
│ Message 100 (最近)          │
│ ✘ 超出 128K 上下文窗口！     │
└─────────────────────────────┘

修剪后的上下文：
┌─────────────────────────────┐
│ System Prompt (10K tokens)  │
│ [历史已压缩摘要]            │
│ Message 85                  │
│ ...                         │
│ Message 100 (最近)          │
│ ✓ 在 128K 窗口内            │
└─────────────────────────────┘

修剪策略

OpenClaw 支持多种修剪策略，可组合使用：

Token 限制（Token-Based）

基于 Token 数量限制历史消息：

pruning:
  strategy: token
  maxHistoryTokens: 80000    # 保留最多 80K tokens 的历史
  reserveForResponse: 4096   # 为回复预留 4K tokens

计算公式：

可用历史 Tokens = 模型上下文窗口
                - System Prompt Tokens
                - reserveForResponse
                - 当前轮次 Tool Result Tokens

时间限制（Time-Based）

基于时间窗口限制历史消息：

pruning:
  strategy: time
  maxHistoryAge: 86400       # 保留最近 24 小时的消息（秒）

消息数量限制（Count-Based）

pruning:
  strategy: count
  maxHistoryMessages: 50     # 保留最近 50 条消息

混合策略

多种策略可以组合，取最严格的结果：

pruning:
  strategy: hybrid
  maxHistoryTokens: 80000
  maxHistoryMessages: 100
  maxHistoryAge: 172800      # 48 小时

推荐配置

大多数场景建议使用混合策略，同时设置 Token 上限和消息数量上限作为双重保障。

工具结果裁剪

Tool Result（工具执行结果）在发送给 LLM 前会进行特殊裁剪：

toolResultTrimming:
  maxResultLength: 8000      # 单个工具结果最大字符数
  maxImagePayload: 1048576   # 图片载荷最大 1MB
  truncationSuffix: "\n...[result truncated]"

裁剪规则：

场景	处理方式
文本结果过长	截断到 maxResultLength，附加截断提示
图片载荷	转换为 URL 引用或缩略图
二进制数据	替换为摘要描述
JSON 结果	保留结构，截断嵌套值

JSONL 不受影响

修剪仅影响发送给 LLM 的上下文。JSONL 转录文件（磁盘上的历史记录）保持完整，不会被修改。

修剪执行时机

修剪在以下时刻自动执行：

1. 每次 LLM 调用前 — 确保上下文在窗口限制内
2. 会话恢复时 — 从 JSONL 加载历史后立即修剪
3. 手动压缩后 — 压缩（Compaction）完成后重新评估

消息入队 → 加载历史 → 修剪 → 构建上下文 → LLM 调用
                        ↑
                  Token 计算 + 策略评估

修剪日志

修剪操作会记录到日志中，方便排查问题：

[PRUNE] Session general::user123
  - Before: 156 messages, ~95K tokens
  - Removed: 82 messages (oldest first)
  - After: 74 messages, ~48K tokens
  - Strategy: hybrid (token limit hit)

配置示例

保守策略

# 适合长对话、大窗口模型
pruning:
  strategy: token
  maxHistoryTokens: 100000
  reserveForResponse: 8192

激进策略

# 适合短对话、小窗口模型
pruning:
  strategy: hybrid
  maxHistoryTokens: 20000
  maxHistoryMessages: 30
  maxHistoryAge: 3600

均衡策略

# 推荐大多数场景
pruning:
  strategy: hybrid
  maxHistoryTokens: 60000
  maxHistoryMessages: 80
  reserveForResponse: 4096

与压缩的关系

修剪（Pruning）和 压缩（Compaction） 是互补的上下文管理机制：

特性	修剪 Pruning	压缩 Compaction
方式	直接丢弃旧消息	摘要化旧消息
信息保留	无	保留关键信息
性能开销	极低	需要额外 LLM 调用
触发方式	每次自动	阈值触发或手动

下一步

• 了解 压缩机制 的摘要化策略
• 查看 上下文管理 了解完整输入管理
• 探索 会话管理 了解会话生命周期