最近在折腾 OpenClaw 时遇到了一个插件加载问题。系统启动时总是提示 “Context engine ‘lossless-claw’ is not registered. Available engines: legacy.”，导致上下文引擎只能回退到 legacy 模式。虽然基本功能不受影响，但 lossless-claw 提供的 DAG-based 对话摘要、增量压缩等高级功能无法使用。研究了一番，发现是 peer dependency 问题，记录一下解决过程。

问题诊断

　　首先检查系统状态，执行 /model status 发现上下文引擎配置为 lossless-claw，但系统提示未注册。查看配置文件 openclaw.json，plugins 部分配置如下：

1
2
3
4
5
6
7
8
9
10
11
"plugins": {
  "enabled": true,
  "slots": {
    "contextEngine": "lossless-claw"
  },
  "entries": {
    "lossless-claw": {
      "enabled": true
    }
  }
}

　　配置没问题，那问题出在哪里？进入插件目录检查依赖情况：

1
2
cd "C:\Program Files\QClaw\resources\openclaw\config\extensions\lossless-claw"
npm list --depth=0

　　输出结果发现了问题：

1
2
3
4
5
6
7
@martian-engineering/lossless-claw@0.3.0
+-- @mariozechner/pi-agent-core@0.67.3
+-- @mariozechner/pi-ai@0.67.3
+-- @sinclair/typebox@0.34.48
`-- UNMET DEPENDENCY openclaw@*

npm error missing: openclaw@*, required by @martian-engineering/lossless-claw@0.3.0

　　原来是 openclaw 包这个 peer dependency 没有满足。peer dependency 是 npm 的一种依赖类型，要求宿主环境提供这个包，而不是由插件自己安装。lossless-claw 需要主程序提供 openclaw 包，但插件目录的 node_modules 里没有找到。

解决方案

方案一：在系统目录创建符号链接（失败）

　　首先想到的是在系统目录创建符号链接。OpenClaw 主包存在于：

1
C:\Program Files\QClaw\resources\openclaw\node_modules\openclaw

　　尝试创建符号链接：

1
2
3
4
$src = "C:\Program Files\QClaw\resources\openclaw\node_modules\openclaw"
$dest = "C:\Program Files\QClaw\resources\openclaw\config\extensions\lossless-claw\node_modules\openclaw"

New-Item -ItemType SymbolicLink -Path $dest -Target $src

　　结果提示权限不足。C:\Program Files 目录需要管理员权限，而 QClaw 的安全策略拦截了提权操作。

方案二：复制插件到用户目录（成功）

　　既然系统目录无法写入，那就把插件复制到用户目录。用户目录有完全的读写权限，可以自由管理。

　　第一步：创建用户插件目录并复制文件

1
2
3
4
5
6
7
$srcPath = "C:\Program Files\QClaw\resources\openclaw\config\extensions\lossless-claw"
$destPath = "C:\Users\hao\.qclaw\extensions\lossless-claw"

New-Item -ItemType Directory -Path $destPath -Force
Copy-Item -Path "$srcPath\*" -Destination $destPath -Recurse -Force

Write-Host "✅ 插件已复制到用户目录"

　　第二步：安装依赖

1
2
cd "C:\Users\hao\.qclaw\extensions\lossless-claw"
npm install

　　等待安装完成，输出：

1
2
3
4
added 621 packages, changed 21 packages, and audited 796 packages in 29s

132 packages are looking for funding
  run `npm fund` for details

　　第三步：验证依赖

1
2
cd "C:\Users\hao\.qclaw\extensions\lossless-claw"
npm list --depth=0

　　输出结果：

1
2
3
4
5
@martian-engineering/lossless-claw@0.3.0
+-- @mariozechner/pi-agent-core@0.67.3
+-- @mariozechner/pi-ai@0.67.3
+-- @sinclair/typebox@0.34.48
`-- openclaw@2026.4.15

　　所有依赖都已满足！可以看到 openclaw@2026.4.15 已经成功安装。

更新配置

　　依赖问题解决了，接下来需要告诉 OpenClaw 去用户目录加载插件。修改 C:\Users\hao\.qclaw\openclaw.json：

1
2
3
4
5
6
7
8
9
10
11
12
"plugins": {
  "enabled": true,
  "load": {
    "paths": [
      "C:\\Program Files\\QClaw\\resources\\openclaw\\config\\extensions",
      "C:\\Users\\hao\\.qclaw\\extensions"
    ]
  },
  "slots": {
    "contextEngine": "lossless-claw"
  }
}

　　主要修改了两处：

  1. plugins.load.paths 新增了用户插件目录
  2. plugins.slots.contextEngine 恢复为 lossless-claw

　　保存配置后重启 OpenClaw：

1
openclaw gateway restart

　　重启完成后执行 /model status，一切正常，不再有错误提示。

验证结果

　　对比修复前后：

项目 修复前 修复后
上下文引擎 ❌ 未注册，回退到 legacy ✅ lossless-claw 正常运行
插件位置 系统目录（无写权限） 用户目录（完全控制）
依赖状态 ❌ 缺少 openclaw 包 ✅ 所有依赖已满足
高级功能 ❌ 不可用 ✅ DAG 摘要、增量压缩可用

lossless-claw 的优势

　　相比 legacy 引擎，lossless-claw 提供了更强大的上下文管理能力：

  1. DAG-based 对话摘要：基于有向无环图的历史管理，保留对话结构
  2. 增量压缩：渐进式上下文压缩，减少信息丢失
  3. 更好的记忆连续性：长对话中保持关键信息
  4. 优化的 token 利用率：更高效地使用上下文窗口

总结

　　这次问题解决了，主要经验是：

  1. 遇到 npm 依赖问题，先用 npm list 诊断
  2. 系统目录权限受限时，考虑迁移到用户目录
  3. peer dependency 需要宿主环境提供，可以用 npm install 安装到本地
  4. 修改配置后记得重启服务

　　另外，用户目录 ~/.qclaw/extensions/ 是一个很好的插件管理位置，有完全的写入权限，方便后续更新和维护。