Claude Code: suscripción o clave de API

¿Qué credencial usa tu sesión de Claude Code?

Un inicio de sesión de Claude Code funciona de una de estas dos formas. Puedes iniciar sesión con una cuenta de suscripción de Claude de claude.ai o autenticarte en una organización de Anthropic Console, que contabiliza cada token contra el saldo de API (interfaz de programación de aplicaciones) de esa organización. Ejecuta /status dentro de una sesión activa para ver cuál está activa: la pestaña Status muestra una fila Login method correspondiente a la cuenta con la que iniciaste sesión, y aparece una fila API key adicional cuando se utiliza una clave de API como credencial.

Determinar si la herramienta está incluida en tu plan es otra cuestión. La respuesta está en si Claude Code está incluido con una suscripción Claude Pro, mientras que el funcionamiento de las claves con la API de Claude se explica en cómo funciona la autenticación de la API de Claude. Esta sección cubre lo que esas dos no explican: qué credencial seleccionó realmente una sesión y cómo cambiarla.

El comportamiento siguiente procede de la documentación de autenticación de Claude Code de Anthropic, consultada el 31 August 2026. Claude Code publica versiones con frecuencia y varios de estos comportamientos requieren una versión mínima, así que ejecuta claude --version antes de concluir que tu equipo está averiado.

Dos cuentas que pueden compartir una dirección de correo electrónico

Una cuenta de claude.ai y una cuenta de Claude Console en platform.claude.com son cuentas diferentes. Pueden usar la misma dirección de correo electrónico y seguir siendo inicios de sesión independientes, con saldos separados y en organizaciones distintas. Crear una no crea la otra. Pagar un plan Max no añade crédito a una organización de Console, y recargar una organización de Console no añade nada a tu plan.

Los saldos difieren porque los modelos de facturación son distintos. Un inicio de sesión mediante suscripción consume la asignación de uso del plan, que se restablece en una ventana móvil de cinco horas y en una ventana semanal. Esa asignación se comparte con Claude en la web. Una credencial de Console se factura por token a la organización, y las cifras oficiales se encuentran en la página de uso de Console. El coste de esa diferencia durante el trabajo real se explica en pagar por token frente a pagar una suscripción.

Un tipo de cuenta no puede usar en absoluto la vía de suscripción. Anthropic indica que se puede iniciar sesión con una suscripción Pro o Max, una plaza de Claude para Teams o Enterprise, una cuenta de Claude Console o un proveedor de nube. Una cuenta gratuita de claude.ai no aparece en esa lista. Por tanto, un usuario del plan gratuito no tiene una credencial de suscripción con la que iniciar sesión, y qué incluye y qué no incluye el nivel gratuito de Claude no se extiende a la herramienta de línea de comandos. La vía restante es una organización de Console con crédito de API, que es una cuenta de otro tipo y de pago.

Ruta uno: iniciar sesión con la suscripción de Claude

Ejecute claude en un directorio de proyecto. En el primer inicio, se abre una ventana del navegador para iniciar sesión con la cuenta de claude.ai que tiene su plan.

claude

En un servidor, hay dos comportamientos diferentes. Si el navegador no se abre, pulse c para copiar la URL de inicio de sesión al portapapeles y péguela en un navegador de su propio equipo. Si ese navegador muestra un código de inicio de sesión en lugar de devolverle al terminal, pegue el código en el indicador que lo solicita. Este segundo caso es normal mediante SSH (secure shell), en WSL2 y dentro de contenedores, porque el navegador no puede acceder al servidor de devolución de llamada local que Claude Code inició en el equipo remoto.

Cuando termine el inicio de sesión, compruébelo en lugar de darlo por hecho. Inicie una sesión y ejecute /status. La pestaña Status indica el método de inicio de sesión, además de la organización y la dirección de correo electrónico guardadas. /login repite el flujo con otra cuenta y /logout elimina la credencial almacenada. Cerrar sesión también restablece el estado de configuración inicial, por lo que el siguiente claude vuelve a guiarle por la configuración inicial.

Es importante saber dónde se guarda esa credencial al reconstruir un equipo o entregárselo a otra persona:

• Linux: ~/.claude/.credentials.json, con permisos 0600.
• macOS: el Keychain cifrado. Cuando Keychain rechaza la escritura, algo que ocurre si está bloqueado en una sesión SSH, Claude Code usa como alternativa el mismo archivo 0600.
• Windows: %USERPROFILE%\.claude\.credentials.json, restringido al usuario mediante los controles de acceso propios del directorio del perfil.
• En cualquier plataforma con CLAUDE_CONFIG_DIR definido: el archivo se mueve dentro de ese directorio y la entrada de macOS Keychain queda asociada a él, por lo que una sesión iniciada con un CLAUDE_CONFIG_DIR diferente lee una credencial distinta.

Claude Code administra ese archivo mediante /login y /logout. Editarlo manualmente no es un método compatible para cambiar de cuenta.

Ruta dos: autenticarse contra una organización de Console

El acceso a Console comienza con un administrador. Este le invita desde Console mediante Settings, después Members y, por último, Invite. También le asigna un rol: el rol Claude Code sólo puede crear claves de API de Claude Code, mientras que el rol Developer puede crear cualquier clave. Después, seleccione la cuenta de Anthropic Console en el mensaje /login.

Desde Claude Code v2.1.242 hay dos rutas de Console, y cada una almacena elementos distintos. Al iniciar sesión con su cuenta de Console, se conserva el token OAuth (autorización abierta) de ese inicio de sesión en el navegador y se almacena como un perfil de Anthropic, sin crear ninguna clave de API. Claude Code actualiza ese inicio de sesión automáticamente. Si la actualización falla, las solicitudes fallan hasta que vuelva a iniciar sesión. Al crear una clave de API, que el mensaje identifica como heredada, se genera una clave de Console y se almacena con las demás credenciales. Una clave estática nunca se actualiza, por lo que sigue funcionando hasta que alguien la revoca. Esto resulta útil en un servidor de compilación, pero supone un riesgo en un portátil.

Anule ANTHROPIC_API_KEY antes de iniciar un acceso a Console sin clave. Si esa variable está definida, Claude Code omite por completo el mensaje de inicio de sesión y le pide que apruebe la clave encontrada.

No siempre podrá elegir. Claude Code crea una clave sin preguntar cuando la sesión se ejecuta con un proveedor cloud, cuando algún archivo de configuración define forceLoginOrgUUID o fija forceLoginMethod en "claudeai" o "console", o cuando existe una fuente de configuración administrada en el equipo y Claude Code no puede leerla. Esas decisiones corresponden al administrador. Si la opción sin clave nunca aparece, consulte a la persona responsable de administrar los equipos. /status también muestra una línea Setting sources con el nombre de cada archivo de configuración que cargó la sesión, e identifica la fuente administrada cuando se aplica a su caso.

La primera vez que autentique Claude Code contra una organización de Console, Console crea un espacio de trabajo llamado "Claude Code". Ese espacio de trabajo permite realizar el seguimiento del gasto de Claude Code en un solo lugar, y no puede crear claves de API dentro de él.

Por qué ANTHROPIC_API_KEY tiene prioridad después de iniciar sesión

Claude Code nunca pregunta qué credencial prefiere usar. Comprueba las fuentes en un orden fijo y utiliza la primera que encuentra. Según la documentación de agosto de 2026, el orden es:

1. Credenciales del proveedor de nube, cuando CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX o CLAUDE_CODE_USE_FOUNDRY está definido.
2. ANTHROPIC_AUTH_TOKEN, enviado como cabecera Authorization: Bearer, para gateways que se autentican con tokens bearer.
3. ANTHROPIC_API_KEY, enviado como cabecera X-Api-Key.
4. La salida de un script apiKeyHelper indicado en un archivo de configuración.
5. CLAUDE_CODE_OAUTH_TOKEN, el token de larga duración de claude setup-token.
6. Credenciales del perfil y de la federación de Anthropic.
7. La credencial de suscripción escrita por /login.

El inicio de sesión de la suscripción tiene la prioridad más baja. Por tanto, cualquier ANTHROPIC_API_KEY exportado en el entorno del proceso tiene prioridad sobre la cuenta con la que inició sesión, y la sesión factura a una organización de Console aunque usted crea que está usando su plan. No hay ningún fallo. El orden funciona como está documentado, por eso no aparece ninguna advertencia.

Dos detalles hacen que esto pase fácilmente desapercibido. En una sesión interactiva, Claude Code pregunta una vez si debe usar la clave encontrada y recuerda la respuesta. Por eso, una elección hecha hace un mes puede seguir aplicándose hoy. En modo no interactivo con -p, no aparece ningún aviso y la clave se usa siempre que esté presente. -p es el modo en que se ejecuta un trabajo de cron o un paso de CI (integración continua), por lo que un trabajo desatendido es precisamente donde una credencial incorrecta puede pasar desapercibida durante más tiempo.

La sesión incluye una comprobación visual rápida. Mientras ANTHROPIC_API_KEY está definido, /config muestra un interruptor "Use custom API key". El interruptor sólo existe mientras la variable está definida, por lo que su ausencia indica que el entorno está limpio.

Encontrar la clave extraviada en un servidor

Una clave exportada puede permanecer en más lugares que un perfil de shell:

• ~/.bashrc, ~/.bash_profile, ~/.profile o ~/.zshrc, que lee cada nuevo shell de inicio de sesión.
• Una unidad de systemd, mediante Environment= o EnvironmentFile=, para cualquier proceso que ejecute como servicio.
• El servidor de tmux, que conserva una copia del entorno con el que se inició. Un panel que abra hoy puede heredar una variable que eliminó de su perfil la semana pasada, porque el servidor lleva ejecutándose desde antes de esa modificación.
• Una imagen de contenedor o la definición de un trabajo de CI, donde la variable se establece fuera de cualquier archivo que pueda leer desde el shell.
• El bloque env de un archivo de configuración de Claude Code, que es una clave de configuración normal y sigue la precedencia habitual de la configuración.

Compruébelos antes de hacer cualquier otra cosa:

[ -n "$ANTHROPIC_API_KEY" ] && echo "ANTHROPIC_API_KEY is set" || echo "not set"
env | grep -E '^(ANTHROPIC_|CLAUDE_CODE_)' | cut -d= -f1
grep -n 'ANTHROPIC_API_KEY' ~/.bashrc ~/.bash_profile ~/.profile ~/.zshrc 2>/dev/null
tmux show-environment 2>/dev/null | grep ANTHROPIC
grep -n 'ANTHROPIC_API_KEY\|apiKeyHelper' ~/.claude/settings.json .claude/settings.json .claude/settings.local.json 2>/dev/null

El segundo comando pasa deliberadamente por cut, para mostrar los nombres de las variables sin imprimir sus valores secretos en una pantalla que quizá comparta o grabe. El primer comando responde a la pregunta: si indica que la variable está definida, el siguiente claude que inicie desde este shell usará esa clave. Si los cinco comandos no muestran nada, no existe ninguna credencial en el entorno, por lo que una sesión iniciada aquí recurrirá a su credencial de /login.

Añada systemctl cat your-unit.service | grep -i environment a cualquier servicio que ejecute Claude Code, porque un archivo de unidad establece su propio entorno y nunca lee el perfil de su shell.

Cambiar una sesión de una credencial a otra

Para volver a su suscripción:

unset ANTHROPIC_API_KEY
[ -n "$ANTHROPIC_API_KEY" ] && echo "still set" || echo "clear"
claude

Espere a que aparezca clear. Después, ejecute /status en la nueva sesión y confirme que la fila API key ya no aparece. Quitar la variable del shell no afecta a un proceso de Claude Code que ya esté en ejecución, porque cada proceso conserva el entorno con el que se inició. Reinicie la sesión.

Después, elimine el export del archivo que lo estableció. De lo contrario, el siguiente shell de inicio de sesión volverá a establecerlo. Dentro de tmux, tmux set-environment -u ANTHROPIC_API_KEY lo elimina para los paneles que se abran después en esa sesión. Los paneles que ya están abiertos conservan su propia copia.

Para hacer el cambio en el otro sentido, establezca ANTHROPIC_API_KEY en el entorno o ejecute /login y seleccione la cuenta de Console. Para eliminar por completo un inicio de sesión almacenado, ejecute /logout. Después de un inicio de sesión sin clave en Console, /logout elimina y revoca la credencial que creó ese inicio de sesión.

Si /status aún no coincide con lo esperado, ejecute claude doctor. Este comando muestra las entradas de configuración que Claude Code rechazó. Así puede detectar un archivo de configuración que no se pudo analizar y, por tanto, nunca se aplicó.

Autenticación cuando no hay navegador

claude setup-token abre el mismo flujo de autorización del navegador que /login e imprime un token OAuth válido durante un año en la terminal.

claude setup-token

No guarda el token en ningún sitio, así que cópielo cuando aparezca. Configúrelo como CLAUDE_CODE_OAUTH_TOKEN en la máquina que lo necesite. El token se autentica con su suscripción, por lo que necesita un plan Pro, Max, Team o Enterprise y sólo puede realizar solicitudes al modelo. El modo bare no lo lee, por lo que un script que pase --bare necesita ANTHROPIC_API_KEY o un apiKeyHelper en su lugar.

La precedencia también es importante en este caso. Si CLAUDE_CODE_OAUTH_TOKEN está definido en un perfil del shell, al ejecutar /login se cambia la sesión actual al nuevo inicio de sesión y todas las sesiones nuevas vuelven a leer la variable hasta que la elimine.

Si su organización ejecuta inferencias mediante Amazon Bedrock, Google Cloud o Microsoft Foundry, esas credenciales tienen la máxima prioridad y no se realiza ningún inicio de sesión mediante el navegador. La configuración correspondiente es una tarea independiente, que se explica en ejecutar Claude Code con Bedrock o Vertex.

Una sesión de larga duración en un VPS (servidor privado virtual) es donde estos problemas se concentran, porque el shell que la inició puede haberse configurado hace meses y no haberse reiniciado desde entonces. ejecutar Claude Code en un VPS dentro de tmux explica la parte de la sesión de esa configuración.

Comprobar qué ha consumido realmente cada credencial

En un inicio de sesión de suscripción, /usage muestra las barras de uso de tu plan y un desglose de lo que las ha consumido. La cifra en dólares de su bloque Session se calcula localmente a partir del recuento de tokens y el precio de lista, por lo que debes tratarla como una estimación orientada a usuarios de la API, no como una factura. Los suscriptores deben consultar las barras, no las cifras en dólares.

En una credencial de Console, las cifras relevantes están en Console: la página de uso muestra el gasto y el panel de Claude Code muestra las cifras por miembro. Nada de lo que aparezca en el terminal es una fuente autorizada para esa facturación.

Si las barras del plan no avanzan mientras trabajas, una credencial del entorno está imponiéndose en el orden de precedencia. Ese síntoma aislado es el indicador más fiable de que se está usando la credencial incorrecta, y seguir el consumo de una sesión de Claude Code explica con más detalle cómo medirlo. Si las barras avanzan y después se detienen, has alcanzado un límite del plan; cómo funcionan los límites de uso de Claude y las ventanas de restablecimiento lo explica.

Modos de fallo y qué revisar

Todo funciona, pero el uso del plan nunca cambia. Hay una credencial de entorno activa. /status muestra una fila de tipo API key, y la comprobación del shell anterior muestra la variable.

Las solicitudes fallan aunque la suscripción esté activa. Una clave perteneciente a una organización de Console deshabilitada o caducada tiene prioridad sobre el inicio de sesión. Ejecute unset ANTHROPIC_API_KEY, inicie una sesión nueva y vuelva a comprobar /status.

Aparece una advertencia al iniciar porque el inicio de sesión está a punto de caducar. Las versiones recientes avisan cuando una credencial /login caduca en un plazo de tres días. /status muestra entonces la fila del inicio de sesión en estado caducado, junto con la organización y el correo electrónico que guardó. Ejecute /login para renovarla. La advertencia nunca bloquea una solicitud. Por eso es fácil ignorarla hasta que una sesión desatendida deja de avanzar.

Un apiKeyHelper es lento o falla. Claude Code vuelve a ejecutar el ayudante cada cinco minutos de forma predeterminada. Puede ajustar este intervalo con CLAUDE_CODE_API_KEY_HELPER_TTL_MS. También muestra un aviso en la barra de indicaciones cuando una ejecución tarda más de diez segundos. Si el ayudante no devuelve ninguna clave, ya sea porque se produjo un error o porque agotó el tiempo de espera, las solicitudes fallan después de tres intentos.

La credencial correcta, pero la organización incorrecta. Una dirección de correo electrónico puede pertenecer a dos organizaciones. /status indica la organización en la que se autenticó. Lea esa línea en lugar de suponer en cuál inició sesión.

FAQ

¿Cómo puedo saber qué cuenta está usando Claude Code ahora mismo?

Ejecute /status en la sesión. La pestaña Status muestra una fila Login method para la cuenta con la que inició sesión y añade una fila API key cuando una clave de API proporciona la credencial. Una fila Profile sustituye a la fila de inicio de sesión cuando se selecciona un perfil de Anthropic o una credencial de federación. Fuera de la sesión, comprobar si ANTHROPIC_API_KEY está definida en el shell permite saber si existe una credencial de entorno que tendría prioridad sobre el inicio de sesión.

¿Por qué se ignora mi suscripción Claude Pro o Max?

Porque una credencial de entorno tiene prioridad sobre ella. Claude Code usa la primera credencial que encuentra en un orden fijo, y la credencial de suscripción /login es la última, por debajo de las variables del proveedor cloud, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper y CLAUDE_CODE_OAUTH_TOKEN. Ejecute unset ANTHROPIC_API_KEY, inicie una sesión nueva y confirme el resultado con /status. Después, elimine la exportación del perfil del shell, de la unidad de systemd, del entorno de tmux o de la definición del contenedor que la estableció. De lo contrario, volverá a aparecer en el siguiente shell de inicio de sesión.

¿Puedo usar Claude Code con una cuenta gratuita de Claude?

No. Los tipos de cuenta que Anthropic permite para iniciar sesión son una suscripción Pro o Max, una cuenta de Claude for Teams o Enterprise, una cuenta de Claude Console y un proveedor cloud. Una cuenta gratuita de claude.ai no está incluida, por lo que no existe una credencial de suscripción que se pueda almacenar. La alternativa de pago a una suscripción es una organización de Claude Console con crédito de API, facturada por token. Es una cuenta independiente, aunque use la misma dirección de correo electrónico.

¿Mi cuenta de claude.ai y mi cuenta de Console comparten un saldo?

No. Son cuentas independientes, con facturación separada, aunque ambas usen la misma dirección de correo electrónico. El uso de la suscripción consume la asignación del plan, que se comparte con Claude en la web y se restablece en una ventana móvil de cinco horas y en una ventana semanal. El uso de Console se factura por token a la organización y aparece en la página de uso de Console. Añadir crédito a una cuenta no afecta a la otra.

¿Cómo autentico Claude Code en un servidor sin interfaz gráfica?

Hay dos opciones. Ejecute claude mediante SSH y complete el inicio de sesión en el navegador de su propio equipo: pulse c para copiar la URL, inicie sesión allí y pegue después el código en la terminal si el navegador muestra uno en lugar de redirigir automáticamente. O ejecute claude setup-token en un equipo que tenga navegador, copie el token con validez de un año que muestra y establézcalo como CLAUDE_CODE_OAUTH_TOKEN en el servidor. Ese token necesita un plan Pro, Max, Team o Enterprise y sólo puede realizar solicitudes a modelos. Por tanto, un script que use --bare necesita una clave de API o un apiKeyHelper en su lugar.