6.2 上下文构建与窗口预算

本节以 OpenClaw 的实际机制为准讨论上下文预算：上下文由工作区、技能、会话历史与工具回执共同组成；当工具输出持续累积时，需要在“发送给模型之前”做有规则的裁剪，而不是修改磁盘历史。重点落在 agents.defaults.contextPruning 的行为与调参方法，以及如何用回放与指标验证裁剪没有破坏关键决策。

6.2.1 上下文组成：工作区、技能、会话与工具回执

在 OpenClaw 中，工作区是上下文的第一来源。官方记忆机制明确了几个关键文件的用途：系统提示、技能、工作区说明、长期记忆与每日日志。参考：记忆。

上下文的工程挑战并不在“有没有信息”，而在“信息是否以可用形态被注入”。典型反模式是把大量工具原始输出长期堆在会话里，导致成本、时延与注意力稀释一起失控。

6.2.2 工具结果裁剪：agents.defaults.contextPruning

官方提供 agents.defaults.contextPruning，用于在请求发送到模型之前裁剪旧工具结果。关键点是：它只改变“发送给模型的上下文”，不会修改磁盘上的会话历史，便于回放与审计。参考：工具结果裁剪。

[!IMPORTANT] Session Pruning 目前仅在 mode: "cache-ttl" 且使用 Anthropic API 时生效（含 OpenRouter 上的 Anthropic 模型）。其核心目的是在会话空闲超过 prompt cache TTL 后，裁剪旧工具结果以减少重新缓存的成本。若使用 OpenAI 或其他供应商，此功能暂不适用。

两种裁剪方式。

• 软裁剪（soft-trim）：对过大的工具结果保留头尾，中间插入 ... 并注明原始体积，跳过含图片块的结果。

• 硬清除（hard-clear）：用占位符替换更旧的工具结果（hardClear.placeholder）。

配置示例（以下为启用时的参考默认值，以官方文档为准）：

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl",
        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]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

验收点：在长会话中，模型输入体积可控且稳定；回放同一 trace 时，关键决策不因裁剪发生不可解释漂移。

6.2.3 调参方法：先保护决策证据，再裁剪噪声

调参时建议遵循两个顺序。

1. 先提高工具回注的结构化程度：把关键字段与摘要回注进会话，把全量输出落盘为证据引用。

2. 再调 contextPruning 的阈值与工具排除列表：避免裁剪掉真正需要的“证据段”。

当出现“工具已调用但模型忽略”时，先检查工具回注是否被硬清除，而不是先改提示词。

6.2.4 验证命令：用状态与回放验证裁剪效果

操作示例：观察系统状态与模型侧错误分布，确认裁剪没有引入异常重试或格式错误。

openclaw status --all

操作示例：统计裁剪相关事件或占位符出现频率，判断是否过度裁剪。日志字段以实际实现为准。

cat runtime.log | rg "Old tool result content cleared" | wc -l