Configura modelos OpenClaw: Guía de selección y fallbacks

¿Alguna vez has sentido que gestionar diferentes modelos de IA es un caos total? Entre cambiar de API, configurar fallbacks y asegurarte de que las claves sigan vigentes, es fácil perder el hilo y terminar con errores inesperados en medio de una sesión.

Aquí es donde entra la CLI de modelos de OpenClaw para poner orden en tu flujo de trabajo. En esta guía te explico cómo configurar y alternar entre modelos de forma directa, para que tu única preocupación sea construir lo que tienes en mente.

Models CLI

Consulta /concepts/model-failover para ver la rotación de perfiles de autenticación, tiempos de espera (cooldowns) y cómo interactúa eso con los fallbacks. Resumen rápido de providers y ejemplos: /concepts/model-providers.

Cómo funciona la selección de modelos

OpenClaw selecciona los modelos en este orden:

1. Modelo Primary (agents.defaults.model.primary o agents.defaults.model).
2. Fallbacks en agents.defaults.model.fallbacks (en orden).
3. El Provider auth failover ocurre dentro de un provider antes de pasar al siguiente modelo.

Relacionado:

• agents.defaults.models es la allowlist/catálogo de modelos que OpenClaw puede usar (además de los alias).
• agents.defaults.imageModel se usa solo cuando el modelo principal no puede aceptar imágenes.
• agents.defaults.imageGenerationModel lo utiliza la capacidad compartida de generación de imágenes. Si se omite, image_generate puede inferir un provider por defecto desde plugins compatibles con autenticación. Si configuras un provider/modelo específico, configura también la auth/API key de ese provider.
• Los valores por defecto por agente pueden sobrescribir agents.defaults.model mediante agents.list[].model más bindings (consulta /concepts/multi-agent).

Política rápida de modelos

• Configura tu modelo principal con el modelo de última generación más potente que tengas disponible.
• Usa fallbacks para tareas sensibles al coste o la latencia y para chats de menor importancia.
• Para agentes con herramientas (tool-enabled) o entradas no confiables, evita niveles de modelos antiguos o más débiles.

Onboarding (recomendado)

Si no quieres editar la configuración a mano, ejecuta el onboarding:

openclaw onboard

Puede configurar el modelo y la autenticación para providers comunes, incluyendo la suscripción de OpenAI Code (Codex) (OAuth) y Anthropic (API key o claude setup-token).

Claves de configuración (resumen)

• agents.defaults.model.primary y agents.defaults.model.fallbacks
• agents.defaults.imageModel.primary y agents.defaults.imageModel.fallbacks
• agents.defaults.imageGenerationModel.primary y agents.defaults.imageGenerationModel.fallbacks
• agents.defaults.models (allowlist + alias + parámetros de provider)
• models.providers (providers personalizados escritos en models.json)

Las referencias de modelos se normalizan a minúsculas. Los alias de provider como z.ai/* se normalizan a zai/*.

Los ejemplos de configuración de providers (incluyendo OpenCode) se encuentran en /providers/opencode.

”Model is not allowed” (y por qué se detienen las respuestas)

Si agents.defaults.models está configurado, se convierte en la allowlist para /model y para los overrides de sesión. Cuando un usuario selecciona un modelo que no está en esa lista, OpenClaw devuelve:

Model "provider/model" is not allowed. Use /model to list available models.

Esto sucede antes de que se genere una respuesta normal, por lo que puede parecer que el mensaje “no respondió”. La solución es:

• Añadir el modelo a agents.defaults.models, o
• Limpiar la allowlist (eliminar agents.defaults.models), o
• Elegir un modelo de /model list.

Ejemplo de configuración de allowlist:

{
  agent: {
    model: { primary: "anthropic/claude-sonnet-4-6" },
    models: {
      "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
      "anthropic/claude-opus-4-6": { alias: "Opus" },
    },
  },
}

Cambiar de modelo en el chat (/model)

Puedes cambiar de modelo para la sesión actual sin reiniciar:

/model
/model list
/model 3
/model openai/gpt-5.2
/model status

Notas:

• /model (y /model list) es un selector compacto y numerado (familia de modelos + providers disponibles).
• En Discord, /model y /models abren un selector interactivo con menús desplegables de provider y modelo, además de un paso para enviar (Submit).
• /model <#> selecciona desde ese selector.
• /model actualiza la selección de la sesión inmediatamente. Si el agente está inactivo, la siguiente ejecución usa el nuevo modelo enseguida. Si el agente está ocupado, la ejecución en curso termina primero y el trabajo en cola o futuro usará el nuevo modelo después.
• /model status es la vista detallada (candidatos de autenticación y, si está configurado, la baseUrl del endpoint del provider + modo api).
• Las referencias de modelos se analizan dividiendo por la primera /. Usa provider/model al escribir /model <ref>.
• Si el ID del modelo contiene / (estilo OpenRouter), debes incluir el prefijo del provider (ejemplo: /model openrouter/moonshotai/kimi-k2).
• Si omites el provider, OpenClaw trata la entrada como un alias o un modelo para el provider por defecto (solo funciona cuando no hay / en el ID del modelo).

Comportamiento y configuración completa de comandos: Slash commands.

Comandos de la CLI

openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

openclaw models aliases list
openclaw models aliases add <alias> <provider/model>
openclaw models aliases remove <alias>

openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear

openclaw models image-fallbacks list
openclaw models image-fallbacks add <provider/model>
openclaw models image-fallbacks remove <provider/model>
openclaw models image-fallbacks clear

openclaw models (sin subcomando) es un atajo para models status.

models list

Muestra los modelos configurados por defecto. Flags útiles:

• --all: catálogo completo
• --local: solo providers locales
• --provider <name>: filtrar por provider
• --plain: un modelo por línea
• --json: salida legible por máquina

models status

Muestra el modelo principal resuelto, los fallbacks, el modelo de imagen y un resumen de autenticación de los providers configurados. También muestra el estado de expiración de OAuth para los perfiles encontrados en el almacén de auth (advierte dentro de las 24h por defecto). --plain imprime solo el modelo principal resuelto. El estado de OAuth siempre se muestra (y se incluye en la salida --json). Si un provider configurado no tiene credenciales, models status imprime una sección de Missing auth. El JSON incluye auth.oauth (ventana de advertencia + perfiles) y auth.providers (autenticación efectiva por provider). Usa --check para automatización (sale con 1 si falta o está expirado, 2 si está por expirar).

La elección de autenticación depende del provider/cuenta. Para hosts de Gateway siempre activos, las API keys suelen ser lo más predecible; también se admiten flujos de tokens de suscripción.

Ejemplo (Anthropic setup-token):

claude setup-token
openclaw models status

Escaneo (modelos gratuitos de OpenRouter)

openclaw models scan inspecciona el catálogo de modelos gratuitos de OpenRouter y opcionalmente puede probar modelos para soporte de herramientas e imágenes.

Flags clave:

• --no-probe: omitir pruebas en vivo (solo metadatos)
• --min-params <b>: tamaño mínimo de parámetros (en miles de millones)
• --max-age-days <days>: omitir modelos antiguos
• --provider <name>: filtro de prefijo de provider
• --max-candidates <n>: tamaño de la lista de fallbacks
• --set-default: establece agents.defaults.model.primary a la primera selección
• --set-image: establece agents.defaults.imageModel.primary a la primera selección de imagen

Las pruebas requieren una API key de OpenRouter (desde perfiles de auth o OPENROUTER_API_KEY). Sin una clave, usa --no-probe para listar solo candidatos.

Los resultados del escaneo se clasifican por:

1. Soporte de imágenes
2. Latencia de herramientas
3. Tamaño de contexto
4. Conteo de parámetros

Input

• Lista de OpenRouter /models (filtro :free)
• Requiere API key de OpenRouter desde perfiles de auth o OPENROUTER_API_KEY (ver /environment)
• Filtros opcionales: --max-age-days, --min-params, --provider, --max-candidates
• Controles de prueba: --timeout, --concurrency

Cuando se ejecuta en una TTY, puedes seleccionar fallbacks de forma interactiva. En modo no interactivo, usa --yes para aceptar los valores por defecto.

Registro de modelos (models.json)

Los providers personalizados en models.providers se escriben en models.json bajo el directorio del agente (por defecto ~/.openclaw/agents/<agentId>/agent/models.json). Este archivo se combina por defecto a menos que models.mode esté configurado como replace.

Precedencia del modo de combinación (merge) para IDs de provider que coincidan:

• Gana la baseUrl no vacía que ya esté presente en el models.json del agente.
• La apiKey no vacía en el models.json del agente gana solo cuando ese provider no está gestionado por SecretRef en el contexto actual de configuración/perfil de auth.
• Los valores de apiKey de providers gestionados por SecretRef se actualizan desde los marcadores de origen (ENV_VAR_NAME para referencias de entorno, secretref-managed para referencias de archivo/ejecución) en lugar de persistir secretos resueltos.
• Los valores de cabecera de providers gestionados por SecretRef se actualizan desde los marcadores de origen (secretref-env:ENV_VAR_NAME para referencias de entorno, secretref-managed para referencias de archivo/ejecución).
• Las apiKey/baseUrl del agente vacías o faltantes recurren a models.providers de la configuración.
• Otros campos del provider se actualizan desde la configuración y los datos normalizados del catálogo.

La persistencia de marcadores es autoritativa desde el origen: OpenClaw escribe marcadores desde la instantánea de configuración activa (antes de la resolución), no desde los valores de secretos resueltos en tiempo de ejecución. Esto se aplica siempre que OpenClaw regenera models.json, incluyendo rutas dirigidas por comandos como openclaw agent.

Relacionado

• Model Providers — enrutamiento de providers y auth
• Model Failover — cadenas de fallbacks
• Image Generation — configuración de modelos de imagen
• Configuration Reference — claves de configuración de modelos

¿Necesitas ayuda para configurar tus modelos? Prueba nuestro AI Setup Assistant.

Pasos siguientes

• Aprende más sobre Model Providers para gestionar tus APIs.
• Configura Model Failover para evitar interrupciones en el servicio.
• Explora la Configuration Reference para un control total.