OpenClaw 启用 QMD 记忆后端：混合检索（BM25+向量）与重排落地指南

背景：为什么要折腾 OpenClaw 的记忆检索后端

OpenClaw 的“记忆”（Memory）本质上是让代理在回答前，能从你的长期笔记里检索到相关片段并引用，从而减少“失忆”和重复沟通成本。默认后端通常能用，但当你的 MEMORY.md、daily notes（memory/**/*.md）逐渐变多后，你会遇到两个典型问题：要么检索命中不稳定（语义像但关键词不对），要么命中内容杂（关键词命中但语义不相关）。

这篇文章给出一套通用落地流程：把 OpenClaw 的 memory_search 检索后端从内置实现切换到 QMD sidecar，实现“关键词 BM25 + 向量语义 + 重排 rerank”的混合检索，并保留可灰度、可回退的运维路径。

官方/指南入口（强烈建议对照阅读，后续也会引用其中关键点）：

AI-Skills：OpenClaw 启用 QMD 记忆后端指南（混合检索 + 重排）

为什么用 QMD（实验性）：它解决的不是“有没有”，而是“好不好用”

QMD 的价值在于：把检索拆成更可靠的三段式链路。

• BM25（关键词）：对专有名词、命令、报错文本非常稳；
• 向量语义（embedding）：对“描述相近但关键词不完全一致”的内容更友好；
• 重排（rerank）：在候选集合里把真正相关的片段排前面，减少“看似命中但没用”的噪声。

但你必须知道：在 OpenClaw 文档中，QMD 标记为 experimental（实验性）。这意味着它可能在版本升级时出现行为变化（模型下载、索引结构、性能参数等）。所以本文强调：先灰度跑通，再逐步调优；同时要保留“随时一键回退”的开关。

一键让 OpenClaw 自助部署（可复制提示词）

如果你习惯“让代理自己做运维”，下面这段提示词可以直接丢给 OpenClaw（或你日常用的代理执行环境）。它会按顺序完成：检查 OpenClaw 状态 → 安装 QMD → 修改配置 → 重启 gateway → 按 XDG 对齐构建索引 → 验证与回退预案。

请注意：这段提示词会涉及安装依赖与编辑配置文件，属于“会改系统状态”的操作。建议你明确要求代理在执行每个命令前先展示命令并等待你确认。

你是我的 OpenClaw 运维助手。目标：把 OpenClaw 的 memory backend 切换为 QMD（混合检索 + rerank），要求可回退、可验证、不要泄露任何凭证。

执行策略：
1) 每一步先输出你准备执行的命令/修改点，等待我确认后再执行；
2) 不要编造不存在的 openclaw CLI 子命令；只在确认存在时才使用；
3) 所有路径以当前用户的 ~/.openclaw 为默认 state dir；如检测到自定义 OPENCLAW_STATE_DIR，要按实际值处理；
4) 遇到下载模型/首次初始化慢要提示我耐心等待；遇到失败要给出可复制的排障命令。

你需要完成：
A. 检查 OpenClaw：执行 openclaw gateway status（如可用），并说明当前 gateway 运行状态；
B. 安装 QMD CLI：优先 npm i -g @tobilu/qmd；若环境无 npm，再给 bun 方案；安装后验证 qmd --help 与 qmd status；
C. 备份并编辑 ~/.openclaw/openclaw.json：新增/修改 memory.backend=qmd，并配置 searchMode=query、update.interval=5m、limits.timeoutMs=4000、maxResults=6；
D. 重启：执行 openclaw gateway restart；
E. 读取 openclaw memory status（如存在该命令），从输出里确认 QMD 的 Store 路径/agentId，并把 QMD 的 XDG_CONFIG_HOME/XDG_CACHE_HOME 对齐到 ~/.openclaw/agents/<agentId>/qmd/xdg-config 与 xdg-cache；
F. 在对齐后的 XDG 目录里执行：qmd collection add（为 memory/**/*.md 与 MEMORY.md 建 collection）→ qmd update → qmd embed；
G. 最后再次执行 openclaw memory status，确认 Indexed > 0，并给一条最小化回退方案：注释/删除 memory.backend=qmd 后再 openclaw gateway restart。

如果你更喜欢手动可控（尤其是在服务器上），继续看下一节。

手动部署步骤（跨发行版通用）

第 0 步：前置假设与“可回退”准备

你需要已安装并能使用 OpenClaw，至少能确认 gateway 的状态管理命令可用：

openclaw gateway status

在修改任何配置前，建议先备份：

cp -a ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%F-%H%M%S) 2>/dev/null || true

第 1 步：安装 QMD CLI（推荐 npm；备用 bun）

方式 A：npm（通用，推荐）

npm i -g @tobilu/qmd

方式 B：bun（部分环境更顺）

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

安装完成后验证：

qmd --help
qmd status

如果 qmd / node-llama-cpp 提示需要从源码编译（无预编译包），你需要补齐编译工具链（下面按发行版列出常用包名）。

第 2 步：补齐编译工具链（按发行版）

Debian / Ubuntu：

sudo apt-get update -y
sudo apt-get install -y git build-essential cmake pkg-config

RHEL / CentOS / Fedora：

sudo dnf install -y git gcc gcc-c++ make cmake pkgconfig

Alpine：

sudo apk add --no-cache git build-base cmake pkgconf python3

Arch：

sudo pacman -Syu --noconfirm git base-devel cmake pkgconf

第 3 步：启用 OpenClaw 的 QMD 后端（修改 openclaw.json）

编辑 ~/.openclaw/openclaw.json，在合适的位置加入/修改以下配置（保持为合法 JSON，不要加注释）：

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

第 4 步：重启 gateway，让配置生效

使用 OpenClaw 内置命令重启 gateway：

openclaw gateway restart

第 5 步：对齐 XDG（关键步骤），然后构建 QMD 索引

这一步是全流程最容易踩坑的地方：OpenClaw 在跑 QMD 时会“改写/指定”QMD 的 XDG 目录，而你在 shell 里手动运行 qmd 时，默认会写到 ~/.cache/qmd/...。如果两边不对齐，就会出现“OpenClaw 读不到你刚建的索引”，表现为 Indexed=0 或 unable to open database file。

先查看（若你的环境提供该命令）：

openclaw memory status

然后在同一套 XDG 目录下执行 collection/update/embed（把 <agentId> 替换为你 status 输出中的值）：

STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
AGENT_ID="<agentId>"

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

# （可选）稳定优先：强制 CPU-only
export NODE_LLAMA_CPP_GPU=false

qmd collection add "$STATE_DIR/workspace/memory" --name memory-root --mask "**/*.md" || true
qmd collection add "$STATE_DIR/workspace" --name memory-long --mask "MEMORY.md" || true

qmd update
qmd embed

验证与回退（灰度上线的关键）

验证：确认 OpenClaw 已切到 QMD 且 Indexed > 0

重启并完成 qmd embed 后，再看一次状态（若命令可用）：

openclaw memory status

回退：随时切回内置后端（最小化改动）

任何时候想回退到 builtin（或暂时禁用 QMD），做两件事：

1. 编辑 ~/.openclaw/openclaw.json：删除或注释掉 "memory": { "backend": "qmd", ... }；
2. 重启 gateway：

openclaw gateway restart

迁移：换机器/换环境时怎么带走 QMD 记忆能力

迁移时要分清两层：

• 事实源（必须迁移）：workspace 里的 MEMORY.md 与 memory/**/*.md；
• 索引（可迁移，但不强依赖）：QMD 在 ~/.openclaw/agents/<agentId>/qmd/xdg-cache 里的 SQLite/缓存。

免责声明

本文涉及的 QMD 记忆后端在 OpenClaw 生态中属于实验性能力，可能随版本更新出现行为变化。请优先在可回退、可验证的灰度方式下启用，并在生产/长期运行环境中自行评估风险与维护成本。