跳转至

压缩行为与设置

上下文窗口与跟踪的 Token

两个不同的概念：

  1. 模型上下文窗口：每个模型的硬性上限（模型可见的 Token）。来自模型目录，可通过配置覆盖。
  2. 会话存储计数器：写入会话行的滚动统计（用于 /status 和仪表盘）。contextTokens 是运行时估算/报告值——不要将其视为严格保证。

已完成的轮次即使未发生压缩也会更新会话计数器。按指令执行的上下文替换会优先于较早的模型使用记录；如果其大小未知，计数器会被标记为过期，而不是借用较早请求的总数。已被取代的运行无法覆盖当前写入者的计数器。

有关限制的更多信息：/reference/token-use。

压缩：它是什么

压缩会将较早的对话汇总为转录中持久化的 compaction 条目，并保持最近的消息完整。压缩之后，后续轮次将看到压缩摘要以及 firstKeptEntryId 之后的消息。与会话修剪不同，压缩是持久性的——参见/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 添加其他提示上下文。

分块边界与工具配对

将长转录拆分为压缩分块时，OpenClaw 会保持助手工具调用与其匹配的 toolResult 条目配对：

  • 如果按 Token 份额的拆分位置落在工具调用与其结果之间，OpenClaw 会将边界移动到助手工具调用消息处，而不是拆开这一对。
  • 如果尾部的工具结果块会将分块推过目标大小，OpenClaw 会保留该待处理的工具块，并保持未摘要的尾部完整。
  • 已中止/出错的工具调用块不会让待处理拆分一直保持挂起状态。

自动压缩何时发生

内置的 OpenClaw 运行时有三条调度路径：

  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。

有一种提供商形态属于终态，无法通过压缩恢复。当拒绝响应声明单个请求大于提供商的整个 Token 限制时——Groq 以 HTTP 413 响应超大请求，指明 TPM 并声明 Limit <n>, Requested <m>——没有任何桶状态可以接纳该请求。压缩的预算是针对模型的上下文窗口而非该单请求上限，而其自身的摘要请求也会被同一上限拒绝，因此它只会继续消耗无法成功的调用。OpenClaw 会立即显示重置指引，而不是进行压缩、采用后续转录或重试。普通的 TPM 限流会在限制内声明请求大小，仍然属于速率限制，并保持正常的退避。

  1. 基于使用的维护：使用 OpenClaw 管理循环的回复和直接命令会在推理前检查预计使用量。在达到或超过活动模型窗口减去所选压缩预留量时，所需的内存检查点会先于压缩执行，并受适用的服务器压缩阈值下限约束。使用该循环的成功 Gateway 命令也会在交付其完整回复后安排可选维护；一次性本地命令会跳过该可选工作。通用 CLI 后端保留其在交付前现有的主机压缩，原生后端则保留自己的压缩策略。内存刷新的软余量不会降低阻塞阈值。禁用内存刷新不会禁用压缩。直接命令维护会遵守 compaction.enabled: false，并在已完成的运行已压缩时跳过第二次轮后压缩。

  2. 会话内部阈值维护：默认模式会话在实际上下文使用量超过模型窗口减去会话预留量时，也可以进行压缩。Safeguard 模式会禁用这条竞争的会话内部路径，并将主动调度留给上方的维护所有者。

持久化的 contextBudgetStatus 是提示前压力估算值，而非执行命令。当运行时提供该值时，已完成的直接命令、正常回复和排队中的后续回复会记录它。当最新的 Token 使用量不可用时，/status 可以显示该估算值，并以 ~ 和 est 标记。压缩和会话重置会使旧估算值失效；没有诊断的已完成运行会清除先前的估算值，除非该运行保留了会话的模型状态（例如心跳）。其 route 和 shouldCompact 字段可以在提供商尝试仍被接纳时报告压力。使用已完成的压缩计数和转录条目来验证压缩确实发生过。

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

  • 预检本地压缩：将 agents.defaults.compaction.maxActiveTranscriptBytes 设置为正数字节阈值（字节数或类似 "20mb" 的字符串），以便在活跃转录达到该大小后、打开下一次运行之前触发本地压缩。常规语义压缩仍会运行。对于 Codex app-server 会话，同一阈值会限制原生 rollout 转录，并且过大的原生线程会重新开始。未设置或 0 会禁用该守卫。
  • 轮中预检：设置 agents.defaults.compaction.midTurnPrecheck.enabled: true（默认 false）以添加工具循环守卫。在工具结果被追加之后、下一次模型调用之前，OpenClaw 会使用与轮次开始时相同的预检预算逻辑来估算 Prompt 压力。如果上下文不再适合，该守卫不会内联压缩——它会发出结构化的轮中预检信号，停止当前 Prompt 提交，并让外层运行循环使用现有恢复路径（如果截断过大的工具结果就足够，则截断；否则触发配置的压缩模式并重试）。兼容 default 和 safeguard 压缩模式，包括由提供商支持的 safeguard 压缩。独立于 maxActiveTranscriptBytes：字节大小守卫在轮次打开之前运行，轮中预检在稍后、新的工具结果被追加之后运行。

压缩设置

检查点重放预检会区分预测压力与提供商确认的溢出。匹配的已测量 Responses 请求提供所覆盖的上下文数量；仅对追加的内容进行估算。如果当前检查点或所覆盖的输入发生变化，则不再使用该测量值。预测压力可以使用原生预算压缩，默认包括公开的 OpenAI compact 端点，而实际的提供商溢出仍保留客户端恢复。当需要客户端摘要时，两条路径都会保留未解决的用户请求。

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

OpenClaw 为嵌入式运行强制执行内置保留，并将其上限设为活动模型上下文窗口的四分之一。对于 80,000 Token 或更大的窗口，默认保留仍为 20,000 Token。较小的窗口至少保留其容量的四分之三用于 Prompt 和对话，而保留部分则为压缩摘要以及内存刷新等维护操作留出空间。

针对聊天回复和受管 Gateway 代理命令的可选维护拥有 新的会话所有者，并在内存刷新和压缩之间共享该轮次剩余的超时额度。 它在实际投递和持久化稳定后开始，即使有界的后续准入等待已经过期。 已完成的回复会先返回。新的前台轮次会在获取会话通道之前取消并完成 可选维护。重启和会话替换也会取消过期工作。已接受的压缩提交仍会被计入， 无限命令超时会保持无限。使用 OpenClaw 受管循环的一次性本地命令 会记录一次有意跳过，而不会将内存刷新标记为成功。

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

手动 /compact 使用 agents.defaults.compaction.keepRecentTokens（默认：20000），并保留该近期尾部切分点。

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

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

可插拔压缩提供商

插件通过插件 API 上的 registerCompactionProvider() 注册压缩提供商。当 agents.defaults.compaction.provider 设置为已注册的提供商 id 时，safeguard 扩展会将摘要委托给该提供商，而不是内置的 summarizeInStages 管道。

  • provider：已注册压缩提供商插件的 id。保持未设置以使用默认 LLM 摘要。设置 provider 会强制 mode: "safeguard"。
  • 提供商接收与内置路径相同的压缩指令和标识符保留策略，并且 safeguard 在提供商输出之后仍会保留近期轮次和拆分轮次的后缀上下文。
  • Safeguard 恢复保持在最新重置或压缩重放窗口内，即使保留的消息早于已存储的压缩标记。较旧的转录条目仍会存储，但不会再次发送给摘要器。
  • 内置 safeguard 摘要会用新消息重新提炼先前摘要，而不是逐字保留完整的先前摘要。
  • Safeguard 模式默认启用内置摘要质量审计。最终预算之后，保留的生成正文必须包含所需标题，并且要持久化的确切工件必须保留待处理请求和精确标识符。纠正尝试保持在 qualityGuard.maxRetries 之内；用尽或纠正生成失败会在追加前取消，并使原始转录保持权威。设置 qualityGuard.enabled: false 可跳过此行为。已配置的压缩提供商输出仍位于内置审计循环之外。
  • 如果提供商失败或返回空结果，OpenClaw 会自动回退到内置 LLM 摘要。提供商本地故障（包括超时）会留在那个受保护的回退中，并在启用时使用内置质量审计。调用方显式触发的中止/超时信号会被重新抛出，而不是被吞掉，因此取消始终会被尊重。

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

用户可见界面

  • 任意聊天会话中的 /status
  • openclaw status（CLI）
  • openclaw sessions / openclaw sessions --json
  • Gateway 日志（pnpm gateway:watch 或 openclaw logs --follow）：embedded run auto-compaction start + complete
  • 详细模式：🧹 Auto-compaction complete 以及压缩次数

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw