OpenClaw QMD Memory Engine 安装配置指南

为 OpenClaw 多 Agent 集群启用 QMD 本地混合搜索引擎，替代内置 memory backend，支持多语言 CJK。

我是 AI灵感闪现，使用 OpenClaw 小龙虾让 AI 自主管理工作和生活上的问题；使用 Claude Code + BMAD AI 驱动敏捷开发框架，让 AI 自主开发和交付软件来表达想法和灵感。是 MoneyMind 省钱思维 App 和 HeartPetBond 心宠纽带 App 开发者。正在实践和分享让 AI 自主解决健康、生活、投资和等方面的问题。我尽可能让 AI 自己完成从目标到交付以及演进的闭环，以最少的人为交互与监督，让 AI 自己跑流程。我只给 AI 想法或目标，全程不陪跑，让 AI 自主运行类似 Tesla FSD 自动驾驶。

环境： macOS (Apple Silicon), OpenClaw 2026.4.11, QMD 2.1.0Agent 数量： 15 个

背景

OpenClaw 内置的 memory engine（builtin）基于 SQLite FTS5，适合简单场景。当需要更高质量的搜索（重排序、语义搜索）、索引 workspace 外的文档、或回溯历史会话时，可以启用 QMD^[1] 作为 memory backend。

QMD 是一个本地搜索 sidecar，组合 BM25 全文检索 + 向量语义搜索 + LLM 重排序，完全在本地运行，无需 API key。

一、安装 QMD

1. 通过 Bun 全局安装

bun install -g @tobilu/qmd

验证：

qmd --version# qmd 2.1.0

2. 创建 symlink（Gateway 服务可达）

OpenClaw Gateway 通过 launchd 运行，其 PATH 可能不包含 ~/.bun/bin。创建 symlink 确保可达：

sudoln -s ~/.bun/bin/qmd /usr/local/bin/qmd

注意： 如果 LaunchAgent plist 的 EnvironmentVariables.PATH 已经包含 ~/.bun/bin，此步骤非必需但仍建议做，以防其他进程也需要调用 qmd。

二、下载 GGUF 模型

QMD 使用 3 个本地 GGUF 模型（首次搜索时自动下载，但从国内下载 HuggingFace 很慢）。建议提前手动下载：

默认模型

模型	用途	大小
embeddinggemma-300M-Q8_0	向量 Embedding	~313MB
qwen3-reranker-0.6b-q8_0	重排序	~610MB
qmd-query-expansion-1.7B-q4_k_m	查询扩展（微调）	~1.2GB

多语言 Embedding 模型（推荐）

默认的 embeddinggemma-300M 对中日韩文支持有限。强烈建议换用 Qwen3-Embedding-0.6B：

模型	用途	大小
Qwen3-Embedding-0.6B-Q8_0	多语言向量 Embedding	~610MB

手动下载命令

mkdir -p ~/.cache/qmd/models# 1. Embedding（默认，可选保留）curl -L -o ~/.cache/qmd/models/hf_ggml-org_embeddinggemma-300M-GGUF_embeddinggemma-300M-Q8_0.gguf \"https://huggingface.co/ggml-org/embeddinggemma-300M-GGUF/resolve/main/embeddinggemma-300M-Q8_0.gguf"# 2. 多语言 Embedding（推荐替代）curl -L -o ~/.cache/qmd/models/hf_Qwen_Qwen3-Embedding-0.6B-GGUF_Qwen3-Embedding-0.6B-Q8_0.gguf \"https://huggingface.co/Qwen/Qwen3-Embedding-0.6B-GGUF/resolve/main/Qwen3-Embedding-0.6B-Q8_0.gguf"# 3. Rerankercurl -L -o ~/.cache/qmd/models/hf_ggml-org_Qwen3-Reranker-0.6B-Q8_0-GGUF_qwen3-reranker-0.6b-q8_0.gguf \"https://huggingface.co/ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/resolve/main/qwen3-reranker-0.6b-q8_0.gguf"# 4. Query Expansioncurl -L -o ~/.cache/qmd/models/hf_tobil_qmd-query-expansion-1.7B-gguf_qmd-query-expansion-1.7B-q4_k_m.gguf \"https://huggingface.co/tobil/qmd-query-expansion-1.7B-gguf/resolve/main/qmd-query-expansion-1.7B-q4_k_m.gguf"

提示： 4 个 curl 可以并行执行加速下载。国内网络下载 HuggingFace 约 0.5-1MB/s，总计 ~2.7GB 预计 30-50 分钟。如有 HuggingFace 镜像可替换 URL。

模型文件命名规则

QMD 通过 hf:<org>/<repo>/<file> URI 定位模型，缓存文件名格式为 hf_<org>_<repo>_<file>（斜杠替换为下划线）。手动下载时必须遵循此命名。

三、配置 OpenClaw

1. 修改 openclaw.json

memory 配置在顶层（不是 agents.defaults 下）：

// ~/.openclaw/openclaw.json{"memory":{"backend":"qmd","qmd":{"sessions":{"enabled":true}}}}

⚠️ 踩坑记录： 最初尝试将 memory 放在 agents.defaults 下，结果 gateway 启动时 schema 校验会静默移除该字段。memory 必须放在顶层。

2. 配置多语言 Embedding 模型

在 Gateway LaunchAgent plist 中添加环境变量：

<!-- ~/Library/LaunchAgents/ai.openclaw.gateway.plist --><key>QMD_EMBED_MODEL</key><string>hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf</string>

如果通过 openclaw tui 或命令行运行，改为 export 环境变量：
export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"

3. 重启 Gateway

launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway

四、数据隔离

OpenClaw 自动为每个 agent 创建独立的 QMD 数据目录：

~/.openclaw/agents/<agentId>/qmd/├── sessions/      # 会话记录导出├── xdg-cache/     # QMD 索引数据库└── xdg-config/    # QMD 配置

每个 agent 自动创建 3 个 collection：

Collection	内容
`memory-root-<agentId>`	Workspace 根目录的 `MEMORY.md` 等
`memory-dir-<agentId>`	`memory/` 子目录下的所有 .md 文件
`sessions-<agentId>`	历史会话记录（需 `sessions.enabled: true`）

15 个 agent = 15 套完全独立的 QMD 索引，互不干扰。

五、验证

1. 检查 Gateway 日志

grep -i "qmd\|memory.*backend" ~/.openclaw/logs/gateway.err.log | tail -20

正常输出会看到每个 agent 的 collection 创建日志：

[memory] qmd collection add skipped for memory-alt-xxx: ... A collection already exists

2. 检查 Agent QMD 目录

ls ~/.openclaw/agents/*/qmd

每个 agent 都应该有 sessions/, xdg-cache/, xdg-config/ 三个子目录。

3. 查看 Agent Collection

XDG_DATA_HOME=~/.openclaw/agents/<agentId>/qmd/xdg-cache \XDG_CONFIG_HOME=~/.openclaw/agents/<agentId>/qmd/xdg-config \qmd collection list

4. 触发首次索引

Gateway 启动后会在后台自动运行 qmd update + qmd embed：

update 周期： 每 5 分钟
embed 周期： 每 60 分钟
启动时立即执行一次（后台，不阻塞）

如需手动触发预热：

qmd query "test"

首次运行会加载 GGUF 模型到内存（约 1-2 分钟），后续查询秒级响应。

六、QMD 搜索模式对比

模式	命令	特点
`search`	`qmd search "query"`	BM25 全文检索，快速，关键词匹配
`vsearch`	`qmd vsearch "query"`	向量语义搜索，理解语义相似性
`query`	`qmd query "query"`	混合搜索 + 查询扩展 + 重排序，最高质量

OpenClaw 默认使用 search 模式。可在配置中修改：

{"memory":{"backend":"qmd","qmd":{"searchMode":"query"// 或 "vsearch"}}}

七、踩坑总结

问题	原因	解决
`memory` 放在 `agents.defaults` 下无效	Schema 不允许，启动时被静默移除	放在顶层
Gateway 找不到 qmd	launchd PATH 不含 `~/.bun/bin`	`sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd`
HuggingFace 下载极慢	国内网络限制	手动 curl 并行下载或用镜像
`qmd query "test"` 首次超时	需要下载 ~2GB GGUF 模型	提前手动下载模型文件
日志显示 "collection add skipped"	Collection 已存在（正常）	忽略，这是幂等操作