[未知内存嵌入提供程序：ollama] - Unknown memory embedding provider: ollama - Troubleshooting Guide

错误表现

当使用 ollama 作为内存嵌入提供程序执行 openclaw memory status --deep 命令时，CLI 会立即终止并返回提供程序解析失败：

$ openclaw memory status --deep

🦞 OpenClaw 2026.4.12 (1c0672b) — If something's on fire, I can't extinguish it—but I can write a beautiful postmortem.

│
◇  
[openclaw] Failed to start CLI: Error: Unknown memory embedding provider: ollama

技术表现

• 退出代码: 非零（通常为 1）
• 错误类型: ProviderResolutionError 或内存子系统中的等效错误
• 错误信息: Unknown memory embedding provider: ollama
• 堆栈跟踪位置: 可能在 packages/core/src/memory/providers/registry.ts 或类似位置

受影响的配置

当 OpenClaw 配置包含以下内容时会发生此错误：

{
  "memory": {
    "embedding": {
      "provider": "ollama",
      "model": "qwen3-embedding:0.6b"
    }
  }
}

或通过环境变量：

$ export OPENCLAW_MEMORY_EMBEDDING_PROVIDER=ollama
$ export OPENCLAW_MEMORY_EMBEDDING_MODEL=qwen3-embedding:0.6b

回归时间线

• 最后正常版本: 2026.04.10
• 首次失败版本: 2026.04.12
• 版本间隔: 2 天的提交

主要根因：提供程序注册表回归

此错误源于内存嵌入提供程序注册表系统的回归。ollama 提供程序可能存在以下情况：

1. 在重构提交期间从提供程序注册表中被移除（2026.04.10 到 2026.04.12 之间）
2. 被重命名但未保持向后兼容性（例如 "ollama" → "ollama-embedding" 或 "ollama/text-embedding-2"）
3. 由于树摇问题或条件导入而被排除在构建包之外
4. 基于默认为禁用的功能标志进行条件注册

代码流程分析

失败序列遵循以下路径：

CLI Entry (memory/status.ts)
  → MemoryService.initialize()
    → EmbeddingProviderFactory.resolve("ollama")
      → ProviderRegistry.get("ollama")
        → ❌ throws "Unknown memory embedding provider: ollama"

可能的提交模式

根据回归时间范围，重构提交可能更改了提供程序注册机制：

之前（正常工作）：

// packages/core/src/memory/providers/index.ts
export { OllamaEmbeddingProvider } from './ollama';
// 通过静态副作用或显式注册调用自动注册

之后（损坏）：

// packages/core/src/memory/providers/index.ts
// OllamaEmbeddingProvider 导出被移除或设为条件
// 提供程序未自动注册

替代根因：配置架构变更

提供程序名称可能在配置架构中发生了更改：

// 旧配置键 (2026.04.10)
memory.embedding.provider = "ollama"

// 新配置键 (2026.04.12)
memory.embedding.provider = "ollama-embed"  // 或
memory.embedding.provider = "ollama/text-embedding-2"

验证命令

要诊断根因，请检查可用的提供程序：

$ openclaw memory providers list
# 或
$ cat ~/.openclaw/config.json | jq '.memory.embedding'

选项 1：回滚到之前的提供程序名称（快速修复）

如果提供程序已被重命名，请使用新的配置值：

# 检查当前 OpenClaw 版本
openclaw --version

# 列出可用的内存嵌入提供程序
openclaw memory status --help 2>&1 | grep -i provider

# 更新配置以使用正确的提供程序名称
openclaw config set memory.embedding.provider ollama-embedding
# 或
openclaw config set memory.embedding.provider ollama/text-embedding-2

选项 2：通过插件强制重新注册（临时解决方案）

如果提供程序代码存在但未自动注册：

# 创建本地插件以重新注册提供程序
mkdir -p ~/.openclaw/plugins/ollama-fix
cd ~/.openclaw/plugins/ollama-fix

cat > plugin.ts << 'EOF'
import { registerEmbeddingProvider } from '@openclaw/core';

export function registerOllamaProvider() {
  registerEmbeddingProvider('ollama', {
    name: 'ollama',
    createClient: () => new OllamaEmbeddingClient()
  });
}
EOF

# 在配置中启用插件
openclaw config set plugins.enabled "['ollama-fix']"

选项 3：重新安装 OpenClaw（彻底修复）

卸载并重新安装以获取已知良好的配置：

# 备份当前配置
cp -r ~/.openclaw ~/.openclaw.backup.$(date +%Y%m%d)

# 重新安装 OpenClaw
npm uninstall -g @openclaw/cli
npm install -g @openclaw/cli@latest

# 重新配置 ollama 提供程序
openclaw config set memory.embedding.provider ollama
openclaw config set memory.embedding.model qwen3-embedding:0.6b

选项 4：固定到正常版本（临时修复）

如果回归阻止了生产使用：

# 卸载当前版本
npm uninstall -g @openclaw/cli

# 安装最后已知正常版本
npm install -g @openclaw/cli@2026.04.10

# 验证版本
openclaw --version

配置文件手动编辑

如果 CLI 命令失败，请直接编辑配置：

# 编辑配置文件
nano ~/.openclaw/config.json

# 确保 memory 部分具有正确的提供程序：
{
  "memory": {
    "embedding": {
      "provider": "ollama",
      "model": "qwen3-embedding:0.6b"
    }
  }
}

验证修复：基本状态检查

应用修复后，使用原始命令进行验证：

$ openclaw memory status --deep

🦞 OpenClaw 2026.4.12 (1c0672b) — If something's on fire, I can't extinguish it—but I can write a beautiful postmortem.

│
◇  
Memory Search (main)
Provider: ollama (requested: ollama)
Model: qwen3-embedding:0.6b
Sources: memory
Indexed: 8/8 files · 99 chunks
Dirty: yes
Store: ~/.openclaw/memory/main.sqlite
Workspace: ~/.openclaw/workspace
Dreaming: 0 3 * * * · limit=10 · minScore=0.8 · minRecallCount=3 · minUniqueQueries=3 · recencyHalfLifeDays=14 · maxAgeDays=30
Embeddings: ready

预期输出：

• 退出代码：0
• 无错误信息
• Provider: ollama 正确显示
• Embeddings: ready 状态

验证修复：直接嵌入测试

直接测试嵌入功能：

$ openclaw memory embed --text "test query"

# 预期：返回嵌入向量且无错误
# 退出代码：0

验证修复：提供程序注册（调试）

如果仍然失败，请检查提供程序注册：

$ openclaw debug providers

Available Memory Providers:
- openai
- anthropic
- ollama          ← 应该列出
- local

验证修复：版本确认

$ openclaw --version

# 验证版本是否符合预期
🦞 OpenClaw 2026.4.12 (1c0672b)

验证修复：Ollama 服务

确保 Ollama 服务正在运行且可访问：

$ curl http://localhost:11434/api/tags

# 预期：返回可用模型的 JSON 响应
{
  "models": [
    {
      "name": "qwen3-embedding:0.6b",
      "size": 378456789,
      "modified_at": "2026-04-10T00:00:00Z"
    }
  ]
}

逻辑关联的错误代码

• UNKNOWN_PROVIDER - 通用提供程序解析失败
• PROVIDER_NOT_INITIALIZED - 提供程序已注册但未就绪
• EMBEDDING_MODEL_NOT_FOUND - 模型在提供程序上不存在
• PROVIDER_CONNECTION_FAILED - 到提供程序的网络/连接断开
• CONFIG_SCHEMA_MISMATCH - 配置结构不兼容

历史相关问题

相关配置键

memory.embedding.provider          # 出问题的键
memory.embedding.model              # 可能需要更新
memory.embedding.providerConfig     # 可选的每个提供程序配置
memory.embedding.dimensionOverride  # 可能与模型输出冲突
memory.providers.fallback            # 回退链配置

下游错误级联

当此错误发生时，后续操作会失败：

openclaw memory search "query"
# → 失败：没有可用的嵌入提供程序

openclaw memory index
# → 失败：无法为新内容生成嵌入

openclaw dream
# → 可能部分工作：使用缓存的嵌入