---
read_when:
    - 你想减少由工具输出导致的上下文增长
    - 你想了解 Anthropic 提示词缓存优化
summary: 修剪旧工具结果以保持上下文精简并提升缓存效率
title: 会话剪枝
x-i18n:
    generated_at: "2026-04-05T08:22:07Z"
    model: gpt-5.4
    provider: openai
    source_hash: 1569a50e0018cca3e3ceefbdddaf093843df50cdf2f7bf62fe925299875cb487
    source_path: concepts/session-pruning.md
    workflow: 15
---

# 会话剪枝

会话剪枝会在每次 LLM 调用之前，从上下文中裁剪**旧的工具结果**。它可以减少累积工具输出（exec 结果、文件读取结果、搜索结果）带来的上下文膨胀，同时不会重写普通对话文本。

<Info>
剪枝仅发生在内存中——不会修改磁盘上的会话转录。
你的完整历史始终会被保留。
</Info>

## 为什么它很重要

长会话会积累大量工具输出，从而膨胀上下文窗口。这会增加成本，并可能迫使系统比预期更早进行[压缩](/concepts/compaction)。

剪枝对于 **Anthropic 提示词缓存** 尤其有价值。缓存 TTL 过期后，下一次请求会重新缓存整个提示词。剪枝会减少缓存写入大小，从而直接降低成本。

## 工作原理

1. 等待缓存 TTL 到期（默认 5 分钟）。
2. 找出可进行常规剪枝的旧工具结果（对话文本保持不变）。
3. 对超大的结果进行**软裁剪**——保留开头和结尾，并插入 `...`。
4. 对其余结果进行**硬清空**——替换为占位符。
5. 重置 TTL，以便后续请求复用新的缓存。

## 旧版图像清理

OpenClaw 还会对较旧的 legacy 会话执行一套单独的幂等清理流程，这些会话会在历史中持久化原始图像块。

- 它会逐字节保留**最近 3 个已完成轮次**，以保持最近后续请求的提示词缓存前缀稳定。
- 较早且已处理过的 `user` 或 `toolResult` 历史中的图像块，可以替换为 `[image data removed - already processed by model]`。
- 这与基于缓存 TTL 的常规剪枝不同。它的存在是为了阻止重复图像载荷在后续轮次中持续破坏提示词缓存。

## 智能默认值

OpenClaw 会为 Anthropic 配置文件自动启用剪枝：

| 配置文件类型                                           | 已启用剪枝 | 心跳 |
| ------------------------------------------------------ | ---------- | ---- |
| Anthropic OAuth / token 认证（包括 Claude CLI 复用）  | 是         | 1 小时 |
| API key                                                | 是         | 30 分钟 |

如果你设置了显式值，OpenClaw 不会覆盖它们。

## 启用或禁用

对于非 Anthropic 提供商，剪枝默认关闭。要启用它：

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

要禁用：将 `mode` 设置为 `off`。

## 剪枝与压缩

|            | 剪枝               | 压缩               |
| ---------- | ------------------ | ------------------ |
| **内容**   | 裁剪工具结果       | 总结对话           |
| **保存？** | 否（按请求）       | 是（写入转录）     |
| **范围**   | 仅工具结果         | 整个对话           |

两者相辅相成——剪枝可在压缩周期之间保持工具输出精简。

## 延伸阅读

- [压缩](/concepts/compaction) —— 基于摘要的上下文缩减
- [Gateway 网关配置](/gateway/configuration) —— 所有剪枝配置项
  （`contextPruning.*`）
