thClaws如何压缩超长对话？Compaction上下文管理机制全解析

【免费下载链接】thClawsOpen-source AI agent harness in native Rust — GUI, CLI, headless, and webapp from one binary. Multi-provider, MCP, skills, plugins, agent teams.项目地址https://gitcode.com/gh_mirrors/th/thClaws点击查看免费下载thClaws 是一款用 Rust 编写的开源 AI agent 框架支持 GUI、CLI、headless 与 Webapp 多种运行形态。面对越来越长的对话thClaws 内置的Compaction上下文压缩机制会在每一轮自动估算 token 占用、裁剪超预算的历史消息甚至调用 LLM 生成摘要来瘦身对话让超长会话永远不会撑爆模型上下文窗口。这篇文章带你完整看懂这套机制的 5 个入口、预算算法和持久化策略。为什么 AI Agent 必须有上下文压缩大模型都有固定的上下文窗口context window比如 128K token。一次请求里要装下的不只是聊天记录还包括系统提示词、工具定义、历史消息。当 agent 长时间运行——读文件、跑命令、调工具——历史消息会迅速膨胀最终触发服务商的400 context length exceeded错误。thClaws 的解法是在每一轮turn发出请求之前先做一次预算核算超了就自动压缩。整个过程对用户完全透明无需任何配置见 ch07-sessions.md 的 Compaction 小节。每轮的预算是怎么算出来的在 agent.rs 的run_turn_multipart中真正的消息预算是扣扣扣出来的消息预算 模型上下文窗口 − 系统提示词 token − 工具定义预留1024 token模型上下文窗口来自项目/用户配置的modelOverrides否则查模型目录查不到则回退到 128K 的默认值。系统提示词扣除CLAUDE.md/AGENTS.md 级联、记忆、技能清单都可能让系统提示词高达数万 token。早期版本没算这笔账导致消息看似装得下、整包请求却溢出。1 KiB 工具定义预留内置 30~40 个工具加 MCP 工具的 JSON Schema 也要占窗口预留一块粗粒度余量最省事。token 估算本身很轻量tokens.rs 用字符数 ÷ 2.8 向上取整的启发式不求精确、只求保守。5 个压缩入口一览压缩逻辑集中在 compaction.rs官方技术手册的汇总见 thclaws-technical-manual/compaction.md。入口触发时机策略compact每轮自动执行预算内则直接跳过丢最旧消息保住工具调用配对必要时原地截断compact_with_summary用户输入/compact调 LLM 把旧消息总结成一段摘要最近 4 条原样保留compact_for_step_boundaryPlan 模式跨步骤时默认结构性瘦身普通工具结果换成占位符计划工具结果保留clear_for_step_boundaryPlan 模式planContextStrategy clear除第一条用户消息外清空全部历史truncate_oversized_messagecompact内部的兜底救援单条消息超预算时按字符边界原地截断并追加提示自动压缩drop-oldest 的两条铁律每轮执行的compact()是同步、零 API 开销的丢弃最旧策略但有两条不变式绝不拆散工具配对ToolUse工具调用必须和它的ToolResult工具结果成对出现所有服务商的线上格式都强制这一对。丢弃最旧消息时如果会留下孤儿结果结果消息会被一并丢掉。至少保留一条 截断救援丢弃循环保证至少留最后一条消息。如果这一条本身就超出预算比如粘贴了一个巨大文件truncate_oversized_message会在 UTF-8 字符边界处原地截断每个 Text / ToolResult 块并追加一行模型能读懂的提示[...truncated by thClaws: original content exceeded the N token context budget]模型看到这个提示后可以主动换一种更窄的读取策略。修复前这种单条超大消息会原样发出去换来一个 HTTP 400。预算内时compact()是纯 no-op不写任何东西所以日常对话不会有任何额外成本。手动压缩/compact一键生成 LLM 摘要自动压缩是粗暴裁剪而/compact是智能压缩。在 CLI 或 GUI 输入框中输入/compact流程是源码见 compaction.rs把历史在倒数第 4 条处切开——最近 4 条消息原样保留最近一轮往往含有模型下一轮还要引用的工具调用 ID总结会丢失结构化信息把更早的消息渲染成转录文本工具调用渲染成[Called tool: …]工具结果只保留 500 字符预览用独立的摘要提示词调当前 provider系统提示见 compaction_system.md指令见 compaction.md——简明总结保留关键事实、决策和工具结果摘要被包成一条合成用户消息[Conversation summary — earlier messages were compacted]插到保留消息之前。失败自动降级摘要调用报错或返回空时自动退回 drop-oldest 策略并提示compaction failed, dropped oldest instead——压缩永远不会把会话搞坏。Plan 模式步骤边界处的换血Plan 模式Ralph 驱动会把长任务切成多个步骤跨步骤的瞬间就是天然的瘦身时机。此时只压缩边界之前的历史默认策略compact保留计划工具SubmitPlan/UpdatePlanStep等的结果——它们是模型判断哪些步骤已完成的面包屑其余普通工具结果比如 50KB 的 Read 输出替换为[ToolResult elided by step-boundary compaction]占位符。激进策略clear除了第一条用户消息历史全部清空。适合 20 步、步骤彼此独立的超长计划通过.thclaws/settings.json中planContextStrategy配置。由于历史在每个步骤边界都会被压缩Plan 模式还设计了显式的output字段让步骤之间通过它传递路径、端口号等关键信息而不是依赖聊天记录。详见 ch18-plan-mode.md 的 Step-boundary compaction 小节。压缩结果如何持久化/compact和步骤边界压缩都会把压缩后的消息列表写成一条compaction检查点事件追加到会话 JSONL 文件session.rs 的append_compaction_to{type:compaction,messages:[...],replaces_count:42,timestamp:1777752000}下次/load恢复会话时load_from走到这条事件会清空并重置消息列表为压缩后的视图——你看到的是瘦身后的历史而不是原始记录。而被替换掉的原始消息事件永远留在磁盘上审计痕迹需要时cat session.jsonl即可看到完整原貌。每轮 no-op 的compact()不写检查点太吵只有真正发生裁剪的路径才落盘。与 Prompt Cache 的联动/compact 为什么贵两次服务商的提示词缓存以字节级前缀不变为前提。compact_with_summary改写了消息列表会打断缓存断点——/compact一次要付两笔钱摘要调用本身 下一轮重新写缓存的溢价详见 thclaws-technical-manual/prompt-cache.md 第 8 节。所以官方建议有意识地用/compact而不是反射性地用。而每轮自动compact()在预算内不动消息列表完全不破坏缓存。如何观察和控制压缩行为Hooks 审计当且仅当本轮真的发生裁剪时pre_tokens messages_budget会触发pre_compact/post_compact两个钩子环境变量THCLAWS_COMPACT_MESSAGES和THCLAWS_COMPACT_TOKENS分别提供压缩前后的消息数和 token 数可写入审计日志。配置示例见 ch13-hooks.md。上下文警告横幅当会话 JSONL 文件大到压缩已跟不上如数十 MB时GUI 会在右上角弹出警告推荐Fork with summary——用 LLM 摘要为新会话播种开启一个记得你在哪的干净上下文。对应组件见 ContextWarningBanner.tsx。总结三句话看懂 thClaws Compaction每轮自动先扣系统提示词和工具定义再算预算超了就丢最旧、保工具配对、兜底截断全程零 API 开销按需智能/compact用 LLM 把旧历史总结成一段摘要最近 4 条原样保留失败自动降级可追溯压缩检查点写入会话 JSONL恢复时看到瘦身视图磁盘上始终留有完整审计痕迹。理解了这套机制你就不会再担心 thClaws 跑长任务时突然失忆或报错 400——它只是安静地把历史瘦身了一版。赞分享【免费下载链接】thClawsOpen-source AI agent harness in native Rust — GUI, CLI, headless, and webapp from one binary. Multi-provider, MCP, skills, plugins, agent teams.项目地址https://gitcode.com/gh_mirrors/th/thClaws点击查看免费下载相关推荐OpenClaw 如何理解并调整会话压缩 Compaction让长对话不超上下文OpenClaw 如何理解并调整会话压缩 Compaction让长对话不超上下文 每个模型都有上下文窗口context window即一次能处理的最大AI 应用AI Agent交互助手后端即时通讯网关ok-ww 鸣潮后台自动战斗指南一键日常声骸刷取简单教程实现后台挂机ok ww 鸣潮后台自动战斗指南一键日常声骸刷取简单教程实现后台挂机 ok wwok wuthering waves是一个基于图像识别的开源鸣潮自动化GUI 自动化计算机视觉RPA人工智能OpenClaw 上下文压缩Compaction机制深度解析让长会话始终控制在模型上下文窗口之内OpenClaw 上下文压缩Compaction机制深度解析让长会话始终控制在模型上下文窗口之内 每个模型都有上下文窗口能看到的最大 token 数人工智能大模型LLM 网关AI Agent即时通讯创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考