Saltar al contenido principal

​
OAuth

OpenClaw admite “autenticación por suscripción” mediante OAuth para proveedores que la ofrecen (en particular OpenAI Codex (ChatGPT OAuth)). Para suscripciones de Anthropic, use el flujo setup-token. Esta página explica:
  • cómo funciona el intercambio de tokens de OAuth (PKCE)
  • dónde se almacenan los tokens (y por qué)
  • cómo manejar múltiples cuentas (perfiles + anulaciones por sesión)
OpenClaw también admite plugins de proveedor que incluyen sus propios flujos de OAuth o de clave de API. Ejecútelos mediante: 
openclaw models auth login --provider <id>

​
El sumidero de tokens (por qué existe)

Los proveedores OAuth suelen emitir un nuevo token de actualización durante los flujos de inicio de sesión/actualización. Algunos proveedores (o clientes OAuth) pueden invalidar tokens de actualización anteriores cuando se emite uno nuevo para el mismo usuario/aplicación. Síntoma práctico:
  • inicia sesión mediante OpenClaw y mediante Claude Code / Codex CLI → uno de ellos termina “cerrando sesión” de forma aleatoria más tarde
Para reducir esto, OpenClaw trata auth-profiles.json como un sumidero de tokens:
  • el runtime lee las credenciales desde un solo lugar
  • podemos mantener múltiples perfiles y enrutarlos de forma determinista

​
Almacenamiento (dónde viven los tokens)

Los secretos se almacenan por agente:
  • Perfiles de autenticación (OAuth + claves de API): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Caché de runtime (gestionada automáticamente; no la edite): ~/.openclaw/agents/<agentId>/agent/auth.json
Archivo heredado solo para importación (aún compatible, pero no es el almacén principal):
  • ~/.openclaw/credentials/oauth.json (importado a auth-profiles.json en el primer uso)
Todo lo anterior también respeta $OPENCLAW_STATE_DIR (anulación del directorio de estado). Referencia completa: /gateway/configuration

​
Anthropic setup-token (autenticación por suscripción)

Ejecute claude setup-token en cualquier máquina y luego péguelo en OpenClaw: 
openclaw models auth setup-token --provider anthropic
Si generó el token en otro lugar, péguelo manualmente: 
openclaw models auth paste-token --provider anthropic
Verifique: 
openclaw models status

​
Intercambio OAuth (cómo funciona el inicio de sesión)

Los flujos interactivos de inicio de sesión de OpenClaw están implementados en @mariozechner/pi-ai y conectados a los asistentes/comandos.

​
Anthropic (Claude Pro/Max) configuración del token

Forma del flujo:
  1. ejecute claude setup-token
  2. pegue el token en OpenClaw
  3. almacénelo como un perfil de autenticación por token (sin actualización)
La ruta del asistente es openclaw onboard → opción de autenticación setup-token (Anthropic).

​
OpenAI Codex (ChatGPT OAuth)

Forma del flujo (PKCE):
  1. generar verificador/desafío PKCE + state aleatorio
  2. abrir https://auth.openai.com/oauth/authorize?...
  3. intentar capturar el callback en http://127.0.0.1:1455/auth/callback
  4. si el callback no puede enlazarse (o está remoto/sin interfaz), pegar la URL/código de redirección
  5. intercambiar en https://auth.openai.com/oauth/token
  6. extraer accountId del token de acceso y almacenar { access, refresh, expires, accountId }
La ruta del asistente es openclaw onboard → opción de autenticación openai-codex.

​
Actualización + caducidad

Los perfiles almacenan una marca de tiempo expires. En tiempo de ejecución:
  • si expires está en el futuro → use el token de acceso almacenado
  • si está caducado → actualice (bajo un bloqueo de archivo) y sobrescriba las credenciales almacenadas
El flujo de actualización es automático; por lo general no necesita gestionar los tokens manualmente.

​
Múltiples cuentas (perfiles) + enrutamiento

Dos patrones:

​
1. Preferido: agentes separados

Si quiere que “personal” y “trabajo” nunca interactúen, use agentes aislados (sesiones + credenciales + espacio de trabajo separados): 
openclaw agents add work
openclaw agents add personal
Luego configure la autenticación por agente (asistente) y enrute los chats al agente correcto.

​
2. Avanzado: múltiples perfiles en un solo agente

auth-profiles.json admite múltiples ID de perfil para el mismo proveedor. Elija qué perfil se usa:
  • globalmente mediante el orden de configuración (auth.order)
  • por sesión mediante /model ...@<profileId>
Ejemplo (anulación por sesión):
  • /model Opus@anthropic:work
Cómo ver qué ID de perfil existen:
  • openclaw channels list --json (muestra auth[])
Documentación relacionada: