chenlincai.com

OpenClaw QMD新手安装/配置指南（macOS）

Feb 7, 2026

这份指南按 OpenClaw 官网「QMD backend (experimental)」思路整理：

  • Markdown 是“记忆源数据”
  • QMD 是本地检索引擎（BM25 + 向量 + rerank），用来减少上下文 token（需要记忆时再检索注入）

适用：macOS（本机自托管 Gateway）。

0. 你需要先理解的 2 件事

  1. 长久记忆不等于自动记住所有聊天
  • OpenClaw 的“记忆”本体是写入磁盘的 Markdown（例如 MEMORY.md、memory/YYYY-MM-DD.md、以及你额外加的笔记目录）。
  • QMD 只是把这些内容建索引，供 memory_search/memory_get 之类的检索使用。
  1. 第一次使用会慢
  • QMD 会自动从 HuggingFace 下载本地 GGUF 模型（query expansion / rerank / embedding）。
  • 第一次 query 可能会下载几百 MB～1GB+。

1) 安装依赖

1.1 安装 Bun

推荐 Homebrew：

brew install oven-sh/bun/bun
bun --version

1.2 安装 QMD CLI

Bun 安装（推荐）：

bun add -g github:tobi/qmd
# 或者：bun add -g github:tobi/qmd#<commit>

验证：

qmd --help

1.3 安装 SQLite（允许 extensions）

官网建议（macOS）：

brew install sqlite

2) OpenClaw 配置（openclaw.json）

文件：~/.openclaw/openclaw.json

最小推荐配置（可直接参考官网结构）：

memory: {
  backend: "qmd",
  citations: "auto",
  qmd: {
    includeDefaultMemory: true,

    // 建议显式指定 qmd 命令路径（避免 PATH 问题）
    command: "/Users/cccc/.bun/bin/qmd",

    update: {
      onBoot: true,
      interval: "5m",
      debounceMs: 15000,
      embedInterval: "1h"
    },

    limits: { maxResults: 6, timeoutMs: 4000 },

    // 默认只允许 direct chat 注入召回（更安全）
    scope: {
      default: "deny",
      rules: [{ action: "allow", match: { chatType: "direct" } }]
    },

    // 额外索引你的知识库目录（Markdown）
    paths: [
      { name: "docs", path: "/Users/cccc/notes", pattern: "**/*.md" }
    ],

    // 可选：把近期对话也导出成可检索的集合（“聊天可检索”）
    sessions: { enabled: true, retentionDays: 14 }
  }
}

配置改完后重启 Gateway：

openclaw gateway restart

3) 你机器上的特殊坑：/Users/cccc/.config 权限

在这台 Mac mini 上：/Users/cccc/.config 目录是 root 拥有，导致 QMD 默认写 ~/.config/qmd 会 EACCES。

解决办法（实战有效）：用一个 wrapper 强制把 qmd 的 config/cache 放到 OpenClaw state 目录下。

示例（路径按需调整）：

  • 脚本：~/.openclaw/bin/qmd-openclaw.sh
  • OpenClaw 配置里把：
    • memory.qmd.command 改成这个脚本路径

脚本做的事：

  • 设置 XDG_CONFIG_HOME / XDG_CACHE_HOME 到 ~/.openclaw/agents/<agentId>/qmd/...
  • 设置 QMD_CONFIG_DIR（qmd 自己支持的 override）到可写目录

4) 初始化/验证（建议按顺序）

4.1 准备笔记目录

mkdir -p /Users/cccc/notes
echo "# qmd test\n\nopenclaw qmd test" > /Users/cccc/notes/qmd-test.md

4.2 触发一次索引

openclaw memory index --verbose

4.3 看状态

openclaw memory status

4.4 直接用 qmd 验证（最直观）

qmd status
qmd search "openclaw" --json
qmd query "openclaw" --json

5) 常见问题（Troubleshooting）

5.1 EACCES: permission denied, mkdir ~/.config/qmd

  • 说明 qmd 还在尝试写 ~/.config/qmd。
  • 用 wrapper + QMD_CONFIG_DIR 解决（见第 3 节）。
  • 优先用 qmd search/query --json 验证 QMD 本身是否有结果。
  • 若 qmd 在 --json 模式下仍向 stdout 输出了“进度/解释文本”，可能会影响上层解析。
  • 这种情况下：
    • 先让 qmd 完成首次模型下载（避免一直输出进度条）
    • 再重跑 openclaw memory index

5.3 首次 query 下载很大

  • 这是正常的：reranker/query-expansion/embedding 会下载 GGUF。
  • 想提前 warm：手动跑一次 qmd query "test" --json。

6) 推荐使用习惯（降低 token 消耗的关键）

  • 让“可沉淀的东西”进 Markdown（Notes/Obsidian/notes 目录）。
  • 对话里需要回忆时，用检索（QMD）找“短 snippet”注入，而不是把整段历史塞进上下文。
  • 定期整理：重要决策写 MEMORY.md；日常流水写 memory/YYYY-MM-DD.md。
    ) QMD 测试结果（实测 OK）

• qmd wrapper 现在能正确使用 OpenClaw 的 agent 目录作为 XDG home（不再碰你那台机子 root 拥有的 ~/.config）
• qmd search / qmd query 都能从我们这次会话的 sessions 和 workspace 的 memory 文件里搜到内容
举例（我实际跑出来的结果里）：

• qmd search "Wake up" 能命中 session 转录（含 “Wake up, my friend!”）
• qmd query "Wake up" --json 能返回 sessions + memory/2026-02-04.md 的条目
注意：第一次 qmd query 会自动下载模型，可能 600MB～1.3GB（正常）。

平时对话会不会记录？

会记录成“可检索的会话转录（sessions）”——这是我刚按官网建议帮你打开的：

• memory.qmd.sessions.enabled = true
• retentionDays = 14
所以：默认保留 14 天的对话转录用于检索召回（不会自动写进 MEMORY.md 这种长期笔记）。

真正“长期记忆”还是你写进 Markdown/Notes 的内容（比如 workspace 的 MEMORY.md、memory/YYYY-MM-DD.md，或你自己的 notes 目录）。

把某个知识库包含为记忆（让 QMD 能搜到）

你有两种方式：

A) 最推荐：把知识库放成 Markdown 文件夹，然后加到 memory.qmd.paths

比如你有个库在 /Users/cccc/KnowledgeBase（里面都是 .md），就加一条：

memory: {
  qmd: {
    paths: [
      { name: "kb", path: "/Users/cccc/KnowledgeBase", pattern: "**/*.md" }
    ]
  }
}

加完重启 Gateway 或跑一次：
openclaw memory index --verbose

B) 如果知识库不是 Markdown

先导出/转换成 Markdown（或至少 txt），再按 A 加路径。QMD/OpenClaw 主要索引 Markdown。

你现在已经包含的知识库有哪些？

• /Users/cccc/notes/**/.md（name: docs）
• workspace 默认记忆：MEMORY.md + memory/.md
• 近 14 天会话（sessions）
你把“知识库路径”发我（例如一个文件夹路径），我可以直接帮你把它加进 memory.qmd.paths 并触发索引。

clinch