La autenticación de modelos en OpenClaw

La documentación abre esta página con una nota de alcance que vale la pena repetir: trata la autenticación con los proveedores de modelos (claves de API, OAuth, la reutilización de Claude CLI y el token de configuración de Anthropic), no el token ni la contraseña que protegen la conexión con el Gateway. OpenClaw admite OAuth y claves de API para los proveedores, y la recomendación es clara: para un host de Gateway siempre encendido, una clave de API es la opción más predecible, mientras que los flujos de suscripción y OAuth funcionan cuando coinciden con tu cuenta del proveedor. Estos son la configuración recomendada, las vías de Anthropic, dónde viven las credenciales, cómo comprobarlas, la rotación y cómo elegir qué credencial usa una sesión.

La configuración recomendada

• Crea una clave en la consola del proveedor, expórtala en el host del Gateway, la máquina que ejecuta el Gateway, y compruébala con el comando de estado de los modelos.
• Si el Gateway se ejecuta con systemd o launchd, pon la clave en el archivo env del directorio de estado para que el daemon pueda leerla, reinicia y vuelve a comprobarlo con el estado de los modelos y el doctor; la configuración inicial puede guardar las claves para que las use el daemon si prefieres no gestionar variables.
• La reutilización de Claude CLI es una vía aprobada por Anthropic y la preferida para el uso local o de escritorio cuando hay un inicio de sesión de Claude en el host: inicia sesión en Claude Code y luego indica a OpenClaw que enrute los modelos de Anthropic a través del backend local de Claude CLI; OpenClaw nunca lee, guarda, renueva ni reenvía los tokens de inicio de sesión nativos, el proceso instalado renueva su propio inicio de sesión y el servicio debe poder resolver el ejecutable en su PATH.
• El token de configuración es la otra vía de Anthropic: un token de larga duración que Claude Code muestra en cualquier máquina y que se guarda en el host con el comando de inicio de sesión de autenticación en modo setup-token, que necesita una terminal interactiva.

Para un host de gateway siempre encendido, una clave de API es la opción más predecible; los flujos de suscripción/OAuth también funcionan cuando coinciden con el modelo de cuenta de tu proveedor.

Dónde viven las credenciales

La introducción manual de tokens funciona con cualquier proveedor y escribe en el almacén de autenticación SQLite por agente, que es de donde OpenClaw lee los perfiles de autenticación; los detalles del endpoint, como las URL base, los tipos de API, los ids de modelo, los encabezados y los tiempos de espera, van en la configuración del proveedor, no en los perfiles. El doctor importa las instalaciones antiguas con archivos de autenticación JSON y crea copias de seguridad con marca de tiempo, las rutas externas como un modo SDK de Bedrock son metadatos de configuración y no credenciales, y las credenciales pueden ser referencias a secretos para claves y tokens, salvo en los perfiles en modo OAuth, que las rechazan. Eliminar la autenticación guardada no revoca la clave en el proveedor, y eliminar la autenticación de un proveedor desde el plano de control mientras el Gateway está en marcha aborta las ejecuciones activas en ese proveedor con un motivo de parada de autenticación revocada, para que los clientes puedan mostrar por qué se detuvo la ejecución.

Comprobar, rotar, elegir

• El estado de los modelos y el doctor son las comprobaciones; para la automatización, el indicador de comprobación sale con código uno cuando una credencial ha caducado o falta y con código dos cuando está a punto de caducar, y el indicador de sondeo ejecuta sondeos de autenticación en vivo con indicadores de alcance e informa de los perfiles excluidos por el orden de autenticación, de los proveedores con autenticación pero sin ningún modelo sondeable y de los periodos de espera por límite de tasa limitados a un modelo, que dejan utilizables los modelos hermanos.
• Algunos proveedores reintentan una solicitud limitada por tasa con otra clave configurada, en una prioridad fija: una única clave de sobrescritura en vivo, una lista delimitada de claves, la variable de clave simple y, después, cualquier variante con prefijo, y los proveedores de Google también recurren a la clave genérica de Google; la rotación solo se activa con errores de límite de tasa, de cuota y de demasiadas solicitudes, y las frases de limitación específicas de cada proveedor alimentan en su lugar la clasificación de conmutación por error, que es independiente.
• Los perfiles de OpenAI con clave de API y los perfiles OAuth de ChatGPT o Codex usan el id canónico de OpenAI, y el doctor reescribe los ids de perfil heredados de Codex y las entradas del orden de autenticación. Varios inicios de sesión para un mismo proveedor se mantienen separados mediante ids de perfil, un indicador de forzado elimina un perfil bloqueado o de la cuenta equivocada y vuelve a ejecutar el flujo, una sesión fija una credencial concreta con el comando de modelo y un sufijo de perfil, y los comandos de orden de autenticación por agente consultan, establecen y borran la selección automática.

OpenClaw con Claude y OpenClaw con una suscripción de ChatGPT son las dos vías de suscripción que esta página distingue de una clave de API.

Cuando falla

“No credentials found” significa que la clave no está en el host del Gateway o que nunca se ejecutó la vía del token de configuración, y el estado de los modelos confirma la solución; un token a punto de caducar o caducado aparece en ese mismo estado, y se renueva con el token de configuración o se sustituye por una clave de API. Los comandos de nueva sesión y de restablecimiento borran el estado automático de respaldo y de rotación, pero conservan las fijaciones explícitas de perfiles que sean válidas, y cambiar el orden de autenticación solo cambia la selección automática. La conmutación por error de modelos en OpenClaw es el mecanismo que cambia de modelo o de proveedor ante fallos repetidos, distinto de la rotación de claves, y los secretos en OpenClaw, la sintaxis de referencia que usan las referencias a claves y tokens.

En Diali

En Diali, la clave que aportas va al Vault y la configuración que generamos hace referencia a ella; sin clave, el asistente funciona con los créditos de IA gestionados, y el panel muestra cuál se está usando. También puede funcionar con un plan de ChatGPT, SuperGrok o MiniMax que ya pagas: el panel muestra un código de un solo uso, lo apruebas en la propia página del proveedor y el asistente guarda el inicio de sesión, así que Diali nunca tiene el token. El setup token de Anthropic y el inicio de sesión con Claude CLI están desactivados en Diali, porque los términos de Anthropic no permiten que un servicio alojado funcione con una suscripción de Claude; en su lugar sirven una clave de API de Anthropic o los créditos gestionados. OpenClaw alojado en Diali es el asistente, y los modelos y proveedores de OpenClaw trata los proveedores que hay detrás de las claves.

• Una clave de API en el host para un Gateway siempre encendido.
• Los perfiles de autenticación, en SQLite; los endpoints, en la configuración.
• Rotación ante límites de tasa; conmutación por error para todo lo demás.