Tu caché de 5 minutos no dura 5 minutos: qué arregla realmente promptCacheTtl
Claude Code 2.1.243 shipeó el setting que un usuario pidió el 18 de mayo. Si te ahorra plata o no depende de un número que el changelog no menciona.
El 25 de agosto de 2026 el changelog de Claude Code trajo esta línea:
“Added
promptCacheTtlandsubagentPromptCacheTtlsettings so API-key and cloud-provider users can keep a 1-hour prompt cache on the main conversation while subagents stay at 5 minutes”
Dos settings, una línea cada uno en settings.json. La tentación es pegar "promptCacheTtl": "1h" y seguir de largo — y para buena parte de los lectores eso sería o redundante o un aumento de precio chico y silencioso.
La cláusula que decide cuál de los dos casos eres es justamente la que la mayoría de la cobertura recorta: API-key and cloud-provider users. Antes de llegar a la configuración hay que tener tres cosas claras: quién ya tenía esto por default, cuánto cuesta realmente la hora, y por qué cinco minutos en Claude Code no son cinco minutos.
Si la mecánica de facturación por token no te resulta familiar, Qué son los tokens en la IA y por qué te cobran por ellos explica la base sobre la que descansa todo lo que sigue: por qué se paga la conversación entera en cada turno, y por qué el caché es la palanca que existe para no pagarla dos veces.
Primero: fíjate si ya lo tienes
La documentación de prompt caching publica el TTL por default de cada request que hace Claude Code, dividido en dos buckets. La conversación principal son tus turnos interactivos, las corridas con -p y los turnos del Agent SDK. Todo lo demás son subagentes, workflows, teammates in-process, forks, compaction y títulos de sesión — un bucket bastante más amplio de lo que sugiere la palabra “subagentes”.
| Bucket de requests | Suscripción Claude, dentro del uso incluido | Usage credits, API key o cloud provider |
|---|---|---|
| Conversación principal | Una hora | Cinco minutos |
| Todo lo demás | Cinco minutos (salvo los helper requests que controla el servidor, que reciben una hora) | Cinco minutos |
Vuelve a leer la columna izquierda. En un plan Pro, Max, Team o Enterprise, dentro de tu uso incluido, la conversación principal ya está en el caché de una hora y los subagentes ya están en cinco minutos. El arreglo exacto que describe el changelog es tu default actual. Poner promptCacheTtl en 1h ahí no cambia nada.
El setting sí importa si estás en alguna de estas situaciones:
- Entras con una API key.
- Corres sobre Amazon Bedrock, Google Cloud’s Agent Platform o Microsoft Foundry.
- Estás en una suscripción y te pasaste del límite de tu plan hacia usage credits. Este es el caso que se pasa por alto: en cuanto Claude Code empieza a consumir créditos, se te factura por token, así que baja la conversación principal al TTL de cinco minutos por su cuenta. Si quieres recuperar la hora mientras gastas créditos, ahora tienes que pedirla.
Dos salvedades de disponibilidad antes de planificar con esto: el TTL de una hora no está disponible a través del Claude apps gateway, y en Amazon Bedrock el soporte de caching, el largo mínimo del prefijo cacheable y la disponibilidad de la hora varían según el modelo.
Segundo: la hora no es gratis
Acá es donde “ahorro de tokens medible” necesita una corrección. El caché de una hora es un tier de precio distinto, no una optimización. Según las reglas de precios de la API de Claude:
- Cache read: 0.1× el precio base de input
- Cache write, TTL de 5 minutos: 1.25× el precio base de input
- Cache write, TTL de 1 hora: 2× el precio base de input
O sea que pagas un 60% de sobreprecio en cada cache write a cambio de una ventana doce veces más larga. La documentación de Claude Code es directa sobre el caso en que sale mal: la hora “costs more on short bursts of work that never idle past five minutes, where the higher write rate applies and the longer cache lifetime goes unused” — cuesta más en ráfagas cortas de trabajo que nunca quedan inactivas más de cinco minutos, donde se aplica la tarifa de escritura más alta y la vida útil más larga no se usa.
Haz la cuenta sobre un contexto de 200k tokens al precio de lista de Sonnet 5, US$2 por millón de tokens de input:
| Operación | Tarifa | Costo por 200k tokens |
|---|---|---|
| Cache read (hit) | $0.20 / Mtok | $0.04 |
| Cache write, 5m | $2.50 / Mtok | $0.50 |
| Cache write, 1h | $4.00 / Mtok | $0.80 |
Elegir la hora te cuesta $0.30 extra en la escritura. Un solo cache miss que evites — un turno que habría reescrito 200k tokens a $0.50 en vez de leerlos a $0.04 — te ahorra $0.46. El break-even es un único hueco de inactividad por hora. Por debajo de eso estás pagando el sobreprecio en vano; por encima, el setting se paga solo y sigue pagándose, porque la entrada de una hora se refresca sin costo adicional cada vez que se lee.
Ese es el encuadre honesto: promptCacheTtl: 1h es una apuesta a que te levantas de la terminal. Si te sientas dos horas en flow ininterrumpido, no la tomes.
Tercero: cinco minutos son menos de lo que crees
Acá está el detalle que no está en el changelog, no está en la documentación de Claude Code, y reencuadra todo el setting. De la referencia de prompt caching de la API:
“The lifetime is measured from the start of the request that writes or reads the cache entry, not from the end of its response. Time spent generating a response counts against the lifetime: if a response takes 4 minutes to stream, a follow-up request that reuses the same cached prefix must start within about 1 minute of that response completing.”
Es decir: la vida útil se mide desde el inicio del request que escribe o lee la entrada, no desde el final de su respuesta. El tiempo que tarda en generarse la respuesta se descuenta de la vida útil — si una respuesta tarda 4 minutos en streamear, el request siguiente que reutilice ese prefijo cacheado tiene que arrancar dentro del minuto posterior a que esa respuesta termine.
Piensa en lo que es realmente un turno de Claude Code. Extended thinking, la lectura de un archivo, tres ediciones, una corrida de tests, un resumen. Los turnos agénticos streamean durante minutos con toda naturalidad. Cada uno de esos minutos sale de tu presupuesto de cinco — el reloj arrancó cuando salió el request, no cuando terminó de imprimirse la respuesta.
La consecuencia práctica: con un TTL de cinco minutos, un turno agéntico largo puede dejarte menos de un minuto para leer el resultado, pensar y escribir tu mensaje siguiente antes de que todo el prefijo expire. Ese es el mecanismo detrás de la queja que originó esta feature, y explica por qué el mismo setting importa muchísimo menos en una app de chat, donde las respuestas tardan segundos.
El pedido que tardó tres meses
promptCacheTtl no es un nombre que inventó Anthropic. Es el nombre que propuso un usuario.
El issue #60316, “Expose cache_control.ttl (5m / 1h) as a user-configurable setting”, lo abrió el 18 de mayo de 2026 OniLorenz-TomTom, corriendo Claude Code 2.1.133 sobre Ubuntu 24.04. El pedido apuntaba a exactamente dos cosas: una key de settings.json escrita "promptCacheTtl": "1h", o un flag de CLI. La key que shipeó el 25 de agosto lleva el nombre del issue, carácter por carácter. El issue sigue abierto.
La sección de motivación es la evidencia de costo más fuerte de esta historia, y conviene etiquetarla con claridad: son números auto-reportados por un usuario sobre sus propias sesiones, no un benchmark. Reporta que cuando una pausa entre turnos superaba los cinco minutos, sus tokens de cache_create saltaban aproximadamente 15× — de unos 10k a unos 154k — y que eso le pasaba entre 10 y 20 veces por sesión en días cargados de thinking, costándole alrededor de US$25 por día por sesión activa solo en cache misses. Su cálculo de break-even: por encima del 24% de reuso de caché dentro de la hora, el tier de una hora sale matemáticamente más barato.
Toma la cifra en dólares como la experiencia de un desarrollador con un workload. Toma la forma — el salto de 15×, la frecuencia, el umbral de break-even — como la razón por la que el setting existe.
La configuración
Ambos settings aceptan exactamente dos valores, 5m y 1h. Claude Code ignora cualquier otra cosa.
{
"promptCacheTtl": "1h",
"subagentPromptCacheTtl": "5m"
}
Ese es el arreglo de la línea del changelog: la hora donde vive tu conversación, cinco minutos para todo lo que se levanta y muere. Va en cualquier archivo de settings — ~/.claude/settings.json para todos tus proyectos, .claude/settings.json para compartir con tu equipo, .claude/settings.local.json para ti solo acá.
Hay environment variables para ambos buckets, que el changelog no menciona:
export CLAUDE_CODE_PROMPT_CACHE_TTL=1h
export CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=5m
Y cuando aplican varios controles a la vez, Claude Code toma la primera coincidencia en este orden:
FORCE_PROMPT_CACHING_5M=1— fuerza cinco minutos en ambos buckets- La environment variable del bucket
- El setting del bucket
ENABLE_PROMPT_CACHING_1H=1— pide una hora para ambos buckets- El default de ese bucket
FORCE_PROMPT_CACHING_5M=1 es el que conviene recordar. La documentación lo recomienda para debuggear el comportamiento del caché o comparar los dos tiers — y, notablemente, para sobrescribir un TTL más largo puesto en managed settings. Si tu organización despliega la hora para toda la flota y quieres medir qué le está haciendo a tu propia cuenta, esa es la salida de emergencia.
Para verificar que algo de esto está funcionando, mira dos campos que la API devuelve en cada respuesta: cache_creation_input_tokens y cache_read_input_tokens. Una relación alta de lecturas sobre creaciones significa que el caching está haciendo su trabajo. Si la creación se mantiene alta turno tras turno, hay algo en tu prefijo que sigue cambiando — y el TTL no es tu problema.
Los otros dos settings del mismo release, y un hueco honesto
La misma entrada del changelog trajo un desglose de Loops en /usage: una fila por cada /loop o scheduled task pesado, ordenadas por tokens totales, con cada cuánto se dispara, cuántas veces corrió, tokens totales y por run, y cuándo corrió por última vez. Las filas se indexan por el prompt de la tarea, así que un loop que detienes y vuelves a crear sigue siendo una sola fila. Si tienes automatización corriendo contra tu cuenta, este es el primer lugar donde Claude Code te va a mostrar qué tarea se está comiendo el presupuesto.
Después está modelPricing, descrito en el changelog como un managed setting que hace que /cost, la status line y la telemetría usen las tarifas por modelo contratadas por tu organización y su multiplicador de descuento en lugar del precio de lista. Para un equipo en Iberoamérica que paga una factura de API en USD contra un contrato negociado, esa es la diferencia entre una estimación y un número que puedes poner en un reporte.
Todavía no podemos decirte cómo configurarlo. Una búsqueda literal de modelPricing devuelve ABSENT en la settings reference, ABSENT en la página de managed settings y ABSENT en la página de costos — que además sigue documentando el comportamiento viejo, diciendo que /usage calcula los tokens “at standard list rates, so it doesn’t reflect promotional pricing or contracted discounts”. El string sí está presente en el binario shipeado. La documentación simplemente no se puso al día. Si eres admin y estás planificando alrededor de esto, espera a que la settings reference publique la forma en vez de adivinar el JSON.
Una discrepancia más que conviene conocer, porque va a confundir a cualquiera que verifique compatibilidad: el changelog archiva las tres features bajo 2.1.243, mientras que la documentación tanto de los settings de TTL como del desglose de Loops dice que requieren v2.1.242 o posterior.
Qué hacer concretamente
Hoy. Corre claude --version. Si estás por debajo de 2.1.243, actualiza — pero no te quedes ahí. 2.1.245 y 2.1.246 shipearon el mismo día, y 2.1.245 arregla un crash de arranque en distribuciones que corren glibc 2.44, lo que incluye Arch, CachyOS y Fedora Rawhide. 2.1.246 es la versión en la que conviene estar.
Esta semana. Determina en qué columna de esa tabla de defaults estás. En una suscripción dentro de tu uso incluido ya tienes el arreglo y no hay nada que configurar — pero anota el momento en que cruzas hacia usage credits, porque ahí tu conversación principal baja a cinco minutos en silencio. Con API key o un cloud provider, pon promptCacheTtl en 1h y deja subagentPromptCacheTtl como está; los subagentes arrancan su propia conversación con su propio prefijo y rara vez viven lo suficiente como para aprovechar la hora.
Antes de commitear el setting al settings.json de tu equipo. Mide. Observa cache_creation_input_tokens unos días con tu ritmo normal de trabajo, y sé honesto sobre si tus sesiones se quedan inactivas más de cinco minutos o trabajas en ráfagas sin cortes. Si es lo segundo, la hora es un sobreprecio del 60% en escrituras que no te compra nada. FORCE_PROMPT_CACHING_5M=1 te da una comparación limpia.
El setting es una línea. Saber si lo quieres toma una semana de mirar tus propios números — que es exactamente el tipo de cosa que el desglose de Loops y modelPricing están para hacer visible, en cuanto la documentación nos deje usarlos.
¿En qué columna de esa tabla estás, y ya mediste cuántas veces por sesión se te vence el caché? Cuéntame en los comentarios.