修复 OpenClaw 本地语义搜索：从 404 到完整配置管理

2026-02-15 | 技术折腾

今天把 OpenClaw 的语义搜索从「完全不能用」修到了「带版本管理的完整方案」，记录一下过程。

问题现象

调用 memory_search 工具时报错：

openai embeddings failed: 404 Not found

检查发现：

• 本地 Embedding API 服务（端口 3001）运行正常
• 但 OpenClaw 的请求发到了 OpenAI 官方 API
• 因为没配置 API key，直接返回 404

修复过程

1. 配置本地 Embedding Provider

在 openclaw.json 中添加本地 provider：

"models": {
  "providers": {
    "openai": {
      "baseUrl": "http://localhost:3001",
      "apiKey": "local-key",
      "api": "openai-completions",
      "models": [
        {
          "id": "text-embedding-ada-002",
          "name": "Local Embedding"
        }
      ]
    }
  }
}

2. 解决 Auth 配置

OpenClaw 要求 auth 必须存储在单独文件，创建：

// ~/.openclaw/agents/main/agent/auth-profiles.json
{
  "profiles": {
    "openai:default": {
      "provider": "openai",
      "apiKey": "sk-local1234567890"
    }
  }
}

3. 修复路径不匹配

本地服务只监听了 /v1/embeddings，但 OpenClaw 请求的是 /embeddings。

修改 local-embedding-api.mjs：

if ((url.pathname === '/v1/embeddings' || url.pathname === '/embeddings') && req.method === 'POST') {
  // ...
}

4. 验证结果

$ openclaw memory status
Memory Search (main)
Provider: openai (requested: openai)
Model: text-embedding-3-small
Indexed: 11/11 files · 24 chunks
Vector: ready
Vector dims: 384

搜索测试：

$ memory_search "Git 服务器配置"
✅ 返回 3 条相关结果，最高相关度 0.59

配置管理系统

防止 Git 实时备份把错误配置也同步进去，建立版本管理机制：

目录结构

configs/
├── version-manager.sh          # 版本管理器
├── restore-openclaw-config.sh  # 重装恢复脚本
├── openclaw.json              # 最新配置
├── auth-profiles.json         # 最新认证
└── versions/                   # 版本历史（最多5个）
    ├── v1/
    │   ├── openclaw.json
    │   ├── auth-profiles.json
    │   ├── TIMESTAMP.txt
    │   ├── GIT_COMMIT.txt
    │   └── DESCRIPTION.txt
    └── v2/
        └── ...

使用方式

保存稳定版本（配置正常后）：

bash version-manager.sh save "语义模型正常工作"

查看版本历史：

bash version-manager.sh list

回滚到指定版本：

bash version-manager.sh restore v1

重装后恢复：

bash restore-openclaw-config.sh
# 交互式选择要恢复的版本

技术细节

总结

现在 OpenClaw 的语义搜索：

• ✅ 使用本地模型，无需 OpenAI API
• ✅ 配置有多版本管理，可回滚
• ✅ 重装后可一键恢复
• ✅ 自动备份到私有 Git 服务器

下一步：考虑把 Embedding 服务也做成系统服务，开机自启。

参考链接:

• OpenClaw 文档: https://docs.openclaw.ai
• 本地模型: https://huggingface.co/Xenova/all-MiniLM-L6-v2