OpenClaw + Qmd 配置实战：把记忆成本砍到脚踝

用户4320978380521
8 阅读3分钟

最近给 OpenClaw 接上了 Qmd 做本地语义搜索，Token 账单直接砍了 90% 以上。这篇记录一下踩坑过程，方便以后复现。

一、Qmd 是什么

简单说：Qmd 是一个跑在你本地的语义搜索引擎。它会把你的 Markdown 笔记转成向量，搜的时候用语义匹配而不是关键词匹配。

为什么选它：

  • 完全本地，模型下载完就断网能用
  • 和 OpenClaw 官方对接，配置即插即用
  • 响应速度比 OpenClaw 自带的记忆快 5-50 倍

代价：

  • 第一次要下两个模型（加起来 1GB 左右）
  • 需要手动维护索引

二、安装 Qmd

方式一：npm（推荐）

npm i -g @tobilu/qmd
qmd --help

方式二：Bun（某些环境更顺）

# 先装 Bun
curl -fsSL https://bun.sh/install | bash

# 装 Qmd
bun install -g https://github.com/tobi/qmd
sudo ln -s $(which qmd) /usr/local/bin/qmd  # 确保全局能调用

第一次运行会自动下载：

  • jina-embeddings-v3（330MB）
  • jina-reranker-v2-base-multilingual（640MB）

下完就离线可用。

三、OpenClaw 配置

  1. 备份原配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%F)
  1. 修改配置

编辑 ~/.openclaw/openclaw.json，在 memory 段加：

{
  "memory": {
    // 【必填】记忆后端类型，填 qmd 启用本地语义搜索
    "backend": "qmd",
    
    // 【可选】引用格式：auto 自动 / inline 行内 / block 块级
    "citations": "auto",
    
    // 【Qmd 专属配置】
    "qmd": {
      // 【必填】qmd 命令路径，全局安装后一般就是 qmd
      "command": "qmd",
      
      // 【必填】搜索模式：
      // query   = 混合搜索（语义+关键词，最准）
      // search  = 纯关键词（最快）
      // vsearch = 纯语义搜索
      "searchMode": "query",
      
      // 【可选】是否包含默认记忆文件，建议 true
      "includeDefaultMemory": true,
      
      // 【自动更新配置】
      "update": {
        // 自动更新间隔，5m = 5分钟
        "interval": "5m",
        // 防抖时间，15秒内多次修改只算一次
        "debounceMs": 15000,
        // 启动时是否立即同步，true = 是
        "onBoot": true,
        // 启动同步时是否阻塞，false = 后台跑不卡启动
        "waitForBootSync": false
      },
      
      // 【限制配置】
      "limits": {
        // 最大返回结果数，默认6条，越多越耗 Token
        "maxResults": 6,
        // 搜索超时时间，毫秒，4秒够用了
        "timeoutMs": 4000
      },
      
      // 【作用域配置】控制哪些对话启用记忆
      "scope": {
        // 默认策略：deny = 默认关闭，需要显式开启
        "default": "deny",
        // 规则列表，从上往下匹配
        "rules": [
          {
            // 允许私聊使用记忆
            "action": "allow",
            "match": {
              "chatType": "direct"
            }
          }
          // 可以继续加规则，比如允许特定群组
          // {
          //   "action": "allow",
          //   "match": {
          //     "chatType": "group",
          //     "chatId": "你的群组ID"
          //   }
          // }
        ]
      },
      
      // 【索引路径配置】告诉 Qmd 要索引哪些文件
      "paths": [
        {
          // 名称，随便取，方便区分
          "name": "workspace",
          // 笔记根目录，改成你的实际路径
          "path": "/home/node/.openclaw/workspace",
          // 匹配模式，**/*.md = 所有子目录的 md 文件
          "pattern": "**/*.md"
        },
        {
          // 专门索引 memory 目录
          "name": "memory",
          "path": "/home/node/.openclaw/workspace/memory",
          "pattern": "**/*.md"
        }
        // 可以继续加，比如：
        // {
        //   "name": "obsidian",
        //   "path": "/home/你的用户名/ObsidianVault",
        //   "pattern": "**/*.md"
        // }
      ]
    }
  }
}
  1. 重启生效
openclaw gateway restart

四、初始化索引（关键）

光改配置不够，得手动把现有笔记喂给 Qmd。

# 设置环境变量，和 OpenClaw 保持一致
STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
AGENT_ID="你的AgentID"  # 用 openclaw memory status 查

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"

# 添加笔记目录到 Qmd
qmd collection add "$STATE_DIR/workspace/memory" --name memory-root --mask "**/*.md"
qmd collection add "$STATE_DIR/workspace" --name memory-long --mask "MEMORY.md"

# 更新索引并生成向量
qmd update
qmd embed

五、验证是否跑通

# 看状态
openclaw memory status

# 直接搜一下
qmd query "测试关键词" --json

# 看日志确认
openclaw logs --follow | grep qmd

看到 qmd memory backend enabled 就是成功了。

六、Docker 部署注意事项

如果用 Docker 跑 OpenClaw，要进容器装：

docker compose exec --user root -it openclaw-gateway bash

apt update && apt install -y jq sqlite3
npm install -g @tobilu/qmd

# 国内镜像加速模型下载
echo "export HF_ENDPOINT=https://hf-mirror.com" >> ~/.bashrc
echo "export PATH=$PATH:/home/node/.bun/bin" >> ~/.bashrc

坑点： 容器重启后模型会丢，建议挂卷持久化：

mkdir -p ~/.openclaw/qmd/
mv ~/.cache/qmd/models ~/.openclaw/qmd/
ln -s ~/.openclaw/qmd/models ~/.cache/qmd/models

七、回退方案

如果搞砸了想回默认记忆：

openclaw config set memory.backend sqlite
openclaw gateway restart

八、实际效果

改后Token消耗全量加载只加载最相关的6条， 响应时间快 5-50 倍 ，离线可用。

参考

avatar
文章
阅读
粉丝