CLI de modelos¶

Vea /concepts/model-failover para la rotación de perfiles de autenticación, los enfriamientos y cómo eso interactúa con las alternativas. Resumen rápido de proveedores + ejemplos: /concepts/model-providers.

Cómo funciona la selección de modelos¶

OpenClaw selecciona modelos en este orden:

1. Primario (agents.defaults.model.primary o agents.defaults.model).
2. Alternativas en agents.defaults.model.fallbacks (en orden).
3. Conmutación por error de autenticación del proveedor ocurre dentro de un proveedor antes de pasar al siguiente modelo.

Relacionado:

• agents.defaults.models es la lista de permitidos/catálogo de modelos que OpenClaw puede usar (más alias).
• agents.defaults.imageModel se usa solo cuando el modelo primario no puede aceptar imágenes.
• Los valores predeterminados por agente pueden sobrescribir agents.defaults.model mediante agents.list[].model más enlaces (ver /concepts/multi-agent).

Selecciones rápidas de modelos (anecdóticas)¶

• GLM: un poco mejor para programación/llamadas a herramientas.
• MiniMax: mejor para redacción y estilo.

Asistente de configuración (recomendado)¶

Si no desea editar la configuración a mano, ejecute el asistente de incorporación:

openclaw onboard

Puede configurar modelo + autenticación para proveedores comunes, incluidos OpenAI Code (Codex) subscription (OAuth) y Anthropic (se recomienda clave de API; claude setup-token también es compatible).

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.models (lista de permitidos + alias + parámetros del proveedor)
• models.providers (proveedores personalizados escritos en models.json)

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

Los ejemplos de configuración de proveedores (incluido OpenCode Zen) están en /gateway/configuration.

“El modelo no está permitido” (y por qué las respuestas se detienen)¶

Si agents.defaults.models está configurado, se convierte en la lista de permitidos para /model y para sobrescrituras 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 ocurre antes de que se genere una respuesta normal, por lo que el mensaje puede sentirse como si “no respondiera”. La solución es:

• Agregar el modelo a agents.defaults.models, o
• Limpiar la lista de permitidos (eliminar agents.defaults.models), o
• Elegir un modelo de /model list.

Ejemplo de configuración de lista de permitidos:

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

Cambiar modelos en el chat (/model)¶

Puede cambiar modelos 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 + proveedores disponibles).
• /model <#> selecciona desde ese selector.
• /model status es la vista detallada (candidatos de autenticación y, cuando está configurado, el endpoint del proveedor baseUrl + el modo api).
• Las referencias de modelos se analizan separando por el primer /. Use provider/model al escribir /model <ref>.
• Si el ID del modelo en sí contiene / (estilo OpenRouter), debe incluir el prefijo del proveedor (ejemplo: /model openrouter/moonshotai/kimi-k2).
• Si omite el proveedor, OpenClaw trata la entrada como un alias o un modelo para el proveedor predeterminado (solo funciona cuando no hay / en el ID del modelo).

Comportamiento/configuración completa del comando: 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 de forma predeterminada. Indicadores útiles:

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

models status¶

Muestra el modelo primario resuelto, las alternativas, el modelo de imágenes y un resumen de autenticación de los proveedores configurados. También muestra el estado de caducidad de OAuth para los perfiles encontrados en el almacén de autenticación (advierte dentro de 24 h de forma predeterminada). --plain imprime solo el modelo primario resuelto. El estado de OAuth siempre se muestra (y se incluye en la salida de --json). Si un proveedor configurado no tiene credenciales, models status imprime una sección Missing auth. El JSON incluye auth.oauth (ventana de advertencia + perfiles) y auth.providers (autenticación efectiva por proveedor). Use --check para automatización (salida 1 cuando falta/está vencida, 2 cuando está por vencer).

La autenticación preferida de Anthropic es el setup-token de la CLI de Claude Code (ejecútelo en cualquier lugar; péguelo en el host del Gateway si es necesario):

claude setup-token
openclaw models status

Escaneo (modelos gratuitos de OpenRouter)¶

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

Indicadores clave:

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

El sondeo requiere una clave de API de OpenRouter (desde perfiles de autenticación o OPENROUTER_API_KEY). Sin una clave, use --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. Recuento de parámetros

Entrada

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

Cuando se ejecuta en un TTY, puede seleccionar alternativas de forma interactiva. En modo no interactivo, pase --yes para aceptar los valores predeterminados.

Registro de modelos (models.json)¶

Los proveedores personalizados en models.providers se escriben en models.json bajo el directorio del agente (predeterminado ~/.openclaw/agents/<agentId>/models.json). Este archivo se fusiona de forma predeterminada a menos que models.mode esté configurado en replace.