6.4 压缩与裁剪：折叠与丢弃策略
本节把“上下文爆炸”拆成两类可配置机制：工具结果裁剪与会话压缩。前者由 agents.defaults.contextPruning 控制，目标是裁掉旧工具结果以降低模型输入体积；后者由 agents.defaults.compaction 控制，目标是在会话接近压缩阈值时生成摘要，并在必要时先刷新长期记忆。两者配合，才能在长会话中同时保证可用性与可回放性。
6.4.1 核心概念辨析：压缩 vs 裁剪
在处理上下文爆炸的问题上，新手很容易混淆 OpenClaw 设计上的这两套方案。它们的本质差异体现在“是否被持久化”与“生命周期触点”上：
上下文裁剪（Session Pruning，由
contextPruning控制）： 发生在 大语言模型调用前，系统为了降低单次请求负荷、减轻算力或缓存失效而“临时舍弃极度老旧的工具打印执行结果”。它 不会修改任何磁盘历史文件，只作用于内存数据结构上。会话压缩（Compaction，由
compaction控制）： 发生在 整个会话接近承载容积瓶颈上限前。把前面冗长繁杂的车轱辘话打散折叠成精华的概要点（摘要），并 回写保存并强制持久化到你的JSONL追踪日志中，属于物理折叠以使得新数据继续顺滑滚动。
官方相关参考资料解释：
工具结果裁剪：https://docs.openclaw.ai/gateway/configuration#agentsdefaultscontextpruning
压缩概念：https://docs.openclaw.ai/concepts/compaction
[!IMPORTANT] Session Pruning 目前 仅在
mode: "cache-ttl"且使用 Anthropic API 等特殊协议驱动时生效。而 Compaction 是每个模型都能通用受益的长效型独立安全控制阀门。两者虽然互助但互不依赖。
6.4.2 触发流程：先裁剪工具，再压缩会话
下面展示一个典型的触发顺序。
图 6-2：裁剪与压缩的典型触发顺序
6.4.3 工具结果裁剪：参数与内部机制
了解裁剪的完整参数有助于在生产环境中精细调优——比如调整保护多少条最近的助手回复、在什么体积阈值触发裁剪等。agents.defaults.contextPruning 的完整默认参数：
mode
"cache-ttl"
裁剪模式
ttlMs
300,000（5 分钟）
缓存 TTL
keepLastAssistants
3
保护最近 N 条助手回复不被裁剪
softTrimRatio
0.3
上下文达到 30% 时触发软裁剪
hardClearRatio
0.5
上下文达到 50% 时触发硬清除
softTrim.maxChars
4,000
仅裁剪超过此长度的工具结果
softTrim.headChars
1,500
软裁剪保留头部字符数
softTrim.tailChars
1,500
软裁剪保留尾部字符数
minPrunableToolChars
50,000
硬清除的最小工具结果大小
裁剪分两阶段执行：第一阶段（softTrim）把超长工具结果截为“头 1500 字符 + ... + 尾 1500 字符”；第二阶段（hardClear）用占位符 [Old tool result content cleared] 替换整个结果。
三个关键的安全约束（源码中的硬编码规则）：
图片保护：包含图片块的工具结果永远不会被裁剪，因为图片内容无法通过 head/tail 截取恢复。
引导消息保护：第一条用户消息之前的所有内容（SOUL.md、USER.md 等身份读取）不参与裁剪。
工具名过滤：通过
tools.deny/tools.allow的 glob 模式，可以指定哪些工具的结果不参与裁剪。
Token 估算：源码使用保守的 CHARS_PER_TOKEN_ESTIMATE = 4（4 字符 ≈ 1 token），图片按 IMAGE_CHAR_ESTIMATE = 8000 字符计入预算。这意味着一张图片约占 2000 token 的预算。
keepLastAssistants 的工作方式是从消息列表末尾向前扫描，找到第 N 条助手回复的位置作为“保护线”——保护线之后的所有消息都不会被裁剪。
验收点：
长会话输入体积稳定，成本与时延不随时间线性上升。
裁剪不会破坏关键证据段，回放一致性可接受。
6.4.4 压缩中的标识符保护与安全过滤
压缩（Compaction）的本质是让 LLM 对历史对话生成摘要。但 LLM 在总结时有一个危险倾向：悄悄篡改不透明标识符——把 UUID 缩短、把 API Key 部分省略、把 URL 参数丢弃。这在后续工具调用中会导致难以排查的幽灵错误。
源码（compaction.ts）中内建了 标识符保护指令（IDENTIFIER_PRESERVATION_INSTRUCTIONS），在每次压缩摘要请求中注入：
"Preserve all opaque identifiers exactly as written (no shortening or reconstruction), including UUIDs, hashes, IDs, tokens, API keys, hostnames, IPs, ports, URLs, and file names."
该指令有三种策略模式：“strict”（默认，始终注入）、“off”（不注入）、“custom”（使用自定义指令）。
分批摘要策略：当对话过长无法一次性摘要时，系统会通过 splitMessagesByTokenShare() 将消息按 token 占比均匀切分为 N 段（默认 2 段），对每段独立摘要后再合并。合并阶段有专门的指令要求保留活跃任务状态、批处理进度（如“5/17 已完成”）、用户最后的请求、决策理由和待办事项，且优先保留近期上下文。
工具结果安全过滤：在压缩前，stripToolResultDetails() 会剥离所有工具结果中的 details 字段。源码注释明确指出：\u201ctoolResult.details can contain untrusted/verbose payloads; never include in LLM-facing compaction.\u201d 这防止了不可信的工具输出（如 stderr、HTTP 头）进入摘要提示词，既节省 token 又避免潜在的提示注入。
超大消息降级：如果单条消息超过上下文窗口的 50%（isOversizedForSummary），会被排除在摘要之外并插入说明（如 [Large assistant (~45K tokens) omitted from summary]）。如果摘要整体失败，系统会逐级降级：先排除超大消息重试，最后回退到纯文本记录。
6.4.5 预压缩记忆刷新机制
OpenClaw 在执行压缩之前，会先尝试让智能体主动保存关键信息。当系统检测到上下文即将触达自动压缩软阈值（softThresholdTokens）时，会在正式压缩前插入一个静默智能体回合，让模型有机会将重要内容归档到持久存储。
这个预压缩流程分六步执行：
持续监控：实时追踪当前会话的 token 消耗量。
触发软警报：消耗超过
softThresholdTokens警戒线时启动预压缩流程。注入指令：向模型发送”上下文即将被压缩，请保存关键信息”的内部指令。
归档落盘：智能体执行记忆存储动作，将关键上下文写入持久文件（如
memory/YYYY-MM-DD.md）。静默确认：智能体回复
NO_REPLY特征字符串收尾，该回复不会显示给用户，整个过程对前端透明。正式压缩：记忆安全落盘后，系统再执行常规的压缩与折叠清理。
启用该特性非常简单：
注意：若全局安全设计把你的当前主目录权限掐断（设为只读如 workspaceAccess: "ro" ），这套智能的记忆刷新流程也会自动休眠跳过。
6.4.6 排障命令：先看状态，再看日志与裁剪事件
操作示例：先用状态命令确认系统是否处于可用状态，再用日志观察裁剪与压缩是否在高峰期被频繁触发。
操作示例：统计工具结果裁剪触发是否过于频繁。日志字段以实际实现为准。
最后更新于