OpenClaw 上下文窗口与压缩机制详解:自动压缩、/compact 命令与 agents.defaults.compaction 完整配置指南
OpenClaw 上下文窗口与压缩机制详解:自动压缩、/compact 命令与 agents.defaults.compaction 完整配置指南
每个模型都有固定大小的上下文窗口(单次可见的最大 token 数),长时间运行的会话会不断累积消息与工具调用结果,最终逼近甚至突破模型限制。OpenClaw 通过在窗口空间紧张时对较早历史记录进行压缩(将早期对话总结为紧凑摘要条目、保留近期消息),把会话持续保持在模型限制之内。本文以 docs/zh-CN/concepts/compaction.md 为骨架,结合 src/agents/compaction.ts、src/agents/pi-embedded-runner/compact.ts、src/agents/pi-embedded-runner/run.ts、src/auto-reply/reply/commands-compact.ts 等源码实现,完整讲解压缩的工作原理、自动/手动触发方式、
agents.defaults.compaction全部配置参数,以及压缩与修剪(session pruning)的区别。读完本文,你将能在实际会话中熟练使用/compact、读懂/status中的压缩计数、按需调优压缩策略,并理解 OpenClaw 如何在接近上下文上限时保证会话不中断。
什么是压缩
压缩(Compaction)指的是:将较早的对话总结成一条紧凑的摘要条目,同时保持近期消息原样不变。压缩之后,后续每次请求实际使用的上下文由两部分组成:
- 压缩摘要(对早期历史的总结);
- 压缩点之后的近期消息(未被压缩的部分)。
与"只读丢弃"不同,压缩结果是持久化的——摘要会写入会话的 JSONL 历史记录(session 文件)中,而不是仅存在内存里。这意味着即使 Agent 重启或切换进程,压缩得到的摘要依然保留在会话历史中,后续请求可以继续基于摘要恢复上下文。
从源码看,OpenClaw 的压缩实现位于 src/agents/compaction.ts,它负责总结的生成(generateSummary / summarizeChunks)、消息分块(chunkMessagesByMaxTokens、splitMessagesByTokenShare)、渐进式降级(summarizeWithFallback)以及分阶段合并(summarizeInStages)等核心逻辑,而触发与执行编排则位于 pi-embedded-runner 模块中。
上下文窗口来源
上下文窗口因模型而异。OpenClaw 使用已配置提供商目录中的模型定义来确定当前 Agent 的上下文限制,而不是硬编码一个全局数值。从实现上看,src/agents/compaction.ts 中的 resolveContextWindowTokens 读取 model.contextWindow,仅在模型未提供该字段时才回退到默认值 DEFAULT_CONTEXT_TOKENS(定义于 src/agents/defaults.ts,当前为 200_000 token)。
这意味着:你在 agents 配置中指定的 provider 与 model 决定了压缩触发判断所用的上下文上限;切换不同模型,压缩阈值也会随之变化。
自动压缩(默认开启)
当会话接近或超过模型的上下文窗口时,OpenClaw 会自动触发压缩,并可能使用压缩后的上下文重试原始请求。自动压缩在默认配置下即处于启用状态(详见下文"配置"中 mode: "safeguard" 的默认值来源)。
触发类型
从 src/agents/pi-embedded-runner/compact.ts 的源码可见,压缩触发被区分为三种类型(trigger 字段):
| 触发类型 | 说明 |
|---|---|
budget |
基于上下文预算/阈值的主动压缩(自动) |
overflow |
上下文溢出后的恢复性压缩(自动) |
manual |
用户执行 /compact 手动触发 |
自动触发时压缩目标为 budget,手动触发时目标为 threshold(见 compact.ts),即手动压缩会更彻底地压缩到阈值以下。
溢出恢复与超时触发(源码级)
在 src/agents/pi-embedded-runner/run.ts 中,运行循环会对两类失败场景做自动压缩恢复:
- 上下文溢出:当 prompt 提交因上下文过大失败(溢出错误)时,运行器会诊断当前 token 使用情况(
[context-overflow-diag]日志),只要本次 attempt 尚未压缩,就在MAX_OVERFLOW_COMPACTION_ATTEMPTS上限内自动执行一次trigger: "overflow"的压缩并重试原始请求;若压缩后溢出仍然存在,则继续重试直至达到上限。 - 超时触发压缩:当 LLM 调用超时且当前 prompt token 使用率很高(如 >70%)时,运行器会先尝试
timeout-compaction,压缩成功后再重试 prompt,避免高 token 占用导致的超时反复出现。
此外,压缩流程还支持 before_compaction 与 after_compaction 两个生命周期钩子(run.ts),便于插件在压缩前后介入(例如持久化状态、记录诊断信息)。
你会在界面上看到什么
自动压缩发生时,你会观察到两类提示:
- 详细模式(verbose)下显示
🧹 Auto-compaction complete; /status命令显示🧹 Compactions: <count>,其中<count>是当前会话累计的压缩次数。
压缩计数会持久化到会话元数据中。执行 /compact 成功后,commands-compact.ts 会调用 incrementCompactionCount 更新会话统计(实现在 src/auto-reply/reply/session-updates.ts),从而使 /status 中的计数保持准确。
压缩前的静默记忆刷写
在压缩之前,OpenClaw 可能先运行一次静默记忆刷写(memory flush)轮次,把持久化笔记写入磁盘——因为压缩会丢弃早期对话细节,若模型此前只把重要信息"记在脑子里"而没有落盘,压缩后就会永久丢失。关于记忆文件布局、刷写时机与配置的完整说明,见 docs/zh-CN/concepts/memory.md;其配置同样位于 agents.defaults.compaction.memoryFlush 下(下文配置章节有示例)。
手动压缩:/compact 命令
使用 /compact 可以强制执行一次压缩,并可附带指令来引导总结的关注方向:
/compact Focus on decisions and open questions
上面的示例会指示总结过程重点保留"决策"与"未决问题"。
命令处理流程(源码级)
从 src/auto-reply/reply/commands-compact.ts 可以看到 /compact 的完整处理逻辑:
- 授权校验:非授权发送者(非 owner/被授权者)发出的
/compact会被直接忽略并记录日志。 - 会话校验:若缺少
sessionId,返回⚙️ Compaction unavailable (missing session id).。 - 中断进行中的运行:若该会话当前有正在执行的 Agent 运行(
isEmbeddedPiRunActive),会先abortEmbeddedPiRun中止,并等待运行结束(最长 15 秒),避免压缩与运行写历史产生竞态。 - 提取指令:
extractCompactInstructions会剥离群组提及与结构化前缀,支持/compact后直接跟文本或:分隔的文本作为自定义总结指令。 - 执行压缩:调用
compactEmbeddedPiSession,trigger: "manual",senderIsOwner等身份信息一并传入。 - 结果输出:压缩成功时输出
⚙️ Compacted (<压缩前> → <压缩后>)(使用formatTokenCount格式化 token 数),若本次没有可压缩内容则输出⚙️ Compaction skipped并附上原因,失败则输出⚙️ Compaction failed;最后还会附带当前上下文使用情况(formatContextUsageShort)。
跳过与失败原因
OpenClaw 会把压缩"跳过/失败"的原因翻译为人类可读文案(formatCompactionReason),常见的有:
nothing compactable in this session yet(还没有可压缩的内容);context is below the compaction threshold(上下文低于压缩阈值,无需压缩);session was already compacted recently(近期已压缩过);no real conversation messages yet(尚无真实对话消息)。
在底层,src/agents/pi-embedded-runner/compact-reasons.ts 的 classifyCompactionReason 会按关键词将原始原因分类为机器可读的枚举,供统计与诊断使用:
| 原始原因包含 | 分类结果 |
|---|---|
nothing to compact |
no_compactable_entries |
below threshold |
below_threshold |
already compacted |
already_compacted_recently |
still exceeds target |
live_context_still_exceeds_target |
guard |
guard_blocked(被压缩质量守护拦截) |
summary |
summary_failed(总结生成失败) |
timed out / timeout |
timeout |
400/401/403/429 |
provider_error_4xx |
500/502/503/504 |
provider_error_5xx |
| 其他 | unknown |
配置:agents.defaults.compaction
压缩的全部调优项集中在 agents.defaults.compaction 配置节点下,完整字段定义见 config/types.agent-defaults.ts。核心参数如下:
| 配置项 | 类型/取值范围 | 默认值 | 说明 |
|---|---|---|---|
mode |
"default" | "safeguard" |
"safeguard" |
压缩总结模式。未显式设置时,config/defaults.ts 中的 applyCompactionDefaults 会强制补齐为 safeguard(即带质量守护的压缩模式,这就是"自动压缩默认开启"的实现来源) |
reserveTokens |
number | — | Pi 压缩的目标保留 token 数(压缩后为后续生成保留的空间) |
keepRecentTokens |
number | — | 用于选择压缩切割点(cut-point)的"保留最近消息"token 预算 |
reserveTokensFloor |
number | 0(0 表示禁用下限) | 强制执行的保留 token 下限;设置如 20000 可确保压缩后仍为输出/后续轮次留足空间 |
maxHistoryShare |
number(0.1–0.9) | 0.5 |
safeguard 修剪时历史最多占上下文窗口的比例;对应 compaction.ts 中 pruneHistoryForContextShare 的 maxHistoryShare |
customInstructions |
string | — | 追加到总结提示中的自定义指令,可用于保持语言风格或人格连续性(也即 /compact 附带的指令) |
recentTurnsPreserve |
number | — | 在压缩总结上下文中原样保留最近 N 轮 user/assistant 对话 |
identifierPolicy |
"strict" | "off" | "custom" |
"strict" |
压缩总结时对不透明标识符(UUID、哈希、ID、token、API key、主机名、IP、端口、URL、文件名等)的保留策略 |
identifierInstructions |
string | — | identifierPolicy: "custom" 时使用的自定义标识符保留指令;为空则回退到内置指令 |
qualityGuard.enabled |
boolean | false |
是否启用总结质量审计与再生成重试 |
qualityGuard.maxRetries |
number | 1(启用时) |
质量审计失败后的最大再生成次数 |
postIndexSync |
"off" | "async" | "await" |
— | 压缩后会话记忆索引同步模式 |
memoryFlush |
对象 | 启用 | 压缩前的静默记忆刷写配置(见下文) |
postCompactionSections |
string[] | ["Session Startup", "Red Lines"] |
压缩后要注入的 AGENTS.md 的 H2/H3 小节名;设为 [] 可完全关闭压缩后上下文注入 |
model |
string | 主模型 | 压缩总结专用的模型覆盖,例如 "openrouter/anthropic/claude-sonnet-4-5";不设置时使用 Agent 主模型 |
timeoutSeconds |
number | 900 |
单次压缩操作的最大耗时(秒) |
truncateAfterCompaction |
boolean | false |
压缩后是否截断会话 JSONL 文件以移除已被总结的条目,防止长会话文件无限增长 |
典型配置示例
{
agents: {
defaults: {
compaction: {
mode: "safeguard",
reserveTokensFloor: 20000,
keepRecentTokens: 60000,
maxHistoryShare: 0.5,
identifierPolicy: "strict",
recentTurnsPreserve: 2,
customInstructions: "保持使用简体中文总结,突出未完成的决策。",
model: "openrouter/anthropic/claude-sonnet-4-5",
timeoutSeconds: 900,
truncateAfterCompaction: true,
qualityGuard: {
enabled: true,
maxRetries: 1,
},
memoryFlush: {
enabled: true,
softThresholdTokens: 4000,
systemPrompt: "Session nearing compaction. Store durable memories now.",
prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
},
},
},
},
}
压缩前记忆刷写(memoryFlush)详解
memoryFlush 控制压缩前的静默记忆刷写行为(config/types.agent-defaults.ts):
enabled(默认true):是否启用刷写;softThresholdTokens:当会话距离压缩阈值还有这么多 token 时提前触发刷写。具体触发条件为:会话 token 估计超过contextWindow - reserveTokensFloor - softThresholdTokens(见 docs/zh-CN/concepts/memory.md);forceFlushTranscriptBytes:当转录体积达到该字节阈值(支持"2mb"这样的字节串)时强制刷写,0表示禁用;prompt/systemPrompt:刷写轮次使用的用户提示与系统提示。默认提示包含NO_REPLY,因此该轮次对用户是静默的(模型通常只落盘记忆、不发送可见回复);- 刷写每个压缩周期只执行一次(在
sessions.json中跟踪); - 若会话以
workspaceAccess: "ro"或"none"在沙箱中运行(工作空间不可写),则跳过刷写。
压缩的底层实现原理
这一节把 src/agents/compaction.ts 的关键机制展开,帮助你理解为什么压缩能在大上下文下稳定工作。
安全边际与 token 估算
压缩的每一步都建立在 token 估算之上:estimateMessagesTokens 使用字符/4 的启发式估算。为了弥补估算偏差(多字节字符、特殊 token、代码 token 等会低估),OpenClaw 引入了 SAFETY_MARGIN = 1.2(20% 缓冲,见 compaction.ts),所有分块与超限判断都会乘以该系数;同时为总结提示、系统提示、先前摘要与序列化包装预留 SUMMARIZATION_OVERHEAD_TOKENS = 4096 的固定开销。
分块总结与自适应比例
- 当消息总量超过单块上限时,
chunkMessagesByMaxTokens会按maxTokens / SAFETY_MARGIN的有效上限切块;单条超大消息(本身超过上限)会被单独切成一块,避免无限增长的块。 computeAdaptiveChunkRatio根据平均消息大小动态调整分块比例:当平均单条消息超过上下文的 10% 时,分块比例会从基准BASE_CHUNK_RATIO = 0.4向下缩减(下限MIN_CHUNK_RATIO = 0.15),防止单块过大超出模型限制。isOversizedForSummary判断单条消息是否过大而无法安全总结(超过上下文窗口的 50%)。
渐进式降级(summarizeWithFallback)
总结并非一次性成功。summarizeWithFallback 采用三级策略:
- 先尝试对全部消息做完整总结;
- 若失败,剔除所有 oversized 消息,仅对剩余消息做部分总结,并在摘要末尾以
[Large <role> (~N K tokens omitted from summary)]标注被省略的大消息; - 若部分总结仍失败,最终兜底返回统计信息(
Context contained N messages (M oversized). Summary unavailable due to size limits.),保证压缩流程不会因总结失败而卡死。
分阶段合并(summarizeInStages)
当消息数量超过 minMessagesForSplit(默认 4)且 token 总量超过单块上限时,summarizeInStages 会先用 splitMessagesByTokenShare 按 token 份额把消息切分为多个批次(默认 DEFAULT_PARTS = 2),逐批总结出 partial summaries,再调用模型将多份 partial summaries 合并为一份连贯的总结。合并指令 MERGE_SUMMARIES_INSTRUCTIONS(compaction.ts)明确要求保留:
- 活动任务及其当前状态(进行中 / 阻塞 / 待处理);
- 批量操作的进度(如"5/17 items completed");
- 用户最后请求的内容及正在进行的处理;
- 已做的决策及其理由;
- TODO、未决问题与约束;
- 承诺过的后续事项(follow-ups)。
且明确要求优先保留近期上下文——"Agent 需要知道自己正在做什么,而不仅仅是讨论过什么"。
安全设计
压缩涉及把历史消息交给模型再总结,因此有两处刻意设计的安全点(compaction.ts 与 compaction.ts):
toolResult.details可能包含不可信或超长的载荷(如文件内容),一律不进入总结提示——estimateMessagesTokens与summarizeChunks都先调用stripToolResultDetails剥离该字段;- 默认的
identifierPolicy: "strict"会注入标识符保留指令(compaction.ts),要求总结时原样保留所有不透明标识符(UUID、哈希、ID、token、API key、主机名、IP、端口、URL、文件名),防止压缩把关键引用改写坏。
失败重试
每块总结通过 retryAsync 执行,最多尝试 3 次,退避间隔 500ms–5000ms、抖动 0.2;AbortError 不参与重试(compaction.ts),从而兼顾稳定性与及时取消。
会话 JSONL 与历史修剪的配合
压缩后,会话的 JSONL 历史文件会被更新以包含新的摘要条目。若开启 truncateAfterCompaction: true,文件还会移除已被总结的旧条目,防止长会话文件无限增长。而在移除历史时,pruneHistoryForContextShare(compaction.ts)会通过 repairToolUseResultPairing 修复被丢弃块留下的孤儿 tool_result(其对应的 tool_use 已被丢弃),避免后续请求因 unexpected tool_use_id 报错——这是 Anthropic 风格 API 的硬性要求。
压缩与修剪(Session Pruning)的区别
两者名字相近、目标都是控制上下文体积,但机制完全不同:
| 维度 | 压缩(Compaction) | 会话修剪(Session Pruning) |
|---|---|---|
| 行为 | 将早期对话总结为摘要条目 | 仅裁剪旧的工具结果(tool results) |
| 持久化 | 摘要持久化写入会话 JSONL | 仅内存中按请求临时裁剪,不写回历史 |
| 触发 | 接近/超过上下文窗口时自动,或 /compact 手动 |
按请求进行,用于缓解工具输出堆积 |
简言之:压缩是"总结并落盘",修剪是"每请求临时裁剪掉旧工具输出"。关于修剪的完整机制,参见 docs/zh-CN/concepts/session-pruning.md。
另外要注意,大型工具输出本身通常已被截断(truncated),修剪可以进一步减少工具结果的堆积对上下文的占用;两者可以配合使用。
实战提示
- 主动压缩:当会话感觉过时、上下文臃肿(例如
\status显示 token 占用接近上限)时,直接执行/compact,可附带指令聚焦关键信息。 - 利用修剪:如果瓶颈来自大量工具输出,除压缩外还可依赖修剪在每请求层面削减旧工具结果。
- 全新开始:如果你需要彻底重来,
/new或/reset会启动一个新的会话 ID(注意:这与压缩不同,新会话不再携带任何旧上下文)。 - 观察压缩状态:在详细模式下留意
🧹 Auto-compaction complete,并通过/status的🧹 Compactions: <count>追踪压缩频率——若过于频繁,可适当调大keepRecentTokens、reserveTokensFloor或切换更大上下文窗口的模型。 - 长会话稳定性:开启
truncateAfterCompaction可防止长会话 JSONL 无限膨胀;若压缩经常失败,可结合/status与运行日志中的[compaction-diag]、[context-overflow-diag]诊断信息,按上文"跳过与失败原因"分类表定位问题(总结失败、provider 4xx/5xx、超时等)。
小结
OpenClaw 的压缩机制由"触发(自动/手动)→ 分块总结(含安全边际、自适应分块、渐进式降级)→ 持久化到会话 JSONL → 压缩后上下文注入与记忆索引同步"构成闭环:自动压缩在会话接近或溢出上下文窗口时兜底恢复,/compact 让用户在任何时候主动整理上下文,而 agents.defaults.compaction 提供了从模式、保留预算、标识符策略到记忆刷写、质量守护、模型覆盖的细粒度调优手段。理解了这些参数与源码实现,你就能针对自己的模型与工作负载,把长会话稳定地维持在上下文窗口之内。