OpenClaw QMD 安装、配置指南

2026年3月6日 · 阅读需 9 分钟

QMD 是 Shopify 创始人 Tobi Lütke 开发的本地语义搜索引擎，专为 AI Agent 设计。本指南介绍在 OpenClaw 中启用 QMD 记忆后端的完整安装与配置流程。

最后修订：2026-03-06

QMD 简介

QMD 是 Shopify 创始人 Tobi Lütke 开发的本地语义搜索引擎，专为 AI Agent 设计（GitHub - tobi/qmd）。它采用三层混合搜索机制：BM25 关键词匹配 + 向量语义搜索 + LLM 重排序。

启用 QMD 后：无论历史记录有多长，每次只提取最相关的几句话（通常削减 95% 以上）。

✅ 响应快了 5–50 倍
✅ 成本降低 90–99%
✅ 精准度反而更高（因为噪音少了）
✅ 再也不会因为上下文太长而卡死或超时

前置条件

OpenClaw 版本 ≥ 2026.2.2
Bun 运行时（推荐）或 Node.js 22+
SQLite 支持扩展的版本（macOS 需 brew install sqlite）
QMD 默认为禁用，需在配置中显式设置 memory.backend = "qmd" 才启用
确保 qmd 二进制在运行 OpenClaw Gateway 的环境的 PATH 上（否则会自动回退到内置 SQLite）

整体流程概览

预下载模型（可选）→ 安装 QMD → 配置 XDG 目录 → 迁移模型（可选）
        ↓
配置 OpenClaw（openclaw.json，memory.backend = "qmd"）并重启 Gateway
        ↓
Gateway 启动后自动创建集合（如 memory-root）、按配置做索引（如 onBoot）
        ↓
验证 qmd status / 可选手动 qmd update && qmd embed / 搜索测试

一、预下载模型

在安装 QMD 之前，若网络受限或希望离线部署，可先将三个 GGUF 模型下载到默认缓存目录（如 /root/.cache/qmd/models/ 或 ~/.cache/qmd/models/）。

模型：向量嵌入（embeddinggemma-300M）、重排序（qwen3-reranker-0.6b）、查询扩展（qmd-query-expansion-1.7B）。
目录：未设置 XDG_CACHE_HOME 时，root 用户即为 /root/.cache/qmd/models/。

操作：按 CPU 环境下 QMD 所需 GGUF 模型安装中的方式（huggingface-cli 或浏览器/wget）下载三个 .gguf 文件到该目录。文件名可为带 hf_ 前缀或简短名，QMD/node-llama-cpp 会按需解析。

若跳过本步，QMD 首次运行 qmd embed 或首次搜索时会自动从 HuggingFace 下载并缓存。

二、安装 QMD

1. 安装 Bun（如未安装）

# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell 管理员)
powershell -c "irm bun.sh/install.ps1 | iex"

2. CPU 模式（无 NVIDIA GPU 或仅用 CPU）

若机器没有 NVIDIA GPU，或希望强制使用 CPU，应在安装 QMD 之前设置环境变量：

export NODE_LLAMA_CPP_CUDA=false

持久生效可写入 ~/.bashrc 或 ~/.zshrc：

echo 'export NODE_LLAMA_CPP_CUDA=false' >> ~/.bashrc
source ~/.bashrc

3. 安装 QMD CLI

任选一种方式即可：

方式一：使用 Bun（推荐）

bun install -g https://github.com/tobi/qmd

方式二：使用 npm

需已安装 Node.js 22+，然后全局安装官方 npm 包：

npm install -g @tobilu/qmd

npm 全局安装后，可执行文件通常在 npm root -g 的父级下的 bin（如 /usr/local/bin 或 $HOME/.nvm/versions/node/.../bin）。若系统已正确配置 Node/npm，一般无需额外设置 PATH。
若终端中找不到 qmd，可把 npm 的 global bin 目录加入 PATH，例如：
```
export PATH="$(npm config get prefix)/bin:$PATH"
```

方式三：直接运行（无需安装）

npx @tobilu/qmd ...

4. 验证安装

# 如使用 Bun 安装，确保 Bun 的 bin 在 PATH 中
export PATH="$HOME/.bun/bin:$PATH"

# 如使用 npm 安装且找不到 qmd，可先执行：
# export PATH="$(npm config get prefix)/bin:$PATH"

qmd --version
qmd --help

三、配置 XDG 目录（指向 OpenClaw 路径）

与 OpenClaw 联用时，需让手动执行的 QMD 与 Gateway 调起的 QMD 使用同一套索引与模型，因此将 XDG 指向 OpenClaw 的 agent 目录：

STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
AGENT_ID="main"   # 替换为你的 agent ID

export XDG_CONFIG_HOME="$STATE_DIR/agents/$AGENT_ID/qmd/xdg-config"
export XDG_CACHE_HOME="$STATE_DIR/agents/$AGENT_ID/qmd/xdg-cache"

XDG_CONFIG_HOME：QMD 的集合与配置（如 qmd/ 下的配置）。
XDG_CACHE_HOME：QMD 的索引与模型缓存（qmd/index.sqlite、qmd/models/）。

后续所有 qmd 命令（status、collection、update、embed、query）均应在已设置上述两个环境变量的同一 shell 中执行。

四、迁移模型文件

若你已在默认目录（如 /root/.cache/qmd/models/）预下载了 GGUF 模型，需要把它们放到 OpenClaw 使用的缓存目录，否则 Gateway 调起的 QMD 找不到模型：

TARGET="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/qmd/xdg-cache/qmd/models"
mkdir -p "$TARGET"
cp /root/.cache/qmd/models/*.gguf "$TARGET/"
# 或使用软链：ln -s /root/.cache/qmd/models/*.gguf "$TARGET/"

确保三个模型（嵌入、重排序、查询扩展）的 .gguf 文件均在 $TARGET 下。

五、确认模型路径（可选）

QMD 通过 XDG_CACHE_HOME 确定模型目录，默认从 $XDG_CACHE_HOME/qmd/models/ 读取，无需单独创建 config.json。完成「三、配置 XDG 目录」和「四、迁移模型文件」后，模型路径即已正确。

若 QMD 官方后续支持通过配置文件显式指定本地模型路径，可参考 QMD 官方文档进行可选配置。

六、验证（qmd status）

在已设置 XDG_CONFIG_HOME、XDG_CACHE_HOME 的 shell 中执行：

qmd status

成功标志：能正常输出状态；若已建集合并做过索引，会看到 Indexed > 0。若需预热索引并触发首次模型加载，可接着执行：

qmd update && qmd embed
qmd query "test" -c memory-root --json >/dev/null 2>&1

七、集合（自动创建与命名）

在实际安装配置过程中，QMD 集合会由 OpenClaw 根据配置自动创建，并已使用固定集合名，例如：

memory-root：对应默认记忆路径下的 memory/**/*.md 等
memory-long：对应工作区根目录的 MEMORY.md

因此一般无需手动执行 qmd collection add。完成「三、配置 XDG 目录」并启动或配置 OpenClaw 后，集合即会就绪。

查看已有集合：

qmd collection list

确认列表中已有上述集合名后，即可进行索引与搜索；集合名（如 memory-root）在搜索时使用（-c memory-root）。

可选：手动补充集合（若需额外路径或 OpenClaw 未自动创建时）：

# 确保 STATE_DIR、AGENT_ID、XDG_* 已设置（见第三节）
WORKSPACE="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/workspace"   # 或你的实际 workspace 路径

qmd collection add "$WORKSPACE/memory" --name memory-root --mask "**/*.md"
qmd collection add "$WORKSPACE" --name memory-long --mask "MEMORY.md"

八、索引

集合由 OpenClaw 自动创建后，在相同 XDG 环境下更新文件索引并生成向量嵌入：

qmd update
qmd embed

首次运行 qmd embed 时，若未预先放置模型，会从 HuggingFace 自动下载 GGUF 模型。完成后再次执行 qmd status 应看到索引数量增加。

九、搜索

在相同 XDG 环境下测试检索：

# 混合搜索（BM25 + 向量 + 重排序，推荐）
qmd query "遗留问题" -c memory-root

# 关键词搜索（最快）
qmd search "遗留问题" -c memory-root

# 语义搜索
qmd vsearch "遗留问题" -c memory-root

能返回与「遗留问题」相关的片段即表示 QMD 与索引工作正常。

十、配置 OpenClaw 使用 QMD

1. 找到配置文件

操作系统	配置文件路径
macOS/Linux	`~/.openclaw/openclaw.json`
Windows	`C:\Users\<用户名>\.openclaw\openclaw.json`
Docker	`/home/node/.openclaw/openclaw.json`

2. 修改配置

基础配置（最小化）：

{
  "memory": {
    "backend": "qmd",
    "qmd": {
      "limits": {
        "timeoutMs": 8000
      }
    }
  }
}

完整配置（推荐）：

{
  "memory": {
    "backend": "qmd",
    "citations": "auto",
    "qmd": {
      "includeDefaultMemory": true,
      "command": "qmd",
      "searchMode": "search",
      "update": {
        "interval": "5m",
        "debounceMs": 15000,
        "onBoot": true,
        "waitForBootSync": false
      },
      "limits": {
        "maxResults": 6,
        "timeoutMs": 4000
      },
      "scope": {
        "default": "deny",
        "rules": [
          { "action": "allow", "match": { "chatType": "direct" } }
        ]
      }
    }
  }
}

配置说明：

backend: 切换到 QMD 记忆后端
citations: 自动添加引用来源（文件路径和行号）；与后端无关，QMD 与 SQLite 均适用
command: 可执行路径，默认 qmd，需在网关的 PATH 上
searchMode: 默认为 search（即 qmd search --json）；可选 vsearch、query。若当前 QMD 构建对某模式参数不支持，OpenClaw 会自动用 qmd query 重试
includeDefaultMemory: 为 true 时自动索引 MEMORY.md 与 memory/**/*.md（默认 true）
maxResults: 最多返回几条记忆片段（建议 3–6）
timeoutMs: 搜索超时（默认 4000ms，首次运行建议 8000ms）
interval: 自动重新索引间隔（默认 5 分钟）
waitForBootSync: 默认 false，启动时在后台刷新索引、不阻塞聊天；设为 true 则阻塞直到索引就绪

3. 重启 OpenClaw

openclaw gateway restart

Docker 环境：

docker compose restart

十一、验证 OpenClaw 侧

日志：openclaw logs --follow，看到 Using QMD memory backend 即表示已启用 QMD。
QMD 状态：在已设置 XDG 的 shell 中执行 qmd status，确认 Indexed > 0。
对话：在 OpenClaw 对话中输入「确认是否启用了 QMD，给出测试报告」，或询问已索引记忆中的具体信息，检查是否能正确召回。

十二、故障排查

问题	解决方案
`better-sqlite3` 编译失败	安装编译工具链：`sudo apt install build-essential cmake` (Linux) 或 Visual Studio + Windows SDK (Windows)
QMD 命令找不到	Bun：`export PATH="$HOME/.bun/bin:$PATH"`；npm：`export PATH="$(npm config get prefix)/bin:$PATH"`
Indexed = 0	检查 XDG 目录对齐，确保 OpenClaw 与手动运行的 QMD 使用相同的 XDG_CONFIG_HOME/XDG_CACHE_HOME；确认已执行 qmd collection add、qmd update、qmd embed
搜索超时	增加 `timeoutMs` 到 8000 或更高
首次搜索很慢	正常：QMD 首次运行会下载或加载 GGUF 模型，之后会快很多；可事先用相同 XDG 目录执行一次 `qmd query "test" -c memory-root --json` 预热
Windows 兼容性	官方建议通过 WSL2 运行；Bun + SQLite 装好后 macOS/Linux 开箱即用

十三、回退方案

如需回退到内置 SQLite 记忆系统：编辑 openclaw.json，删除或注释 memory.backend（或改为 "sqlite"），然后执行 openclaw gateway restart。

提示：当 QMD 子进程异常或 JSON 解析失败时，OpenClaw 会自动回退到内置 SQLite 管理器，记忆工具仍可用；诊断时可查看 status().backend（为 "qmd" 时表示当前由 QMD 提供结果）。

十四、参考链接

最后修订：2026-03-06

说明	链接
QMD 官方仓库	https://github.com/tobi/qmd
CPU 环境下 QMD 所需 GGUF 模型安装（手动/离线）	CPU 环境下 QMD 安装 GGUF 模型
OpenClaw Memory（向量记忆与 QMD 后端）	https://docs.openclaw.ai/concepts/memory#vector-memory-search

QMD 简介​

前置条件​

整体流程概览​

一、预下载模型​

二、安装 QMD​

1. 安装 Bun（如未安装）​

2. CPU 模式（无 NVIDIA GPU 或仅用 CPU）​

3. 安装 QMD CLI​

4. 验证安装​

三、配置 XDG 目录（指向 OpenClaw 路径）​

四、迁移模型文件​

五、确认模型路径（可选）​

六、验证（qmd status）​

七、集合（自动创建与命名）​

八、索引​

九、搜索​

十、配置 OpenClaw 使用 QMD​

1. 找到配置文件​

2. 修改配置​

3. 重启 OpenClaw​

十一、验证 OpenClaw 侧​

十二、故障排查​

十三、回退方案​

十四、参考链接​

相关内容推荐