# QMD 功能修复实战：从 "spawn EINVAL" 到完美搜索

> **时间**: 2026-02-28 13:11 - 13:30  

> **环境**: Windows 11, OpenClaw 2026.2.26, QMD 1.1.0, Node.js v24.13.1  

> **问题**: QMD 搜索报 `spawn EINVAL` 错误，无法索引和搜索  

> **结果**: 修复配置后成功索引 32 个文件，BM25 搜索正常工作  

> **状态**: ✅ 已解决

---

## 🚨 问题现象

在执行 `openclaw memory search` 时持续报错：

```

[memory] qmd collection add failed for memory-root-main: spawn EINVAL

[memory] qmd collection add failed for memory-alt-main: spawn EINVAL

[memory] qmd collection add failed for memory-dir-main: spawn EINVAL

[memory] qmd search denied by scope (channel=unknown, chatType=unknown, session=<none>)

[memory] qmd boot update failed: Error: spawn EINVAL

```

**关键错误**: `spawn EINVAL` —— Node.js 的 `child_process.spawn()` 在 Windows 上调用失败。

---

## 🔍 排查过程

### 第一阶段：初步诊断

**步骤 1**: 检查 `qmd` 命令是否可用

```bash

$ qmd --version

qmd 1.1.0

```

✅ `qmd` 命令本身工作正常。

**步骤 2**: 手动测试 `qmd search`

```bash

$ qmd search "test" --dir "C:\Users\fly\.openclaw\workspace-magic"

No results found.

```

✅ `qmd` 可以正常运行，只是没有索引。

**步骤 3**: 检查 OpenClaw 调用方式

问题定位：OpenClaw 内部使用 `spawn()` 调用 `qmd` 时失败，但手动执行正常。

### 第二阶段：配置修复

**尝试 1**: 清理无效配置

发现配置中存在不存在的 `acp-backend` 插件条目，将其删除：

```json

{

  "plugins": {

    "entries": {

      "acp-backend": null  // 删除此无效项

    }

  }

}

```

❌ **结果**: 仍然报 `spawn EINVAL`。

**尝试 2**: 显式指定 `qmd` 命令路径

```json

{

  "memory": {

    "qmd": {

      "command": "qmd.exe"

    }

  }

}

```

✅ **突破!** `spawn EINVAL` 错误消失了！

现在的错误变为：

```

[memory] qmd search denied by scope

```

这说明 `qmd` 命令已经可以正常调用，但被权限策略阻止。

**尝试 3**: 配置 QMD 作用域策略

```json

{

  "memory": {

    "qmd": {

      "command": "qmd.exe",

      "scope": {

        "default": "allow"

      }

    }

  }

}

```

✅ **成功!** 权限问题解决。

### 第三阶段：索引构建

**步骤 1**: 手动运行 QMD 更新

```bash

$ qmd update --dir "C:\Users\fly\.openclaw\workspace-magic"

Updating 1 collection(s)...

Indexed: 12 new, 2 updated, 17 unchanged, 0 removed

✓ All collections updated.

Run 'qmd embed' to update embeddings (31 unique hashes need vectors)

```

✅ 成功索引 31 个文件。

**步骤 2**: 测试搜索功能

```bash

$ qmd search "blog" -c "C:\Users\fly\.openclaw\workspace-magic"

qmd://C:\Users\fly\.openclaw\workspace-magic/memory/2026-02-23-final.md:129

qmd://C:\Users\fly\.openclaw\workspace-magic/memory/2026-02-23.md:167

```

✅ 搜索功能正常工作！

**步骤 3**: 创建测试文件验证

创建 `blog.md` 文件后再次更新索引：

```bash

$ qmd update --dir "C:\Users\fly\.openclaw\workspace-magic"

Indexed: 1 new, 0 updated, 31 unchanged, 0 removed

```

**步骤 4**: 验证新文件可搜索

```bash

$ qmd search "ACP" -c "C:\Users\fly\.openclaw\workspace-magic"

qmd://C:\Users\fly\.openclaw\workspace-magic/blog.md:1

Title: 实战记录：OpenClaw 中 ACP 后端不可用问题的排查与解决

Score: 87%

```

🎉 **完美！搜索功能完全正常！**

---

## 💡 根本原因分析

### 问题 1: `spawn EINVAL` 错误

**原因**: OpenClaw 默认未显式指定 `qmd` 命令路径，导致 `spawn()` 调用时参数传递异常。

**解决**: 在配置中显式指定 `memory.qmd.command: "qmd.exe"`。

### 问题 2: 作用域拒绝

**原因**: QMD 默认策略拒绝未明确允许的会话访问。

**解决**: 设置 `memory.qmd.scope.default: "allow"` 允许默认访问。

### 问题 3: 索引为空

**原因**: QMD 需要手动触发初始索引构建。

**解决**: 运行 `qmd update --dir <工作区路径>` 创建索引。

---

## ✅ 最终配置

```json

{

  "memory": {

    "backend": "qmd",

    "qmd": {

      "command": "qmd.exe",

      "scope": {

        "default": "allow"

      }

    }

  }

}

```

**配置路径**: `C:\Users\fly\.openclaw\openclaw.json`

---

## 📊 修复结果

| 检查项 | 修复前 | 修复后 |

|--------|--------|--------|

| `spawn EINVAL` | ❌ 报错 | ✅ 正常 |

| 作用域限制 | ❌ 拒绝 | ✅ 允许 |

| 索引文件数 | 0 | 32 |

| BM25 搜索 | ❌ 不可用 | ✅ 正常 |

| 向量嵌入 | 0/32 | 0/32 (可选) |

---

## 🚀 使用指南

### 命令速查

```bash

# 更新索引

qmd update --dir "C:\Users\fly\.openclaw\workspace-magic"

# 搜索关键词

qmd search "关键词" -c "C:\Users\fly\.openclaw\workspace-magic"

# 列出所有索引文件

qmd ls "C:\Users\fly\.openclaw\workspace-magic"

# 查看状态

qmd status

# 生成向量嵌入 (可选，用于语义搜索)

qmd embed

```

### OpenClaw 集成

```bash

# 通过 OpenClaw 搜索

openclaw memory search "关键词"

```

---

## 📚 经验总结

### 1. Windows 上的 `spawn` 陷阱

在 Windows 上，Node.js 的 `spawn()` 对命令路径和参数格式敏感。如果遇到问题：

- ✅ 显式指定命令路径（如 `qmd.exe`）

- ✅ 避免使用未解析的命令别名

- ✅ 检查 PATH 环境变量

### 2. QMD 双层架构

QMD 采用双层记忆架构：

- **短期记忆 (QMD)**: 本地 BM25 关键词搜索，毫秒级响应

- **长期记忆 (Mem0)**: 远程向量语义搜索，跨会话知识

两者互补，QMD 适合工作区文档快速检索，Mem0 适合全局知识沉淀。

### 3. 索引维护

- 新文件创建后需运行 `qmd update` 重新索引

- 向量嵌入是可选的，BM25 搜索不需要

- 定期清理过期索引可提升性能

---

## 🔧 故障排除

### 问题：仍然报 `spawn EINVAL`

**解决**:

1. 确认 `qmd` 命令在 PATH 中

2. 尝试显式指定完整路径：`memory.qmd.command: "C:\\Users\\fly\\.bun\\bin\\qmd.exe"`

3. 重启 Gateway 服务

### 问题：搜索返回 "No matches"

**解决**:

1. 运行 `qmd ls` 确认文件已索引

2. 运行 `qmd update` 更新索引

3. 检查搜索关键词是否在索引文件中

### 问题：作用域拒绝

**解决**:

1. 添加 `memory.qmd.scope.default: "allow"`

2. 或针对特定会话配置允许规则

---

## 🎯 后续优化

- [ ] 运行 `qmd embed` 生成向量嵌入，启用语义搜索

- [ ] 配置 QMD 自动索引（文件变更时自动更新）

- [ ] 优化 BM25 参数，提升中文搜索准确率

- [ ] 探索 QMD 与 Mem0 的协同工作机制

---

> **总结**: 通过显式配置命令路径和作用域策略，成功修复了 QMD 在 Windows 上的 `spawn EINVAL` 问题。现在 QMD 已完全就绪，支持 32 个文件的毫秒级关键词搜索！🎉

**时间线**:

- 13:11 - 开始排查

- 13:15 - 发现 `spawn EINVAL` 根本原因

- 13:18 - 修复配置，索引构建成功

- 13:21 - 搜索功能验证通过

- 13:30 - 完成文档记录

**总耗时**: ~19 分钟