SpyBara
Go Premium

prompt-caching.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 146 additions and 44 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Mon 14 22:58 Fri 18 23:58 Tue 22 23:59 Wed 23 23:57 Fri 25 23:58

Cómo Claude Code utiliza el almacenamiento en caché de prompts

Claude Code gestiona automáticamente el almacenamiento en caché de prompts. Vea por qué un cambio de modelo desencadena un turno lento sin caché, qué cuesta /compact, por qué las ediciones de CLAUDE.md no se aplican a mitad de sesión, y cómo verificar su tasa de aciertos de caché.

El almacenamiento en caché de prompts hace que Claude Code sea más rápido y eficiente en costos. Sin almacenamiento en caché, la API reprocesaría su historial completo en cada turno. Con almacenamiento en caché, reutiliza lo que ya procesó, factura la relectura a la tasa de token en caché, y solo procesa completamente lo que cambió.

Claude Code gestiona el almacenamiento en caché de prompts automáticamente, a menos que lo desactive. Aún es útil saber cómo funciona el almacenamiento en caché de prompts, porque algunas acciones invalidan el caché y hacen que la siguiente respuesta sea más lenta y costosa mientras se reconstruye. Esta página cubre qué acciones son esas, por qué algunos ajustes esperan un reinicio para aplicarse, y cómo verificar el rendimiento del caché cuando el uso parece alto.

Cómo se organiza el caché

Cada vez que envía un mensaje en Claude Code, realiza una nueva solicitud de API. El modelo no recuerda nada entre solicitudes, por lo que Claude Code reenvía el contexto completo: el prompt del sistema, el contexto de su proyecto, cada mensaje anterior y resultado de herramienta, y su nuevo mensaje. El contenido nuevo se añade al final, lo que significa que la mayoría de cada solicitud es idéntica a la anterior. El almacenamiento en caché de prompts es cómo la API evita reprocesar la parte que no cambió.

La API almacena en caché haciendo coincidir el inicio de cada solicitud, llamado el prefijo, con el contenido que procesó recientemente. En un turno normal, el prefijo es la solicitud anterior completa y solo el intercambio más reciente es nuevo. La coincidencia es exacta, por lo que un cambio en cualquier lugar del prefijo recalcula todo después de él. No hay almacenamiento en caché por archivo o por segmento. Vea cómo funciona el almacenamiento en caché de prompts en la referencia de API para el mecanismo subyacente.

Cuatro turnos mostrados como barras horizontales crecientes. La solicitud de cada turno contiene todo del turno anterior más el intercambio más reciente añadido al final. En los turnos dos y tres, el prefijo sin cambios se lee del caché y solo se procesa el nuevo intercambio. En el turno cuatro, el prompt del sistema cambió, por lo que el prefijo ya no coincide y toda la solicitud se reprocesa y se escribe. Cuatro turnos mostrados como barras horizontales crecientes. La solicitud de cada turno contiene todo del turno anterior más el intercambio más reciente añadido al final. En los turnos dos y tres, el prefijo sin cambios se lee del caché y solo se procesa el nuevo intercambio. En el turno cuatro, el prompt del sistema cambió, por lo que el prefijo ya no coincide y toda la solicitud se reprocesa y se escribe.

Para aprovechar al máximo la coincidencia de prefijos, Claude Code ordena cada solicitud para que el contenido que rara vez cambia entre turnos venga primero:

Capa Contenido Cambia cuando
Prompt del sistema Instrucciones principales, definiciones de herramientas, estilo de salida El conjunto de definiciones de herramientas cargadas cambia, o Claude Code se actualiza
Contexto del proyecto CLAUDE.md, memoria automática, reglas sin alcance La sesión comienza, o después de /clear o /compact
Conversación Sus mensajes, respuestas de Claude, resultados de herramientas Cada turno

Un cambio en la capa de conversación deja el prompt del sistema y el contexto del proyecto en caché. Un cambio en el prompt del sistema invalida todo, porque todo el contenido posterior ahora se encuentra detrás de un prefijo diferente. La tercera columna proporciona desencadenantes comunes en lugar de una lista exhaustiva, y las secciones a continuación cubren el conjunto completo.

La regla de coincidencia de prefijos explica la mayoría de los comportamientos en esta página. Plan Mode y skill loading, por ejemplo, añaden sus instrucciones como mensajes de conversación, por lo que el prefijo en caché permanece intacto.

Dos ajustes no aparecen en la tabla de capas pero aún afectan lo que permanece en caché:

  • Model: cada modelo tiene su propio caché. Cambiar de modelo recalcula toda la solicitud incluso cuando el contenido es idéntico. Vea Cambiar de modelo a continuación.
  • Effort level: en la mayoría de los modelos, cada nivel de esfuerzo tiene su propio caché, por lo que cambiar el esfuerzo a mitad de sesión recalcula toda la solicitud. En Fable 5.1 con una clave de API o una suscripción de Claude, el caché permanece intacto de forma predeterminada. Vea Cambiar nivel de esfuerzo a continuación.

Dónde vive el caché

El almacenamiento en caché ocurre del lado del servidor, en cualquier infraestructura que sirva su modelo. Dónde es eso depende de cómo se autentique:

  • Clave de API, suscripción de Claude, o Claude Platform on AWS: el caché vive en la infraestructura de Anthropic, accedido a través de la Claude API
  • Amazon Bedrock o Google Cloud's Agent Platform: el caché vive en la infraestructura de servicio de su proveedor de nube
  • Microsoft Foundry: depende de la opción de alojamiento del despliegue. Los despliegues alojados en Azure se sirven en infraestructura de Azure; los despliegues alojados en Anthropic se sirven en la infraestructura de Anthropic
  • ANTHROPIC_BASE_URL personalizado o LLM gateway: el caché vive donde se reenvíen sus solicitudes, y si el almacenamiento en caché funciona depende de la puerta de enlace

Claude Code también añade contexto del sistema a mitad de la conversación, como notificaciones de cambios de archivo, y marca ese bloque para almacenamiento en caché en cada proveedor y conexión.

En el punto final propio del proveedor, Amazon Bedrock y su punto final de Mantle, Google Cloud's Agent Platform, y Microsoft Foundry almacenan en caché el bloque de la misma manera que lo hace la Claude API.

Cuando sus solicitudes pasan a través de una puerta de enlace LLM, un ANTHROPIC_BASE_URL personalizado, o una anulación de URL base del proveedor de nube como ANTHROPIC_BEDROCK_BASE_URL, lo que permanece en caché depende de cómo la puerta de enlace maneja los marcadores cache_control que Claude Code envía:

  • Los reenvía sin cambios: el bloque y su conversación se almacenan en caché de la misma manera que en el punto final propio del proveedor.
  • Rechaza la solicitud marcada con un error 400 que nombra cache_control: Claude Code reenvía la solicitud con el marcador movido del bloque y hacia su último mensaje de conversación, y lo mantiene allí para el resto de la conversación. El bloque se factura como entrada sin caché; su conversación permanece en caché.
  • Elimina los marcadores mientras devuelve éxito: todo su historial de conversación se factura como entrada sin caché en cada turno. Una puerta de enlace que convierte contenido del sistema en forma de bloque a una cadena simple elimina el marcador de la misma manera.

Para lo que cada proveedor almacena y procesa, vea data usage. Dondequiera que viva el caché, las entradas expiran después de un período de inactividad, y Cache lifetime a continuación cubre el TTL y cómo extenderlo.

Acciones que invalidan el caché

Estas acciones hacen que la siguiente solicitud pierda parte o todo el caché. Verá un turno más lento y costoso de una sola vez, después del cual el nuevo prefijo se almacena en caché. La mayoría de ellas se pueden evitar a mitad de tarea una vez que sabe que tienen un costo. Un cambio de modelo puede parecer gratuito hasta que note el turno más lento que sigue.

Cambiar de modelo

Cada modelo tiene su propio caché. Cambiar con /model significa que la siguiente solicitud lee todo el historial de conversación sin aciertos de caché, aunque el contenido sea idéntico.

Cuando ejecuta /model en la terminal, Claude Code le pide que confirme el cambio solo mientras el caché aún está caliente. El caché permanece caliente durante un TTL de caché después de que Claude Code envió por última vez una solicitud en esta conversación o Claude respondió por última vez. Una vez que pasa ese tiempo, el caché ha expirado, por lo que Claude Code cambia sin preguntar.

Antes de v2.1.238, Claude Code no verificaba el TTL de caché y preguntaba incluso después de que el caché había expirado.

También puede requerir esta confirmación u omitirla con un hook PreModelSwitch.

La configuración de modelo opusplan se resuelve a Opus durante el modo de plan y Sonnet durante la ejecución, por lo que cada alternancia de modo de plan es un cambio de modelo e inicia un caché nuevo.

El respaldo automático de modelo en Fable 5.1, Fable 5 y Opus 5 también es un cambio de modelo. Cuando un clasificador de seguridad marca una solicitud y la categoría marcada tiene un modelo de respaldo, Claude Code vuelve a ejecutar la solicitud en ese modelo y la sesión continúa allí.

Cambiar el nivel de esfuerzo

En la mayoría de los modelos, cambiar el nivel de esfuerzo a mitad de sesión significa que la siguiente solicitud lee todo el historial de conversación sin aciertos de caché. Mientras el caché aún está caliente, Claude Code le pide que confirme el cambio primero.

En Fable 5.1 con una clave de API o una suscripción de Claude, cambiar el esfuerzo mantiene el caché, y Claude Code aplica el nuevo nivel sin preguntar. Esto no se aplica en Amazon Bedrock, en la Plataforma de Agentes de Google Cloud, o en una puerta de enlace de aplicaciones Claude, o cuando establece CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS o su organización tiene una configuración HIPAA.

Antes de v2.1.260, cambiar el esfuerzo en Fable 5.1 con una clave de API o una suscripción de Claude también invalidaba el caché.

Activar el modo rápido

Habilitar modo rápido añade un encabezado de solicitud que forma parte de la clave de caché, por lo que la primera solicitud que Claude Code envía con el modo rápido activado lee todo el historial de conversación sin aciertos de caché. Claude Code establece ese encabezado una vez cuando comienza un turno y lo mantiene durante todo el turno, por lo que cuando activa el modo rápido mientras Claude está trabajando, la pérdida de caché del encabezado ocurre en la primera solicitud de su siguiente turno. Esos tokens de entrada sin caché se facturan a tasas de modo rápido, por lo que activarlo al inicio de una sesión cuesta menos que activarlo profundamente en una larga. Si su modelo actual no admite el modo rápido, habilitar el modo rápido también cambia su modelo, y ese cambio inicia un caché nuevo por sí solo desde la siguiente solicitud en el turno en ejecución.

El costo se aplica una vez por conversación. Después del primer turno de modo rápido, Claude Code sigue enviando el encabezado y varía solo la configuración de velocidad de la solicitud, que no forma parte de la clave de caché. Desactivar el modo rápido, la reversión automática a velocidad estándar después de un límite de velocidad, y activarlo nuevamente más tarde mantienen el caché. Si se queda sin créditos de uso a mitad de sesión, Claude Code reintenta cada solicitud de modo rápido rechazada a velocidad estándar de la misma manera, por lo que este respaldo también mantiene el caché. /clear y /compact restablecen esto, ya que reconstruyen el caché en esos puntos de todas formas.

Conectar o desconectar un servidor MCP

Las definiciones de herramientas se encuentran en la capa del prompt del sistema, por lo que el caché se invalida cuando el conjunto de definiciones de herramientas en la solicitud cambia entre turnos. Alternar la herramienta de asesor es una excepción: su definición se encuentra después del punto de ruptura de caché, por lo que habilitar o deshabilitar /advisor mantiene el prefijo en caché intacto. Si un cambio de servidor MCP hace esto depende de si sus herramientas se difieren por búsqueda de herramientas o se cargan en el prefijo:

  • Herramientas diferidas, el valor predeterminado en modelos compatibles: un servidor que se conecta, desconecta o cambia su lista de herramientas solo añade contenido nuevo y no perturba nada ya almacenado en caché.
  • Herramientas cargadas en el prefijo: cualquier cambio en ellas invalida el caché. Esto sucede cuando la búsqueda de herramientas no está disponible o está deshabilitada, como en los modelos de la Plataforma de Agentes de Google Cloud anteriores a la generación Claude 4.5, con una puerta de enlace ANTHROPIC_BASE_URL personalizada, o en una implementación de Microsoft Foundry alojada en Azure una vez que Claude Code detecta que la implementación rechaza la búsqueda de herramientas. También sucede para un servidor o herramienta marcada alwaysLoad, y para definiciones mantenidas al frente por carga basada en umbral.

Cuando las herramientas se cargan en el prefijo, la causa más común de una invalidación es un servidor que se conecta o desconecta a mitad de sesión, lo que puede suceder sin ninguna acción de su parte: el proceso de un servidor stdio sale, una sesión HTTP expira, o un servidor se reconecta automáticamente después de una falla transitoria. Un servidor conectado también puede enviar una actualización de herramienta dinámica que cambia su lista de herramientas.

Editar su configuración de MCP no cambia el caché por sí solo. La nueva configuración entra en vigor solo después de un reinicio, que es cuando el servidor se conecta o desconecta.

Habilitar o deshabilitar un plugin

Cuando habilita o deshabilita un plugin, lo que cuesta el cambio depende de qué tipos de componentes proporciona el plugin. Los casos a continuación cubren cada tipo de componente, cuándo Claude Code aplica el cambio, y qué sucede cuando deshabilita un plugin nuevamente en la misma sesión.

Componentes de plugin que mantienen el caché

Claude Code nunca invalida el caché para las skills, comandos, agentes, hooks, monitores o temas de un plugin. Añade su contenido después de la conversación existente, por lo que la siguiente solicitud paga por ese contenido y aún lee todo lo anterior desde el caché.

Plugins que proporcionan servidores MCP

Cuando habilita o deshabilita un plugin que proporciona servidores MCP, Claude Code sigue las mismas reglas que cuando conecta o desconecta un servidor MCP:

  • Si Claude Code difiere las herramientas del servidor, mantiene el caché.
  • Si Claude Code las carga en el prefijo, la siguiente solicitud vuelve a leer toda la conversación.

Plugins de inteligencia de código

Cuando habilita un plugin de inteligencia de código, Claude obtiene la herramienta LSP.

Cuándo se aplican los cambios de plugin

Claude Code aplica un cambio de plugin cuando ejecuta /reload-plugins o inicia una nueva sesión. Paga el costo, ya sean anuncios añadidos o una relectura completa, en el primer turno después de que se aplique el cambio, no cuando ejecuta /plugin enable o /plugin disable. Claude Code también puede aplicar un cambio por su cuenta en tres casos:

  • Para un plugin con una fuente command, Claude Code puede recargar el plugin por sí mismo.
  • Cuando instala un plugin desde la interfaz /plugin, Claude Code puede activarlo durante la instalación. Claude Code le indica en el resumen de instalación si lo hizo o si debe ejecutar /reload-plugins.
  • Cuando mueve la sesión con /cd en v2.1.246 o posterior, Claude Code aplica los plugins que la configuración del nuevo directorio habilita como parte del movimiento, sin la advertencia de relectura completa que retiene un /reload-plugins.

Cuando ejecuta /reload-plugins y la recarga activaría una relectura completa, Claude Code muestra una advertencia y no aplica la recarga. Ejecútelo nuevamente con --force para aplicar la recarga de todas formas.

Plugins que habilita y luego deshabilita en una sesión

Cuando deshabilita un plugin que habilitó anteriormente en la sesión, Claude Code restaura la forma de solicitud anterior. Si ese prefijo aún está dentro de su vida útil de caché, la siguiente solicitud lee la entrada de caché más antigua en lugar de reconstruir.

Denegar una herramienta completa

Agregar un nombre de herramienta simple como Bash o WebFetch como una regla de denegación elimina esa herramienta del contexto de Claude por completo. Claude Code carga las definiciones de herramientas integradas en la capa del prompt del sistema, por lo que agregar o eliminar una de estas reglas a mitad de sesión invalida el caché. Claude Code aplica el cambio en la siguiente solicitud, ya sea que agregue la regla a través de /permissions o editando un archivo de configuración directamente. Eso incluye una regla que agrega a través de /permissions en medio de un turno.

Solo una regla de denegación que coincida en la posición del nombre de la herramienta tiene este efecto: un nombre de herramienta simple, la forma equivalente Bash(*), o un glob de nombre de herramienta como "*". Un glob que coincida solo con herramientas MCP, como "mcp__*", elimina esas herramientas de la misma manera pero deja el caché intacto cuando las herramientas coincidentes se difieren, el valor predeterminado, ya que las definiciones diferidas nunca estuvieron en el prefijo en caché. Las reglas de denegación con alcance como Bash(rm *), y todas las reglas de permitir y preguntar, no cambian qué herramientas ve Claude. Claude Code las verifica cuando Claude intenta una llamada, dejando el prefijo intacto.

Cambiar el estilo de salida

El estilo de salida es parte del prompt del sistema. Cuando cambia de estilos a mitad de sesión con /config o la configuración outputStyle, Claude usa el nuevo estilo comenzando con su siguiente mensaje, y esa solicitud lee todo el historial de conversación sin aciertos de caché. Para mantener ese costo pequeño, cambie de estilos antes de su primer mensaje en una sesión o justo después de /clear o /compact, cuando hay poco o ningún historial de conversación para releer.

Antes de v2.1.251, un cambio de estilo a mitad de sesión mantenía el caché pero no se aplicaba hasta que ejecutaba /clear o iniciaba una nueva sesión.

Compactar la conversación

La compactación reemplaza su historial de mensajes con un resumen. Por diseño, esto invalida la capa de conversación, ya que la siguiente solicitud tiene un historial nuevo y más corto que no comparte un prefijo con el anterior. Claude Code reutiliza la capa del prompt del sistema y recarga el contexto del proyecto desde el disco, que solo tiene aciertos de caché si CLAUDE.md y la memoria no han cambiado desde que comenzó la sesión.

Para producir el resumen, Claude Code envía una solicitud única con el mismo prompt del sistema, herramientas e historial que su conversación, más una instrucción de resumen añadida como un mensaje de usuario final. Mientras el caché está caliente, esa solicitud lee su prefijo desde el caché, por lo que una /compact a mitad de sesión cuesta una fracción de lo que sugiere el tamaño del contexto y dedica la mayoría de su tiempo a generar el resumen.

Después de una pausa más larga que la vida útil del caché, no hay caché izquierdo para leer, por lo que la solicitud de resumen reprocesa el historial completo como entrada sin caché. Por eso /compact cuesta más cuando reanuda una sesión antigua. En ambos casos, caliente y frío, el turno después de la compactación reconstruye el caché de conversación solo para el resumen mucho más corto, por lo que ese turno no es la parte lenta.

Acumular muchas imágenes

La API limita cuántas imágenes y PDF puede llevar cada solicitud. Para los números actuales, consulte Límites de solicitud en los documentos de la API. Claude Code también limita el tamaño total de las imágenes y PDF en una solicitud, por lo que las capturas de pantalla grandes alcanzan el límite con menos imágenes que las pequeñas.

Cuando la siguiente solicitud pasaría cualquiera de los límites, Claude Code elimina un lote de las imágenes y PDF más antiguas de lo que envía, lo que deja espacio para más antes de que necesite eliminar alguna nuevamente. Claude ya no puede ver las imágenes eliminadas. Si Claude necesita una de ellas nuevamente, compártala nuevamente.

Eliminar imágenes cambia los mensajes que las contenían, por lo que la siguiente solicitud reprocesa la conversación desde la más antigua de esos mensajes en adelante. Porque Claude Code elimina un lote a la vez, ve un turno más lento por lote en lugar de uno con cada nueva captura de pantalla.

Actualizar Claude Code

Una nueva versión de Claude Code típicamente actualiza el prompt del sistema o las definiciones de herramientas, por lo que la primera solicitud después de una actualización reconstruye el caché desde el principio. Auto-update descarga nuevas versiones en segundo plano pero las aplica en el siguiente lanzamiento, nunca a mitad de sesión, por lo que ve esto como un primer turno sin caché después de reiniciar en lugar de una sorpresa durante una sesión. Establezca DISABLE_AUTOUPDATER=1 para controlar cuándo se aplican las actualizaciones.

Acciones que mantienen el caché

Estas acciones ya sea se añaden al final de la conversación o no tocan la solicitud en absoluto. Algunas de ellas, como editar CLAUDE.md, mantienen el caché por la misma razón que el cambio no llega a la sesión en ejecución hasta /clear, /compact, o un reinicio.

Editar archivos en su repositorio

El contenido del archivo entra en contexto solo cuando Claude lo lee, y las lecturas se añaden a la conversación. Editar un archivo que Claude leyó anteriormente no cambia retroactivamente la lectura anterior en el historial. En su lugar, Claude Code añade un <system-reminder> notando que el archivo cambió, y Claude lo relee si es necesario.

Editar CLAUDE.md a mitad de sesión

Sus archivos CLAUDE.md de raíz de proyecto y nivel de usuario se leen una vez al inicio de la sesión y se mantienen en memoria. Editarlos a mitad de sesión no invalida el caché, pero la edición tampoco se aplica. Claude continúa trabajando con la versión que se cargó al inicio de la sesión. El nuevo contenido se carga en el siguiente /clear, /compact, o reinicio.

Archivos CLAUDE.md anidados en subdirectorios y reglas con frontmatter paths: se cargan más tarde, cuando Claude lee por primera vez un archivo coincidente. Editar uno antes de que se cargue sí tiene efecto. Después de que se carga, el contenido es parte del historial de conversación, por lo que una edición a mitad de sesión no lo cambia retroactivamente.

Cambiar el modo de permiso

Cambiar entre permission modes, como de Manual a aceptar ediciones, no cambia el prompt del sistema o las definiciones de herramientas, por lo que los cambios de modo son seguros para el caché. La excepción es el modo de plan con la configuración de modelo opusplan, que cambia el modelo entre Opus y Sonnet cuando entra o sale del modo de plan. Eso hace que el cambio de modo sea un cambio de modelo.

Invocar skills y comandos

Skills y commands inyectan sus instrucciones como mensajes de usuario en el punto de invocación. Nada anterior en la conversación cambia.

Ejecutar `/recap`

/recap genera un resumen para mostrar en su terminal. A diferencia de /compact, añade el resumen como salida de comando en lugar de reemplazar su historial de mensajes, por lo que el prefijo en caché permanece intacto.

Rewind de la conversación

/rewind trunca su conversación de vuelta a un turno anterior. El historial restante es el mismo contenido del que se construyó el caché en ese punto, y las capas del prompt del sistema y contexto del proyecto no cambian, por lo que la siguiente solicitud acierta la entrada de caché anterior. Cada turno desde entonces ha leído a través de ese prefijo, que mantuvo la entrada activa incluso si el turno original fue hace más tiempo que el TTL.

Restaurar puntos de control de archivo junto con la conversación no tiene efecto separado en el caché. El contenido del archivo entra en contexto solo cuando Claude lo lee, igual que editar archivos en su repositorio.

Duración del caché

Los prefijos en caché expiran después de un período de inactividad. Cada solicitud que acierta el caché reinicia el temporizador, por lo que el caché permanece activo mientras continúe trabajando. Después de una brecha lo suficientemente larga, la siguiente solicitud recalcula la entrada completa y restablece el caché, que es por qué el primer turno después de alejarse puede ser notablemente más lento.

En un plan Pro o Max, cuando reanuda una sesión grande después de un descanso prolongado, Claude Code ofrece reanudar desde un resumen para que las solicitudes posteriores no lleven el historial completo.

El tiempo de vida (TTL) controla cuánto tiempo la brecha el caché sobrevive. La API ofrece dos: un TTL de cinco minutos, y un TTL de una hora que mantiene el caché activo a través de descansos más largos pero factura escrituras de caché a una tasa más alta. El TTL más largo ayuda cuando deja una sesión inactiva y vuelve a ella, porque omite el reprocesamiento que cuesta un prefijo expirado. Cuesta más en ráfagas cortas de trabajo que nunca se quedan inactivas más de cinco minutos, donde se aplica la tasa de escritura más alta y la duración de caché más larga no se utiliza.

Qué TTL obtiene cada solicitud

Claude Code decide el TTL por solicitud, y cada solicitud cae en uno de dos depósitos fijos:

  • Conversación principal: sus turnos interactivos, ejecuciones -p no interactivas, y turnos del SDK de Agent, más los ayudantes que Claude Code ejecuta en línea con ellos
  • Todo lo demás: las solicitudes que Claude Code realiza fuera de esa conversación, como subagentes, flujos de trabajo, compañeros de equipo en proceso, bifurcaciones, compactación, y títulos de sesión

A menos que elija un TTL usted mismo, Claude Code solicita el TTL de una hora solo en una suscripción de Claude dentro del uso incluido en su plan. Allí solicita la hora para la conversación principal, más un pequeño conjunto de solicitudes de ayuda que Anthropic controla del lado del servidor. Esta tabla proporciona el TTL predeterminado de cada depósito bajo ambos tipos de facturación.

Depósito de solicitud Suscripción de Claude, dentro del uso del plan Créditos de uso, clave de API, o proveedor de nube
Conversación principal Una hora Cinco minutos
Todo lo demás Cinco minutos, excepto las solicitudes de ayuda controladas por el servidor, que obtienen una hora Cinco minutos

Una vez que supera el límite de uso de su plan y Claude Code utiliza créditos de uso, se le factura por ese uso, por lo que Claude Code reduce la conversación principal al TTL de cinco minutos más económico. Para mantener el TTL de una hora allí, elija el TTL usted mismo.

Elija el TTL usted mismo

Puede establecer un TTL para cualquier depósito. Cada control toma 5m o 1h, y Claude Code ignora cualquier otro valor.

Ambas configuraciones y ambas variables de entorno requieren Claude Code v2.1.242 o posterior. Si inicia sesión con una clave de API o utiliza un proveedor de nube, establezca promptCacheTtl en 1h para dar a la conversación principal un caché de una hora. Las solicitudes fuera de ella mantienen el predeterminado de cinco minutos hasta que elija un TTL para ese depósito también.

Cuando se aplica más de un control, Claude Code toma la primera coincidencia en este orden:

  1. FORCE_PROMPT_CACHING_5M=1, que fuerza cinco minutos para ambos depósitos
  2. La variable de entorno del depósito
  3. La configuración del depósito
  4. Para las solicitudes de un subagente, el valor cacheTtl en el campo frontmatter experimental del subagente, que requiere Claude Code v2.1.248 o posterior. Claude Code ignora un 1h allí mientras su suscripción de Claude está utilizando créditos de uso
  5. ENABLE_PROMPT_CACHING_1H=1, que solicita una hora para ambos depósitos
  6. El predeterminado para el depósito de la solicitud

Establezca FORCE_PROMPT_CACHING_5M=1 cuando esté depurando el comportamiento del caché, comparando los dos TTL, o anulando un TTL más largo establecido en configuración administrada.

Para confirmar qué TTL utilizaron las escrituras de caché de su conversación principal, ejecute claude -p "hello" --output-format json y lea usage.cache_creation en el resultado. Claude Code reporta escrituras de caché de una hora bajo ephemeral_1h_input_tokens y escrituras de caché de cinco minutos bajo ephemeral_5m_input_tokens.

A través de una puerta de enlace LLM que establece con ANTHROPIC_BASE_URL, parte de la solicitud de una hora viaja en el encabezado anthropic-beta, por lo que configure la puerta de enlace para reenviar ese encabezado sin cambios. El TTL de una hora no está disponible a través de la puerta de enlace de aplicaciones Claude. En Amazon Bedrock, el soporte de almacenamiento en caché de prompts, la longitud mínima de prefijo almacenable en caché, y la disponibilidad de TTL de una hora varían según el modelo. Si los recuentos de tokens de caché permanecen en cero, verifique modelos soportados, regiones y límites en la documentación de Amazon Bedrock.

Alcance del caché

En Claude Code, el caché está efectivamente limitado a una máquina y directorio. El prompt del sistema incorpora el directorio de trabajo, plataforma, shell, versión del SO, y rutas de memoria automática, por lo que dos sesiones en directorios diferentes construyen prefijos diferentes y se pierden el caché del otro. Eso incluye worktrees del mismo repositorio, ya que cada worktree tiene su propio directorio de trabajo.

Las sesiones que ejecuta en paralelo en el mismo directorio construyen prefijos coincidentes y leen el caché del otro. Las sesiones secuenciales comparten el prefijo solo cuando la instantánea de estado de git al inicio coincide, ya que el prompt del sistema también captura rama y commits recientes.

El caché de API subyacente es más amplio. Los cachés están aislados entre organizaciones, y en algunos proveedores, entre espacios de trabajo dentro de una organización. Dentro de esos límites, cualquier dos solicitudes con el mismo modelo y prefijo leen el mismo caché. Para llamadores de Agent SDK que ejecutan flotas de procesos automatizados, vea mejorar el almacenamiento en caché de prompts entre usuarios y máquinas para suprimir las secciones por máquina del prompt del sistema y compartir el caché entre máquinas.

Verificar el rendimiento del caché

El rendimiento del caché se muestra como dos recuentos de tokens que la API reporta en cada respuesta. La forma más directa de verlos en vivo es un script de statusline que lee el objeto current_usage:

Campo Significado
cache_creation_input_tokens Tokens escritos en el caché en este turno, facturados a la tasa de escritura de caché
cache_read_input_tokens Tokens servidos desde caché en este turno, facturados a aproximadamente el 10% de la tasa de entrada estándar

Una alta relación de lectura a creación significa que el almacenamiento en caché está funcionando bien. Si la creación permanece alta turno tras turno, algo está cambiando en su prefijo. La sección acciones que invalidan el caché enumera las causas usuales.

Para un resumen por sesión, ejecute /usage. Después de la primera respuesta de la conversación principal, Claude Code añade una línea Prompt cache (main) al bloque de sesión, mostrando la relación de aciertos de la sesión, el recuento de fallos y si el caché está activo en este momento. Un script de statusline puede leer los mismos números desde el objeto prompt_cache. Ambos requieren Claude Code v2.1.251 o posterior.

La línea Prompt cache (main) también nombra la causa probable del último fallo cuando Claude Code puede identificar una, por ejemplo likely cause: tool definitions changed. El texto de causa probable requiere Claude Code v2.1.260 o posterior.

Para visibilidad en toda una organización, el exportador de OpenTelemetry reporta tokens de lectura y creación de caché por usuario y sesión. Vea Monitor usage para la referencia de métrica y atributo de evento.

Subagentes y el caché

Un subagent inicia su propia conversación con su propio prompt del sistema y conjunto de herramientas, separado del padre. Su primera solicitud no lee el caché del padre, porque los dos prefijos difieren, y calienta un caché propio a través de sus turnos. Los subagentes caen fuera del bucket TTL de la conversación principal, por lo que obtienen cinco minutos incluso en una suscripción hasta que elija uno más largo.

El caché del padre no se ve afectado. Desde el lado del padre, la llamada y resultado del subagente se añaden a la conversación, dejando el prefijo del padre intacto.

Un fork, por el contrario, hereda el prompt del sistema del padre, herramientas e historial de conversación exactamente, por lo que su primera solicitud lee el caché del padre.

Otras solicitudes también pueden leer un prefijo que una solicitud anterior almacenó en caché:

  • Copias de sesión: una sesión que copia con /fork recibe su instrucción de aislamiento como un mensaje al final de la conversación copiada, por lo que el caché que la conversación original construyó permanece intacto.
  • Compactación: la llamada de resumen descrita en Compactar la conversación utiliza el mismo enfoque de compartir prefijo.
  • Fan-outs de flujo de trabajo: en un fan-out de flujo de trabajo de agentes con el mismo prefijo, Claude Code retiene todos excepto el primero durante hasta 5 segundos por defecto, por lo que sus primeras solicitudes pueden leer el prefijo que el primer agente almacenó en caché.

Desactivar el almacenamiento en caché de prompts

Desactivar el almacenamiento en caché es ocasionalmente útil cuando se depura el comportamiento del almacenamiento en caché con un modelo o proveedor específico. Para desactivarlo, establezca una de estas variables de entorno a 1:

Variable Efecto
DISABLE_PROMPT_CACHING Desactivar para todos los modelos
DISABLE_PROMPT_CACHING_HAIKU Desactivar solo para Haiku
DISABLE_PROMPT_CACHING_SONNET Desactivar solo para Sonnet
DISABLE_PROMPT_CACHING_OPUS Desactivar solo para Opus
DISABLE_PROMPT_CACHING_FABLE Desactivar solo para Fable

Para establecer la política de almacenamiento en caché en toda una organización, coloque cualquiera de estas o las variables de TTL en el bloque env de configuración administrada. Para uso normal, deje el almacenamiento en caché habilitado.