OpenClaw 如何理解并调整会话压缩 Compaction让长对话不超上下文【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw每个模型都有上下文窗口context window即一次能处理的最大 token 数。长对话不断累积消息和工具输出迟早会撞上这个上限。OpenClaw 的解决办法是Compaction会话压缩把较早的对话轮次总结成一条摘要写回会话 transcript只保留近期消息原文让对话可以继续而不超出模型的上下文限制。这篇文章面向正在使用 OpenClaw 的开发者讲清楚三件事压缩实际做了什么、怎么确认它发生了、以及如何通过openclaw.json里的agents.defaults.compaction配置和/compact等命令调整它的行为。Compaction 到底做了什么按 Compaction 文档 的说明压缩分三步较早的对话轮次被总结成一条紧凑的摘要条目compactionentry持久化在 transcript 中记录firstKeptEntryId和tokensBefore摘要保存在 session transcript近期消息保持原样。几个关键事实直接影响你对压缩结果的预期完整历史仍在磁盘上。压缩只改变模型下一轮看到的内容不改写原始记录。工具调用成对保留选择切分点时OpenClaw 会把 assistant 的工具调用与对应的toolResult放在一起如果切分点落在工具块中间会移动边界而不是拆开配对。默认模式新配置的agents.defaults.compaction.mode默认为safeguard更严格的护栏 摘要质量审计想回到旧行为需显式设置mode: default。safeguard 质量审计保留的摘要正文必须包含要求的标题待处理的问题和精确标识符必须保留在将要写入的摘要文本中不合格时只做配置允许次数的纠正尝试若始终不通过压缩在写入前停止原始历史保留不变。内置 summarizer 只接收文本不接收图片像素被省略的图片会以[image data omitted from summary input]之类的标记表示不会谎称模型处理过这些数据。自动压缩默认开启。它的三条触发路径见 Session management deep dive溢出恢复模型返回 context-overflow 错误如request_too_large、context length exceeded、input is too long for the model、ollama error: context length exceeded等各 provider 变体时先压缩再重试。如果恢复仍失败OpenClaw 会保留当前会话映射并给出明确指引——重试消息、执行/compact或/new。基于用量的维护内置运行时在推理前检查投影用量达到模型窗口减去压缩保留量的阈值时先做 memory checkpointing再做压缩。会话内阈值维护default模式会话的实际上下文用量超过窗口减去保留量时触发safeguard模式禁用这条竞争路径把主动调度交给上面的维护路径。保留量reserve的规则80,000 token 及以上窗口默认保留 20,000 token更小的窗口至少保留四分之三容量给提示和对话reserve 为压缩摘要和 memory flush 等杂务留空间。文档给了一个 32,768-token 窗口的文档示例使用 8,192-token reserve 和 4,000-token 软边距约 20,576 投影 token 时开始提前 memory flush24,576 起触发阻塞式压缩。怎么确认压缩发生了压缩默认静默执行。确认它是否发生、发生了多少次有这几个观察面来自 Session management deep dive 的 User-visible surfaces聊天中发送/status会显示 Compactions: countCLIopenclaw status、openclaw sessions或openclaw sessions --jsonGateway 日志openclaw logs --follow中出现embedded run auto-compaction start和completeverbose 模式下看到 Auto-compaction complete。openclaw status openclaw sessions --agent main --json openclaw logs --follow注意 token usage 文档 的提醒/status里的上下文用量是运行时估计值计费统计与当前上下文窗口是分开维护的不要把contextTokens当作严格保证。手动触发压缩聊天内/compact在任意聊天中输入/compact强制压缩一次可以带指令引导摘要重点/compact Focus on the API design decisions手动压缩的切分预算同样由agents.defaults.compaction.keepRecentTokens默认 20,000 token决定该预算内的近期尾部会原样保留。两个容易踩的坑openclaw agent --message /compact ...不是压缩路径——CLI 传入的斜杠命令会被 authorized-sender 检查拒绝命令非零退出并指路到openclaw sessions compact。外部渠道上未被授权的发送者执行/compact会得到授权拒绝回复。CLIopenclaw sessions compact针对卡住或超大的会话Sessions CLI 文档 提供了一等封装要求 Gateway 正在运行openclaw sessions compact agent:main:main openclaw sessions compact agent:main:main --max-lines 200 openclaw sessions compact agent:work:main --agent work --json不带--max-lines时Gateway 用 LLM 总结 transcript走配置的压缩生命周期CLI 默认不设客户端超时。带--max-lines n是另一回事它把 SQLite transcript 永久截断到最后 n 行不生成备份归档。对卡死会话可用但属于不可逆操作先用/status和openclaw sessions确认会话 key 无误。Gateway 报告压缩失败或不可达时命令非零退出方便脚本判断。不带--max-lines的成功响应文档示例{ ok: true, key: agent:main:main, compacted: true, result: { tokensBefore: 243868, tokensAfter: 34941 } }其中tokensBefore/tokensAfter只是文档中的示例数值不要当成固定预期。调整压缩行为所有压缩配置位于~/.openclaw/openclaw.json的agents.defaults.compaction下。完整字段参考见 Agent heartbeat、compaction 与流式配置最常用的几个开关如下。换一个小模型专门做摘要压缩默认使用当前会话模型。用compaction.model可以指定另一个总结模型接受provider/model-id字符串或agents.defaults.models下配置的裸别名裸值同时匹配别名和字面模型 ID 时字面 ID 优先。适合主对话用大模型、摘要用本地小模型的场景{ agents: { defaults: { compaction: { model: ollama/llama3.1:8b } } } }未设置时压缩使用会话主模型若总结遇到可 fallback 的 provider 错误会沿会话既有的模型 fallback 链重试但这个选择是临时的不会写回会话状态。显式设置了compaction.model后则精确命中该模型不继承 fallback 链。保留更多近期上下文keepRecentTokens默认20000是原样保留的最近 transcript 尾部的切分预算recentTurnsPreserve默认3是 safeguard 总结之外原样保留的最近 user/assistant 轮数。压缩后觉得上下文变旧调大前者能让摘要覆盖得更靠后、原文留得更多。用字节阈值提前触发maxActiveTranscriptBytes用于长时会话模型上下文可能还健康但持久化的 transcript 历史一直在增长。设为正数字节数或20mb之类的字符串后transcript 窗口自最近一次压缩或 reset 以来的部分达到阈值就在一轮运行开始前触发常规语义压缩0或不设置则关闭。它不直接切字节而是让正常压缩管线生成摘要。{ agents: { defaults: { compaction: { maxActiveTranscriptBytes: 20mb } } } }工具循环中途的上下文压力midTurnPrecheck.enabled: true默认关闭加一道工具循环护栏每次工具结果追加后、下一次模型调用前用与轮次开始相同的预算逻辑估算提示压力。上下文放不下时它不会就地压缩而是发出结构化的 mid-turn 信号、停止当前提交让外层循环走既有恢复路径——够用的话截断超大工具结果否则触发配置的压缩模式并重试。default和safeguard模式都支持。让压缩可见、让 memory flush 走本地模型notifyUser: true默认 false会在压缩开始、完成、以及 memory flush 耗尽时发送简短状态消息如 Compacting context...。默认行为是静默的。压缩前 OpenClaw 会运行一个静默 memory flush 轮次把持久笔记写到磁盘如工作区的memory/YYYY-MM-DD.md防止压缩抹掉关键上下文。它由memoryFlush子块控制enabled默认 truesoftThresholdTokens默认 4000forceFlushTranscriptBytes默认2mb。如果这个杂务轮次想留在本地模型上单独指定模型即可{ agents: { defaults: { compaction: { memoryFlush: { model: ollama/qwen3:8b } } } } }该 override 不继承会话 fallback 链失败含重试耗尽不会重置会话或丢弃历史只是继续回复notifyUser开启时会给出降级提示。工作区为只读workspaceAccess: ro或none时 flush 会跳过。关掉自动压缩保留手动路径enabled: false禁用嵌入式运行时的阈值自动压缩和直接命令的 post-turn 维护但 overflow 恢复压缩和手动/compact仍然可用{ agents: { defaults: { compaction: { enabled: false } } } }压缩太频繁、或上下文变旧了怎么办Compaction 文档 的 Troubleshooting 一节给出了三个方向压缩太频繁多半是模型上下文窗口偏小或工具输出太大。可以启用 session pruning——它只裁剪旧工具结果不进摘要、不改写磁盘历史在两次压缩之间把工具输出控制住。开启方式{ agents: { defaults: { contextPruning: { mode: cache-ttl, ttl: 5m } } } }pruning 默认关闭它对toolResult消息生效超过 4,000 字符的结果软裁剪为保留首尾各 1,500 字符上下文占用仍高时再硬清空为占位符。压缩后上下文感觉变旧用/compact Focus on topic引导摘要侧重或保持 memory flush 开启让笔记存活。需要彻底重来/new直接开新会话不做压缩/new [model]还可以同时指定模型别名。deep dive 文档 的排查清单还补了两条判断Compaction spam检查模型上下文窗口太小会逼出频繁压缩和工具结果膨胀调 session pruning。小本地模型几乎每条提示都溢出确认 provider 报告的模型上下文窗口是否正确——OpenClaw 只有在窗口已知时才能限制有效 reserve。边界与限制压缩只改变模型下一轮看到的内容完整历史保留在磁盘可用openclaw sessions相关命令查看会话行与 transcript。keepRecentTokens与 reserve 是压缩管线的预算不是 provider 的 token 硬上限选更大的摘要模型也不会扩大前台模型的上下文窗口。maxActiveTranscriptBytes作用于活跃 SQLite transcript 历史旧版 JSONL checkpoint 工件不在其目标内。溢出恢复并非万能provider 表示单次请求本身超过其全部 token 上限时文档以 Groq 的 HTTP 413 为例压缩的摘要请求会被同一上限拒绝OpenClaw 会直接给出 reset 指引而不反复压缩重试。插件可通过registerCompactionProvider()注册自定义压缩 provider并在配置中设置compaction.provider设置 provider 会强制mode: safeguardprovider 失败或返回空时自动回退到内置 safeguard 摘要管线。验证是否配置生效的闭环是改完~/.openclaw/openclaw.json后继续跑一段长对话用/status看 Compactions: count是否增长、openclaw logs --follow里是否出现embedded run auto-compaction start/complete以及openclaw sessions --json中会话行的压缩计数是否更新。计数不变且日志无压缩记录说明要么阈值还没到要么enabled/mode与你预期的路径不一致再对照上面的触发路径逐项核对。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OpenClaw 如何理解并调整会话压缩 Compaction让长对话不超上下文【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw每个模型都有上下文窗口context window即一次能处理的最大 token 数。长对话不断累积消息和工具输出迟早会撞上这个上限。OpenClaw 的解决办法是Compaction会话压缩把较早的对话轮次总结成一条摘要写回会话 transcript只保留近期消息原文让对话可以继续而不超出模型的上下文限制。这篇文章面向正在使用 OpenClaw 的开发者讲清楚三件事压缩实际做了什么、怎么确认它发生了、以及如何通过openclaw.json里的agents.defaults.compaction配置和/compact等命令调整它的行为。Compaction 到底做了什么按 Compaction 文档 的说明压缩分三步较早的对话轮次被总结成一条紧凑的摘要条目compactionentry持久化在 transcript 中记录firstKeptEntryId和tokensBefore摘要保存在 session transcript近期消息保持原样。几个关键事实直接影响你对压缩结果的预期完整历史仍在磁盘上。压缩只改变模型下一轮看到的内容不改写原始记录。工具调用成对保留选择切分点时OpenClaw 会把 assistant 的工具调用与对应的toolResult放在一起如果切分点落在工具块中间会移动边界而不是拆开配对。默认模式新配置的agents.defaults.compaction.mode默认为safeguard更严格的护栏 摘要质量审计想回到旧行为需显式设置mode: default。safeguard 质量审计保留的摘要正文必须包含要求的标题待处理的问题和精确标识符必须保留在将要写入的摘要文本中不合格时只做配置允许次数的纠正尝试若始终不通过压缩在写入前停止原始历史保留不变。内置 summarizer 只接收文本不接收图片像素被省略的图片会以[image data omitted from summary input]之类的标记表示不会谎称模型处理过这些数据。自动压缩默认开启。它的三条触发路径见 Session management deep dive溢出恢复模型返回 context-overflow 错误如request_too_large、context length exceeded、input is too long for the model、ollama error: context length exceeded等各 provider 变体时先压缩再重试。如果恢复仍失败OpenClaw 会保留当前会话映射并给出明确指引——重试消息、执行/compact或/new。基于用量的维护内置运行时在推理前检查投影用量达到模型窗口减去压缩保留量的阈值时先做 memory checkpointing再做压缩。会话内阈值维护default模式会话的实际上下文用量超过窗口减去保留量时触发safeguard模式禁用这条竞争路径把主动调度交给上面的维护路径。保留量reserve的规则80,000 token 及以上窗口默认保留 20,000 token更小的窗口至少保留四分之三容量给提示和对话reserve 为压缩摘要和 memory flush 等杂务留空间。文档给了一个 32,768-token 窗口的文档示例使用 8,192-token reserve 和 4,000-token 软边距约 20,576 投影 token 时开始提前 memory flush24,576 起触发阻塞式压缩。怎么确认压缩发生了压缩默认静默执行。确认它是否发生、发生了多少次有这几个观察面来自 Session management deep dive 的 User-visible surfaces聊天中发送/status会显示 Compactions: countCLIopenclaw status、openclaw sessions或openclaw sessions --jsonGateway 日志openclaw logs --follow中出现embedded run auto-compaction start和completeverbose 模式下看到 Auto-compaction complete。openclaw status openclaw sessions --agent main --json openclaw logs --follow注意 token usage 文档 的提醒/status里的上下文用量是运行时估计值计费统计与当前上下文窗口是分开维护的不要把contextTokens当作严格保证。手动触发压缩聊天内/compact在任意聊天中输入/compact强制压缩一次可以带指令引导摘要重点/compact Focus on the API design decisions手动压缩的切分预算同样由agents.defaults.compaction.keepRecentTokens默认 20,000 token决定该预算内的近期尾部会原样保留。两个容易踩的坑openclaw agent --message /compact ...不是压缩路径——CLI 传入的斜杠命令会被 authorized-sender 检查拒绝命令非零退出并指路到openclaw sessions compact。外部渠道上未被授权的发送者执行/compact会得到授权拒绝回复。CLIopenclaw sessions compact针对卡住或超大的会话Sessions CLI 文档 提供了一等封装要求 Gateway 正在运行openclaw sessions compact agent:main:main openclaw sessions compact agent:main:main --max-lines 200 openclaw sessions compact agent:work:main --agent work --json不带--max-lines时Gateway 用 LLM 总结 transcript走配置的压缩生命周期CLI 默认不设客户端超时。带--max-lines n是另一回事它把 SQLite transcript 永久截断到最后 n 行不生成备份归档。对卡死会话可用但属于不可逆操作先用/status和openclaw sessions确认会话 key 无误。Gateway 报告压缩失败或不可达时命令非零退出方便脚本判断。不带--max-lines的成功响应文档示例{ ok: true, key: agent:main:main, compacted: true, result: { tokensBefore: 243868, tokensAfter: 34941 } }其中tokensBefore/tokensAfter只是文档中的示例数值不要当成固定预期。调整压缩行为所有压缩配置位于~/.openclaw/openclaw.json的agents.defaults.compaction下。完整字段参考见 Agent heartbeat、compaction 与流式配置最常用的几个开关如下。换一个小模型专门做摘要压缩默认使用当前会话模型。用compaction.model可以指定另一个总结模型接受provider/model-id字符串或agents.defaults.models下配置的裸别名裸值同时匹配别名和字面模型 ID 时字面 ID 优先。适合主对话用大模型、摘要用本地小模型的场景{ agents: { defaults: { compaction: { model: ollama/llama3.1:8b } } } }未设置时压缩使用会话主模型若总结遇到可 fallback 的 provider 错误会沿会话既有的模型 fallback 链重试但这个选择是临时的不会写回会话状态。显式设置了compaction.model后则精确命中该模型不继承 fallback 链。保留更多近期上下文keepRecentTokens默认20000是原样保留的最近 transcript 尾部的切分预算recentTurnsPreserve默认3是 safeguard 总结之外原样保留的最近 user/assistant 轮数。压缩后觉得上下文变旧调大前者能让摘要覆盖得更靠后、原文留得更多。用字节阈值提前触发maxActiveTranscriptBytes用于长时会话模型上下文可能还健康但持久化的 transcript 历史一直在增长。设为正数字节数或20mb之类的字符串后transcript 窗口自最近一次压缩或 reset 以来的部分达到阈值就在一轮运行开始前触发常规语义压缩0或不设置则关闭。它不直接切字节而是让正常压缩管线生成摘要。{ agents: { defaults: { compaction: { maxActiveTranscriptBytes: 20mb } } } }工具循环中途的上下文压力midTurnPrecheck.enabled: true默认关闭加一道工具循环护栏每次工具结果追加后、下一次模型调用前用与轮次开始相同的预算逻辑估算提示压力。上下文放不下时它不会就地压缩而是发出结构化的 mid-turn 信号、停止当前提交让外层循环走既有恢复路径——够用的话截断超大工具结果否则触发配置的压缩模式并重试。default和safeguard模式都支持。让压缩可见、让 memory flush 走本地模型notifyUser: true默认 false会在压缩开始、完成、以及 memory flush 耗尽时发送简短状态消息如 Compacting context...。默认行为是静默的。压缩前 OpenClaw 会运行一个静默 memory flush 轮次把持久笔记写到磁盘如工作区的memory/YYYY-MM-DD.md防止压缩抹掉关键上下文。它由memoryFlush子块控制enabled默认 truesoftThresholdTokens默认 4000forceFlushTranscriptBytes默认2mb。如果这个杂务轮次想留在本地模型上单独指定模型即可{ agents: { defaults: { compaction: { memoryFlush: { model: ollama/qwen3:8b } } } } }该 override 不继承会话 fallback 链失败含重试耗尽不会重置会话或丢弃历史只是继续回复notifyUser开启时会给出降级提示。工作区为只读workspaceAccess: ro或none时 flush 会跳过。关掉自动压缩保留手动路径enabled: false禁用嵌入式运行时的阈值自动压缩和直接命令的 post-turn 维护但 overflow 恢复压缩和手动/compact仍然可用{ agents: { defaults: { compaction: { enabled: false } } } }压缩太频繁、或上下文变旧了怎么办Compaction 文档 的 Troubleshooting 一节给出了三个方向压缩太频繁多半是模型上下文窗口偏小或工具输出太大。可以启用 session pruning——它只裁剪旧工具结果不进摘要、不改写磁盘历史在两次压缩之间把工具输出控制住。开启方式{ agents: { defaults: { contextPruning: { mode: cache-ttl, ttl: 5m } } } }pruning 默认关闭它对toolResult消息生效超过 4,000 字符的结果软裁剪为保留首尾各 1,500 字符上下文占用仍高时再硬清空为占位符。压缩后上下文感觉变旧用/compact Focus on topic引导摘要侧重或保持 memory flush 开启让笔记存活。需要彻底重来/new直接开新会话不做压缩/new [model]还可以同时指定模型别名。deep dive 文档 的排查清单还补了两条判断Compaction spam检查模型上下文窗口太小会逼出频繁压缩和工具结果膨胀调 session pruning。小本地模型几乎每条提示都溢出确认 provider 报告的模型上下文窗口是否正确——OpenClaw 只有在窗口已知时才能限制有效 reserve。边界与限制压缩只改变模型下一轮看到的内容完整历史保留在磁盘可用openclaw sessions相关命令查看会话行与 transcript。keepRecentTokens与 reserve 是压缩管线的预算不是 provider 的 token 硬上限选更大的摘要模型也不会扩大前台模型的上下文窗口。maxActiveTranscriptBytes作用于活跃 SQLite transcript 历史旧版 JSONL checkpoint 工件不在其目标内。溢出恢复并非万能provider 表示单次请求本身超过其全部 token 上限时文档以 Groq 的 HTTP 413 为例压缩的摘要请求会被同一上限拒绝OpenClaw 会直接给出 reset 指引而不反复压缩重试。插件可通过registerCompactionProvider()注册自定义压缩 provider并在配置中设置compaction.provider设置 provider 会强制mode: safeguardprovider 失败或返回空时自动回退到内置 safeguard 摘要管线。验证是否配置生效的闭环是改完~/.openclaw/openclaw.json后继续跑一段长对话用/status看 Compactions: count是否增长、openclaw logs --follow里是否出现embedded run auto-compaction start/complete以及openclaw sessions --json中会话行的压缩计数是否更新。计数不变且日志无压缩记录说明要么阈值还没到要么enabled/mode与你预期的路径不一致再对照上面的触发路径逐项核对。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
