跳到主要内容

会话剪裁 (Session Pruning)

会话剪裁在每次 LLM 调用之前，从内存上下文中修剪旧的工具执行结果。它不会重写磁盘上的会话历史记录 (*.jsonl)。

何时运行​

  • 当启用 mode: "cache-ttl" 且该会话的最后一次 Anthropic 调用时间早于 ttl 时。
  • 仅影响该请求发送给模型的消息。
  • 仅对 Anthropic API 调用（以及 OpenRouter 中的 Anthropic 模型）有效。
  • 为了获得最佳效果，请将 ttl 与模型的 cacheControlTtl 设置匹配。
  • 剪裁运行后，TTL 窗口会重置，因此后续请求会保持缓存，直到 ttl 再次过期。

智能默认值 (Anthropic)​

  • OAuth 或 setup-token 配置文件：启用 cache-ttl 剪裁，并将心跳 (heartbeat) 设置为 1h。
  • API key 配置文件：启用 cache-ttl 剪裁，心跳设置为 30m，并将 Anthropic 模型的默认 cacheControlTtl 设置为 1h。
  • 如果您显式设置了其中任何值，Clawdbot 不会覆盖它们。

改进了什么（成本 + 缓存行为）​

  • 为什么要剪裁： Anthropic 的提示词缓存仅在 TTL 内有效。如果会话闲置时间超过 TTL，下一次请求将重新缓存完整提示词，除非您先对其进行修剪。
  • 什么变得更便宜： 剪裁减少了 TTL 过期后第一次请求的 cacheWrite 大小。
  • 为什么 TTL 重置很重要： 剪裁运行后，缓存窗口会重置，因此后续请求可以重用新缓存的提示词，而不是再次重新缓存完整历史记录。
  • 它不做什么： 剪裁不会增加令牌或导致“双倍”成本；它只改变 TTL 后第一次请求中被缓存的内容。

哪些内容可以被剪裁​

  • 仅限 toolResult 消息。
  • 用户 (User) 和助手 (Assistant) 的消息绝不会被修改。
  • 最后 keepLastAssistants 条助手的消息受到保护；在此截止点之后的工具结果不会被剪裁。
  • 如果没有足够的助手消息来建立截止点，则跳过剪裁。
  • 包含图像块 (image blocks) 的工具结果将被跳过（从不修剪/清除）。

上下文窗口估计​

剪裁使用估计的上下文窗口（字符数 ≈ 令牌数 × 4）。窗口大小按以下顺序解析：

  1. 模型定义的 contextWindow（来自模型注册表）。
  2. models.providers.*.models[].contextWindow 覆盖设置。
  3. agents.defaults.contextTokens。
  4. 默认 200000 令牌。

模式​

cache-ttl​

  • 仅当最后一次 Anthropic 调用早于 ttl（默认 5m）时运行剪裁。
  • 运行时：采用与以前相同的软修剪 (soft-trim) + 硬清除 (hard-clear) 行为。

软剪裁 vs 硬剪裁​

  • 软修剪 (Soft-trim)：仅针对过大的工具结果。
    • 保留头部和尾部，插入 ...，并追加一条包含原始大小的注释。
    • 跳过包含图像块的结果。
  • 硬清除 (Hard-clear)：将整个工具结果替换为 hardClear.placeholder。

工具选择​

  • tools.allow / tools.deny support * wildcards.
  • 拒绝 (Deny) 优先。
  • 匹配不区分大小写。
  • 空白允许列表 => 允许所有工具。

与其他限制的交互​

  • 内置工具已经会截断自己的输出；会话剪裁是一个额外的层，用于防止长期运行的聊天在模型上下文中累积过多的工具输出。
  • 压缩 (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]" }

示例​

默认（关闭）：

{
  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)