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

6.2.5 可插拔上下文引擎

从 2026.3 版本起，OpenClaw 的上下文管理不再是硬编码的单一实现，而是抽象为上下文引擎（Context Engine）接口。内置的 legacy 引擎提供前述的裁剪和压缩行为；插件可以注册自定义引擎来完全替换上下文的组装、摄入、压缩和子智能体传递逻辑。

上下文引擎的生命周期方法包括：

• assemble：在每次模型调用前，将会话历史按 token 预算组装为有序消息列表。引擎可以在此阶段注入检索结果、调整消息顺序或插入系统提示词片段。

• ingest / ingestBatch：每轮对话后将新消息摄入引擎存储，供后续 assemble 使用。

• compact：当上下文接近预算时压缩历史，可实现摘要、合并或外部向量化等策略。

• maintain：在引导、成功轮次或压缩后执行转录维护，通过运行时提供的 rewriteTranscriptEntries() 安全地修改会话 DAG。

• afterTurn：轮次结束后的持久化和后台决策钩子。

通过 plugins.slots.contextEngine 配置项可以将自定义引擎绑定到指定的插件。当引擎声明 ownsCompaction: true 时，运行时会将压缩决策完全委托给该引擎，不再触发内置的自动压缩流程。这为需要深度定制上下文策略的场景（如 RAG 增强、长期记忆向量化、领域特定的摘要算法）提供了无侵入的扩展点。

---

📚 延伸阅读：上下文工程是智能体性能的关键杠杆。关于上下文窗口管理、信息密度优化和多轮对话架构的系统性方法论，参见 《大模型上下文工程权威指南》。