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 usar 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 configurar provider/model explícitamente.

Valor predeterminado recomendado: usa el modelo más potente de última generación disponible en tu conjunto de proveedores. Para agentes con herramientas habilitadas o entradas no confiables: 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 práctica: usa el mejor modelo que puedas pagar 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 demasiado 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)
• editar agents.defaults.model en ~/.openclaw/openclaw.json

Evita config.apply con un objeto parcial a menos 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 repararla.

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 cambiar manualmente, 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 firmemente modelos grandes para cualquier bot que pueda usar herramientas. Si aun así quieres modelos pequeños, habilita el aislamiento y listas estrictas de herramientas permitidas.

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

• Estas implementaciones pueden diferir y cambiar con el tiempo; no hay una recomendación fija de proveedor.
• Revisa la configuración de tiempo de ejecución actual en cada Gateway con openclaw models status.
• Para agentes sensibles a la seguridad o con herramientas habilitadas, usa el modelo más potente de última generación 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 añadir 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á después. También muestra el endpoint del 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, selecciónalo 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 de 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 coincida el id de modelo sin proveedor.

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 valores predeterminados configurados, primarios de trabajos cron y estado de respaldo seleccionado automáticamente.

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

Consulta Modelos y Conmutación por error de modelos.

Sí. Trata la elección del modelo y la elección del tiempo de ejecución por separado:

• Agente de programación Codex nativo: configura agents.defaults.model.primary como openai/gpt-5.5. Inicia sesión con openclaw models auth login --provider openai-codex 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 la API de OpenAI que no son de agente.
• Autenticación con clave de API para agente de OpenAI: usa /model openai/gpt-5.5 con un perfil de clave de API openai-codex ordenado.
• Subagentes: enruta tareas de programación a un agente enfocado en Codex con su propio modelo openai/gpt-5.5.

Consulta Modelos y Comandos de barra.

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.
• Valor predeterminado por modelo: configura agents.defaults.models["openai/gpt-5.5"].params.fastMode como true.

Ejemplo:

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: {            fastMode: true,          },        },      },    },  },}

Para OpenAI, el modo rápido se asigna a service_tier = "priority" en solicitudes Responses nativas compatibles. Las anulaciones de sesión con /fast tienen prioridad sobre los valores predeterminados de configuración.

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

Si agents.defaults.models está configurado, 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. Solució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 de solución:

1. Actualiza a una versión actual de OpenClaw (o ejecuta desde main de origen), 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 env/perfiles de 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-M2.7 o minimax/MiniMax-M2.7-highspeed para configuración con clave de API, o minimax-portal/MiniMax-M2.7 / minimax-portal/MiniMax-M2.7-highspeed para configuración con OAuth.

4. Ejecuta:

   openclaw models list

   y elige desde 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-M2.7" },      models: {        "minimax/MiniMax-M2.7": { alias: "minimax" },        "openai/gpt-5.5": { alias: "gpt" },      },    },  },}

Entonces:

/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-7
• 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-preview

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

Los alias vienen 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" },        "anthropic/claude-haiku-4-5": { alias: "haiku" },      },    },  },}

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, obtendrá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 suele significar 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 portátiles estáticos 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 desde el agente predeterminado/principal sin clonar tokens de actualización.

No reutilices agentDir entre agentes; provoca 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. Respaldo de modelo al siguiente modelo en agents.defaults.model.fallbacks.

Los tiempos de espera se aplican a los perfiles con errores (retroceso exponencial), por lo que OpenClaw puede seguir respondiendo incluso cuando un proveedor tiene límite de frecuencia o falla temporalmente.

El grupo de límites de frecuencia 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 ventana de uso (weekly/monthly limit reached) como límites de frecuencia que justifican 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 al que pertenecen (por ejemplo, OpenRouter Key limit exceeded). Si un mensaje 402 parece en cambio un límite reintentable de ventana de uso o 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 larga 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 al respaldo de modelo.

El texto genérico de error de servidor es intencionalmente más estrecho que "cualquier cosa con unknown/error en él". OpenClaw sí trata formas transitorias limitadas por proveedor como An unknown error occurred sin más de Anthropic, Provider returned error sin más de OpenRouter, errores de motivo de detención como Unhandled stop reason: error, cargas JSON api_error con texto transitorio de 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 que justifican conmutación por error cuando el contexto del proveedor coincide. El texto genérico interno de respaldo como LLM request failed with an unknown error. permanece conservador y no activa el respaldo 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 verificación de corrección:

• 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 esté cargada por el Gateway
  • Si defines ANTHROPIC_API_KEY en tu shell pero ejecutas el Gateway mediante systemd/launchd, puede 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.
• Comprueba rápidamente el estado del modelo/autenticación
  • Usa openclaw models status para ver los modelos configurados y si los proveedores están autenticados.

Lista de verificación de corrección para "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 faltante:

    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 modelo incluye Google Gemini como respaldo (o cambiaste a una abreviatura de Gemini), OpenClaw lo intentará durante el respaldo de modelo. Si no has configurado 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 el respaldo no se dirija ahí.

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

Causa: el historial de sesión contiene bloques de pensamiento sin firmas (a menudo de una transmisión abortada/parcial). Google Antigravity requiere firmas para los bloques de pensamiento.

Corrección: OpenClaw ahora elimina bloques de pensamiento sin firmar para Google Antigravity Claude. Si aún aparece, inicia una sesión nueva o define /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 más detalles.

OpenClaw usa IDs con prefijo de proveedor como:

• anthropic:default (común cuando no existe identidad de correo electrónico)
• anthropic:<email> para identidades OAuth
• IDs 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 IDs a proveedor/modo y define el orden de rotación.

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

Los tiempos de espera por límite de frecuencia pueden estar limitados al modelo. Un perfil que está en espera para un modelo aún puede ser utilizable para un modelo hermano en el mismo proveedor, mientras que las ventanas de facturación/deshabilitación siguen bloqueando todo el perfil.

También puedes definir una sobrescritura 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, el sondeo informa excluded_by_auth_order para ese perfil en lugar de intentarlo silenciosamente.

OpenClaw admite ambos:

• OAuth a menudo aprovecha el acceso por suscripción (cuando corresponde).
• Las claves de API usan facturación por token.

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