openclaw models

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

Relacionado:

• Proveedores + modelos: Modelos
• Conceptos de selección de modelos + comando de barra /models: Concepto de modelos
• Configuración de autenticación del proveedor: Primeros pasos

Comandos comunes

openclaw models statusopenclaw models listopenclaw 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.

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

openclaw models aliases listopenclaw models fallbacks list

Perfiles de autenticación

openclaw models auth addopenclaw models auth list [--provider <id>] [--json]openclaw models auth login --provider <id>openclaw models auth login --provider openai --profile-id openai:workopenclaw 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:

openclaw models auth login --provider openai --set-defaultopenclaw models auth login --provider openai --method api-keyopenclaw models auth paste-api-key --provider openaiopenclaw 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
• Selección de modelos
• Conmutación por error de modelos