压缩

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

工作原理¶

1. 较早的对话轮次被总结为一条压缩条目。
2. 摘要保存在会话转录中。
3. 最近的消息保持完整。

OpenClaw 在选择压缩切分点时，会保持助手工具调用与其匹配的 toolResult 条目配对。如果切分点落在工具块内部，OpenClaw 会移动边界，使该配对保持在一起，并保留当前未摘要的尾部。

内置摘要器在估算块大小时，会考虑消息文本和工具参数中的中文、日文和韩文（CJK）字符。这些预算是近似值；即使该组超过块目标，工具调用及其结果也会保持在一起。

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

内置摘要接收文本，而非图像像素。被省略的图像和其他非文本输入会收到标记，例如 [image data omitted from summary input]，而不会声称模型已处理该数据。前八条受影响的消息每条最多接收两个固定标记；后续省略接收一条汇总说明。这些新增内容（包括新保留的角色标签和分隔符）每次摘要器请求总计最多 847 个 UTF-8 字节，并计入 Token 估算。现有文本不受此省略预算限制。自定义压缩提供商仍会收到原始消息内容。

启用内置 safeguard 质量守卫时，OpenClaw 会在验证前应用最终摘要预算。必需标题必须保留在保留的生成正文中，而待处理询问和精确标识符必须保留在将被存储的精确文本中。无效输出只会获得配置数量的纠正尝试。如果没有已定稿的摘要通过，压缩会在写入转录条目之前停止，保留原始历史，并显示现有恢复结果。

自动压缩¶

自动压缩默认开启。当会话接近上下文限制，或模型返回上下文溢出错误时运行（此时 OpenClaw 会压缩并重试）。

如果提供商在工具调用完成后拒绝请求，内置运行时可以压缩并从其记录的结果继续。它会保留当前模型和账户，保留原始请求，并且不会重放已完成的操作。此恢复需要已确定的工具结果；待处理工具、审批、取消以及有意结束轮次的工具仍保留其正常处理。

溢出恢复会在当前模型上下文窗口内修剪工具结果。较早的消息和重置边界保留在保留历史中，而不会被复制到新的转录条目中。

停止或超时运行也会停止其溢出或超时恢复。内置 OpenClaw 运行时在取消后不会启动进一步的恢复钩子、维护、转录截断或重试。取消不是回滚：已完成的压缩仍保留在转录中并仍被计数，而不会发送迟到的回复。上下文估算遵循最新的模型或压缩观察；计费总额保持独立。

内置 OpenClaw 运行时在推理前执行必需的检查点和压缩。在持久 Gateway 会话中，可选内存刷新和压缩会等待回复投递已确定且其前台所有者已关闭。该工作使用单独的会话所有者和该轮次的剩余时间。新消息会在读取会话以进行自身推理之前取消并确定可选工作。

一次性 openclaw agent --local 命令会跳过可选的轮次后工作；下一条命令会在推理前执行必需的维护。通用 CLI 后端保留其现有同步主机压缩，原生运行时保留其自身的压缩策略。可选维护失败会被记录，而不会替换已完成的回复。取消、重启或被替换的会话仍会隔离活动写入者。

设置 agents.defaults.compaction.enabled: false 可禁用内置运行时中的主动阈值压缩和可选维护。溢出恢复压缩和手动 /compact 仍可用。

你会看到：

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

手动压缩¶

在聊天中输入 /compact 可在其运行时支持手动压缩时强制压缩。在内置 OpenClaw 运行时中，添加指令以引导摘要，如下例所示。当原生 Codex 会话使用 Codex 登录或 API 密钥且支持手动压缩时，仅使用 /compact；聚焦指令不会传递给 Codex。使用 使用 ChatGPT 登录 的原生 Codex 会话支持自动压缩，但无法运行手动 /compact。

/compact Focus on the API design decisions

内置 OpenClaw 运行时中的客户端压缩会将 focus 传递给旧历史摘要和拆分轮次前缀摘要。主机将操作员提供的 focus 限制为 800 个 Unicode 码点，并在将其添加到模型请求之前将其转义为 Prompt 数据。

客户端手动压缩使用 agents.defaults.compaction.keepRecentTokens（默认值：20,000）作为其切分点预算，并在重建的上下文中保留该近期尾部。

当内置 OpenClaw 运行时已准备好前台请求时，客户端自动压缩在选择保留尾部时也会考虑其系统 Prompt、工具架构、待处理输入和输出预留。它可能会保留较少的近期消息，以便摘要和对话能够一起容纳。选择更大的摘要模型不会增加前台模型的上下文窗口。预留是一个首选目标，而不是提供商 Token 限制。当固定 Prompt 或待处理输入消耗了该目标时，OpenClaw 仍可以回收旧历史，同时保留未处理的请求。此类替换必须严格减少历史；未变化或更大的结果会被拒绝。否则，自动压缩要求完整替换适合估算目标。早期必需的预检在这些请求事实可用之前运行，并且仍使用基于历史的大小；它不保证此首选余量。

配置¶

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

使用不同的模型¶

内置 OpenClaw 运行时使用活动会话模型开始压缩。设置 agents.defaults.compaction.model 可选择不同的摘要模型。该覆盖值接受 provider/model-id 字符串，或配置在 agents.defaults.models 下的裸别名：

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

裸配置别名会在压缩开始前解析为其规范提供商和模型。如果裸值同时匹配一个别名和一个已配置的直连模型 ID，则直连模型 ID 优先。未匹配的裸值仍作为活动提供商上的模型 ID。

如果 Gateway 配置在压缩等待启动期间重新加载，压缩会一起使用新加载的上下文引擎和模型设置。其请求的工作区和转录保持不变。

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

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

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

在保护模式下，内置摘要产生的提供商超时和速率限制仍然符合该链的条件。调用方取消和保护质量检查失败不会触发模型切换。

标识符保留¶

压缩摘要默认保留不透明标识符（agents.defaults.compaction.identifierPolicy: "strict"）。设置 agents.defaults.compaction.identifierPolicy: "off" 可禁用。自定义指导应放在压缩提供商的 summarize() 实现中。

活动转录字节保护¶

当设置 agents.defaults.compaction.maxActiveTranscriptBytes 时，如果转录历史达到该大小，OpenClaw 会在运行前触发正常的本地压缩。这对于长时间运行的会话很有用，因为提供商侧的上下文管理可能保持模型上下文健康，而持久化的转录历史持续增长。设置正数字节数或大小字符串（例如 "20mb"）以启用；0 或未设置值会禁用该保护。它不会拆分原始字节；它要求正常压缩管道创建语义摘要。对于 Codex app-server 会话，相同阈值会限制原生 rollout 转录，超大的原生线程会重新开始。

压缩通知¶

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

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

内存刷新¶

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

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

内存刷新是可选维护：失败（包括重试耗尽）不会重置会话或丢弃对话历史。如果压缩不必要或成功，OpenClaw 会继续回复；启用 notifyUser 时，耗尽的刷新重试也会产生降级通知。如果必需的压缩失败，OpenClaw 会报告该失败，并保持对话完整，而不是自动重新开始。

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

提供商和引擎行为¶

提供商检查点¶

当嵌入式 Responses 提供商返回压缩后的窗口时，OpenClaw 会连同检查点一起保留完整返回的上下文。近期轮次历史限制不会丢弃符合条件的检查点，并且保留的上下文仍计入模型的 Prompt 预算。保存的检查点限制为 16 MiB；超大或不兼容的端点输出会使用正常的客户端压缩路径，而不是被截断。

在成功续接后，当保存的请求前缀仍与当前检查点、对话和提供商身份匹配时，OpenClaw 会使用提供商测量的上下文使用情况。新内容和当前请求开销仍会获得本地估算。经过编辑或不兼容的历史会回退到估算，而不会更改已保存的对话。

预测的上下文压力会在下一次请求前使用预算压缩。公开的 OpenAI Responses API 和原生 xAI 默认可以使用它们的 compact 端点；params.responsesCompactEndpoint: false 会为某个模型禁用该端点。提供商确认的溢出会保留客户端恢复路径，因为 compact 端点也要求其输入能够容纳。端点失败会回退到客户端端摘要。

如果旧版本或转录脱敏移除了重放所需的完整窗口，OpenClaw 会要求你运行 /compact。该命令通过客户端端压缩从已保存的对话重建上下文。它不会猜测缺失的提供商上下文，也不会删除转录。

后继转录¶

上下文引擎可以在同一代理、会话键和存储内返回一个显式的已压缩后继会话身份。OpenClaw 会在维护、钩子或重试使用该后继之前发布已接受的后继，同时保留当前写入者的所有权。之后取消不会回滚该已完成的转换。内置 SQLite 压缩器会保留当前会话身份，并且不会创建第二个运行时转录。

worker 放置 不能在压缩期间将所有权转移到不同的会话身份。自定义引擎必须在放置拥有会话期间保留当前身份，或者操作员必须在重试前将会话移回 Gateway。被拒绝的转换会保持原始会话和 worker 声明不变。

OpenClaw 不会创建压缩检查点记录或快照副本。 现有的历史转录引用仍受常规会话清理保护；移除检查点控制不会删除已存储的对话历史。

可插拔压缩提供商¶

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

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

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

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

内置质量审计及其纠正重试仅适用于内置摘要。已配置的提供商输出保留提供商现有的验证语义。

压缩与修剪¶

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

故障排除¶

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

压缩后上下文感觉过时？ 使用 /compact Focus on <topic> 来引导摘要，或启用内存刷新 以便笔记得以保留。

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

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

相关¶

• 代理循环：触发自动压缩的轮次生命周期。
• 会话：会话管理和生命周期。
• 会话修剪：修剪工具结果。
• 上下文：如何为代理轮次构建上下文。
• 上下文引擎：可插拔的上下文组装。
• 钩子：内部压缩事件（session:compact:before、session:compact:after）。
• 插件钩子：类型化压缩钩子（before_compaction、after_compaction）。
• Goal — 持久的每会话目标和 /goal 控制