---
read_when:
    - Quieres cambiar los modelos predeterminados o ver el estado de autenticación del proveedor
    - Quieres analizar los modelos/proveedores disponibles y depurar los perfiles de autenticación
summary: Referencia de CLI para `openclaw models` (status/list/set/scan, alias, alternativas, autenticación)
title: Modelos
x-i18n:
    generated_at: "2026-06-27T11:02:06Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 15d0a01e0f8f971996359413306a1c694e5a787eaef69b13eb8ac63c2a7c8990
    source_path: cli/models.md
    workflow: 16
---

# `openclaw models`

Descubrimiento, análisis y configuración de modelos (modelo predeterminado, alternativas de respaldo, perfiles de autenticación).

Relacionado:

- Proveedores + modelos: [Modelos](/es/providers/models)
- Conceptos de selección de modelos + comando de barra `/models`: [Concepto de modelos](/es/concepts/models)
- Configuración de autenticación del proveedor: [Primeros pasos](/es/start/getting-started)

## Comandos comunes

```bash
openclaw models status
openclaw models list
openclaw models set <model-or-alias>
openclaw models scan
```

`openclaw models status` muestra el valor predeterminado resuelto y las alternativas de respaldo, además de una vista general de autenticación.
Cuando hay instantáneas de uso de proveedores disponibles, la sección de estado de OAuth/clave de API incluye
ventanas de uso del proveedor e instantáneas de cuota.
Proveedores actuales con ventana de uso: Anthropic, GitHub Copilot, Gemini CLI, OpenAI,
MiniMax, Xiaomi y z.ai. La autenticación de uso proviene de hooks específicos del proveedor
cuando están disponibles; de lo contrario, OpenClaw recurre a credenciales OAuth/clave de API
coincidentes desde perfiles de autenticación, env o configuración.
En la salida `--json`, `auth.providers` es la vista general del proveedor consciente de env/config/almacén,
mientras que `auth.oauth` es solo el estado de salud de los perfiles del almacén de autenticación.
Añade `--probe` para ejecutar sondeos de autenticación en vivo contra cada perfil de proveedor configurado.
Los sondeos son solicitudes reales (pueden consumir tokens y activar límites de tasa).
Usa `--agent <id>` para inspeccionar el estado de modelo/autenticación de un agente configurado. Si se omite,
el comando usa `OPENCLAW_AGENT_DIR` si está definido; de lo contrario, usa el
agente predeterminado configurado.
Las filas de sondeo pueden provenir de perfiles de autenticación, credenciales env o `models.json`.
Para solucionar problemas de OAuth de OpenAI ChatGPT/Codex, `openclaw models status`,
`openclaw models auth list --provider openai` y
`openclaw config get agents.defaults.model --json` son la forma más rápida de
confirmar si un agente tiene un perfil OAuth `openai` utilizable para
`openai/*` a través del runtime nativo de Codex. Consulta [Configuración del proveedor OpenAI](/es/providers/openai#check-and-recover-codex-oauth-routing).

Notas:

- `models set <model-or-alias>` acepta `provider/model` o un alias.
- `models list` es de solo lectura: lee configuración, perfiles de autenticación, estado de catálogo existente
  y filas de catálogo propiedad del proveedor, pero no reescribe
  `models.json`.
- La columna `Auth` es de nivel de proveedor y de solo lectura. Se calcula a partir de metadatos locales
  de perfiles de autenticación, marcadores env, claves de proveedor configuradas, marcadores de proveedor local,
  marcadores env/perfil de AWS Bedrock y metadatos de autenticación sintética de plugins;
  no carga el runtime del proveedor, no lee secretos del keychain, no llama a APIs de proveedores
  ni prueba la preparación exacta para ejecución por modelo.
- `models list --all --provider <id>` puede incluir filas de catálogo estático propiedad del proveedor
  desde manifiestos de plugins o metadatos de catálogo de proveedor integrado incluso cuando
  aún no te has autenticado con ese proveedor. Esas filas siguen mostrándose como
  no disponibles hasta que se configure la autenticación correspondiente.
- `models list` mantiene el plano de control con capacidad de respuesta mientras el descubrimiento del catálogo
  del proveedor es lento. Las vistas predeterminada y configurada recurren a filas de modelo configuradas o
  sintéticas tras una breve espera y dejan que el descubrimiento termine en segundo plano.
  Usa `--all` cuando necesites el catálogo descubierto completo y exacto y
  estés dispuesto a esperar el descubrimiento del proveedor.
- Un `models list --all` amplio fusiona filas de catálogo de manifiesto sobre filas de registro
  sin cargar hooks suplementarios del runtime del proveedor. Las rutas rápidas de manifiesto filtradas por proveedor
  usan solo proveedores marcados como `static`; los proveedores marcados como `refreshable`
  permanecen respaldados por registro/caché y anexan filas de manifiesto como suplementos, mientras
  que los proveedores marcados como `runtime` permanecen en descubrimiento de registro/runtime.
- `models list` mantiene separados los metadatos nativos del modelo y los límites del runtime. En la salida de tabla,
  `Ctx` muestra `contextTokens/contextWindow` cuando un límite efectivo del runtime
  difiere de la ventana de contexto nativa; las filas JSON incluyen `contextTokens`
  cuando un proveedor expone ese límite.
- `models list --provider <id>` filtra por id de proveedor, como `moonshot` u
  `openai`. No acepta etiquetas de visualización de selectores interactivos de proveedores,
  como `Moonshot AI`.
- Las referencias de modelo se analizan dividiendo por la **primera** `/`. Si el ID del modelo incluye `/` (estilo OpenRouter), incluye el prefijo del proveedor (ejemplo: `openrouter/moonshotai/kimi-k2`).
- Si omites el proveedor, OpenClaw resuelve la entrada primero como alias, luego
  como una coincidencia única de proveedor configurado para ese id de modelo exacto y solo entonces
  recurre al proveedor predeterminado configurado con una advertencia de obsolescencia.
  Si ese proveedor ya no expone el modelo predeterminado configurado, OpenClaw
  recurre al primer proveedor/modelo configurado en lugar de mostrar un
  valor predeterminado obsoleto de proveedor eliminado.
- `models status` puede mostrar `marker(<value>)` en la salida de autenticación para marcadores de posición no secretos (por ejemplo `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) en lugar de enmascararlos como secretos.

### Análisis de modelos

`models scan` lee el catálogo público `:free` de OpenRouter y clasifica candidatos para
uso como alternativa de respaldo. El catálogo en sí es público, así que los análisis solo de metadatos no necesitan
una clave de OpenRouter.

De forma predeterminada, OpenClaw intenta sondear la compatibilidad con herramientas e imágenes mediante llamadas a modelos en vivo.
Si no hay una clave de OpenRouter configurada, el comando recurre a una salida solo de metadatos
y explica que los modelos `:free` aún requieren `OPENROUTER_API_KEY` para
sondeos e inferencia.

Opciones:

- `--no-probe` (solo metadatos; sin búsqueda de configuración/secretos)
- `--min-params <b>`
- `--max-age-days <days>`
- `--provider <name>`
- `--max-candidates <n>`
- `--timeout <ms>` (solicitud de catálogo y tiempo de espera por sondeo)
- `--concurrency <n>`
- `--yes`
- `--no-input`
- `--set-default`
- `--set-image`
- `--json`

`--set-default` y `--set-image` requieren sondeos en vivo; los resultados de análisis
solo de metadatos son informativos y no se aplican a la configuración.

### Estado de modelos

Opciones:

- `--json`
- `--plain`
- `--check` (salida 1=expirado/faltante, 2=por expirar)
- `--probe` (sondeo en vivo de perfiles de autenticación configurados)
- `--probe-provider <name>` (sondear un proveedor)
- `--probe-profile <id>` (ids de perfil repetidos o separados por comas)
- `--probe-timeout <ms>`
- `--probe-concurrency <n>`
- `--probe-max-tokens <n>`
- `--agent <id>` (id de agente configurado; anula `OPENCLAW_AGENT_DIR`)

`--json` mantiene stdout reservado para la carga útil JSON. Los diagnósticos de perfiles de autenticación, proveedor
y arranque se enrutan a stderr para que los scripts puedan canalizar stdout directamente
a herramientas como `jq`.

Categorías de estado de sondeo:

- `ok`
- `auth`
- `rate_limit`
- `billing`
- `timeout`
- `format`
- `unknown`
- `no_model`

Casos esperados de detalle/código de motivo del sondeo:

- `excluded_by_auth_order`: existe un perfil almacenado, pero `auth.order.<provider>`
  explícito lo omitió, por lo que el sondeo informa la exclusión en lugar de
  intentarlo.
- `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`:
  el perfil está presente pero no es elegible/resoluble.
- `no_model`: existe autenticación del proveedor, pero OpenClaw no pudo resolver un candidato
  de modelo sondeable para ese proveedor.

## Alias + alternativas de respaldo

```bash
openclaw models aliases list
openclaw models fallbacks list
```

## Perfiles de autenticación

```bash
openclaw models auth add
openclaw models auth list [--provider <id>] [--json]
openclaw models auth login --provider <id>
openclaw models auth login --provider openai --profile-id openai:work
openclaw models auth paste-api-key --provider <id>
openclaw models auth setup-token --provider <id>
openclaw models auth paste-token
```

`models auth add` es el asistente interactivo de autenticación. Puede iniciar un flujo de autenticación
del proveedor (OAuth/clave de API) o guiarte para pegar un token manualmente, según el
proveedor que elijas.

`models auth list` enumera los perfiles de autenticación guardados para el agente seleccionado sin
imprimir material de token, clave de API o secreto OAuth. Usa `--provider <id>` para
filtrar a un proveedor, como `openai`, y `--json` para scripts.

`models auth login` ejecuta el flujo de autenticación de un plugin de proveedor (OAuth/clave de API). Usa
`openclaw plugins list` para ver qué proveedores están instalados.
Usa `openclaw models auth --agent <id> <subcommand>` para escribir resultados de autenticación en un
almacén de agente configurado específico. La bandera padre `--agent` se respeta en
`add`, `list`, `login`, `paste-api-key`, `setup-token`, `paste-token` y
`login-github-copilot`.

Para modelos OpenAI, `--provider openai` usa de forma predeterminada el inicio de sesión de cuenta ChatGPT/Codex.
Usa `--method api-key` solo cuando quieras añadir un perfil de clave de API de OpenAI,
normalmente como respaldo para límites de suscripción de Codex. Ejecuta `openclaw doctor --fix`
para migrar estados heredados antiguos de autenticación/perfil con prefijo OpenAI Codex a `openai`.

Ejemplos:

```bash
openclaw models auth login --provider openai --set-default
openclaw models auth login --provider openai --method api-key
openclaw models auth paste-api-key --provider openai
openclaw models auth list --provider openai
```

Notas:

- `login` acepta `--profile-id <id>` para proveedores que admiten perfiles con nombre
  durante el inicio de sesión. Úsalo para mantener separados varios inicios de sesión del mismo
  proveedor.
- `paste-api-key` acepta claves de API generadas en otro lugar, solicita el valor de la clave
  y la escribe en el id de perfil predeterminado `<provider>:manual` salvo que
  pases `--profile-id`. En automatización, canaliza la clave por stdin, por ejemplo
  `printf "%s\n" "$OPENAI_API_KEY" | openclaw models auth paste-api-key --provider openai`.
- `setup-token` y `paste-token` siguen siendo comandos genéricos de token para proveedores
  que exponen métodos de autenticación con token.
- `setup-token` requiere una TTY interactiva y ejecuta el método de autenticación con token
  del proveedor (con valor predeterminado en el método `setup-token` de ese proveedor cuando expone
  uno).
- `paste-token` acepta una cadena de token generada en otro lugar o desde automatización.
- `paste-token` requiere `--provider`, solicita el valor del token de forma predeterminada
  y lo escribe en el id de perfil predeterminado `<provider>:manual` salvo que pases
  `--profile-id`.
- En automatización, canaliza el token por stdin en lugar de pasarlo como argumento para que
  las credenciales del proveedor no aparezcan en el historial de shell ni en listas de procesos.
- `paste-token --expires-in <duration>` almacena una expiración absoluta del token a partir de una
  duración relativa como `365d` o `12h`.
- Para `openai`, las claves de API de OpenAI y el material de token ChatGPT/OAuth son
  formas de autenticación distintas. Usa `paste-api-key` para claves de API de OpenAI `sk-...` y
  `paste-token` solo para material de autenticación con token.
- Nota sobre Anthropic: personal de Anthropic nos dijo que el uso estilo OpenClaw de Claude CLI está permitido otra vez, así que OpenClaw trata la reutilización de Claude CLI y el uso de `claude -p` como aprobados para esta integración salvo que Anthropic publique una nueva política.
- `setup-token` / `paste-token` de Anthropic siguen disponibles como una ruta de token compatible de OpenClaw, pero ahora OpenClaw prefiere la reutilización de Claude CLI y `claude -p` cuando están disponibles.

## Relacionado

- [Referencia de CLI](/es/cli)
- [Selección de modelos](/es/concepts/model-providers)
- [Conmutación por error de modelos](/es/concepts/model-failover)