---
summary: "压缩的作用是什么、自动压缩运行时、它的设置、可插入提供程序以及它出现的位置"
read_when:
  - "你正在更改自动压缩行为或添加“压缩前”清理工作"
  - "调整压缩阈值、储备或压缩提供程序插件"
title: "压缩行为和设置"
---

## <a id="context-windows-vs-tracked-tokens"></a> 上下文窗口 vs 已跟踪 token

两个不同的概念：

1. **模型上下文窗口**：每个模型的硬性上限（模型可见的 token）。来自模型目录，并且可以通过配置覆盖。
2. **会话存储计数器**：写入会话行的滚动统计信息（用于`/status`和仪表板）。 `contextTokens` 是运行时 estimate/reporting 值 - 不要将其视为严格保证。

即使没有发生压缩，完成的轮次也会更新会话计数器。有序上下文替换优先于早期模型使用；如果其大小未知，则计数器将被标记为过时，而不是借用旧请求的总数。被取代的运行不能覆盖当前写入器的计数器。

有关限制的更多信息：[/reference/token-use](/reference/token-use).

## <a id="compaction%3A-what-it-is"></a><a id="compaction-what-it-is"></a> 压缩：它是什么

压缩将较旧的对话总结为记录中持久的 `compaction` 条目，并保持最近的消息完整。压缩后，未来的回合会看到压缩摘要以及 `firstKeptEntryId` 之后的消息。压缩是 **persistent**，与会话修剪不同 - 请参阅 [/concepts/session-pruning](/concepts/session-pruning).

嵌入式 OpenClaw 压缩使用提供商的压缩思维偏好，回退到 `low`。本机本地 Ollama 更喜欢 `off` 将摘要保持在其请求预算内。设置 `agents.defaults.compaction.thinkingLevel: "inherit"` 以重用会话级别，或为摘要调用选择显式级别；运行时将其固定到每个混凝土压实模型或后备模型。本机 Codex 应用程序服务器压缩拥有其压缩请求，并且无法接受每次压缩思维覆盖，因此 OpenClaw 会发出警告并将该设置保留为 Codex。

每个汇总请求都使用一种主要格式。 Safeguard 历史摘要使用其结构化检查点格式，而分转前缀则使用前缀格式。操作员关注点和标识符保存指南仍然是附加说明；他们没有添加一组相互竞争的必填标题。

当保护压缩更新先前的摘要或总结较旧的历史记录时，其主要摘要请求还包括来自准备好的窗口的保留的最近轮次和分轮进度。这些说明需要明确的更正和观察结果来更新主要决策和任务状态，而不仅仅是出现在附加的上下文部分中。被取代的事实可能会保留为标记的历史或逐字摘录；它们不得继续与当前的决策相竞争。

分支导航摘要预算实际发送用于摘要的文本，包括有界工具输出、指令和输出余量。旧的摘要不能覆盖该预算。如果可见分支历史记录无法容纳，摘要会报告失败，而不是声称没有内容。

在压缩后重新注入 AGENTS.md 部分仍然需要显式开启，可通过 `agents.defaults.compaction.postCompactionSections` 配置。插件还可以通过 `before_prompt_build` 添加其他提示上下文。

### <a id="summary-input-and-tool-pairing"></a> 汇总输入和工具配对

压缩切割点使辅助工具调用与其匹配的 `toolResult` 条目配对：如果切割落在调用及其结果之间，OpenClaw 会移动它，以便这对在保留的尾部中保持在一起。

剪切之前的较旧历史记录被汇总在一个请求中，该请求的对话输入是有界的（请参阅 [Compaction](/concepts/compaction#how-it-works)）。当该历史记录大于界限时，摘要生成器会收到一个样本：逐字记录的最新消息、较旧的用户消息、最旧的消息以及均匀间隔的其余消息，每个间隙都标有其大小。采样工具结果可能会在没有调用的情况下显示，因此它会命名生成它的调用，例如 `[Tool result of exec(cmd="npm test")]`。结果会逐次与同一助理的呼叫进行匹配，因此重复呼叫 ID 绝不会借用先前未应答呼叫的标签。

## <a id="when-auto-compaction-happens"></a> 自动压缩何时发生

内置OpenClaw运行时有3个调度路径：

1. **溢出恢复**：模型返回上下文溢出错误（`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`，以及其他类似提供方的变体）——先压缩，然后重试。当提供方报告了尝试的 token 数时，OpenClaw 会将该观察到的数量传递给溢出恢复压缩；如果提供方确认发生溢出但未暴露可解析的数量，OpenClaw 会向压缩引擎和诊断传递一个仅略微超出预算的合成数量。如果溢出恢复仍然失败，OpenClaw 会给出明确指导并保留当前会话映射，而不是静默切换到新的会话 id——重试该消息、运行 `/compact`，或者运行 `/new`。

   一种提供者形状是终端的而不是压缩可恢复的。当拒绝声明单个请求大于提供者的整个令牌限制时 - Groq 使用 HTTP 413 命名 TPM 并声明 `Limit <n>, Requested <m>` 来回答超大请求 - 没有存储桶状态可以承认它。根据模型的上下文窗口而不是每个请求的上限来压缩预算，并且它自己的汇总请求被同一上限拒绝，因此它只能花费无法成功的进一步调用。 OpenClaw 立即显示重置指导，而不是压缩、采用后续转录本或重试。普通 TPM 节流表明请求的大小在限制内，保持速率限制并保持其正常的退避。

2. **基于使用情况的维护**：使用OpenClaw的托管循环检查预测使用情况的回复和直接命令在推理之前。所需的内存检查点先于活动模型窗口或高于活动模型窗口减去选定的压缩储备进行压缩，但须遵守适用的服务器压缩阈值下限。使用该循环的成功网关命令还会在交付完成的答复后安排可选的维护；一次性本地命令会跳过该可选工作。通用 CLI 后端在交付前保留其现有的主机压缩，本机后端保留其自己的压缩策略。内存刷新软余量不会降低阻塞阈值。禁用内存刷新不会禁用压缩。直接命令维护遵循 `compaction.enabled: false` 并在完成的运行已经压实时跳过第二次转弯后压实。
3. **会话内部阈值维护**：当实际上下文使用量超过模型窗口减去会话保留时，默认模式会话也可以压缩。保护模式禁用此竞争会话内部路径，并将主动调度留给上面的维护所有者。

持久化的 `contextBudgetStatus` 是预先提示的压力估计，而不是执行命令。已完成的直接命令、正常回复和排队的后续回复会在运行时提供命令时记录下来。当新的代币使用不可用时，`/status` 可以显示此估计值，并标记为 `~` 和 `est`。压缩和会话重置使旧的估计无效；没有诊断的已完成运行将清除前一个运行，除非该运行保留会话的模型状态（例如，心跳）。其 `route` 和 `shouldCompact` 字段可以报告压力，同时仍允许提供者尝试。使用已完成的压缩计数和转录条目来验证压缩是否确实发生。

两个额外的警卫在这些路径之外运行：

- **预检本地压缩**：将 `agents.defaults.compaction.maxActiveTranscriptBytes` 设置为一个正的字节阈值（字节数或类似 `"20mb"` 的字符串），即可在活动转录达到该大小后、打开下一轮之前触发本地压缩。常规语义压缩仍然会运行。对于 Codex app-server 会话，同一阈值会限制原生滚动转录，且过大的原生线程会重新从新会话开始。未设置或设为 `0` 会禁用此保护。
- **中转预检查**：设置`agents.defaults.compaction.midTurnPrecheck.enabled: true`（默认`false`）以添加刀环防护装置。附加工具结果后、下一次模型调用之前，OpenClaw 检查实际的提供者绑定工具结果投影。当请求前缀、系统提示、工具和模型不变时，它会重用先前调用报告的提示和完成占用率，包括不透明推理。匹配的辅助碎片计算一次；仅估计新工具结果和其他附加内容。保留的完成用法可以在上下文更改后覆盖不透明的推理。缺少使用或改变上下文保持保守估计；预检预算和回收阈值保持不变。如果上下文不再适合，守卫不会内联压缩 - 它会引发结构化的中转预检查信号，停止当前的提示提交，并让外部运行循环使用现有的恢复路径（当足够时截断过大的工具结果，或触发配置的压缩模式并重试）。适用于 `default` 和 `safeguard` 压缩模式，包括提供商支持的保护压缩。独立于 `maxActiveTranscriptBytes`：字节大小防护在回合打开之前运行，中间回合预检查稍后在附加新工具结果之后运行。

  工具结果后引导至活动运行的消息包含在此检查中。如果添加的上下文超出预算，则已确定的工具批次可以压缩并继续，而无需重放该工具。

## <a id="compaction-settings"></a> 压缩设置

检查点重放预检查将预测压力与提供商确认的溢出区分开来。匹配的测量响应请求提供覆盖的上下文计数；仅估计附加内容。如果当前检查点或覆盖的输入发生变化，则不再使用该测量。预测压力可以使用本机预算压缩，默认情况下包括公共 OpenAI 压缩端点，而实际提供程序溢出则保留客户端恢复。当需要客户端汇总时，这两个路径都会保留未解析的用户请求。

```json5
{
  agents: {
    defaults: {
      compaction: {
        enabled: true,
        keepRecentTokens: 20000,
      },
    },
  },
}
```

OpenClaw 强制执行嵌入式运行的内置保留，并将其限制为活动模型上下文窗口的四分之一。对于 80,000 个代币或更多的窗口，默认储备仍为 20,000 个代币。较小的窗口保留了至少四分之三的提示和对话容量，而保留空间则为压缩摘要和内存刷新等内务管理留下了空间。

聊天回复和托管网关代理命令的可选维护拥有新的会话所有者，并在内存刷新和压缩过程中共享轮次的剩余超时限额。它在实际交付和持久性结算后开始，即使有界后续准入等待已经到期。完成的回复首先返回。新的前台转弯会在获取会话通道之前取消并解决可选维护。重新启动和会话替换也会取消陈旧的工作。接受的压缩提交仍然被考虑，并且无限的命令超时仍然是无限的。使用 OpenClaw 的托管循环的一次性本地命令会记录一次有意的跳过，而不会标记内存刷新成功。

当新创建的隔离子代理在其进程中启动携带已提交的创建事实时，它会在第一次转动之前跳过基于转录本的压缩估计。分叉和恢复的子项保持正常的飞行前维护。随后轮流使用孩子当前的成绩单和计数器；创建事实不会保留为空转录本缓存。

设置 `enabled: false` 以禁用嵌入式代理运行时内的阈值驱动自动压缩和直接命令轮后维护。 OpenClaw 的回复预检和溢出恢复压缩路径仍然可用，并且手动 `/compact` 继续工作。

手动 `/compact` 使用 `agents.defaults.compaction.keepRecentTokens`（默认值：`20000`）并保留该最近尾部截断点。

OpenClaw 采用上下文引擎返回的显式后继标识。内置 SQLite 压缩器保留当前会话身份。压缩摘要和令牌节省保留在成绩单历史记录中；普通会话分叉仍然可用。

压缩检查点浏览、分支和恢复不再可用。 OpenClaw 不会创建新的检查点元数据或快照文件。此更改不会删除现有的转录本生成和文件。只读遗留元数据读取器保留历史令牌测量和现有的清理保护，而较旧的记录仍然引用这些记录。删除该读取器需要单独批准的迁移来保留这些事实；此删除不会更改保留策略或数据库架构版本。

## <a id="pluggable-compaction-providers"></a> 可插拔压实供应商

插件通过 API 上的 `registerCompactionProvider()` 注册压缩提供程序。当 `agents.defaults.compaction.provider` 设置为已注册的提供程序 ID 时，防护扩展会将汇总委托给该提供程序，而不是内置的汇总请求。

- `provider`：已注册压缩提供方插件的 id。若留空，则使用默认的 LLM 摘要生成。设置 `provider` 会强制使用 `mode: "safeguard"`。
- 提供方接收与内置路径相同的压缩指令和标识符保留策略，并且在提供方输出后，保护机制仍会保留最近轮次和拆分轮次的后缀上下文。
- Safeguard 恢复保留在最新的重置或压缩重播窗口内，即使保留的消息先于存储的压缩标记也是如此。较旧的记录条目仍被存储，但不会再次发送到摘要器。
- 内置的 safeguard 摘要会结合新消息对先前摘要进行重新提炼，而不是逐字保留完整的前一版摘要。
- Safeguard 模式默认启用内置摘要质量审核。它检查最终摘要的结构、待处理的询问和确切的标识符，最多进行 `qualityGuard.maxRetries` 的纠正尝试。耗尽的审核或不可行的保留提交标记为 `details.qualityDegraded` 的最佳可用生成摘要，保持会话可压缩。审计违规次数最少的尝试获胜；关系保持了早期的尝试。所需事实的保留将尽最大努力：旧的详细信息、标识符和待处理的请求可能会丢失。纠正性生成失败会重用早期的摘要（如果可用）；初始生成、模型解析或凭证失败使原始历史具有权威性。当无法重用早期摘要时，自动摘要超时也有一个单独的回退（请参阅 [Auto-compaction](/concepts/compaction#auto-compaction)）。设置`qualityGuard.enabled: false`跳过审核。配置的压缩提供程序输出保留在内置审核循环之外。
- 如果提供程序失败或返回空结果，OpenClaw会自动回退到内置LLM摘要。提供商本地故障（包括超时）会保留在受保护的回退中，并在启用时使用内置质量审核。 Abort/timeout 表示调用者显式触发的信号将被重新抛出，而不是被吞咽，因此始终尊重取消。

来源：`src/plugins/compaction-provider.ts`，`src/agents/agent-hooks/compaction-safeguard.ts`。

## <a id="user-visible-surfaces"></a> 用户可见界面

- 任何聊天会话中的 `/status`，包括录制时的降级摘要指示器
- `openclaw status` (CLI)
- `openclaw sessions` / `openclaw sessions --json`
- 网关日志（`pnpm gateway:watch` 或 `openclaw logs --follow`）：`embedded run auto-compaction start` + `complete`
- 详细模式：`🧹 Auto-compaction complete`加上压缩计数

即使使用 `notifyUser: false`，降级的摘要也始终会产生可见的警告。它指出了旧详细信息、标识符或待处理请求可能丢失的情况，并建议使用 `/new` 或更大的模型。成绩单的`details.qualityDegraded`字段是持久的；日志中的 `reasonCode=quality_guard_degraded_fallback` 仅用于诊断。