Lossless-Claw 关键实现验证

OpenClaw 插件集成

安装与配置

环境要求：

• OpenClaw >= 0.5.0 (支持 ContextEngine 插件接口)
• Node.js >= 22.0.0
• SQLite3 (通常随 Node.js 绑定)

安装步骤：

# 通过 OpenClaw 插件管理器安装
openclaw plugins install @martian-engineering/lossless-claw

# 验证安装
openclaw plugins list

启用插件：

LCM 需要占用 contextEngine 插槽，在 OpenClaw 配置中启用：

{
  "plugins": {
    "slots": {
      "contextEngine": "lossless-claw"
    },
    "entries": {
      "lossless-claw": {
        "enabled": true,
        "config": {
          "freshTailCount": 32,
          "contextThreshold": 0.75,
          "incrementalMaxDepth": -1,
          "summaryModel": "anthropic/claude-sonnet-4-20250514"
        }
      }
    }
  }
}

配置生效验证：

# 检查 LCM 是否正确加载
openclaw plugins info lossless-claw

# 预期输出：
# Plugin: lossless-claw
# Status: enabled
# Slot: contextEngine
# Database: ~/.openclaw/lcm.db

核心配置参数

配置参数详解

参数调优指南

场景 1：高实时性要求（如客服机器人）

{
  "freshTailCount": 16,
  "contextThreshold": 0.85,
  "incrementalMaxDepth": 0
}

• 保护更少消息，减少组装时间
• 提高触发阈值，减少压缩频率
• 仅 Leaf 层压缩，避免递归凝聚延迟

场景 2：长周期任务（如代码审查）

{
  "freshTailCount": 48,
  "contextThreshold": 0.70,
  "incrementalMaxDepth": -1,
  "leafTargetTokens": 1500,
  "condensedTargetTokens": 2500
}

• 保护更多近期消息
• 降低触发阈值，更早开始压缩
• 允许无限深度凝聚
• 增加摘要 token 数以保留更多细节

场景 3：资源受限环境（如边缘设备）

{
  "freshTailCount": 24,
  "contextThreshold": 0.80,
  "leafChunkTokens": 15000,
  "leafTargetTokens": 800
}

• 减少摘要生成的 token 开销
• 更小的 chunk 降低单次 LLM 调用成本

Agent 工具调用

工具概览

LCM 提供 4 个专用工具供 Agent 检索历史信息：

lcm_grep 工具

功能：全文检索历史消息和摘要

参数：

使用示例：

Agent: 让我搜索之前提到的 JWT 配置...

[调用 lcm_grep]
- query: "JWT|token|过期"
- depth: -1

[返回结果]
1. [Leaf @ depth=1] "讨论了登录实现方案，确定使用 JWT + Redis..."
2. [Raw @ depth=0] "用户: JWT 过期时间设多久合适？"
3. [Raw @ depth=0] "助手: 建议 30 分钟，可以配置 refresh token"

性能指标：

• 平均响应时间：80-150ms（FTS5 索引）
• 命中率：>90%（关键词存在于历史中时）

lcm_describe 工具

功能：获取指定时间范围的对话摘要

参数：

使用示例：

Agent: 让我回顾一下本周的讨论重点...

[调用 lcm_describe]
- timeRange: {start: "2026-03-11", end: "2026-03-18"}
- detailLevel: "normal"

[返回结果]
本周主要讨论了：
1. 登录系统架构设计（JWT vs Session）
2. 数据库选型（PostgreSQL vs MySQL）
3. API 安全策略（Rate Limiting, CORS）
关键决策：采用 JWT + Redis 方案，Token 过期时间 30 分钟

lcm_expand 工具

功能：展开摘要节点，查看原始消息

参数：

使用示例：

Agent: 我需要查看登录方案讨论的详细内容...

[调用 lcm_expand]
- summaryId: "leaf_abc123"
- maxTokens: 2000

[返回结果]
完整对话记录：
- [T+0] 用户: 需要实现用户登录功能，有什么建议？
- [T+1] 助手: 可以考虑 JWT 或 Session 方案。JWT 适合分布式，Session 简单但依赖存储。
- [T+2] 用户: 我们用微服务架构，推荐 JWT 吗？
- [T+3] 助手: 是的，JWT 更适合。建议搭配 Redis 存储黑名单...

工具调用流程图

sequenceDiagram
    participant Agent
    participant LCM as LCM Engine
    participant DB as SQLite
    participant LLM as 摘要模型

    Agent->>LCM: lcm_grep("JWT")
    LCM->>DB: FTS5 查询
    DB-->>LCM: 匹配结果
    LCM-->>Agent: 返回摘要列表

    Agent->>LCM: lcm_describe(timeRange)
    LCM->>DB: 查询对应时段摘要
    DB-->>LCM: 摘要节点
    LCM-->>Agent: 返回结构化摘要

    Agent->>LCM: lcm_expand(summaryId)
    LCM->>DB: 查询摘要的 source_ids
    DB-->>LCM: 原始消息 ID 列表
    LCM->>DB: 批量查询原始消息
    DB-->>LCM: 完整消息内容
    LCM-->>Agent: 返回展开后的对话

集成检查清单

部署前检查

功能验证：

• 插件安装成功，openclaw plugins list 显示 lossless-claw
• 配置文件正确，slot 指向 lossless-claw
• SQLite 数据库可写入，~/.openclaw/lcm.db 存在
• 摘要模型配置正确，能正常调用

性能基准：

• 单轮对话延迟 < 500ms
• lcm_grep 响应 < 200ms
• 50 轮对话后上下文组装 < 300ms

质量验证：

• lcm_describe 返回的摘要准确反映历史
• lcm_expand 能正确回溯到原始消息
• 长对话（>30 轮）关键信息未被截断

常见问题排查

问题 1：LCM 未生效，仍然使用滑动窗口

检查项：

1. 确认 plugins.slots.contextEngine 设置为 "lossless-claw"
2. 确认插件状态为 enabled
3. 重启 OpenClaw 服务

问题 2：摘要生成失败

检查项：

1. 确认 summaryModel 配置正确
2. 检查 API Key 权限
3. 查看日志：~/.openclaw/logs/lcm.log

问题 3：数据库性能差

优化方案：

1. 启用 FTS5 索引：PRAGMA enable_fts5
2. 定期清理旧对话
3. 考虑分库（按 conversation_id 分片）

参考资料

1. Lossless-Claw Configuration Guide - 官方配置文档
2. Agent Tools Reference - 工具 API 详细说明
3. OpenClaw Plugin Development - 插件开发指南
4. SQLite Performance Optimization - 全文检索性能调优