Tokens de Claude: cálculo real en Claude Code

¿Qué son los tokens en Claude?

Un token es la unidad de texto que Claude lee y escribe: un fragmento de palabra. El glosario de Anthropic lo sitúa en aproximadamente 3,5 caracteres en inglés para modelos anteriores a Claude Opus 4.7. En el tokenizador actual, la cifra se acerca más a 2,5, ya que Anthropic estima que 1M de tokens equivalen a unos 2,5M de caracteres. En cualquier caso, el resultado es superior a un token por palabra una vez que se cuentan espacios y puntuación, por lo que mil palabras de prosa superan holgadamente los 1.300 tokens. El código es más denso por línea: las llaves, los operadores, los guiones bajos y la sangría se dividen en más tokens por carácter que el inglés, y un archivo fuente de unos pocos cientos de líneas suele pesar varios miles de tokens. Un archivo de 2.000 líneas que el agente decida leer supone un consumo de cinco cifras en tokens antes de que nadie haya escrito una sola línea de código nuevo.

Dos aspectos sobre los tokenizadores suelen confundir a los usuarios. Primero, son específicos de cada modelo. A fecha de octubre de 2026, Claude Opus 4.7 y todos los modelos posteriores, incluidos los actuales Fable 5.1, Opus 5.5, Sonnet 5.5 y Haiku 5.5, utilizan un tokenizador más reciente que genera aproximadamente un 30% más de tokens para el mismo texto que los modelos anteriores de Claude, como Haiku 4.5 (el incremento exacto varía según el contenido), lo cual altera cualquier presupuesto en tokens aunque los precios por token no hayan subido con ello. Segundo, tiktoken, la biblioteca que citan todas las entradas de blog, es el tokenizador de OpenAI, no el de Claude, por lo que sus conteos no coincidirán con lo que factura Anthropic. El único conteo fiable es el endpoint count_tokens, que se detalla a continuación.

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

Cada factura de Claude, ya sea un recibo de API o un límite de suscripción, se basa principalmente en una métrica: tokens de entrada y tokens de salida. Algunas herramientas de API añaden su propio coste (la búsqueda web, por ejemplo, cuesta 10 USD por cada 1000 búsquedas a fecha de octubre de 2026, además de los tokens que añaden sus resultados), pero en una sesión de programación es el contador de tokens el que determina el gasto. La página de precios lo presenta de forma sencilla: una cantidad de dólares por millón de tokens de entrada y otra por millón de tokens de salida. Lo que no explica es que, en una sesión de programación con agentes, el contador de entrada aumenta mucho más rápido de lo que sugiere la intuición, ya que toda la conversación se reenvía en cada turno. He vendido infraestructura basada en consumo durante quince años y los tokens son el primer medidor donde la mayoría de los clientes no saben realmente qué es lo que genera el gasto. Esta es la lección sobre cómo leer el contador: qué cuenta como entrada y salida en una sesión con agentes, por qué el bucle de reenvío es tan costoso, por qué el almacenamiento en caché de prompts (prompt caching) cambia los cálculos y qué factores influyen realmente en el coste final.

Todo es entrada: qué contabiliza realmente el medidor

La gente asume que paga por el código que escribe Claude. En una sesión de agente, esa es la partida pequeña. Los tokens de entrada, que tienen una tarifa más económica pero un volumen mucho mayor, incluyen:

• El prompt del sistema. Las instrucciones propias del entorno de Claude Code, además de sus CLAUDE.md y archivos de memoria, que se cargan al inicio de la sesión y están presentes en cada solicitud posterior.
• 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 difiere las definiciones completas de herramientas MCP de forma predeterminada. Por tanto, solo los nombres de las herramientas permanecen en el contexto hasta que se utiliza una herramienta por primera vez, lo que suaviza pero no elimina el coste.
• Cada archivo que lee el agente. Un Read de un archivo fuente coloca todo su contenido en el contexto, y allí permanece.
• Cada resultado de herramienta. Las ejecuciones de pruebas, la salida de grep, el volcado de terminal, los registros de compilación; todo ello regresa como tokens de entrada. Una suite de pruebas fallida que imprime 8.000 líneas equivale a un libro pequeño. A fecha de octubre de 2026, Claude Code transmite aproximadamente 30.000 caracteres de salida de comandos en línea de forma predeterminada. Cualquier contenido más largo llega como un archivo guardado junto con una vista previa de hasta 2.000 caracteres, pero cada salida por debajo de ese límite, y cada lectura posterior del archivo guardado, se factura en su totalidad.
• Toda la conversación hasta el momento, reenviada en cada turno. Esto merece su propia sección.

El reenvío que nadie calcula

La API de Claude no conserva 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, su respuesta y el mensaje nuevo. En el turno 50, vuelve a enviar todo lo que siga en el contexto de los turnos 1 a 49, cada archivo leído, resultado de herramienta y diff que no se haya eliminado mediante compactación, además del turno 50. (La compactación sustituye el historial antiguo por un resumen, y las lecturas de archivos de un subagente permanecen en su propio contexto; sólo vuelve su resultado). El modelo vuelve a leer toda la transcripción conservada en cada solicitud, y cada uno de esos tokens releídos se factura como entrada.

La consecuencia es que el coste por turno crece aproximadamente de forma lineal con la duración de la sesión, y el coste total de la sesión crece aproximadamente de forma cuadrática. Un mensaje que costaba medio centavo en el turno 3 puede costar veinte veces más en el turno 60, con la misma pregunta de una línea, porque transporta la carga de sesenta turnos. Este es el único hecho que explica la mayoría de las consultas «¿por qué fue tan alta mi factura?». No es una particularidad de Claude: todo producto LLM que parece conservar estado usa en realidad una API sin estado con un bucle de reenvío subyacente.

Salida: lo que ve, más el razonamiento que no ve

Los tokens de salida son los más caros: cuestan cinco veces la tarifa de entrada en toda la gama actual ($10/$50 en Fable 5.1, $4/$20 en Opus 5.5, $2/$10 en Sonnet 5.5 y $0.10/$0.50 en Haiku 5.5 para prompts de hasta 100,000 tokens, a fecha de octubre 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 la API que termina con stop_reason: "max_tokens" y una respuesta truncada suelen indicar que el razonamiento consumió el presupuesto antes que la respuesta. Además, en los modelos actuales es posible que el resumen del razonamiento no se muestre. La API lo omite de forma predeterminada en Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5 y en los modelos anteriores hasta Opus 4.7, pero el razonamiento se produjo y se sigue facturando. Que no sea visible no significa que sea gratuito.

Claude Code habilita el razonamiento extendido de forma predeterminada porque mejora de forma medible el trabajo en varios pasos, y el presupuesto predeterminado puede llegar a decenas de miles de tokens por solicitud. En tareas sencillas, puede reducirlo: disminuya el nivel de esfuerzo con /effort o en /model, o desactive el razonamiento en /config en los modelos que lo permiten. A fecha de octubre de 2026, Claude Code no puede desactivar el razonamiento en Opus 5.5, Sonnet 5.5, Haiku 5.5 ni en los modelos Fable, por lo que el nivel de esfuerzo es el mecanismo de control en esos casos. La API ofrece más margen en dos de ellos. Haiku 5.5 acepta thinking: {"type": "disabled"} con un nivel de esfuerzo alto o inferior, al igual que los modelos Opus 5 y Sonnet 5 anteriores. Sonnet 5.5 rechaza "disabled" y usa thinking: {"type": "between_tools"} en su lugar. Esto elimina el razonamiento inicial con niveles de esfuerzo bajo, medio o alto, de modo que una solicitud sin herramientas recibe la respuesta sin razonamiento previo. Sólo Opus 5.5 y los modelos Fable mantienen el razonamiento independientemente de lo que envíe. Este es un mecanismo real para controlar costes, no una 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 arruina a nadie. La API puede almacenar un prefijo estable de su prompt, el prompt del sistema, las definiciones de herramientas, el historial de la conversación y, en la siguiente solicitud, servirlo a una fracción del precio. A fecha de octubre de 2026, los multiplicadores son: una escritura en caché cuesta 1,25× la tarifa base de entrada (2× para la variante de 1 hora), y una lectura de caché cuesta 0,1× en la mayoría de los modelos, 0,05× en Claude Opus 5.5 y Claude Sonnet 5.5, y 0,025× en Claude Fable 5.1. Las escrituras tienen un sobrecoste; las lecturas suponen un descuento del 90% en la mayoría de los modelos, del 95% en Opus 5.5 y Sonnet 5.5, y del 97,5% en Fable 5.1. (La tarifa de lectura de Sonnet 5.5 se redujo de 0,1× a 0,05× el 7 de octubre de 2026). Una sola lectura compensa con creces el sobrecoste de escritura de 5 minutos.

Claude Code gestiona el almacenamiento en caché por usted y, en una sesión saludable, casi todo ese reenvío masivo se sirve desde la caché. Sin embargo, la caché caduca tras un periodo de inactividad. A fecha de octubre de 2026, Claude Code ofrece a su conversación principal una caché de una hora en una suscripción dentro del uso incluido en su plan, y de cinco minutos desde el último uso en una clave de API, un proveedor de nube o una vez que esté consumiendo créditos de uso (el ajuste promptCacheTtl puede solicitar la hora en ese caso, a la tarifa de escritura de 2×). Con una caché de cinco minutos, si se ausenta para tomar un café que se alarga, vuelve y envía un mensaje, la caché habrá caducado y el prefijo acumulado completo se reescribirá a 1,25× en lugar de leerse a la tarifa de caché. En una sesión de 150K tokens, ese único turno en frío escribe los 150K tokens a 1,25×, mientras que un turno en caliente los habría leído a 0,1×; una diferencia de 12,5 veces en el prefijo (25 veces en Opus 5.5 y Sonnet 5.5, 50 veces en Fable 5.1). Este es el resultado contraintuitivo que merece la pena interiorizar: un ritmo de inactividad seguido de reanudación puede costar más que el trabajo continuo, porque cada intervalo de inactividad que supera el TTL convierte su siguiente turno de una lectura barata en una reescritura costosa. Trabaje en periodos intensivos; con una caché de cinco minutos, no alimente una sesión enorme con un mensaje cada diez minutos.

Si está llamando a la API desde su propia aplicación en un VPS, nada de esto ocurre automáticamente: usted debe optar por ello con cache_control, y el error clásico autoinfligido es incluir una marca de tiempo o un ID de solicitud interpolado en el prompt del sistema, lo que cambia los bytes del prefijo en cada solicitud y deshabilita el almacenamiento en caché de forma silenciosa. El indicador es usage.cache_read_input_tokens, que se mantiene en cero en llamadas que parecen idénticas.

La fórmula, con un ejemplo práctico

Ignore a cualquiera que cite un simple "una sesión cuesta $X". Las sesiones varían en dos órdenes de magnitud. Lo que se mantiene es la fórmula:

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

read multiplier = 0.10 on most models, 0.05 on Opus 5.5 and Sonnet 5.5, 0.025 on Fable 5.1
session cost = sum over all turns

Ejemplo práctico con Claude Opus 4.8, un modelo antiguo pero aún disponible y que, a fecha de octubre de 2026, sigue costando $5 por millón de tokens de entrada y $25 por millón de salida. Un turno a mitad de sesión con 80.000 tokens de contexto acumulado: 75.000 leídos de caché, 3.000 escritos recientemente, 2.000 de entrada nueva sin caché y 1.500 tokens de salida incluyendo el proceso de pensamiento.

• Lecturas de caché: 75.000 × $0.50/M = $0.0375
• Escrituras de caché: 3.000 × $6.25/M = $0.019
• Entrada sin caché: 2.000 × $5/M = $0.010
• Salida: 1.500 × $25/M = $0.0375

Aproximadamente $0.10 por el turno; cincuenta turnos similares, alrededor de $5. Ahora, el mismo turno tras expirar la caché: los 78.000 tokens almacenables se reescriben a $6.25/M, más los mismos 2.000 tokens sin caché a $5/M, suman cerca de $0.50 antes de la salida, aproximadamente cinco veces el coste del turno en caliente, para el mismo trabajo. Esa diferencia es toda la historia del almacenamiento en caché resumida en una cifra. En el actual Claude Opus 5.5 ($4/$20, con lecturas de caché a 0.05×), el mismo turno en caliente cuesta cerca de $0.07 (lecturas $0.015, escrituras $0.015, entrada sin caché $0.008, salida $0.030), y la versión en frío cuesta $0.40 antes de la salida, cerca de seis veces el turno en caliente. Esas mismas cuatro líneas son también la única forma honesta de comparar proveedores, ya que las tarifas de lista ignoran por completo las lecturas de caché y el proceso de pensamiento, y ejecutarlas en tres trabajos reales muestra dónde se sitúa la factura de Claude por encima o por debajo de la de OpenAI.

Si lo que busca es una idea de la unidad de facturación en lugar de un solo turno, a cuánto equivalen un millón de tokens en páginas, archivos y dólares realiza la misma aritmética un nivel por encima. Para calibrar en lugar de predecir: las cifras publicadas por Anthropic para despliegues empresariales de Claude Code, a octubre de 2026, promedian unos $13 por desarrollador por día activo, de $150 a $250 al mes, con un 90% de los usuarios por debajo de los $30 al día. Su resultado depende de la elección del modelo, la higiene de la sesión y el tamaño de la base de código, que es precisamente por lo que los controles siguientes son importantes.

Visualización de su propio uso

En Claude Code, el comando es /usage (/cost sigue funcionando, es un alias). El bloque de sesión en la parte superior muestra 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 de su plan y un desglose que atribuye el uso reciente a habilidades, subagentes, plugins y servidores MCP individuales. En versiones recientes, el bloque de sesión también incluye una línea Prompt cache (main) que muestra la proporción de entrada servida desde la caché, los fallos de caché y si la caché está activa en este momento. Para la facturación oficial en cuentas API, la página de uso en la Claude Console es la fuente de verdad; la cifra de la CLI es una estimación. /context dibuja una cuadrícula coloreada de 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 inflado o un servidor MCP demasiado comunicativo. Pase all para expandir el desglose completo por elemento.

Desde la API, cada respuesta le indica exactamente qué ha ocurrido:

response = client.messages.create(model="claude-sonnet-5-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 es solo el resto no almacenado 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 mostrando input_tokens: 4000 no es barato; los otros 200,000 tokens se sirvieron desde la caché. Para realizar una estimación antes de enviar, utilice el endpoint de conteo de tokens; su llamada es gratuita, tiene su propio límite de tasa y cuenta con el tokenizador del modelo que usted especifique (considere el resultado como una estimación cercana; la facturación refleja la solicitud real):

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

Nunca tiktoken, por la razón expuesta anteriormente.

Planes de suscripción frente a pago por uso

Los mecanismos descritos en esta guía son idénticos en todos los casos; solo difiere la facturación. Con una API key, Anthropic factura mediante pago por uso, por token, según las tarifas publicadas; cada cifra mencionada arriba representa dinero real. Ese contador comienza antes de lo que la mayoría espera, ya que no existe un nivel gratuito al cual recurrir, solo un pequeño crédito al registrarse y un puñado de endpoints que no generan cargos, que es lo que realmente obtiene una cuenta de API nueva antes de añadir una tarjeta. La excepción, desde el 7 de octubre de 2026, son las suscripciones Max o Team: estos planes ahora incluyen créditos mensuales de API para sus propias aplicaciones y agentes en la Claude Platform, 100 dólares al mes en Max 5x y 200 en Max 20x, y en Team 20 dólares por asiento Standard y 100 por asiento Premium, acumulados y limitados a 500 dólares. Se reclaman vinculando una organización en la Console, los créditos no utilizados caducan al final de cada ciclo de facturación y no cubren el uso interactivo de Claude Code. En una suscripción a Claude (Pro, Max, Team y planes Enterprise heredados basados en asientos), el uso de Claude Code consume la asignación incluida en su plan: a fecha de octubre de 2026, esto consiste en una ventana de sesión móvil de cinco horas más una ventana semanal, compartida entre modelos y con el chat de claude.ai, y la cifra en dólares /usage es informativa en lugar de una factura. Dos excepciones a fecha de octubre de 2026: los asientos Enterprise actuales basados en uso no incluyen ninguna asignación, por lo que cada token se factura a las tarifas estándar de la API, y los modelos Fable no están incluidos en la asignación de Pro, asientos Team estándar o asientos Enterprise heredados estándar, donde funcionan mediante créditos de pago por uso. Si agota una ventana, verá "You've hit your session limit" o "You've hit your weekly limit" con un tiempo de restablecimiento, y cambiar de modelo con /model no restaurará el acceso, ya que las ventanas son compartidas entre modelos. Esas ventanas siguen a la cuenta y no al cliente en el que se encuentre, algo que conviene saber si aún está determinando qué se ejecuta de forma nativa en Linux y qué plan cubre cada superficie. Cuál de las dos ventanas haya agotado determina cuánto tiempo debe esperar y qué es recomendable hacer mientras tanto, por lo que resulta útil conocer sus opciones cuando alcanza un límite a mitad de una tarea. Los planes pueden habilitar opcionalmente créditos de uso, gestionados con /usage-credits, para comprar capacidad más allá del límite. Deliberadamente no incluiré las cuotas de los planes: son las cifras más volátiles de todo este tema, así que consulte claude.com/pricing y sus propias barras de /usage en su lugar. Los mecanismos de tokens siguen siendo importantes en una suscripción; una sesión ineficiente consume su ventana exactamente igual que consumiría dólares. Para el aspecto de la suscripción, consulte qué plan de Claude se ajusta a su uso.

Las palancas que realmente funcionan

• Limite lo que lee el agente. "Corregir el error de validación en auth.py" lee un solo archivo; "mejorar esta base de código" lee cuarenta. Mantenga CLAUDE.md ligero, ya que se carga en cada sesión; limítelo a lo esencial y mueva las instrucciones específicas de flujo de trabajo a habilidades que se carguen bajo demanda.
• Claro y compacto. /clear entre tareas no relacionadas; el contexto obsoleto se reenvía y se vuelve a facturar en cada mensaje posterior. Dentro de una tarea larga, /compact Focus on the failing tests and the diff resume el historial y le mantiene fuera de la curva cuadrática.
• Ajuste el tamaño del modelo. Sonnet maneja la mayoría de la programación a $2/$10 por millón de tokens a fecha de octubre de 2026, ahora un precio estándar en lugar de uno introductorio: Sonnet 5.5 cuesta $2/$10, y Sonnet 5 mantuvo los $2/$10 cuando se canceló su subida prevista a $3/$15 para el 1 de septiembre. Esto se compara con Opus 5.5 a $4/$20, y Haiku 5.5 a $0.10/$0.50 (para prompts de hasta 100,000 tokens, $0.50/$2.50 por encima de eso) es la herramienta adecuada para el trabajo mecánico de subagentes, como el triaje de registros. Fable 5.1 se sitúa en el otro extremo a $10/$50, la misma tarifa que Fable 5 y dos veces y media Opus 5.5 en ambos lados del medidor, por lo que vale la pena saber qué trabajos justifican realmente esa tarifa antes de dejarlo seleccionado para el trabajo rutinario. /model cambia a mitad de la sesión.
• Pre-filtre la salida verbosa. Un hook que utiliza grep para reducir una ejecución de prueba a solo los fallos antes de que Claude la vea convierte 20,000 tokens de resultado de herramienta en 300, y lo hace en cada reenvío futuro de ese turno.
• Procese por lotes lo que no sea interactivo. Para sus propias tuberías de API, clasificación, revisión masiva y trabajos nocturnos, la API de lotes (Batches API) ejecuta los mismos modelos con un 50% de descuento a cambio de una entrega asíncrona.
• Respete el reloj de caché. Trabaje en periodos continuos. Una sesión de Claude Code en tmux en un VPS desconectada no cuesta nada mientras está inactiva; los tokens solo se consumen cuando se ejecuta un turno, pero el tiempo de inactividad que supera el TTL de la caché invalida la caché activa, y el siguiente turno paga la reescritura.

FAQ

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

No existe un número fijo. Un turno intermedio en una sesión suele conllevar decenas de miles de tokens de prompt una vez que se acumulan los archivos y el historial, y una sesión de trabajo puede alcanzar los millones. La mayoría se sirven desde la caché a una décima parte de la tarifa base o menos, dependiendo del modelo. Para calibrar, las cifras empresariales publicadas por Anthropic en octubre de 2026 promedian alrededor de 13 USD por desarrollador por día activo, con el 90% de los usuarios por debajo de los 30 USD. Ejecute /usage en su propia sesión; cinco minutos de observación valen más que cualquier promedio publicado.

¿Los tokens de pensamiento cuestan dinero incluso cuando no puedo verlos?

Sí. Los tokens de pensamiento se facturan como tokens de salida, a la tarifa más cara, y descuentan de max_tokens. Los modelos actuales los facturan incluso cuando la interfaz omite el resumen del razonamiento en la pantalla. Si una respuesta se trunca con stop_reason: "max_tokens" antes de que termine la respuesta visible, es probable que el razonamiento haya consumido el presupuesto. En Claude Code, reduzca el nivel de esfuerzo con /effort para tareas que no requieran un razonamiento profundo.

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

Porque la API no tiene estado: cada turno vuelve a enviar la conversación que aún está en contexto, cada lectura de archivo, resultado de herramienta e intercambio previo que no se haya compactado, como entrada facturada. Por lo tanto, el turno 50 transporta los turnos 1 al 49 como carga. El almacenamiento en caché de prompts sirve el prefijo repetido a una décima parte del precio de entrada base en la mayoría de los modelos (5% en Opus 5.5 y Sonnet 5.5, 2.5% en Fable 5.1), pero el prefijo sigue creciendo y cualquier periodo de inactividad que supere el TTL de la caché convierte el siguiente turno en una reescritura a precio completo. /compact reduce el historial; /clear lo restablece.

¿Cómo verifico mi uso de tokens y el costo en Claude?

En Claude Code, /usage muestra las estadísticas de tokens de la sesión, una estimación de costo local y barras de límite de plan en las suscripciones (/cost es un alias); /context muestra qué está llenando la ventana. Para obtener la facturación oficial de la API, utilice la página de uso en la Claude Console. En su propio código, lea response.usage; sumar input_tokens, cache_creation_input_tokens y cache_read_input_tokens proporciona el tamaño real del prompt. Realice estimaciones con antelación mediante el endpoint count_tokens, nunca con tiktoken.