会话修剪

会话修剪在每�?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 密钥 配置：启�?cache-ttl 修剪，将心跳设置�?30m，并�?Anthropic 模型上默�?cacheRetention: "short"�?
  • 如果你明确设置这些值中的任何一个，OpenClaw 不会覆盖它们�?

这改善了什么（成本 + 缓存行为�?

  • 为什么修剪： Anthropic 提示缓存仅在 TTL 内适用。如果会话空闲超�?TTL，下一个请求会重新缓存完整提示，除非你先修剪它�?
  • *什么变得更便宜�? 修剪减少�?TTL 过期后第一个请求的 cacheWrite 大小�?
  • *为什�?TTL 重置重要�? 修剪运行后，缓存窗口重置，因此后续请求可以重用新缓存的提示，而不是重新缓存完整历史�?
  • 它不做什么： 修剪不会添加令牌�?加�?成本；它只改变在 TTL 过期后第一个请求上缓存的内容�?

可以修剪什�?

  • �?toolResult 消息�?
  • 用户 + 助手消息永远不会修改�?
  • 最�?keepLastAssistants 助手消息受到保护；该截止点之后的工具结果不会被修剪�?
  • 如果没有足够的助手消息来建立截止点，跳过修剪�?
  • 包含**图像�?*的工具结果会被跳过（永远不会被修�?清除）�?

上下文窗口估�?

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

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

如果设置�?agents.defaults.contextTokens，它被视为解析窗口的上限（最小值）�?

模式

cache-ttl

  • 修剪仅在最后一�?Anthropic 调用早于 ttl（默�?5m）时运行�?
  • 运行时：与之前相同的软修�?+ 硬清除行为�?

软修�?vs 硬清�?

  • **软修�?*：仅对过大的工具结果�?
    • 保留头部 + 尾部，插�?...，并附加包含原始大小的注释�?
    • 跳过包含图像块的结果�?
  • **硬清�?*：用 hardClear.placeholder 替换整个工具结果�?

工具选择

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

与其他限制的交互

  • 内置工具已经截断了自己的输出；会话修剪是额外的一层，防止长时间运行的聊天在模型上下文中积累过多的工具输出�?
  • 压缩是独立的：压缩总结并持久化，而修剪是每个请求的临时层。请参阅 /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*"] },
      },
    },
  },
}

请参阅配置参考：网关配置