CLI de modelos

Las referencias de modelo eligen un proveedor y un modelo. Normalmente no eligen el runtime de agente de bajo nivel. Por ejemplo, openai/gpt-5.5 puede ejecutarse mediante la ruta normal del proveedor OpenAI o mediante el runtime de app-server de Codex, según agents.defaults.agentRuntime.id. En el modo de runtime de Codex, la referencia openai/gpt-* no implica facturación por clave de API; la autenticación puede venir de una cuenta de Codex o de un perfil de autenticación openai-codex. Consulta Runtimes de agentes.

# Cómo funciona la selección de modelos

OpenClaw selecciona modelos en este orden:

# Origen de selección y comportamiento de alternativas

El mismo provider/model puede significar cosas distintas según de dónde venga:

• Los valores predeterminados configurados (agents.defaults.model.primary y los principales específicos del agente) son el punto de partida normal y usan agents.defaults.model.fallbacks.
• Las selecciones automáticas de alternativa son estado de recuperación temporal. Se almacenan con modelOverrideSource: "auto" para que los turnos posteriores puedan seguir usando la cadena de alternativas sin probar primero un principal que se sabe que falla.
• Las selecciones de sesión del usuario son exactas. /model, el selector de modelos, session_status(model=...) y sessions.patch almacenan modelOverrideSource: "user"; si ese proveedor/modelo seleccionado no es accesible, OpenClaw falla de forma visible en lugar de pasar a otro modelo configurado.
• Cron --model / carga útil model es un principal por trabajo. Aún usa las alternativas configuradas, salvo que el trabajo suministre fallbacks explícitas en la carga útil (usa fallbacks: [] para una ejecución de cron estricta).
• Los selectores de modelo predeterminado y lista permitida de la CLI respetan models.mode: "replace" al listar models.providers.*.models explícitos en lugar de cargar el catálogo integrado completo.
• El selector de modelos de la IU de Control pide al Gateway su vista de modelos configurada: agents.defaults.models cuando está presente; de lo contrario, models.providers.*.models explícitos más proveedores con autenticación utilizable. El catálogo integrado completo se reserva para vistas de exploración explícitas como models.list con view: "all" u openclaw models list --all.

# Política rápida de modelos

• Establece tu principal en el modelo de última generación más potente disponible para ti.
• Usa alternativas para tareas sensibles a coste/latencia y chats de menor riesgo.
• Para agentes con herramientas habilitadas o entradas no confiables, evita niveles de modelo más antiguos o débiles.

# Incorporación (recomendada)

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

openclaw onboard

Puede configurar modelo + autenticación para proveedores comunes, incluida suscripción de OpenAI Code (Codex) (OAuth) y Anthropic (clave de API o Claude CLI).

# 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.pdfModel.primary y agents.defaults.pdfModel.fallbacks
• agents.defaults.imageGenerationModel.primary y agents.defaults.imageGenerationModel.fallbacks
• agents.defaults.videoGenerationModel.primary y agents.defaults.videoGenerationModel.fallbacks
• agents.defaults.models (lista permitida + alias + parámetros de proveedor)
• models.providers (proveedores personalizados escritos en models.json)

# Ediciones seguras de la lista permitida

Usa escrituras aditivas al actualizar agents.defaults.models a mano:

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge

# "El modelo no está permitido" (y por qué se detienen las respuestas)

Si agents.defaults.models está establecido, se convierte en la lista permitida para /model y para anulaciones 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 /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

Cuando el comando rechazado incluía una anulación de runtime como /model openai/gpt-5.5 --runtime codex, corrige primero la lista permitida y luego vuelve a intentar el mismo comando /model ... --runtime .... Para la ejecución nativa de Codex, el modelo seleccionado sigue siendo openai/gpt-5.5; el runtime codex selecciona el arnés y usa la autenticación de Codex por separado.

Para modelos locales/GGUF, almacena la referencia completa con prefijo de proveedor en la lista permitida, por ejemplo ollama/gemma4:26b, lmstudio/Gemma4-26b-a4-it-gguf o el proveedor/modelo exacto que muestra openclaw models list --provider <provider>. Los nombres de archivo locales simples o los nombres para mostrar no son suficientes cuando la lista permitida está activa.

Ejemplo de configuración de lista permitida:

{
  agent: {
    model: { primary: "anthropic/claude-sonnet-4-6" },
    models: {
      "anthropic/claude-sonnet-4-6": { 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.4
/model status

Comportamiento/configuración completa del comando: Comandos slash.

# Comandos de 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 de forma predeterminada los modelos configurados/con autenticación disponible. Flags útiles:

--allboolean

Catálogo completo. Incluye filas del catálogo estático incluido y propiedad del proveedor antes de configurar la autenticación, por lo que las vistas solo de descubrimiento pueden mostrar modelos que no están disponibles hasta que agregues las credenciales del proveedor correspondiente.

--localboolean

Solo proveedores locales.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> Filtra por id de proveedor, por ejemplo moonshot. No se aceptan las etiquetas de visualización de los selectores interactivos.

--plainboolean

Un modelo por línea.

--jsonboolean

Salida legible por máquina.

# models status

Muestra el modelo principal resuelto, los modelos alternativos, el modelo de imagen y una descripción general de autenticación de los proveedores configurados. También muestra el estado de expiración 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 principal resuelto.

Ejemplo (Claude CLI):

claude auth login
openclaw models status

# Escaneo (modelos gratuitos de OpenRouter)

openclaw models scan inspecciona el catálogo de modelos gratuitos de OpenRouter y, opcionalmente, puede sondear modelos para comprobar la compatibilidad con herramientas e imágenes.

--no-probeboolean

Omite los sondeos en vivo (solo metadatos).

"--min-params

"--max-age-days

"--provider

"--max-candidates

--set-defaultboolean

Define agents.defaults.model.primary como la primera selección.

--set-imageboolean

Define agents.defaults.imageModel.primary como la primera selección de imagen.

Los resultados del escaneo se clasifican por:

1. Compatibilidad con imágenes
2. Latencia de herramientas
3. Tamaño de contexto
4. Recuento de parámetros

Entrada:

• Lista /models de OpenRouter (filtro :free)
• Los sondeos en vivo requieren una clave API de OpenRouter desde perfiles de autenticación o OPENROUTER_API_KEY (consulta Variables de entorno)
• Filtros opcionales: --max-age-days, --min-params, --provider, --max-candidates
• Controles de solicitud/sondeo: --timeout, --concurrency

Cuando los sondeos en vivo se ejecutan en un TTY, puedes seleccionar alternativas de forma interactiva. En modo no interactivo, pasa --yes para aceptar los valores predeterminados. Los resultados solo de metadatos son informativos; --set-default y --set-image requieren sondeos en vivo para que OpenClaw no configure un modelo de OpenRouter sin clave inutilizable.

# Registro de modelos (models.json)

Los proveedores personalizados en models.providers se escriben en models.json dentro del directorio del agente (valor predeterminado ~/.openclaw/agents/<agentId>/agent/models.json). Este archivo se fusiona de forma predeterminada salvo que models.mode esté definido como replace.

# Relacionado

• Runtimes de agentes — PI, Codex y otros runtimes de bucle de agentes
• Referencia de configuración — claves de configuración de modelos
• Generación de imágenes — configuración de modelos de imagen
• Conmutación por error de modelos — cadenas de alternativas
• Proveedores de modelos — enrutamiento y autenticación de proveedores
• Generación de música — configuración de modelos de música
• Generación de video — configuración de modelos de video