Qué son los tokens en Claude Code y cuánto cuestan

¿Qué son los tokens en Claude?

Un token es la unidad de texto que Claude lee y escribe: un fragmento de una palabra, de aproximadamente 3.5 caracteres en inglés. Esta cifra procede del glosario de Anthropic. Al contar también los espacios y la puntuación, el resultado supera ampliamente un token por palabra. Por eso, mil palabras de prosa suelen superar con holgura los 1,300 tokens. El código consume más tokens por línea: las llaves, los operadores, los guiones bajos y la indentación se dividen en más tokens por carácter que el inglés. Un archivo de código fuente de unos cientos de líneas suele ocupar varios miles de tokens. Un archivo de 2,000 líneas que el agente decida leer puede suponer un consumo de cinco cifras en tokens antes de escribir una sola línea de código nuevo.

Los tokenizadores presentan dos aspectos que suelen causar confusión. Primero, dependen del modelo. En julio de 2026, Opus 4.7 y versiones posteriores, Sonnet 5 y Fable 5 usan un tokenizador más reciente que produce aproximadamente un 30% más de tokens para el mismo texto que los modelos Claude anteriores. El incremento exacto depende del contenido. Esto cambia cualquier cálculo de presupuesto basado en tokens, aunque el precio por token no haya aumentado. Segundo, tiktoken, la biblioteca que aparece en casi todas las publicaciones de blogs, es el tokenizador de OpenAI. En texto normal, subestima el consumo de Claude aproximadamente entre un 15% y un 20%, y la diferencia es mayor con código. El único recuento fiable es el endpoint count_tokens, que se explica a continuación.

Por qué cuesta lo que cuesta tu sesión de programación

Cada factura de Claude, ya sea una factura de API o un límite de suscripción, se reduce a un único contador: tokens de entrada y tokens de salida. La página de precios parece sencilla: cierta cantidad de dólares por cada millón de tokens de entrada y otra por cada millón de tokens de salida. Lo que no explica es que, en una sesión de programación con un agente, el contador de entrada aumenta mucho más de lo que sugiere la intuición, porque la conversación completa se vuelve a enviar en cada turno. He vendido infraestructura con medición durante quince años, y los tokens son el primer contador que he visto cuyo consumo la mayoría de los clientes realmente no puede explicar. Esta es la lección para leer el contador: qué cuenta como entrada y salida en una sesión con un agente, por qué el ciclo de reenvío es tan caro, cómo el almacenamiento en caché de prompts cambia los cálculos y qué factores modifican realmente la cifra.

Todo es entrada: lo que el medidor cuenta realmente

Se suele asumir que se paga por el código que escribe Claude. En una sesión agéntica, ese es el concepto menor. Los tokens de entrada, con la tarifa más baja pero un volumen mucho mayor, incluyen:

• El prompt del sistema. Las instrucciones del propio arnés de Claude Code, además de CLAUDE.md y los archivos de memoria, que se cargan al inicio de la sesión y están presentes en todas las solicitudes posteriores.
• Las definiciones de herramientas. Cada esquema de herramienta que el agente podría invocar. Cada servidor MCP que conecte aumenta esta sobrecarga fija, aunque Claude Code ahora aplaza de forma predeterminada las definiciones completas de las herramientas MCP. Por tanto, sólo los nombres de las herramientas permanecen en el contexto hasta que se usa una de ellas. Esto reduce el coste, pero no lo elimina.
• Cada archivo que lee el agente. Un Read de un archivo de código fuente introduce el archivo completo en el contexto y permanece allí.
• Cada resultado de una herramienta. Ejecuciones de pruebas, salida de grep, salida del terminal, registros de compilación: todo vuelve como tokens de entrada. Una suite de pruebas fallida que imprime 8,000 líneas acaba facturando el equivalente a un libro corto.
• Toda la conversación hasta ese momento, reenviada en cada turno. Este punto merece su propia sección.

El reenvío que nadie tiene en cuenta

La API de Claude no tiene estado. No recuerda la sesión entre solicitudes; en realidad, nada lo hace. Por eso, en el turno 2, el cliente envía el turno 1, la respuesta de Claude y el mensaje nuevo. En el turno 50, vuelve a enviar los turnos 1 a 49, cada archivo leído, cada resultado de herramienta y cada diferencia, además del turno 50. El modelo vuelve a leer toda la transcripción en cada solicitud, y todos esos tokens que vuelve a leer se facturan como entrada.

La consecuencia es que el coste por turno crece aproximadamente de forma lineal con la duración de la sesión, mientras que el coste total de la sesión crece aproximadamente de forma cuadrática. Un mensaje que costó medio centavo en el turno 3 puede costar veinte veces más en el turno 60, aunque contenga la misma pregunta de una sola línea, porque incluye sesenta turnos de contexto. Este es el hecho principal que explica la mayoría de las consultas sobre facturas inesperadamente altas. No es una particularidad de Claude: cualquier producto LLM que parezca tener estado es una API sin estado con un ciclo de reenvío subyacente.

Salida: lo que ves y el razonamiento que no ves

Los tokens de salida son el componente más caro, con una tarifa cinco veces superior a la de entrada en la gama actual ($5/$25 en Opus 4.8, $3/$15 en Sonnet 5 y $1/$5 en Haiku 4.5, a fecha de julio de 2026). La salida incluye el texto y el código que genera Claude, además de los tokens de razonamiento: el razonamiento interno que realiza el modelo antes de responder. Aquí importan dos hechos. El razonamiento se factura con las tarifas de salida y cuenta para max_tokens. Una respuesta de API que termina con stop_reason: "max_tokens" y una respuesta truncada suelen indicar que el razonamiento consumió el presupuesto antes de que se generara la respuesta. Además, en los modelos actuales es posible que el resumen del razonamiento no se muestre. Opus 4.8, Sonnet 5 y Fable 5 lo omiten de forma predeterminada, pero el razonamiento sigue produciéndose y facturándose. Que no sea visible no significa que sea gratuito.

Claude Code habilita el razonamiento ampliado de forma predeterminada porque mejora de forma medible el trabajo en varios pasos, y el presupuesto predeterminado puede alcanzar decenas de miles de tokens por solicitud. En tareas sencillas puede reducirlo: disminuya el nivel de esfuerzo con /effort o en /model, o ajuste la configuración del razonamiento en /config. Es una forma real de controlar los costes, no una cuestión de superstición.

El almacenamiento en caché de prompts cambia los cálculos

El almacenamiento en caché de prompts es la razón por la que el bucle de reenvío no dispara los costes. La API puede almacenar en caché un prefijo estable del prompt, el prompt del sistema, las definiciones de herramientas y el historial de la conversación, y servirlo en la siguiente solicitud por una fracción del precio. A fecha de julio de 2026, los multiplicadores son los siguientes: una escritura en la caché cuesta 1.25× la tarifa base de entrada (2× para la variante de 1 hora), y una lectura de la caché cuesta 0.1×. Las escrituras tienen un recargo; las lecturas tienen un descuento del 90%. Una sola lectura ya compensa con creces el recargo de la escritura de 5 minutos.

Claude Code gestiona la caché por usted y, en una sesión en buen estado, casi todo ese reenvío enorme se sirve desde la caché. Sin embargo, la caché predeterminada permanece activa durante cinco minutos desde el último uso. Si se aleja para tomar un café, tarda más de lo previsto, vuelve y envía un mensaje, la caché ha caducado y todo el prefijo acumulado se vuelve a escribir a 1.25% en lugar de leerse a 0.1×. En una sesión de 150K tokens, ese único turno en frío cuesta más que una docena de turnos en caliente. Este es el resultado contrario a la intuición que conviene tener presente: un ritmo de pausa y reanudación puede costar más que el trabajo continuo, porque cada pausa que supera el TTL convierte el siguiente turno de una lectura barata en una reescritura cara. Trabaje por tandas; no alimente una sesión enorme con un mensaje cada diez minutos.

Si llama a la API desde su propia aplicación en un VPS, no obtiene nada de esto de forma gratuita. El error clásico que uno mismo puede provocar es interpolar una marca de tiempo o un ID de solicitud en el prompt del sistema. Esto cambia los bytes del prefijo en cada solicitud y deshabilita la caché silenciosamente. La señal es que usage.cache_read_input_tokens permanece en cero en llamadas con el mismo aspecto.

La fórmula, con un ejemplo práctico

Ignore a cualquiera que cite una tarifa fija de «$X por sesión». Las sesiones pueden variar en dos órdenes de magnitud. La fórmula válida es:

turn cost = (uncached input      x base input price)
          + (cache writes        x 1.25 x base input price)
          + (cache reads         x 0.10 x base input price)
          + (output incl. thinking x output price)

session cost = sum over all turns

Ejemplo práctico con Claude Opus 4.8, cuyo precio en julio de 2026 es de $5 por millón de tokens de entrada y $25 por millón de tokens de salida. En un turno a mitad de la sesión, con 80,000 tokens de contexto acumulado: 75,000 se leen de la caché, se escriben 3,000 nuevos, 2,000 son entradas nuevas sin caché y la salida contiene 1,500 tokens, incluido el razonamiento.

• Lecturas de caché: 75,000 × $0.50/M = $0.0375
• Escrituras en caché: 3,000 × $6.25/M = $0.019
• Entrada sin caché: 2,000 × $5/M = $0.010
• Salida: 1,500 × $25/M = $0.0375

Unos $0.10 por turno; cincuenta turnos como este costarían alrededor de $5. Ahora suponga el mismo turno después de que caduque la caché: volver a escribir los 80,000 tokens completos a $6.25/M cuesta $0.50 antes de contar la salida, aproximadamente cinco veces el coste del turno completo con la caché activa, para realizar exactamente el mismo trabajo. Esa diferencia resume toda la cuestión de la caché en una sola cifra. Esas mismas cuatro líneas son también la única forma fiable de comparar proveedores, porque las tarifas publicadas no tienen en cuenta las lecturas de caché ni el razonamiento, y aplicarlas a tres trabajos reales muestra dónde la factura de Claude queda por encima o por debajo de la de OpenAI.

Si quiere entender la unidad de facturación en sí, en lugar de un solo turno, cuánto representan un millón de tokens en páginas, archivos y dólares aplica el mismo cálculo en un nivel superior. Sirve para orientarse, no para hacer predicciones: las cifras publicadas por Anthropic para implementaciones empresariales de Claude Code indican que, en julio de 2026, el promedio es de unos $13 por desarrollador y día activo y de $150–250 al mes, mientras que el 90% de los usuarios se mantiene por debajo de $30 al día. El consumo depende del modelo elegido, la higiene de las sesiones y el tamaño del código base. Por eso son importantes los controles que se explican a continuación.

Ver su propio uso

En Claude Code, el comando es /usage (/cost sigue funcionando porque es un alias). El bloque Session de la parte superior muestra las estadísticas de tokens y una estimación de coste calculada localmente para la sesión actual. En los planes de suscripción, la misma pantalla muestra las barras de límite del plan y un desglose que atribuye el uso reciente a skills, subagentes, plugins y servidores MCP individuales. Para consultar la facturación oficial de las cuentas de API, la página de uso de Claude Console es la fuente de referencia; la cifra de la CLI es una estimación. /context muestra una cuadrícula de colores con lo que ocupa la ventana de contexto, el prompt del sistema, las herramientas, las definiciones de MCP, los archivos y el historial. Es la forma más rápida de detectar un CLAUDE.md demasiado grande o un servidor MCP que genera demasiados mensajes. Pase all para ampliar el desglose completo por elemento.

Desde la API, cada respuesta indica exactamente lo que ocurrió:

response = client.messages.create(model="claude-sonnet-5", max_tokens=2048,
                                  messages=messages)
u = response.usage
total_prompt = u.input_tokens + u.cache_creation_input_tokens + u.cache_read_input_tokens
print(f"uncached={u.input_tokens} written={u.cache_creation_input_tokens} "
      f"read={u.cache_read_input_tokens} output={u.output_tokens}")

Tenga en cuenta que input_tokens sólo representa la parte restante no almacenada en caché. El tamaño real del prompt es la suma de los tres campos de entrada. Un agente que se ejecutó durante una hora y mostró input_tokens: 4000 no es barato; los otros 200,000 tokens se sirvieron desde la caché. Para hacer una estimación antes de enviar la solicitud, use el endpoint de recuento de tokens. Es gratuito, tiene su propio límite de tasa y cuenta con el tokenizer del modelo que indique. Considere el resultado una estimación aproximada; la facturación refleja la solicitud real:

count = client.messages.count_tokens(model="claude-sonnet-5",
                                     messages=[{"role": "user", "content": big_file}])
print(count.input_tokens)

Nunca tiktoken por el motivo anterior.

Planes de suscripción frente al pago por uso

La mecánica de esta guía es idéntica en todos los casos; sólo cambia la facturación. Con una clave de API, Anthropic factura mediante pago por uso, por token y según las tarifas publicadas. Cada cifra anterior representa dinero real. Ese contador empieza antes de lo que espera la mayoría, porque no hay un nivel gratuito al que recurrir. Sólo hay un crédito pequeño al registrarse y algunos endpoints que no generan cargos. Esto es lo que obtiene realmente una cuenta de API nueva antes de asociar una tarjeta. En una suscripción de Claude (Pro, Max, Team, Enterprise), el uso de Claude Code se descuenta del límite incluido en el plan. En julio de 2026, ese límite consiste en una ventana móvil de sesión de cinco horas y una ventana semanal, compartidas entre modelos y con el chat de claude.ai. La cifra de dólares /usage es informativa y no representa un cargo. Cuando se agota una ventana, aparece "You've hit your session limit" o "You've hit your weekly limit", junto con la hora de restablecimiento. Cambiar de modelo con /model no restaura el acceso porque las ventanas se comparten entre modelos. Estas ventanas dependen de la cuenta, no del cliente que esté utilizando. Conviene saberlo si todavía está comprobando qué funciona de forma nativa en Linux y qué plan cubre cada superficie. La ventana que se haya agotado determina cuánto debe esperar y qué medidas puede tomar mientras tanto. Por eso conviene conocer sus opciones cuando alcanza un límite durante una tarea. Los planes pueden habilitar créditos de uso de forma opcional. Se gestionan con /usage-credits y permiten comprar uso por encima del límite. No incluyo deliberadamente las cuotas de los planes: son las cifras más variables de todo este tema. Consulte claude.com/pricing y sus propias barras de /usage. La mecánica de los tokens sigue siendo importante con una suscripción. Una sesión ineficiente consume la ventana igual que consumiría dólares. Para la parte de las suscripciones, consulte qué plan de Claude se adapta a su uso.

Las medidas que realmente funcionan

• Limite lo que lee el agente. «Corrige el error de validación en auth.py» lee un archivo; «mejora este código» lee cuarenta. Mantenga CLAUDE.md reducido: se carga en todas las sesiones, así que debe contener sólo lo esencial. Traslade las instrucciones específicas del flujo de trabajo a skills que se carguen cuando sean necesarias.
• Sea claro y conciso. /clear entre tareas no relacionadas. El contexto obsoleto se vuelve a enviar y se vuelve a facturar en cada mensaje posterior. En una tarea larga, /compact Focus on the failing tests and the diff resume el historial y evita la curva cuadrática.
• Elija un modelo adecuado. Sonnet se encarga de la mayoría de las tareas de programación a $2/$10 por millón de tokens con los precios introductorios de julio de 2026 ($3/$15 como precio de lista, frente a $5/$25 para Opus), y Haiku, a $1/$5, es la opción adecuada para tareas mecánicas de subagentes, como clasificar registros. Fable 5 está en el extremo opuesto, a $10/$50, el doble que Opus en ambos tipos de tokens. Por eso conviene saber qué trabajos justifican realmente esa tarifa antes de dejarlo seleccionado para tareas rutinarias. /model cambia de modelo a mitad de la sesión.
• Filtre previamente la salida extensa. Un hook que reduzca una ejecución de pruebas a los fallos mediante grep antes de que Claude la vea convierte 20,000 tokens de resultado de herramienta en 300. Además, lo hace en cada reenvío posterior de ese turno.
• Agrupe lo que no sea interactivo. Para sus propios pipelines de API, clasificación, revisiones masivas y tareas nocturnas, la Batches API ejecuta los mismos modelos con un descuento del 50% a cambio de una entrega asíncrona.
• Respete el ciclo de vida de la caché. Trabaje en sesiones continuas. Una sesión de Claude Code en tmux en un VPS no cuesta nada mientras está inactiva; los tokens sólo se consumen cuando se ejecuta un turno. Sin embargo, el tiempo de inactividad hace que se pierda la caché activa, y el siguiente turno debe volver a escribir el contexto.

FAQ

¿Cuántos tokens consume una sesión de programación en Claude Code?

No hay una cantidad fija. Un turno a mitad de la sesión suele incluir decenas de miles de tokens de solicitud cuando se acumulan los archivos y el historial, y una sesión de trabajo llega a millones. La mayor parte se sirve desde la caché a una décima parte de la tarifa base. Como referencia, las cifras empresariales publicadas por Anthropic en julio de 2026 indican un promedio de unos $13 por desarrollador y día activo, y que el 90% de los usuarios se mantiene por debajo de $30. Ejecute /usage en su propia sesión. Observarlo durante cinco minutos es más útil que cualquier promedio publicado.

¿Los tokens de razonamiento cuestan dinero aunque no pueda verlos?

Sí. Los tokens de razonamiento se facturan como tokens de salida, con la tarifa más alta, y cuentan para max_tokens. Los modelos actuales también los facturan aunque la interfaz no muestre el resumen del razonamiento. Si una respuesta se trunca con stop_reason: "max_tokens" antes de terminar la respuesta visible, es probable que el razonamiento haya consumido el presupuesto. En Claude Code, reduzca el nivel de esfuerzo con /effort para las tareas que no necesitan un razonamiento profundo.

¿Por qué una sesión larga de Claude Code se vuelve más cara por mensaje?

Porque la API no conserva el estado. En cada turno vuelve a enviar toda la conversación, cada archivo leído, cada resultado de herramienta y cada intercambio anterior como entrada facturada. Por eso, el turno 50 incluye los turnos 1 a 49. La caché de solicitudes sirve el prefijo repetido aproximadamente a una décima parte del precio base de entrada, pero el prefijo sigue creciendo. Además, cualquier intervalo de inactividad superior al TTL de la caché convierte el siguiente turno en una reescritura a precio completo. /compact reduce el historial; /clear lo reinicia.

¿Cómo puedo consultar el uso de tokens y el coste de Claude?

En Claude Code, /usage muestra las estadísticas de tokens de la sesión, una estimación del coste local y las barras de límite del plan en las suscripciones (/cost es un alias). /context muestra qué elementos ocupan la ventana. Para consultar la facturación autorizada de la API, use la página de uso de Claude Console. En su propio código, lea response.usage. La suma de input_tokens, cache_creation_input_tokens y cache_read_input_tokens proporciona el tamaño real de la solicitud. Para estimarlo de antemano, use el endpoint count_tokens, nunca tiktoken.