Session Pruning

Session pruning 会在每次调用 LLM 之前，从内存中的 Context 里修剪掉旧的工具结果。它不会改写磁盘上的 Session 历史记录（*.jsonl 文件）。

什么时候运行

当 mode: "cache-ttl" 启用，且该 Session 上次调用 Anthropic API 的时间超过 ttl 时触发。
只影响本次请求发送给模型的消息。
只对 Anthropic API 调用生效（包括 OpenRouter 的 Anthropic 模型）。
为了获得最佳效果，建议让 ttl 和模型的 cacheControlTtl 保持一致。
修剪执行后，TTL 窗口会重置，后续请求会继续使用缓存，直到 ttl 再次过期。

智能默认值（Anthropic）

OAuth 或 setup-token 配置：启用 cache-ttl 修剪，Heartbeat 设为 1h。
API key 配置：启用 cache-ttl 修剪，Heartbeat 设为 30m，Anthropic 模型的 cacheControlTtl 默认为 1h。
如果你手动设置了这些值，OpenClaw 不会覆盖它们。

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

为什么要修剪： Anthropic 的 Prompt 缓存只在 TTL 内有效。如果 Session 闲置超过 TTL，下次请求会重新缓存完整的 Prompt，除非你先修剪掉一部分。
什么变便宜了： 修剪会减少 TTL 过期后第一次请求的 cacheWrite 大小。
为什么 TTL 重置很重要： 一旦修剪运行，缓存窗口会重置，后续请求可以复用刚缓存的 Prompt，而不是再次重新缓存完整历史。
它不会做什么： 修剪不会增加 Token 或”双倍”成本；它只是改变了 TTL 过期后第一次请求缓存的内容。

什么可以被修剪

只有 toolResult 消息。
用户和 Assistant 消息永远不会被修改。
最后 keepLastAssistants 条 Assistant 消息会被保护；这个截止点之后的工具结果不会被修剪。
如果 Assistant 消息数量不足以确定截止点，修剪会被跳过。
包含图片块的工具结果会被跳过（永远不会被修剪/清除）。

Context 窗口估算

修剪使用估算的 Context 窗口（字符数 ≈ Token 数 × 4）。基础窗口按以下顺序解析：

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

如果设置了 agents.defaults.contextTokens，它会被当作解析窗口的上限（最小值）。

模式

cache-ttl

只有当上次 Anthropic 调用的时间超过 ttl（默认 5m）时，修剪才会运行。
运行时：和之前一样的 soft-trim + hard-clear 行为。

Soft 修剪 vs Hard 修剪

Soft-trim：只针对过大的工具结果。
- 保留头部 + 尾部，插入 ...，并附加一条说明原始大小的注释。
- 跳过包含图片块的结果。
Hard-clear：用 hardClear.placeholder 替换整个工具结果。

工具选择

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

与其他限制的交互

内置工具已经会截断自己的输出；Session pruning 是额外的一层，防止长时间对话在模型 Context 中积累过多工具输出。
Compaction 是独立的：Compaction 会总结并持久化，Pruning 是每次请求的临时操作。参见 /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]" }

示例

默认（关闭）：

{
  agent: {
    contextPruning: { mode: "off" },
  },
}

启用基于 TTL 的修剪：

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

限制修剪特定工具：

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

参见配置参考：Gateway Configuration