夜雨聆风
## 一、背景
瑞吉娜是运行在极空间NAS Docker容器中的OpenClaw智能体，负责财经新闻抓取、简报生成和知识库构建。为了支持千万级文本的语义检索，我为其配置了本地向量搜索，使用QMD（Query Memory Document）后端，搭载`embeddinggemma-300M`等模型。
但自3月20日上午起，瑞吉娜出现飞书消息卡在“Gathering information”，无法回复。伴随容器CPU飙升（最高达333%）、端口冲突（18790被多个网关进程占用）、反复杀进程后立即重生等问题，导致服务不可用。
## 二、问题现象
1. **飞书交互异常**：消息发送后，OpenClaw网关显示“Gathering information”无限转圈，无最终回复。
2. **资源占用**：容器内`openclaw-gateway`进程CPU占用率高达100%~333%，内存持续增长。
3. **进程残留**：使用`pkill`无法彻底清除网关进程，新启动的网关总报“port already in use”，且PID不断递增。
4. **日志特征**：
- `Multiple listeners detected`
- `Gateway already running locally`
- `memory embeddings query timed out after 300s`
- `qmd update failed (Error: spawn qmd ENOENT)`
## 三、根本原因分析
1. **OpenClaw 3.8版本已知缺陷**：官方社区确认3.8的本地向量引擎（`local` provider）存在资源泄漏和进程管理bug，长时间运行或高频调用时易导致网关僵死和端口残留。
2. **模型下载网络问题**：首次启动向量搜索时，OpenClaw会从HuggingFace自动下载`embeddinggemma-300M`（约328MB）等模型文件，国内访问极慢，导致超时（300秒）后自动降级，但下载不完整，后续请求仍卡住。
3. **定时任务与网关冲突**：瑞吉娜配置了密集的定时任务（如`regina盯盘`），在网关启动瞬间尝试执行，干扰了端口绑定和进程初始化。
4. **配置残留**：之前尝试过手动指定`modelPath`等无效配置，导致配置验证失败，网关启动异常。
## 四、解决过程
### 阶段一：基础清理与降级（临时恢复）
1. **清理网关进程**：
```bash
docker exec -it -u root regina-openclaw pkill -f openclaw
```
反复执行，直到`ps aux`无相关进程。
2. **禁用向量搜索，改用内置搜索**：
```bash
openclaw config set memory.backend builtin
openclaw gateway restart
```
此时飞书恢复基础对话能力（但仅支持关键词搜索）。
### 阶段二：升级OpenClaw至3.13版本
官方在3.13中修复了本地模型的进程管理和超时问题，因此决定升级。
1. **备份数据卷**：
```bash
mkdir -p /tmp/regina-backup
cp -r /tmp/zfsv3/sata11/13339035399/data/docker/regina /tmp/regina-backup/regina-$(date +%Y%m%d-%H%M)
```
2. **拉取3.13镜像**（国内源）：
```bash
docker pull registry.cncfstack.com/cncfstack/openclaw-in-docker:v2026.3.13-1-v0.1.2
```
3. **重建容器**（保留数据卷）：
```bash
docker stop regina-openclaw && docker rm regina-openclaw
docker run -d \
--name regina-openclaw \
--restart unless-stopped \
--network host \
--privileged \
-v /tmp/zfsv3/sata11/13339035399/data/docker/regina:/home/node/.openclaw \
-e OPENCLAW_TZ="Asia/Shanghai" \
registry.cncfstack.com/cncfstack/openclaw-in-docker:v2026.3.13-1-v0.1.2
```
> 注：`--privileged`解决容器内mount权限问题。
4. **运行doctor修复配置**：
```bash
docker exec -it -u node regina-openclaw openclaw doctor --fix
```
### 阶段三：恢复向量搜索（使用本地模型）
1. **设置HuggingFace镜像加速**：
```bash
export HF_ENDPOINT=https://hf-mirror.com
```
2. **删除可能损坏的缓存**：
```bash
rm -rf /home/node/.cache/openclaw/embeddings
```
3. **触发向量模型下载**：
```bash
openclaw memory search "测试"
```
观察到从镜像站下载`embeddinggemma-300M`，速度稳定，约6分钟完成。
4. **验证模型加载**：
```bash
openclaw memory search "测试"
```
输出成功返回记忆片段（包含`Cron: regina盯盘`等条目），向量搜索生效，无超时。
5. **最终配置确认**：
- `memory.backend` 为 `builtin`（实际内置搜索+向量？3.13默认混合？）
- `agents.defaults.memorySearch.provider` 为 `local`（自动启用本地向量）
- 模型文件位于 `/home/node/.cache/openclaw/embeddings/`（约328MB）
## 五、关键技术点
1. **OpenClaw版本差异**：
- 3.8：本地向量搜索存在进程残留、超时处理不完善。
- 3.13：修复了上述问题，且对国内网络环境做了优化（支持环境变量设置镜像）。
2. **模型下载机制**：
- OpenClaw 首次调用`memory search`时，通过`node-llama-cpp`自动下载所需GGUF模型。
- 默认从HuggingFace官方源，可设置`HF_ENDPOINT`切换镜像。
3. **资源影响**：
- 模型文件约328MB，加载后网关内存增加约1GB，CPU在推理时瞬时飙升。
- 使用内置搜索（`memory.backend builtin`）时，模型仅在检索时加载，平时内存占用较低。
4. **容器管理**：
- 重启容器会保留所有挂载数据卷，但容器内进程被清空，是解决进程残留的有效手段。
- `--privileged`用于解决mount操作权限，但会增加安全风险，实际可考虑`--cap-add=SYS_ADMIN`。
## 六、最终状态
- **版本**：OpenClaw 3.13
- **向量搜索**：启用本地`embeddinggemma-300M`模型，语义检索正常
- **飞书对话**：恢复稳定，消息秒回
- **CPU/内存**：日常约5%-10%，检索时短时飙升至100%但迅速回落
- **定时任务**：全部恢复运行
## 七、后续建议
1. **短期观察**：运行一周，关注`docker stats`资源曲线，确认无内存泄漏。
2. **备选方案**：若再出现类似问题，可切换至Ollama外挂模式，将模型服务与OpenClaw解耦，提升稳定性。
3. **网络优化**：可预先将常用GGUF模型下载到本地，避免首次使用时网络波动。
4. **配置固化**：将当前可用配置（`memory.backend`、`memorySearch`）记录到文档，便于快速恢复。
---
本次问题的根本在于3.8版本的底层缺陷叠加网络不稳定，通过版本升级、合理配置镜像、耐心等待下载，最终实现了向量搜索的稳定运行。过程中对OpenClaw的进程管理、配置体系、资源模型有了深刻理解，为后续维护积累了宝贵经验。
PS:为什要死磕向量搜索？——从“关键词机器”到“真正懂你的图书管理员”
关键词搜索（FTS）：• 你说“矛盾”，它只能找包含“矛盾”二字的段落。• 对“对立统一”、“转化”、“斗争”视而不见。 • 像在图书馆里按书名找书，找不到就是找不到。****************************************************************************向量搜索（语义检索）：• 你说“矛盾”，它能找到所有讨论辩证关系的段落，无论用词如何。• 跨语言、跨领域，发现隐藏的关联和思想脉络。• 像让一个读过所有书的图书管理员，根据你的模糊描述， 从千万册书中精准找出你真正需要的那几页。这是AI的“大脑皮层”，让瑞吉娜从“信息搬运工” 升级为“知识策展人”。
