April 16, 2026 • 版本: 2026.4.12

CLI 内存命令因'Unknown memory embedding provider: ollama'而崩溃

CLI 内存命令（status、backup、rebuild）崩溃，原因是 ollama 嵌入提供程序由插件在运行时注册，但 CLI 代码路径不加载插件，导致硬编码的提供程序查找失败。

🔍 症状

当使用配置了 ollama provider 的 CLI memory 命令时，命令会立即终止并抛出 JavaScript 错误。

错误输出

$ openclaw memory status
Error: Unknown memory embedding provider: ollama
    at getAdapter (manager-FzeN0TEi.js:341:22)
    at createEmbeddingProvider (manager-FzeN0TEi.js:393:25)
    at MemoryIndexManager.loadProviderResult (manager-FzeN0TEi.js:2759:16)

$ openclaw memory backup
Error: Unknown memory embedding provider: ollama
    at getAdapter (manager-FzeN0TEi.js:341:22)
    at createEmbeddingProvider (manager-FzeN0TEi.js:393:25)
    at MemoryIndexManager.loadProviderResult (manager-FzeN0TEi.js:2759:16)

$ openclaw memory rebuild
Error: Unknown memory embedding provider: ollama
    at getAdapter (manager-FzeN0TEi.js:341:22)
    at createEmbeddingProvider (manager-FzeN0TEi.js:393:25)
    at MemoryIndexManager.loadProviderResult (manager-FzeN0TEi.js:2759:16)

受影响的命令

openclaw memory status
openclaw memory backup
openclaw memory rebuild

正常工作的代码路径（Gateway）

Gateway 运行时能正确处理内存搜索，因为插件初始化发生在内存系统初始化之前：

# Gateway memory_search 正常工作
$ openclaw gateway memory_search "test query"
[使用 ollama embeddings 返回结果]

触发该 Bug 的配置

# ~/.openclaw/config.yaml
agents:
  defaults:
    memorySearch:
      provider: "ollama"
      model: "snowflake-arctic-embed2"
      remote:
        baseUrl: "http://192.168.1.100:11434"
      fallback: "none"

🧠 根因分析

架构分歧：插件注册与 CLI 代码路径

内存嵌入 provider 系统有两种注册机制，但初始化顺序不兼容。

机制一：基于插件的注册（Gateway 可用）

ollama 插件 通过插件 API 在运行时注册其嵌入 provider：

// extensions/ollama/index.js
api.registerMemoryEmbeddingProvider(ollamaMemoryEmbeddingProviderAdapter);

此注册发生在插件初始化阶段，该阶段在 gateway 运行时的内存系统完全初始化之前运行。

机制二：硬编码的内置注册（仅 CLI）

CLI memory 命令调用 registerBuiltInMemoryEmbeddingProviders()，它填充一个硬编码数组：

// manager-FzeN0TEi.js（编译后的捆绑包）
const builtinMemoryEmbeddingProviderAdapters = [
  'local',
  'openai',
  'gemini',
  'voyage',
  'mistral'
];

function registerBuiltInMemoryEmbeddingProviders() {
  for (const adapter of builtinMemoryEmbeddingProviderAdapters) {
    // 使用其关联的元数据注册每个 adapter
  }
}

失败序列

用户执行 openclaw memory status
CLI 初始化一个 MemoryIndexManager 实例
使用配置的 provider（"ollama"）调用 MemoryIndexManager.loadProviderResult()
createEmbeddingProvider() 调用 getAdapter()
getAdapter() 在内部注册表中查找 "ollama"
由于 CLI 从未加载插件，"ollama" 不在注册表中
抛出错误："Unknown memory embedding provider: ollama"

Gateway 为何能正常工作

Gateway 运行时在初始化任何子系统之前显式加载并初始化所有已启用的插件：

// Gateway 初始化序列（简化版）
await pluginManager.loadPlugins();           // 加载 extensions/ollama/index.js
await pluginManager.initializePlugins();     // 调用 api.registerMemoryEmbeddingProvider()
await memoryManager.initialize();            // 现在注册表中包含 ollama

更广泛的影响

builtinMemoryEmbeddingProviderAdapters 数组缺少多个文档化的 provider：

ollama - 第一方捆绑扩展（此 bug）
lmstudio - 在运行时 schema 中记录为有效
bedrock - 在运行时 schema 中记录为有效

所有这些在使用 CLI memory provider 时都会表现出相同的崩溃行为。

隐私/安全副作用

当使用 provider: “auto” 作为变通方法时，自动选择优先级链为：

local(10) → openai(20) → gemini(30) → voyage(40) → mistral(50)

由于 ollama 没有定义 autoSelectPriority，自动选择永远不会选中它。寻求本地/自托管嵌入的用户可能会无意中将其内存数据发送到 OpenAI 的服务器。

🛠️ 逐步修复

推荐的修复：将 Ollama 添加到内置 Provider

修改 manager 捆绑包中的 builtinMemoryEmbeddingProviderAdapters 数组以包含 ollama。

修复前

// manager-FzeN0TEi.js（约第 XXX 行）
const builtinMemoryEmbeddingProviderAdapters = [
  'local',
  'openai',
  'gemini',
  'voyage',
  'mistral'
];

修复后

// manager-FzeN0TEi.js（约第 XXX 行）
const builtinMemoryEmbeddingProviderAdapters = [
  'local',
  'openai',
  'gemini',
  'voyage',
  'mistral',
  'ollama'
];

实施步骤

在源 manager 文件中找到 builtinMemoryEmbeddingProviderAdapters 定义（不是编译后的捆绑包）
将 'ollama' 作为数组的最后一个元素添加
重新构建应用程序捆绑包
或者，向 OpenClaw 仓库提交 pull request

替代修复：在 CLI Memory 命令中加载插件

如果首选解决方案是在 CLI 和 gateway 之间保持功能对等：

// 在 CLI memory 命令初始化中（伪代码）
async function initializeMemoryCommands() {
  // 在初始化内存系统之前加载插件
  await pluginManager.loadPlugins();
  await pluginManager.initializePlugins();
  
  // 现在 ollama（和其他插件 provider）已注册
  registerBuiltInMemoryEmbeddingProviders();
  
  // 继续进行命令设置
}

临时变通方法（不建议用于生产环境）

将 provider 更改为内置 provider 之一：

# ~/.openclaw/config.yaml
agents:
  defaults:
    memorySearch:
      provider: "local"  # 使用 local 而非 ollama
      # 或者如果您有 API key，使用 "openai"
      # 或者使用 "auto"（但请注意隐私影响）

🧪 验证

应用修复后，通过运行受影响的 CLI 命令进行验证。

测试命令

# 测试 1：Memory status 命令
$ openclaw memory status
✓ Connected to memory index
✓ Provider: ollama
✓ Model: snowflake-arctic-embed2
✓ Endpoint: http://192.168.1.100:11434
✓ Status: Ready

# 测试 2：Memory backup 命令
$ openclaw memory backup --output ./memory-backup.json
✓ Backup completed successfully
✓ Records: 1,247 entries
✓ File: ./memory-backup.json

# 测试 3：Memory rebuild 命令
$ openclaw memory rebuild --provider ollama
✓ Rebuild initiated
✓ Processing embeddings...
✓ Complete: 1,247 records re-embedded

预期的退出码

所有命令在成功时都应以退出码 0 结束。

集成测试：CLI 与 Gateway 对等性

验证两种代码路径产生相同的结果：

# 通过 CLI 运行相同的查询
$ openclaw memory search "meeting notes from last week" --limit 5
[
  {
    "id": "mem_abc123",
    "content": "Quarterly planning meeting...",
    "score": 0.94
  }
]

# 通过 gateway 运行相同的查询
$ openclaw gateway memory_search "meeting notes from last week"
[
  {
    "id": "mem_abc123",
    "content": "Quarterly planning meeting...",
    "score": 0.94
  }
]

# 结果应该匹配

测试所有先前受影响的 Provider

验证其他基于插件的 provider（lmstudio、bedrock）如果也被添加也会被修复：

# 如果 lmstudio 被添加到内置 provider
$ openclaw memory status --provider lmstudio
✓ Provider: lmstudio
✓ Model: your-configured-model
✓ Status: Ready

⚠️ 常见陷阱

环境特定陷阱

Apple Silicon（macOS arm64）： Apple Silicon 上的 Ollama 可能需要 Rosetta 2 来运行某些模型。在执行 memory 命令之前确保 ollama serve 正在运行。
Docker 环境： 如果 OpenClaw 在 Docker 中运行，请确保 Ollama 端点可从容器网络访问。使用 --network=host 或配置正确的网络。
Tailscale/远程端点： 使用 Tailnet IP 时，验证 Tailscale 守护进程正在运行且子网已发布。

配置陷阱

端点 URL 格式： base URL 必须包含端口。错误：http://192.168.1.100/ollama，正确：http://192.168.1.100:11434
模型名称不匹配： 确保模型名称与 Ollama 中可用的名称完全匹配。运行 ollama list 进行验证。
Fallback 配置： 设置 fallback: "none" 将导致在 Ollama 无法访问时立即失败。考虑使用 fallback: "local" 以提高弹性。

“auto” 变通方法的隐私影响

# 错误：使用 auto-select 作为变通方法
agents:
  defaults:
    memorySearch:
      provider: "auto"  # ⚠️ 将数据发送到 OpenAI！

# 正确：显式指定本地 provider
agents:
  defaults:
    memorySearch:
      provider: "ollama"  # ✓ 保持在本地

误解：插件与内置的区别

许多用户不知道 provider 分为两类：

内置 Provider： 硬编码在 manager 中，始终可用
插件 Provider： 在运行时由插件注册

这种区别没有文档化，导致 CLI 命令失败时用户感到困惑。

版本兼容性

此 bug 影响版本 2026.4.12。如果从早期版本升级，请验证 ollama 插件与新的 manager 捆绑包兼容。

🔗 相关错误

直接相关的错误

Unknown memory embedding provider: lmstudio — 相同的 bug 影响 lmstudio provider（也是插件注册的）
Unknown memory embedding provider: bedrock — 相同的 bug 影响 bedrock provider（也是插件注册的）
Unknown memory embedding provider: [任何插件注册的 provider] — 此 bug 的一般化形式

上下文相关的错误

Plugin initialization failed: ollama — 当 ollama 插件加载失败时发生，在某些场景下可能掩盖此错误
ECONNREFUSED — 当 Ollama 端点无法访问时的网络错误；与 provider 注册错误不同
Model not found: [model-name] — Ollama 服务器没有请求的模型；不同的错误路径

历史背景

2026.3.x： 插件系统引入用于扩展，包括 ollama provider
2026.4.x： CLI memory 命令提取到单独入口点，该入口点绕过插件初始化
2026.4.12： 当前版本存在此差异 bug（此问题）

代码库中的类似模式

相同的架构模式（内置 vs 插件注册）存在于：

Memory retrieval provider
LLM provider
工具适配器

这些可能表现出类似的 CLI 与 gateway 不一致。