Skip to main content
每个模型都有一个上下文窗口：它能处理的最大 token 数量。当对话接近该限制时，OpenClaw 会将较早的消息压缩成摘要，以便聊天可以继续。

​
工作原理

  1. 较早的对话轮次会被总结为一个压缩条目。
  2. 该摘要会保存在会话转录中。
  3. 最近的消息会保持完整。
OpenClaw 在选择压缩分割点时，会将助手的工具调用与其对应的 toolResult 条目配对保留。如果分割点落在工具块内部，OpenClaw 会移动边界，确保这对内容保持在一起，并保留当前尚未总结的尾部。 完整的对话历史仍保存在磁盘上。压缩只会改变模型在下一轮看到的内容。
新配置会将 agents.defaults.compaction.mode 默认设为 "safeguard"（更严格的保护措施、摘要质量审计）。如需退出，请显式设置 mode: "default"。

​
自动压缩

默认开启自动压缩。当会话接近上下文限制时，或者模型返回上下文溢出错误时（在这种情况下 OpenClaw 会先压缩再重试），它就会运行。 将 agents.defaults.compaction.enabled: false 设置为禁用嵌入式运行时的主动阈值压缩。OpenClaw 的预检和溢出恢复压缩路径仍然可用，同时也支持手动 /compact。 你会看到：
  • 普通 Gateway 日志中出现 embedded run auto-compaction start / complete。
  • 详细模式中出现 🧹 自动压缩完成。
  • /status 显示 🧹 压缩次数: <count>。
在压缩之前，OpenClaw 会自动提醒代理将重要笔记保存到 memory 文件中。这可以防止上下文丢失。
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 可强制执行一次压缩。你也可以附加指令来指导摘要内容：
手动压缩使用 agents.defaults.compaction.keepRecentTokens（默认值：20,000）作为其截断点预算，并在重建的上下文中保留最近的那部分内容。

​
配置

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

​
使用不同的模型

默认情况下，压缩使用代理的主模型。将 agents.defaults.compaction.model 设置为不同的值，可将总结任务委托给更强大或更专门的模型。此覆盖项接受 provider/model-id 字符串，或在 agents.defaults.models 下配置的裸别名：
在压缩开始之前，裸配置别名会被解析为其规范的提供方和模型。如果一个裸值同时匹配别名和已配置的字面模型 ID，则以字面模型 ID 为准。不匹配的裸值会保留为当前活跃提供方上的模型 ID。 这同样适用于本地模型，例如专用于总结的第二个 Ollama 模型：
如果未设置，压缩将从当前活跃的会话模型开始。如果由于适合回退的提供方错误导致总结失败，OpenClaw 会使用该会话现有的模型回退链重试该压缩。回退选择是临时的，不会写回会话状态。显式的 agents.defaults.compaction.model 覆盖项保持精确，不会继承会话回退链。

​
标识符保留

压缩总结默认会保留不透明标识符（identifierPolicy: "strict"）。如需禁用，请改用 identifierPolicy: "off"。自定义指导应在压缩提供方的 summarize() 实现中处理。

​
活跃转录字节守卫

当设置了 agents.defaults.compaction.maxActiveTranscriptBytes 时，如果转录历史达到该大小，OpenClaw 会在运行前触发常规的本地压缩。这对长时间运行的会话很有用，因为提供方侧的上下文管理可以保持模型上下文健康，而持久化的转录历史会持续增长。可设置一个正字节数或类似 "20mb" 的大小字符串以启用；0 或未设置的值会禁用此守卫。它不会按原始字节切分；而是请求正常的压缩管线生成语义摘要。对于 Codex app-server 会话，同一阈值会限制原生 rollout 转录，超大的原生线程会重新从新状态开始。
字节守卫适用于活跃的 SQLite 转录历史。旧版 JSONL 检查点工件不是当前活跃的压缩目标。

​
后继转录

上下文引擎可能会返回一个显式的压缩后继会话标识。OpenClaw 会采用该后继并将检查点元数据记录到其上。内置的 SQLite 压缩器会保留当前会话标识，不会创建第二份运行时转录。 OpenClaw 不再为新的压缩写入单独的 .checkpoint.*.jsonl 副本。现有的旧版检查点文件在仍被引用时仍可使用，并会在正常的会话清理过程中被清除。

​
压缩通知

默认情况下，压缩会静默运行。将 notifyUser 设置为在压缩开始和完成时显示简短状态消息，并在预压缩内存刷新耗尽但回复仍继续时显示降级通知：

​
内存刷新

在压缩之前，OpenClaw 可以运行一个静默内存刷新轮次，将笔记持久化到磁盘。如果这个维护轮次应使用本地模型而不是当前对话模型，请设置 agents.defaults.compaction.memoryFlush.model：
内存刷新模型覆盖是精确的，不会继承活跃会话的回退链。详情和配置请参见 内存。

​
可插拔的压缩提供方

插件可以通过插件 API 上的 registerCompactionProvider() 注册自定义压缩提供方。注册并配置后，OpenClaw 会将摘要生成委托给该提供方，而不是内置的 LLM 流水线。 要使用已注册的提供方，请在配置中设置其 id：
设置 provider 会自动强制 mode: "safeguard"。提供方会接收与内置路径相同的压缩指令和标识符保留策略，而 OpenClaw 在提供方输出后仍会保留最近轮次和拆分轮次后缀上下文。
如果提供方失败或返回空结果，OpenClaw 会回退到内置的 LLM 摘要生成。

​
压缩与修剪

会话修剪 是一个更轻量的补充，它会截断工具输出而不进行摘要。

​
故障排除

压缩过于频繁？ 模型的上下文窗口可能较小，或者工具输出可能较大。尝试启用 会话修剪。 压缩后上下文感觉陈旧？ 使用 /compact Focus on <topic> 来引导摘要，或者启用 内存刷新 以便笔记得以保留。 需要一个全新开始？ /new 会在不压缩的情况下开启一个新会话。 有关高级配置（保留 token、标识符保留、自定义上下文引擎、OpenAI 服务器端压缩），请参见 Session management deep dive。

​
相关内容

  • Session：会话管理和生命周期。
  • Session pruning：截断工具结果。
  • Context：代理轮次的上下文如何构建。
  • Hooks：压缩生命周期钩子（before_compaction、after_compaction）。