**适用人群**：本地部署、使用向量记忆、多智能体、QQBot/通道集成的用户

**实测环境**：OpenClaw 官方正式版 + 本地 Ollama 模型 + Ubuntu 系统

**核心结论前置**

1. `2026.5.x` 全系列（5.22/5.27/5.28 beta）：**记忆摄入管道原生代码BUG，新对话无法写入**，不建议生产使用；

2. `2026.4.29（build a448042 主流稳定版）`：**memory-core 插件被硬标记为不受信任**，官方向量记忆模块彻底失效，不存在“只读/半启用”状态，必须强制关闭；

3. 两个主流版本的官方记忆链路均存在硬限制，想实现**本地向量记忆、断网可用、隐私安全**，只能采用「外置独立向量库」方案。

--- ## 一、版本分坑详解（现象+根因+日志佐证+正确配置）

### 坑1：OpenClaw 2026.5.x 系列（5.22/5.27/所有Beta版）

#### 1. 故障现象 1. 记忆摄入管道状态永久为 `Ingestion state: absent`，无法初始化； 2. 所有新对话无法自动写入本地记忆日志，日志文件固定0字节； 3. 后台抛出报错：`Cannot read properties of undefined (reading 'run')`（空指针异常）； 4. 连锁问题：GPU高负载、消息回复延迟2分钟以上、进程频繁卡顿/崩溃、工具调用随机失败。

#### 2. 根因（关键） 该问题是 **5.x 版本底层代码原生BUG**，属于记忆摄入模块内部逻辑缺陷。 截至 2026-05-31，官方更新日志、社区 Issue 均**未发布对应修复补丁**。 ❌ 常规修复手段无效：清理状态文件、重置配置、重启服务、重装插件、降级/升级子版本，均无法根治，问题会反复复现。

#### 3. 版本建议 1. **生产环境严禁使用 5.x 系列**，仅适合纯测试体验； 2. 不要继续在该版本上折腾官方记忆功能，浪费时间； 3. 持续跟踪官方公告，**只有日志明确标注“修复记忆摄入管道初始化、修复空指针run报错”后，再考虑升级**。

--- ### 坑2：OpenClaw 2026.4.29（公认LTS稳定版，目前最优生产版本） > 补充说明：该版本是目前多智能体、QQBot、工具调用兼容性最好的版本，仅记忆模块存在硬限制，其余核心功能全部稳定。

#### 1. 故障现象 开启记忆相关配置后，后台持续输出日志： ``` plugin "memory-core" is not trusted Memory search disabled. narrative generation failed ``` 表现：向量搜索失效、记忆召回无结果，无论读写功能均无法使用。

#### 2. 根因（社区极少有人讲透） 在 `2026.4.29 build a448042` 主流发行版中： 1. `memory-core` 插件被**代码层硬编码为不受信任（untrusted）**，并非配置项控制； 2. **无中间状态**：不存在「开启后仅只读、不写入」的用法； 3. 只要开启 `memory-core.enabled` 或 `memorySearch.enabled`，就会触发信任校验，模块被系统强制禁用。

#### 3. 该版本【唯一正确配置】（直接复制使用） 必须彻底关闭官方自带向量记忆链路，杜绝报错与资源占用： ```json { "agents": { "defaults": { "memorySearch": { "enabled": false } } }, "plugins": { "entries": { "memory-core": { "enabled": false }, "active-memory": { "enabled": true } } } } ``` - `memorySearch.enabled: false`：关闭全局向量搜索； - `memory-core.enabled: false`：关闭底层记忆核心插件（必关）； - `active-memory.enabled: true`：可保留，用于短期上下文记忆，不依赖失效的底层向量模块。

--- ## 二、通用解决方案（绕开官方BUG，实现本地向量记忆）

### 适用场景 需要 **100%本地运行、断网可用、无云端上传、无需境外账号/付费、保护隐私** 的用户。

### 方案思路（全平台通用） 放弃 OpenClaw 自带的记忆链路，**外置独立本地向量记忆系统**，和主程序解耦： 1. 依靠 Python 轻量脚本监听 OpenClaw 本地日志，自动捕获全部对话； 2. 调用本地 Ollama 嵌入模型（如 `nomic-embed-text`）生成向量，全程本地计算； 3. 使用 `sqlite-vec` 本地向量数据库存储对话+向量，数据仅存本机； 4. 智能体通过自定义本地工具调用外置向量库完成记忆召回，无缝衔接原有业务。

### 方案优势 ✅ 完全脱离 OpenClaw 官方记忆BUG，稳定性由自己掌控； ✅ 断网正常使用，无需公网、无需境外服务器； ✅ 零成本、无需注册境外账号、无需美元支付工具； ✅ 数据全本地留存，隐私安全可控； ✅ 兼容 2026.4.29 稳定版，不影响多智能体、QQBot、股票/网页检索等核心功能。

--- ## 三、最终选型建议（按使用场景划分） 1. **生产环境/长期稳定使用** 首选 `2026.4.29`，严格按照上文配置关闭官方记忆模块，搭配**外置本地向量库**实现记忆需求。 2. **纯测试/尝鲜** 可短暂使用 2026.5.x Beta 版，提前体验新功能，但接受记忆模块永久不可用的现状。 3. **观望升级** 目前不建议升级任何新版，等待官方明确修复两大记忆BUG： - 修复 5.x 摄入管道初始化 & 空指针报错； - 修复 4.29/后续版本 `memory-core` 硬编码不受信任问题。

--- ## 四、补充避坑小贴士 1. 不要照搬网络通用教程：目前大部分公开教程仍默认开启 `memorySearch` 和 `memory-core`，在上述两个版本中均会失效； 2. 版本回滚注意：从 5.x 降级到 4.29 时，务必彻底清理旧版本残留文件、状态锁、systemd 服务，避免新旧环境冲突； 3. 资源占用：强行开启 4.29 记忆模块，会导致后台无限重试、GPU/CPU 无效占用，务必按规范关闭。