Preguntas frecuentes: modelos y autenticación

El modelo predeterminado de OpenClaw es lo que configures como:

agents.defaults.model.primary

Los modelos se referencian como provider/model (ejemplo: openai/gpt-5.5 o anthropic/claude-sonnet-4-6). Si omites el proveedor, OpenClaw primero intenta un alias, luego una coincidencia única de proveedor configurado para ese id de modelo exacto y solo después recurre al proveedor predeterminado configurado como ruta de compatibilidad obsoleta. 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 un proveedor eliminado. Aun así, deberías definir provider/model explícitamente.

Valor predeterminado recomendado: usa el modelo de generación más reciente y potente disponible en tu conjunto de proveedores. Para agentes con herramientas habilitadas o entrada no confiable: prioriza la potencia del modelo sobre el costo. Para chat rutinario/de bajo riesgo: usa modelos de respaldo más baratos y enruta según el rol del agente.

MiniMax tiene su propia documentación: MiniMax y Modelos locales.

Regla general: usa el mejor modelo que puedas permitirte para trabajo de alto riesgo, y un modelo más barato para chat rutinario o resúmenes. Puedes enrutar modelos por agente y usar subagentes para paralelizar tareas largas (cada subagente consume tokens). Consulta Modelos y Subagentes.

Advertencia importante: los modelos más débiles o excesivamente cuantizados son más vulnerables a la inyección de prompts y al comportamiento inseguro. Consulta Seguridad.

Más contexto: Modelos.

Usa comandos de modelo o edita solo los campos de modelo. Evita reemplazos completos de configuración.

Opciones seguras:

• /model en el chat (rápido, por sesión)
• openclaw models set ... (actualiza solo la configuración del modelo)
• openclaw configure --section model (interactivo)
• edita agents.defaults.model en ~/.openclaw/openclaw.json

Evita config.apply con un objeto parcial salvo que quieras reemplazar toda la configuración. Para ediciones RPC, inspecciona primero con config.schema.lookup y prefiere config.patch. La carga de lookup te da la ruta normalizada, documentación/restricciones superficiales del esquema y resúmenes inmediatos de elementos secundarios. para actualizaciones parciales. Si sobrescribiste la configuración, restaura desde una copia de seguridad o vuelve a ejecutar openclaw doctor para reparar.

Documentación: Modelos, Configurar, Configuración, Doctor.

Sí. Ollama es la ruta más sencilla para modelos locales.

Configuración más rápida:

1. Instala Ollama desde https://ollama.com/download
2. Descarga un modelo local como ollama pull gemma4
3. Si también quieres modelos en la nube, ejecuta ollama signin
4. Ejecuta openclaw onboard y elige Ollama
5. Elige Local o Cloud + Local

Notas:

• Cloud + Local te da modelos en la nube además de tus modelos locales de Ollama
• los modelos en la nube como kimi-k2.5:cloud no necesitan una descarga local
• para cambio manual, usa openclaw models list y openclaw models set ollama/<model>

Nota de seguridad: los modelos más pequeños o muy cuantizados son más vulnerables a la inyección de prompts. Recomendamos encarecidamente modelos grandes para cualquier bot que pueda usar herramientas. Si aun así quieres modelos pequeños, habilita aislamiento y listas estrictas de herramientas permitidas.

Documentación: Ollama, Modelos locales, Proveedores de modelos, Seguridad, Aislamiento.

• Estos despliegues pueden diferir y cambiar con el tiempo; no hay una recomendación fija de proveedor.
• Comprueba la configuración actual en tiempo de ejecución en cada Gateway con openclaw models status.
• Para agentes sensibles a la seguridad/con herramientas habilitadas, usa el modelo de generación más reciente y potente disponible.

Usa el comando /model como mensaje independiente:

/model sonnet/model opus/model gpt/model gpt-mini/model gemini/model gemini-flash/model gemini-flash-lite

Estos son los alias integrados. Se pueden agregar alias personalizados mediante agents.defaults.models.

Puedes listar los modelos disponibles con /model, /model list o /model status.

/model (y /model list) muestra un selector compacto y numerado. Selecciona por número:

/model 3

También puedes forzar un perfil de autenticación específico para el proveedor (por sesión):

/model opus@anthropic:default/model opus@anthropic:work

Consejo: /model status muestra qué agente está activo, qué archivo auth-profiles.json se está usando y qué perfil de autenticación se intentará a continuación. También muestra el endpoint de proveedor configurado (baseUrl) y el modo de API (api) cuando están disponibles.

¿Cómo desanclo un perfil que configuré con @profile?

Vuelve a ejecutar /model sin el sufijo @profile:

/model anthropic/claude-opus-4-6

Si quieres volver al valor predeterminado, elígelo desde /model (o envía /model <default provider/model>). Usa /model status para confirmar qué perfil de autenticación está activo.

/model provider/model selecciona esa ruta exacta del proveedor para la sesión.

Por ejemplo, qianfan/deepseek-v4-flash y deepseek/deepseek-v4-flash son referencias de modelo distintas aunque ambas contengan deepseek-v4-flash. OpenClaw no debería cambiar silenciosamente de un proveedor al otro solo porque el id de modelo simple coincide.

Una referencia /model seleccionada por el usuario también es estricta para la política de respaldo. Si ese proveedor/modelo seleccionado no está disponible, la respuesta falla de forma visible en lugar de responder desde agents.defaults.model.fallbacks. Las cadenas de respaldo configuradas siguen aplicándose a los valores predeterminados configurados, a los primarios de trabajos cron y al estado de respaldo seleccionado automáticamente.

Si una ejecución que comenzó desde una anulación que no es de sesión puede usar respaldo, OpenClaw prueba primero el proveedor/modelo solicitado, después los respaldos configurados y solo entonces el primario configurado. Eso evita que los ids de modelo simples duplicados salten directamente de vuelta al proveedor predeterminado.

Consulta Modelos y Conmutación por error de modelos.

Sí. Trata la elección de modelo y la elección de runtime por separado:

• Agente de programación nativo Codex: establece agents.defaults.model.primary en openai/gpt-5.5. Inicia sesión con openclaw models auth login --provider openai cuando quieras autenticación de suscripción de ChatGPT/Codex.
• Tareas directas de la API de OpenAI fuera del bucle del agente: configura OPENAI_API_KEY para imágenes, embeddings, voz, tiempo real y otras superficies de API de OpenAI que no son de agente.
• Autenticación con clave de API de agente OpenAI: usa /model openai/gpt-5.5 con un perfil de clave de API openai ordenado.
• Subagentes: enruta tareas de programación a un agente centrado en Codex con su propio modelo openai/gpt-5.5.

Consulta Modelos y Comandos slash.

Usa una alternancia de sesión o un valor predeterminado de configuración:

• Por sesión: envía /fast on mientras la sesión usa openai/gpt-5.5.
• Por valor predeterminado de modelo: establece agents.defaults.models["openai/gpt-5.5"].params.fastMode en true.
• Corte automático: usa /fast auto o params.fastMode: "auto" para iniciar llamadas de modelo nuevas en modo rápido hasta el corte automático y, después, iniciar llamadas posteriores de reintento, respaldo, resultado de herramienta o continuación sin modo rápido. El corte predeterminado es de 60 segundos; establece params.fastAutoOnSeconds en el modelo activo para cambiarlo.

Ejemplo:

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: {            fastMode: "auto",            fastAutoOnSeconds: 30,          },        },      },    },  },}

Para OpenAI, el modo rápido se asigna a service_tier = "priority" en solicitudes nativas Responses compatibles. Las anulaciones de sesión /fast prevalecen sobre los valores predeterminados de configuración. Los turnos del servidor de aplicación de Codex solo pueden recibir el nivel al inicio del turno, por lo que auto se aplica en el siguiente turno de modelo iniciado por OpenClaw en lugar de dentro de un turno de servidor de aplicación que ya está en ejecución.

Consulta Razonamiento y modo rápido y Modo rápido de OpenAI.

Si agents.defaults.models está definido, se convierte en la lista de permitidos para /model y cualquier anulación de sesión. Elegir un modelo que no está en esa lista 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

Ese error se devuelve en lugar de una respuesta normal. Corrección: añade el modelo exacto a agents.defaults.models, añade un comodín de proveedor como "provider/*": {} para catálogos dinámicos de proveedores, elimina la lista de permitidos o elige un modelo desde /model list. Si el comando también incluía --runtime codex, actualiza primero la lista de permitidos y luego vuelve a intentar el mismo comando /model provider/model --runtime codex.

Esto significa que el proveedor no está configurado (no se encontró ninguna configuración de proveedor MiniMax ni perfil de autenticación), por lo que el modelo no puede resolverse.

Lista de comprobación para corregirlo:

1. Actualiza a una versión actual de OpenClaw (o ejecuta desde la fuente main) y luego reinicia el Gateway.

2. Asegúrate de que MiniMax esté configurado (asistente o JSON), o de que la autenticación de MiniMax exista en perfiles de entorno/autenticación para que se pueda inyectar el proveedor correspondiente (MINIMAX_API_KEY para minimax, MINIMAX_OAUTH_TOKEN u OAuth de MiniMax almacenado para minimax-portal).

3. Usa el id de modelo exacto (distingue mayúsculas y minúsculas) para tu ruta de autenticación: minimax/MiniMax-M3, minimax/MiniMax-M2.7 o minimax/MiniMax-M2.7-highspeed para la configuración con clave de API, o minimax-portal/MiniMax-M3, minimax-portal/MiniMax-M2.7 o minimax-portal/MiniMax-M2.7-highspeed para la configuración con OAuth.

4. Ejecuta:

   openclaw models list

   y elige de la lista (o /model list en el chat).

Consulta MiniMax y Modelos.

Sí. Usa MiniMax como predeterminado y cambia de modelo por sesión cuando sea necesario. Los respaldos son para errores, no para "tareas difíciles", así que usa /model o un agente separado.

Opción A: cambiar por sesión

{  env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M3" },      models: {        "minimax/MiniMax-M3": { alias: "minimax" },        "openai/gpt-5.5": { alias: "gpt" },      },    },  },}

Luego:

/model gpt

Opción B: agentes separados

• Agente A predeterminado: MiniMax
• Agente B predeterminado: OpenAI
• Enruta por agente o usa /agent para cambiar

Documentación: Modelos, Enrutamiento multiagente, MiniMax, OpenAI.

Sí. OpenClaw incluye algunos atajos predeterminados (solo se aplican cuando el modelo existe en agents.defaults.models):

• opus → anthropic/claude-opus-4-8
• sonnet → anthropic/claude-sonnet-4-6
• gpt → openai/gpt-5.4
• gpt-mini → openai/gpt-5.4-mini
• gpt-nano → openai/gpt-5.4-nano
• gemini → google/gemini-3.1-pro-preview
• gemini-flash → google/gemini-3-flash-preview
• gemini-flash-lite → google/gemini-3.1-flash-lite

Si defines tu propio alias con el mismo nombre, tu valor tiene prioridad.

Los alias provienen de agents.defaults.models.<modelId>.alias. Ejemplo:

{  agents: {    defaults: {      model: { primary: "anthropic/claude-opus-4-6" },      models: {        "anthropic/claude-opus-4-6": { alias: "opus" },        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },      },    },  },}

Luego /model sonnet (o /<alias> cuando sea compatible) se resuelve a ese ID de modelo.

OpenRouter (pago por token; muchos modelos):

{  agents: {    defaults: {      model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },      models: { "openrouter/anthropic/claude-sonnet-4-6": {} },    },  },  env: { OPENROUTER_API_KEY: "sk-or-..." },}

Z.AI (modelos GLM):

{  agents: {    defaults: {      model: { primary: "zai/glm-5" },      models: { "zai/glm-5": {} },    },  },  env: { ZAI_API_KEY: "..." },}

Si haces referencia a un proveedor/modelo pero falta la clave de proveedor requerida, recibirás un error de autenticación en tiempo de ejecución (por ejemplo, No API key found for provider "zai").

No se encontró ninguna clave de API para el proveedor después de agregar un agente nuevo

Esto normalmente significa que el agente nuevo tiene un almacén de autenticación vacío. La autenticación es por agente y se almacena en:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Opciones de corrección:

• Ejecuta openclaw agents add <id> y configura la autenticación durante el asistente.
• O copia solo perfiles estáticos portables api_key / token desde el almacén de autenticación del agente principal al almacén de autenticación del agente nuevo.
• Para perfiles OAuth, inicia sesión desde el agente nuevo cuando necesite su propia cuenta; de lo contrario, OpenClaw puede leer a través del agente predeterminado/principal sin clonar tokens de actualización.

No reutilices agentDir entre agentes; causa colisiones de autenticación/sesión.

La conmutación por error ocurre en dos etapas:

1. Rotación de perfiles de autenticación dentro del mismo proveedor.
2. Reserva de modelo al siguiente modelo en agents.defaults.model.fallbacks.

Los periodos de enfriamiento se aplican a los perfiles con errores (retroceso exponencial), por lo que OpenClaw puede seguir respondiendo incluso cuando un proveedor está limitado por tasa o falla temporalmente.

El grupo de límites de tasa incluye más que respuestas 429 simples. OpenClaw también trata mensajes como Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, resource exhausted y límites periódicos de ventanas de uso (weekly/monthly limit reached) como límites de tasa aptos para conmutación por error.

Algunas respuestas que parecen de facturación no son 402, y algunas respuestas HTTP 402 también permanecen en ese grupo transitorio. Si un proveedor devuelve texto explícito de facturación en 401 o 403, OpenClaw aún puede mantenerlo en la vía de facturación, pero los comparadores de texto específicos del proveedor permanecen limitados al proveedor propietario de ellos (por ejemplo, OpenRouter Key limit exceeded). Si un mensaje 402 en cambio parece una ventana de uso reintentable o un límite de gasto de organización/espacio de trabajo (daily limit reached, resets tomorrow, organization spending limit exceeded), OpenClaw lo trata como rate_limit, no como una desactivación prolongada por facturación.

Los errores de desbordamiento de contexto son diferentes: firmas como request_too_large, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model u ollama error: context length exceeded permanecen en la ruta de Compaction/reintento en lugar de avanzar a la reserva de modelo.

El texto genérico de error del servidor es intencionadamente más restringido que "cualquier cosa con unknown/error en ella". OpenClaw sí trata formas transitorias con alcance de proveedor como el An unknown error occurred escueto de Anthropic, el Provider returned error escueto de OpenRouter, errores de motivo de detención como Unhandled stop reason: error, cargas JSON api_error con texto transitorio del servidor (internal server error, unknown error, 520, upstream error, backend error) y errores de proveedor ocupado como ModelNotReadyException como señales de tiempo de espera/sobrecarga aptas para conmutación por error cuando el contexto del proveedor coincide. El texto genérico interno de reserva como LLM request failed with an unknown error. se mantiene conservador y no activa la reserva de modelo por sí solo.

Significa que el sistema intentó usar el ID de perfil de autenticación anthropic:default, pero no pudo encontrar credenciales para él en el almacén de autenticación esperado.

Lista de comprobación para corregirlo:

• Confirma dónde viven los perfiles de autenticación (rutas nuevas frente a heredadas)
  • Actual: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Heredada: ~/.openclaw/agent/* (migrada por openclaw doctor)
• Confirma que tu variable de entorno la carga el Gateway
  • Si configuras ANTHROPIC_API_KEY en tu shell pero ejecutas el Gateway mediante systemd/launchd, es posible que no la herede. Ponla en ~/.openclaw/.env o habilita env.shellEnv.
• Asegúrate de estar editando el agente correcto
  • Las configuraciones multiagente significan que puede haber varios archivos auth-profiles.json.
• Haz una comprobación básica del estado de modelo/autenticación
  • Usa openclaw models status para ver los modelos configurados y si los proveedores están autenticados.

Lista de comprobación para corregir "No credentials found for profile anthropic"

Esto significa que la ejecución está fijada a un perfil de autenticación de Anthropic, pero el Gateway no puede encontrarlo en su almacén de autenticación.

• Usa Claude CLI

  • Ejecuta openclaw models auth login --provider anthropic --method cli --set-default en el host del gateway.

• Si quieres usar una clave de API en su lugar

  • Pon ANTHROPIC_API_KEY en ~/.openclaw/.env en el host del gateway.

  • Borra cualquier orden fijado que fuerce un perfil ausente:

    openclaw models auth order clear --provider anthropic

• Confirma que estás ejecutando comandos en el host del gateway

  • En modo remoto, los perfiles de autenticación viven en la máquina del gateway, no en tu portátil.

Si tu configuración de modelos incluye Google Gemini como alternativa (o cambiaste a un atajo de Gemini), OpenClaw lo intentará durante la reserva de modelo. Si no configuraste credenciales de Google, verás No API key found for provider "google".

Corrección: proporciona autenticación de Google, o elimina/evita modelos de Google en agents.defaults.model.fallbacks / alias para que la reserva no enrute allí.

Solicitud de LLM rechazada: se requiere firma de pensamiento (Google Antigravity)

Causa: el historial de la sesión contiene bloques de pensamiento sin firmas (a menudo de un flujo abortado/parcial). Google Antigravity requiere firmas para los bloques de pensamiento.

Corrección: OpenClaw ahora elimina bloques de pensamiento sin firma para Google Antigravity Claude. Si aún aparece, inicia una sesión nueva o configura /thinking off para ese agente.

Un perfil de autenticación es un registro de credenciales con nombre (OAuth o clave de API) vinculado a un proveedor. Los perfiles viven en:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Para inspeccionar perfiles guardados sin volcar secretos, ejecuta openclaw models auth list (opcionalmente --provider <id> o --json). Consulta CLI de modelos para obtener detalles.

OpenClaw usa ID con prefijo de proveedor como:

• anthropic:default (común cuando no existe identidad de correo electrónico)
• anthropic:<email> para identidades OAuth
• ID personalizados que elijas (por ejemplo, anthropic:work)

Sí. La configuración admite metadatos opcionales para perfiles y un orden por proveedor (auth.order.<provider>). Esto no almacena secretos; asigna ID a proveedor/modo y establece el orden de rotación.

OpenClaw puede omitir temporalmente un perfil si está en un breve periodo de enfriamiento (límites de tasa/tiempos de espera/fallos de autenticación) o en un estado desactivado más prolongado (facturación/créditos insuficientes). Para inspeccionarlo, ejecuta openclaw models status --json y revisa auth.unusableProfiles. Ajuste: auth.cooldowns.billingBackoffHours*.

Los periodos de enfriamiento por límite de tasa pueden tener alcance de modelo. Un perfil que se está enfriando para un modelo aún puede ser utilizable para un modelo hermano en el mismo proveedor, mientras que las ventanas de facturación/desactivación siguen bloqueando todo el perfil.

También puedes definir una anulación de orden por agente (almacenada en el auth-state.json de ese agente) mediante la CLI:

# Defaults to the configured default agent (omit --agent)openclaw models auth order get --provider anthropic # Lock rotation to a single profile (only try this one)openclaw models auth order set --provider anthropic anthropic:default # Or set an explicit order (fallback within provider)openclaw models auth order set --provider anthropic anthropic:work anthropic:default # Clear override (fall back to config auth.order / round-robin)openclaw models auth order clear --provider anthropic

Para apuntar a un agente específico:

openclaw models auth order set --provider anthropic --agent main anthropic:default

Para verificar qué se intentará realmente, usa:

openclaw models status --probe

Si un perfil almacenado se omite del orden explícito, la sonda informa excluded_by_auth_order para ese perfil en lugar de intentarlo silenciosamente.

OpenClaw admite ambos:

• Inicio de sesión OAuth / CLI a menudo aprovecha el acceso de suscripción donde el proveedor lo admite. Para Anthropic, el backend Claude CLI de OpenClaw usa Claude Code claude -p; Anthropic actualmente lo trata como uso de Agent SDK/programático. Anthropic pausó el cambio de créditos independiente de Agent SDK del 15 de junio de 2026, por lo que por ahora esto todavía consume los límites de uso de la suscripción. Consulta el artículo del plan Agent SDK de Anthropic para ver el aviso de pausa actual.
• Claves de API usan facturación de pago por token.

El asistente admite explícitamente Anthropic Claude CLI, OpenAI Codex OAuth y claves de API.