Claude Code: API key o suscripción, cuál manda en la facturación

A 10 de octubre de 2026, la respuesta corta es esta: para trabajar con Claude Code en tu terminal con Claude Pro o Max no necesitas una API key, y la suscripción tampoco te da una. La factura de API aparece cuando en tu entorno hay una ANTHROPIC_API_KEY. En modo interactivo, Claude Code te pregunta una sola vez si quieres usarla y recuerda la respuesta; si aceptaste, todo lo que hagas a partir de ahí se cobra en Claude Console por token. En modo no interactivo (claude -p) no pregunta: si la clave existe, la usa siempre. /status te dice qué credencial está activa y marca la que no se está usando.

Tres datos actuales cambian la decisión. Desde el 7 de octubre de 2026, Max y Team incluyen créditos mensuales de API, pero no cubren Claude Code interactivo. claude setup-token permite usar tu plan en scripts sin crear ninguna API key. Y el cambio anunciado para el uso del Agent SDK con suscripción quedó en pausa el 15 de junio de 2026.

Mira primero la ruta activa

Claude Code puede tener varias credenciales a la vez en la misma máquina y solo usa una. La documentación de autenticación de Claude Code fija este orden: gana la primera que encuentra. Cada fila tiene un dueño de factura distinto.

Dos detalles de la misma documentación cambian el diagnóstico. Si tienes sesión iniciada y también una API key, /status marca la credencial que no está en uso, así que basta una mirada para saber cuál paga. Y las sesiones en la nube usan siempre tu suscripción: aunque pongas ANTHROPIC_API_KEY o ANTHROPIC_AUTH_TOKEN en el entorno de la nube, no sustituyen al plan. Claude Desktop tampoco lee esas variables; sí las leen la CLI y lo que se apoya en ella, como la extensión de VS Code, el Agent SDK y GitHub Actions.

Por qué aparece facturación API si ya pagas una suscripción

La causa más habitual no es que la clave «se cuele» sin avisar, sino que en algún momento aceptaste el aviso. Claude Code pregunta una vez si quieres usar la ANTHROPIC_API_KEY que encuentra en el entorno y guarda la respuesta. Si dijiste que sí hace semanas, hoy sigue cobrando en Console aunque hayas olvidado el aviso. Además, con esa clave aprobada Claude Code se salta la pantalla de inicio de sesión, así que no ves ninguna pista de que estás fuera del plan.

Otras rutas que llevan al mismo resultado:

• Scripts y CI con claude -p. En modo no interactivo no hay aviso: si la variable existe, se usa.
• La extensión de VS Code, el Agent SDK o GitHub Actions heredan las mismas variables que la CLI.
• Un apiKeyHelper o un ANTHROPIC_AUTH_TOKEN en la configuración del proyecto o del equipo, que van por delante de la suscripción.
• Iniciaste sesión con una cuenta de Console en lugar de la de claude.ai. Desde la versión 2.1.242 Claude Code permite entrar con Console sin crear una API key, y esa ruta factura por token.

La variable suele venir de .zshrc, .bashrc, un .env, un perfil de terminal, un devcontainer, un secreto de CI o un script de arranque del IDE. Si la clave pertenece a una organización desactivada o caducada, el síntoma puede ser un error de autenticación en vez de un cargo, según advierte la misma documentación.

Para comprobarlo sin mostrar el secreto, mira solo los nombres de las variables en el shell desde el que lanzas Claude Code y luego /status dentro de la sesión:

env | grep -E '^(ANTHROPIC_|CLAUDE_CODE_)' | cut -d= -f1
claude
/status

Si /status muestra tu suscripción, el problema son los límites del plan. Si muestra la API key, mira de dónde sale la variable y qué proyecto de Console la emitió. No cambies de plan ni compres créditos hasta resolver esa bifurcación.

Qué significan /status, /usage, /cost y Console

Cada pantalla responde a una pregunta distinta y ninguna sustituye a las demás.

/status responde quién paga: qué método de autenticación usa la sesión y cuál queda sin usar. Es la primera lectura.

/usage mezcla dos cosas. Según la guía de costes de Claude Code, el bloque Session muestra tokens y una cifra en dólares calculada en local a precio de lista; está pensado para quien usa API, y para Pro y Max esa cifra no tiene efecto en la factura. En la misma pantalla los suscriptores ven las barras de uso del plan, estadísticas de actividad y un desglose de qué consumió más (skills, subagentes, servidores MCP, contexto largo, fallos de caché). Si tienes activado el uso adicional, aparece una fila con lo gastado este mes frente a tu límite mensual. Todo se calcula con el historial de esa máquina; el uso desde otros dispositivos o desde claude.ai no entra.

/cost aparece en muchas guías antiguas. La guía de costes actual ya no lo menciona y sitúa el gasto de la sesión en el bloque Session de /usage. Sea cual sea el comando, una cifra en dólares dentro de Claude Code es una estimación, no la factura de tu suscripción.

/usage-credits abre Settings > Usage en claude.ai si tienes Pro o Max, donde activas o desactivas el uso adicional y ves saldo, gasto del mes y límite. No funciona si estás autenticado con API key.

La página Usage de Claude Console es el registro que vale para la ruta API. La primera vez que autenticas Claude Code con una cuenta de Console se crea un espacio de trabajo llamado «Claude Code», donde puedes poner un límite de gasto. Si un equipo pregunta qué proyecto pagó una ejecución, la respuesta sale de ahí.

El gráfico es anterior a la actualización del 10 de octubre de 2026 y muestra /stats; el texto refleja los comandos actuales.

¿Claude Pro o Max incluye una API key? No, pero Max trae créditos de API

No. Con los planes de suscripción no recibes ninguna API key: la suscripción mejora la experiencia en Claude y la API de Claude se factura aparte, con créditos de prepago en Console. Si buscas una «Claude Pro key», lo que existe es el inicio de sesión de tu cuenta Pro en Claude Code o, para scripts, el token de claude setup-token, que tampoco es una API key.

Lo nuevo desde el 7 de octubre de 2026 son los créditos mensuales de API para Max y Team:

En Team se suman en un fondo común con un tope de 500 $ al mes. Free, Pro y Enterprise no los reciben. Se reclaman a partir de los siete días vinculando una organización de Claude Console, se renuevan cada ciclo y no se acumulan. Cubren la Claude API, Managed Agents, el Agent SDK y el playground de Console. No cubren Claude Code interactivo ni el uso adicional del plan. Para que claude -p o el Agent SDK los consuman, tienen que ir con una API key de esa organización vinculada; con tu /login siguen gastando límites del plan.

Cuándo sí usar una API key

Una API key es la credencial correcta cuando el trabajo es un producto o un servicio, o cuando quieres que el gasto sea de un proyecto de Console. No es una mejora automática sobre la suscripción ni una forma de saltarse sus límites. Para trabajo propio, incluso automatizado, a menudo basta el plan.

La línea la marcan las condiciones legales de Claude Code: el inicio de sesión OAuth es para quien compró un plan Free, Pro, Max, Team o Enterprise y para el uso ordinario de Claude Code y de las aplicaciones de Anthropic. Quien desarrolla productos o servicios, también con el Agent SDK, debe usar una API key de Console o de un proveedor en la nube. Los límites anunciados de Pro y Max suponen un uso individual y ordinario de Claude Code y del Agent SDK.

Si tu problema es que el trabajo interactivo choca con los límites, la comparación de Claude Pro vs Max es más útil que cambiar a API. Para la diferencia de producto entre las dos vías, mira Claude API vs Claude Code: diferencias, cuál usar y cómo se paga.

Scripts y CI con tu plan: claude setup-token

claude setup-token genera un token OAuth válido durante un año. Según la documentación de autenticación, no lo guarda en ningún sitio: lo copias y lo pones en la variable CLAUDE_CODE_OAUTH_TOKEN del script o del sistema de CI. Funciona contra tu suscripción y requiere Pro, Max, Team o Enterprise. Solo sirve para peticiones al modelo, y el modo bare no lo lee.

La trampa está en el orden de la tabla anterior: CLAUDE_CODE_OAUTH_TOKEN va en quinto lugar, detrás de ANTHROPIC_API_KEY. Si en ese mismo entorno de CI también existe una API key, claude -p usará la API key y cobrará en Console aunque hayas configurado el token del plan. Deja solo una de las dos.

Si manejas varias cuentas, la documentación recomienda darle a cada una su propio directorio de configuración con CLAUDE_CONFIG_DIR. Las credenciales se guardan en el llavero de macOS, o en ~/.claude/.credentials.json en Linux y Windows. Las variables y archivos de configuración están en Configuración de Claude Code API: claves, settings.json, modelos y gateways.

Herramientas de terceros: qué dice Anthropic sobre usar tu plan

Aquí las fuentes no coinciden del todo, y conviene saberlo antes de conectar tu cuenta a una herramienta externa.

• El artículo de ayuda de Anthropic sobre el uso programático, actualizado el 7 de octubre de 2026, dice que puedes seguir usando el Agent SDK, claude -p y aplicaciones de terceros con los límites de tu suscripción, y que los cambios anunciados para el Agent SDK se pausaron el 15 de junio de 2026: «nothing has changed».
• Las condiciones legales prohíben que un desarrollador externo ofrezca el inicio de sesión de Claude.ai dentro de su aplicación o enrute peticiones de sus usuarios a través de credenciales de Free, Pro o Max.
• Varios medios contaron en abril de 2026 que los límites del plan dejaron de cubrir herramientas tipo OpenClaw, que pasaron a pago por uso, paquetes o API key; después se informó de una marcha atrás parcial. Un artículo de Qiita de julio de 2026 describe exclusiones para OpenClaw, OpenCode y Cline.

En la práctica: usar tu propia cuenta en una herramienta para tu trabajo encaja con la ayuda actual; una herramienta que ofrece «entra con Claude» a sus propios usuarios choca con las condiciones. Antes de conectar una, lee su documentación sobre qué credencial usa y mira en Settings > Usage si su consumo aparece contra tu plan o contra uso adicional. Los paquetes de uso adicional se aplican, según la ayuda de Anthropic, también a productos de terceros que usan tu cuenta de Claude. Si la herramienta es OpenClaw, la comparación OpenClaw vs Claude Code compara las dos herramientas.

Usage credits y precios

Los créditos de uso, que Anthropic también llama uso adicional (extra usage), permiten a Pro, Max 5x y Max 20x seguir trabajando cuando se agota lo incluido. Se cobran aparte a las tarifas estándar de la API y valen tanto para las conversaciones en Claude como para Claude Code en la terminal. Se activan en Settings > Usage con método de pago, límite de gasto mensual, alertas y recarga automática, según la ayuda de Anthropic sobre los créditos de uso. Los créditos mensuales de API de Max no se aplican aquí.

Si sabes que vas a pasarte del plan, los paquetes de uso con descuento abaratan esos créditos: 50 $ de crédito por 45 $, 250 $ por 200 $ y 1.000 $ por 700 $, hasta 2.000 $ en paquetes al mes por persona. Solo se gastan después de los límites del plan y requieren tener activado el uso adicional.

Precios de lista por millón de tokens en la página de precios de Claude a 10 de octubre de 2026 (entrada / salida):

Un ejemplo para hacerse una idea, con supuestos: un turno de Claude Code que lee 200.000 tokens y escribe 20.000, sin caché. En Opus 5.5 son 0,2 × 4 $ + 0,02 × 20 $ = 1,20 $; en Sonnet 5.5, 0,60 $; en Fable 5.1, 3,00 $. Con 20 $ de créditos salen unos 16 turnos así en Opus 5.5. Los turnos reales varían mucho, y la caché los abarata: la guía de costes indica que la caché dura una hora con suscripción y baja a cinco minutos cuando consumes créditos de uso, y que con API key son cinco minutos por defecto.

Dos datos más para presupuestar. Los planes cuestan 20 $ al mes en Pro (o 200 $ al año, 17 $ al mes), 100 $ en Max 5x y 200 $ en Max 20x, sin impuestos. Y en Pro los modelos Fable no entran en los límites del plan: se pagan con créditos de uso desde la primera petición, mientras que Max puede dedicar a Fable hasta la mitad de su límite semanal sin coste extra.

La decisión no es «la API siempre sale más barata» ni lo contrario. Para alguien que programa varias horas al día en un repositorio, la suscripción es más predecible. Para CI, backend y automatización de equipo, la API es más fácil de auditar. Las cuentas del uso adicional, con más ejemplos, están en Coste del uso adicional de Claude: créditos, Max y Claude Code, y si quieres empezar con la API, en Cómo comprar acceso a Claude API: créditos, Console y claves bajo tu control.

Cómo volver al inicio de sesión de suscripción

Si esperabas usar tu plan y ves gasto en Console, no empieces borrando claves en Console. La documentación de autenticación propone quitar la variable del entorno y comprobar con /status:

unset ANTHROPIC_API_KEY
claude
/status

Si la clave tiene que seguir en el entorno para otras herramientas, la alternativa es el toggle «Use custom API key» de /config, que solo aparece mientras ANTHROPIC_API_KEY está definida: desactívalo y Claude Code vuelve a tu sesión de suscripción sin tocar la variable. Si además entraste con la cuenta equivocada, /logout dentro de la sesión borra las credenciales y /login te deja elegir de nuevo tu cuenta de Claude.

unset no borra la API key de Claude Console; solo evita que ese shell se la pase a Claude Code. Si la clave reaparece al abrir otra terminal, está en una configuración persistente: archivos de inicio del shell, .env, devcontainer, secretos de CI, un LaunchAgent o los scripts de arranque del IDE. Revisa también ANTHROPIC_AUTH_TOKEN y apiKeyHelper, que van por delante de la suscripción.

Lo que no conviene mezclar

No digas que Claude Code es gratis porque se puede usar con un plan de pago. La suscripción tiene límites y la API tiene su propia factura.

No digas que Pro incluye llamadas a la API. Pro y Max cubren Claude Code mediante tu cuenta de Claude; la Claude API es un contrato de Console. Los créditos mensuales de Max son la excepción, y no sirven para Claude Code interactivo.

No uses la cifra en dólares de /usage como la factura de tu suscripción. /status, /usage, Settings > Usage y Console Usage responden a preguntas distintas.

No confundas un error del servidor con un problema de facturación. Un API Error: 529 Overloaded es un fallo temporal del lado de Anthropic y no indica qué credencial pagó; para eso está Claude Code API Error 500 y 529: reanuda sin duplicar trabajo.

No pegues una API key real en tickets, chats, capturas o prompts de soporte. Basta con decir si la variable existe y qué muestra /status.

Regla práctica para equipos

Conviene escribir la regla antes de que llegue la factura. Trabajo local e interactivo: inicio de sesión con suscripción. Scripts personales: claude setup-token o API key, pero nunca ambas en el mismo entorno. CI compartido, backend, agentes programados y productos: API key con un responsable de presupuesto. Seguir después del límite incluido: uso adicional con consentimiento explícito. Gasto de proyecto y recarga automática de la API: Claude Console.

En Team, cada miembro consume un cupo por puesto que se renueva en ventanas de cinco horas y semanales, y se gestiona en la consola de administración de claude.ai, no en Claude Console. Los créditos de API de Team (20 $ o 100 $ por puesto, hasta 500 $ al mes) son para la API, no para ese cupo. Si tu equipo usa la API, el espacio de trabajo «Claude Code» de Console admite límites de gasto propios.

Separar estas rutas evita dos errores frecuentes: subir a Max cuando el problema era una API key aprobada hace meses, o comprar créditos cuando el bloqueo real era un límite de suscripción. Primero identifica la ruta; después decide si limpias el entorno, esperas al reinicio, activas el uso adicional, cambias de plan o pasas la tarea a la API.

Ruta de verificación en tu cuenta

Sigue siempre el mismo orden: /status para saber qué credencial paga, después las variables ANTHROPIC_* y CLAUDE_CODE_* del shell, y por último Settings > Usage (plan y uso adicional) o la página Usage de Console (API). Así sabes primero quién paga la sesión y luego si toca limpiar el entorno, comprar créditos, comparar planes o cambiar una automatización.

Los datos de esta página corresponden a la documentación de autenticación, costes y condiciones de Claude Code, a la ayuda de Anthropic y a la página de precios de Claude a 10 de octubre de 2026. Si tienes dudas sobre qué créditos o reinicios existen además del uso adicional, Claude: crédito de la nube, créditos de uso y reinicio del límite los separa uno a uno.

Preguntas frecuentes

¿Necesito una API key para usar Claude Code?

No para el uso interactivo normal con Claude Pro o Max: inicias sesión con tu cuenta y consumes los límites del plan. Para scripts propios puedes usar claude setup-token. Necesitas API key para productos y servicios, para usar los créditos de API de Max o cuando quieres que el gasto sea de un proyecto de Console.

¿Claude Pro incluye una API key?

No. Ningún plan de suscripción incluye una API key; la Claude API se factura aparte en Console. Max y Team sí incluyen desde el 7 de octubre de 2026 créditos mensuales de API (100 $ en Max 5x, 200 $ en Max 20x), que se usan con una API key de la organización de Console que vincules. Pro no los recibe.

¿Por qué Claude Code factura a mi cuenta API si tengo Pro o Max?

Porque la sesión usa una credencial que va por delante de tu suscripción, casi siempre una ANTHROPIC_API_KEY que aprobaste en el aviso, o un claude -p lanzado en un shell donde existe la clave. /status marca qué credencial no se está usando.

¿Los usage credits son lo mismo que la suscripción?

No. Los créditos de uso permiten seguir después del uso incluido, pero se cobran aparte a tarifas estándar de API. La suscripción Pro o Max mantiene sus propios límites, y los créditos mensuales de API de Max tampoco se aplican al uso adicional.

¿Cuántos tokens tiene el plan Pro de Claude?

Anthropic no publica una cifra fija de tokens ni de mensajes para Pro. El plan tiene un límite por sesión que se renueva cada cinco horas y un límite semanal, y lo que consume cada petición depende del modelo y del tamaño del contexto. /usage te muestra las barras de tu plan. Cómo se multiplican esos límites en Max está en Límites de uso de Claude Pro y Max: el 5x y 20x es por sesión.

¿Hay plan de estudiante de Claude con Claude Code o API?

Anthropic no ofrece un precio de estudiante individual para Pro; Claude for Education se contrata a través de la universidad. Las opciones que existen están en Descuento Claude para estudiantes 2026, y las formas de pagar menos por Claude Code, en Descuento de Claude Code en 2026: cupones, Pro anual y créditos.

¿Debería usar API en vez de subir a Claude Max?

Solo si el trabajo es realmente de API: producto, backend, CI compartido o automatización que debe auditarse en Console. Para programar en local, revisa antes cómo consumes los límites en Límite de uso en Claude Code: cómo verlo y auditar tus tokens y la comparación Pro/Max. Ten en cuenta que Max 5x ya incluye 100 $ al mes en créditos de API para esa parte del trabajo.

¿/cost muestra mi factura de Pro o Max?

No. La cifra en dólares de la sesión, que la guía de costes actual sitúa en el bloque Session de /usage, es una estimación calculada a precio de lista. Para Pro y Max no tiene efecto en la factura; usa /status para saber la ruta, las barras de /usage o Settings > Usage para el plan y Console Usage para la API.

¿Cómo hago que Claude Code deje de usar mi API key?

Ejecuta unset ANTHROPIC_API_KEY en el shell desde el que lanzas Claude Code, o desactiva «Use custom API key» en /config, y confirma con /status. Si la clave vuelve, quítala de los archivos del shell, .env, secretos de CI o configuración del contenedor. Para cambiar de cuenta, usa /logout y /login.