OpenClaw无损上下文管理插件：基于DAG摘要系统解决长对话记忆难题

1. 项目概述：一个为OpenClaw量身定制的无损上下文管理插件

如果你正在使用OpenClaw构建或运行复杂的AI智能体，那么“上下文窗口溢出”这个问题，你一定不陌生。当对话历史越来越长，超过了AI模型（比如GPT-4、Claude等）能处理的token上限时，系统就不得不做出一个痛苦的选择：丢弃掉一部分历史消息。这就像一本小说的中间章节被撕掉了，智能体瞬间“失忆”，无法连贯地理解整个任务脉络，导致后续的对话质量断崖式下跌。

我最近在生产环境中深度使用并维护了一个名为lossless-claw-enhanced的OpenClaw插件，它彻底解决了这个问题。这个项目是原版lossless-claw的一个增强分支，核心使命就一个：在有限的模型上下文窗口内，无损地管理无限增长的对话历史。它不是简单地丢弃旧消息，而是通过一套基于有向无环图（DAG）的智能摘要系统，将海量历史压缩成精炼的摘要，同时保留随时回溯到原始细节的能力。简单说，它让你的智能体拥有了一个“永远不会满的、且自带目录和全文检索功能的外接大脑”。

我之所以特别关注这个增强版分支，是因为它修复了原版在处理中文、日文、韩文（CJK）文本时一个非常严重的Bug——token估算严重偏低，这直接导致上下文管理在CJK场景下几乎失效。同时，它还精选合并了上游几个关键的生产环境稳定性修复。经过我的实测和代码审查，这个版本在中文内容处理和长期运行可靠性上，已经达到了生产可用的水准。接下来，我将为你彻底拆解它的工作原理、配置要点以及我在部署和调试中积累的一手经验。

2. 核心原理：DAG摘要系统如何实现“无损压缩”

要理解这个插件的价值，我们得先看看OpenClaw默认是怎么处理长上下文的。通常，它采用一种叫“滑动窗口”的策略：只保留最近N条消息，更早的直接丢弃。这种方法简单粗暴，代价就是历史信息的永久丢失。对于需要长期记忆、多轮复杂协作的智能体来说，这是不可接受的。

而lossless-claw-enhanced引入的LCM（Lossless Context Management）机制，则是一种降维打击式的解决方案。它的核心思想不是“丢弃”，而是“提炼”和“重组”。整个过程可以类比为图书馆管理海量书籍：

1. 原始信息入库（持久化存储）：插件首先会将对话中的每一条消息，无论新旧，都完整地存入一个SQLite数据库。这就好比图书馆收进了每一本原始的书稿。

2. 初级摘要生成（分块压缩）：当对话长度触及预设的阈值（比如用满了模型上下文窗口的75%），插件就会启动“压缩”流程。它会将较早的一批消息（除了受保护的最近若干条“新鲜”消息）作为一个“块”，发送给一个你指定的、通常更廉价快速的LLM（例如Claude Haiku），让它生成一段浓缩摘要。这个摘要，就是第一层级的“图书摘要卡片”。

3. 摘要的再摘要（构建知识图谱/DAG）：随着对话继续进行，会产生越来越多的初级摘要。当这些摘要积累到一定数量，插件会再次将它们作为“源材料”，让LLM生成更高级别、更概括的二级摘要。这个过程可以递归进行，最终形成一个树状或图状的结构，也就是有向无环图（DAG）。顶层摘要可能只有几句话，却概括了几个小时的对话精髓。这就像图书馆的目录体系：章节摘要 -> 书籍摘要 -> 丛书概览。

4. 智能上下文组装（按需提取）：当智能体需要回复时，插件会动态组装上下文。它会将受保护的“新鲜”原始消息（确保最新细节不丢失），与相关路径上的各级摘要组合起来，拼接成一段不超过模型token限制的、连贯的历史叙述。这相当于你要研究一个主题，图书管理员不是把几百本书都堆给你，而是根据你的问题，递给你一份综合了丛书概览、相关书籍摘要和最关键原始章节的定制化资料包。

5. 无损回溯能力（工具支持）：这是“无损”的关键。所有原始消息都安然躺在数据库里。插件还提供了lcm_grep、lcm_describe、lcm_expand等工具，智能体可以在对话中直接使用这些工具，对摘要进行全文检索，或者将任何一级摘要“展开”，回溯到构成它的原始消息。这就好比你看完摘要后，可以随时根据卡片编号，去仓库里调出对应的原始书稿进行精读。

为什么DAG结构优于简单链表？传统的线性摘要链，一旦中间某个摘要丢失或失真，其后的所有历史都会受损。而DAG结构允许多个父节点和子节点，提供了更强的鲁棒性和更灵活的信息组织方式。例如，关于“项目架构”和“API设计”的讨论可能最终被汇总到一个“技术方案”的高级摘要下，这种非线性的归纳更符合人类知识的组织方式。

实操心得：模型选择的经济账摘要生成是个高频、重复性的任务。用GPT-4o这种顶级模型来做，效果当然好，但成本会高得离谱。我的经验是，像Anthropic Claude Haiku或OpenAI GPT-4o-mini这类“快而省”的模型，是这项工作性价比最高的选择。它们的总结和归纳能力对于压缩文本信息已经绰绰有余，能节省95%以上的成本，且速度极快，几乎不影响对话的流畅性。在插件配置中，务必为摘要任务单独指定一个这样的经济型模型。

3. 关键增强解析：修复CJK Token估算与生产环境Bug

原版lossless-claw在设计时，对非拉丁文本（特别是CJK）的考虑不足，这导致了在中文等环境下的严重问题。lossless-claw-enhanced分支的核心贡献就在于精准地修复了这些痛点。

3.1 CJK Token估算Bug：为什么原版在中文下会“失控”

这是最核心的一个修复。原版插件估算文本token数的逻辑极其简单：Math.ceil(text.length / 4)。这个公式基于一个假设：平均4个英文字符对应1个token。这在纯英文环境下是近似合理的。

然而，对于中文、日文、韩文（CJK）字符，现代主流的分词器（如OpenAI的cl100k_base、o200k_base）的处理方式完全不同。一个CJK字符通常被编码为1到2个token，平均约1.5个。原版的公式（1个字符算0.25个token）严重低估了CJK文本的实际token消耗，低估幅度高达2到6倍。

这个Bug带来的连锁反应是灾难性的：

1. 上下文窗口溢出：插件认为对话还没达到压缩阈值，但实际上token早已爆窗。导致AI模型接收到的上下文被意外截断，智能体表现失常。
2. 预算分配全盘错误：用于组装上下文的token预算、摘要生成的目标大小，全部基于错误的token数计算，导致摘要要么过短丢失信息，要么过长浪费资源。
3. 大文件处理失效：基于token大小的文件拦截机制会失灵，本应被处理的CJK大文件可能被错误放行。

增强版的解决方案：项目在src/estimate-tokens.ts中实现了一个共享的、语言感知的token估算器。它不再一刀切，而是区分对待：

举例说明： 假设一句中文：“这个项目的架构设计非常优秀”（14个CJK字符）。

• 原版错误估算：Math.ceil(14 / 4) = 4 tokens
• 增强版估算：Math.ceil(14 * 1.5) = 21 tokens
• 实际值 (cl100k_base分词器)：约19 tokens

可以看到，增强版的估算值已经非常接近真实情况，从根本上杜绝了因误算导致的管理失效。

注意事项：数据库迁移插件在升级时，会执行一次幂等的数据迁移，自动为数据库中已有的、包含CJK字符的消息和摘要重新计算正确的token_count值。纯英文的历史记录则不会被触动。这意味着你可以平滑升级，历史对话的上下文管理会立即变得更准确。这是增强版一个非常贴心的设计。

3.2 精选的上游关键修复

除了CJK问题，该分支还精心挑选并合并了上游仓库中几个对生产稳定性至关重要的修复：

这些修复看似细微，但每一个都对应着智能体在长期运行中可能突然“僵死”或“失忆”的致命场景。增强版分支将这些修复一并纳入，显著提升了插件的健壮性。

4. 完整安装与配置指南

理论讲完了，我们来看看怎么把它用起来。我的部署环境是基于Docker的OpenClaw，但步骤是通用的。

4.1 安装插件

首先，我们需要获取插件代码。推荐使用--link模式安装，这样方便后续拉取更新。

# 1. 克隆增强版仓库 git clone https://github.com/win4r/lossless-claw-enhanced.git cd lossless-claw-enhanced # 2. 安装插件依赖 (--link模式必需步骤) npm install # 3. 以链接模式安装到OpenClaw openclaw plugins install --link .

--link模式相当于创建了一个软链接，OpenClaw会直接运行你当前目录的代码。这意味着你后续通过git pull更新代码后，只需重启网关即可生效，无需重新安装。

如果你希望一个固定的版本，可以使用拷贝安装：

openclaw plugins install ./lossless-claw-enhanced

4.2 配置OpenClaw网关

安装后，需要修改OpenClaw的配置文件（通常是~/.openclaw/config.json或config/production.json），告诉它使用LCM作为上下文引擎。

{ "plugins": { "slots": { // 关键：将contextEngine槽位指向我们的插件 "contextEngine": "lossless-claw" }, "entries": { "lossless-claw": { "enabled": true, "config": { // 保留最近多少条原始消息不被压缩？根据模型窗口调整。 "freshTailCount": 32, // 上下文使用率达到多少时触发压缩？0.75即75%。 "contextThreshold": 0.75, // 压缩深度。-1表示无限递归，直到无法再压缩。 "incrementalMaxDepth": -1, // 忽略哪些会话模式？例如定时任务或子智能体会话。 "ignoreSessionPatterns": [ "agent:*:cron:**", "agent:*:subagent:**" ], // 指定用于摘要生成的模型，格式为“提供商/模型” "summaryModel": "anthropic/claude-haiku-4-5" } } } } }

配置参数详解：

• freshTailCount: 这是你的“短期记忆缓冲区”。保留最新的N条原始消息，确保智能体对刚刚发生的事拥有最精确的记忆。设置太小可能丢失细节，太大则压缩不积极。对于支持128K上下文的模型，32-64是个不错的起点。
• contextThreshold: 压缩触发的灵敏度。0.75意味着当估算的对话token数达到模型窗口上限的75%时，就开始压缩更早的消息。设置越高，压缩越不频繁，但溢出风险增加。
• incrementalMaxDepth: 控制摘要的“层级”。-1允许无限递归摘要，适合极长的对话。0或1可以限制摘要层级，让结构更扁平。
• ignoreSessionPatterns: 非常重要！有些会话（如定时触发的Cron任务、内部调用的子智能体）可能不需要或不适合上下文压缩。用通配符模式忽略它们，可以提升性能和避免干扰。
• summaryModel:强烈建议明确设置。使用一个快速、廉价的模型，如anthropic/claude-haiku-4-5、openai/gpt-4o-mini或google/gemini-2.0-flash。

4.3 重启与验证

配置完成后，重启OpenClaw网关使配置生效。

openclaw gateway restart

如何验证插件是否正常工作？你可以查看网关日志，通常会有[LCM]开头的日志行，提示数据库初始化、压缩触发等信息。更直接的方法是，开始一个长对话，观察当消息变多时，响应是否依然流畅，并通过lcm_describe工具询问智能体当前的上下文结构。

4.4 后续更新

如果你使用--link模式安装，更新非常简单：

# 进入插件目录 cd /path/to/lossless-claw-enhanced # 拉取最新代码 git pull origin main # 重启网关 openclaw gateway restart

5. 高级配置与环境变量详解

除了在JSON配置文件中设置，插件还支持通过环境变量进行配置，环境变量的优先级更高。这对于Docker部署或平台即服务（PaaS）环境特别有用。

5.1 核心环境变量列表

下表列出了所有关键的环境变量及其作用：

5.2 摘要模型配置的优先级与选择

插件选择摘要模型的逻辑有一个清晰的优先级链：

1. 最高优先级：环境变量LCM_SUMMARY_MODEL。
2. 次优先级：插件JSON配置中的summaryModel字段。
3. 回退1：OpenClaw网关配置中agents.defaults.compaction.model。
4. 最终回退：使用当前对话智能体自身的主模型（最不推荐，可能又贵又慢）。

模型选择策略：再次强调，摘要任务不需要复杂的推理、创造或代码生成能力。它需要的是：

• 速度快：不影响主对话响应延迟。
• 成本低：摘要生成量可能很大。
• 归纳能力强：能准确抓住一段文本的主旨和关键事实。

根据我的实测，以下模型是绝佳选择：

• Anthropic Claude 3.5 Haiku：速度快，成本极低，摘要质量可靠。
• OpenAI GPT-4o-mini：性价比之王，速度和质量平衡得很好。
• Google Gemini 2.0 Flash：同样快速且便宜。

绝对要避免使用 Claude Opus、GPT-4o、DeepSeek-V3等大型模型做摘要，那纯粹是浪费资源。

避坑指南：模型ID的“坑”配置summaryModel时，填写的provider/model字符串必须与你在OpenClaw中配置的模型目录（Model Catalog）里的ID完全一致。OpenClaw允许你为同一个模型起别名。例如，你在配置里可能将openai/gpt-4o-mini简写为gpt-mini。此时，你必须使用gpt-mini，而不是原始ID。最稳妥的方法是运行openclaw agents list命令，查看你网关里注册的模型列表，使用那里显示的ID。

6. 生产环境部署与调试心得

将lossless-claw-enhanced用于生产环境，除了正确配置，还有一些“只有踩过坑才知道”的经验。

6.1 数据库性能与维护

插件使用SQLite作为存储后端，轻便但在大规模使用下仍需注意。

• 路径规划：通过LCM_DATABASE_PATH将数据库文件放在高性能、高可靠性的存储上。如果是Docker部署，务必挂载持久化卷。
• 定期清理（可选）：虽然插件设计为无损存储，但如果你有严格的隐私或存储空间要求，可以考虑定期归档或清理非常旧的、标记为完成的会话。这需要你自行编写维护脚本，因为插件本身不提供自动清理功能。
• 监控大小：定期检查lcm.db文件大小。一个活跃的智能体，其数据库每月增长几百MB是正常的。

6.2 监控与日志分析

健康的LCM插件运行，日志是相对安静的，只有在触发压缩时才会有信息输出。

你需要关注的日志模式：

• [LCM] Compaction triggered for session ...：正常，压缩被触发。
• [LCM] Summarizing chunk of X messages (Y tokens)...：正常，正在生成摘要。
• [LCM] Context assembled (Z tokens)：正常，上下文已组装。

需要警惕的日志或现象：

• 长时间没有压缩日志：在长对话中，这可能意味着contextThreshold设置过高，或者CJK token估算在修复前仍有问题（增强版已修复）。检查对话是否已明显变慢或AI开始“胡言乱语”，这可能是上下文已溢出。
• 频繁的压缩日志：说明freshTailCount可能设置过小，或者对话信息密度极高。频繁压缩会增加LLM API调用成本和延迟。可以考虑适当增加freshTailCount或contextThreshold。
• 错误信息：如数据库连接错误、模型调用失败等。需要根据错误信息具体排查。

6.3 与智能体技能的配合

LCM插件提供的lcm_grep,lcm_describe,lcm_expand是强大的工具。你应该在你的智能体技能（Skills）或系统提示词（System Prompt）中，教会智能体在以下场景主动使用它们：

• 当用户问“我们之前谈过XXX吗？”-> 建议智能体使用lcm_grep搜索关键词。
• 当对话非常长，智能体似乎混淆了细节-> 建议智能体使用lcm_describe查看当前上下文的摘要结构，或使用lcm_expand展开某个模糊的摘要节点。
• 在开始一个复杂任务前-> 可以提示智能体：“在开始前，请先用lcm_describe回顾一下我们当前项目的上下文状态。”

6.4 常见问题排查速查表

7. 项目结构与开发指引

如果你需要对插件进行定制化开发，或者想更深入地理解其运作机制，了解其代码结构是很有帮助的。增强版分支在结构上保持了上游的清晰性，并集中修改了核心模块。

7.1 核心代码文件说明

src/ ├── estimate-tokens.ts # 【新增】核心修复！CJK感知的token估算器，被其他模块导入。 ├── engine.ts # 【修改】主引擎文件，集成了token估算器、会话轮换修复、空消息跳过逻辑。 ├── assembler.ts # 【修改】上下文组装器，集成token估算器，跳过空助手消息。 ├── compaction.ts # 【修改】压缩流程控制器，集成token估算器。 ├── retrieval.ts # 【修改】检索逻辑，集成token估算器。 ├── summarize.ts # 【修改】摘要生成器，集成token估算器、修复误报身份验证错误、优化提示词。 └── db/ └── migration.ts # 【修改】数据库迁移脚本，加入了CJK token重新计数的迁移逻辑。 test/ # 【增强】测试用例 ├── estimate-tokens.test.ts # 【新增】包含10个针对CJK、emoji等token估算的测试。 └── cjk-token-recount.test.ts # 【新增】包含8个针对数据库迁移中CJK重新计数的测试。

开发与测试流程：

# 克隆项目后，安装依赖 npm install # 运行所有测试 npx vitest run # 运行特定测试文件（例如，专门测试token估算） npx vitest run test/estimate-tokens.test.ts # 在监视模式下运行测试，便于开发 npx vitest

7.2 如何贡献与同步上游

这个增强版分支的目标是与上游Martian-Engineering/lossless-claw的main分支保持兼容并选择性合并关键修复。

同步上游更改：

# 添加上游仓库为远程源（如果还没添加） git remote add upstream https://github.com/Martian-Engineering/lossless-claw.git # 获取上游最新代码 git fetch upstream # 合并到本地增强版分支 # 注意：可能会产生冲突，需要手动解决，尤其是estimate-tokens.ts等修改过的文件 git merge upstream/main

冲突解决提示：冲突最可能发生在src/estimate-tokens.ts和src/summarize.ts等文件。因为增强版修改了这些核心逻辑。解决冲突时，务必保留增强版的CJK修复和关键Bug修复。合并后，务必重新运行测试，确保功能正常。

经过数周在包含大量中文技术文档讨论的智能体项目上的实际部署，lossless-claw-enhanced的表现非常稳定。它让智能体在面对长达数百页的对话历史时，依然能精准地回忆起几小时前提到的某个API参数细节，这种体验的提升是颠覆性的。如果你受困于OpenClaw的上下文限制，这个插件是目前最优雅、最可靠的解决方案之一。它的设计哲学——不丢弃任何信息，而是智能地管理信息密度——也正是构建强大、持久化AI智能体的关键所在。