Claude Code: usar una clave API sin suscripción

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

Un inicio de sesión de Claude Code funciona de una de dos formas. Puede iniciar sesión con una cuenta de suscripción de Claude de claude.ai, o autenticarse en una organización de Anthropic Console, que factura el uso de tokens a la cuenta de API (interfaz de programación de aplicaciones) de esa organización en lugar de aplicarlo a su plan. Ejecute /status dentro de una sesión activa para ver cuál está activa: la pestaña Status muestra una fila Login method para la cuenta con la que inició sesión, y aparece una fila API key adicional cuando una clave de API proporciona la credencial.

La cuestión de si la herramienta está incluida en su plan es independiente. La respuesta se encuentra en si Claude Code está incluido en una suscripción Claude Pro, mientras que los mecanismos de las claves para la API de Claude se explican en cómo funciona la autenticación de la API de Claude. Lo que sigue cubre lo que esos dos temas no explican: qué credencial seleccionó realmente una sesión y cómo cambiarla.

El comportamiento descrito a continuación procede de la documentación de autenticación de Claude Code de Anthropic, consultada el 10 de octubre de 2026. Claude Code publica versiones con frecuencia y varios de estos comportamientos requieren una versión mínima, por lo que debe ejecutar claude --version antes de concluir que su equipo tiene un problema.

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. Añadir fondos a una organización de Console no añade nada a tu plan.

La relación inversa tiene una excepción, comprobada el 10 de octubre de 2026. Los planes Max 5x y Max 20x ahora incluyen créditos mensuales de API, de $100 y $200 al mes, respectivamente, y los planes Team reciben una cantidad común. Esos créditos sólo llegan a una organización de Console después de vincularla desde la configuración de facturación de claude.ai, y no cubren Claude Code. La documentación de plataforma de Anthropic indica que Claude Code no está cubierto, y su centro de ayuda sólo exceptúa las ejecuciones de claude -p que utilizan una clave de API de la organización vinculada, por lo que una sesión interactiva facturada a una organización que sólo contiene esos créditos falla con Credit balance too low.

Los saldos difieren porque los modelos de facturación son distintos. Un inicio de sesión con suscripción consume la cuota de uso del plan, que se restablece en una ventana móvil de cinco horas y en una ventana semanal, y esa cuota se comparte con Claude en la web. Una credencial de Console se factura por token a la organización, y las cifras autorizadas 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 la vía de suscripción. Anthropic indica que las cuentas con las que puedes iniciar sesión son una suscripción Pro o Max, un puesto de Claude for Teams o Enterprise, una cuenta de Claude Console, un proveedor de nube y una pasarela Cloud, es decir, una pasarela de aplicaciones de Claude alojada por tu organización que se ejecuta en su propia infraestructura y en la que inicias sesión mediante SSO corporativo (inicio de sesión único) a través de /login. Una cuenta gratuita de claude.ai no aparece en esa lista, por lo que 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 pago con una estructura diferente.

Ruta 1: iniciar sesión con su 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, dos aspectos funcionan de forma diferente. 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 la solicitud que lo pide. Este segundo caso es normal mediante SSH (secure shell), en WSL2 y dentro de contenedores, porque el navegador no puede acceder al servidor de callback 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 que se guardaron. /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 el modo de archivo 0600.
• macOS: el Keychain cifrado. Si Keychain rechaza la escritura, lo que ocurre cuando está bloqueado en una sesión SSH, Claude Code usa como alternativa el mismo archivo 0600. Un inicio de sesión en Console que crea una clave de API no usa esa alternativa y falla hasta que Keychain permite escribir.
• 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 otra credencial.

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

Ruta dos: autenticarse en una organización de Console

El acceso a Console comienza con un administrador. El administrador 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, debe elegir la cuenta de Anthropic Console en el indicador /login.

Desde Claude Code v2.1.242 hay dos rutas de Console y cada una almacena elementos diferentes. Al iniciar sesión con la cuenta de Console, Claude Code conserva el token OAuth (autorización abierta) de ese inicio de sesión en el navegador y lo 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. Este inicio de sesión sin clave también cierra cualquier sesión de claude.ai almacenada en el equipo. Al crear una clave de API, que el indicador identifica como legacy, 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 indicador de inicio de sesión y le pide que apruebe la clave que ha encontrado.

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. Son decisiones del administrador. Si la opción sin clave nunca aparece, consulte a la persona responsable de administrar la flota. /status también muestra una línea Setting sources que indica todos los archivos de configuración cargados por la sesión. Además, indica la fuente administrada cuando se aplica a su caso.

La primera vez que autentique Claude Code en una organización de Console, Console crea un espacio de trabajo llamado "Claude Code" para esa organización. Ese espacio de trabajo permite realizar un seguimiento centralizado del gasto de Claude Code. No puede crear claves de API dentro de él.

Por qué ANTHROPIC_API_KEY gana después de iniciar sesión

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

1. Credenciales de proveedor de nube, cuando CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX o CLAUDE_CODE_USE_FOUNDRY están definidas.
2. ANTHROPIC_AUTH_TOKEN, enviada como cabecera Authorization: Bearer, para pasarelas que se autentican con tokens de tipo bearer.
3. ANTHROPIC_API_KEY, enviada como cabecera X-Api-Key.
4. La salida de un script apiKeyHelper nombrado en un archivo de configuración.
5. CLAUDE_CODE_OAUTH_TOKEN, el token de larga duración de claude setup-token.
6. Credenciales de perfil y federación de Anthropic, las credenciales que utilizan la CLI ant y Workload Identity Federation.
7. La credencial de suscripción escrita por /login.

Existen dos excepciones en torno a esta lista. Un perfil ocupa la posición 6 cuando se especifica en ANTHROPIC_PROFILE, cuando las variables de federación están definidas o cuando el perfil activo es un perfil de Workload Identity Federation. Un perfil activo en modo user_oauth, el tipo que escribe ant auth login o un inicio de sesión sin clave en la consola, se sitúa por debajo de una credencial /login funcional. Y una sesión de pasarela de aplicaciones de Claude iniciada mediante sesión queda fuera de la lista por completo: tiene prioridad sobre todo lo demás, incluidas las variables de proveedor de nube. Cuando la configuración gestionada por un administrador requiere el inicio de sesión en la pasarela, Claude Code omite las otras fuentes y le solicita que inicie sesión a través de /login.

Ninguna de las dos excepciones rescata su suscripción de una clave exportada. Sin una pasarela, todo lo que va de la posición 1 a la 5 tiene prioridad sobre la cuenta con la que inició sesión, por lo que una ANTHROPIC_API_KEY exportada en cualquier parte del entorno de proceso gana, y la sesión factura a una organización de la consola mientras usted cree que está utilizando su plan. Nada está roto. El orden hace lo que documenta, razón por la cual no hay advertencias.

Dos detalles hacen que esto sea fácil de pasar por alto. En una sesión interactiva, Claude Code pregunta una vez si desea utilizar la clave que encontró y recuerda su respuesta, por lo que una elección que hizo hace un mes sigue aplicándose hoy. En modo no interactivo con -p, no hay ninguna solicitud y la clave se utiliza siempre que está presente. -p es el modo en el que se ejecuta un trabajo cron o un paso de CI (integración continua), por lo que un trabajo desatendido es precisamente donde la credencial incorrecta pasa desapercibida durante más tiempo.

Existe una comprobación visual rápida dentro de la sesión. Mientras ANTHROPIC_API_KEY esté definida, /config muestra un interruptor de "Use custom API key". El interruptor solo existe mientras la variable está definida, por lo que su ausencia significa que el entorno está limpio.

Cómo encontrar la clave perdida en un servidor

Una clave exportada permanece 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 se ejecuta desde antes de esa modificación.
• Una imagen de contenedor o una definición de 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 de configuración habitual.

Compruébelos antes de realizar cualquier otra acción:

[ -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 los valores secretos en una pantalla que quizá esté compartiendo o grabando. El primer comando determina la respuesta: si indica que la variable está establecida, el siguiente claude que inicie desde este shell utilizará esa clave. Si los cinco comandos no muestran nada, no existe ninguna credencial de entorno y una sesión iniciada aquí recurrirá a su credencial /login.

Añada systemctl cat your-unit.service | grep -i environment a cualquier servicio que ejecute Claude Code, ya que un archivo de unidad establece su propio entorno y nunca lee el perfil del 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 clear. Después, ejecute /status en la nueva sesión y confirme que la fila API key haya desaparecido. Quitar la variable del shell no afecta a un proceso de Claude Code que ya esté en ejecución, porque el proceso conserva el entorno con el que se inició. Reinicie la sesión.

Después, elimine la exportación del archivo que la estableció. De lo contrario, el siguiente shell de inicio de sesión volverá a establecerla. Dentro de tmux, tmux set-environment -u ANTHROPIC_API_KEY la elimina para los paneles abiertos después de ese momento en la sesión. Los paneles que ya estaban abiertos conservan su propia copia.

Para cambiar en la otra dirección, 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 de Console sin clave, /logout elimina y revoca la credencial que escribió ese inicio de sesión.

Si /status sigue sin coincidir 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 necesita. 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 a modelos. El modo bare no lo lee, de modo que un script que pase --bare necesita ANTHROPIC_API_KEY o un apiKeyHelper.

La precedencia también se aplica aquí. Si CLAUDE_CODE_OAUTH_TOKEN está definido en un perfil de shell, al ejecutar /login se cambia la sesión actual al nuevo inicio de sesión, y cada sesión nueva vuelve a leer la variable hasta que la elimine.

Si su organización ejecuta inferencia mediante Amazon Bedrock, Google Cloud o Microsoft Foundry, esas credenciales ocupan el primer lugar en el orden de precedencia y no se produce ningún inicio de sesión mediante navegador. La configuración correspondiente es una tarea independiente, descrita 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é consumió realmente cada credencial

En un inicio de sesión con suscripción, /usage muestra las barras de uso de tu plan y un desglose de lo que las consumió. La cifra en dólares de su bloque Session se calcula localmente a partir del recuento de tokens y del precio de lista, o de las tarifas contratadas por tu organización cuando un administrador ha configurado una tabla modelPricing en los ajustes administrados. En ese caso, la línea Total cost lo indica. En cualquier caso, considérala una estimación dirigida a usuarios de la API, no una factura. Los suscriptores deben fijarse en las barras, no en las cifras en dólares.

En una credencial de Console, las cifras importantes 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 se imprime en tu terminal es una fuente autorizada para esa facturación.

Si las barras del plan nunca avanzan mientras trabajas, probablemente una credencial del entorno está ganando prioridad, y /status lo resuelve. La excepción se produce cuando las barras ya están completas: una sesión con suscripción puede continuar después de alcanzar el límite incluido usando créditos de uso, que Anthropic factura con las tarifas estándar de la API, y las barras permanecen sin cambios mientras lo hace. Fuera de ese caso, unas barras inmóviles son la señal más clara de que se está usando la credencial incorrecta, y comprobar cuánto consume una sesión de Claude Code explica cómo medirlo con más detalle. Si las barras avanzan y después se detienen, en cambio, has alcanzado el 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 de tu plan nunca cambia. Normalmente hay una credencial de entorno activa: /status muestra una fila de API key, y la comprobación del shell anterior muestra la variable. Si no aparece ninguna de las dos y las barras se mantienen en el límite, la sesión ha pasado a usar créditos de uso, facturados con las tarifas estándar de la API. Ese gasto aparece en Settings y después en Usage, en claude.ai.

Las solicitudes fallan aunque la suscripción esté activa. Una clave perteneciente a una organización de Console deshabilitada o caducada tiene prioridad sobre tu inicio de sesión. Ejecuta unset ANTHROPIC_API_KEY, inicia una sesión nueva y vuelve a comprobar /status. Si el error indica que la clave de API no es válida, solucionar el error de clave de API no válida de Claude Code explica ese caso en detalle, incluido el motivo por el que ejecutar /login de nuevo no lo corrige.

Aparece una advertencia al iniciar que indica que tu inicio de sesión está a punto de caducar. Las versiones recientes muestran una advertencia cuando una credencial de /login caduca en menos de tres días. Cuando ya ha caducado, /status muestra la fila de inicio de sesión como caducada, junto con la organización y el correo electrónico guardados. Ejecuta /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 asistente cada cinco minutos de forma predeterminada. Puedes 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 asistente no devuelve ninguna clave, ya sea porque produjo un error o porque agotó el tiempo de espera, las solicitudes fallan en un máximo 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 ha autenticado, así que lee esa línea en lugar de asumir en cuál has iniciado sesión.

FAQ

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

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 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. Claude Code usa la primera credencial que encuentra en un orden fijo, y la credencial de suscripción /login queda por debajo de las variables del proveedor cloud, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper, CLAUDE_CODE_OAUTH_TOKEN y cualquier perfil de Anthropic o credencial de federación que seleccione con ANTHROPIC_PROFILE o con las variables de federación. Sólo un perfil activo en modo user_oauth queda por debajo de ella, y una sesión iniciada en una pasarela de Claude apps supera toda la lista. Ejecute unset ANTHROPIC_API_KEY, inicie una sesión nueva y confirme con /status. Después elimine la exportación del perfil del shell, la unidad de systemd, el entorno de tmux o 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 ofrece para iniciar sesión son una suscripción Pro o Max, una licencia de Claude for Teams o Enterprise, una cuenta de Claude Console, un proveedor cloud y una pasarela Cloud. Esta última es una pasarela de Claude apps autohospedada, iniciada con SSO corporativo mediante /login. Una cuenta gratuita de claude.ai no es uno de ellos, por lo que no existe una credencial de suscripción que Claude Code pueda guardar. 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 el mismo 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 de tu 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. El único vínculo opcional va del plan a Console: un plan Max o Team puede enviar sus créditos de API mensuales a una organización de Console que vincules desde claude.ai. Esos créditos no cubren Claude Code.

¿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 el terminal si el navegador muestra uno en lugar de redirigir. También puede ejecutar claude setup-token en un equipo que tenga navegador, copiar el token de un año que muestra y establecerlo como CLAUDE_CODE_OAUTH_TOKEN en el servidor. Ese token requiere 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.