CLI de Modelos

Consulta /concepts/model-failover para la rotación de perfiles de autenticación, cooldowns y cómo interactúa con los fallbacks. Visión general rápida de providers + ejemplos: /concepts/model-providers.

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. El failover de autenticación del provider ocurre dentro de un provider antes de pasar al siguiente modelo.

Relacionado:

  • agents.defaults.models es la lista permitida/catálogo de modelos que OpenClaw puede usar (más aliases).
  • agents.defaults.imageModel se usa solo cuando el modelo primario no puede aceptar imágenes.
  • Los valores por defecto por agente pueden sobrescribir agents.defaults.model vía agents.list[].model más bindings (consulta /concepts/multi-agent).

Política rápida de modelos

  • Configura tu modelo primario como el modelo de última generación más potente disponible para ti.
  • Usa fallbacks para tareas sensibles a costo/latencia y chats de menor importancia.
  • Para agentes con herramientas habilitadas o entradas no confiables, evita modelos de niveles antiguos/débiles.

Asistente de configuración (recomendado)

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

openclaw onboard

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

Claves de configuración (visión general)

  • agents.defaults.model.primary y agents.defaults.model.fallbacks
  • agents.defaults.imageModel.primary y agents.defaults.imageModel.fallbacks
  • agents.defaults.models (lista permitida + aliases + parámetros de provider)
  • models.providers (providers personalizados escritos en models.json)

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

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

”Model is not allowed” (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 permitida, OpenClaw devuelve:

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

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

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

Ejemplo de configuración de lista permitida:

{
  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)

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 modelo + providers disponibles).
  • En Discord, /model y /models abren un selector interactivo con desplegables de provider y modelo más un paso de Submit.
  • /model <#> selecciona de ese selector.
  • /model status es la vista detallada (candidatos de autenticación y, cuando está configurado, baseUrl + modo api del endpoint del provider).
  • Las referencias de modelo se parsean dividiendo en 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 completo del comando/configuración: Comandos slash.

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 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 primario resuelto, fallbacks, modelo de imagen y una visión general de autenticación de los providers configurados. También muestra el estado de expiración de OAuth para perfiles encontrados en el almacén de autenticación (avisa dentro de las 24h por defecto). --plain imprime solo el modelo primario resuelto. El estado de OAuth siempre se muestra (e incluye en la salida --json). Si un provider configurado no tiene credenciales, models status imprime una sección Missing auth. JSON incluye auth.oauth (ventana de aviso + perfiles) y auth.providers (autenticación efectiva por provider). Usa --check para automatización (exit 1 cuando falta/expirado, 2 cuando está por expirar).

La elección de autenticación depende del provider/cuenta. Para hosts de gateway siempre activos, las claves API suelen ser las más predecibles; los flujos de token de suscripción también están soportados.

Ejemplo (setup-token de Anthropic):

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 principales:

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

La prueba requiere una clave API de OpenRouter (desde perfiles de autenticación o OPENROUTER_API_KEY). Sin clave, usa --no-probe para listar solo candidatos.

Los resultados del escaneo se rankean por:

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

Entrada

  • Lista /models de OpenRouter (filtro :free)
  • Requiere clave API de OpenRouter desde perfiles de autenticación o OPENROUTER_API_KEY (consulta /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 interactivamente. En modo no interactivo, pasa --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 fusiona por defecto a menos que models.mode esté configurado como replace.

Precedencia del modo merge para IDs de provider coincidentes:

  • El baseUrl no vacío ya presente en el models.json del agente gana.
  • El apiKey no vacío en el models.json del agente gana solo cuando ese provider no está gestionado por SecretRef en el contexto actual de config/auth-profile.
  • Los valores de apiKey de providers gestionados por SecretRef se refrescan desde marcadores de origen (ENV_VAR_NAME para refs de env, secretref-managed para refs de archivo/exec) en lugar de persistir secretos resueltos.
  • Los valores de cabeceras de providers gestionados por SecretRef se refrescan desde marcadores de origen (secretref-env:ENV_VAR_NAME para refs de env, secretref-managed para refs de archivo/exec).
  • apiKey/baseUrl vacíos o faltantes del agente recurren a la configuración de models.providers.
  • Otros campos del provider se refrescan desde la configuración y datos normalizados del catálogo.

La persistencia de marcadores es autoritativa desde la fuente: OpenClaw escribe marcadores desde el snapshot de configuración de origen activa (pre-resolución), no desde valores de secretos resueltos en runtime. Esto aplica siempre que OpenClaw regenera models.json, incluyendo rutas dirigidas por comandos como openclaw agent.

arrow_back
Anterior
Models
Siguiente
Model Providers
arrow_forward