Concepts and configuration

CLI de modelos

Conmutación por error de modelos

Rotación de perfiles de autenticación, tiempos de enfriamiento y cómo interactúa eso con las alternativas.

Proveedores de modelos

Resumen rápido de proveedores y ejemplos.

Runtimes de agentes

OpenClaw, Codex y otros runtimes de bucle de agente.

Referencia de configuración

Claves de configuración de modelos.

Las referencias de modelo eligen un proveedor y un modelo. Normalmente no eligen el runtime de agente de bajo nivel. Las referencias de agentes de OpenAI son la principal excepción: openai/gpt-5.5 se ejecuta mediante el runtime del servidor de aplicaciones de Codex de forma predeterminada en el proveedor oficial de OpenAI. Las referencias de Copilot por suscripción (github-copilot/*) también pueden habilitarse para usar el Plugin externo de runtime de agente de GitHub Copilot; esa ruta sigue siendo explícita (sin alternativa auto). Las sustituciones explícitas de runtime pertenecen a la política de proveedor/modelo, no a todo el agente ni a la sesión. En el modo de runtime de Codex, la referencia openai/gpt-* no implica facturación por clave de API; la autenticación puede provenir de una cuenta de Codex o de un perfil OAuth de openai. Consulta Runtimes de agentes y Runtime de agente de GitHub Copilot.

Cómo funciona la selección de modelos

OpenClaw selecciona modelos en este orden:

Modelo principal

agents.defaults.model.primary (o agents.defaults.model).

Alternativas

agents.defaults.model.fallbacks (en orden).

Conmutación por error de autenticación del proveedor

La conmutación por error de autenticación ocurre dentro de un proveedor antes de pasar al siguiente modelo.

Superficies de modelo relacionadas

agents.defaults.models es la lista de permitidos/catálogo de modelos que OpenClaw puede usar (más alias). Usa entradas provider/* para limitar los proveedores visibles mientras mantienes dinámica la detección de proveedores.
agents.defaults.imageModel se usa solo cuando el modelo principal no puede aceptar imágenes.
agents.defaults.pdfModel lo usa la herramienta pdf. Si se omite, la herramienta recurre a agents.defaults.imageModel y luego al modelo de sesión/predeterminado resuelto.
agents.defaults.imageGenerationModel lo usa la capacidad compartida de generación de imágenes. Si se omite, image_generate todavía puede inferir un valor predeterminado de proveedor respaldado por autenticación. Prueba primero el proveedor predeterminado actual y luego los demás proveedores registrados de generación de imágenes en orden de ID de proveedor. Si estableces un proveedor/modelo específico, configura también la autenticación/clave de API de ese proveedor.
agents.defaults.musicGenerationModel lo usa la capacidad compartida de generación de música. Si se omite, music_generate todavía puede inferir un valor predeterminado de proveedor respaldado por autenticación. Prueba primero el proveedor predeterminado actual y luego los demás proveedores registrados de generación de música en orden de ID de proveedor. Si estableces un proveedor/modelo específico, configura también la autenticación/clave de API de ese proveedor.
agents.defaults.videoGenerationModel lo usa la capacidad compartida de generación de video. Si se omite, video_generate todavía puede inferir un valor predeterminado de proveedor respaldado por autenticación. Prueba primero el proveedor predeterminado actual y luego los demás proveedores registrados de generación de video en orden de ID de proveedor. Si estableces un proveedor/modelo específico, configura también la autenticación/clave de API de ese proveedor.
Los valores predeterminados por agente pueden sustituir agents.defaults.model mediante agents.list[].model más vinculaciones (consulta Enrutamiento multiagente).

Fuente de selección y comportamiento de alternativas

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

Los valores predeterminados configurados (agents.defaults.model.primary y los principales específicos de agente) son el punto de partida normal y usan agents.defaults.model.fallbacks.
Las selecciones de alternativa automática son estado de recuperación temporal. Se almacenan con modelOverrideSource: "auto" para que los turnos posteriores puedan seguir usando la cadena de alternativas sin sondear siempre un principal conocido como defectuoso; OpenClaw sondea periódicamente de nuevo el principal original, borra la selección automática cuando se recupera y anuncia las transiciones de alternativa/recuperación una vez por cada cambio de estado.
Las selecciones de sesión de usuario son exactas. /model, el selector de modelos, session_status(model=...) y sessions.patch almacenan modelOverrideSource: "user"; si ese proveedor/modelo seleccionado no es alcanzable, OpenClaw falla de forma visible en lugar de pasar a otro modelo configurado.
Cambiar agents.defaults.model.primary no reescribe las selecciones de sesiones existentes. Si el estado dice This session is pinned to X; config primary Y will apply to new/unpinned sessions., borra la selección de la sesión actual con /model default para que vuelva a heredar el principal configurado.
Cron --model / payload model es un principal por trabajo. Sigue usando las alternativas configuradas a menos que el trabajo proporcione fallbacks explícitas en el payload (usa fallbacks: [] para una ejecución de cron estricta).
Los selectores de modelo predeterminado y lista de permitidos de la CLI respetan models.mode: "replace" al listar models.providers.*.models explícitos en lugar de cargar el catálogo incorporado completo.
El selector de modelos de la interfaz de Control pide al Gateway su vista de modelos configurada: agents.defaults.models cuando está presente, incluidas las entradas provider/* de alcance de proveedor, o bien models.providers.*.models explícitos más proveedores con autenticación utilizable. El catálogo incorporado completo queda reservado 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 chat de menor riesgo.
Para agentes con herramientas habilitadas o entradas no confiables, evita niveles de modelo antiguos o más débiles.

Incorporación (recomendado)

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

bash

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 de permitidos + alias + parámetros de proveedor + entradas dinámicas de proveedor provider/*)
models.providers (proveedores personalizados escritos en models.json)

Ediciones seguras de la lista de permitidos

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

bash

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

Reglas de protección contra sobrescritura

openclaw config set protege los mapas de modelo/proveedor contra sobrescrituras accidentales. Una asignación de objeto simple a agents.defaults.models, models.providers o models.providers.<id>.models se rechaza cuando eliminaría entradas existentes. Usa --merge para cambios aditivos; usa --replace solo cuando el valor proporcionado deba convertirse en el valor objetivo completo.

La configuración interactiva de proveedores y openclaw configure --section model también fusionan selecciones con alcance de proveedor en la lista de permitidos existente, por lo que agregar Codex, Ollama u otro proveedor no elimina entradas de modelo no relacionadas. Configure conserva un agents.defaults.model.primary existente cuando se vuelve a aplicar la autenticación del proveedor. Los comandos explícitos de configuración predeterminada como openclaw models auth login --provider <id> --set-default y openclaw models set <model> siguen reemplazando agents.defaults.model.primary.

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

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

Code

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 sustitución de runtime como /model openai/gpt-5.5 --runtime codex, corrige primero la lista de permitidos 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 de permitidos, por ejemplo ollama/gemma4:26b, lmstudio/Gemma4-26b-a4-it-gguf o el proveedor/modelo exacto mostrado por openclaw models list --provider <provider>. Los nombres de archivo locales simples o los nombres visibles no son suficientes cuando la lista de permitidos está activa.

Si quieres limitar proveedores sin listar manualmente cada modelo, agrega entradas provider/* a agents.defaults.models:

json5

{  agents: {    defaults: {      models: {        "openai/*": {},        "vllm/*": {},      },    },  },}

Con esa política, /model, /models y los selectores de modelos muestran el catálogo detectado solo para esos proveedores. Pueden aparecer nuevos modelos de los proveedores seleccionados sin editar la lista de permitidos. Las entradas exactas provider/model pueden combinarse con entradas provider/* cuando necesitas un modelo específico de otro proveedor.

Ejemplo de configuración de lista de permitidos:

json5

{  agents: {    defaults: {      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 modelos para la sesión actual sin reiniciar:

Code

/model/model list/model 3/model openai/gpt-5.4/model default/model status

Comportamiento del selector

/model (y /model list) es un selector compacto y numerado (familia de modelos + proveedores disponibles).
En Discord, /model y /models abren un selector interactivo con desplegables de proveedor y modelo más un paso de envío.
En Telegram, las selecciones del selector /models tienen alcance de sesión; no cambian el valor predeterminado persistente del agente en openclaw.json.
/models add está obsoleto y ahora devuelve un mensaje de obsolescencia en lugar de registrar modelos desde el chat.
/model <#> selecciona desde ese selector.

Persistencia y cambio en vivo

/model conserva inmediatamente la nueva selección de sesión.
Si el agente está inactivo, la siguiente ejecución usa el nuevo modelo de inmediato.
Si ya hay una ejecución activa, OpenClaw marca un cambio en vivo como pendiente y solo reinicia con el nuevo modelo en un punto de reintento limpio.
Si la actividad de herramientas o la salida de respuesta ya comenzó, el cambio pendiente puede permanecer en cola hasta una oportunidad de reintento posterior o el siguiente turno del usuario.
/model default borra la selección de sesión y devuelve la sesión al modelo predeterminado configurado.
Una referencia /model seleccionada por el usuario es estricta para esa sesión: si el proveedor/modelo seleccionado no está disponible, la respuesta falla de forma visible en lugar de responder silenciosamente desde agents.defaults.model.fallbacks. Esto es diferente de los valores predeterminados configurados y los primarios de trabajos cron, que aún pueden usar cadenas de respaldo.
/model status es la vista detallada (candidatos de autenticación y, cuando está configurado, endpoint de proveedor baseUrl + modo api).

Análisis de refs

Las refs de modelo 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 proveedor (ejemplo: /model openrouter/moonshotai/kimi-k2).
Si omites el proveedor, OpenClaw resuelve la entrada en este orden:
1. coincidencia de alias
2. coincidencia única de proveedor configurado para ese ID de modelo exacto sin prefijo
3. respaldo obsoleto al proveedor predeterminado configurado; si ese proveedor ya no expone el modelo predeterminado configurado, OpenClaw recurre en su lugar al primer proveedor/modelo configurado para evitar mostrar un valor predeterminado obsoleto de un proveedor eliminado.

Comportamiento/configuración completa de comandos: comandos slash.

Comandos de CLI

bash

openclaw models listopenclaw models statusopenclaw models set <provider/model>openclaw models set-image <provider/model> openclaw models aliases listopenclaw models aliases add <alias> <provider/model>openclaw models aliases remove <alias> openclaw models fallbacks listopenclaw models fallbacks add <provider/model>openclaw models fallbacks remove <provider/model>openclaw models fallbacks clear openclaw models image-fallbacks listopenclaw 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/disponibles por autenticación. Flags útiles:

--allboolean

Catálogo completo. Incluye filas de catálogo estático agrupadas y propiedad del proveedor antes de que la autenticación esté configurada, de modo que las vistas solo de descubrimiento puedan mostrar modelos que no están disponibles hasta que agregues credenciales coincidentes del proveedor.

--localboolean

Solo proveedores locales.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> Filtra por ID de proveedor, por ejemplo moonshot. No se aceptan 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 primario resuelto, los respaldos, el modelo de imagen y una vista general de autenticación de los proveedores configurados. También expone el estado de vencimiento 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.

Comportamiento de autenticación y sondeo

El estado de OAuth siempre se muestra (y se incluye en la salida --json). Si un proveedor configurado no tiene credenciales, models status imprime una sección Falta autenticación.
JSON incluye auth.oauth (ventana de advertencia + perfiles) y auth.providers (autenticación efectiva por proveedor, incluidas credenciales respaldadas por env). auth.oauth es solo el estado de salud de perfiles del almacén de autenticación; los proveedores solo por env no aparecen allí.
Usa --check para automatización (sale con 1 cuando falta o está vencido, 2 cuando está por vencer).
Usa --probe para comprobaciones de autenticación en vivo; las filas de sondeo pueden venir de perfiles de autenticación, credenciales env o models.json.
Si auth.order.<provider> explícito omite un perfil almacenado, el sondeo informa excluded_by_auth_order en lugar de intentarlo. Si existe autenticación pero no se puede resolver ningún modelo sondeable para ese proveedor, el sondeo informa status: no_model.

Ejemplo (Claude CLI):

bash

claude auth loginopenclaw 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 compatibilidad con herramientas e imágenes.

--no-probeboolean

Omite sondeos en vivo (solo metadatos).

"--min-params

"--max-age-days

"--provider

"--max-candidates

--set-defaultboolean

Establece agents.defaults.model.primary en la primera selección.

--set-imageboolean

Establece agents.defaults.imageModel.primary en la primera selección de imagen.

Los resultados del escaneo se clasifican por:

Compatibilidad con imágenes
Latencia de herramientas
Tamaño de contexto
Recuento de parámetros

Entrada:

Lista /models de OpenRouter (filtro :free)
Los sondeos en vivo requieren una clave API de OpenRouter de 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 una TTY, puedes seleccionar respaldos 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 OpenRouter sin clave inutilizable.

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>/agent/models.json). Los catálogos de Plugin de proveedor se almacenan como fragmentos de catálogo generados y propiedad del Plugin bajo el estado de plugins del agente, y se cargan automáticamente. Este archivo se fusiona de forma predeterminada a menos que models.mode esté establecido en replace.

Precedencia del modo de fusión

Precedencia del modo de fusión para IDs de proveedor coincidentes:

Gana baseUrl no vacío ya presente en el models.json del agente.
apiKey no vacío en el models.json del agente gana solo cuando ese proveedor no está gestionado por SecretRef en el contexto actual de configuración/perfil de autenticación.
Los valores apiKey de proveedores gestionados por SecretRef se actualizan desde marcadores de origen (ENV_VAR_NAME para refs env, secretref-managed para refs de archivo/exec) en lugar de conservar secretos resueltos.
Los valores de encabezado de proveedores gestionados por SecretRef se actualizan desde marcadores de origen (secretref-env:ENV_VAR_NAME para refs env, secretref-managed para refs de archivo/exec).
apiKey/baseUrl vacíos o ausentes del agente recurren a models.providers de la configuración.
Otros campos de proveedor se actualizan desde la configuración y datos de catálogo normalizados.

Relacionado

Tiempos de ejecución de agentes — OpenClaw, Codex y otros tiempos de ejecución de bucle de agentes
Referencia de configuración — claves de configuración de modelo
Generación de imágenes — configuración de modelo de imagen
Conmutación por error de modelo — cadenas de respaldo
Proveedores de modelos — enrutamiento de proveedores y autenticación
Generación de música — configuración de modelo de música
Generación de video — configuración de modelo de video

Was this useful?

CLI de modelos

Cómo funciona la selección de modelos

Modelo principal

Alternativas

Conmutación por error de autenticación del proveedor

Fuente de selección y comportamiento de alternativas

Política rápida de modelos

Incorporación (recomendado)

Claves de configuración (resumen)

Ediciones seguras de la lista de permitidos

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

Cambiar modelos en el chat (`/model`)

Comandos de CLI

`models list`

`models status`

Escaneo (modelos gratuitos de OpenRouter)

Registro de modelos (`models.json`)

Relacionado

On this page

Molty

Cómo funciona la selección de modelos

Modelo principal

Alternativas

Conmutación por error de autenticación del proveedor

Fuente de selección y comportamiento de alternativas

Política rápida de modelos

Incorporación (recomendado)

Claves de configuración (resumen)

Ediciones seguras de la lista de permitidos

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

Cambiar modelos en el chat (/model)

Comandos de CLI

models list

models status

Escaneo (modelos gratuitos de OpenRouter)

Registro de modelos (models.json)

Relacionado

On this page

Cambiar modelos en el chat (`/model`)

`models list`

`models status`

Registro de modelos (`models.json`)