当对话接近模型 context 窗口上限或返回 context length exceeded 等溢出错误时，OpenClaw 自动将旧轮次摘要化（Compaction），保留最近消息和工具调用配对。支持 openclaw.json 中配置压缩模型、identifierPolicy 保留/丢弃标识符、notifyUser 显示通知、memoryFlush 预存笔记到磁盘。手动 /compact [指令] 可引导摘要重点。与仅内存裁剪旧工具结果的 Session Pruning 互补使用。

OpenClaw 上下文压缩（Compaction）配置与排查

每个模型都有上下文窗口（context window），即一次能处理的最大 token 数。对话接近上限时，OpenClaw 自动将较早消息压缩成摘要，对话得以继续。

工作原理

1. 将较早的对话轮次摘要化为一条压缩条目。
2. 摘要保存到会话记录（session transcript）中。
3. 最近的消息保持完整。

切分历史时，OpenClaw 会保证 assistant 工具调用与对应的 toolResult 配对不被打断。若分界点落在工具块中间，OpenClaw 移动边界保持配对完整，并保留当前未摘要的尾部。

完整对话历史始终保存在磁盘上；压缩只改变模型下一轮看到的内容，不删除记录。

自动压缩

自动压缩默认开启。触发条件：

• 会话接近 context 窗口上限。
• 模型返回 context 溢出错误（此时 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

压缩前，OpenClaw 自动提醒 agent 将重要笔记保存到 memory 文件，防止上下文丢失。

日志表现：

• 普通日志：embedded run auto-compaction start / complete
• 详细日志（verbose）：🧹 Auto-compaction complete
• /status 命令：🧹 Compactions: <count>

手动压缩

在任意聊天中输入 /compact 强制压缩。可添加指令引导摘要方向：

/compact 重点保留 API 设计相关决策

若设置了 agents.defaults.compaction.keepRecentTokens，手动压缩会尊重该截断点，保留近期尾部；否则手动压缩硬性截断，仅从新摘要继续。

配置

在 openclaw.json 中 agents.defaults.compaction 下配置。常用项如下；完整参考见 Session Management Deep Dive。

使用不同模型

默认使用 agent 主模型。设置 model 指定摘要模型：

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

也支持本地模型，例如用另一个 Ollama 实例专门做摘要：

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

• 未设置时使用当前会话模型。
• 若摘要失败且 provider 支持模型回退，OpenClaw 会通过会话的回退链重试该次压缩（临时选择，不回写会话状态）。
• 显式设置 model 后不使用会话回退链，保持精确。

标识符保留

默认 identifierPolicy: "strict" 保留不透明标识符（如 ID、API key）。可改为 "off" 关闭，或 "custom" 配合 identifierInstructions 自定义。

活动 transcript 字节防护

设置 agents.defaults.compaction.maxActiveTranscriptBytes 后，当活跃 JSONL 达到该字节大小时，OpenClaw 在下一次运行前触发本地压缩。适用于长时间会话中 provider 端管理正常但本地 transcript 持续增长的情况。

注意：字节防护需要同时设置 truncateAfterCompaction: true，否则活跃文件不会缩小，防护不生效。

后继 transcript

启用 truncateAfterCompaction 后，OpenClaw 不会原地重写现有 transcript，而是从压缩摘要、保存状态和未摘要尾部创建新的后继 transcript，原 JSONL 保留为归档检查点。

后继 transcript 还会丢弃短重试窗口内重复的长用户消息，避免渠道重试风暴带入新活跃 transcript。

压缩前的检查点仅在磁盘大小不超过上限时保留；超大活跃 transcript 仍会压缩，但跳过检查点快照以节省空间。

压缩通知

默认静默运行。设置 notifyUser: true 显示压缩开始/完成的状态消息：

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

记忆刷新（Memory Flush）

压缩前，OpenClaw 可执行一次静默的 memory flush 回合，将持久化笔记写入磁盘。设置 memoryFlush.model 指定用于此维护的模型（不继承会话回退链）：

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

详见 Memory。

可插拔压缩提供商

插件可通过插件 API 的 registerCompactionProvider() 注册自定义压缩提供商。注册并配置后，OpenClaw 使用提供商而非内置 LLM 管道。

配置中设置 provider 的 ID：

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

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

若提供商失败或返回空结果，OpenClaw 回退到内置 LLM 摘要。

Compaction 与 Session Pruning 对比

	Compaction	Session Pruning
作用	摘要化旧对话内容	裁剪旧工具输出
是否持久化	是（保存到会话记录）	否（仅内存，单次请求）
范围	整个对话历史	仅工具调用结果

Session Pruning 是更轻量补充，仅裁剪工具输出而不做摘要。

常见问题

压缩太频繁怎么办？

模型 context 窗口可能较小，或工具输出太大。尝试启用 Session Pruning 降低工具结果占用；也可调大 keepRecentTokens 或使用更高级别的摘要模型提升压缩效果，减少频率。

压缩后上下文感觉变“傻”了？

使用 /compact 重点保留 <话题> 引导摘要方向，或启用记忆刷新（配置 memoryFlush）让关键笔记在压缩中存活。也可在手动压缩时指定指令。

想完全重置不要压缩？

/new 启动全新会话，不会触发压缩。