给Qclaw安装memory-tencentdb插件教程（实战版）

无标签
发布日期:   2026-06-06

QClaw 安装 memory-tencentdb 插件教程（实战版）

本文是一份经过实战验证的完整安装指南。假设你已有一个解压好的 memory-tencentdb 插件目录，放在 C:\memory-tencentdb，下面是每一步的详细操作。

一、插件简介

memory-tencentdb 是 QClaw 的四层记忆系统插件（L0-L3），提供：

  • L0：对话自动捕获
  • L1：记忆提取与去重
  • L2/L3：场景归纳与用户画像

支持两种存储后端：SQLite（本地，开箱即用）和 TCVDB（腾讯云向量数据库）。

本文以 SQLite 模式为例完成安装。

二、准备工作

环境要求

项目 要求
操作系统 Windows 10/11（macOS/Linux 流程类似）
Node.js v18+（QClaw 自带，位于安装目录）
QClaw 版本 v0.2.24+
插件源码 解压后的 memory-tencentdb 目录

确认 Node.js 可用

打开 PowerShell，执行：

node --version
# 应输出 v22.x 或更高
npm --version
# 应输出 10.x 或更高

三、安装步骤

第 1 步：复制插件到用户扩展目录

QClaw 加载用户插件的目录是 ~/.qclaw/extensions/（即 C:\Users\<用户名>\.qclaw\extensions\）。

将解压好的插件目录复制过去：

# 假设你的解压目录在 C:\memory-tencentdb
Copy-Item -Path "C:\memory-tencentdb" -Destination "$env:USERPROFILE\.qclaw\extensions\memory-tencentdb" -Recurse

⚠️ 注意：不要放到 C:\Program Files\QClaw\... 下面，那里权限受限且下次更新会被覆盖。

验证复制成功：

Get-ChildItem "$env:USERPROFILE\.qclaw\extensions\memory-tencentdb" | Select-Object Name

你应该看到 package.json、openclaw.plugin.json、index.ts 等文件。

第 2 步：安装 npm 依赖

进入插件目录并安装依赖：

Push-Location "$env:USERPROFILE\.qclaw\extensions\memory-tencentdb"
npm install --no-audit --no-fund
Pop-Location

⚠️ 为什么要加 --no-audit --no-fund？

npm 10.x 存在一个已知 bug，在执行 npm install 时会读取全局审计缓存中的无关包信息，导致 Arborist 内部报错：

Cannot read properties of undefined (reading 'spec')

加上 --no-audit --no-fund 可以绕过这个问题。

安装成功的标志：输出末尾显示类似 added 197 packages in 15s。

如果 postinstall 脚本报错（Windows 上 bash 不兼容），可以忽略——依赖本身不受影响。

第 3 步：构建插件

插件源码是 TypeScript，需要编译成 JavaScript 才能运行：

Push-Location "$env:USERPROFILE\.qclaw\extensions\memory-tencentdb"
npx tsdown index.ts --out-dir dist --format esm --clean
Pop-Location

预期输出：

ℹ dist\index.mjs               758.34 kB
ℹ dist\l1-reader-XXXXXX.mjs      3.67 kB
✔ Build complete in 258ms

验证构建产物：

Get-ChildItem "$env:USERPROFILE\.qclaw\extensions\memory-tencentdb\dist"

应该看到 index.mjs 和 l1-reader-*.mjs 两个文件。

⚠️ 关键：package.json 中 "main" 字段指向 ./dist/index.mjs，构建产物必须放在 dist/ 子目录中。如果构建产物跑到了根目录，QClaw 将无法加载插件。

第 4 步：配置 QClaw 启用插件

编辑 QClaw 配置文件 C:\Users\<用户名>\.qclaw\openclaw.json。

你需要修改两个地方：

4.1 在 plugins.allow 中添加插件名

找到 plugins.allow 数组（通常长这样）：

"plugins": {
  "allow": [
    "wechat-access",
    "qclaw-plugin",
    "feishu",
    "lossless-claw",
    "browser"
  ]
}

在数组末尾追加 "memory-tencentdb"（注意逗号）：

"plugins": {
  "allow": [
    "wechat-access",
    "qclaw-plugin",
    "feishu",
    "lossless-claw",
    "browser",
    "memory-tencentdb"
  ]
}

4.2 在 plugins.entries 中添加插件配置

找到 plugins.entries 对象，添加：

"plugins": {
  "entries": {
    "wechat-access": { "enabled": true },
    "qclaw-plugin": { "enabled": true },
    "memory-tencentdb": { "enabled": true }
  }
}

完整示例（最小 SQLite 配置）：

"memory-tencentdb": {
  "enabled": true,
  "config": {
    "storeBackend": "sqlite"
  }
}

💡 之后可以通过添加 "capture"、"extraction"、"persona" 等子配置来定制记忆行为，详见插件自带的 openclaw.plugin.json 中的 configSchema。

第 5 步：检查并清理冲突

如果你之前手动把插件放到了 QClaw 安装目录（C:\Program Files\QClaw\...\extensions\），会产生 duplicate plugin ID 冲突。

检查是否存在冲突文件：

Test-Path "C:\Program Files\QClaw\v0.2.24.540\resources\openclaw\config\extensions\memory-tencentdb"

如果返回 True，需要删除它：

Remove-Item "C:\Program Files\QClaw\v0.2.24.540\resources\openclaw\config\extensions\memory-tencentdb" -Recurse -Force

⚠️ 如果提示权限不足（UnauthorizedAccessException），需要提示用户在文件资源管理器中手动删除。

第 6 步：重启网关

配置修改后需要重启 QClaw 网关才能生效。

方案 A：通过命令行重启

# 停止旧网关
openclaw gateway stop

# 启动新网关
openclaw gateway

方案 B：重启 QClaw 主程序

右键任务栏 QClaw 图标 → 退出 → 重新打开。

四、验证安装

4.1 检查配置是否生效

向 AI 发送：

请检查 memory-tencentdb 插件是否已加载

或者直接让 AI 执行：

gateway config.get plugins

查看输出中 plugins.entries.memory-tencentdb 是否为 enabled: true。

4.2 检查可用工具

插件加载成功后会注册两个工具：

  • tdai_memory_search：搜索结构化记忆
  • tdai_conversation_search：搜索原始对话

让 AI 确认这两个工具是否出现在工具列表中。

4.3 无警告 = 成功

关键在于 gateway config.get 的输出中 warnings 数组应为空。如果出现：

duplicate plugin id: memory-tencentdb

说明第 5 步的冲突未清理干净，回到第 5 步重新处理。

五、常见问题

Q1：npm install 报 Cannot read properties of undefined (reading 'spec')

原因：npm 10.x Arborist 内部 bug。

解决：加 --no-audit --no-fund 参数。

npm install --no-audit --no-fund

如果仍然失败，删除 node_modules 和 package-lock.json 后重试：

Remove-Item node_modules -Recurse -Force
Remove-Item package-lock.json -Force
npm install --no-audit --no-fund

Q2：postinstall 脚本报错 "bash not found"

原因：postinstall 脚本调用了 bash，Windows 默认没有 bash。

影响：无。postinstall 脚本是一个可选的补丁操作，失败不影响插件功能。

Q3：网关重启后插件没加载

检查清单：

  1. dist/index.mjs 是否存在？（第 3 步）
  2. package.json 中 "main" 是否指向 ./dist/index.mjs？
  3. openclaw.json 中是否已添加 plugins.allow 和 plugins.entries？（第 4 步）
  4. plugins.load.paths 中是否包含 ~/.qclaw/extensions？
  5. 有没有 duplicate plugin ID 警告？（第 5 步）

Q4：config.patch 报 "Unrecognized key"

原因：config.patch 对 plugins.entries 下的自定义 key 存在 schema 校验限制。

解决：直接编辑 openclaw.json 文件，不要通过 config.patch。

Q5：Program Files 下的冲突目录删不掉

解决：打开文件资源管理器，导航到 C:\Program Files\QClaw\v0.2.24.540\resources\openclaw\config\extensions\，右键 → 删除 memory-tencentdb 文件夹。如果系统提示需要管理员权限，点击「继续」。

六、进阶配置（可选）

启用记忆自动捕获

"memory-tencentdb": {
  "enabled": true,
  "config": {
    "storeBackend": "sqlite",
    "capture": {
      "enabled": true
    },
    "extraction": {
      "enabled": true,
      "maxMemoriesPerSession": 20
    },
    "recall": {
      "enabled": true,
      "strategy": "hybrid"
    }
  }
}

切换到腾讯云向量数据库（TCVDB）

"memory-tencentdb": {
  "enabled": true,
  "config": {
    "storeBackend": "tcvdb",
    "tcvdb": {
      "url": "http://your-tcvdb-instance:8100",
      "username": "root",
      "apiKey": "your-api-key"
    }
  }
}

七、卸载插件

  1. 关闭 QClaw 网关：openclaw gateway stop
  2. 编辑 openclaw.json，从 plugins.allow 和 plugins.entries 中移除 memory-tencentdb
  3. 删除插件目录：Remove-Item "$env:USERPROFILE\.qclaw\extensions\memory-tencentdb" -Recurse -Force
  4. 重启网关：openclaw gateway

📝 本文基于 2026-06-06 实战安装过程编写，涵盖从源码到运行的 6 个步骤和 5 个常见踩坑点。如有问题欢迎反馈。

文章作者: 摸鱼
文章链接: https://gtjs-9gjbu0mx.maozi.io/2026/06/06/guan-yu-ji-neng/22-gei-qclaw-an-zhuang-memory-tencentdb-cha-jian-jiao-cheng/
版权声明: 本博客所有文章除特別声明外，均采用 CC BY 4.0 许可协议。转载请注明来源 摸鱼 !
无标签
赏
  目录