Skip to main content

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

会话修剪会在每次 LLM 调用之前，从上下文中修剪掉旧的工具结果。它通过移除累积的工具输出（执行结果、文件 读取、搜索结果）来减少上下文膨胀，同时不会重写普通对话文本。
修剪仅在内存中进行 — 它不会修改磁盘上的会话转录记录。 你的完整历史始终会被保留。

​
为什么它很重要

长会话会累积工具输出，从而膨胀上下文窗口。这 会增加成本，并且可能迫使更早进行压缩， 而不是在必要时才进行。 修剪对于 Anthropic 提示缓存 尤其有价值。缓存 TTL 过期后，下一次请求会重新缓存完整提示。修剪会减少 缓存写入大小，从而直接降低成本。

​
工作原理

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

​
旧版图像清理

OpenClaw 还会为那些在历史中保留原始图像块或提示预热媒体标记的会话构建一个单独的幂等重放视图。
  • 它会逐字节保留最近的 3 个已完成轮次，以便最近后续请求的提示 缓存前缀保持稳定。
  • 在重放视图中，来自 user 或 toolResult 历史的较早且已处理过的图像块可以被替换为 [image data removed - already processed by model]。
  • 更早的文本媒体引用，例如 [media attached: ...]、[Image: source: ...] 和 media://inbound/...，可以被替换为 [media reference removed - already processed by model]。当前轮次的 附件标记会保持不变，因此视觉模型仍然可以预热新的 图像。
  • 原始会话转录记录不会被重写，因此历史查看器仍然可以 渲染原始消息条目及其图像。
  • 这与常规的缓存 TTL 修剪是分开的。它的存在是为了防止重复的 图像负载或过时的媒体引用在后续轮次中破坏提示缓存。

​
智能默认值

OpenClaw 会为 Anthropic 配置文件自动启用修剪：
配置文件类型已启用修剪Heartbeat
Anthropic OAuth/token 认证（包括 Claude CLI 复用）是1 小时
API 密钥是30 分钟
如果你设置了显式值，OpenClaw 不会覆盖它们。

​
启用或禁用

对于非 Anthropic 提供商，修剪默认关闭。要启用： 
{
  agents: {
    defaults: {
      contextPruning: { mode: "cache-ttl", ttl: "5m" },
    },
  },
}
要禁用：设置 mode: "off"。

​
修剪 vs 压缩

修剪压缩
是什么修剪工具结果总结对话
保存？否（按请求）是（写入转录记录）
范围仅工具结果整个对话
它们相辅相成 — 修剪会在 压缩周期之间保持工具输出精简。

​
延伸阅读

  • 压缩 — 基于总结的上下文减少
  • 网关配置 — 所有修剪配置项 (contextPruning.*)

​
相关内容