会话修剪

会话修剪会在每次 LLM 调用前，从内存中的上下文里裁剪较早的工具结果。它不会改写磁盘上的会话历史（*.jsonl）。

触发时机

当启用 mode: "cache-ttl" 且该会话上次 Anthropic 调用距今超过 ttl 时执行。
只影响当次请求发送给模型的消息。
仅对 Anthropic API 调用（以及 OpenRouter 的 Anthropic 模型）生效。
为了达到最佳效果，建议把 ttl 与模型的 cacheRetention 策略对齐（short = 5 分钟，long = 1 小时）。
修剪执行后 TTL 窗口会重置，后续请求可以继续利用缓存，直到 ttl 再次到期。

智能默认值（Anthropic）

OAuth 或 setup-token 配置：启用 cache-ttl 修剪，心跳设为 1h。
API key 配置：启用 cache-ttl 修剪，心跳设为 30m，Anthropic 模型默认 cacheRetention: "short"。
如果你显式设置了这些值，OpenClaw 不会覆盖它们。

这能改善什么（成本 + 缓存行为）

为什么要修剪： Anthropic 的 prompt 缓存只在 TTL 内有效。如果会话空闲超过 TTL，下次请求会重新缓存整个 prompt——除非你先做裁剪。
哪些成本降低了： 修剪减少了 TTL 过期后第一次请求的 cacheWrite 大小。
TTL 重置为什么重要： 修剪完成后缓存窗口重置，后续请求可以复用刚缓存的 prompt，不必再次缓存完整历史。
它不做什么： 修剪不会增加 token 或”翻倍”成本——它只改变 TTL 过期后那次请求的缓存写入内容。

可以修剪的内容

仅限 toolResult 消息。
用户消息和助手消息绝不会被修改。
最后 keepLastAssistants 条助手消息受保护；在此截断点之后的工具结果不会被修剪。
如果助手消息数量不足以确定截断点，则跳过修剪。
包含图片块的工具结果会被跳过（不会被裁剪或清除）。

上下文窗口估算

修剪使用估算的上下文窗口大小（字符数 ≈ token 数 × 4）。基础窗口按以下优先级确定：

models.providers.*.models[].contextWindow 覆盖值。
模型定义中的 contextWindow（来自模型注册表）。
默认 200000 token。

如果设置了 agents.defaults.contextTokens，它会作为上限值（取较小值）。

模式

cache-ttl

仅当上次 Anthropic 调用距今超过 ttl（默认 5m）时才执行修剪。
执行时：同样的 soft-trim + hard-clear 行为。

软修剪 vs 硬清除

软修剪（Soft-trim）：只针对过大的工具结果。
- 保留头部和尾部，中间插入 ...，末尾附加原始大小说明。
- 跳过包含图片块的结果。
硬清除（Hard-clear）：用 hardClear.placeholder 替换整个工具结果。

工具筛选

tools.allow / tools.deny 支持 * 通配符。
deny 优先。
匹配不区分大小写。
allow 列表为空 => 允许所有工具。

与其他限制的交互

内置工具已经会截断自身输出；会话修剪是额外的一层，防止长时间运行的对话在模型上下文中积累过多的工具输出。
压缩（Compaction）是独立的：压缩会总结并持久化，修剪只是每次请求的临时操作。参见 /concepts/compaction。

默认值（启用时）

ttl: "5m"
keepLastAssistants: 3
softTrimRatio: 0.3
hardClearRatio: 0.5
minPrunableToolChars: 50000
softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }
hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }

示例

默认关闭：

{
  agents: { defaults: { contextPruning: { mode: "off" } } },
}

启用 TTL 感知修剪：

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

限定只对特定工具修剪：

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl",
        tools: { allow: ["exec", "read"], deny: ["*image*"] },
      },
    },
  },
}

配置参考：Gateway Configuration