April 16, 2026 • 版本: 2026.4.5 - 2026.4.8

未知记忆嵌入提供商：ollama — v2026.4.x 中的回归问题

OpenClaw 在配置使用 ollama 提供商时初始化记忆嵌入失败，抛出 'Unknown memory embedding provider: ollama' 错误，这是由于提供商注册表回归问题导致的。

🔍 症状

OpenClaw 内存子系统在使用 ollama 作为嵌入提供程序时初始化失败。该错误在 CLI 和网关运行时环境中的表现完全相同。

CLI 执行失败：

$ openclaw memory status

🦞 OpenClaw 2026.4.8 (9ece252) — iMessage green bubble energy, but for everyone.

[openclaw] Failed to start CLI: Error: Unknown memory embedding provider: ollama
    at getAdapter (file:///home/openclaw/.npm-global/lib/node_modules/openclaw/dist/manager-BRmgtjii.js:317:22)
    at createEmbeddingProvider (file:///home/openclaw/.npm-global/lib/node_modules/openclaw/dist/manager-BRmgtjii.js:369:25)
    at MemoryIndexManager.loadProviderResult (file:///home/openclaw/.npm-global/lib/node_modules/openclaw/dist/manager-BRmgtjii.js:2706:16)
    at file:///home/openclaw/.npm-global/lib/node_modules/openclaw/dist/manager-BRmgtjii.js:2811:52)
    at MemoryIndexManager.ensureProviderInitialized (file:///home/openclaw/.npm-global/lib/node_modules/openclaw/dist/manager-BRmgtjii.js:2819:5)
    at MemoryIndexManager.probeVectorAvailability (file:///home/openclaw/.npm-global/lib/node_modules/openclaw/dist/manager-BRmgtjii.js:3168:14)
    at Object.run (file:///home/openclaw/.npm-global/lib/node_modules/openclaw/dist/cli.runtime-CN0Ckcb_.js:325:25)

网关进程失败：

23:28:54+00:00 error Memory index failed (main): Unknown memory embedding provider: ollama

诊断指标：

在 2026.4.5 之前的版本中，相同配置下的先前安装可以正常工作
CLI 的 memory status 和 memory index 命令均失败
网关内存索引计划任务失败，静默记录错误
其他非内存的 ollama 操作（聊天补全）继续正常运行

🧠 根因分析

堆栈跟踪显示内存嵌入初始化链中的提供程序注册表查找失败。错误源于：

getAdapter (manager-BRmgtjii.js:317:22)
createEmbeddingProvider (manager-BRmgtjii.js:369:25)

技术分析

提供程序注册表隔离： 在受影响的版本中，嵌入提供程序注册表使用与 LLM 提供程序注册表分开的查找表。字符串 "ollama" 对于聊天补全有效，但未在嵌入特定的适配器映射中注册。
静默提供程序映射回归： 在 v2026.4.5 之前，内存子系统执行隐式提供程序规范化——将运行时提供程序名称映射到正确的嵌入适配器。此规范化在回归中被移除或重构，导致连接断开。
代码路径分析：

MemoryIndexManager.probeVectorAvailability()
  → ensureProviderInitialized()
    → loadProviderResult()         // Line 2706
      → createEmbeddingProvider()  // Line 369 — FAILS HERE
        → getAdapter()             // Line 317 — Unknown provider lookup

getAdapter() 函数对 ADAPTER_REGISTRY 执行直接映射查找。由于 “ollama” 从未添加到此注册表（或在重构期间被移除），查找返回 undefined，触发错误。

受影响的配置模式

以下配置模式的用户受到影响：

// openclaw.yaml or openclaw.json
memory:
  embedding:
    provider: ollama
    model: nomic-embed-text:latest
  // ...

内存子系统期望提供程序存在于嵌入适配器注册表中，但 ollama 仅注册在 LLM 适配器注册表中，而非嵌入特定的注册表中。

🛠️ 逐步修复

选项 A：使用 OpenAI-Compat 提供程序（推荐）

Ollama 的 API 与 OpenAI 兼容。将内存嵌入配置为使用指向本地 ollama 端点的 openai-compat 提供程序：

修复前（损坏）：

memory:
  embedding:
    provider: ollama
    model: nomic-embed-text:latest

修复后（已修复）：

memory:
  embedding:
    provider: openai-compat
    model: nomic-embed-text:latest
    apiKey: not-required
    baseURL: http://localhost:11434/v1

选项 B：使用带完整路径的 Ollama 提供程序

如果您的安装包含 ollama 插件，请指定完整的提供程序路径：

memory:
  embedding:
    provider: @openclaw/provider-ollama
    model: nomic-embed-text:latest

选项 C：环境变量覆盖

在运行时覆盖提供程序，无需修改配置文件：

$ OPENCLAW_MEMORY_EMBEDDING_PROVIDER=openai-compat \
  OPENCLAW_MEMORY_EMBEDDING_BASE_URL=http://localhost:11434/v1 \
  openclaw memory status

配置验证

确保您的完整内存配置与此结构匹配：

memory:
  enabled: true
  embedding:
    provider: openai-compat
    model: nomic-embed-text:latest
    apiKey: not-required
    baseURL: http://localhost:11434/v1
    dimensions: 768  # Required for nomic-embed-text
  index:
    enabled: true
    chunkSize: 512
    overlap: 64

🧪 验证

步骤 1：验证提供程序连接

$ curl -s http://localhost:11434/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model": "nomic-embed-text:latest", "input": "test"}' \
  | jq '.data[0].embedding[:5]'

预期输出：

[
  -0.02187623,
  0.04312847,
  -0.05898431,
  0.02345612,
  -0.03456789
]

步骤 2：测试 CLI 内存状态

$ openclaw memory status

🦞 OpenClaw 2026.4.8 (9ece252) — iMessage green bubble energy, but for everyone.

✅ Memory System Ready
   Provider: openai-compat
   Model: nomic-embed-text:latest
   Dimensions: 768
   Status: Connected

预期：退出代码 0，无错误。

步骤 3：验证向量可用性

$ openclaw memory index --dry-run

✅ Embedding provider verified
   Vector dimensions: 768
   Average latency: 45ms

步骤 4：确认网关运行

重启网关并检查日志以确认内存初始化成功：

$ systemctl restart openclaw-gateway
$ journalctl -u openclaw-gateway -n 20 --no-pager | grep -i memory

预期输出应不包含任何错误，并确认提供程序初始化。

⚠️ 常见陷阱

大小写敏感性： 提供程序名称区分大小写。使用 openai-compat（小写，连字符），而不是 openaiCompat 或 OpenAI-Compat。
端口冲突： 确保端口 11434 未被其他服务使用。使用 ss -tlnp | grep 11434 进行验证。
API 密钥不匹配： Ollama 不需要 API 密钥。使用 sk-... 占位符可能导致身份验证失败。使用 apiKey: not-required 或 apiKey: ""。
模型名称不匹配： 确保模型名称与 ollama 报告的完全一致。运行 curl http://localhost:11434/api/tags 列出可用模型并验证确切的字符串。
Docker 网络： 如果在 Docker 中运行 OpenClaw 且 ollama 在主机上，请使用 host.docker.internal（macOS）或 172.17.0.1（Linux）而不是 localhost。
维度不匹配： nomic-embed-text 输出 768 维向量。如果您的向量数据库期望不同的维度计数，请明确指定 dimensions: 768。
插件加载： 如果使用选项 B，请确保插件已安装：npm list @openclaw/provider-ollama。如果缺失，通过 npm install -g @openclaw/provider-ollama 安装。
配置文件位置： 确保配置在正确位置：~/.openclaw/config.yaml 或 /etc/openclaw/config.yaml。运行 openclaw config show 验证已加载的配置。

🔗 相关错误

E_PROVIDER_NOT_FOUND — 通用提供程序解析失败，通常表示缺少插件或提供程序名称中的拼写错误。
E_EMBEDDING_INIT_FAILED — 嵌入提供程序已初始化，但在首次嵌入生成时失败（身份验证、网络、模型未找到）。
E_VECTOR_DIMENSION_MISMATCH — 提供程序返回的向量维度与数据库架构期望不匹配。
Issue #62282 — 相同错误的先前报告，据称在 2026.4.8 中已修复。用户报告在 2026.4.5 和 2026.4.8 中都存在回归。
Unknown memory embedding provider: azure-openai — 相同模式影响 Azure OpenAI 嵌入；解决方法（使用带 Azure 端点的 openai-compat）适用。
Unknown memory embedding provider: bedrock — AWS Bedrock 嵌入受相同注册表隔离问题影响。