Coste de Claude Code por subagente: dónde fueron $0.17

Una ejecución de Claude Code por un gateway: la primera llamada de cada uno de los tres agentes sumó el 72% de $0.17. Bastan dos variables de entorno.

11 de octubre de 2026

Claude Code muestra cuánto ha costado una sesión, pero no en qué parte se ha gastado el dinero. Cuando lo usa un equipo, tampoco permite saber a qué repositorio o desarrollador corresponde cada cargo. Pasar Claude Code por un gateway (un proxy entre Claude Code y el proveedor del modelo) resuelve ambas cosas sin plugins ni wrappers: el gateway ya ve todas las peticiones y Claude Code ya las identifica con un id de sesión y un id de agente. En esta guía ejecutamos una tarea pequeña a través del gateway de Synthorai y analizamos el resultado: $0.1728 por 11 peticiones, de los cuales el 72% corresponde a la primera llamada de cada uno de los tres agentes.

TL;DR

• Una ejecución de Claude Code con Claude Sonnet 5.5 y dos subagentes costó $0.1728 a través de un gateway, y $0.0812 al repetirla medio minuto después.
• Las escrituras en caché supusieron el 77% de la primera ejecución; la primera llamada de cada uno de los tres agentes, el 72%.
• Los dos subagentes representaron el 39% del coste de la sesión.
• Dos variables de entorno permiten pasar Claude Code por un gateway; una tercera identifica el tipo de cada subagente.

El código está en github.com/synthorai-io/use-cases, dentro de coding-agent-spend/. Necesitas Python 3.10 o posterior y el comando claude en la versión 2.1.280 o posterior, que es la que exige este modelo.

git clone https://github.com/synthorai-io/use-cases
cd use-cases
cp .env.example .env    # put your API key in it
cd coding-agent-spend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python run.py --hints --label repo=shipping --label _user=dev_1

El script inicia Claude Code sobre una copia de un pequeño repositorio de ejemplo con un test que falla. Configura la dirección del gateway y la clave solo en el entorno de ese proceso, con un directorio de configuración vacío, así que no lee ni modifica tu configuración de Claude Code. Cada ejecución tarda aproximadamente medio minuto. El script limita cada ejecución a $0.60 con --max-budget-usd y no inicia ninguna que pueda elevar el total por encima de $2.

Las cifras de esta página proceden de ejecuciones del 10 de octubre de 2026 con Claude Code 2.1.296 y Claude Sonnet 5.5.

¿Cómo se pasa Claude Code por un gateway?

Basta con definir dos variables de entorno. Claude Code usa la API Messages de Anthropic y el gateway ofrece esa misma API en su propia dirección:

export ANTHROPIC_BASE_URL="https://synthorai.io"   # no /v1: Claude Code adds /v1/messages itself
export ANTHROPIC_API_KEY="<your gateway key>"

No cambia nada más. La página de integración de Claude Code explica los detalles. A partir de ahí, todas las llamadas al modelo de todas las sesiones aparecen en el registro de peticiones del gateway, agrupadas en la consola.

¿Qué ve el gateway sin configurar nada más?

Ve la sesión, sus trazas, el cliente y cada subagente. Claude Code envía su propio id de sesión en todas las peticiones, de modo que una ejecución de claude corresponde a una sesión en la consola. La página de la sesión identifica el cliente como “Claude Code 2.1.296”. Las peticiones también muestran un id de traza en la consola, por lo que la sesión incluye sus trazas: en esta ejecución fueron dos, de 6 y 5 llamadas. La tabla “Agentes de esta sesión” ya separa las llamadas entre la conversación principal y una fila por subagente.

Un subagente es un segundo agente que Claude Code inicia para resolver una parte de la tarea, con sus propias instrucciones y su propio contexto. La tarea de la demo pide dos: el subagente integrado Explore para localizar una regla y un subagente personalizado, test-runner, para ejecutar los tests.

Por defecto, cada subagente aparece con un id como a05e467acd14b25e6. Eso permite saber que hubo dos, pero no cuál era cada uno. Una variable más lo resuelve:

export CLAUDE_CODE_GATEWAY_HINT_HEADERS=1

Con esta variable, la tabla identifica cada subagente por su tipo. Al abrir una llamada en Logs, se muestra su tipo (subagent:Explore) y una lista de “Herramientas anteriores a esta llamada” con el nombre y el tiempo de ejecución de cada herramienta, como Read 7 ms. El gateway conserva el tipo del agente, no el nombre que le hayas dado, así que test-runner aparece como custom. Se guardan los nombres de las herramientas y sus tiempos de ejecución, pero no lo que leyeron o escribieron.

¿Dónde fueron los $0.17?

Se repartieron entre tres agentes, sobre todo en la primera llamada de cada uno.

Los dos subagentes costaron $0.0676, el 39% de la sesión, para resolver las dos partes más pequeñas de la tarea: localizar una regla en una biblioteca con tres archivos de código fuente y ejecutar cinco tests. La corrección en sí fue de un solo carácter: cambiar > por >=.

La explicación está en los recuentos de tokens que Claude Code muestra al terminar:

claude-sonnet-5-5                20 in   158612 cache read   53058 cache write   2425 out  $0.1728

Con las tarifas del modelo ($2 por millón de tokens de entrada, $10 de salida, $0.10 de lectura de caché y $2.50 de escritura en caché), esas cuatro cifras se traducen en:

Las escrituras en caché suponen el 77% de la factura. La escritura se produce la primera vez que se envía un prefijo del prompt: cuesta 1.25 veces el precio de entrada. En este modelo, las peticiones posteriores lo leen por una vigésima parte del precio de entrada. El prompt de un agente de programación ya es largo antes de que escribas nada, porque incluye el prompt de sistema y la definición de todas las herramientas. Por eso su primera llamada es la más cara.

Cada agente empieza con su propio prompt, así que cada uno paga esa primera llamada:

Esas tres llamadas suman $0.1240, el 72% de la ejecución. Las siguientes son baratas: la segunda y la tercera llamada del subagente Explore leyeron de caché el 94% de la entrada y costaron $0.0052 y $0.0132.

El coste de arrancar un subagente con la caché fría compensa cuando evita cargar mucho contenido en el contexto de la conversación principal. Esa es la función de Explore en una base de código real. Para un trabajo de una o dos llamadas, hacerlo en la conversación principal evita otra escritura en caché. Este ejemplo usa un repositorio pequeño: revisa el desglose de tus propias sesiones antes de cambiar tu forma de trabajar.

¿Cuánto cuesta una segunda ejecución?

Cuesta aproximadamente la mitad si empieza mientras la caché sigue caliente. Repetimos la misma ejecución medio minuto después. Hizo las mismas 11 llamadas, leyó de caché el 93.1% de la entrada frente al 74.9% de la primera ejecución y costó $0.0812 frente a $0.1728. Sus tres primeras llamadas leyeron de caché el 82%, el 81% y el 71%, porque sus prompts iniciales ya estaban almacenados desde la ejecución anterior.

La caché de Anthropic conserva cada entrada durante cinco minutos por defecto y renueva ese plazo con cada lectura. Un desarrollador que trabaja de forma continuada en un repositorio paga principalmente la tarifa con caché caliente. Un trabajo programado que se ejecuta una vez por hora paga la de caché fría en cada ejecución.

¿Coincide el coste que muestra Claude Code con la factura?

En la versión 2.1.296 coincidió hasta el cuarto decimal: $0.1728 con caché fría y $0.0812 con caché caliente en ambos lados. Depende de la versión. Claude Code calcula el coste con su propia tabla de precios. En la versión 2.1.278, que aún ejecutaba este modelo el 8 de octubre, aplicaba $5 y $25 por millón de tokens de entrada y salida, mientras que la factura aplicaba $2 y $10. Por eso mostraba unas 2.7 veces el importe cobrado. Los recuentos de tokens coincidieron siempre en ambos lados.

Esto afecta a un ajuste concreto. --max-budget-usd detiene la ejecución cuando el cálculo de Claude Code alcanza el límite. Con la versión anterior, una ejecución se detenía al llegar a $0.60 según Claude Code, aunque el importe facturado era aproximadamente un tercio de esa cifra. Después de actualizar, compara una vez el importe con la página de la sesión. El límite del que dependas debe estar donde se contabiliza la factura: en el límite de gasto de la clave de API.

¿Cómo se reparte el gasto por desarrollador o repositorio?

Añade una etiqueta a cada petición. Claude Code puede enviarla mediante una variable que ya admite para cabeceras personalizadas:

export ANTHROPIC_CUSTOM_HEADERS='X-Synthorai-Metadata: {"repo":"shipping","_user":"dev_1"}'

X-Synthorai-Metadata es la cabecera del gateway para las etiquetas: un objeto JSON plano de hasta 10 cadenas cortas, donde _user identifica a la persona para la que se hizo la petición. Las opciones --label de la demo configuran exactamente esto, y la página de la sesión que aparece arriba muestra ambas etiquetas.

Configura la variable para cada desarrollador en su perfil de shell y para cada repositorio en el mecanismo que cargue las variables de entorno del proyecto. Así podrás usar dos vistas:

• En Traces, el buscador acepta metadata.repo = shipping y lista las sesiones de ese repositorio.
• En la pestaña Breakdown de Analytics, la tarjeta Cost by metadata suma las peticiones y el coste por cada valor de una clave. Así, repo da la factura por repositorio y _user, por desarrollador.

Esto funciona con una única clave compartida. Usar una clave por desarrollador permite el mismo reparto de la facturación y añade límites de gasto independientes, a cambio de gestionar más claves.

¿Cómo se consulta el coste de los agentes entre varias sesiones?

Usa la tarjeta Cost by agent de la pestaña Breakdown de Analytics. La página de la sesión desglosa una sola sesión. Esta tarjeta suma todas las sesiones del intervalo por tipo de agente:

Explore × 2 y custom × 2 corresponden a las ejecuciones con caché fría y caliente anteriores: un total por tipo de agente para ambas sesiones. La columna Share indica qué proporción del gasto total del intervalo representa cada fila; ese intervalo también incluía otras sesiones. Sin la variable de información adicional, los subagentes de una ejecución no comunican su tipo y se agrupan en una fila llamada “Subagente”. Un agente de tu propio programa que establezca X-Agent-Id, como el de Seguir las trazas de un agente LLM, aparece en una fila con el nombre que haya enviado.

Con una semana de sesiones de un equipo, esta vista permite saber si los subagentes representan una parte pequeña o grande de la factura, y de qué tipo son.

¿Qué no ofrece esta configuración?

No ofrece ids de span, nombres de agentes personalizados, un atajo para aislar la ejecución ni una vista del trabajo realizado.

• Sin ids de span. Las peticiones de Claude Code 2.1.296 muestran un id de sesión y un id de traza, pero no un id de span, así que el campo de span de una llamada indica “no enviado”. Las unidades disponibles son la sesión, sus trazas y sus agentes.
• Sin nombres de agentes personalizados. Todos los subagentes personalizados aparecen como custom. Si ejecutas varios tipos y necesitas distinguirlos, el id de agente de la página de la sesión es la única referencia.
• Sin atajo para aislar la ejecución. --bare parece la forma de ejecutar Claude Code sin tus plugins ni ajustes. También desactiva los subagentes, por lo que la sesión tiene un único agente y no hay nada que desglosar. La demo aísla la ejecución con un CLAUDE_CONFIG_DIR vacío.
• Sin vista del trabajo realizado. El gateway registra las llamadas al modelo, los nombres de las herramientas y los tiempos de ejecución. No registra el contenido de los archivos, los diffs ni la salida de los comandos.

Preguntas frecuentes

¿Cuánto cuesta una sesión de Claude Code?

Depende del modelo, del tamaño del repositorio, del número de agentes que intervengan y de si la caché está caliente. La ejecución de esta página, con 11 peticiones a Claude Sonnet 5.5 para corregir un bug de un carácter con dos subagentes, costó $0.1728 con caché fría y $0.0812 al repetirla medio minuto después.

¿Cómo controlo los costes de Claude Code en un equipo?

Configura el Claude Code de cada desarrollador para usar un gateway mediante ANTHROPIC_BASE_URL y añade etiquetas del desarrollador y del repositorio con ANTHROPIC_CUSTOM_HEADERS. El gateway suma los costes por sesión, por valor de etiqueta y por tipo de agente, sin instalar nada en Claude Code.

¿Los subagentes de Claude Code cuestan más?

Cada subagente empieza con su propio prompt y paga su propia escritura en caché. En la demo con Claude Sonnet 5.5, la primera llamada del subagente Explore costó $0.0391 y las dos siguientes, $0.0052 y $0.0132. Los dos subagentes juntos representaron el 39% de la sesión. Ese coste permite disponer de un contexto separado, que compensa en exploraciones amplias, pero no en trabajos de una sola llamada.

¿Es preciso el coste que muestra Claude Code?

Compruébalo una vez por versión. Claude Code 2.1.296 mostró los mismos $0.1728 que se facturaron. Claude Code 2.1.278 aplicaba a Claude Sonnet 5.5 unas tarifas de $5 y $25 por millón de tokens, frente a los $2 y $10 de la factura, y mostraba unas 2.7 veces el importe facturado. Los recuentos de tokens coincidieron en ambas versiones.

¿Qué hace CLAUDE_CODE_GATEWAY_HINT_HEADERS?

Hace que Claude Code envíe tres datos adicionales con cada petición: el tipo de agente, el tipo de llamada y los nombres y tiempos de ejecución de las herramientas ejecutadas antes de ella. Sin esta variable, el gateway sigue viendo la sesión y cada subagente, pero solo por su id.

Lecturas relacionadas

• Seguir las trazas de un agente LLM: las mismas vistas de la consola para un agente que desarrolles tú.
• ¿Por qué cuesta tanto mi agente LLM?: fallos de caché, crecimiento del contexto y bucles de reintentos, reproducidos y corregidos.
• ¿Por qué es lento mi agente LLM? y Depurar un agente LLM: cómo usar las mismas vistas para analizar la latencia y los fallos.
• Pregunta a Claude sobre tus registros de LLM: preguntas sobre sesiones como estas, respondidas a través del servidor MCP del gateway.
• Dale a tu agente herramientas para consultar registros: cómo leer el mismo registro desde tu propio programa y cuánto cuestan los tokens del modelo.
• Integración de Claude Code: las dos variables y los nombres de los modelos.
• Referencia de cabeceras de petición: qué cabeceras de Claude Code y de otros agentes lee el gateway.

← Casos de uso