Session 裁剪

Session 裁剪在每次 LLM 调用前从内存上下文中修剪旧工具结果。它不重写磁盘上的 session 历史（*.jsonl）。

何时运行

• 启用 mode: "cache-ttl" 后，当该 session 的最后一次 Anthropic 调用超过 ttl 时运行。
• 仅影响发送给模型的当次请求消息。
• 仅对 Anthropic API 调用有效（以及 OpenRouter Anthropic 模型）。
• 为获得最佳效果，ttl 应与你的模型 cacheRetention 策略匹配（short = 5m，long = 1h）。
• 裁剪后，TTL 窗口重置，后续请求可继续复用缓存直到 ttl 再次到期。

智能默认值（Anthropic）

• OAuth 或 setup-token profile：启用 cache-ttl 裁剪并将心跳设为 1h。
• API key profile：启用 cache-ttl 裁剪，将心跳设为 30m，并在 Anthropic 模型上默认 cacheRetention: "short"。
• 若你显式设置了上述任何值，OpenClaw 不会覆盖它们。

改善的内容（成本 + 缓存行为）

• 为何裁剪：Anthropic prompt 缓存仅在 TTL 内有效。若 session 空闲超过 TTL，下次请求会重新缓存完整 prompt，除非先裁剪。
• 成本降低的地方：裁剪减少了 TTL 过期后第一次请求的 cacheWrite 大小。
• TTL 重置的作用：裁剪运行后，缓存窗口重置，后续请求可复用新缓存的 prompt，而无需再次重缓存完整历史。
• 不做什么：裁剪不增加 token，也不"双倍"计费；它只改变那次 TTL 后第一次请求的缓存内容。

可裁剪的内容

• 仅 toolResult 消息。
• 用户和 assistant 消息永不被修改。
• 最后 keepLastAssistants 条 assistant 消息受保护；该截止点之后的工具结果不会被裁剪。
• 若 assistant 消息不足以确定截止点，裁剪跳过。
• 包含图像块的工具结果跳过（永不修剪/清空）。

上下文窗口估算

裁剪使用估算的上下文窗口（字符数 ≈ token 数 × 4）。基础窗口按以下顺序解析：

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

若设置了 agents.defaults.contextTokens，它被视为解析窗口的上限（min）。

模式

cache-ttl

• 仅当该 session 的最后一次 Anthropic 调用超过 ttl（默认 5m）时才运行裁剪。
• 运行时：与之前相同的软修剪 + 硬清除行为。

软修剪 vs 硬清除

• 软修剪：仅针对超大工具结果。
  • 保留头部 + 尾部，插入 ...，并追加原始大小的说明。
  • 跳过包含图像块的结果。
• 硬清除：用 hardClear.placeholder 替换整个工具结果。

工具选择

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

与其他限制的交互

• 内置工具已自行截断输出；session 裁剪是额外的一层，防止长时间运行的聊天在模型上下文中积累过多工具输出。
• 压缩（compaction）是独立的：压缩会总结并持久化，裁剪是每次请求的临时操作。参见 /openclaw/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*"] },
      },
    },
  },
}

小龙虾的记忆也需要定期清理——session 裁剪就是它的"选择性遗忘"机制，帮你省钱又保速度。

配置参考：Gateway 配置