# OpenClaw Memory Search 终极指南：从原理到本地部署
# OpenClaw Memory Search 终极指南：从原理到本地部署
## Memory Search 是什么？
OpenClaw 的 **Memory Search（语义记忆搜索）** 是一套**跨会话语义召回系统**。它将笔记、对话记录等 Markdown 文件转换成数学向量（向量嵌入），使 Agent 能通过"意思相近"而非"关键词完全匹配"来检索历史信息。
例如，你搜索"投资目标"，它也能找到含有"财务规划"或"资金配置"的记录——这就是语义搜索与关键词搜索的本质区别。
这个功能依赖**外部嵌入服务（Embedding Provider）** 将文字转成向量，没有 API Key 就无法启动。
## 三条修复路径
根据你是否需要这个功能，分两大方向：
### 路径一：直接关闭（推荐新手）
如果你不需要 Agent 跨会话记住语义信息，一条命令搞定：
```bash
openclaw config set agents.defaults.memorySearch.enabled false
```
执行后 Memory Search 模块被完全禁用，不再报错，OpenClaw 其他功能完全不受影响。
### 路径二：配置嵌入服务（真正启用语义记忆）
OpenClaw 会按优先级自动检测可用的 Embedding Provider：
1. **本地模型 (local)** — `memorySearch.local.modelPath`（离线，无 API 费用）
2. **OpenAI** — `OPENAI_API_KEY`（模型：`text-embedding-3-small`）
3. **Google Gemini** — `GEMINI_API_KEY`（模型：`gemini-embedding-001`）
4. **Voyage AI** — `VOYAGE_API_KEY`（模型：`voyage-3-large`）
5. **Mistral** — `MISTRAL_API_KEY`
**方法 A：设置环境变量（以 Gemini 为例）**
```bash
export GEMINI_API_KEY=AIza-你的Key
echo 'export GEMINI_API_KEY=AIza-你的Key' >> ~/.bashrc
source ~/.bashrc
openclaw doctor --fix
```
**方法 B：通过向导配置**
```bash
openclaw configure --section model
```
向导会逐步引导选择 Provider 并输入 API Key，自动写入 `~/.openclaw/openclaw.json`。
### 路径三：使用本地模型（完全离线，零费用）
如果不想依赖任何云服务 API，可以配置本地 GGUF 格式的嵌入模型：
```bash
openclaw config set agents.defaults.memorySearch.provider local
openclaw config set agents.defaults.memorySearch.local.modelPath /你的路径/embedding-model.gguf
```
## Google Gemini 免费额度
`gemini-embedding-001` 在免费层标准输入价格为 **Free of charge**（免费），付费层每 100 万输入 tokens 收费 0.15 美元。
Google 的限制按三个维度计算：
- **RPM**（每分钟请求数）
- **TPM**（每分钟输入 tokens）
- **RPD**（每天请求数以太平洋时间午夜重置）
具体限制以 [Google AI Studio](https://aistudio.google.com/) 中显示的项目配额为准。
**实用建议**：Gemini 嵌入对中国用户性价比高——免费额度足够记忆搜索跑起来，嵌入质量优秀。但要注意，免费层提交的内容可能被用于改进产品。
## LM Studio 本地嵌入模型完整配置
为什么不直接用 OpenClaw 自带的 `local` 方案？因为那个方案依赖 `node-llama-cpp`，有时还需要 `pnpm approve-builds` 和重建原生模块。相比之下，把 LM Studio 当成 OpenAI-compatible embeddings 服务更省心。
### 原理
核心两步：
1. 在 LM Studio 里加载**嵌入模型**并启动本地服务
2. 把 OpenClaw 的 `memorySearch` 指到这个本地地址
### 准备工作
1. 在 LM Studio 里加载一个**嵌入模型**（不是聊天模型），如 `text-embedding-nomic-embed-text-v1.5` 或 `Qwen3-Embedding-8B`
2. 打开 LM Studio 的 Local Server 页面，点击 **Start Server**（默认端口 1234）
### 验证服务
```bash
curl http://127.0.0.1:1234/v1/models
curl -s http://127.0.0.1:1234/v1/models | jq '.data[].id'
```
如果返回 `invalid_api_key`，说明开启了认证——在 Server Settings 关闭 **Require Authentication**，或带上 Bearer token。
### 配置命令
```bash
openclaw config set agents.defaults.memorySearch.enabled true
openclaw config set agents.defaults.memorySearch.provider openai
openclaw config set agents.defaults.memorySearch.model text-embedding-nomic-embed-text-v1.5
openclaw config set agents.defaults.memorySearch.remote.baseUrl http://127.0.0.1:1234/v1/
openclaw config set agents.defaults.memorySearch.remote.apiKey lm-studio
openclaw config set agents.defaults.memorySearch.fallback none
```
> ⚠️ `model` 必须和 `/v1/models` 返回的模型 id 完全一致，前面加 `text-embedding-` 前缀是常见情况。
### 进阶：Qwen3-Embedding-8B 配置
对于中文用户，更推荐 **`Qwen3-Embedding-8B`**——支持 100+ 语言、32k 上下文，MTEB 多语言榜第一（2025 年 6 月）。
```bash
openclaw config set agents.defaults.memorySearch.model qwen3-embedding-8b
```
LM Studio 参数设置：
| 参数 | 推荐值 |
|------|--------|
| API 标识符 | `qwen3-embedding-8b` |
| 上下文长度 | `4096` |
| GPU 卸载 | 最大 |
| 评估批处理大小 | `512` |
| RoPE 频率基/比例 | 自动 |
| 保持模型在内存中 | 开 |
| 尝试 mmap() | 开 |
RTX 4070 12GB 可完整加载 Q8_0 版本进显存。
### 重启并诊断
```bash
systemctl --user restart openclaw-gateway.service
openclaw doctor --fix
```
## 配置后的进阶参数
启用后，可以在 `~/.openclaw/openclaw.json` 中微调语义搜索行为：
```json
{
"agents": {
"defaults": {
"memorySearch": {
"enabled": true,
"provider": "openai",
"maxResults": 8,
"vectorWeight": 0.7,
"textWeight": 0.3,
"sync": { "watch": true }
}
}
}
}
```
| 参数 | 说明 |
|------|------|
| `vectorWeight` | 语义相似度占比（0-1） |
| `textWeight` | 关键词匹配占比（0-1） |
| `maxResults` | 每次检索返回的最相关条目数 |
| `sync.watch: true` | 监听 memory 文件夹变化，自动重建向量索引 |
## 分场景模型推荐
| 场景 | 推荐模型 | 核心优势 |
|------|---------|---------|
| 默认通用、本地先跑通 | `EmbeddingGemma 300M` | 支持 100+ 语言，LM Studio 直接支持，体积仅 300M |
| 中文效果优先 | `Qwen3-Embedding-8B` | MTEB 多语言榜第一，32k 上下文 |
| 英文高质量检索 | `mxbai-embed-large` | MTEB SOTA，号称超过 text-embedding-3-large |
| 极致轻量、CPU 优先 | `all-MiniLM-L6-v2` | 仅 384 维，22M 参数，CPU 推理极快 |
| 超长上下文文档 | `BGE-M3` | 最高 8192 tokens，支持 dense/sparse/multi-vector |
## 决策建议
对于中国用户：
1. **轻度使用** → 直接关闭，毫无损失
2. **先跑通** → `EmbeddingGemma 300M`（Gemini 免费额度也够用）
3. **中文 + 多语言效果优先** → `Qwen3-Embedding-8B` + LM Studio 本地部署
一句话总结：**先用 `EmbeddingGemma 300M` 跑通，中文效果不够再升级到 `Qwen3-Embedding-8B`。**
***
--全文完--
***
{{< admonition type=question title="若你有故事想讲、有困惑想聊、或是想找个人说说心里话，甚至只是吐槽发泄一下情绪，都欢迎来找我聊聊： 《内容已折叠，点击展开》 " open=false >}}
{{< typeit tag=h4 >}}
**"同频之人，终会相遇；同行之路，终有光亮。愿与身处同境、灵魂同频、砥砺前行的你相遇相伴，倾听彼此的故事与困惑，分享心路与感悟，在逆境中自救破局的路上彼此陪伴、相互照亮、同行向前,一起走向重生与新生。"**...
{{< /typeit >}}
点击跳转：关于我
{{< /admonition >}}
***
{{< admonition type=success title="希望我写的每一个字，成为我自己和某个人活下去、拼下去的力量。 《内容已折叠，点击展开》" open=false >}}
"技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。"
转载请注明来自https://oklife.me。
{{< /admonition >}}
{{< /admonition >}}