1. OpenClaw 长会话为什么又慢又烧钱
如果你用 OpenClaw 跑过一周以上的长期会话，大概率遇到过这种情况：问一句「我们上个月讨论的那个方案最后怎么定的」，它先愣十几秒，然后要么超时失败，要么吐出一堆和问题无关的历史内容，账单还悄悄涨上去了。这不是模型不行，而是记忆检索方式出了问题。
OpenClaw 默认的记忆后端会把整个 MEMORY.md 或历史会话文件直接塞进上下文。一个运行一周的会话，历史轻松超过 1 万 token，跑一个月可能到 10 万 token 级别。大模型的推理时间和输入 token 数量基本成正比，上下文从 2000 token 涨到 50000 token，响应时间会从 5 秒级跳到 1-2 分钟，而且长上下文里 90% 的内容和当前问题无关，模型容易被噪音干扰，精准度反而下降。
QMD（Quantum Memory Database）是 Shopify 联合创始人 Tobi Lütke 开发的本地语义搜索引擎，核心思路很简单：不要把整个文件塞给 AI，而是先用本地搜索找到最相关的 2-3 句话，再把这些精准片段传给模型。它基于 TypeScript + Bun 开发，用 node-llama-cpp 跑本地 GGUF 模型，三层混合检索（BM25 全文 + 向量语义 + LLM 重排序），完全离线运行，不消耗任何 API 配额。
实测下来，启用 QMD 后 token 削减普遍在 90% 以上，响应速度提升 5-50 倍，单次请求成本能降一到两个数量级。这篇就按「装 QMD → 配 OpenClaw → 验证生效 → 排障」的顺序，把可复制的配置和踩坑点讲清楚。适合已经在用 OpenClaw、会话历史超过 1 万 token、或者被慢响应和超时困扰的人。
2. 装 QMD 之前：OpenClaw 版本与前置检查
QMD 作为 OpenClaw 的记忆后端 Skill，对版本有硬性要求：OpenClaw 需要 ≥ 2026.2.2。低于这个版本，配置文件里的memory.backend: "qmd"不会被识别，重启后仍然走内置 SQLite，你会以为配了但实际没生效。
先确认版本：
openclaw --version如果输出低于 2026.2.2，先升级到最新版再往下走。升级方式取决于你的安装渠道，用官方安装脚本或包管理器更新即可，这里不展开。
第二个前置是 SQLite 需要支持 vector 扩展。QMD 的向量检索依赖 SQLite 的 vector 能力，系统自带的 SQLite 版本太老会直接报错。验证命令：
sqlite3 --version版本号需要 ≥ 3.40.0。macOS 用户如果版本偏低，用brew install sqlite装新版；Ubuntu/Debian 用sudo apt update && sudo apt install sqlite3；Windows 去 SQLite 官网下载sqlite-tools-win-x64-*.zip，解压到比如C:\sqlite，然后把该目录加进系统 PATH，重启终端再验证。
注意：Windows 上加 PATH 后一定要重开终端，旧终端不会刷新环境变量，这是最常见的「明明装了却找不到 sqlite3」的原因。
3. 安装 QMD 与 Skill 配置骨架
3.1 安装 QMD 本体
推荐用 Bun，安装速度快：
bun install -g @tobilu/qmd没有 Bun 就用 npm：
npm install -g @tobilu/qmd不想全局安装也可以直接跑：
npx @tobilu/qmd --help # 或 bunx @tobilu/qmd --help装完验证：
qmd --version能打印版本号就说明本体就绪。首次运行会下载本地模型（GGUF 格式，几百 MB），这一步需要联网，之后完全离线。
3.2 OpenClaw 的 settings.json / openclaw.json 片段
OpenClaw 的配置文件位置按系统和版本略有差异：
macOS / Linux：~/.openclaw/openclaw.jsonWindows：C:\Users\你的用户名\.openclaw\openclaw.json
在配置文件里加入或修改 memory 段：
{ "memory": { "backend": "qmd", "qmd": { "limits": { "timeoutMs": 8000 } } } }两个关键参数：
| 参数 | 作用 | 建议值 |
|---|---|---|
backend | 切换记忆后端为 QMD | "qmd" |
timeoutMs | 单次检索超时时间 | 8000（默认 4000 偏短） |
timeoutMs默认 4 秒，在文件多、首次建索引的场景下容易超时，调到 8000 更稳。如果你的知识库文件特别多（几百个 md），可以再往上加到 12000，但别无限拉大，否则真出问题时你会等很久才看到回退。
3.3 Skill 配置骨架
如果你是通过 Skill 机制挂载 QMD，Skill 描述文件（通常放在 OpenClaw 的 skills 目录下）骨架大致如下，重点是声明它作为 memory backend 的检索入口：
{ "name": "qmd-memory", "version": "1.0.0", "description": "本地语义搜索引擎，作为 OpenClaw 记忆后端", "entry": "qmd", "type": "memory-backend", "config": { "indexPaths": [ "~/.openclaw/memory", "~/notes" ], "topK": 3, "hybrid": true } }indexPaths指向你要索引的 Markdown / 文本目录，topK控制每次返回的片段数（2-3 条通常够用），hybrid: true开启 BM25 + 向量 + 重排序的混合检索。纯语义检索实测精准度只有 59% 左右，混合检索能到 93%，所以这个开关别关。
4. 重启、验证与成功结果确认
配置改完必须重启 OpenClaw Gateway 才生效：
openclaw gateway restart重启后 OpenClaw 会自动用 QMD 做记忆检索。如果 QMD 出问题，它会自动回退到内置 SQLite，不会让整个服务挂掉，这点设计得比较稳。
验证是否真的切过去了，跟日志：
openclaw logs --follow看到类似Using QMD memory backend的日志行，说明配置成功。如果还是Using SQLite memory backend，说明配置没被读到，回到第 5 节排查。
进一步做一次实际检索验证。先手动建索引，确认 QMD 能扫到你的文件：
qmd index ~/.openclaw/memory然后跑一次查询：
qmd search "项目最终采用的方案" --top 3正常输出应该是 2-3 条最相关的片段，每条带来源文件和相似度分数，而不是把整个文件倒出来。如果这一步能出精准片段，OpenClaw 里的检索就基本没问题了。
成功后的体感变化：问历史相关问题时，响应从几十秒降到 1-3 秒；长会话不再因为上下文过长而超时；单次请求的 token 消耗肉眼可见地下降。你可以对比启用前后同一个问题的响应时间和日志里的 token 数，差距通常很明显。
5. 本篇常见错排查
报错一：qmd: command not found全局安装后 PATH 没生效。Bun 的全局 bin 目录通常在~/.bun/bin，npm 在 npm 的 global prefix 下。确认该目录在 PATH 里，或者直接用bunx @tobilu/qmd绕过。
报错二：SQLite vector extension not available系统 SQLite 版本低于 3.40.0，或者装的是不带扩展的精简版。按第 2 节重装 SQLite，装完sqlite3 --version确认版本，再重启 OpenClaw。
报错三：日志里仍是Using SQLite memory backend三种可能：OpenClaw 版本低于 2026.2.2；配置文件路径不对（Windows 用户容易把文件放到错误盘符）；JSON 格式有语法错误导致整段被忽略。用openclaw --version和 JSON 校验工具各查一遍。
报错四：检索超时频繁回退timeoutMs太小或索引文件过多。先把timeoutMs调到 8000-12000，再检查indexPaths是否误包含了超大目录（比如整个 home 目录），把范围收窄到真正的记忆和笔记目录。
报错五：首次搜索特别慢首次运行要下载 GGUF 模型并建索引，慢是正常的。模型下载完成后，后续检索都在本地，1-3 秒内出结果。如果每次都慢，检查是不是每次都在重建索引。
报错六：想临时关掉 QMD把配置改回"backend": "sqlite"，重启 Gateway 即可。要彻底卸载再跑bun uninstall -g @tobilu/qmd或npm uninstall -g @tobilu/qmd。
6. 把 QMD 接进你的 OpenClaw 工作流
QMD 解决的是「记忆检索」这一层的效率问题，它不替代模型本身，也不替代你的编辑器，只是让每次请求带上的上下文从「整本历史」变成「最相关的几句话」。落地顺序建议是：先确认 OpenClaw 版本和 SQLite 版本达标，再装 QMD 本体，然后改openclaw.json的 memory 段，重启后跟日志确认后端切换成功，最后用qmd search手动验证检索质量。
如果你还在选模型和配 Key 的阶段，可以先用模型对话页面把常用模型跑通，确认调用链路正常；等进入长期编码或 Agent 场景、会话历史开始膨胀时，再按这篇把 QMD 挂上。接入相关的 Key 管理和文档入口在这里：
- 模型对话：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=model_chat
- API Keys：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api_keys
- 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc
- Coding Plan（长期编码 / Agent 场景）：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding_plan
- API 端点：https://taotoken.net/api
一个实用技巧：QMD 的indexPaths不要贪多，先把~/.openclaw/memory这一个目录跑顺，确认检索质量后再逐步加笔记目录。索引范围越大，首次建索引越慢，超时风险也越高。另外topK保持 3 左右就够，返回片段太多等于又把上下文撑大了，反而抵消了 QMD 的收益。
