CLI de Modelos
CLI de Modelos: listar, configurar, alias, fallbacks, escanear, estado.
Ver ''/concepts/model-failover'' para rotación de perfiles de auth, enfriamientos, y cómo interactúa con fallbacks.
Resumen rápido de proveedores + ejemplos: ''/concepts/model-providers''.
ReferenceConceptsModelsPage.intro.p3
Cómo funciona la selección de modelos
OpenClaw selecciona modelos en este orden:
1. Modelo ''Primario'' (''agents.defaults.model.primary'' o ''agents.defaults.model'').
2. ''Fallbacks'' en ''agents.defaults.model.fallbacks'' (en orden).
3. Failover de auth de proveedor ocurre dentro de un proveedor antes de pasar al siguiente modelo.
Relacionado:
- ''agents.defaults.models'' es la lista permitida/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'' via ''agents.list[].model'' más bindings (ver ''/concepts/multi-agent'').
Selecciones rápidas de modelo (anecdótico)
- GLM: un poco mejor para coding/llamadas de herramientas.
- MiniMax: mejor para escritura y vibes.
Asistente de configuración (recomendado)
Si no quieres editar la configuración manualmente, ejecuta el asistente de onboarding:
openclaw onboard
Puede configurar modelo + auth para proveedores comunes, incluyendo suscripción ''OpenAI Code (Codex)'' (OAuth) y ''Anthropic'' (clave API recomendada; ''claude setup-token'' también soportado).
ReferenceConceptsModelsPage.step03.p3
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 permitida + alias + parámetros de proveedor)
- ''models.providers'' (proveedores personalizados escritos en ''models.json'')
Las referencias de modelo se normalizan a minúsculas. Alias de proveedor como ''z.ai/*'' se normalizan a ''zai/*''.
Ejemplos de configuración de proveedores (incluyendo OpenCode Zen) están en ''/gateway/configuration''.
ReferenceConceptsModelsPage.step04.p7
ReferenceConceptsModelsPage.step04.p8
"El modelo no está permitido" (y por qué las respuestas se detienen)
Si ''agents.defaults.models'' está configurado, se convierte en la ''lista permitida'' 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, así que el mensaje puede sentirse como que "no respondió." La solución es:
- Añadir el modelo a ''agents.defaults.models'', o
- Limpiar la lista permitida (remover ''agents.defaults.models''), o
- Elegir un modelo de ''/model list''.
ReferenceConceptsModelsPage.step05.p7
ReferenceConceptsModelsPage.step05.p8
{
agent: {
model: { primary: "anthropic/claude-sonnet-4-5" },
models: {
"anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
"anthropic/claude-opus-4-5": { alias: "Opus" },
},
},
}Cambiando modelos en chat (`/model`)
Puedes 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 numerado compacto (familia de modelo + proveedores disponibles).
- ''/model <#>'' selecciona de ese selector.
- ''/model status'' es la vista detallada (candidatos de auth y, cuando configurado, endpoint de proveedor ''baseUrl'' + modo ''api'').
- Las referencias de modelo se analizan dividiendo en la ''primera'' ''/''. Usa ''provider/model'' al escribir ''/model <ref>''.
- Si el ID del modelo contiene ''/'' (estilo OpenRouter), debes incluir el prefijo del proveedor (ejemplo: ''/model openrouter/moonshotai/kimi-k2'').
- Si omites 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).
Comandos 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 modelos configurados por defecto. Flags ú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áquina
#
`models status`
Muestra el modelo primario resuelto, fallbacks, modelo de imagen, y un resumen de auth de proveedores configurados. También muestra estado de expiración OAuth para perfiles encontrados en el almacén de auth (advierte dentro de 24h por defecto). ''--plain'' imprime solo el modelo primario resuelto.
El estado OAuth siempre se muestra (e incluye en salida ''--json''). Si un proveedor configurado no tiene credenciales, ''models status'' imprime una sección ''Auth faltante''.
JSON incluye ''auth.oauth'' (ventana de advertencia + perfiles) y ''auth.providers'' (auth efectivo por proveedor).
Usa ''--check'' para automatización (salida ''1'' cuando falta/expira, ''2'' cuando está expirando).
La auth preferida de Anthropic es el setup-token del CLI Claude Code (ejecuta en cualquier lugar; pega en el host del gateway si es necesario):
ReferenceConceptsModelsPage.step09.p6
ReferenceConceptsModelsPage.step09.p7
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 probar modelos para soporte de herramientas e imágenes.
Flags clave:
- ''--no-probe'': saltar pruebas en vivo (solo metadatos)
- ''--min-params <b>'': tamaño mínimo de parámetros (miles de millones)
- ''--max-age-days <days>'': saltar modelos antiguos
- ''--provider <name>'': filtro de prefijo de proveedor
- ''--max-candidates <n>'': tamaño de lista de fallback
- ''--set-default'': configurar ''agents.defaults.model.primary'' a la primera selección
- ''--set-image'': configurar ''agents.defaults.imageModel.primary'' a la primera selección de imagen
El sondeo requiere una clave API de OpenRouter (de perfiles de auth o ''OPENROUTER_API_KEY''). Sin clave, usa ''--no-probe'' para listar solo candidatos.
Los resultados del escaneo se clasifican por:
1. Soporte de imagen
2. Latencia de herramientas
3. Tamaño de contexto
4. Conteo de parámetros
Cuando se ejecuta en TTY, puedes seleccionar fallbacks interactivamente. En modo no interactivo, pasa ''--yes'' para aceptar valores predeterminados.
ReferenceConceptsModelsPage.step10.p17
ReferenceConceptsModelsPage.step10.p18
ReferenceConceptsModelsPage.step10.p19
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 por defecto a menos que ''models.mode'' esté configurado en ''replace''.
ReferenceConceptsModelsPage.step11.p2