本页内容
本页内容
会话和内存
压缩
每个模型都有一个上下文窗口:它能处理的最大 token 数量。当对话接近该限制时,OpenClaw 会将较早的消息压缩成摘要,以便聊天可以继续。
工作原理
- 较早的对话轮次会被总结为一个压缩条目。
- 该摘要会保存在会话转录中。
- 最近的消息会保持完整。
OpenClaw 在选择压缩分割点时,会将助手的工具调用与其对应的 toolResult 条目配对保留。如果分割点落在工具块内部,OpenClaw 会移动边界,确保这对内容保持在一起,并保留当前尚未总结的尾部。
无论会话或上下文窗口的大小如何,内置压缩都会总结一个模型请求中的较旧历史记录。分割转弯会添加一个转弯前缀请求,而失败的保障质量审核会在每次纠正尝试中添加一个请求。每个请求的对话输入上限为 160,000 个字符(约 40,000 个标记),或者当摘要生成器自己的上下文窗口较小时更少。更大的历史记录按此顺序填充:最新消息逐字记录,占预算的一半;您的旧消息,其中包含询问、决定和更正,在一个季度内,每条消息最多缩减为 2,000 个字符,并在它们不完全适合时均匀地分布在历史记录中;最古老的消息,十分之一;其余消息的间隔均匀,每条消息被修剪为 6,000 个字符。每个间隙都标有遗漏的消息数量,并且告诉摘要者不要猜测其内容并保留先前摘要的事实。中文、日文和韩文 (CJK) 字符按其近似标记权重进行计数。该界限仅适用于摘要器输入;文字记录保留了每条消息。
完整的对话历史仍保存在磁盘上。压缩只会改变模型在下一轮看到的内容。
对于直接 OpenAI API-key 会话,/responses/compact 端点可以返回保留消息的规范窗口,后跟加密检查点。 OpenClaw 为下一个请求和重新启动后保留整个窗口,包括保留的辅助消息。提供者选择保留哪些消息;它不必保留每条原始用户消息。请参阅 OpenAI 服务器端压缩。
内置摘要接收文本,而不是图像像素。省略的图像和其他非文本输入接收标记,例如 [image data omitted from summary input],而不声称模型处理了数据。前八条受影响的消息每条最多接收两个固定标记;进一步的遗漏将收到一份汇总报表。这些添加内容(包括新保留的角色标签和分隔符)每个摘要器请求总计最多 847 UTF-8 字节,并且计入令牌估计值。现有案文不受此省略预算的限制。自定义压缩提供程序仍会收到原始消息内容。
启用内置安全质量防护后,OpenClaw 使用 CJK-aware 代币估算来预算最终摘要,然后检查其结构、待处理请求和准确标识符。失败的检查仅获得配置的纠正尝试次数。如果这些尝试已用尽,或者所需的事实无法满足,OpenClaw 会存储最佳的可用生成摘要,以便会话可以继续。失败的纠正生成也可以重用早期的摘要。
这种后备是故意有损的。它将生成的事实保留在结构化主体中,并尝试保留最新的请求上下文、准确的标识符、分流进度和最近的回合。如果它们不适合,它会首先删除最长的标识符,然后放宽所需事实的保留。因此,旧的详细信息、标识符和待处理的请求可能会离开模型上下文。压缩条目记录details.qualityDegraded,/status显示降级状态,并且可见警告表明/new或更大的模型。即使 notifyUser 为 false 时也会出现此警告。
如果未生成摘要,则生成、模型解析或凭证失败将保留原始历史记录。始终尊重呼叫者发起的取消。如果配置的压缩提供程序失败或返回空结果(包括没有调用方取消的提供程序本地超时),则会回退到内置摘要生成器。自动压缩还有一个单独的超时回退,可以在没有生成摘要的情况下提交;参见自动压实。
自动压缩
默认开启自动压缩。当会话接近上下文限制时,或者模型返回上下文溢出错误时(在这种情况下 OpenClaw 会先压缩再重试),它就会运行。
在内置运行时中,本机 ChatGPT 登录在正常请求边界(包括已完成的工具轮次之间)使用 V2 压缩。当已知或预计的请求占用率达到基于预留的提示预算和上下文窗口的 90%(向下舍入)中的较小者时,它开始。对于 500,000 个代币窗口和 20,000 个代币储备,这意味着 450,000 个代币,而不是 480,000 个。完整的传出请求仍必须适合模型窗口:单个大型待处理消息或工具结果可能会消耗安全边界之前的剩余空间,在这种情况下,OpenClaw 会保留现有的客户端后备,而不是删除待处理内容。其他提供商、手动 /compact 和溢出恢复保留其现有的阈值和行为。
如果提供者在工具调用完成后拒绝请求,内置运行时可以压缩并从记录的结果继续。它保留当前模型和帐户,保留原始请求,并且不重播已完成的操作。这种恢复需要稳定的工具结果;待处理的工具、批准、取消以及有意结束转弯的工具保留其正常处理。如果稍后网关重新启动中断了继续运行,即使压缩已经汇总了输入,恢复也会保留接受的输入。
对于 OpenAI- 兼容聊天完成,以 length 结尾的自动上下文上限响应也会进入此恢复。 OpenClaw 保留不完整的候选者及其工具调用,直到知道完成原因为止。这种缓冲是有界的;过大的响应将恢复普通流式传输并保留其正常的 length 结果。显式输出限制保留其正常行为。
在自动减少 OpenAI- 兼容工具请求的输出预算之前,OpenClaw 使用等于模型声明的最大输出的八分之一的最小输出预算,范围在 16 到 2,048 个代币之间。如果该最小值无法满足,则在发送请求之前运行压缩。没有活动工具的请求保留 16 个令牌下限,并且适合的明确输出限制仍然有效。
溢出恢复会修剪当前模型上下文窗口内的工具结果。较旧的消息和重置边界保留在保留的历史记录中,而不会复制到新的记录条目中。
如果溢出恢复无法使提示适合,失败的回复会建议 /reset、/new 或更大上下文的模型。 Control UI 在“详细信息”中显示此指导,并将其保存在已保存的聊天历史记录中。对于单个过大的提示,请在新会话中重新发送之前缩短提示。
停止或超时运行也会停止其溢出或超时恢复。内置 OpenClaw 运行时不会启动进一步的恢复挂钩、维护、转录截断或取消后重试。取消不是回滚:已经完成的压缩保留在记录中并且仍然被计数,而不发送延迟的回复。上下文估计遵循最新模型或压实观察;账单总额保持独立。
如果轮次仍处于活动状态时自动压缩的摘要超时(摘要截止时间已过期,或者提供者回答 HTTP 408 或 504)并且无法重用较早的摘要,则 OpenClaw 会在没有摘要的情况下提交该压缩,而不是结束轮次。它逐字保留相同的最新消息,包括完整的工具调用和结果、待处理的请求和分流的原始请求,向前传送先前的摘要,并记录有多少较旧的消息被删除。然后继续回复,下一回合不再等待相同的摘要。网关日志记录[compaction-diag] fallback ... reason=timeout summary=deterministic;没有添加聊天通知。超时摘要不会移动到模型回退链,因为每个额外的模型都可能会在等待中添加另一个完整的超时窗口。停止和运行超时总是会取消恢复。当无法重用早期摘要时,手动 /compact 和其他摘要器错误会不断报告失败。
这也适用于保护模式:从未汇总的旧事实离开模型上下文,并且后来的压缩不会将它们带回来,因为每个事实都从前一个压缩边界开始。文字记录仍然保留每条消息以供历史记录和显式检索。如果没有此异常,接下来的每个回合都会等待相同的超时,并且会话将保持不可用。
内置的 OpenClaw 运行时在推理之前执行所需的检查点和压缩。这包括帮助者完成和批准后续轮流;他们面向用户的模型选择保持不变。在持久网关会话中,可选的内存刷新和压缩会等待回复传递完成并且其前台所有者已关闭。该工作使用单独的会话所有者和回合的剩余时间。新消息在读取会话进行自己的推理之前会取消并解决可选工作。
一次性 openclaw agent --local 命令跳过可选的转弯后工作;下一个命令在推理之前执行所需的维护。通用 CLI 后端保留其现有的同步主机压缩,本机运行时保留其自己的压缩策略。记录可选的维护故障,而不替换已完成的回复。取消、重新启动或替换会话仍然会限制活跃的写入者。
设置 agents.defaults.compaction.enabled: false 以禁用内置运行时中的主动阈值压缩和可选维护。溢出恢复压缩和手册 /compact 仍然可用。
你会看到:
- 普通 Gateway 日志中出现
embedded run auto-compaction start/complete。 🧹 Auto-compaction complete处于详细模式。/status显示🧹 Compactions: <count>。
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(基岩)input is too long for the model`inputs` must have less than N tokens和`inputs` tokens + `max_new_tokens` must be <= N(Hugging Face TGI;仅输出max_new_tokens限制不会触发压缩)ollama error: context length exceeded
手动压缩
当运行时支持手动压缩时,在聊天中键入 /compact 即可强制压缩。在内置的OpenClaw运行时中,添加指令来引导摘要,如下例所示。当通过 Codex 登录或 API 密钥在本机 Codex 会话中使用手动压缩时,请使用裸 /compact;焦点指令不会传递到 Codex。使用 Sign in with ChatGPT 的本机 Codex 会话支持自动压缩,但无法运行手动 /compact。
如果转弯处于活动状态,/compact 会在取消转弯之前给予最多 60 秒的时间来完成,并再等待最多 15 秒以使其停止。当取消成功时,命令的回复会要求您重新发送中断的请求,包括当运行仍在停止且压缩无法继续时。
在 Telegram 等通道上,/compact 在中断活动运行或开始压缩之前确认传入命令,因此通道的五分钟采用看门狗不会中止并重播它。压缩使用 agents.defaults.compaction.timeoutSeconds 并在回复中报告其结果;取消仍然会停止工作。
内置 OpenClaw 运行时中的客户端压缩将焦点传递给较旧的历史记录和分轮前缀摘要。主机将操作员提供的焦点限制为 800 个 Unicode 代码点,并在将其添加到模型请求之前将其转义为提示数据。
自动会话标题生成在后台运行,不会阻止手动压缩。网关压缩请求立即拒绝承认的轮流并接受排队的工作。前台准入结束后,在请求重新检查会话之前,仍在保存或清理的已完成回复可能需要长达 15 秒的时间才能完成。带内命令将其自己的执行排除在此等待之外,但仍等待其他已完成的编写器。
客户端手动压缩使用 agents.defaults.compaction.keepRecentTokens(默认值:20,000)作为其切点预算,并将最近的尾部保留在重建的上下文中。
会话的每个模型 contextTokens 上限不会缩小汇总模型的本机 contextWindow。较小的主动输入预算仍然适用于正常轮次,而摘要器使用自己的窗口来读取较旧的历史记录。
当内置的 OpenClaw 运行时准备好前台请求时,客户端自动压缩在选择保留尾部时也会考虑其系统提示、工具模式、挂起的输入和输出保留。它可能会保留较少的最近消息,以便摘要和对话能够结合在一起。选择较大的摘要模型不会增加前景模型的上下文窗口。储备是首选目标,而不是提供者代币限制。当固定提示或待处理输入消耗该目标时,OpenClaw 仍然可以回收较旧的历史记录,同时保留未处理的请求。这样的替换必须严格减少历史;不变或更大的结果被拒绝。否则,自动压缩需要完全替换以适应估计的目标。在这些请求事实可用之前运行早期所需的预检,并且仍然使用基于历史的大小调整;它不能保证这个首选净空。
如果单独的固定指令和工具超出了模型窗口,或者在准备的请求仍然太大时无法压缩进一步的历史记录,则 OpenClaw 会报告估计的预算组成部分,而不是将结果视为无害的跳过。使用 /context detail 来识别大型贡献者、缩短请求或选择更大上下文的模型。 /new 清除对话历史记录,但保留固定的指令和工具。
配置
在 openclaw.json 中的 agents.defaults.compaction 下配置压缩。下面列出了最常见的旋钮;有关完整参考,请参阅 会话管理深入探讨 。
使用不同的模型
内置的 OpenClaw 运行时开始使用活动会话模型进行压缩。设置 agents.defaults.compaction.model 以选择不同的汇总模型。覆盖接受 provider/model-id 字符串或在 agents.defaults.models 下配置的裸别名:
在压缩开始之前,裸配置的别名会解析为其规范化的提供程序和模型。如果裸值同时与别名和配置的文字模型 ID 匹配,则文字模型 ID 获胜。活跃提供商上的模型 ID 仍具有无与伦比的裸值。
如果在压缩等待开始时重新加载网关配置,则压缩会一起使用新加载的上下文引擎和模型设置。其请求的工作区和脚本保持不变。
这同样适用于本地模型,例如专用于总结的第二个 Ollama 模型:
如果未设置,压缩将从当前活跃的会话模型开始。如果由于适合回退的提供方错误导致总结失败,OpenClaw 会使用该会话现有的模型回退链重试该压缩。回退选择是临时的,不会写回会话状态。显式的 agents.defaults.compaction.model 覆盖项保持精确,不会继承会话回退链。
当主要身份验证配置文件已处于冷却状态时,预检压缩也会使用该链。每位考生必须在总结前通过审核;健康的回退可以压缩会话,而无需等待主要冷却时间到期。
在保护模式下,当无法重用早期摘要时,内置摘要的提供程序超时和速率限制仍然适用于该链。摘要截止日期或 HTTP 408 或 504 改为使用自动超时回退(请参阅 Auto-compaction)。呼叫者取消和失败的保障质量检查不会触发模型切换。
标识符保留
默认情况下,压缩汇总请求精确的不透明标识符保留 (agents.defaults.compaction.identifierPolicy: "strict")。降级摘要可能会忽略不适合的标识符。设置 agents.defaults.compaction.identifierPolicy: "off" 以禁用保留指导。自定义指导属于压缩提供商的 summarize() 实现。
活跃转录字节守卫
设置 agents.defaults.compaction.maxActiveTranscriptBytes 时,如果转录历史记录达到该大小,OpenClaw 会在运行之前触发正常的本地压缩。这对于长时间运行的会话非常有用,其中提供者端上下文管理可以保持模型上下文健康,同时持久的转录历史记录不断增长。设置正字节数或大小字符串(例如 "20mb")以选择加入; 0 或未设置的值会禁用防护。它不分割原始字节;它要求正常的压缩管道创建语义摘要。如果压缩被拒绝或使历史超出限制,则转向将继续以最近历史的有限视图进行。 OpenClaw 忽略最旧的整圈,保留工具调用及其结果,并保留系统指令和当前请求。一个过大的历史转折可能会被完全省略。此回退不会重写已保存的消息或将失败的尝试计为成功的压缩。即使禁用压缩通知,它也会显示通知;重新发送省略的历史记录中的任何重要细节。该界限适用于选定的历史记录,而不是固定指令、工具定义或当前请求。
抑制的字节压缩重试在后续回合中仍然使用有界视图。使宿主转录本保持不变的本机压缩保留了重试抑制。主机压缩清除或刷新它;更改会话或限制、低于限制或增长另一个完整阈值也会重新武装警卫。保留的历史记录在磁盘上仍然可用,并且可能会继续增长;这不是存储保留限制。对于 Codex 应用程序服务器会话,相同的阈值限制本机转出脚本和超大本机线程重新启动。
H历史水合字节限制
嵌入式运行时还限制了它为模型重放加载的历史记录,独立于基于令牌的压缩和 maxActiveTranscriptBytes。其字节上限是有效上下文令牌预算的八倍,最小为 1 KiB,最大为 64 MiB。这是绑定在序列化模型上下文事件上的资源,而不是令牌计数。私人转录元数据和工具结果详细信息被排除在外,但事件信封和其他内容在模型的代币预算已满之前仍然可以达到字节上限。
当超过此上限时,历史加载器会以四分之一大写的步长推进省略的前缀。它更喜欢完整的转弯,保留工具调用及其结果,并保留最新的压实摘要。保留的历史记录开始时接近可用字节容量的 75%,具体取决于事件和回合大小,然后向上限增长。其现有前缀在步骤之间保持不变,包括跨工作程序或进程重新启动。独立的事件计数限制仍然可以缩短异常密集的历史记录。
此选择不会删除已保存的历史记录、创建摘要、运行内存刷新或触发压缩通知。因此,当代币预算有空间时,较旧的上下文可以保留在模型的视图之外。分块用一些直接历史记录来换取前缀缓存重用;它不能解决 byte/token 不匹配的问题。当您需要语义摘要时,请使用 /compact。正常压缩触发器和选择加入的活动转录本字节保护保持不变。
压缩通知
默认情况下,例行压缩以静默方式运行。降级的摘要始终会生成一条警告,指出较旧的详细信息、标识符或待处理的请求可能会丢失,而 /new 或更大的模型可以提供帮助。设置 notifyUser 在压缩开始和完成时以及在预压缩内存刷新耗尽但回复仍然继续时也显示简短的状态消息:
内存刷新
在压缩之前,OpenClaw可以运行silent内存刷新来保存持久上下文。 Memory Core 附加到工作区内存文件;另一个选定的内存插件可以通过自己的工具进行持久化,并使用声明的只读查找工具首先检查现有内存。这些工具保留源对话的内存受众和沙箱限制。缺少查找工具会产生警告,但不会阻止持久性。如果策略删除每个声明的持久性工具,OpenClaw 会跳过刷新并继续压缩。
当此内务处理轮次应使用本地模型而不是活动对话模型时,设置 agents.defaults.compaction.memoryFlush.model:
内存刷新是可选的维护:失败(包括用尽的重试)不会重置会话或丢弃对话历史记录。如果不需要compaction或者compaction成功,则OpenClaw继续回复;启用 notifyUser 后,用尽的刷新重试也会产生降级通知。如果所需的压缩失败,OpenClaw 会报告该失败并保持对话完整,而不是自动重新开始。
内存刷新模型覆盖是精确的,不会继承活跃会话的回退链。详情和配置请参见 内存。
Provider 和引擎行为
Provider 检查点
当嵌入式响应提供程序返回压缩窗口时,OpenClaw 会保留完整返回的上下文以及检查点。最近回合历史记录限制不会丢弃符合条件的检查点,并且保留的上下文仍然计入模型的即时预算。保存的检查点限制为16个MiB;过大或不兼容的端点输出使用正常的客户端压缩路径而不是被截断。
成功继续后,当保存的请求前缀仍然与当前检查点、对话和提供者身份匹配时,OpenClaw 使用提供者测量的上下文使用情况。新内容和当前请求开销仍接受本地估计。编辑或不兼容的历史记录会回退到估计,而不更改已保存的对话。
本机 ChatGPT 登录路径在下一个正常模型请求边界(包括已解决的工具轮次之间)使用流式 Codex V2 压缩。它保留正常的请求表面并保存保留的用户消息以及通过现有会话所有者的不透明检查点。失败或取消的流不会安装检查点。在此路线上,手动 /compact(带或不带焦点指令)和提供商确认的溢出使用客户端压缩,而不是 V2。有关控制和回退行为,请参阅 OpenAI 高级配置。
对于 V2-eligible 请求,回复级别令牌维护和可选的中转预检查将本地恢复推迟到此边界,因此它们无法抢占提供程序压缩。内存刷新和转录字节维护仍在运行。其他请求保留提供者绑定的预检查,包括在没有匹配的当前运行使用情况可用时保存的检查点压力。
预测的上下文压力在下一个请求之前使用预算压缩。默认情况下,公共 OpenAI 响应 API 和本机 xAI 使用其压缩端点进行预算压缩,并用于没有焦点指令的 /compact。 params.responsesCompactEndpoint: false 禁用模型的该端点。 /compact <focus> 保留客户端摘要,因此说明适用。提供者确认的溢出保留了客户端恢复路径,因为紧凑端点也需要其输入来适应。端点故障回退到客户端汇总。
一旦准备好前台请求预算,返回的端点窗口也必须适合其固定指令、工具、待处理输入并在 OpenClaw 保存之前进行保留。如果保留的用户消息仍然超出该预算,则客户端压缩会选择较小的最近尾部,而不是重试相同的超大窗口。
返回的窗口逐字保留最近的用户消息,并且在 xAI 上系统也会提示(公共 OpenAI 端点将其接收为 instructions)。转录本的准备不会秘密掩盖该内容。丢弃的端点结果或端点故障将记录为警告并附有原因。
如果仅待处理的输入填充了模型的上下文窗口,则恢复会要求较小的消息或较大的上下文模型,而无需重复压缩历史记录。稍后的消息保留其正常的恢复预算。
如果旧版本留下重播所需的完整窗口不可用,OpenClaw 会要求您运行 /compact。该命令通过客户端压缩从保存的对话中重建上下文。它不会猜测丢失的提供者上下文或删除记录。
在 Anthropic 记录阈值压缩的模型上,直接 Anthropic API-key 请求要求 API 在输入达到阈值后在普通请求内进行压缩,并且 OpenClaw 在以后的请求中重播返回的摘要。 params.anthropicServerCompaction: false 为模型禁用它。如果 Anthropic 返回空摘要,则 OpenClaw 继续发送现有历史记录,并且其客户端压缩仍然是后备。请参阅 人工服务器端压缩 。
内存刷新会禁用提供程序服务器端压缩,包括 Anthropic 阈值压缩和 OpenAI 内联压缩,因此内存提取会看到未汇总的历史记录。
后继转录
上下文引擎可以返回同一代理内的显式压缩后继会话身份、会话密钥和存储。 OpenClaw 在维护、挂钩或重试使用已接受的后继者之前发布它,同时保留当前作者的所有权。之后取消不会回滚已完成的转换。主动回复遵循其剩余会话状态读取的已接受身份;不相关的重置和取消仍然会停止陈旧的工作。工具策略分类保留其独立捕获的会话身份。内置 SQLite 压缩器保留当前会话身份,并且不会创建第二个运行时脚本。
worker 放置 无法在压缩期间将所有权转移到不同的会话身份。当展示位置拥有会话时,自定义引擎必须保留当前身份,或者操作员必须在重试之前将会话移回网关。被拒绝的转换会使原始会话和工作人员声明保持不变。
OpenClaw 不创建压缩检查点记录或快照副本。现有的历史记录参考仍然受到正常会话清理的保护;删除检查点控件不会删除存储的对话历史记录。
可插拔压实供应商
插件可以通过插件 API 上的 registerCompactionProvider() 注册自定义压缩提供方。注册并配置后,OpenClaw 会将摘要生成委托给该提供方,而不是内置的 LLM 流水线。
要使用已注册的提供方,请在配置中设置其 id:
设置 provider 会自动强制 mode: "safeguard"。提供方会接收与内置路径相同的压缩指令和标识符保留策略,而 OpenClaw 在提供方输出后仍会保留最近轮次和拆分轮次后缀上下文。
内置质量审核及其纠正重试仅适用于内置汇总。配置的提供程序输出保留提供程序的现有验证语义。
压缩与修剪
| 压缩 | 修剪 | |
|---|---|---|
| 它做什么 | 总结较早的对话 | 截断旧的工具结果 |
| 已保存? | 是(在会话转录中) | 否(仅内存中,每次请求) |
| 范围 | 整个对话 | 仅工具结果 |
会话修剪 是一个更轻量的补充,它会截断工具输出而不进行摘要。
故障排查
压缩过于频繁? 模型的上下文窗口可能较小,或者工具输出可能较大。尝试启用 会话修剪。
压缩后上下文感觉陈旧? 使用 /compact Focus on <topic> 来引导摘要,或者启用 内存刷新 以便笔记得以保留。
需要一个全新开始? /new 会在不压缩的情况下开启一个新会话。
有关高级配置(保留 token、标识符保留、自定义上下文引擎、OpenAI 服务器端压缩),请参见 Session management deep dive。