OpenClaw 记忆系统探索,配置 Embedding 向量检索,让记忆查询真正做到语义上的准确.

大家好，我们继续聊 OpenClaw 的记忆系统。

之前一篇文章介绍了基于关键字搜索的记忆系统机制和 FTS 索引。 大家如果需要了解，可以查看之前的文章：

OpenClaw 记忆系统探索，memory-core 插件的FTS文本检索

简单概括， 基于关键字索引的 FTS 很擅长查找完全相同的关键词，但如果用户和原文使用了不同的表达，结果可能就不够理想。这正是 Embedding 向量检索要解决的问题。也是大家让记忆系统能真正发挥作用的一个地方。

特别是记忆库中包含中文等非英语内容时，OpenClaw 默认使用的 SQLite FTS 分词处理可能并不准确。

Embedding 是什么

Embedding 这个词，估计大家应该听过不少次了。可以理解为把一段文字转换成一组数字。比如下面只是一个为了方便理解而简化的三维向量：

“OpenClaw 运行在哪台电脑” → [0.81, 0.12, 0.66]“Gateway 所在的主机”      → [0.79, 0.15, 0.63]“今天上海天气怎么样”      → [0.08, 0.91, 0.20]

前两句话虽然没有几个相同的词，但意思接近，因此向量位置也接近。第三句话语义不同，向量位置就会更远。真实的 Embedding 向量可能包含几百到几千个数字，这里为了方便理解进行了简化。

查询时通常会计算两个向量的余弦距离。它关注的不是每个数字是否相等，而是两个向量指向的方向是否接近。余弦相似度越高，代表语义越接近；换成余弦距离来表示，就是距离越小越相关。

SQLite 本身负责保存文本、文件路径和 chunk 等数据。加载 sqlite-vec 这类向量扩展后，它还可以保存向量并执行近邻查询：把查询向量和数据库中的向量计算距离，按照距离从小到大排列，再返回最接近的几条记录。

这就是向量查询能提高准确度的原因：它不只查“有没有相同关键词”，还会查“表达的意思是否相近”。当然，纯关键词搜索，也有它的价值，比如文件名、配置项和错误码仍然更适合 FTS，因此 OpenClaw 默认会把两种结果合并返回。

Embedding 分为两个阶段， 创建索引，还有查询阶段。

创建向量索引

如果没有可用的 Embedding Provider，OpenClaw 就不会建立向量索引，只会保留 FTS 关键词检索。我们需要配置一个 Embedding API，很多云端模型厂商都提供这类 API。

这个 API 接收文字，返回固定维度的向量。有一点要注意， Embedding 模型一旦选定，建立索引和查询时必须使用同一个模型，否则两边的向量不在同一个坐标体系中，距离也就没有意义。

配置好后， 再建立记忆索引的时候， OpenClaw 会读取 MEMORY.md、USER.md 和 memory/*.md，默认把内容切成大约 400 token 的 chunk，并保留 80 token 的重叠。每个 chunk 分别提交给 Embedding API，得到向量后写入当前 Agent 的 SQLite 数据库。

Markdown → 切分 chunk → 调用 Embedding API → 保存文本和向量

相关的记忆文件发生变化后，OpenClaw 会标记索引需要更新，并增量处理改变的内容，不需要每次重建全部数据。

执行向量查询

当模型调用 memory_search 时，OpenClaw 会把查询语句也发送给同一个 Embedding API，生成查询向量。然后 SQLite 从已经索引的 chunk 中查找距离最近的结果。 就是说，我们配置的 Embedding API， 除了在建立索引的时候会被调用， 查询的时候也会被调用。

与此同时，FTS 还会执行一次关键词查询。OpenClaw 合并两边的候选结果，再结合时间、重要性和去重规则进行排序，最后只把最相关的几个 chunk 返回给模型。如果模型需要更多上下文，再根据结果中的文件路径读取原文。

在 OpenClaw 中开启 Embedding

要配置 Embedding，需要编辑 ~/.openclaw/openclaw.json 配置文件，并在其中加入一个名为 memory 的顶层节点。这个节点和 agents、gateway 平级。最简单的 OpenAI 配置如下：

{  agents: {    // 原有 Agent 配置  },  memory: {    search: {      provider: "openai",      model: "text-embedding-3-small"    }  }}

这段配置只指定 Embedding Provider 和模型，对应服务的 API Key 和调用权限也要提前配置好。例如使用 OpenAI，就要准备能够调用 Embedding API 的 OpenAI API Key。篇幅原因，这里不再重复凭据配置过程。

更完整的配置可以参考 OpenClaw 官方文档：https://docs.openclaw.ai/reference/memory-config

配置完成后，可以通过命令行触发一次重新索引：

openclaw memory index --force --agent main

执行后，OpenClaw 会读取本地记忆文件，调用刚才配置的 Embedding API 生成向量，并把结果保存到当前 Agent 的本地 SQLite 记忆数据库中。完成后再检查状态：

openclaw memory status --deep --agent main

成功时会看到类似这样的输出：

Provider: openaiModel: text-embedding-3-smallEmbeddings: readyVector store: readySemantic vectors: readyVector dims: 1536

看到这些 ready 状态，就表示 Embedding API 可用，向量索引也已建立成功。文件和 chunk 数量会因本地记忆内容不同而变化。后续 OpenClaw 会继续维护索引，实际搜索仍由模型按需调用 memory_search。

总结

最后简单总结一下，配置 Embedding 的主要作用，就是进行语义查询，文章开始跟大家聊的这个例子就是这样。如果没有可用的 Embedding，记忆搜索就主要依赖关键词分词。两个意思相同、文字表达却不同的内容，就更容易被遗漏。也就是说，如果你希望 OpenClaw 的记忆系统能够实现更有效的语义查询，那么配置 Embedding 是很有必要的。

提醒：文章内容都是基于当时的日期的运行环境，软件版本等，作为思考和学习过程的分享，给大家提供思路。但由于行业技术的更新速度非常快，如果你是距离文章发布比较长的时间看到的，很可能你当前的各种运行环境和文章中提到的会有差异，有些情况下差异还可能很大。所以请大家保持验证信息的习惯，以你当前实际环境的运行结果和官方文档为准。