OpenClaw 上下文压缩：工具调用配对保留与修剪机制的区别

核心洞察

上下文压缩OpenClaw 将较早的消息汇总为摘要，使聊天能够继续的机制。这事，很多人以为只是"把旧消息删掉"，其实 OpenClaw 的处理比这细致得多。最让我意外的是它会把工具调用和对应的 toolResult 配对保留，拆分点落在工具块内部时会自动挪边界，这个细节说明设计者确实踩过坑。另外，压缩和修剪是两套独立机制，别搞混了。

每个模型都有一个上下文窗口LLM处理输入文本时的长度限制，超出部分可能被截断或忽略，影响模型对长内容的整体理解。，也就是它能处理的最大 token 数。对话一旦接近这个上限，OpenClaw 就会把较早的消息压缩成摘要，让聊天能继续下去。

核心结论

1. OpenClaw 的上下文压缩会将较早的对话轮次汇总为精简摘要并保存在会话转录记录中，近期消息保持完整，完整对话历史记录仍保留在磁盘上，压缩只改变模型在下一轮看到的内容。

2. 自动压缩默认启用的压缩方式，在会话接近上下文限制或模型返回上下文溢出错误时运行。默认开启，当会话接近上下文限制或模型返回上下文溢出错误时触发；OpenClaw 可识别数十种提供商特定的溢出错误字符串（如 request_too_large、context length exceeded、Bedrock 的 input token count exceeds the maximum number of input tokens 等）。

3. 压缩拆分点会配对保留智能体的工具调用和对应的 toolResult 条目，若拆分点落在工具块内部，OpenClaw 会自动移动边界使配对内容待在一起。

4. 压缩与修剪是两套独立机制：压缩汇总较早对话并保存到会话转录记录，作用于整个对话；修剪仅修剪旧工具结果，不保存，仅在内存中按请求生效。

5. 手动压缩通过输入 /compact 命令强制执行的压缩，可附加指令引导摘要内容。可通过 /compact 强制执行并附加指令引导摘要内容；设置 agents.defaults.compaction.keepRecentTokens（默认值 20,000）时手动压缩会遵循该截断点，未指定保留预算时则作为硬检查点仅从新摘要继续。

工作原理

1. 较早的对话轮次汇总成一个精简条目。
2. 摘要保存在会话转录记录里。
3. 近期消息保持完整。

OpenClaw 选择压缩拆分点的时候，会把智能体的工具调用和对应的 toolResult 条目配对保留。如果拆分点正好落在工具块内部，OpenClaw 会移动边界，让配对内容待在一起，同时保留当前未摘要的尾部内容。

完整的对话历史记录仍然存在磁盘上。压缩只改变模型在下一轮看到的内容。

自动压缩

自动压缩默认开启。会话接近上下文限制时它会运行，或者模型返回上下文溢出错误时也会触发（这种情况下 OpenClaw 会压缩后重试）。

你会看到这些：

• 正常 Gateway 网关日志中的 embedded run auto-compaction start / complete。
• 详细模式下的 🧹 Auto-compaction complete。
• /status 中显示的 🧹 Compactions: <count>。

OpenClaw 可识别的溢出错误模式

OpenClaw 会匹配数十种提供商特定的溢出错误字符串（Anthropic、OpenAI、Bedrock、Gemini、Ollama、OpenRouter 等）。常见示例：

• request_too_large
• context length exceeded
• input exceeds the maximum number of tokens
• input token count exceeds the maximum number of input tokens（Bedrock）
• input is too long for the model
• ollama error: context length exceeded

手动压缩

在任意聊天中输入 /compact 可以强制执行压缩。加上指令能引导摘要内容：

/compact 重点关注 API 设计决策

设置 agents.defaults.compaction.keepRecentTokens 时（默认值：20,000），手动压缩会遵循该截断点，并在重建的上下文中保留近期尾部内容。如果没有明确指定保留预算，手动压缩就作为硬检查点，仅从新摘要继续。

配置

在你的 openclaw.json 中，通过 agents.defaults.compaction 配置压缩。下面列出最常用的选项；完整参考请看会话管理深入解析。

使用其他模型

默认情况下，压缩使用智能体的主模型。设置 agents.defaults.compaction.model 可以把摘要任务交给能力更强或更专业的模型。这个覆盖项接受 provider/model-id 字符串，或者在 agents.defaults.models 下配置的纯别名：

{
  "agents": {
    "defaults": {
      "compaction": {
        "model": "openrouter/anthropic/claude-sonnet-4-6"
      }
    }
  }
}

压缩开始前，已配置的纯别名会解析为对应的规范提供商和模型。如果一个纯值同时匹配别名和已配置的字面模型 ID，字面模型 ID 优先。未匹配的纯值仍然作为当前提供商上的模型 ID 使用。

这个功能也适用于本地模型，比如专门用来做摘要的第二个 Ollama 模型：

{
  "agents": {
    "defaults": {
      "compaction": {
        "model": "ollama/llama3.1:8b"
      }
    }
  }
}

未设置时，压缩从当前会话模型开始。如果摘要因为符合模型回退条件的提供商错误而失败，OpenClaw 会通过会话现有的模型回退链重试这次压缩。回退选择是临时的，不会写回会话状态。显式的 agents.defaults.compaction.model 覆盖项保持精确，不会继承会话回退链。

标识符保留压缩摘要默认保留不透明标识符（identifierPolicy: "strict"），可通过 identifierPolicy: "off" 禁用。

压缩摘要默认保留不透明标识符（identifierPolicy: "strict"）。可以用 identifierPolicy: "off" 覆盖来禁用。自定义指导应该放在压缩提供商的 summarize() 实现中。

活跃转录记录字节防护

设置 agents.defaults.compaction.maxActiveTranscriptBytes 后，如果转录历史记录达到该大小，OpenClaw 会在运行前触发常规本地压缩。这适用于长期运行的会话：提供商侧的上下文管理可能让模型上下文保持健康，但持久化的转录历史记录会持续增长。它不会拆分原始字节，而是要求常规压缩流水线创建语义摘要。

后继转录记录

启用 agents.defaults.compaction.truncateAfterCompaction 后，OpenClaw 不会就地重写现有转录记录。它会根据压缩摘要、保留的状态和未摘要的尾部内容创建新的活跃后继转录记录，然后记录检查点元数据，把分支/恢复流程指向该压缩后的后继记录。后继转录记录还会丢弃在较短重试时间窗口内出现的完全重复的长用户轮次，这样渠道重试风暴不会在压缩后带入下一个活跃转录记录。

对于新的压缩，OpenClaw 不再写入单独的 .checkpoint.*.jsonl 副本。现有的旧版检查点文件在仍被引用时可以继续使用，并由常规会话清理进行修剪。

压缩通知

默认情况下，压缩静默运行。设置 notifyUser 后，可以在压缩开始和完成时显示简短的状态消息；如果压缩前的记忆刷新压缩前运行的静默轮次，将持久笔记保存到磁盘，可使用本地模型。耗尽但回复仍继续，还会显示降级通知：

{
  agents: {
    defaults: {
      compaction: {
        notifyUser: true,
      },
    },
  },
}

记忆刷新

压缩前，OpenClaw 可以运行一次静默记忆刷新轮次，把持久笔记保存到磁盘。如果希望这个维护轮次使用本地模型而非当前对话模型，请设置 agents.defaults.compaction.memoryFlush.model：

{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "model": "ollama/qwen3:8b"
        }
      }
    }
  }
}

记忆刷新模型覆盖项是精确的，不会继承当前会话回退链。详细信息和配置请看记忆。

可插拔压缩提供商插件通过 registerCompactionProvider() 注册的自定义压缩提供商，OpenClaw 会将摘要任务委托给它。

插件可以通过插件 API 上的 registerCompactionProvider() 注册自定义压缩提供商。提供商已注册并配置后，OpenClaw 会把摘要任务委托给它，而不是使用内置的 LLM 流水线。

要使用已注册的提供商，在配置中设置它的 ID：

{
  "agents": {
    "defaults": {
      "compaction": {
        "provider": "my-provider"
      }
    }
  }
}

设置 provider 会自动强制启用 mode: "safeguard"。提供商会收到与内置路径相同的压缩指令和标识符保留策略，并且 OpenClaw 仍会在提供商输出后保留近期轮次和拆分轮次的后缀上下文。

压缩与修剪

会话修剪是一种更轻量的补充机制，不需要摘要就能修剪工具输出。

故障排查

压缩过于频繁？ 模型的上下文窗口可能较小，或者工具输出可能较大。试试启用会话修剪。

压缩后感觉上下文陈旧？ 用 /compact Focus on <topic> 引导摘要，或者启用记忆刷新来保留笔记。

需要从头开始？ /new 会启动一个新会话，不进行压缩。

高级配置（预留 token、标识符保留、自定义上下文引擎、OpenAI 服务端压缩）请看会话管理深入解析。

相关内容

• 会话：会话管理和生命周期。
• 会话修剪：修剪工具结果。
• 上下文：如何为智能体轮次构建上下文。
• Hooks：压缩生命周期钩子（before_compaction、after_compaction）。

常见问题（FAQ）

OpenClaw 压缩后，之前的聊天记录会丢失吗？

不会。压缩只改变模型下一轮看到的内容，完整对话历史仍保存在磁盘上。摘要会写入会话转录记录，近期消息保持完整，你随时可以回溯原始记录。

压缩和修剪有什么区别？

压缩是把较早对话汇总成摘要并保存在会话转录记录中，范围是整个对话；修剪只针对旧工具结果，仅在内存中按请求生效，不保存，两者是独立机制。

压缩时工具调用和结果会被拆开吗？

不会。OpenClaw 选择拆分点时会配对保留工具调用和对应的 toolResult，若拆分点落在工具块内部会自动移动边界，让配对内容待在一起。