OAuth

OpenClaw soporta "autenticación de suscripción" via OAuth para proveedores que lo ofrecen (notablemente OpenAI Codex (ChatGPT OAuth)). Para suscripciones de Anthropic, usa el flujo setup-token. Esta página explica:

- 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 + anulaciones por sesión)

OpenClaw también soporta plugins de proveedor que traen sus propios flujos OAuth o de clave API. Ejecútalos via:

openclaw models auth login --provider <id>

Los proveedores OAuth comúnmente generan un nuevo refresh token durante flujos de login/refresh. Algunos proveedores (o clientes OAuth) pueden invalidar refresh tokens más antiguos cuando se emite uno nuevo para el mismo usuario/app.

Síntoma práctico:

- inicias sesión via OpenClaw _y_ via Claude Code / Codex CLI → uno de ellos aleatoriamente es "desconectado" después

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

- el runtime lee credenciales de un solo lugar

- podemos mantener múltiples perfiles y enrutarlos determinísticamente

Los secretos se almacenan por agente:

- Perfiles de autenticación (OAuth + claves API): ''~/.openclaw/agents/<agentId>/agent/auth-profiles.json''

- Caché de runtime (gestionado automáticamente; no editar): ''~/.openclaw/agents/<agentId>/agent/auth.json''

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

- ''~/.openclaw/credentials/oauth.json'' (importado a ''auth-profiles.json'' en primer uso)

Todo lo anterior también respeta ''$OPENCLAW_STATE_DIR'' (anulación de directorio de estado). Referencia completa: ''/gateway/configuration''

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 interactivos de OpenClaw están implementados en ''@mariozechner/pi-ai'' y cableados en los asistentes/comandos.

Forma del flujo:

1. ejecuta ''claude setup-token''

2. pega el token en OpenClaw

3. almacena como un perfil de autenticación de token (sin refresh)'
'La ruta del asistente es ''openclaw onboard'' → elección de auth ''setup-token'' (Anthropic).

Forma del flujo (PKCE):

1. genera verificador/desafío PKCE + ''state'' aleatorio

2. abre ''https://auth.openai.com/oauth/authorize?...''

3. intenta capturar callback en ''http://127.0.0.1:1455/auth/callback''

4. si el callback no puede vincularse (o estás remoto/sin interfaz), pega la URL de redirección/código

5. intercambia en ''https://auth.openai.com/oauth/token''

6. extrae ''accountId'' del access token y almacena ''{ access, refresh, expires, accountId }''

La ruta del asistente es ''openclaw onboard'' → elección de auth ''openai-codex''.

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 refresh es automático; generalmente no necesitas gestionar tokens manualmente.

Dos patrones:

Si quieres que "personal" y "trabajo" nunca interactúen, usa agentes aislados (sesiones separadas + credenciales + espacio de trabajo):

openclaw agents add work
openclaw agents add personal

Luego configura auth por agente (asistente) y enruta chats al agente correcto.

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

Elige qué perfil se usa:

- globalmente via ordenamiento de config (''auth.order'')

- por sesión via ''/model ...@<profileId>''

Ejemplo (anulación de sesión):

- ''/model Opus@anthropic:work''

Cómo ver qué IDs de perfil existen:

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

Docs relacionados:

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