环境信息

• OpenClaw 版本：3.8
• 系统：Windows

背景介绍

什么是 QMD？

QMD 是一个专为 AI 应用设计的长期记忆系统，通过向量数据库技术让 AI 能够"记住"并"回忆"过去的对话或知识。

核心技术：

• 向量嵌入：将文本转换为高维向量（使用 gemma-300M-Q8_0 模型），使语义可计算
• 向量数据库：基于 SQLite + vector 扩展，高效存储和检索向量
• 语义搜索：根据语义相似度而非关键词匹配，实现更智能的记忆召回

为什么 OpenClaw 需要 QMD？

在 OpenClaw 3.8 中，QMD 是内置的核心性能组件，从根本上解决了大语言模型在实际应用中的三大痛点。

核心价值：

1. 智能上下文管理：告别"全量记忆"的浪费

   • 传统 AI 对话需要将整个历史对话作为上下文反复发送，导致 Token 消耗随对话轮次线性增长
   • QMD 通过向量检索，只加载与当前问题最相关的历史记忆，大幅降低冗余

2. 响应速度飞跃：从"等待"到"即时"

   • Token 数量的减少直接带来响应速度的提升
   • QMD 的检索时间恒定（约 100ms），不会随历史增长而变慢

3. 成本断崖式下降：从"烧钱"到"可控"

   • Token 即成本。通过减少无效上下文，QMD 让 API 调用费用实现指数级降低

一句话总结：QMD = 记忆更准、响应更快、成本更低。它是 OpenClaw 从"能用"到"好用"的关键一跃。

第一步：安装 QMD CLI

1.1 安装 QMD

所有平台统一使用以下命令：

npm i -g bun
bun install -g github:tobi/qmd

1.2 安装支持向量扩展的 SQLite

QMD 需要支持 vector 扩展的 SQLite。

Windows 手动安装步骤：

1. 访问 SQLite 官网下载页面：https://www.sqlite.org/download.html
2. 下载 “Precompiled Binaries for Windows” 中的 sqlite-tools-win-x64-*.zip（包含 sqlite3.exe）
3. 解压到任意目录（例如 F:\Learning\sqlite）
4. 将该目录添加到系统 PATH 环境变量：
   • 右键"此电脑" → “属性” → “高级系统设置”
   • 点击"环境变量" → 编辑"Path"变量
   • 添加解压路径（例如 F:\Learning\sqlite）
5. 重启终端，验证安装：

sqlite3 --version

1.3 验证 QMD 安装

qmd --version

⚠️ 问题诊断与解决

问题 1：Bun 安装失败

错误信息：

error: interpreter executable "/bin/sh" not found in %PATH%
Bun failed to remap this bin to its proper location within node_modules.

根本原因：

• Bun 是主要为 Linux/macOS 设计的工具链
• QMD 的二进制文件包含 Unix shebang（#!/bin/sh）
• Windows 的 cmd 和 PowerShell 无法解析这种脚本

解决方案：使用 npm 全局安装 QMD（而不是 Bun）

第二步：正确安装 QMD（Windows）

2.1 卸载 Bun 安装的版本

bun remove -g @tobilu/qmd

2.2 使用 npm 全局安装

npm install -g github:tobi/qmd

可能遇到的错误：

npm error code 4294963245
npm error git dep preparation failed
npm error code ENOTEMPTY
npm error syscall rmdir

原因：npm 在全局安装时，因为之前失败的安装残留了一个不为空的目录

解决办法：

# 先卸载
npm uninstall -g @tobilu/qmd

# 清除缓存
npm cache clean --force

# 重新安装
npm install -g @tobilu/qmd --force

2.3 定位 QMD 安装路径

运行以下命令找到 QMD 的完整路径：

npm list -g @tobilu/qmd

输出示例：

F:\app\nvm\nodejs\node_global
`-- @tobilu/qmd@2.0.1

2.4 验证 qmd.cmd 文件

检查该目录是否有 qmd 或 qmd.cmd 文件：

cd /d F:\app\nvm\nodejs\node_global
dir qmd*

尝试运行：

qmd.cmd --version

如果显示"系统找不到指定的路径"，说明 qmd.cmd 文件内部引用的路径是错误的。

查看 qmd.cmd 内容：

type qmd.cmd

输出示例（错误的）：

@ECHO off
GOTO start
:find_dp0
SET dp0=%~dp0
EXIT /b
:start
SETLOCAL
CALL :find_dp0

IF EXIST "%dp0%\/bin/sh.exe" (
  SET "_prog=%dp0%\/bin/sh.exe"
) ELSE (
  SET "_prog=/bin/sh"
  SET PATHEXT=%PATHEXT:;.JS;=;%
)

endLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & "%_prog%"  "%dp0%\node_modules\@tobilu\qmd\bin\qmd" %*

问题：qmd.cmd 文件是为 Unix/Linux 环境设计的，在尝试寻找 /bin/sh.exe，这在 Windows 上根本不存在。

2.5 创建正确的 Windows 版 qmd.cmd

首先验证 QMD 的实际位置：

dir "F:\app\nvm\nodejs\node_global\node_modules\@tobilu\qmd\bin"

直接运行测试：

node "F:\app\nvm\nodejs\node_global\node_modules\@tobilu\qmd\dist\cli\qmd.js" --version

应该显示：qmd 2.0.1

现在创建正确的 qmd.cmd 文件：

notepad F:\app\nvm\nodejs\node_global\qmd.cmd

删除所有内容，粘贴以下代码：

@echo off
node "F:\app\nvm\nodejs\node_global\node_modules\@tobilu\qmd\dist\cli\qmd.js" %*

2.6 测试新的 qmd.cmd

cd \
qmd --version

应该显示 qmd 2.0.1。如果成功，说明 PATH 配置正确。

2.7 为 OpenClaw 创建专用的 .bat 文件

在 OpenClaw 的工作区创建一个包装器：

notepad C:\Users\Administrator\.openclaw\workspace\qmd.bat

粘贴同样的内容：

@echo off
node "F:\app\nvm\nodejs\node_global\node_modules\@tobilu\qmd\dist\cli\qmd.js" %*

测试 .bat 文件：

C:\Users\Administrator\.openclaw\workspace\qmd.bat --version

---

第三步：配置 OpenClaw 与 QMD 集成

3.1 编辑 OpenClaw 配置文件

找到 OpenClaw 配置文件（通常位于）：

C:\Users\你的用户名\.openclaw\openclaw.json

用记事本打开，添加以下配置：

"memory": {
  "backend": "qmd",
  "qmd": {
    "command": "C:/Users/Administrator/.openclaw/workspace/qmd.bat",
    "scope": {
      "default": "allow"
    },
    "limits": {
      "maxResults": 6,
      "timeoutMs": 8000
    }
  }
}

关键配置说明：

配置项	说明
backend: "qmd"	切换到 QMD 记忆后端
scope.default: "allow"	🔑 关键，允许 QMD 搜索所有记忆文件，避免 qmd search denied by scope 错误
timeoutMs: 8000	超时设为 8 秒（默认 4 秒可能不够）
maxResults: 6	控制返回结果数量

3.2 初始化索引

C:\Users\Administrator\.openclaw\workspace\qmd.bat update --dir "C:\Users\Administrator\.openclaw\workspace"

3.3 创建集合

首先进入工作区目录：

cd C:\Users\Administrator\.openclaw\workspace

然后创建集合：

qmd.bat collection add . --name workspace

命令说明：

• collection add：创建新集合的命令
• .：表示当前目录（你的 workspace 目录）
• --name workspace：给这个集合起个名字叫 “workspace”

3.4 验证集合创建

qmd.bat collection list

3.5 更新索引

qmd.bat update --dir "C:\Users\Administrator\.openclaw\workspace"

成功输出示例：

Updating 1 collection(s)...
Indexed: X new, X updated, X unchanged, X removed
✓ All collections updated.

第四步：判断 OpenClaw 是否使用 QMD

4.1 启动观察日志

重启 OpenClaw 服务，仔细观察启动日志：

openclaw gateway restart
openclaw gateway logs --tail 50

成功标志：如果 QMD 正常工作，你应该能看到类似这样的日志：

[memory] qmd memory backend initialized
[memory] qmd collection ready: workspace (7 files)
[memory] qmd startup update completed in 0.5s
[memory] qmd memory service started

4.2 通过对话行为测试

测试步骤：

1. 在 OpenClaw 中与 AI 聊天，随便聊一些内容
2. 聊完后等待几分钟（让记忆被保存）
3. 关闭并重新打开 OpenClaw（确保是新会话）
4. 问一个与刚才聊天相关的问题，例如：
   • “我们刚才聊了什么？”
   • “你还记得我提到过…吗？”

⚠️ 问题 2：OpenClaw 没有调用 QMD

症状：日志中没有 QMD 相关信息，或显示 switching to builtin index

根本原因：OpenClaw 无法在 PATH 中找到 qmd 命令

解决方案：将 QMD 目录添加到 PATH

第一步：确认 qmd.cmd 的位置

dir F:\app\nvm\nodejs\node_global\qmd*

第二步：将目录添加到 PATH

1. 按下 Win + R，输入 sysdm.cpl 回车
2. 点击"高级" → “环境变量”
3. 编辑 Path 变量：
   • 在"系统变量"列表中找到 Path，选中后点击"编辑"
   • 点击"新建"添加路径：F:\app\nvm\nodejs\node_global
   • 点击"确定"保存所有窗口

第三步：验证 PATH 添加成功

必须关闭所有已打开的命令行窗口，然后新开一个，再运行：

# 测试 PATH
echo %PATH%

# 测试 qmd 命令
where qmd

⚠️ 问题 3：CMD 和 PowerShell 行为不一致

现象：

CMD 测试（✅ 成功）：

C:\Users\Administrator>where qmd
F:\app\nvm\nodejs\node_global\qmd
F:\app\nvm\nodejs\node_global\qmd.cmd
C:\Users\Administrator\.bun\bin\qmd.exe

C:\Users\Administrator>qmd --version
qmd 2.0.1

PowerShell 测试（❌ 失败）：

PS C:\Windows\system32> where qmd
PS C:\Windows\system32> qmd --version
& : 无法将“/bin/sh.exe”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如果包括路径，请确保路径
正确，然后再试一次。
所在位置 F:\app\nvm\nodejs\node_global\qmd.ps1:24 字符: 7
+     & "/bin/sh$exe"  "$basedir/node_modules/@tobilu/qmd/bin/qmd" $arg ...
+       ~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (/bin/sh.exe:String) [], CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException

根本原因

PowerShell 和 CMD 的命令执行优先级不同：

工具	执行优先级
CMD	.bat / .cmd > .exe > 其他
PowerShell	.ps1 > .exe > .bat / .cmd

PowerShell 优先执行 qmd.ps1，而这个文件是为 Unix 环境设计的，导致失败。

解决方案：修改 PowerShell 的执行优先级

让 PowerShell 优先使用 qmd.cmd，重命名 qmd.ps1：

# 重命名 qmd.ps1，这样 PowerShell 就找不到它了
Rename-Item "F:\app\nvm\nodejs\node_global\qmd.ps1" "F:\app\nvm\nodejs\node_global\qmd.ps1.bak"

# 测试是否生效
PS C:\Windows\system32> qmd --version
qmd 2.0.1

✅ 成功！现在 PowerShell 也能正常使用 QMD 了。

第五步：最终配置修改

5.1 修改 OpenClaw 配置

编辑 C:\Users\Administrator\.openclaw\openclaw.json，将 memory 部分改为：

"memory": {
  "backend": "qmd",
  "qmd": {
    "command": "qmd.exe",
    "scope": {
      "default": "allow"
    },
    "limits": {
      "maxResults": 6,
      "timeoutMs": 8000
    }
  }
}

为什么这样改：

• qmd.exe 让 OpenClaw 通过系统 PATH 找到命令
• 避免了之前路径解析丢失反斜杠的问题
• OpenClaw 会自动调用正确的 qmd.cmd 版本

5.2 重启 OpenClaw 服务

# 重启服务
openclaw gateway restart

# 查看日志
openclaw gateway logs

观察日志输出，关键要看：

• ✅ 不再有 qmd update failed 错误
• ✅ 不再有 switching to builtin index 提示
• ✅ 应该看到 [memory] qmd memory backend initialized 或类似成功信息

总结

完成以上步骤后，OpenClaw 的 QMD 记忆系统应该能够正常工作。

关键要点：

1. 使用 npm 而不是 Bun 安装 QMD
2. 创建正确的 Windows 版 qmd.cmd 文件
3. 将 QMD 目录添加到系统 PATH
4. 重命名 qmd.ps1 以避免 PowerShell 冲突
5. 在 OpenClaw 配置中设置 scope.default: "allow"
6. 使用 qmd.exe 作为命令引用

真是太不容易了，差点崩溃啊，还好还好最终还是配置成功了。