OpenClaw 上下文窗口与压缩机制详解:自动压缩、/compact 命令与 agents.defaults.compaction 完整配置指南

原创2026-10-14 21:24:131,859 阅读
文章标签:人工智能大模型LLM 网关AI AgentAPI网关后端CLI浏览器控制插件系统MCP Clients即时通讯语音桌面应用

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 的完整处理逻辑:

  1. 授权校验:非授权发送者(非 owner/被授权者)发出的 /compact 会被直接忽略并记录日志。
  2. 会话校验:若缺少 sessionId,返回 ⚙️ Compaction unavailable (missing session id).。
  3. 中断进行中的运行:若该会话当前有正在执行的 Agent 运行(isEmbeddedPiRunActive),会先 abortEmbeddedPiRun 中止,并等待运行结束(最长 15 秒),避免压缩与运行写历史产生竞态。
  4. 提取指令:extractCompactInstructions 会剥离群组提及与结构化前缀,支持 /compact 后直接跟文本或 : 分隔的文本作为自定义总结指令。
  5. 执行压缩:调用 compactEmbeddedPiSession,trigger: "manual",senderIsOwner 等身份信息一并传入。
  6. 结果输出:压缩成功时输出 ⚙️ 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 采用三级策略:

  1. 先尝试对全部消息做完整总结;
  2. 若失败,剔除所有 oversized 消息,仅对剩余消息做部分总结,并在摘要末尾以 [Large <role> (~N K tokens omitted from summary)] 标注被省略的大消息;
  3. 若部分总结仍失败,最终兜底返回统计信息(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 提供了从模式、保留预算、标识符策略到记忆刷写、质量守护、模型覆盖的细粒度调优手段。理解了这些参数与源码实现,你就能针对自己的模型与工作负载,把长会话稳定地维持在上下文窗口之内。

登录后查看全文
openclaw-zero-token