El TTL de caché en Claude Code es una hora en la conversación principal solo si tienes suscripción y estás dentro del uso incluido del plan; con créditos de uso, clave de API o proveedor de nube son cinco minutos. Desde la versión 2.1.242 lo eliges tú con los ajustes promptCacheTtl y subagentPromptCacheTtl, que aceptan 5m o 1h.
Claude Code decide por ti cuánto vive tu caché de prompts, y esa decisión cambia según cómo se esté facturando tu uso. Desde la versión 2.1.242 puedes tomar tú la decisión con una línea. Esta guía es para saber en qué situación estás ahora y para decidir si te conviene cambiarla, que no siempre es que sí.
Qué es el TTL de caché y por qué te lo asignan
El TTL (time to live) es cuánto sobrevive tu contexto ya procesado en el servidor cuando dejas de escribir. Mientras siga vivo, el siguiente mensaje no reprocesa toda la conversación y se cobra a tarifa de caché. Cada petición que acierta reinicia el reloj.
La API ofrece dos TTL: cinco minutos y una hora. Claude Code elige uno por petición y reparte todas tus peticiones en dos cubos:
Conversación principal: tus turnos interactivos, las corridas no interactivas con `-p`, los turnos del Agent SDK y los auxiliares que corren en línea con ellos.
Todo lo demás: subagentes, workflows, teammates en proceso, forks, compactación y títulos de sesión.
Con suscripción y dentro del uso incluido de tu plan, la conversación principal recibe una hora. Con créditos de uso, clave de API o proveedor de nube, recibe cinco minutos. El cubo de "todo lo demás" recibe cinco minutos en los dos casos, salvo unas peticiones auxiliares que Anthropic controla en el servidor y que sí reciben una hora.
Cómo saber en qué cubo estás
Tres comprobaciones, de la más barata a la más lenta.
Mira cómo entras. Si usas clave de API, Amazon Bedrock, Google Cloud o Microsoft Foundry, tu conversación principal está en cinco minutos por defecto. Sin excepciones ni matices.
Mira si ya pasaste el límite del plan. Con suscripción tienes una hora solo mientras estés dentro del uso incluido. En el momento en que Claude Code empieza a tirar de créditos de uso, la conversación principal baja a cinco minutos porque ese consumo ya se te está facturando.
Mira `/usage`. En los planes de pago, el desglose marca los comportamientos que se llevan el diez por ciento o más de tu consumo reciente, y "cache misses" es uno de ellos. Si ese aviso te aparece, estás pagando reprocesos de contexto completo.
Una prueba manual que tarda diez minutos: mira tu consumo, deja la sesión quieta diez minutos (más de cinco y menos de sesenta), vuelve y escribe algo corto. Si ese mensaje minúsculo cuesta como empezar la sesión de nuevo, estabas en el reloj de cinco minutos.
Cómo elegir el TTL paso a paso
Abre `~/.claude/settings.json`.
Añade `promptCacheTtl` con el valor `1h` para la conversación principal.
Si además quieres cubrir subagentes, workflows y compactación, añade `subagentPromptCacheTtl` con el mismo valor.
Reinicia Claude Code.
Los dos ajustes aceptan exactamente dos valores: `5m` y `1h`. Cualquier otra cosa la ignora, en silencio y sin error.
Si prefieres no tocar el archivo, existen las dos variables de entorno equivalentes: `CLAUDE_CODE_PROMPT_CACHE_TTL` para la conversación principal y `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` para el resto. Son cuatro nombres en total, dos por cubo, porque cada cubo se configura aparte.
Cuando hay varios controles en juego, Claude Code aplica el primero que encaje en este orden: `FORCE_PROMPT_CACHING_5M=1` (fuerza cinco minutos en los dos cubos), la variable de entorno del cubo, el ajuste del cubo, `ENABLE_PROMPT_CACHING_1H=1` (pide una hora para los dos) y, por último, el valor por defecto del cubo.
Cuándo NO te conviene la hora
Este es el punto que la mayoría se salta. El TTL de una hora mantiene la caché caliente durante pausas largas, pero cobra más cara cada escritura de caché. La documentación lo dice con todas las letras: sale más caro en ráfagas cortas de trabajo que nunca superan los cinco minutos de inactividad, porque pagas el recargo de escritura y la vida extra no se usa.
Regla práctica: activa `1h` si dejas la sesión abierta y te alejas (reuniones, revisiones, sesiones largas de lectura). Déjalo en `5m` si tu patrón es entrar, disparar veinte minutos seguidos y cerrar.
Y si dudas, hay una tercera vía: ponlo solo en la conversación principal, que es la que se queda abierta, y deja el otro cubo en el valor por defecto.
Qué puede salir mal
Versión vieja. Los dos ajustes y las dos variables piden Claude Code 2.1.242 o superior. En versiones anteriores no existen.
Valor inválido. `30m`, `60m` o `3600` se ignoran sin aviso; te queda el valor por defecto y la sensación de haberlo configurado.
Confundirlo con el límite de sesión. El TTL decide cuánto cuesta volver tras una pausa. El límite decide cuándo te quedas sin turnos. Son cosas distintas.
Claude apps gateway. Ahí el TTL de una hora no está disponible.
Amazon Bedrock. El soporte de caché, la longitud mínima de prefijo y la disponibilidad del TTL de una hora varían por modelo. Si tus contadores de tokens en caché se quedan en cero, es el primer sitio donde mirar.
Cambios que invalidan la caché igual. Cambiar de modelo, cambiar el nivel de esfuerzo o compactar reinician el prefijo. Ningún TTL te protege de eso.
Preguntas frecuentes
¿Dónde se pone promptCacheTtl?
En el archivo de ajustes de Claude Code, normalmente ~/.claude/settings.json para tu usuario. Es una clave más del objeto de ajustes y acepta solo dos valores, 5m o 1h. También existe la variable de entorno CLAUDE_CODE_PROMPT_CACHE_TTL si prefieres no tocar el archivo, por ejemplo en un contenedor o en varias máquinas.
¿Qué diferencia hay entre promptCacheTtl y subagentPromptCacheTtl?
Cada uno configura un cubo distinto. promptCacheTtl controla la conversación principal, es decir tus turnos interactivos, las corridas con -p y los turnos del Agent SDK. subagentPromptCacheTtl controla todo lo demás: subagentes, workflows, forks, compactación y títulos de sesión. Configurar uno no afecta al otro.
¿Cómo compruebo si estoy perdiendo dinero por cache misses?
En los planes de pago, el desglose de /usage marca los comportamientos que representan el diez por ciento o más de tu consumo reciente, y los fallos de caché aparecen como uno de esos avisos. También puedes probarlo a mano: deja la sesión quieta diez minutos, escribe algo corto y compara el consumo antes y después.
¿Qué pasa si escribo un valor distinto de 5m o 1h?
Claude Code lo ignora sin dar error ni advertencia y se queda con el valor que le corresponda por defecto. Es la trampa más común de este ajuste, porque el archivo queda escrito y parece configurado. Solo hay dos valores válidos y hay que escribirlos exactamente así, 5m o 1h.