Caché de prompts en agentes de código: coste y fallos

Cada paso de una sesión de agente genera una petición a la API: tus mensajes y las respuestas de herramientas que el agente devuelve. El modelo no conserva memoria entre peticiones, así que se reenvían el prompt de sistema, las definiciones de herramientas, las instrucciones del proyecto y el historial. Casi todo coincide con la petición anterior; la caché evita procesarlo desde cero.

Claude Code gestiona la caché automáticamente. En la API, cache_control permite activarla. Los modelos de OpenAI que usa Codex CLI también reconocen prefijos repetidos, aunque tienen precios y duraciones propios. Las cifras siguientes corresponden a Claude.

Un prefijo exacto y un orden fijo

La caché compara el principio de la petición con lo procesado recientemente. La coincidencia debe ser exacta: cambiar un carácter invalida todo lo posterior. No existe una caché independiente por archivo o sección.

El orden es definiciones de herramientas, prompt de sistema y mensajes. Un cambio invalida su nivel y los siguientes. Si editas un mensaje, las herramientas y el sistema pueden seguir cacheados; si cambia una herramienta, ya no.

Claude Code coloca primero lo que cambia poco: sus instrucciones y herramientas, luego CLAUDE.md, memoria y reglas, y por último la conversación. En un turno normal, la petición anterior forma el prefijo y solo el intercambio nuevo se añade al final.

Cuánto cuestan la escritura y la lectura

La caché cambia el precio de la entrada, no el de la respuesta. A septiembre de 2026, Anthropic cobra una escritura de cinco minutos a 1,25 veces la entrada normal y una de una hora al doble. La lectura cuesta una décima parte, salvo en Fable 5.1, que cobra 0,025, y Opus 5.5, que cobra 0,05. Lo situado después del último punto cacheado se cobra como entrada corriente.

Con 100.000 tokens en Sonnet 5, a 2 dólares por millón de entrada en septiembre de 2026, leer de la caché cuesta 0,02 dólares por petición. Sin caché cuesta 0,20. Reescribir tras un fallo cuesta 0,25 con cinco minutos o 0,40 con una hora: la escritura supera el precio de entrada sin caché.

En la mayoría de modelos, escribir durante cinco minutos cuesta 12,5 veces una lectura; en Opus 5.5, 25 veces, y en Fable 5.1, 50. La escritura de cinco minutos se amortiza con una lectura; la de una hora necesita dos.

Cinco minutos o una hora

El TTL es el tiempo que un prefijo permanece guardado sin uso. Cada lectura reinicia el reloj sin coste adicional. Este empieza cuando comienza la petición, no cuando termina la respuesta: si la respuesta tarda cuatro minutos en llegar, queda aproximadamente uno para reutilizar una caché de cinco minutos.

A septiembre de 2026, Claude Code usa una hora para la conversación principal dentro del uso incluido de una suscripción Claude y cinco minutos con clave de API, proveedor en la nube o créditos. Los subagentes usan cinco minutos por defecto.

promptCacheTtl o la variable CLAUDE_CODE_PROMPT_CACHE_TTL permiten elegir 5m o 1h desde Claude Code v2.1.242. La hora compensa cuando hay pausas de cinco a sesenta minutos, como una reunión o una compilación larga. Si las peticiones nunca se separan más de cinco minutos, solo encarece las escrituras.

$claude -p "hello" --output-format json

Qué rompe la caché sin avisar

Un fallo de caché no produce error. La petición tarda más y el informe muestra una escritura grande donde esperabas una lectura. Las causas habituales son:

• →Cambiar de modelo. Cada uno tiene su caché. /model a mitad de tarea obliga a releer el historial; también puede ocurrir con una skill que elige modelo o con opusplan.
• →Cambiar el esfuerzo. En la mayoría de modelos, cada nivel tiene caché propia. Opus 5.5 y Fable 5.1 la conservan al cambiarlo, a septiembre de 2026.
• →Cambiar herramientas. Sus definiciones van primero. Claude Code aplaza las de MCP por defecto, pero si se cargan por adelantado, por ejemplo tras una pasarela ANTHROPIC_BASE_URL, una desconexión puede invalidar el prefijo.
• →Cambiar algo al principio del prompt. Una marca de tiempo en el sistema invalida lo posterior en cada petición. Una actualización de Claude Code también suele cambiar sus instrucciones.
• →Dejar pasar la duración: cinco minutos por defecto con API, una hora con suscripción incluida.

Por qué cuesta más volver tras una pausa

El fallo se paga en la siguiente petición: se procesa el prefijo completo y se escribe de nuevo a tarifa de escritura. Las posteriores vuelven a leerlo. Por eso el primer mensaje tras un descanso puede ser lento y caro aunque solo tenga una línea.

Compactar mientras la caché sigue activa permite leer el historial a precio reducido para resumirlo. Tras una pausa larga, ese mismo resumen relee todo sin caché; compactar inmediatamente después de retomar una sesión es el caso más caro.

Conviene fijar modelo y esfuerzo al comenzar, terminar una tarea antes de parar y usar /clear al cambiar de tema. /rewind elimina un camino equivocado y vuelve a un prefijo anterior. En Pro y Max, Claude Code puede ofrecer reanudar una sesión grande desde un resumen tras una pausa larga.

Cómo leer la tasa de acierto

La API informa de tres cifras: cache_read_input_tokens para lecturas, cache_creation_input_tokens para escrituras e input_tokens para la entrada posterior al último punto de caché. El total es la suma de las tres, no solo input_tokens.

La tasa de acierto son las lecturas divididas por el total. En sesiones largas y activas debería dominar la lectura. Una tasa baja es normal en sesiones cortas, donde la primera escritura pesa mucho; en una larga, escrituras grandes repetidas indican un problema en el prefijo.

$/usage

Desde v2.1.260 también puede señalar la causa del último fallo, como un cambio de herramientas. La cifra corresponde solo a la conversación principal: un subagente tiene instrucciones y caché propias. En la API, la página Usage de la Console muestra lecturas; el diagnóstico de caché, en beta a septiembre de 2026, muestra dónde divergen dos peticiones.

Suscripción o API: quién paga el fallo

Con clave de API, un fallo consume dinero según la tabla y puede reducir el margen del límite de tokens de entrada por minuto. En la mayoría de modelos Claude, las lecturas de caché no cuentan para ese límite; escrituras y entrada nueva sí.

Con Pro o Max no hay factura por token. El importe en dólares de /usage es una estimación a precios de API. El fallo consume cuota del plan; la documentación de Claude Code lo cita como causa de un consumo inesperado en sesiones largas. En Pro, Max, Team y Enterprise, /usage destaca los fallos cuando llegan a una décima parte del uso reciente.

Un token cacheado sigue siendo un token

Aunque cueste una décima parte, el contexto entero se relee en cada petición. Una pregunta de una línea al final del día sigue arrastrando toda la conversación. Mantén estable el principio del prompt para aprovechar la caché y pequeño el contexto para abaratar tanto lecturas como fallos.

capsul usa la CLI del agente en la que ya has iniciado sesión y envía lo que pide la tarea bajo el presupuesto de tokens que fijas. Se detiene en ese límite e informa de lo que dejó fuera. La página del banco de pruebas publica el efecto medido por modelo junto con las comprobaciones de respuesta.