Claude Code setup-token: 2 capas de auth (2026)

claude setup-token y claude login parecen hacer lo mismo. No lo hacen. Son dos capas de autenticación distintas, y cuando apuntan a cuentas diferentes, la interfaz muestra una identidad mientras Claude Code en realidad usa otra. Me pasó la primera vez cuando tenía dos cuentas de Anthropic en la misma computadora, y la UI insistía en que estaba usando mi cuenta Max cuando el comando corría bajo una cuenta secundaria.

El problema se arregla en diez minutos cuando sabes dónde mirar. El objetivo de este artículo es ese: entender las dos capas, aprender a diagnosticar cuándo divergen, y evitar la trampa clásica de equipos que operan varias computadoras con varias cuentas.

Capa 1: credentials.json

La primera capa es ~/.claude/.credentials.json. Es lo que escribe claude login cuando te autenticas en el navegador. Contiene el access token y el refresh token OAuth. Cuando el access token expira, el refresh token obtiene uno nuevo de manera automática.

Esta es la capa que la mayoría de los usuarios conocen. Haces login una vez, el archivo queda escrito, y Claude Code lo lee en cada ejecución. El archivo está atado a una sola cuenta Anthropic. Si cambias de cuenta, cambias el contenido del archivo (herramientas como claude-shift hacen exactamente eso: sobrescribir el credentials.json para alternar cuentas).

Capa 2: CLAUDE_CODE_OAUTH_TOKEN

La segunda capa es una variable de entorno: CLAUDE_CODE_OAUTH_TOKEN. Cuando esta variable está presente en el shell donde lanzas claude, sobrescribe la capa 1 completamente.

La lógica del runtime es simple: si CLAUDE_CODE_OAUTH_TOKEN existe en el entorno, usa ese valor. Si no existe, cae a credentials.json. La variable de entorno siempre gana.

Esto significa que tu cuenta “logueada” (capa 1) y tu cuenta “corriendo” (capa 2) pueden ser dos identidades diferentes al mismo tiempo. Si no sabes que la variable existe, y algo la configura por ti (un script de arranque, un gestor de cuentas, una sesión anterior), vas a ver exactamente lo que yo vi: la UI resalta una cuenta mientras claude corre como otra.

Qué es setup-token en realidad

claude setup-token genera una credencial de larga duración para un caso de uso específico: ejecutar Claude Code de manera no interactiva, en máquinas donde el OAuth basado en navegador es incómodo o imposible. Entornos de CI. Máquinas remotas. Servidores sin interfaz gráfica.

El token que genera este comando se diferencia de los tokens OAuth de credentials.json en algo importante: no tiene refresh token.

Un flujo OAuth normal emite un access token de corta duración más un refresh token de larga duración. Cuando el access expira, el refresh obtiene uno nuevo de forma invisible. Un setup token se emite como una credencial única con una ventana de validez de un año. No hay refresh token. Cuando expira, generas uno nuevo. A cambio, es estable: la misma cadena del token funciona en varias máquinas, puede guardarse en gestores de secretos, y no requiere interacción con el navegador para renovarse.

Cuando asignas un setup token a CLAUDE_CODE_OAUTH_TOKEN, Claude Code lo usa como identidad en runtime. El setup token ocupa el lugar tanto del access token como del proceso de refresh.

Por qué existen dos capas

El diseño tiene sentido cuando piensas en los escenarios de despliegue que Claude Code necesita soportar.

Uso interactivo, una sola máquina: un desarrollador, una computadora, una cuenta. claude login una vez, credentials.json se encarga de todo, el refresh automático funciona. La capa 2 no interviene.

Uso interactivo, varias cuentas en una computadora: alternas credentials.json para cambiar de cuenta. La capa 2 se puede usar para “fijar” una cuenta destinada a automatización mientras la capa 1 maneja las sesiones interactivas. Las dos capas cumplen roles diferentes al mismo tiempo.

Uso no interactivo, remoto o CI: el login por navegador es imposible. claude setup-token genera una credencial estable. Configuras CLAUDE_CODE_OAUTH_TOKEN en el entorno. Claude Code corre sin ninguna ceremonia OAuth. La capa 1 no interviene.

Uso multi-máquina: una cuenta repartida en varias computadoras, cada una con cargas de trabajo diferentes. El setup token puede provisionarse a cada máquina a través de un gestor de secretos sin requerir logins individuales por navegador.

El diseño de dos capas no es redundancia. Es la forma de hacer que la misma herramienta funcione en una amplia variedad de contextos sin forzar a todos a soportar el flujo OAuth interactivo.

El problema de la divergencia

Cuando usas una herramienta que gestiona las dos capas de manera independiente, es posible que apunten a lugares distintos. La capa 1 puede apuntar a la cuenta A (porque hiciste claude login con la cuenta A la última vez). La capa 2 puede apuntar a la cuenta B (porque un setup token para la cuenta B está configurado en el entorno). Esto es lo que yo tenía sin saberlo.

Según qué cuenta quieras realmente que Claude use, una de las dos es la correcta y la otra es estado residual. El problema es que ni el CLI ni la UI te dan una señal clara de que las dos capas apuntan a lugares diferentes, a menos que tu herramienta chequee explícitamente los dos lugares.

El patrón que ahora uso: cuando reviso qué cuenta está “activa”, reviso las dos. Si coinciden, todo está limpio. Si divergen, decido con intención cuál debe ganar, y limpio la otra.

Un comando rápido de diagnóstico (en bash o zsh):

# Qué dice la capa 2
echo "ENV token (capa 2): ${CLAUDE_CODE_OAUTH_TOKEN:0:20}..."

# Qué dice la capa 1
head -c 200 ~/.claude/.credentials.json

# Qué cuenta ve Claude Code en runtime
claude /status

Si las dos primeras líneas no concuerdan con la tercera, tienes divergencia.

El escenario multi-computadora en equipo

Este es el caso donde las dos capas te muerden más fuerte, y donde LatAm (equipos distribuidos trabajando desde computadoras personales y de la oficina) tiende a toparse con ellas antes que un entorno centralizado.

Supón que tu equipo tiene tres personas, y cada una usa dos computadoras: una laptop de trabajo y una PC de escritorio en casa. Si usan claude login en cada una, cada computadora tiene su propio credentials.json apuntando a la misma cuenta, y entras en un conflicto de rotación de refresh tokens: cuando una máquina refresca su access token, el refresh token de la otra queda invalidado, y aproximadamente una vez al día una de las dos se encuentra deslogueada sin aviso.

La alternativa limpia: un setup token por persona, guardado en el gestor de secretos del equipo (1Password, Bitwarden, lo que sea), configurado como variable de entorno al abrir la terminal. Un token, varias computadoras, cero fricción al cambiar de máquina.

El error que vi tres veces: alguien hace claude login en una computadora nueva “por costumbre”, eso escribe un credentials.json que no coincide con el setup token en la variable de entorno, y las sesiones corren bajo una cuenta diferente a la que la UI muestra. El token en la variable de entorno siempre gana.

Reglas prácticas

Si usas Claude Code en una sola máquina con una sola cuenta, nada de esto importa. El flujo OAuth por defecto resuelve todo.

Si corres varias cuentas, o si usas setup-token para automatización, vale la pena interiorizar tres hechos:

1. CLAUDE_CODE_OAUTH_TOKEN siempre gana sobre credentials.json. Si la variable está configurada, esa es la cuenta corriendo.
2. claude login escribe en credentials.json pero no toca CLAUDE_CODE_OAUTH_TOKEN. Loguearte de forma interactiva no limpia un token fijado previamente.
3. Un setup token no rota de manera automática. Pon un recordatorio para regenerarlo antes del año.

Lo que me llevo

El diseño de dos capas no es complicado una vez que sabes que está ahí. La dificultad es que casi nada en la documentación oficial te dice que existe. Por eso cualquier equipo que escala Claude Code más allá de “un desarrollador en una computadora” termina chocando con este mismo problema. Ahora que lo sabes, te toma diez minutos diagnosticarlo en lugar de medio día.

---

ken imoto · WebRTC & Voice AI engineer · kenimoto.dev