Configuración de API: Inicio de sesión con suscripción o API key, cómo elegir y cómo cambiar
📚 Navegación de la serie: El artículo anterior 03 · Cómo funciona desglosó el ciclo de agente: cómo Claude Code "Piensa → Actúa → Observa". Este artículo resuelve el requisito previo para que funcione: con qué identidad se conecta al modelo. El próximo artículo tratará sobre la conexión a modelos de terceros / nacionales (chinos).
En junio de 2026, la documentación oficial de Claude Code enumeraba 6 formas de autenticación, desde el inicio de sesión con suscripción hasta las credenciales de proveedores en la nube, con prioridades superpuestas capa por capa.
Aquí hay un problema muy común en el que yo mismo he caído. En su momento, para ahorrar esfuerzo, exporté un ANTHROPIC_API_KEY en ~/.zshrc. Más tarde, compré una suscripción Max y me conecté correctamente con /login. Sin embargo, un día al revisar las facturas en la Console, descubrí que me seguían cobrando por la API, cuando pensaba que estaba usando la cuota de mi suscripción. Después de investigar mucho tiempo, entendí: siempre que haya una API key en el entorno, su prioridad anula a la suscripción.
Para decirlo sin rodeos, "haber iniciado sesión" no es igual a "usar la identidad correcta". Este artículo explicará esto a fondo.
Después de leer este artículo, obtendrás:
- Una tabla de comparación de escenarios aplicables entre el inicio de sesión con suscripción y la API key, para saber qué camino tomar.
- Tres enfoques prácticos de "dónde configurar y cómo cambiar" (inicio de sesión por línea de comandos / variables de entorno / settings.json), y las diferencias entre Mac / Windows / Linux.
- Un conjunto de comandos de autocomprobación: usa
/statuspara confirmar "qué identidad y qué modelo estoy usando realmente en este momento", para no volver a pagar cargos sin saber por qué.
01 Dos identidades: Inicio de sesión con suscripción vs API key
Primero la conclusión: Para uso personal, elige el inicio de sesión con suscripción; si necesitas integrarlo en scripts / CI / facturación por uso de equipo, entonces usa una API key.
Para que Claude Code se conecte a un modelo, fundamentalmente tiene que responder a una pregunta: "¿Con qué derecho me dejas usarlo?" Esto es la autenticación (authentication): debes demostrar quién eres y de quién es la cuota que estás usando. Las formas soportadas oficialmente son varias, pero para un principiante, basta con entender los dos caminos principales.
Analogía: Entrar al gimnasio. El inicio de sesión con suscripción es como comprar una tarjeta mensual: entras con reconocimiento facial, puedes entrenar todo lo que quieras durante un mes, no te cobran por entrada. La API key es como entradas compradas por uso: cada vez que entras te descuentan una entrada, pagas por lo que usas. La tarjeta mensual es para los que van todos los días, las entradas son para los que van de vez en cuando, o si traes a amigos (scripts, automatización).
La diferencia entre los dos caminos se resume en una tabla:
| Dimensión | Inicio de sesión con suscripción (Cuenta Claude.ai) | API key (Console / Variable de entorno) |
|---|---|---|
| Cómo conectar | Ejecutar claude en terminal, inicio de sesión en navegador | Configurar la variable de entorno ANTHROPIC_API_KEY |
| Cómo se factura | Suscripción mensual (Pro / Max / Team) | Por uso de tokens, descontado del saldo de la Console |
| Cuota | Tiene límite de uso, hay que esperar al reinicio al llegar al tope | Recargas lo que usas, sin límite fijo |
| Adecuado para | Desarrollo interactivo diario personal | Scripts / CI / facturación por uso de equipo |
| De dónde salen las credenciales | Autorización del navegador con /login | Crear la key en Claude Console |
| ¿Funciona sin navegador? | Por defecto requiere navegador (CI usa setup-token) | Sí, basta con la variable de entorno pura |
Vamos a desglosar más el lado de la suscripción, porque se utilizará al elegir modelos más adelante:
- Claude Pro / Max: Suscripciones personales, inicia sesión con la cuenta de Claude.ai. Pro es más ligero, Max tiene una cuota mayor y puede usar el modelo más potente.
- Claude for Teams / Enterprise: Planes de equipo, un administrador te invita, facturación unificada. Enterprise también puede configurar SSO y políticas administradas.
Para proyectos personales, usa siempre el inicio de sesión con suscripción Max; te ahorra preocupaciones y no tienes que vigilar el saldo. Solo cuando vayas a integrar tareas automatizadas en GitHub Actions es cuando debes configurar una API key aparte (las tácticas específicas para CI se tratarán en el artículo 44). Para el desarrollo diario, no toques la API key, es solo buscarte ansiedad por los cobros.
💡 Resumen en una frase: Suscripción = Tarjeta mensual (uso diario personal), API key = Entradas (scripts/equipo por uso). Ten claro qué tipo de persona eres antes de configurar.
02 Inicio de sesión con suscripción: El camino más libre de preocupaciones
Si eres un usuario individual y compraste Pro o Max, entonces la configuración es básicamente cero configuración: solo ejecútalo e inicia sesión.
La operación es solo un paso. Una vez instalado Claude Code (para la instalación mira el artículo 02), en la terminal escribe:
claudeEn el primer inicio, Claude Code automáticamente abrirá el navegador para que inicies sesión en tu cuenta de Claude.ai. Después de iniciar sesión, el navegador regresará a la terminal y listo.
Algunas situaciones reales que encontrarás, mencionadas de antemano:
- ¿El navegador no apareció automáticamente? En la interfaz de Claude Code, presiona
c, copiará el enlace de inicio de sesión al portapapeles y tú mismo lo pegas y lo abres en el navegador. - ¿Después de iniciar sesión, el navegador te dio un "código de inicio de sesión" y no regresó? Pega ese código de nuevo en la terminal donde dice
Paste code here if prompted. Esta situación es común en WSL2, sesiones SSH remotas o contenedores, porque el navegador no puede conectarse al puerto de devolución de llamada local. - ¿Quieres cambiar de cuenta / cerrar sesión? En Claude Code, ingresa
/logouty vuelve a iniciar sesión la próxima vez que lo arranques.
¿Dónde se guardaron las credenciales de inicio de sesión? Esto depende de la plataforma, y saberlo ayuda a solucionar problemas para no estar a ciegas:
| Plataforma | Ubicación de almacenamiento de credenciales |
|---|---|
| macOS | Llavero del sistema cifrado (Keychain) |
| Linux | ~/.claude/.credentials.json (Permisos 0600) |
| Windows | %USERPROFILE%\.claude\.credentials.json (Hereda permisos del directorio de usuario) |
Todos estos son gestionados automáticamente por Claude Code a través de /login / /logout, no tienes que tocarlos manualmente. Cuando yo mismo estaba solucionando problemas de inicio de sesión en Mac, busqué ~/.claude/.credentials.json siguiendo el enfoque de Linux, y no lo encontré de ninguna manera, hasta llegué a dudar de si había iniciado sesión con éxito; la razón era esta: macOS no lo guarda como un archivo en absoluto, sino que lo mete en el Keychain.
💡 Resumen en una frase: Para los usuarios con suscripción, "ejecutar
claude→ iniciar sesión en el navegador" es todo. Las credenciales las guarda Claude Code automáticamente, no vayas a hurgar manualmente.
03 API key: El camino para scripts y equipos
El alcance del camino de la API key es en realidad muy estrecho: Si no haces automatización y no pagas por uso en un equipo, básicamente no la usarás. Pero ya que estamos explicando "cómo cambiar", primero hay que saber qué aspecto tiene.
Primer paso, obtener la key. Ve a Claude Console y crea una clave API (Esta es la consola de desarrolladores oficial de Anthropic, factura por uso de tokens y es una cuenta separada de la suscripción de Claude.ai).
Segundo paso, configurarla como variable de entorno. Los comandos de la plataforma son diferentes, hablemos de ellos por separado:
macOS / Linux:
export ANTHROPIC_API_KEY=sk-ant-tu-claveWindows (PowerShell, escribe permanentemente en las variables de entorno del usuario):
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-tu-clave", [EnvironmentVariableTarget]::User)⚠️ La clave es dinero, no la dejes por ahí. No escribas la key en el código, no la subas a Git y no la pegues en ningún archivo que se vaya a compartir. Usar
exporttemporalmente en la terminal actual es lo más seguro, cuando la cierras desaparece. Para hacerla persistente, usa las variables de entorno del sistema, no la codifiques (hardcode) en tu proyecto.
Tercer paso, iniciar y confirmar. Una vez configurada, ejecuta claude. En modo interactivo, el sistema te pedirá que apruebes esta key una vez (elige entre aprobar / rechazar, la elección se recordará). Una vez aprobada, se usará para ejecutarse.
Aquí hay un comportamiento crítico que el equipo oficial aclara, que es la raíz del problema mencionado al principio:
Si tienes una suscripción activa a Claude, pero al mismo tiempo has configurado
ANTHROPIC_API_KEYen el entorno, entonces la API key tendrá prioridad una vez aprobada. Si esta key pertenece a una organización deshabilitada o caducada, también causará directamente que falle la autenticación.
En otras palabras, la API key "cubrirá" tu suscripción. Es por eso que existe el problema del cambio que discutiremos en la siguiente sección.
💡 Resumen en una frase: La API key implica tres pasos: obtener la key de la Console → configurar la variable de entorno → aprobar al iniciar; recuerda que una vez que existe, tiene prioridad sobre la suscripción, esta es la raíz de todos los problemas de "cambio" que veremos después.
04 Cómo cambiar: La prioridad es la verdad
Conclusión central: Lo que tú "creas que es la identidad que estás usando" no importa; la orden de prioridad de Claude Code es la que manda. Cambiar, en esencia, es tocar esta prioridad.
Analogía: El orden de conexión de una regleta. Tienes varios enchufes en la pared de tu casa (suscripción, API key, credenciales de la nube...). El aparato del que realmente saca electricidad no depende de cuál tengas en mente, sino de cuál esté realmente enchufado y cuál esté en una posición más adelantada. Para cambiar de fuente de alimentación, debes desenchufar el que está más adelante.
La prioridad de autenticación proporcionada por la documentación oficial, de mayor a menor (6 niveles, los más altos cubren a los más bajos):
| Prioridad | Origen de credenciales | Escenario típico |
|---|---|---|
| 1 (Más alta) | Proveedor de la nube (Bedrock / Vertex / Foundry) | Empresas usando proveedores en la nube |
| 2 | Variable de entorno ANTHROPIC_AUTH_TOKEN | A través de pasarelas / proxies de LLM |
| 3 | Variable de entorno ANTHROPIC_API_KEY | Conexión directa a la API de Anthropic |
| 4 | Salida del script apiKeyHelper | Credenciales dinámicas / rotativas |
| 5 | CLAUDE_CODE_OAUTH_TOKEN | Token a largo plazo usado en CI |
| 6 (Más baja) | Credenciales de suscripción de /login | La suscripción personal usa esto por defecto |
Esta imagen "levanta" la tabla anterior: las 6 capas de credenciales se apilan verticalmente de mayor a menor. Claude Code escanea desde la parte superior de la pila hacia abajo, omite todas las capas "vacías" y se detiene en la primera capa con "valor" para usarla: en el escenario de suscripción personal, las 5 capas superiores están vacías, por lo que acierta el inicio de sesión con suscripción en la capa inferior.
¿Lo has entendido? La suscripción está en la capa más baja. Así que, mientras cualquier capa superior tenga un valor, cubrirá tu suscripción. Esto explica el escenario del principio: claramente iniciaste sesión en Max, pero estás quemando dinero de la API, porque el ANTHROPIC_API_KEY de la 3ª capa está presionando a la suscripción de la 6ª capa.
¿Entonces cómo cambiar de nuevo a la suscripción? La solución que da el equipo oficial es muy directa: borrar la capa de mayor prioridad:
unset ANTHROPIC_API_KEYLuego ejecuta /status para confirmar. Si, en modo interactivo, temporalmente no quieres usar una key específica, también puedes desactivarla usando el interruptor "Usar clave API personalizada" dentro de /config.
Por el contrario, cambiar de suscripción a API key significa hacer un export de la key y aprobarla una vez (ver sección 03).
Hay algunos detalles en los que es fácil caer, anótalos también:
ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKENsolo tienen efecto en sesiones CLI de terminal. El cliente de escritorio Claude Desktop y las sesiones remotas solo reconocen el inicio de sesión de OAuth y no leen estas variables de entorno.- Claude Code on the Web (versión web) siempre usa tus credenciales de suscripción; las variables de entorno de la API key en la sandbox no pueden anularlas.
ANTHROPIC_AUTH_TOKEN(Capa 2) yANTHROPIC_API_KEY(Capa 3) son dos cosas diferentes: el primero se envía como un encabezadoAuthorization: Bearer, usado al pasar por pasarelas / proxies; el segundo se envía como un encabezadoX-Api-Key, usado al conectarse directamente a la API oficial. No los mezcles.
💡 Resumen en una frase: Cambiar = ajustar prioridades. La suscripción está en el fondo, cualquier capa superior con un valor la anulará; para volver a la suscripción, haz
unsetde la capa superior y vuelve a comprobar con/status.
05 Fundamentos de la selección del modelo: opus, sonnet o default
La identidad ya está configurada, hay otra cosa que decidir: qué modelo hacer que use para trabajar.
Analogía: Asignar tareas a personas. Opus es el ingeniero senior más fuerte del equipo: buena mente, razonamiento profundo, pero lento y caro; Sonnet es el caballo de batalla: programación diaria rápida y estable, buena relación calidad-precio; Haiku es el chico de los recados: responde al instante a tareas sencillas, es el que más ahorra. Dale los problemas difíciles a Opus, el día a día a Sonnet, las tareas menores a Haiku.
Claude Code usa alias de modelo para que no tengas que recordar cadenas largas de números de versión. Los comunes son estos:
| Alias | Uso |
|---|---|
default | Valor especial: borra las anulaciones manuales, vuelve al modelo recomendado para el nivel de tu cuenta |
opus | Último Opus, razonamiento complejo / decisiones de arquitectura |
sonnet | Último Sonnet, programación diaria |
haiku | Rápido y eficiente, maneja tareas simples |
best | Actualmente equivalente a opus, usa el modelo más potente disponible |
opusplan | Modo mixto: usa Opus para pensar en Modo Plan, y cambia a Sonnet para ejecutar |
opus[1m] / sonnet[1m] | Con ventana de contexto de 1 millón de tokens, para masticar grandes repositorios de código / sesiones largas |
Nota: El alias apunta a la "versión recomendada de tu nivel", la cual se actualizará con el tiempo. En cuanto a la versión específica que se resuelve, la documentación oficial es la que manda: por ejemplo, en la API de Anthropic, opus se resuelve actualmente a Opus 4.8, sonnet se resuelve a Sonnet 4.6, pero diferentes proveedores (Bedrock / Vertex, etc.) resuelven a versiones diferentes (según la documentación oficial, sujeta a cambios).
El nivel al que estás suscrito determina qué modelo se te da por defecto:
| Tipo de cuenta | default se resuelve a |
|---|---|
| Max / Team Premium / Enterprise pago por uso / API de Anthropic | Opus 4.8 |
| Pro / Team Standard / Asientos de suscripción Enterprise | Sonnet 4.6 |
Es decir, los usuarios Pro por defecto tienen Sonnet, y los usuarios Max por defecto pueden usar Opus: esta es una de las razones por las que se recomienda a los usuarios intensivos usar Max. Además, cuando se alcanza el umbral de uso de Opus, Claude Code podría volver automáticamente a Sonnet, esto es un comportamiento normal, no un error.
¿Cómo se configura el modelo? El equipo oficial da cuatro formas, según su prioridad:
# 1. Cambiar temporalmente durante la sesión (ejecutar /model sin parámetros abre un selector) — prioridad más alta
/model sonnet
# 2. Especificarlo al iniciar
claude --model opus
# 3. Variable de entorno (válida para esta sesión)
ANTHROPIC_MODEL=opus// 4. Escrito en settings.json, de forma permanente como predeterminado para nuevas sesiones — prioridad más baja
{
"model": "opus"
}Lo anterior está ordenado de mayor a menor prioridad: /model en la sesión > --model al iniciar > variable de entorno ANTHROPIC_MODEL > archivo de configuración settings. Un hábito práctico: fijar sonnet en tu settings.json para uso diario, y cuando te encuentres con un problema de arquitectura difícil, cambia temporalmente en el chat con /model opus, así ahorras cuota.
En cuanto a los detalles del nivel de esfuerzo (
/effort, que controla la profundidad del pensamiento) yopusplan, no los desglosaremos aquí: elegir el modelo correcto es suficiente para un principiante. Cuando necesites profundizar, consulta el documento oficial "Configuración del modelo".
💡 Resumen en una frase: Para lo difícil
opus, para el día a díasonnet, para las tareas menoreshaiku;defaultsigue el nivel de tu suscripción: Pro usa Sonnet por defecto, Max usa Opus por defecto.
06 Práctica: 3 minutos para confirmar "¿Qué estoy usando?"
Ver sin practicar es como no ver. Si ejecutas este conjunto de comandos una vez, comprenderás completamente tu identidad actual y el estado de tu modelo. Todo el proceso se realiza en la terminal y luego dentro de la interfaz de Claude Code, sin depender de ningún entorno complejo.
Primer paso: Entrar a Claude Code. Busca cualquier directorio y ejecuta:
claudeSegundo paso: Comprobar el estado actual. En el cuadro de entrada de Claude Code, escribe:
/statusMostrará la información de tu cuenta y el método de autenticación / modelo actualmente vigente. Es de esperar que veas algo como esto (los campos específicos dependen de la versión, limítate a lo que se muestra realmente):
Account: your@email.com (Max)
Auth: Claude subscription (OAuth)
Model: opus (Opus 4.8)Si aquí Auth muestra una API key, y pensabas que estabas usando tu suscripción... Felicidades, acabas de encontrarte con el problema mencionado al principio.
Tercer paso: Ver qué modelos se pueden usar / hacer un cambio. Escribe:
/modelAparecerá un selector de modelo listando opciones como opus / sonnet / haiku, elige subiendo o bajando y presiona Enter para confirmar. Si quieres cambiar directamente, simplemente:
/model sonnetCuarto paso (Opcional): Verificar la prioridad de "Suscripción vs API key". Este paso te permite ver con tus propios ojos la regla explicada en la sección 04. Primero, sal de Claude Code, y en la terminal:
# Mira si hay alguna API key en el entorno "sobreescribiendo" silenciosamente tu suscripción
echo $ANTHROPIC_API_KEY- Si sale una cadena
sk-ant-...: Significa que está pisando tu suscripción. Si quieres volver a usar tu suscripción, ejecutaunset ANTHROPIC_API_KEY, luego entra enclaudey vuelve a comprobar con/status; elAuthdebería volver a ser suscripción. - Si sale vacío: Ya estabas usando la suscripción (u otras credenciales de mayor prioridad), no hay problema.
En Windows (PowerShell), comprueba las variables de entorno con:
echo $env:ANTHROPIC_API_KEYCriterio de aceptación: Con /status, puedes decir de un vistazo "estoy usando mi suscripción o mi API key en este momento, y qué modelo estoy ejecutando", y además puedes, usando unset + comprobación, cambiar manualmente de vuelta a la suscripción. Si puedes hacer esto, has alcanzado el objetivo principal de este artículo.
07 Resumen
Este artículo aclaró una cosa clave: Qué identidad utiliza Claude Code para conectarse al modelo, y cómo elegir y cambiar esa identidad.
| Tu situación | Cómo configurarlo | Modelo por defecto |
|---|---|---|
| Pro / Max personal | Ejecutar claude → /login en el navegador | Pro→Sonnet, Max→Opus |
| Script / CI / Facturación de equipo por uso | Obtener key de la Console → Configurar ANTHROPIC_API_KEY | Depende de la configuración específica |
| Querer volver a la suscripción | unset ANTHROPIC_API_KEY + comprobar con /status | — |
Los tres puntos que más debes recordar:
- La suscripción está en el nivel de prioridad más bajo, cualquier API key / token en el entorno la anulará: si te cobran sin motivo, comprueba esto primero.
/statuses tu espejo mágico: si no tienes claro a quién estás usando, escríbelo.- Elige el modelo según el trabajo:
opuspara problemas difíciles,sonnetpara el uso diario,defaultsegún el nivel de tu suscripción.
Ahora deberías ser capaz de: iniciar sesión correctamente después de la instalación, comprender qué identidad y modelo estás usando, cambiar entre suscripción y API key sin problemas, y dejar de ser engañado por la situación de "haber iniciado sesión con suscripción, pero que te cobren tarifas de API".
Avance del próximo artículo
Hasta aquí, te estás conectando a los modelos oficiales de Claude. Pero el uso de Claude en China con la API oficial no es muy amigable. ¿Se puede hacer que Claude Code corra modelos de terceros como DeepSeek, Qwen (Tongyi Qianwen), GLM, etc.?
Sí. El secreto está en esa variable de entorno que ha aparecido varias veces en este artículo pero que aún no se ha explicado: ANTHROPIC_BASE_URL. Esta no cambia "qué modelo usar", solo cambia "a dónde enviar la solicitud". En el próximo artículo 05 · Conexión a modelos de terceros / nacionales, usaremos esto para conectar Claude Code a grandes modelos nacionales, ahorrando dinero sin necesidad de usar "magia de internet (VPN)".
Te dejo algo para pensar: ya que la API key anula la suscripción, si apuntamos ANTHROPIC_BASE_URL a una plataforma nacional (china) y además configuramos la clave correspondiente, ¿significa eso que le hemos "cambiado el núcleo" a Claude Code? Descúbrelo en el próximo artículo.
Una vez conectada esta "ruta principal" de modelos oficiales, en el próximo artículo entraremos en la "ruta secundaria" de modelos de terceros/nacionales.