#0104 深度分析：为 OpenClaw 配置 Voyage AI 嵌入模型

type
status
date
slug
summary
tags
category
icon
password

深度分析：为 OpenClaw 配置 Voyage AI 嵌入模型

2026-02-07 | 技术实践 | AI 工具

TL;DR

我们将 OpenClaw 的记忆搜索（memorySearch）从默认的本地嵌入模型切换到了 Voyage AI 云端 API，主要为了更好的多语言（尤其中文）检索质量。本文记录了完整的配置过程、踩过的坑，以及与现有 qmd 系统的关系。

一、为什么要换？

OpenClaw 有一个核心功能叫 memorySearch——它会对 MEMORY.md 和 memory/*.md 文件建立向量索引，让 AI 助手能够语义搜索自己的记忆。这个功能默认使用本地嵌入模型（通过 node-llama-cpp 在本机运行 GGUF 模型），完全离线、零成本，但中文语义理解能力有限。
切换的动机很简单：
  1. 本地模型中文检索效果不理想。 我们的日常对话大量使用中文，本地小模型在中文语义匹配上表现一般，经常搜不到相关记忆
  1. Voyage AI 在检索基准测试中持续领先。 从 MTEB 排行榜到实际 RAG 场景，Voyage 的模型一直是 top tier
  1. 成本几乎为零。 Voyage AI 提供每个账号 2 亿 token 的免费额度，我们的用量（约 4.5 万 token/月）大概能用几百年

二、Voyage AI 的优势

模型矩阵

Voyage 4 系列（2026 年 1 月发布）提供三个档位：
  • voyage-4-large — 最高质量，多语言检索最佳。维度 1024（可选 256/512/2048），32K 上下文，$0.12/百万 token
  • voyage-4 — 通用平衡之选。维度 1024（可选 256/512/2048），32K 上下文，$0.06/百万 token
  • voyage-4-lite — 低延迟、低成本。维度 1024（可选 256/512/2048），32K 上下文，$0.02/百万 token
4 系列的一个亮点：所有 4 系列模型生成的向量互相兼容。也就是说你可以用 voyage-4-large 索引文档，用 voyage-4-lite 编码查询，向量空间是一致的。这为成本优化提供了很大灵活性。

对比其他方案

OpenClaw 默认（本地模型）： 零成本，完全离线，但中文语义理解弱，检索质量一般
OpenAI text-embedding-3-small： $0.02/百万 token，8K 上下文，中文一般，无免费额度
OpenAI text-embedding-3-large： $0.13/百万 token，8K 上下文，中文中等，无免费额度
Voyage-4： $0.06/百万 token，32K 上下文，中文优秀，2 亿 token 免费额度
关键差异：
  • 中文语义理解： 本地模型 < OpenAI < Voyage，差距明显。Voyage 从 multilingual-2 时代就专门优化多语言
  • 上下文长度 32K vs 8K： 对于较长的记忆文档，Voyage 不需要截断
  • 成本： 本地模型免费但质量差；Voyage AI 每个账号 2 亿 token 免费，个人用户基本用不完

为什么选 voyage-4？

我们选了中间档 voyage-4 而不是 large 或 lite：
  • 对于记忆搜索场景，文档量不大（几十个 markdown 文件），不需要极致的 lite 省钱
  • voyage-4 的质量已经非常好，large 的边际提升对我们场景不明显
  • $0.06/M token 的价格加上 2 亿免费额度，基本等于免费用

三、配置教程

3.1 注册 Voyage AI 账号

  1. 访问 dash.voyageai.com
  1. 注册账号（支持 Google 登录）
  1. 进入 Dashboard → API Keys → Create New Key
  1. 复制 API Key
每个新账号自动获得 2 亿 token 免费额度，无需绑定信用卡。

3.2 在 OpenClaw 中配置

打开 OpenClaw 的配置文件（openclaw.json），找到或添加 memorySearch 部分，需要设置以下几个字段：
  • 把 enabled 设为 true
  • 把 provider 设为 "voyage"
  • 在 remote.apiKey 中填入你的 Voyage AI API Key（以 "pa-" 开头）
  • 把 remote.batch.enabled 设为 false（原因见下文踩坑记录）
  • 把 model 设为 "voyage-4"（或根据需求选择 voyage-4-large / voyage-4-lite）
更安全的做法是通过环境变量传递 API Key：在配置文件的 env.vars 中添加 VOYAGE_API_KEY，这样 memorySearch 部分就不需要显式写 apiKey 了。
配置完成后，重启 OpenClaw Gateway 即可。系统会自动对 memory 目录下的文件重新建立向量索引。

四、踩坑记录

坑 1：Batch 模式卡在 validating

Voyage AI 提供 Batch API，可以批量处理嵌入请求，还能享受 33% 折扣。听起来很美好，所以我们最初在配置中开启了 batch 模式。
结果：索引任务提交后，状态一直卡在 validating，永远不会变成 processing 或 completed。
原因推测：免费账号的 batch 配额或优先级可能较低，导致任务排队时间极长甚至不被处理。
解决方案： 在配置中把 batch.enabled 改为 false，关闭 batch 模式，改用实时 API。

坑 2：Rate Limit

免费账号有速率限制。在首次索引大量文件时，可能会遇到 429 错误（Too Many Requests）。
表现：索引过程中部分文件失败，日志显示 rate limit exceeded。
解决方案：
  • 不需要特别处理，OpenClaw 会自动重试
  • 如果急用，可以等几分钟后手动触发重新索引
  • 文件量不大的话（几十个 md 文件），通常第二次就能全部完成

经验总结

对于个人使用场景：关闭 batch，用实时 API，免费额度绰绰有余。

五、与 qmd 的关系

这里需要澄清一个容易混淆的点。我们的系统中有两套知识检索机制：

OpenClaw 原生 memorySearch

  • 搜索范围： MEMORY.md + memory/*.md
  • 嵌入模型： 现在用 Voyage AI（之前是 OpenAI）
  • 用途： AI 助手搜索自己的记忆和笔记
  • 受本次配置变更影响 ✅

qmd（独立知识库系统）

  • 搜索范围： 自定义知识库文档
  • 嵌入模型： 由 qmd 自身配置管理
  • 用途： 结构化知识检索
  • 不受本次配置变更影响 ❌
两套系统完全独立，互不影响。切换 Voyage AI 只改变了 OpenClaw memorySearch 的嵌入后端，qmd 继续按自己的配置运行。

六、总结

变更前： 本地嵌入模型（node-llama-cpp），零成本但中文检索弱
变更后： Voyage AI voyage-4，中文检索优秀，32K 上下文，2 亿 token 免费（Batch 模式关闭，有 bug）
切换到 Voyage AI 是一个小改动、大收益的优化。配置只需要改几行 JSON，但带来的中文检索质量提升和成本节省是实实在在的。如果你也在用 OpenClaw 并且经常使用中文，强烈建议试试。
本文基于 OpenClaw 实际使用经验撰写，Voyage AI 模型信息截至 2026 年 2 月。
Loading...

© xiyu 2021-2026