[Error de proveedor de embedding de memoria desconocido: ollama] - Unknown memory embedding provider: ollama - Troubleshooting Guide

Manifestación del Error

Al ejecutar el comando openclaw memory status --deep con ollama configurado como el proveedor de embedding de memoria, la CLI termina inmediatamente con un fallo de resolución del proveedor:

$ 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

Manifestaciones Técnicas

• Código de salida: Distinto de cero (típicamente 1)
• Tipo de error: ProviderResolutionError o equivalente en el subsistema de memoria
• Mensaje de error: Unknown memory embedding provider: ollama
• Ubicación del stack trace: Probablemente en packages/core/src/memory/providers/registry.ts o equivalente

Configuraciones Afectadas

El error ocurre cuando la configuración de OpenClaw contiene:

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

O mediante variable de entorno:

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

Línea de Tiempo de la Regresión

• Última versión funcional: 2026.04.10
• Primera versión fallida: 2026.04.12
• Delta de versiones: 2 días de commits

Causa Raíz Principal: Regresión del Registro de Proveedores

El error se origina por una regresión en el sistema de registro de proveedores de embedding de memoria. El proveedor ollama fue:

1. Eliminado del registro de proveedores durante un commit de refactorización entre 2026.04.10 y 2026.04.12
2. Renombrado sin compatibilidad hacia atrás (por ejemplo, "ollama" → "ollama-embedding" o "ollama/text-embedding-2")
3. Excluido del bundle de compilación debido a un problema de tree-shaking o importación condicional
4. Registrado condicionalmente basado en una feature flag que está deshabilitada por defecto

Análisis del Flujo de Código

La secuencia de fallo sigue esta ruta:

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

Patrón de Commit Probable

Basado en la ventana de regresión, un commit de refactorización probablemente cambió el mecanismo de registro del proveedor:

Antes (funcionando):

// packages/core/src/memory/providers/index.ts
export { OllamaEmbeddingProvider } from './ollama';
// Auto-registers via static side effect or explicit registry call

Después (roto):

// packages/core/src/memory/providers/index.ts
// OllamaEmbeddingProvider export removed or conditional
// Provider not auto-registering

Causa Raíz Alternativa: Cambio en el Esquema de Configuración

El nombre del proveedor puede haber cambiado en el esquema de configuración:

// Old config key (2026.04.10)
memory.embedding.provider = "ollama"

// New config key (2026.04.12)
memory.embedding.provider = "ollama-embed"  // or
memory.embedding.provider = "ollama/text-embedding-2"

Comando de Verificación

Para diagnosticar la causa raíz, inspeccione los proveedores disponibles:

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

Opción 1: Revertir al Nombre Anterior del Proveedor (Corrección Rápida)

Si el proveedor fue renombrado, use el nuevo valor de configuración:

# Check current OpenClaw version
openclaw --version

# List available memory embedding providers
openclaw memory status --help 2>&1 | grep -i provider

# Update configuration to use correct provider name
openclaw config set memory.embedding.provider ollama-embedding
# OR
openclaw config set memory.embedding.provider ollama/text-embedding-2

Opción 2: Forzar el Registro Mediante Plugin (Solución Alternativa)

Si el código del proveedor existe pero no se está registrando automáticamente:

# Create a local plugin to re-register the provider
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

# Enable plugin in config
openclaw config set plugins.enabled "['ollama-fix']"

Opción 3: Reinstalar OpenClaw (Corrección Limpia)

Desinstale y reinstale para obtener una configuración conocida como buena:

# Backup current configuration
cp -r ~/.openclaw ~/.openclaw.backup.$(date +%Y%m%d)

# Reinstall OpenClaw
npm uninstall -g @openclaw/cli
npm install -g @openclaw/cli@latest

# Reconfigure ollama provider
openclaw config set memory.embedding.provider ollama
openclaw config set memory.embedding.model qwen3-embedding:0.6b

Opción 4: Fijar a la Versión Funcional (Corrección Temporal)

Si la regresión bloquea el uso en producción:

# Uninstall current version
npm uninstall -g @openclaw/cli

# Install last known working version
npm install -g @openclaw/cli@2026.04.10

# Verify version
openclaw --version

Edición Manual del Archivo de Configuración

Si los comandos de CLI fallan, edite directamente la configuración:

# Edit the configuration file
nano ~/.openclaw/config.json

# Ensure memory section has correct provider:
{
  "memory": {
    "embedding": {
      "provider": "ollama",
      "model": "qwen3-embedding:0.6b"
    }
  }
}

Verificar Corrección: Verificación de Estado Básica

Después de aplicar la corrección, verifique con el comando original:

$ 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

Salida esperada:

• Código de salida: 0
• Sin mensajes de error
• Provider: ollama mostrado correctamente
• Estado Embeddings: ready

Verificar Corrección: Prueba Directa de Embedding

Pruebe la funcionalidad de embedding directamente:

$ openclaw memory embed --text "test query"

# Expected: Returns embedding vector without error
# Exit code: 0

Verificar Corrección: Registro del Proveedor (Depuración)

Si aún falla, verifique el registro del proveedor:

$ openclaw debug providers

Available Memory Providers:
- openai
- anthropic
- ollama          ← Should be listed
- local

Verificar Corrección: Confirmación de Versión

$ openclaw --version

# Verify version matches expected
🦞 OpenClaw 2026.4.12 (1c0672b)

Verificar Corrección: Servicio Ollama

Asegúrese de que el servicio Ollama esté ejecutándose y sea accesible:

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

# Expected: JSON response with available models
{
  "models": [
    {
      "name": "qwen3-embedding:0.6b",
      "size": 378456789,
      "modified_at": "2026-04-10T00:00:00Z"
    }
  ]
}

Códigos de Error Lógicamente Conectados

• UNKNOWN_PROVIDER - Fallo genérico de resolución del proveedor
• PROVIDER_NOT_INITIALIZED - Proveedor registrado pero no listo
• EMBEDDING_MODEL_NOT_FOUND - El modelo no existe en el proveedor
• PROVIDER_CONNECTION_FAILED - Conexión de red al proveedor rota
• CONFIG_SCHEMA_MISMATCH - Estructura de configuración incompatible

Problemas Históricamente Relacionados

Claves de Configuración Relacionadas

memory.embedding.provider          # The failing key
memory.embedding.model              # May need updating
memory.embedding.providerConfig     # Optional per-provider config
memory.embedding.dimensionOverride  # May conflict with model output
memory.providers.fallback            # Fallback chain configuration

Cascada de Errores Aguas Abajo

Cuando ocurre este error, las operaciones subsiguientes fallan:

openclaw memory search "query"
# → Fails: No embedding provider available

openclaw memory index
# → Fails: Cannot generate embeddings for new content

openclaw dream
# → May partially work: Uses cached embeddings