跳转至

压缩行为与设置

上下文窗口与跟踪的 Token

这是两个不同的概念:

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

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

关于限制的更多信息:/reference/token-use。

压缩:它是什么

压缩将较早的对话总结为会话记录(transcript)中持久化的 compaction 条目,并保留最近的消息不变。压缩后,未来的轮次将看到压缩摘要以及 firstKeptEntryId 之后的消息。与会话修剪不同,压缩是持久性的——参见 /concepts/session-pruning。

嵌入式 OpenClaw 压缩使用提供方的压缩思考偏好,回退到 low。原生本地 Ollama 更倾向于 off,以将摘要生成保持在其请求预算内。设置 agents.defaults.compaction.thinkingLevel: "inherit" 以复用会话级别,或者为摘要调用选择显式级别;运行时会将其限制到每个具体的压缩模型或回退模型。原生 Codex 应用服务器压缩拥有其自身的压缩请求,无法接受每次压缩的思考覆盖,因此 OpenClaw 会发出警告并将该设置留给 Codex。

每个摘要生成请求使用一种主要格式。保护历史摘要使用其结构化检查点格式,而拆分轮次前缀使用前缀格式。操作员焦点和标识符保留指南仍然作为附加指令;它们不会增加一套竞争性的必需标题。

当保护压缩更新先前的摘要或总结较早的历史时,其主摘要请求还包括来自已准备窗口的保留近期轮次和拆分轮次进度。指令要求以明确的更正和观察到的结果来更新主要决策和任务状态,而不是仅仅出现在附加的上下文部分中。被取代的事实可能保留为带标签的历史或逐字摘录;它们不得继续作为相互竞争的当前决策。

分支导航摘要会为实际发送用于摘要生成的文本设定预算,包括受限的工具输出、指令和输出余量。较早的摘要不能覆盖该预算。如果可见的分支历史无法容纳,摘要生成会报告失败,而不是声称没有内容。

压缩后重新注入 AGENTS.md 部分仍是通过 agents.defaults.compaction.postCompactionSections 选择启用的。插件可以通过 before_prompt_build 添加其他提示上下文。

摘要输入与工具配对

压缩切割点会保持助手工具调用与其匹配的 toolResult 条目配对:如果切割点落在调用和其结果之间,OpenClaw 会移动它,使配对留在保留的尾部。

切割点之前的较早历史在一次请求中被总结,其对话输入是受限的(参见 压缩)。当该历史大于界限时,摘要器会收到一个样本:最新的消息逐字保留、较早的用户消息、最旧的消息以及其余部分的均匀间隔片段,每个间隙均标明其大小。采样到的工具结果可能在没有其调用的情况下显示,因此它会指明产生该结果的调用,例如 [Tool result of exec(cmd="npm test")]。结果按出现顺序与同一助手轮次的调用匹配,因此重复的调用 ID 永远不会借用较早未应答调用的标签。

自动压缩的触发时机

内置的 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. 会话内部阈值维护:默认模式的会话在实际上下文使用量超过模型窗口减去会话储备时也可以压缩。保护模式禁用这条竞争的会话内部路径,并将主动调度留给上面的维护责任方。

持久化的 contextBudgetStatus 是 Prompt 前压力估计,而不是执行命令。已完成的直接命令、普通回复和排队的后续回复会在运行时提供该值时记录它。当最新 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 和 Completion 占用,包括不透明推理。匹配的助手片段只计算一次;仅对新工具结果和其他追加内容进行估计。保留的 Completion 用量可在上下文变化后继续覆盖不透明推理。缺少用量或上下文变化会保持保守估计;预检预算和恢复阈值保持不变。如果上下文不再容纳,该保护不会内联压缩——它会发出结构化的轮次中途预检信号,停止当前 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 扩展会将摘要委托给该提供商,而不是内置摘要请求。

  • provider:已注册的压缩提供商插件的 id。留空以使用默认 LLM 摘要。设置 provider 会强制 mode: "safeguard"。
  • 提供商接收与内置路径相同的压缩指令和标识符保留策略,并且 safeguard 仍会在提供商输出后保留最近轮次和拆分轮次的后缀上下文。
  • Safeguard 恢复始终保持在最新重置或压缩重放窗口内,即使保留的消息早于已存储的压缩标记。较旧的转录条目仍会存储,但不会再次发送给摘要器。
  • 内置 safeguard 摘要会用新消息重新提炼先前摘要,而不是逐字保留完整的先前摘要。
  • Safeguard 模式默认启用内置摘要质量审计。最终预算分配后,保留的生成正文必须包含必需标题,并且要持久化的确切工件必须保留待处理请求和精确标识符。纠正尝试保持在 qualityGuard.maxRetries 内;重试耗尽或纠正生成失败会在追加前取消,并保留原始转录为权威版本。自动压缩中的摘要超时是例外:OpenClaw 会提交没有摘要的压缩(参见 自动压缩)。这包括在超时窗口后保持静默的纠正尝试;获得 HTTP 408 的纠正尝试仍会取消。设置 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
  • 网关日志(pnpm gateway:watch 或 openclaw logs --follow):embedded run auto-compaction start + complete
  • 详细模式:🧹 Auto-compaction complete 以及压缩次数

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