OAuth

OpenClaw soporta “autenticación por suscripción” mediante OAuth para proveedores que lo ofrecen (particularmente OpenAI Codex (ChatGPT OAuth)). Para suscripciones de Anthropic, usa el flujo de setup-token. El uso de suscripciones de Anthropic fuera de Claude Code ha sido restringido para algunos usuarios en el pasado, así que trátalo como un riesgo a criterio del usuario y verifica tú mismo la política actual de Anthropic. OAuth de OpenAI Codex está explícitamente soportado para uso en herramientas externas como OpenClaw. Esta página explica:

Para Anthropic en producción, la autenticación con clave API es la ruta más segura y recomendada frente a la autenticación por suscripción con setup-token.

cómo funciona el intercambio de tokens OAuth (PKCE)
dónde se almacenan los tokens (y por qué)
cómo manejar múltiples cuentas (perfiles + sobrecargas por sesión)

OpenClaw también soporta plugins de proveedores que incluyen sus propios flujos de OAuth o clave API. Ejecútalos mediante:

openclaw models auth login --provider <id>

El sumidero de tokens (por qué existe)

Los proveedores OAuth suelen generar un nuevo refresh token durante los flujos de login/refresco. Algunos proveedores (o clientes OAuth) pueden invalidar refresh tokens anteriores cuando se emite uno nuevo para el mismo usuario/aplicación.

Síntoma práctico:

inicias sesión mediante OpenClaw y mediante Claude Code / Codex CLI → uno de ellos queda “desconectado” aleatoriamente después

Para reducir esto, OpenClaw trata auth-profiles.json como un sumidero de tokens:

el runtime lee credenciales desde un solo lugar
podemos mantener múltiples perfiles y enrutarlos de forma determinista

Almacenamiento (dónde residen los tokens)

Los secretos se almacenan por agente:

Perfiles de autenticación (OAuth + claves API + referencias opcionales a nivel de valor): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
Archivo de compatibilidad legacy: ~/.openclaw/agents/<agentId>/agent/auth.json (las entradas estáticas de api_key se eliminan al ser descubiertas)

Archivo legacy solo de importación (aún soportado, pero no es el almacén principal):

~/.openclaw/credentials/oauth.json (se importa a auth-profiles.json en el primer uso)

Todos los anteriores también respetan $OPENCLAW_STATE_DIR (sobreescritura del directorio de estado). Referencia completa: /gateway/configuration

Para referencias de secretos estáticos y el comportamiento de activación de snapshots en runtime, consulta Gestión de secretos.

Setup-token de Anthropic (autenticación por suscripción)

Advertencia: El soporte de setup-token de Anthropic es compatibilidad técnica, no una garantía de política. Anthropic ha bloqueado el uso de algunas suscripciones fuera de Claude Code en el pasado. Decide tú mismo si usar la autenticación por suscripción, y verifica los términos actuales de Anthropic.

Ejecuta claude setup-token en cualquier máquina, luego pégalo en OpenClaw:

openclaw models auth setup-token --provider anthropic

Si generaste el token en otro lugar, pégalo manualmente:

openclaw models auth paste-token --provider anthropic

Verificar:

openclaw models status

Los flujos de login interactivo de OpenClaw están implementados en @mariozechner/pi-ai y conectados a los wizards/comandos.

Setup-token de Anthropic

Forma del flujo:

ejecuta claude setup-token
pega el token en OpenClaw
almacena como perfil de autenticación por token (sin refresco)

La ruta del wizard es openclaw onboard → opción de autenticación setup-token (Anthropic).

OpenAI Codex (ChatGPT OAuth)

OAuth de OpenAI Codex está explícitamente soportado para uso fuera del CLI de Codex, incluyendo flujos de trabajo de OpenClaw.

Forma del flujo (PKCE):

genera verificador/challenge PKCE + state aleatorio
abre https://auth.openai.com/oauth/authorize?...
intenta capturar el callback en http://127.0.0.1:1455/auth/callback
si el callback no puede enlazarse (o estás en remoto/headless), pega la URL/código de redirección
intercambia en https://auth.openai.com/oauth/token
extrae accountId del access token y almacena { access, refresh, expires, accountId }

La ruta del wizard es openclaw onboard → opción de autenticación openai-codex.

Refresco + expiración

Los perfiles almacenan una marca de tiempo expires.

En runtime:

si expires está en el futuro → usa el access token almacenado
si expiró → refresca (bajo un bloqueo de archivo) y sobrescribe las credenciales almacenadas

El flujo de refresco es automático; generalmente no necesitas gestionar los tokens manualmente.

Múltiples cuentas (perfiles) + enrutamiento

Dos patrones:

1) Preferido: agentes separados

Si quieres que “personal” y “trabajo” nunca interactúen, usa agentes aislados (sesiones + credenciales + workspace separados):

openclaw agents add work
openclaw agents add personal

Luego configura la autenticación por agente (wizard) y enruta los chats al agente correcto.

2) Avanzado: múltiples perfiles en un agente

auth-profiles.json soporta múltiples IDs de perfil para el mismo proveedor.

Elige qué perfil se usa:

globalmente mediante ordenamiento de configuración (auth.order)
por sesión mediante /model ...@<profileId>

Ejemplo (sobreescritura por sesión):

/model Opus@anthropic:work

Para ver qué IDs de perfil existen:

openclaw channels list --json (muestra auth[])

Documentación relacionada:

/concepts/model-failover (reglas de rotación + cooldown)
/tools/slash-commands (superficie de comandos)