压缩
每个模型都有一个上下文窗口:它所能处理的最大 Token 数。当对话接近该限制时,OpenClaw 会将较旧的消息压缩成摘要,以便聊天继续进行。
工作原理¶
- 较旧的对话轮次被总结为一条紧凑的条目。
- 摘要保存在会话记录中。
- 最近的消息保持不变。
OpenClaw 在选择压缩分割点时,会保持助手工具调用与其对应的 toolResult 条目成对出现。如果分割点落在工具块内部,OpenClaw 会移动边界,使这一对保持在一起,并保留当前未摘要的尾部。
内置压缩会在一次模型请求中总结较旧的历史,无论会话或上下文窗口的大小如何。分割轮次会为轮次前缀增加一次请求;失败的保护性质量审计每次纠正尝试增加一次请求。每个请求的对话输入上限为 160,000 个字符(约 40,000 个 Token),如果摘要器自身的上下文窗口更小,则上限更小。更大的历史按以下顺序填充:最新消息逐字逐句,占该预算的一半;承载请求、决策和纠正的较旧消息,占四分之一,每条最多裁剪到 2,000 个字符,若不能全部放入则在整个历史中均匀分布;最旧的消息占十分之一;其余消息均匀间隔的片段,每条裁剪到 6,000 个字符。每个间隙都标出被省略的消息数量,并告知摘要器不要猜测其内容,且保留先前摘要中的事实。中文、日文、韩文(CJK)字符按近似 Token 权重计数。该上限仅适用于摘要器输入;会话记录保留所有消息。
完整的对话历史仍保存在磁盘上。压缩只会改变模型在下一轮看到的内容。
内置摘要接收的是文本,而非图像像素。被省略的图像和其他非文本输入会收到诸如 [image data omitted from summary input] 的标记,而不会声称模型处理了这些数据。受影响的前八条消息每条最多收到两个固定标记;后续省略则收到一条汇总说明。这些新增内容,包括新保留的角色标签和分隔符,每个摘要器请求最多合计 847 个 UTF-8 字节,并计入 Token 估算。现有文本不受此省略预算限制。自定义压缩提供程序仍会收到原始消息内容。
Note
新配置默认将 agents.defaults.compaction.mode 设置为 "safeguard"(更严格的护栏、摘要质量审计)。显式设置 mode: "default" 可选择退出。
启用内置的 safeguard 质量保护后,OpenClaw 会在验证前应用最终摘要预算。必需的标题必须保留在保留的生成正文中,而待处理的请求和准确标识符必须保留在将要存储的确切文本中。无效输出仅获得配置的纠正尝试次数。如果没有最终摘要通过,压缩会在写入会话记录条目之前停止,保留原始历史,并呈现现有的恢复结果。摘要超时是唯一的例外;请参阅自动压缩。
自动压缩¶
自动压缩默认开启。当会话接近上下文限制,或模型返回上下文溢出错误时,它会运行(在这种情况下,OpenClaw 会进行压缩并重试)。
如果提供程序在工具调用完成后拒绝请求,内置运行时可以压缩并根据已记录的结果继续。它保持当前模型和账户不变,保留原始请求,并且不重放已完成的操作。此恢复需要已确定的工具结果;待处理的工具、审批、取消,以及有意结束该轮次的工具,都维持其正常处理方式。如果稍后 Gateway 重启中断了该继续运行,即使压缩已将其摘要化,恢复也会保留已接受的输入。
溢出恢复会在当前模型上下文窗口内裁剪工具结果。较旧的消息和重置边界保留在保留的历史中,不会被复制到新的会话记录条目中。
如果溢出恢复无法使提示词适配,失败的回复会建议 /reset、/new,或使用更大上下文的模型。Control UI 会在详细信息中显示此指导,并将其保留在已保存的聊天历史中。对于单个过大的提示词,请先缩短提示词,再在新会话中重新发送。
停止或超时运行也会停止其溢出或超时恢复。内置的 OpenClaw 运行时在取消后不会启动进一步的恢复钩子、维护、会话记录截断或重试。取消不是回滚:已经完成的压缩仍会保留在会话记录中并继续计入,而不会发送迟到的回复。上下文估算遵循最新的模型或压缩观察;计费总额保持单独计算。
如果自动压缩的摘要在一轮仍处于活动状态时超时(摘要截止时间到期,或提供程序返回 HTTP 408 或 504),OpenClaw 会无摘要地提交该压缩,而不是结束这一轮。它会保持相同的最近消息逐字不变,包括完整的工具调用和结果、待处理的请求,以及分割轮的原始请求,继续保留之前的摘要,并记录移除了多少条较旧消息。回复随后继续,下一轮不会再次等待同一个摘要。Gateway 日志记录 [compaction-diag] fallback ... reason=timeout summary=deterministic;不会添加聊天通知。超时的摘要不会进入模型回退链,因为每增加一个模型都可能为等待增加一个完整的超时窗口。停止、运行超时、手动 /compact 以及其他摘要器错误仍会继续报告失败。
这一点在 safeguard 模式下同样适用,该模式会为这次压缩放弃其标识符保留保证:从未被摘要的较旧事实会离开模型上下文,后续压缩也不会把它们带回来,因为每次压缩都从之前的压缩边界开始。会话记录仍会保留所有消息,以供历史和显式检索。如果没有这个例外,后续每一轮都会等待同样的超时,会话将一直无法使用。
内置 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>。
Info
在压缩之前,OpenClaw 会自动提醒代理将重要笔记保存到 memory 文件中。这有助于保留持久上下文。
OpenClaw 识别的溢出错误模式
OpenClaw 会匹配数十种特定提供商的溢出错误字符串(Anthropic、OpenAI、Bedrock、Gemini、Ollama、OpenRouter 等)。常见示例:
request_too_largecontext length exceededinput exceeds the maximum number of tokensinput token count exceeds the maximum number of input tokens(Bedrock)input is too long for the modelollama error: context length exceeded
手动压缩¶
在聊天中输入 /compact,当其运行时支持手动压缩时强制压缩。在内置 OpenClaw 运行时中,添加指令以引导摘要,如下例所示。当原生 Codex 会话使用 Codex 登录或 API 密钥且支持手动压缩时,使用不带参数的 /compact;焦点指令不会传递给 Codex。使用 通过 ChatGPT 登录 的原生 Codex 会话支持自动压缩,但无法运行手动 /compact。
如果某个轮次处于活动状态,/compact 会最多给它 60 秒完成,然后取消它,并最多再等待 15 秒让它停止。当取消成功时,该命令的回复会要求你重新发送被中断的请求,包括当运行仍在停止且压缩无法继续时。
内置 OpenClaw 运行时中的客户端压缩会将焦点传递给旧历史摘要和拆分轮次前缀摘要。主机将操作员提供的焦点限制为 800 个 Unicode 码点,并在将其添加到模型请求之前将其转义为提示数据。
自动会话标题生成在后台运行,不会阻塞手动压缩。Gateway 压缩请求会立即拒绝已准入的轮次和已接受的排队工作。一旦前台准入结束,一个已完成但仍正在保存或清理的回复可能需要最多 15 秒才能稳定,然后请求才会重新检查会话。带内命令会将其自身执行排除在此等待之外,但仍会等待其他已完成写入者。
客户端手动压缩使用 agents.defaults.compaction.keepRecentTokens(默认:20,000)作为其切分点预算,并在重建的上下文中保留该近期尾部。
当内置 OpenClaw 运行时已准备好前台请求时,客户端自动压缩在选择保留尾部时也会考虑其系统提示、工具模式、待处理输入和输出预留。它可能会保留较少的近期消息,以便摘要和对话能够适配在一起。选择更大的摘要模型不会增加前台模型的上下文窗口。预留是一个首选目标,而不是提供商的 token 限制。当固定提示或待处理输入消耗了该目标时,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 模型:
当未设置时,压缩从当前会话模型开始。如果摘要因符合模型回退条件的提供商错误而失败,OpenClaw 会通过会话现有的模型回退链重试该次压缩尝试。回退选择是临时的,不会写回会话状态。显式的 agents.defaults.compaction.model 覆盖保持精确,并且不会继承会话回退链。
预检压缩在主身份验证配置已处于冷却期时也会使用该链。每个候选项在摘要前都必须通过身份验证准入;健康的回退可以在不等待主冷却期结束的情况下压缩会话。
在保护模式下,内置摘要产生的提供商超时和速率限制仍然符合该链的条件,但摘要截止时间或 HTTP 408 或 504 除外,这些情况会改为在没有摘要的情况下提交压缩(参见 自动压缩)。调用方取消和保护质量检查失败不会触发模型切换。
标识符保留¶
压缩摘要默认保留不透明标识符(agents.defaults.compaction.identifierPolicy: "strict")。设置 agents.defaults.compaction.identifierPolicy: "off" 可禁用。自定义指导应放在压缩提供商的 summarize() 实现中。
活动转录字节保护¶
当 agents.defaults.compaction.maxActiveTranscriptBytes 已设置时,如果转录历史达到该大小,OpenClaw 会在运行前触发正常的本地压缩。这对于长时间运行的会话很有用,因为提供商端上下文管理可能保持模型上下文健康,而持久化转录历史却持续增长。设置正数字节数或大小字符串(例如 "20mb")可启用;0 或未设置值会禁用保护。它不会拆分原始字节;它要求正常压缩管道创建语义摘要。如果压缩被拒绝或使历史记录超过限制,该轮次会以最近历史的有界视图继续。OpenClaw 会省略最旧的完整轮次,保留工具调用及其结果,并保留系统指令和当前请求。超大的历史轮次可能被整体省略。此回退不会重写已保存消息,也不会将失败尝试计为成功压缩。即使禁用压缩通知,它也会显示通知;请重新发送被省略历史中的任何必要细节。该边界适用于所选历史,而不是固定指令、工具定义或当前请求。
被抑制的字节压缩重试在后续轮次中仍使用有界视图。保持主机转录不变的原生压缩会保留重试抑制。主机压缩会清除或刷新它;更改会话或限制、低于限制、或再增长一个完整阈值也会重新武装保护。 保留的历史记录仍可在磁盘上访问并可能继续增长;这不是存储保留限制。对于 Codex app-server 会话,相同阈值会限制原生 rollout 转录,超大的原生线程会重新开始。
Warning
字节保护适用于活动的 SQLite 转录历史。旧版 JSONL 检查点工件不是活动压缩目标。
历史水合字节限制¶
嵌入式运行时还会限制其为模型重放加载的历史记录,独立于
基于令牌的压缩和 maxActiveTranscriptBytes。其字节上限为有效上下文
令牌预算的八倍,最小 1 KiB,最大 64 MiB。这是
对序列化模型上下文事件的资源边界,而不是令牌数量。私有
转录元数据和工具结果详情会被排除,但事件信封和
其他内容仍可能在模型令牌预算未满之前达到字节上限。
当超过此上限时,历史记录加载器按四分之一上限步长推进被省略的前缀。 它优先选择完整轮次,保留工具调用及其结果, 并保留最新的压缩摘要。保留的历史记录从可用字节容量的约 75% 开始,受事件和轮次大小影响,然后逐渐增长到 上限。其现有前缀在步骤之间保持不变,包括跨 worker 或进程重启。独立的事件数量限制仍可能缩短 异常密集的历史记录。
此选择不会删除已保存的历史记录、创建摘要、运行内存
刷新或触发压缩通知。因此,当令牌预算仍有空间时,较旧的上下文可能仍位于
模型视图之外。分块以部分即时历史换取前缀缓存复用;它不能解决该字节/令牌
不匹配问题。当你想要语义摘要时,请使用 /compact。正常
压缩触发器和可选的活动转录字节保护保持不变。
压缩通知¶
默认情况下,压缩静默运行。设置 notifyUser 可在压缩开始和完成时显示简短状态消息,并在压缩前内存刷新耗尽但回复仍继续时显示降级通知:
内存刷新¶
在压缩之前,OpenClaw 可以运行一个静默内存刷新轮次以保存持久上下文。Memory Core 会追加到工作区内存文件;另一个选定的内存插件可以通过其自身工具持久化,并使用声明的只读查找工具先检查现有内存。这些工具保留源对话的内存受众和沙箱限制。缺少查找工具会产生警告,但不会阻止持久化。如果策略移除了所有声明的持久化工具,OpenClaw 会跳过刷新并继续压缩。
当此维护轮次应使用本地模型而不是活动对话模型时,设置 agents.defaults.compaction.memoryFlush.model:
内存刷新是可选维护:失败(包括重试耗尽)不会重置会话或丢弃对话历史。如果压缩不必要或成功,OpenClaw 会继续回复;启用 notifyUser 时,耗尽的刷新重试也会产生降级通知。如果必需的压缩失败,OpenClaw 会报告该失败并保持对话完整,而不是自动重新开始。
内存刷新模型覆盖是精确的,不会继承当前会话的回退链。有关详细信息和配置,请参阅内存。
提供商与引擎行为¶
提供商检查点¶
当嵌入式 Responses 提供商返回压缩窗口时,OpenClaw 会保留完整返回的上下文,并与检查点一起保存。最近轮次历史限制不会丢弃符合条件的检查点,且保留的上下文仍会计入模型的 Prompt 预算。保存的检查点限制为 16 MiB;过大或不兼容的端点输出会使用正常的客户端压缩路径,而不是被截断。
在成功继续之后,如果保存的请求前缀仍与当前检查点、对话和提供商身份匹配,OpenClaw 会使用提供商测量的上下文使用情况。新内容和当前请求开销仍会获得本地估算。已编辑或不兼容的历史会回退到估算,而不更改已保存的对话。
预测的上下文压力会在下一次请求之前使用预算压缩。公开的 OpenAI Responses API 和原生 xAI 默认可以使用其压缩端点;params.responsesCompactEndpoint: false 会为某个模型禁用该端点。提供商确认的溢出会保留客户端恢复路径,因为压缩端点也要求其输入能够容纳。端点失败会回退到客户端摘要。
一旦前台请求预算准备就绪,返回的端点窗口还必须与其固定指令、工具、待处理输入和预留空间一起容纳,OpenClaw 才会保存它。如果保留的用户消息仍超过该预算,客户端压缩会选择更小的最近尾部,而不是重试同一个过大的窗口。
如果仅待处理输入就填满了模型的上下文窗口,恢复会要求更小的消息或更大上下文的模型,而不会反复压缩历史。后续消息保留其正常恢复预算。
如果旧版本或转录删节删除了重放所需的完整窗口,OpenClaw 会要求你运行 /compact。该命令通过客户端压缩从已保存的对话重建上下文。它不会猜测缺失的提供商上下文,也不会删除转录。
后继转录¶
上下文引擎可以在同一代理、会话键和存储内返回显式的压缩后继会话身份。OpenClaw 会在维护、钩子或重试使用之前发布已接受的后继,同时保留当前写入者的所有权。之后取消不会回滚该已完成的转换。活动回复会遵循已接受的身份,用于其剩余的会话状态读取;无关的重置和取消仍会停止过期工作。工具策略分类保留其独立捕获的会话身份。内置 SQLite 压缩器保留当前会话身份,不会创建第二个运行时转录。
工作节点放置 在压缩期间不能将所有权转移到不同的会话身份。自定义引擎必须在放置拥有会话期间保持当前身份,或者操作员必须在重试前将会话移回 Gateway。被拒绝的转换会保留原始会话和工作节点声明不变。
OpenClaw 不会创建压缩检查点记录或快照副本。 现有历史转录引用仍受正常会话清理保护;移除检查点控制不会删除已存储的对话历史。
可插拔压缩提供商¶
插件可以通过插件 API 上的 registerCompactionProvider() 注册自定义压缩提供商。当提供商已注册并配置后,OpenClaw 会将摘要委托给它,而不是使用内置 LLM 管道。
要使用已注册的提供商,请在配置中设置其 id:
设置 provider 会自动强制 mode: "safeguard"。提供商接收与内置路径相同的压缩指令和标识符保留策略,并且 OpenClaw 仍会在提供商输出后保留最近轮次和拆分轮次的后缀上下文。
内置质量审计及其纠正重试仅适用于内置摘要。已配置的提供商输出保留提供商现有的验证语义。
Note
如果提供商失败或返回空结果,OpenClaw 会回退到内置保护摘要器及其配置的质量检查。提供商本地超时不会绕过这些检查;压缩请求的取消仍会被尊重。
压缩与修剪¶
| 压缩 | 修剪 | |
|---|---|---|
| 它做什么 | 摘要较早的对话 | 修剪旧的工具结果 |
| 是否保存? | 是(在会话转录中) | 否(仅内存中,按请求) |
| 范围 | 整个对话 | 仅工具结果 |
会话修剪 是一种更轻量的补充,它修剪工具输出而不进行摘要。
故障排除¶
压缩过于频繁? 模型的上下文窗口可能较小,或工具输出可能较大。请尝试启用会话修剪。
压缩后上下文感觉过时? 使用 /compact Focus on <topic> 来引导摘要,或启用内存刷新 以便笔记得以保留。
需要全新开始? /new 会启动一个全新会话,而不进行压缩。
有关高级配置(预留 Token、标识符保留、自定义上下文引擎、OpenAI 服务端压缩),请参阅会话管理深入解析。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw