my-project/doc/LOCAL_VECTOR_CONFIG.md

# 本地向量模型配置详细解说

> **思考时间**: 5.85s  
> **主题**: OpenClaw 本地向量化服务配置  
> **适用**: 需要本地运行嵌入模型的场景

---

## 文档概述

本文档详细记录了在 OpenClaw 中配置本地向量化服务的完整过程，包括：
- 技术方案、实施步骤
- 配置代码
- 踩坑记录与解决方案

---

## 一、配置背景与目标

### 1.1 应用场景分析

| 需求 | 说明 |
|------|------|
| 数据隐私 | 敏感数据不出本地环境 |
| 成本控制 | 本地部署无 API 费用 |
| 网络稳定 | 本地服务更可靠 |
| 离线使用 | 无外网环境必需 |

### 1.2 技术选型

选择 **Ollama** 作为本地向量化平台：

| 优势 | 说明 |
|------|------|
| 开箱即用 | mxbai-embed-large 可在 CPU 高效运行 |
| OpenAI 兼容 | 与 OpenClaw "openai" provider 无缝对接 |
| 便捷管理 | 简单命令完成模型下载/更新/卸载 |

**OpenClaw provider 类型：**
- `local`: node-llama-cpp 直接运行
- `openai`: OpenAI 兼容 API（Ollama 用这个）
- `gemini`: Google Gemini 服务

---

## 二、系统环境与硬件要求

### 2.1 测试环境

| 组件 | 配置 |
|------|------|
| 设备 | ThinkPad X230 (2012年老旧笔记本) |
| CPU | Intel Core i5-3320M 双核 2.6GHz |
| 内存 | 8GB DDR3L (可用 7.7GB) |
| 存储 | SSD |
| OS | Ubuntu/Linux + systemd 用户服务 |

### 2.2 性能表现

| 模型 | mxbai-embed-large:latest |
|------|--------------------------|
| 参数 | 334M |
| 大小 | 669MB (F16量化) |
| 内存占用 | 58MB (峰值69MB) |
| 响应时间 | < 1秒 |

**结论**: 老旧硬件完全可胜任本地向量化任务。

---

## 三、Ollama 服务部署详解

### 3.1 安装流程

```bash
# 正常网络
curl -fsSL https://ollama.ai/install.sh | sh

# 如果代理干扰，用这个
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY
curl -k -fsSL https://ollama.ai/install.sh | sh
```

安装后自动：
- 下载二进制到 `/usr/local/bin/`
- 创建 systemd 服务
- 默认监听 `127.0.0.1:11434`

### 3.2 下载嵌入模型

```bash
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY
ollama pull mxbai-embed-large:latest
```

验证：
```bash
curl http://localhost:11434/api/tags
```

### 3.3 服务管理

```bash
# systemd 用户服务管理
systemctl --user status ollama      # 查看状态
systemctl --user start ollama        # 启动
systemctl --user stop ollama         # 停止
systemctl --user restart ollama      # 重启
systemctl --user disable ollama      # 禁用自启动
```

**注意**: 有两种服务位置
- 系统级: `/etc/systemd/system/ollama.service`
- 用户级: `~/.config/systemd/user/ollama.service`

---

## 四、OpenClaw 配置详解

### 4.1 配置文件结构

```
~/.openclaw/openclaw.json (JSON5格式，支持注释)

顶级字段:
├── meta          # 元数据
├── wizard        # 向导状态
├── browser       # 浏览器功能
├── models        # 模型提供商配置 ⭐
├── agents        # Agent配置 ⭐
├── tools         # 工具设置
├── messages      # 消息行为
├── commands      # 命令执行
├── channels      # 通信渠道
├── gateway       # 网关参数
└── plugins       # 插件管理
```

### 4.2 Ollama Provider 配置

```json
{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://localhost:11434/v1",
        "apiKey": "ollama-local",
        "models": [
          {
            "id": "llama3:latest",
            "name": "Llama 3",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 32768,
            "maxTokens": 8192
          },
          {
            "id": "mxbai-embed-large:latest",
            "name": "MxBai Embed",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 512,
            "maxTokens": 512
          }
        ]
      }
    }
  }
}
```

**配置要点:**
- `baseUrl`: `http://localhost:11434/v1` (`/v1` 是 OpenAI API 前缀)
- `apiKey`: 任意值，Ollama 不验证
- `models`: 列出所有可用模型

### 4.3 向量化搜索配置

```json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "minimax/minimax-m2.1",
        "fallbacks": ["deepseek/deepseek-chat"]
      },
      "memorySearch": {
        "provider": "openai",                    // ⭐ 关键：provider类型
        "model": "mxbai-embed-large:latest",     // ⭐ 必须与provider中id一致
        "remote": {
          "baseUrl": "http://localhost:11434/v1",
          "apiKey": "ollama-local"
        },
        "cache": {
          "enabled": true,
          "maxEntries": 50000
        }
      }
    }
  }
}
```

**关键说明:**
- `provider` 必须设为 `"openai"`（Ollama 是 OpenAI 兼容接口）
- `remote.baseUrl` 指定 Ollama 具体地址
- `cache` 提高性能

---

## 五、踩坑记录与解决方案

### 5.1 代理干扰问题 ⭐最重要⭐

**问题:**
```
curl 请求 127.0.0.1:11434 返回 "Empty reply from server"
```

**根因:**
代理环境变量将本地请求转发到了 `192.168.0.66:7890`

**发现:**
```
"Uses proxy env variable ALL_PROXY == 'socks5h://192.168.0.66:7890'"
```

**解决方案:**
```bash
# 方法1: 临时关闭代理
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY no_proxy NO_PROXY

# 方法2: curl 跳过代理
curl --noproxy 127.0.0.1 http://127.0.0.1:11434/api/tags
```

**教训:** 排查类似问题首先检查代理设置。

---

### 5.2 SSL 下载失败

**问题:**
```
curl: (56) OpenSSL SSL_read: ... decryption failed or bad record mac
```

**解决方案:**
```bash
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY
curl -k -fsSL https://ollama.ai/install.sh | sh
```

**教训:** 代理软件 SSL 中间人解密可能导致错误。

---

### 5.3 systemd 自动重启

**问题:** 杀掉进程后立即被 systemd 重新启动

**解决方案:**
```bash
# 先停止服务
systemctl --user stop ollama.service
systemctl --user disable ollama.service

# 再杀进程
pkill -9 ollama
```

**教训:** systemd 管理的服务要按正确顺序操作。

---

### 5.4 JSON 配置格式错误

**问题:**
```
JSON5: invalid character '"' at 175:3
```

**解决:** 用 heredoc 重写配置文件
```bash
cat > ~/.openclaw/openclaw.json << 'EOF'
{...完整正确的内容...}
EOF

# 验证
python3 -m json.tool ~/.openclaw/openclaw.json
```

---

### 5.5 batch 配置项不被识别

**问题:**
```
agents.defaults.memorySearch: Unrecognized key: 'batch'
```

**解决:** 移除不支持的配置项，只保留核心配置。

---

### 5.6 provider 命名混淆

**错误理解:** provider 应该设为 "ollama"

**正确理解:**
- `provider` = API 类型 (`openai`/`local`/`gemini`)
- `remote.baseUrl` = 具体服务地址

**教训:** 区分 provider 类型和服务实例。

---

## 六、验证与测试

### 6.1 Ollama 服务验证

```bash
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY

# 1. 检查服务
systemctl --user status ollama

# 2. 测试 API
curl http://localhost:11434/api/tags

# 3. 测试嵌入
curl -X POST http://localhost:11434/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model": "mxbai-embed-large:latest", "input": ["测试文本"]}'
```

### 6.2 OpenClaw 验证

```bash
# 验证 JSON 格式
python3 -m json.tool ~/.openclaw/openclaw.json

# 健康检查
openclaw doctor

# 查看配置加载日志
journalctl --user -u openclaw-gateway.service -n 50
```

### 6.3 重启 Gateway

```bash
systemctl --user restart openclaw-gateway
sleep 5
systemctl --user status openclaw-gateway
```

---

## 七、运维命令速查

### Ollama 管理

```bash
systemctl --user status ollama      # 状态
systemctl --user start ollama       # 启动
systemctl --user stop ollama        # 停止
systemctl --user restart ollama     # 重启
```

### OpenClaw 管理

```bash
openclaw doctor                     # 健康检查
systemctl --user restart openclaw-gateway  # 重启 Gateway
```

### 日志查看

```bash
journalctl --user -u ollama -n 50           # Ollama 日志
journalctl --user -u openclaw-gateway -n 50 # Gateway 日志
```

### 常见故障

| 故障 | 症状 | 解决 |
|------|------|------|
| 向量化无响应 | 超时 | 检查代理、Ollama 服务状态 |
| 配置不生效 | 无变化 | 重启 Gateway |
| 内存过高 | 系统慢 | 重启 Ollama 服务 |

---

## 八、性能优化

### 8.1 内存优化

| 方法 | 效果 |
|------|------|
| 更小量化模型 (Q4_0/Q5_1) | 降低 30-50% |
| 减少缓存 (10000) | 降低内存占用 |
| 按需启动 Ollama | 不用时停止 |

### 8.2 启动速度

- 使用 SSD 存储
- 保持 Ollama 持续运行

### 8.3 网络优化

**不推荐**暴露 Ollama 到外网，如需：
```bash
export OLLAMA_HOST=0.0.0.0:11434  # 允许外部访问（不推荐）
```

---

## 九、配置总结

### 成功实现

| 目标 | 状态 |
|------|------|
| 本地向量化服务 | ✅ ThinkPad X230 成功运行 |
| 嵌入模型 | ✅ mxbai-embed-large:latest (334M, F16) |
| Provider 模式 | ✅ openai (Ollama 兼容) |
| 向量记忆搜索 | ✅ 功能正常 |

### 关键成功因素

1. ✅ 准确理解 provider 类型与 remote 配置的关系
2. ✅ 正确处理代理干扰问题
3. ✅ 严格遵守 JSON 配置格式

### 经验

- 主要问题都是环境配置（代理、进程管理）
- 技术方案本身成熟可靠
- 老旧硬件完全可以胜任

---

*文档创建: 2026-02-04*