OpenClaw AI助手入门教程-配置QMD记忆系统，优化反馈速度
说明
- 你是否遇到过这样的困扰：刚开始用OpenClaw时响应还挺快，聊了几轮后速度越来越慢，最后甚至卡死？更糟心的是，API账单还在蹭蹭往上涨，仿佛在为一个“失忆”的AI付高额账单。这背后的罪魁祸首，往往是上下文爆炸——每次对话都携带大量无关历史记录，让AI花大量时间“阅读理解”，既耗钱又降速。
别担心，从OpenClaw 2026.2.2版本开始，内置的QMD记忆系统完美解决了这个问题。本文将带你从零开始，一步步配置QMD，让你的AI助手响应速度从“蜗牛”变“猎豹”。
- 为什么你的OpenClaw越来越慢？
1.1 传统记忆系统的痛点
传统的记忆机制，简单粗暴——把整个MEMORY.md文件或完整的对话历史，一股脑全塞给AI。这导致几个严重问题：
上下文越长，速度越慢：大模型的推理时间与输入token数量成正比。5000 token的请求要等8-15秒，20000 token直接奔着1分钟去了
成本指数级增长：一个20000 token的会话，单次请求成本可能高达数美元，如果频繁调用，月账单令人心惊
容易卡死超时：当上下文累积到8万、10万token时，请求很容易超时失败，钱花了，结果却没得到
噪音干扰精度：塞入大量无关信息，反而会让AI“分心”，回答质量下降
1.2 QMD是什么？
QMD（Quantum Memory Database）是由Shopify联合创始人Tobi Lütke开发的本地语义搜索引擎，专为AI Agent场景设计。
它的核心思路是：不要把整个文件塞给AI，而是先用本地搜索找到最相关的片段（通常只需2-3句话），再把精准内容传给AI。
技术原理上，QMD采用三层混合搜索机制，确保检索精准度：
层级 技术 作用
第一层 BM25全文搜索 精准匹配关键词，类似传统搜索引擎
第二层 向量语义搜索 理解语义相似度，能找到意思相近但用词不同的内容
第三层 LLM重排序 用AI对结果二次优化，确保最相关内容排前面
这种混合搜索模式能将精准度提升至93%，而纯语义搜索只有59%
- 注意：qmd的query功能，需要有GPU支持才比较顺畅，CPU下很慢不建议使用。cpu下使用search即可
openclaw自安装：
- 我们直接利用openclaw自动帮我们完整部署，web-ui的chat发指令:
为openclaw配置QMD记忆系统，优化反馈速度
- 通过这个指令，应该能让openclaw自己完成安装，配置和重启openclaw
- 同时openclaw会给出一个测试报告
- 使用docker安装，这个方法可能不一定成功安装，可以参考手工安装。
- OpenClaw 会自动使用 QMD 进行记忆检索，如果 QMD 出现问题，会自动回退到内置的 SQLite 记忆系统，不影响正常使用
手工安装
- 最好是有vpn，要不下载模型容易失败，只能采用手工下载比较麻烦
- root方式进入容器
docker compose exec --user root -it openclaw-gateway bash
- 安装依赖
#QMD 需要支持 vector 扩展的 SQLite
apt update && apt install jq sqlite3
#测试生效
sqlite3 --version
- 安装qmd
#方法1：
bun install -g @tobilu/qmd
#方法2：自动先安装qmd
npx @tobilu/qmd ...
#方法3：
# 使用 npm 安装
npm install -g @tobilu/qmd
#安装后添加到PATH路径
echo "export PATH=$PATH:/home/node/.bun/bin" >> ~/.bashrc
#测试生效
qmd --version
#保证目录权限
mkdir -p /home/node/.cache/qmd
chown -R node:node /home/node/.cache/qmd
chown -R node:node /home/node/.bun/install/global/node_modules/node-llama-cpp
- 普通用户方式进入容器
docker compose exec -it openclaw-gateway bash
#如果不带GPU，基于源码安装CUP支持的node-llama-cpp版本
NODE_LLAMA_CPP_SKIP_DOWNLOAD=true npm install node-llama-cpp
#测试建立索引
$ ~/.bun/bin/qmd update --verbose
Updating 1 collection(s)...
[1/1] workspace (**/*.md)
Collection: /home/node/.openclaw/workspace (**/*.md)
Indexing: 206/206 ETA: 0s
Indexed: 197 new, 9 updated, 0 unchanged, 0 removed
Cleaned up 9 orphaned content hash(es)
✓ All collections updated.
Run 'qmd embed' to update embeddings (193 unique hashes need vectors)
#为索引的文档生成向量
HF_ENDPOINT=https://hf-mirror.com ~/.bun/bin/qmd embed --verbose
............
QMD Warning: cuda reported available but failed to initialize. Falling back to CPU.
QMD Warning: no GPU acceleration, running on CPU (slow). Run 'qmd status' for details.
Downloading to ~/.cache/qmd/models
⏵ hf_ggml-org_embeddinggemma-300M-Q8_0.gguf 86.03% (282.69MB/328.58MB) 1.22MB/s | 37s left
#测试关键词搜索
~/.bun/bin/qmd search "关键词" # 关键词搜索
#测试语义搜索
HF_ENDPOINT=https://hf-mirror.com ~/.bun/bin/qmd query "你的测试关键词" # 语义搜索（推荐）
.......
QMD Warning: cuda reported available but failed to initialize. Falling back to CPU.
QMD Warning: no GPU acceleration, running on CPU (slow). Run 'qmd status' for details.
Downloading to ~/.cache/qmd/models
⏵ hf_tobil_qmd-query-expansion-1.7B-q4_k_m.gguf 60.29% (773.28MB/1.28GB) 1.17MB/s | 7m left
#模型下载路径在容器内~/.cache/qmd/models下，名称为。
hf_tobil_qmd-query-expansion-1.7B-q4_k_m.gguf
hf_ggml-org_embeddinggemma-300M-Q8_0.gguf
hf_ggml-org_qwen3-reranker-0.6b-q8_0.gguf
#也可以单独下载放在对应的目录下，为了避免重启容器丢失
mkdir -p ~/.openclaw/qmd/
mv ~/.cache/qmd/models ~/.openclaw/qmd/
ln -s ~/.openclaw/qmd/models ~/.cache/qmd/models
#把HF_ENDPOINT=https://hf-mirror.com加到bashrc
echo "export HF_ENDPOINT=https://hf-mirror.com" >> ~/.bashrc
参考的整合流程：
- 检查OpenClaw版本，需要大于2026.2.2
$ docker compose exec openclaw-gateway node dist/index.js --version
2026.2.9
- 备份openclaw.json配置
cd ~/.openclaw/
cp openclaw.json openclaw.json.backup
- 修改openclaw配置，添加内容
"hooks": {
"internal": {
"enabled": true,
"entries": {
"session-memory": {
"enabled": true
}
}
}
},
"memory": {
"backend": "qmd",
"citations": "auto",
"qmd": {
"includeDefaultMemory": true,
"update": {
"interval": "5m",
"debounceMs": 15000
},
"limits": {
"maxResults": 6,
"timeoutMs": 4000
},
"scope": {
"default": "deny",
"rules": [
{
"action": "allow",
"match": {
"chatType": "direct"
}
}
]
}
}
},
- 关键配置项说明：
backend: "qmd"：这一行告诉 OpenClaw 使用 QMD 作为记忆后端，是启用一切的前提 。
includeDefaultMemory: true：建议保留为 true。这样 QMD 除了索引你指定的额外路径外，仍然会索引默认的 MEMORY.md 和 memory/ 目录，确保你的核心记忆不受影响 。
paths 数组：这是指定额外“内存文件”的关键。
你可以填入绝对路径或相对于当前工作空间的路径 。
如果填入的是目录，QMD 会递归扫描该目录下所有的 .md (Markdown) 文件并建立索引 。
你也可以直接填入一个具体的 .md 文件路径，让 QMD 只索引这一个文件。
- 重启openclaw
cd openclaw
docker compose restart
- 验证是否启用，在web-ui的chat发指令：
确认是否启用了qmd给出测试报告
qmd帮助文档
$ qmd -h
qmd — Quick Markdown Search
Usage:
qmd <command> [options]
Primary commands:
qmd query <query> - Hybrid search with auto expansion + reranking (recommended)
qmd query 'lex:..\nvec:...' - Structured query document (you provide lex/vec/hyde lines)
qmd search <query> - Full-text BM25 keywords (no LLM)
qmd vsearch <query> - Vector similarity only
qmd get <file>[:line] [-l N] - Show a single document, optional line slice
qmd multi-get <pattern> - Batch fetch via glob or comma-separated list
qmd skill show/install - Show or install the packaged QMD skill
qmd mcp - Start the MCP server (stdio transport for AI agents)
Collections & context:
qmd collection add/list/remove/rename/show - Manage indexed folders
qmd context add/list/rm - Attach human-written summaries
qmd ls [collection[/path]] - Inspect indexed files
Maintenance:
qmd status - View index + collection health
qmd update [--pull] - Re-index collections (optionally git pull first)
qmd embed [-f] - Generate/refresh vector embeddings
qmd cleanup - Clear caches, vacuum DB
Query syntax (qmd query):
QMD queries are either a single expand query (no prefix) or a multi-line
document where every line is typed with lex:, vec:, or hyde:. This grammar
matches the docs in docs/SYNTAX.md and is enforced in the CLI.
Grammar:
query = expand_query | query_document ;
expand_query = text | explicit_expand ;
explicit_expand= "expand:" text ;
query_document = [ intent_line ] { typed_line } ;
intent_line = "intent:" text newline ;
typed_line = type ":" text newline ;
type = "lex" | "vec" | "hyde" ;
text = quoted_phrase | plain_text ;
quoted_phrase = '"' { character } '"' ;
plain_text = { character } ;
newline = "\n" ;
Examples:
qmd query "how does auth work" # single-line → implicit expand
qmd query $'lex: CAP theorem\nvec: consistency' # typed query document
qmd query $'lex: "exact matches" sports -baseball' # phrase + negation lex search
qmd query $'hyde: Hypothetical answer text' # hyde-only document
Constraints:
- Standalone expand queries cannot mix with typed lines.
- Query documents allow only lex:, vec:, or hyde: prefixes.
- Each typed line must be single-line text with balanced quotes.
AI agents & integrations:
- Run `qmd mcp` to expose the MCP server (stdio) to agents/IDEs.
- `qmd skill install` installs the QMD skill into ./.agents/skills/qmd.
- Use `qmd skill install --global` for ~/.agents/skills/qmd.
- `qmd --skill` is kept as an alias for `qmd skill show`.
- Advanced: `qmd mcp --http ...` and `qmd mcp --http --daemon` are optional for custom transports.
Global options:
--index <name> - Use a named index (default: index)
Search options:
-n <num> - Max results (default 5, or 20 for --files/--json)
--all - Return all matches (pair with --min-score)
--min-score <num> - Minimum similarity score
--full - Output full document instead of snippet
-C, --candidate-limit <n> - Max candidates to rerank (default 40, lower = faster)
--line-numbers - Include line numbers in output
--explain - Include retrieval score traces (query --json/CLI)
--files | --json | --csv | --md | --xml - Output format
-c, --collection <name> - Filter by one or more collections
Multi-get options:
-l <num> - Maximum lines per file
--max-bytes <num> - Skip files larger than N bytes (default 10240)
--json/--csv/--md/--xml/--files - Same formats as search
Index: /home/node/.cache/qmd/index.sqlite
手工验证qmd是否生效
- 1.查看qmd版本
#进入容器
docker compose exec -it openclaw-gateway bash
qmd --version
- 2.手工索引
qmd update --dir "/home/node/.openclaw/workspace"
#查看集合
qmd collection list
- 3.测试搜索功能
#默认集合位置/home/node/.cache/qmd/index.sqlite
qmd search "你的关键词"
#指定集合位置
qmd search "你的关键词" -c "/home/node/.cache/qmd/index.sqlite"
- 4.验证实时更新
#默认目录索引
qmd update
#指定工作目录做更新索引
qmd update --dir "/home/node/.openclaw/workspace"
- openclaw搜索
#进入容器
docker compose exec --user root -it openclaw-gateway bash
openclaw memory search "你的关键词"
- 示例配置及权限配置
{
"memory": {
"backend": "qmd",
"qmd": {
"includeDefaultMemory": true,
"paths": [
// 你的额外路径
],
// 关键部分：scope 权限控制
"scope": {
// 默认允许所有未知类型的会话执行搜索
"default": "allow",
// 也可以针对已知类型单独设置（可选）
"private": "allow", // 私聊允许
"group": "deny", // 群聊拒绝（可根据需要调整）
"channel": "allow" // 频道允许
}
}
}
}
- 补充说明
安全考虑：default: allow 会让所有无法识别类型的会话都能搜索记忆。如果你担心安全性，可以尝试先确定你的实际会话类型（比如在私聊中测试，将 private 设为 allow，default 保持 deny），但根据你的错误信息，当前环境无法识别类型，所以最简单的修复是临时允许默认。
权限优先级：scope 匹配顺序是：优先匹配具体类型（如 private），如果没有匹配则使用 default。如果 default 也未设置，则默认行为是 deny
获取最新文章: 扫一扫右上角的二维码加入“创客智造”公众号