2026年完全指南：OpenClaw LCM 插件 — 再也不会丢失任何对话

2026年完全指南：OpenClaw LCM 插件 — 再也不会丢失任何对话

核心要点 (TL;DR)

  • Lossless-Claw 插件用 DAG 结构的存储系统替换了 OpenClaw 默认的上下文引擎，让对话历史永不丢失
  • 每条消息都持久化到 SQLite 数据库并汇总为可展开的节点——你可以随时回溯到对话的任意时间点
  • 5 分钟内完成配置：安装插件，改一行配置，立刻生效
  • 注重成本的用户可以让摘要走便宜模型（如 Claude Haiku），主对话保持在高级模型上
  • 本指南涵盖安装、配置、架构、代理工具、故障排除——你需要的一切都在这里

目录

  1. LCM 解决了什么问题？
  2. 安装步骤
  3. DAG 模型的工作原理
  4. 配置详解
  5. 代理工具：grep、describe、expand_query
  6. 架构内部原理
  7. 相比传统上下文管理的优势
  8. 已知限制
  9. 故障排除
  10. 常见问题

1. LCM 解决了什么问题？

默认情况下，OpenClaw 使用的是传统上下文引擎，当对话变长时会截断或滑动清除旧消息。一旦这些消息消失，代理就彻底失去了对早期上下文的访问能力。这对于长期项目、复杂的调试会话，或任何跨越数天至数周的对话来说，都是一个根本性问题。

Lossless-Claw 插件用一种根本不同的方式解决这个问题：

  • 每条消息都持久化到本地 SQLite 数据库——永不删除
  • 旧消息被汇总成 DAG（有向无环图）结构的多层摘要
  • 代理可以随时展开任意摘要，恢复完整细节
  • 上下文组装是预算感知的，将最相关的信息装入模型的上下文窗口

结果：可以运行数百甚至数千轮对话，而代理永远不会"遗忘"之前发生的事。

2. 安装步骤

从 npm 安装（推荐）

openclaw plugins install @martian-engineering/lossless-claw

从本地克隆安装（开发用）

git clone https://github.com/Martian-Engineering/lossless-claw.git
openclaw plugins install --link ./lossless-claw

激活为上下文引擎

这一步必须。不执行的话插件加载了但不运行——默认的 legacy 引擎仍然生效。

openclaw config set plugins.slots.contextEngine lossless-claw

验证

openclaw plugins list

你应该看到 lossless-claw 列为已启用，且 contextEngine 槽位已分配给它。

更新

openclaw plugins update @martian-engineering/lossless-claw
# 或者一次性更新所有插件：
openclaw plugins update --all

3. DAG 模型的工作原理

核心思路

传统上下文管理是线性的：保留最新的 N 条消息，丢弃其余。LCM 则构建一棵树：

原始消息:   [m1] [m2] [m3] ... [m20] [m21] ... [m40] ... [m80] ... [m100]
                 ↓ 分块                  ↓ 分块            ↓ 分块
叶子(d0):    [leaf_1: m1-m20]      [leaf_2: m21-m40]   [leaf_3: ...]  [leaf_4: ...]
                 ↓                        ↓
 凝聚(d1):  [cond_1: leaf_1 + leaf_2]                 [cond_2: leaf_3 + leaf_4]
                 ↓                                            ↓
 凝聚(d2):  [cond_3: cond_1 + cond_2]
                                                    ↑
                                            仍可展开

每个节点都携带元数据：时间范围、token 数量、后裔数量、源引用。代理在上下文窗口中看到的是摘要，通过检索工具可以深入任意节点获取完整细节。

生命周期钩子

引擎钩入 OpenClaw 对话流程的四个关键点：

阶段 发生什么
Bootstrap 启动时协调 JSONL 会话文件和 SQLite 数据库，导入自上次检查点以来的新消息
Assemble 每次模型调用前，在 token 预算内构建消息数组：最近的原始消息（"新鲜尾部"）+ 从 DAG 中选出的摘要
After Turn 模型响应后，持久化新消息并评估是否需要压缩
Compact 当上下文超过阈值时，运行叶子层和/或凝聚层摘要压缩

压缩：三档降级机制

每次摘要尝试都遵循一个保证进度的降级链：

  1. Normal — 高保真提示词，温度 0.2，目标约 1200 tokens
  2. Aggressive — 更严格的提示词，更少细节，温度 0.1，较低 token 目标
  3. Deterministic fallback — 截断至约 512 tokens，带 [Truncated for context management] 标记

即使摘要模型宕机或返回垃圾，压缩也会成功。

大文件处理

当消息中的文件（代码粘贴、日志转储等）超过 largeFileTokenThreshold（默认 25,000 tokens）时：

  1. 文件内容被提取并存储到磁盘（~/.openclaw/lcm-files/）
  2. 用约 200 tokens 的结构摘要替换消息中的文件
  3. 可通过 lcm_describe 获取完整文件

这防止单个大粘贴把整个上下文窗口吃光。

4. 配置详解

用 openclaw config edit 打开配置，在 plugins.entries.lossless-claw.config 下添加设置：

{
  "plugins": {
    "slots": {
      "contextEngine": "lossless-claw"
    },
    "entries": {
      "lossless-claw": {
        "enabled": true,
        "config": {
          // 所有字段都是可选的 — 默认值都很合理
        }
      }
    }
  }
}

所有设置也可通过环境变量覆盖（前缀 LCM_，如 LCM_FRESH_TAIL_COUNT=32）。环境变量优先级最高。

关键参数

参数 默认值 说明
contextThreshold 0.75 触发压缩的上下文窗口比例。设为 0.75 表示消耗 75% 预算时触发压缩
freshTailCount 20 最近原始消息数量，始终保留不压缩，即代理的"工作内存"
incrementalMaxDepth -1 增量（每轮）凝聚的深度。0 = 仅叶子压缩，1 = 一级凝聚，-1 = 无限制
dbPath ~/.openclaw/lcm.db SQLite 数据库路径
summaryModel （会话模型） 摘要用模型覆盖，可用便宜/快速的模型降成本（如 anthropic/claude-haiku-4-5）
expansionModel （会话模型） lcm_expand_query 子代理的模型覆盖
largeFileTokenThreshold 25000 超过此 token 数的文件外部化到磁盘

会话过滤

参数 说明
ignoreSessionPatterns 完全排除的会话 glob 模式，如 ["agent:*:cron:**"] 排除所有 cron 会话
statelessSessionPatterns 只读数据库但不写入的会话模式，如 ["agent:*:subagent:**"] 让子代理访问父上下文但不污染 DB
skipStatelessSessions 设为 true 时，无状态会话跳过所有 LCM 持久化

推荐配置

通用（平衡型）：

{
  "contextThreshold": 0.75,
  "freshTailCount": 32,
  "incrementalMaxDepth": -1
}

长期运行会话（数百轮）：

{
  "contextThreshold": 0.8,
  "freshTailCount": 32,
  "incrementalMaxDepth": 2
}

成本敏感（最小化摘要调用）：

{
  "contextThreshold": 0.85,
  "freshTailCount": 16,
  "summaryModel": "anthropic/claude-haiku-4-5"
}

5. 代理工具：grep、describe、expand_query

LCM 激活后会注册三个工具，代理可随时调用来检索压缩的上下文：

lcm_grep — 快速全文搜索

lcm_grep({ pattern: "database migration", mode: "full_text" })
lcm_grep({ pattern: "error.*timeout", mode: "regex", scope: "messages" })
lcm_grep({ pattern: "deployment", since: "2026-03-01", limit: 20 })
  • 快速（<100ms）— 直接 SQLite 查询
  • 支持 FTS5（有则用），CJK 文本自动回退到 LIKE 查询
  • 可限定范围为 messages、summaries 或 both
  • 用 since/before 按时间范围过滤

lcm_describe — 直接元数据查询

lcm_describe({ id: "sum_abc123" })
lcm_describe({ id: "file_xyz789" })
  • 快速（<100ms）— 直接查找
  • 摘要：返回完整内容、元数据、父子链接、源消息 ID、子树结构
  • 文件：返回完整文件内容和探索摘要

lcm_expand_query — 子代理深度检索

lcm_expand_query({
  prompt: "我们在 users 表的 SQL 迁移上具体讨论了什么？",
  summaryIds: ["sum_abc123"]
})
  • 慢但强大（约 30-120 秒）— 启动遍历 DAG 的子代理
  • 子代理对当前对话有只读权限
  • 有时间限制（5 分钟 TTL），超时自动撤销
  • 当 lcm_grep 或 lcm_describe 不够用时使用

何时用哪个工具

需求 工具 原因
"我们讨论过 X 吗？" lcm_grep 快速关键词/正则扫描
"这个摘要包含什么？" lcm_describe 直接元数据查找
"三天前我们关于 X 具体决定了什么？" lcm_expand_query 有证据的深度检索

6. 架构内部原理

                        ┌─────────────────────┐
                        │   OpenClaw Gateway   │
                        └──────────┬──────────┘
                                   │
                          ┌────────▼────────┐
                          │  Agent Runtime   │
                          └────────┬────────┘
                                   │
               ┌───────────────────┼───────────────────┐
               │                   │                   │
       ┌───────▼───────┐  ┌───────▼───────┐  ┌───────▼───────┐
       │   Bootstrap    │  │   Assemble    │  │  After Turn   │
       │ (session sync) │  │ (build prompt)│  │ (persist +    │
       │                │  │               │  │  compact?)    │
       └───────┬───────┘  └───────┬───────┘  └───────┬───────┘
               │                  │                   │
               └──────────────────┼───────────────────┘
                                  │
                     ┌────────────▼────────────┐
                     │    SQLite Database       │
                     │  ┌──────────────────┐   │
                     │  │ messages          │   │
                     │  │ summaries (DAG)   │   │
                     │  │ context_items     │   │
                     │  │ large_files       │   │
                     │  └──────────────────┘   │
                     └─────────────────────────┘
                                  │
                    ┌─────────────┼─────────────┐
                    │             │             │
              ┌─────▼─────┐ ┌────▼────┐ ┌─────▼──────┐
              │ lcm_grep  │ │lcm_desc │ │lcm_expand  │
              │ (search)  │ │(inspect)│ │(sub-agent) │
              └───────────┘ └─────────┘ └────────────┘

崩溃恢复

Bootstrap 系统通过字节偏移和条目哈希追踪对账进度。如果 OpenClaw 在会话中途崩溃，下次启动会精确地从中断处继续——无重复摄入，无消息丢失。

子代理隔离

扩展系统使用带 TTL 和显式撤销的作用域委托授权。子代理获得精确所需的对话的只读访问权限，在完成或超时时自动清理。

7. 相比传统上下文管理的优势

永不丢失

每条消息都被持久化。摘要链接回源消息。代理永远可以通过 lcm_expand_query 恢复完整细节。这与滑动窗口截断有本质区别——旧上下文一去不返。

智能压缩

深度感知的摘要提示词在不同层级产生不同风格的摘要： - 叶子摘要 保留具体决定、命令、错误和理由 - 中级摘要 提取主题、关键决定和未解决的张力 - 高层摘要 捕获会话弧线、重大转折点和长期约束

成本控制

可以用便宜模型做摘要（如 Haiku），主对话保持在高级模型（如 Opus）。summaryModel 和 expansionModel 设置让这变得明确。

崩溃恢复

Bootstrap 系统追踪字节偏移和对账进度，崩溃后可精确恢复。

子代理隔离

扩展系统用 TTL 和显式撤销确保子代理只读访问精确所需的对话。

会话过滤

Glob 模式让你排除嘈杂会话（cron、心跳）的存储，同时将子代理会话标记为无状态——享受父上下文的好处但不污染数据库。

8. 已知限制

摘要质量依赖模型

摘要质量取决于生成它的模型。用太便宜或太小的模型做摘要可能会丢失细节。即使是好的模型，重要细节也可能被压缩掉——lcm_expand_query 可以缓解，但会增加延迟。

扩展很慢

lcm_expand_query 会启动子代理，需要 30-120 秒。快速检索用 lcm_grep 和 lcm_describe 快得多但能力有限。在时间敏感的 workflow 中，代理可能跳过扩展，仅凭摘要工作。

存储增长

SQLite 数据库随每条消息增长。长期重型会话（数千轮带大工具输出）可能产生数百兆的数据库。外部化到磁盘的大文件进一步增加。目前没有内置垃圾回收或保留策略——旧对话永久保留。

单模型摘要

每次摘要使用一次模型调用。没有集成或验证步骤。如果模型在摘要过程中产生幻觉或误解上下文，错误会传播到 DAG 并可能影响未来的组装。

无跨会话上下文

每个对话在数据库中独立。LCM 不会在不同会话或代理间自动共享上下文。检索工具上的 allConversations 标志允许跨对话搜索，但组装时没有自动跨-pollination。

CJK 全文搜索限制

FTS5（SQLite 全文搜索引擎）对中文、日文、韩文的分词效果不佳。LCM 回退到 CJK 查询的 LIKE 搜索，在大型数据库上更慢且精度更低。

压缩延迟

每次压缩需要 LLM 调用（通常每叶子或凝聚步骤 5-15 秒）。重度压缩时会在回合完成后产生明显延迟。afterTurn 钩子按会话串行化压缩，不会阻塞其他会话。

9. 故障排除

插件安装了但没激活

检查上下文引擎槽位是否设置：

openclaw config get plugins.slots.contextEngine

必须返回 lossless-claw。如果是 legacy 或为空，则设置：

openclaw config set plugins.slots.contextEngine lossless-claw

摘要认证错误

如果看到 LcmProviderAuthError，摘要所用模型无法认证。检查： - summaryModel 是否设为你有访问权限的模型？ - 提供商是否需要单独的 API 密钥？ - 尝试取消设置 summaryModel，回退到会话模型。

数据库位置

默认：~/.openclaw/lcm.db。可通过 dbPath 配置或 LCM_DB_PATH 环境变量覆盖。

直接检查数据库：

sqlite3 ~/.openclaw/lcm.db ".tables"
sqlite3 ~/.openclaw/lcm.db "SELECT COUNT(*) FROM messages"
sqlite3 ~/.openclaw/lcm.db "SELECT id, kind, depth, token_count FROM summaries ORDER BY created_at DESC LIMIT 10"

重置 LCM 状态

清空并重新开始（删除所有持久化上下文）：

rm ~/.openclaw/lcm.db
rm -rf ~/.openclaw/lcm-files/

数据库和文件存储会在下次会话启动时重建。

10. 常见问题

Q: 安装 LCM 后工作流需要改变吗？

A: 不需要。安装并激活后，LCM 在后台静默运行。正常对话工作流完全不变。代理自动管理上下文组装和压缩。只有在想检索特定历史细节时才需要使用检索工具（lcm_grep、lcm_describe、lcm_expand_query）。

Q: LCM 会拖慢对话吗？

A: 正常对话中影响很小。某些回合后压缩运行时你可能会注意到 5-15 秒的停顿——但这发生在后台，不会阻塞你。lcm_grep 和 lcm_describe 很快（<100ms）。只有 lcm_expand_query 慢（30-120 秒），但这是设计如此。

Q: 可以用不同模型做摘要来省钱吗？

A: 可以。将 summaryModel 设为 anthropic/claude-haiku-4-5 等更便宜的模型。主对话可以继续用 Opus 或 Sonnet，摘要通过 Haiku 路由。这是 LCM 最实用的成本控制功能之一。

Q: 如果摘要模型失败了怎么办？

A: LCM 使用三级降级链：Normal → Aggressive → Deterministic（截断）。即使摘要模型完全宕机，deterministic fallback 也能保证压缩成功。

Q: 子代理可以写入 LCM 数据库吗？

A: 默认情况下子代理是无状态的，从父上下文读取。你可以通过配置 statelessSessionPatterns 来控制哪些子代理写入 vs. 只读。除非显式配置，否则子代理不会污染数据库。

Q: LCM 如何处理超大的代码粘贴？

A: 超过 25,000 tokens 的文件外部化到磁盘（~/.openclaw/lcm-files/），用约 200 tokens 的结构摘要替换。使用 lcm_describe 可以按需检索完整文件内容。

Q: 我的数据是存在本地还是发送到服务器？

A: 所有数据保留在本地。SQLite 数据库和外部化文件位于你机器上的 ~/.openclaw/。不会将数据发送到任何外部服务。

总结与建议

LCM 将 OpenClaw 从一个健忘的聊天机器人变成了真正的长期记忆系统。如果你从事复杂项目、与 AI 助手保持持续对话，或者只是讨厌讨论变长时丢失上下文——这个插件是必备的。

从这里开始： 1. 安装：openclaw plugins install @martian-engineering/lossless-claw 2. 激活：openclaw config set plugins.slots.contextEngine lossless-claw 3. 验证：openclaw plugins list 4. 完成。下一个对话就开始构建 DAG 了。

专业提示： 成本敏感的设置，在配置中添加 "summaryModel": "anthropic/claude-haiku-4-5"。摘要调用随时间累积，而 Haiku 能以很低成本很好地处理这个任务。

延伸阅读： - Lossless-claw 仓库 - OpenClaw 插件架构 - 构建 OpenClaw 插件 - 上下文引擎概念

本文基于官方 LCM 插件（Lossless Context Management）文档生成。最新信息请查阅 GitHub 仓库。

posted on 2026-03-30 12:19  见路非道  阅读(10)  评论(0)    收藏  举报