Preguntas frecuentes: modelos y autenticación

Se establece con:

agents.defaults.model.primary

Los modelos son referencias provider/model (ejemplo: openai/gpt-5.5, anthropic/claude-sonnet-4-6). Establezca siempre provider/model explícitamente. Si se omite el proveedor, OpenClaw intenta primero encontrar una coincidencia de alias, después una coincidencia única entre los proveedores configurados para ese identificador de modelo y, por último, recurre al proveedor predeterminado configurado (ruta de compatibilidad obsoleta). Si ese proveedor ya no dispone del modelo predeterminado configurado, OpenClaw recurre al primer proveedor/modelo configurado en lugar de usar un valor predeterminado obsoleto.

Utilice el modelo más potente de última generación que ofrezca su conjunto de proveedores, especialmente para agentes con herramientas habilitadas o que reciben entradas no confiables; los modelos más débiles o excesivamente cuantizados son más vulnerables a la inyección de prompts y a comportamientos inseguros (consulte Seguridad). Dirija los chats rutinarios o de bajo riesgo a modelos más económicos según el rol del agente.

Dirija los modelos por agente y utilice subagentes para paralelizar tareas largas (cada subagente consume sus propios tokens). Consulte Modelos, Subagentes, MiniMax y Modelos locales.

Cambie únicamente los campos del modelo; evite reemplazar toda la configuración.

• /model en el chat (por sesión; consulte Comandos de barra)
• openclaw models set ... (actualiza únicamente la configuración del modelo)
• openclaw configure --section model (interactivo)
• edite agents.defaults.model directamente en ~/.openclaw/openclaw.json

Para las ediciones mediante RPC, inspeccione primero con config.schema.lookup (ruta normalizada, documentación superficial del esquema y resúmenes de elementos secundarios) y, después, prefiera config.patch en lugar de config.apply con un objeto parcial. Si se sobrescribió la configuración, restáurela desde una copia de seguridad o ejecute openclaw doctor para repararla.

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

Sí; Ollama es la opción más sencilla. Configuración rápida:

1. Instale Ollama desde https://ollama.com/download
2. Descargue un modelo local, por ejemplo, ollama pull gemma4
3. Para usar también modelos en la nube, ejecute ollama signin
4. Ejecute openclaw onboard, elija Ollama y, después, Local o Cloud + Local

Cloud + Local proporciona modelos en la nube además de los modelos locales de Ollama; los modelos en la nube como kimi-k2.5:cloud no requieren una descarga local. Para cambiar manualmente: openclaw models list y, después, openclaw models set ollama/<model>.

Los modelos más pequeños o muy cuantizados son más vulnerables a la inyección de prompts. Utilice modelos grandes para cualquier bot con acceso a herramientas; si aun así utiliza modelos pequeños, habilite el aislamiento y listas estrictas de herramientas permitidas.

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

Envíe /model <name> como mensaje independiente. Consulte Comandos de barra para ver la lista completa de comandos, incluido el selector numerado (/model, /model list, /model 3), /model default para borrar una anulación de sesión y /model status para consultar los detalles del endpoint/modo de API.

Fuerce un perfil de autenticación específico por sesión con @profile:

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

Para desanclar un perfil establecido con @profile, vuelva a ejecutar /model sin el sufijo (por ejemplo, /model anthropic/claude-opus-4-6) o seleccione el predeterminado en /model. Utilice /model status para confirmar el perfil de autenticación activo.

/model provider/model selecciona esa ruta de proveedor exacta. Por ejemplo, qianfan/deepseek-v4-flash y deepseek/deepseek-v4-flash son referencias diferentes aunque el identificador de modelo coincida; OpenClaw no cambia silenciosamente de proveedor al encontrar una coincidencia de identificador sin proveedor.

Una referencia /model seleccionada por el usuario es estricta respecto a la conmutación por error: si ese proveedor/modelo deja de estar disponible, la respuesta falla de forma visible en lugar de recurrir a agents.defaults.model.fallbacks. Las cadenas de conmutación por error configuradas siguen aplicándose a los valores predeterminados configurados, los modelos principales de trabajos Cron y el estado de conmutación por error seleccionado automáticamente. Cuando una ejecución sin anulación de sesión puede utilizar la conmutación por error, OpenClaw prueba primero el proveedor/modelo solicitado, después las alternativas configuradas y, por último, el modelo principal configurado; por lo tanto, los identificadores de modelo sin proveedor duplicados nunca vuelven directamente al proveedor predeterminado.

Consulte Modelos y Conmutación por error de modelos.

Sí; la elección del modelo y la elección del entorno de ejecución son independientes:

• Agente de programación nativo de Codex: establezca agents.defaults.model.primary en openai/gpt-5.5. Inicie sesión con openclaw models auth login --provider openai para usar la autenticación de suscripción de ChatGPT/Codex.
• Tareas directas de la API de OpenAI fuera del bucle del agente: configure OPENAI_API_KEY para imágenes, embeddings, voz, tiempo real y otras superficies de la API de OpenAI ajenas al agente.
• Autenticación del agente de OpenAI mediante clave de API: /model openai/gpt-5.5 con un perfil de clave de API openai ordenado.
• Subagentes: dirija las tareas de programación a un agente centrado en Codex con su propio modelo openai/gpt-5.5.

Consulte Modelos y Comandos de barra.

• Por sesión: envíe /fast on mientras utiliza openai/gpt-5.5.
• Valor predeterminado por modelo: establezca agents.defaults.models["openai/gpt-5.5"].params.fastMode en true.
• Límite automático: /fast auto o params.fastMode: "auto" ejecuta rápidamente las nuevas llamadas al modelo hasta alcanzar el límite y, después, ejecuta las llamadas posteriores de reintento, conmutación por error, resultado de herramienta o continuación sin el modo rápido. El límite predeterminado es de 60 segundos; anúlelo con params.fastAutoOnSeconds en el modelo.

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

El modo rápido se asigna a service_tier = "priority" en las solicitudes nativas de OpenAI Responses; los valores service_tier existentes se conservan y el modo rápido no reescribe reasoning ni text.verbosity. Las anulaciones de sesión /fast tienen prioridad sobre los valores predeterminados de configuración.

Consulte Razonamiento y modo rápido y la sección Modo rápido de Configuración avanzada en la página del proveedor OpenAI.

Si agents.defaults.modelPolicy.allow no está vacío, se convierte en la lista de permitidos para /model, las anulaciones de sesión y --model. Seleccionar un modelo que no figure en esa lista devuelve lo siguiente en lugar de una respuesta normal:

La anulación del modelo "provider/model" no está permitida por agents.defaults.modelPolicy.allow.

Solución: añada el modelo exacto o un comodín de proveedor como "provider/*" a la lista modelPolicy.allow indicada, elimine o vacíe esa lista, o seleccione un modelo de /model list. Si el comando también incluía --runtime codex, actualice primero la lista de permitidos y, después, vuelva a intentar el mismo comando /model provider/model --runtime codex.

Si se utiliza una versión anterior de OpenClaw, actualícela primero (o ejecute desde el código fuente main) y reinicie el Gateway; es posible que MiniMax-M3 todavía no figure en el catálogo de la versión instalada. De lo contrario, el proveedor MiniMax no está configurado (no se encontró ninguna entrada de proveedor ni ningún perfil de autenticación), por lo que no se puede resolver el modelo. Consulte la sección Solución de problemas de la página del proveedor MiniMax para ver la lista de comprobación completa de la solución, la tabla de identificadores de proveedor/modelo y un ejemplo de bloque de configuración.

Sí. Utilice MiniMax como predeterminado y cambie de modelo por sesión; las alternativas son para errores, no para «tareas difíciles», así que utilice /model o un agente independiente.

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" },      },    },  },}

Después, /model gpt.

Opción B: agentes independientes: el agente A utiliza MiniMax de forma predeterminada y el agente B utiliza OpenAI; dirija las tareas por agente o utilice /agent para cambiar.

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

Sí; son abreviaturas integradas que solo se aplican cuando el modelo de destino existe en agents.defaults.models:

Un alias propio con el mismo nombre anula el integrado.

Los alias se encuentran en agents.defaults.models.<modelId>.alias:

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

Después, /model sonnet (o /<alias> cuando sea compatible) se resuelve como ese identificador 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.1" },      models: { "zai/glm-5.1": {} },    },  },  env: { ZAI_API_KEY: "..." },}

Si falta la clave del proveedor correspondiente a un proveedor/modelo referenciado, se produce 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 añadir un agente nuevo

Un agente nuevo tiene un almacén de autenticación vacío; la autenticación es específica de cada agente y se almacena en:

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

Solución: ejecuta openclaw agents add <id> y configura la autenticación en el asistente, o copia únicamente los perfiles estáticos portátiles api_key/token del almacén del agente principal. Para OAuth, inicia sesión desde el agente nuevo cuando necesite su propia cuenta. Consulta Enrutamiento multiagente para conocer todas las reglas de reutilización de agentDir y uso compartido de credenciales; nunca reutilices agentDir entre agentes.

Consta de dos etapas:

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

Se aplican periodos de espera a los perfiles que fallan (retroceso exponencial), por lo que OpenClaw sigue respondiendo cuando un proveedor limita la frecuencia o falla temporalmente.

El grupo de límites de frecuencia abarca más que simples 429: Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, resource exhausted y los límites periódicos de ventanas de uso (weekly/monthly limit reached) se consideran límites de frecuencia que justifican una conmutación por error.

Las respuestas de facturación no siempre son 402, y algunos 402 permanecen en el grupo de errores transitorios o límites de frecuencia en lugar de pasar a la vía de facturación. El texto explícito de facturación en 401/403 aún puede dirigir a facturación; los detectores de texto específicos de cada proveedor (p. ej., Key limit exceeded de OpenRouter) quedan limitados a su propio proveedor. Un 402 que parezca un límite reintentable de ventana de uso o de gasto de la organización o del espacio de trabajo (daily limit reached, resets tomorrow, organization spending limit exceeded) se trata como rate_limit, no como una desactivación prolongada por facturación.

Los errores de desbordamiento de contexto quedan totalmente fuera de la ruta alternativa: las 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 o ollama error: context length exceeded pasan a Compaction y reintento en lugar de avanzar al siguiente modelo alternativo.

El texto genérico de error del servidor es más específico que «cualquier cosa que contenga unknown/error». Estas formas transitorias limitadas al proveedor sí se consideran señales de conmutación por error: An unknown error occurred sin formato de Anthropic, Provider returned error sin formato de OpenRouter, errores de motivo de detención como Unhandled stop reason: error, cargas útiles 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 cuando coincide el contexto del proveedor. El texto genérico interno de alternativa como LLM request failed with an unknown error. se interpreta de forma conservadora y no activa una alternativa por sí solo.

El identificador de perfil de autenticación anthropic:default no tiene credenciales en el almacén de autenticación esperado.

Lista de comprobación para solucionarlo:

• Confirma dónde se almacenan los perfiles: ubicación actual: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json; ubicación heredada: ~/.openclaw/agent/* (migrada por openclaw doctor).
• Confirma que el Gateway carga la variable de entorno. Si ANTHROPIC_API_KEY solo está definida en el shell, no llegará a un Gateway ejecutado mediante systemd/launchd; añádela a ~/.openclaw/.env o habilita env.shellEnv.
• Confirma que estás editando el agente correcto: las configuraciones multiagente tienen varios archivos auth-profiles.json.
• Ejecuta openclaw models status para ver los modelos configurados y el estado de autenticación del proveedor.

Para "No credentials found for profile anthropic" (sin sufijo de correo electrónico):

La ejecución está fijada a un perfil de Anthropic que el Gateway no puede encontrar.

• Usa la CLI de Claude: ejecuta openclaw models auth login --provider anthropic --method cli --set-default en el host del Gateway.

• Si se prefiere una clave de API: añade ANTHROPIC_API_KEY a ~/.openclaw/.env en el host del Gateway y, a continuación, borra cualquier orden fijado que fuerce el uso del perfil ausente:

  openclaw models auth order clear --provider anthropic

• Modo remoto: los perfiles de autenticación se almacenan en la máquina del Gateway, no en el portátil; confirma que los comandos se ejecutan allí.

Si la configuración de modelos incluye Google Gemini como alternativa (o si se cambió a un alias de Gemini), OpenClaw lo intenta durante la conmutación por error. Si no hay credenciales de Google configuradas, se obtiene No API key found for provider "google". Solución: añade la autenticación de Google o elimina los modelos de Google de agents.defaults.model.fallbacks/aliases.

Solicitud al LLM rechazada: se requiere una firma de razonamiento (Google Antigravity)

Causa: el historial de la sesión contiene bloques de razonamiento sin firmas (a menudo debido a un flujo interrumpido o parcial); Google Antigravity exige firmas en los bloques de razonamiento. OpenClaw elimina los bloques de razonamiento sin firma para Google Antigravity Claude; si el problema persiste, inicia una sesión nueva o establece /thinking off para ese agente.

Un registro de credenciales con nombre (OAuth o clave de API) vinculado a un proveedor, almacenado en:

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

Inspecciona los perfiles guardados sin mostrar secretos: openclaw models auth list (opcionalmente --provider <id> o --json). Consulta CLI de modelos.

Con prefijo del proveedor: anthropic:default (habitual cuando no existe una identidad de correo electrónico), anthropic:<email> para identidades OAuth o un identificador personalizado que se elija (p. ej., anthropic:work).

Sí. La configuración auth.order.<provider> establece el orden de rotación por proveedor (solo metadatos; no se almacenan secretos).

OpenClaw puede omitir un perfil durante un breve periodo de espera (límites de frecuencia, tiempos de espera agotados o fallos de autenticación) o durante un estado más prolongado de desactivación (facturación o créditos insuficientes). Inspecciónalo con openclaw models status --json y comprueba auth.unusableProfiles. Los periodos de espera por límites de frecuencia pueden limitarse a un modelo: un perfil en periodo de espera para un modelo aún puede atender a un modelo relacionado del mismo proveedor; las ventanas de facturación o desactivación bloquean todo el perfil.

Establece una anulación del orden por agente (almacenada en el archivo auth-state.json de ese agente):

# Usa de forma predeterminada el agente predeterminado configurado (omite --agent)openclaw models auth order get --provider anthropic # Limita la rotación a un solo perfilopenclaw models auth order set --provider anthropic anthropic:default # O establece un orden explícito (alternativa dentro del proveedor)openclaw models auth order set --provider anthropic anthropic:work anthropic:default # Borra la anulación (vuelve a la configuración auth.order / round-robin)openclaw models auth order clear --provider anthropic # Apunta a un agente específicoopenclaw models auth order set --provider anthropic --agent main anthropic:default

Verifica qué se probará realmente: openclaw models status --probe. Un perfil almacenado que se omita de un orden explícito muestra excluded_by_auth_order en lugar de probarse silenciosamente.

• El inicio de sesión con OAuth o mediante la CLI suele utilizar el acceso por suscripción cuando el proveedor lo admite. Para Anthropic, el backend de la CLI de Claude de OpenClaw usa claude -p de Claude Code, que Anthropic considera actualmente un uso programático o mediante el Agent SDK que consume los límites de uso de la suscripción; consulta Anthropic para conocer el estado actual de la pausa de facturación y los enlaces a las fuentes.
• Las claves de API usan facturación por token.

El asistente admite la CLI de Anthropic Claude, OAuth de OpenAI Codex y claves de API.