压缩

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

工作原理

较早的对话轮次会被总结为一个压缩条目。
摘要会保存在会话记录中。
最近的消息会保持原样。

当 OpenClaw 将历史记录拆分为压缩块时，它会确保助手工具调用与其匹配的 OpenClawtoolResultOpenClaw 条目保持配对。如果拆分点位于工具块内，OpenClaw 会移动边界以保持这对内容在一起，并保留当前未汇总的尾部。

完整的对话历史记录会保留在磁盘上。压缩仅改变模型在下一轮所看到的内容。

自动压缩

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

您将会看到：

embedded run auto-compaction start / completeGateway(网关) 在普通 Gateway(网关) 日志中。
🧹 Auto-compaction complete 在详细模式中。
/status 显示 🧹 Compactions: <count>。

Recognized overflow signatures

OpenClaw 会根据以下提供商错误模式检测上下文溢出：

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

手动压缩

在任何聊天中输入 /compact 以强制执行压缩。添加指令以指导摘要生成：

/compact Focus on the API design decisions

当设置了 agents.defaults.compaction.keepRecentTokens 时，手动压缩会遵循 OpenClaw 的切断点，并在重建的上下文中保留最近的尾部。如果没有显式的保留预算，手动压缩将表现为硬检查点，并仅从新的摘要继续。

配置

在您的 openclaw.json 中的 agents.defaults.compaction 下配置压缩。下面列出了最常用的调整项；完整的参考信息请参阅 Session management deep dive。

使用不同的模型

默认情况下，压缩使用代理的主要模型。设置 agents.defaults.compaction.model 以将摘要任务委托给更强大或专门的模型。该覆盖设置接受任何 provider/model-id 字符串：

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

这也适用于本地模型，例如第二个专用于摘要的 Ollama 模型：

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

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

标识符保留

压缩摘要默认保留不透明标识符 (identifierPolicy: "strict")。使用 identifierPolicy: "off" 覆盖以禁用，或使用 identifierPolicy: "custom" 加上 identifierInstructions 进行自定义指导。

活跃转录字节保护

当设置了 agents.defaults.compaction.maxActiveTranscriptBytesOpenClaw 时，如果活跃的 JSONL 达到该大小，OpenClaw 会在运行前触发正常的本地压缩。这对于长时间运行的会话非常有用，因为在这种情况下，提供商端的上下文管理可能会保持模型上下文的健康，而本地记录则会不断增长。它不会分割原始 JSONL 字节；而是要求正常的压缩管道创建语义摘要。

后续记录

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

OpenClaw 不再为新的压缩操作写入单独的 OpenClaw.checkpoint.*.jsonl 副本。现有的旧版检查点文件在被引用时仍可使用，并会被正常的会话清理修剪。

压缩通知

默认情况下，压缩静默运行。设置 notifyUser 可在压缩开始和完成时显示简短的状态消息：

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

内存刷新

在压缩之前，OpenClaw 可以运行一个 静默内存刷新 轮次，将持久化笔记存储到磁盘。设置 agents.defaults.compaction.memoryFlush.model 以指定此内务处理轮次应使用本地模型而非当前活动对话模型：

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

内存刷新模型覆盖是精确的，不会继承活动会话的回退链。有关详细信息和配置，请参阅内存。

可插拔压缩提供商

插件可以通过插件 API 上的 registerCompactionProvider()APIOpenClawLLM 注册自定义压缩提供商。当注册并配置了提供商后，OpenClaw 会将摘要工作委托给它，而不是使用内置的 LLM 管道。

要使用注册的提供商，请在配置中设置其 id：

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

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

压缩与修剪

	压缩	修剪
作用	总结较早的对话	修剪旧的工具结果
是否保留？	是（在会话记录中）	否（仅在内存中，每个请求）
范围	整个对话	仅工具结果

会话修剪是一种更轻量级的补充机制，它会在不进行摘要的情况下修剪工具输出。

故障排除

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

压缩后上下文感觉陈旧？ 使用 /compact Focus on <topic> 来引导摘要，或启用内存刷新以便保留备注。

需要全新的开始？ /new 启动一个新的会话，而无需进行压缩。

有关高级配置（保留令牌、标识符保留、自定义上下文引擎、OpenAI 服务端压缩），请参阅会话管理深度剖析。