image Tool devuelve 'Unknown Model' para Modelos Ollama Configurados con Image Input

La herramienta image no puede resolver modelos de Ollama correctamente configurados, produciendo un error Unknown model a pesar de que el modelo aparece como válido en los diagnósticos del sistema.

Manifestación Principal del Error

$ openclaw tools run image --prompt "Describe this image" --image "https://example.com/image.jpg"
{
  "status": "error",
  "tool": "image",
  "error": "Unknown model: ollama/qwen3.5:397b-cloud"
}

Contradicción en la Salida de Diagnóstico

El modelo aparece correctamente configurado en múltiples comandos de diagnóstico:

$ openclaw models status
Image model   : qwen3.5:397b-cloud
Default model : gpt-4o

$ openclaw models list --all | grep qwen
ollama/qwen3.5:397b-cloud                  text+image 256k     yes   no    fallback#1,configured,alias:qwen

Variantes de Modelos Afectadas

Múltiples modelos de Ollama exhiben el mismo comportamiento:

• ollama/qwen3.5:397b-cloud — capacidad text+image
• ollama/kimi-k2.5:cloud — capacidad text+image

Confirmación de Solución Alternativa Funcional

La integración MCP Vision funciona correctamente, confirmando que el problema está aislado en la resolución de modelo de la herramienta integrada image:

$ mcporter call gemini.analyze_media --args '{"media_source": "", "prompt": "..."}'

El problema surge de una falta de coincidencia bidireccional en la normalización del ID del modelo entre tres componentes distintos:

Flujo de Interacción de Componentes

┌─────────────────────────────────────────────────────────────────┐ │ Model Resolution Pipeline │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ openclaw.json image tool │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ imageModel: { │ ──────► │ Normalizes to: │ │ │ │ primary: │ │ “ollama/qwen…"│ │ │ │ “qwen3.5…” │ │ │ │ │ └──────────────────┘ └────────┬─────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────┐ │ │ │ Model Registry Lookup │ │ │ │ Expected: “qwen3.5…” │ │ │ │ Got: “ollama/q…” │ │ │ └────────┬────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────┐ │ │ │ MISMATCH ERROR │ │ │ │ Unknown model returned │ │ │ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘

Secuencia de la Causa Raíz

1. Almacenamiento de Configuración: El archivo openclaw.json del usuario almacena la referencia del modelo sin el prefijo del proveedor:

   "imageModel": {
     "primary": "qwen3.5:397b-cloud"
   }

2. Recuperación de Configuración: El comando openclaw models status lee y muestra correctamente este valor (eliminando el prefijo del proveedor para mostrar).
3. Resolución de Modelo de la Herramienta: La lógica interna de la herramienta image realiza la inyección del prefijo del proveedor durante la construcción del ID del modelo:

   // Pseudocode representation of the bug
   const resolvedModel = `ollama/${config.imageModel.primary}`;
   // Results in: "ollama/qwen3.5:397b-cloud"
   

4. Fallo en la Búsqueda del Registro: Las claves del registro de modelos se almacenan internamente sin el prefijo ollama/, lo que causa el fallo en la búsqueda.

Estructura de Claves del Registro

El registro de modelos almacena internamente las claves en un formato normalizado que varía según el proveedor:

Desviación de Ruta de Código

El error se manifiesta porque dos rutas de código diferentes manejan la resolución del modelo:

• Ruta de Visualización CLI: Maneja correctamente los IDs de modelo sin prefijo comparándolos con el ID base del modelo.
• Ruta de Ejecución de Herramientas: Agrega incorrectamente el espacio de nombres del proveedor, creando una clave de búsqueda que no existe.

Método 1: Actualizar la Configuración para Usar el ID Completo del Modelo (Recomendado)

Modificar openclaw.json para usar el ID del modelo completamente calificado con el prefijo del proveedor:

Antes:

{
  "agents": {
    "defaults": {
      "imageModel": {
        "primary": "qwen3.5:397b-cloud"
      }
    }
  }
}

Después:

{
  "agents": {
    "defaults": {
      "imageModel": {
        "primary": "ollama/qwen3.5:397b-cloud"
      }
    }
  }
}

Método 2: Corrección mediante Comando CLI

Usar la CLI de OpenClaw para actualizar la configuración del modelo:

$ openclaw config set agents.defaults.imageModel.primary "ollama/qwen3.5:397b-cloud"
✓ Configuration updated: agents.defaults.imageModel.primary = "ollama/qwen3.5:397b-cloud"

$ openclaw models status
Image model   : ollama/qwen3.5:397b-cloud

Método 3: Verificar y Re-registrar el Modelo (Si los Problemas Persisten)

Si la corrección no resuelve el problema, re-registrar el modelo en el registro:

# Step 1: Remove existing model registration
$ openclaw models remove ollama/qwen3.5:397b-cloud

# Step 2: Re-register with explicit provider
$ openclaw models add ollama/qwen3.5:397b-cloud --input-types text,image

# Step 3: Set as primary image model
$ openclaw config set agents.defaults.imageModel.primary "ollama/qwen3.5:397b-cloud"

Ubicación del Archivo de Configuración

La ubicación del archivo de configuración varía según el sistema operativo:

Alternativa: Usar un Proveedor Alternativo

Si los modelos de Ollama continúan fallando, configurar un proveedor alternativo:

{
  "agents": {
    "defaults": {
      "imageModel": {
        "primary": "openai/gpt-4o-mini"
      }
    }
  }
}

Paso 1: Verificar la Actualización de Configuración

Confirmar que el archivo de configuración refleja el ID del modelo correcto:

$ grep -A2 "imageModel" ~/.config/openclaw/openclaw.json
"imageModel": {
  "primary": "ollama/qwen3.5:397b-cloud"
}

Paso 2: Verificar el Estado del Modelo

$ openclaw models status
Default model : gpt-4o
Image model   : ollama/qwen3.5:397b-cloud

Paso 3: Verificar que el Modelo Está Listado y Configurado

$ openclaw models list --all | grep qwen
ollama/qwen3.5:397b-cloud                  text+image 256k     yes   no    fallback#1,configured,alias:qwen

La bandera configured confirma que el modelo está correctamente registrado.

Paso 4: Probar la Ejecución de la Herramienta de Imagen

Ejecutar la herramienta de imagen con la configuración corregida:

$ openclaw tools run image --prompt "What is in this image?" --image "https://httpbin.org/image/jpeg"
{
  "status": "ok",
  "tool": "image",
  "model": "ollama/qwen3.5:397b-cloud",
  "result": "[Image analysis content would appear here]"
}

Paso 5: Verificar el Código de Salida

$ echo $?
0

Una ejecución exitosa devuelve el código de salida 0. Las condiciones de error devuelven códigos de salida distintos de cero.

Paso 6: Verificación Alternativa con Salida JSON

Para verificación programática:

$ openclaw tools run image --prompt "Count the objects" --image "https://httpbin.org/image/jpeg" --output json
{
  "status": "ok",
  "tool": "image",
  "model": "ollama/qwen3.5:397b-cloud",
  "result": "...",
  "timing": {
    "total_ms": 4523
  }
}

Error común 1: Caché de Configuración No Actualizada

La CLI puede almacenar en caché la configuración. Forzar una actualización:

$ openclaw config reload
$ openclaw models status

Error común 2: Sensibilidad a Mayúsculas y Minúsculas en los ID de Modelos

Los ID de modelos son sensibles a mayúsculas y minúsculas. Verificar la escritura exacta:

# Incorrecto
"ollama/Qwen3.5:397b-cloud"

# Correcto
"ollama/qwen3.5:397b-cloud"

Error común 3: Resolución de Modelos en Entorno Docker

Al ejecutar OpenClaw en Docker, Ollama debe ser accesible desde dentro del contenedor:

# Docker run with Ollama network access
$ docker run -e OLLAMA_HOST=host.docker.internal:11434 openclaw/openclaw:latest

# Or use host network mode
$ docker run --network host openclaw/openclaw:latest

Error común 4: Servidor de Ollama No Está Ejecutándose

Asegurarse de que el servidor de Ollama está ejecutándose y es accesible:

$ curl http://localhost:11434/api/tags
{"models":[...]}

Si el curl falla, iniciar Ollama:

$ ollama serve
# In another terminal
$ ollama list

Error común 5: Modelo No Descargado

Verificar que el modelo está descargado en Ollama:

$ ollama list
NAME                            ID           SIZE      MODIFIED
qwen3.5:397b-cloud              a1b2c3d4     7.2GB     2 hours ago

Si no está presente, descargar el modelo:

$ ollama pull qwen3.5:397b-cloud

Error común 6: Mezclar Referencias de Modelos Configuradas y Ad-hoc

Usar referencias de modelos ad-hoc en llamadas de herramientas puede omitir la configuración:

# Esto puede funcionar si el modelo es válido pero no está "configurado"
$ openclaw tools run image --model "ollama/qwen3.5:397b-cloud" ...

# Esto usa el modelo configurado y puede fallar
$ openclaw tools run image ...

Error común 7: Conflictos de Alias de Modelos

Los alias de modelos pueden crear ambigüedad en la resolución:

# El alias "qwen" podría resolver a diferentes modelos
$ openclaw models list --all | grep alias:qwen
ollama/qwen3.5:397b-cloud          text+image 256k     yes   no    configured,alias:qwen
openai/qwen-vl-max               text+image 1024k    yes   no    alias:qwen

Error común 8: Tiempo de Espera de Red en la Primera Solicitud

Las solicitudes de modelo por primera vez pueden agotar el tiempo de espera mientras Ollama descarga las capas del modelo:

# Increase timeout in config
{
  "providers": {
    "ollama": {
      "timeout": 120000
    }
  }
}

Código de Error: MODEL_NOT_FOUND

Descripción: Fallo genérico en la búsqueda de modelo, a menudo debido a que el modelo no está registrado en el sistema.

Distinción: El error Unknown model en este problema es una instanciación específica donde el modelo ESTÁ registrado pero el formato de la clave de búsqueda es incorrecto.

Código de Error: PROVIDER_NOT_CONFIGURED

Descripción: El proveedor (por ejemplo, ollama) no está inicializado o no es accesible.

Problema Relacionado: A menudo aparece cuando el servidor de Ollama no está ejecutándose o la configuración de red de Docker es incorrecta.

{
  "error": "Provider 'ollama' not available",
  "code": "PROVIDER_NOT_CONFIGURED"
}

Código de Error: MODEL_CAPABILITY_MISMATCH

Descripción: El modelo no soporta el tipo de entrada requerido (por ejemplo, usando un modelo de solo texto para análisis de imágenes).

Problema Relacionado: Puede ocurrir si la configuración del modelo tiene capacidades de input incorrectamente definidas.

{
  "error": "Model 'ollama/qwen3.5:397b-cloud' does not support image input",
  "code": "MODEL_CAPABILITY_MISMATCH"
}

Problema Histórico: MODEL_ID_NORMALIZATION_V1

Descripción: Las versiones anteriores de OpenClaw (anteriores a 2026.3.0) tenían normalización inconsistente de ID de modelo en todas las herramientas, no solo en la herramienta de imagen.

Resolución: Actualizar a 2026.4.2 o posterior donde la normalización fue estandarizada para la mayoría de las herramientas. El error de normalización de la herramienta de imagen permanece sin corregir a partir de 2026.4.2.

Issue Relacionado de GitHub: #1847

Descripción: “La herramienta de imagen falla con ‘Unknown model’ para modelos de ollama” — Este es el issue de origen que se está documentando.

Estado: Abierto a la fecha de documentación.

Problema de Configuración Relacionado: CONFIG_MODEL_PRIMARY_AMBIGUITY

Descripción: Cuando imageModel.primary coincide con múltiples modelos entre proveedores debido a nombres base similares.

Conflicto de Ejemplo:

openai/gpt-4o
ollama/llama3:8b-gpt4o-compatible  # Ambiguo al buscar "gpt-4o"