Cómo se organiza la caché
Cada vez que envías un mensaje en Claude Code, se 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 tu proyecto, cada mensaje anterior y resultado de herramienta, y tu nuevo mensaje. El contenido nuevo se añade al final, lo que significa que la mayor parte de cada solicitud es idéntica a la anterior. La caché de prompts es la forma en que la API evita reprocesar la parte que no cambió. La API almacena en caché haciendo coincidir el inicio de cada solicitud, llamado 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 lo que viene después. No hay almacenamiento en caché por archivo ni por segmento. Consulta cómo funciona la caché de prompts en la referencia de la API para conocer el mecanismo subyacente.
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 ofrece 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 de esta página. El modo plan y la carga de skills, 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 aun así afectan lo que permanece en caché:
- Modelo: cada modelo tiene su propia caché. Cambiar de modelo recalcula toda la solicitud incluso cuando el contenido es idéntico. Consulta Cambiar de modelo a continuación.
- Nivel de esfuerzo: en la mayoría de los modelos, cada nivel de esfuerzo tiene su propia caché, por lo que cambiar el esfuerzo a mitad de sesión recalcula toda la solicitud. En Opus 5.5, Sonnet 5.5, Haiku 5.5 y Fable 5.1 con una clave de API o una suscripción de Claude, la caché permanece intacta de forma predeterminada. Consulta Cambiar el nivel de esfuerzo a continuación.
Dónde vive la caché
El almacenamiento en caché ocurre del lado del servidor, en la infraestructura que sirva tu modelo. Dónde está depende de cómo te autentiques:- Clave de API, suscripción de Claude o Claude Platform on AWS: la caché vive en la infraestructura de Anthropic, accesible a través de la Claude API
- Amazon Bedrock o Agent Platform de Google Cloud: la caché vive en la infraestructura de servicio de tu 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_URLpersonalizado o LLM gateway: la caché vive donde se reenvíen tus solicitudes, y que el almacenamiento en caché funcione depende del gateway
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS, en cuyo caso ese bloque se envía sin caché.
En el endpoint propio del proveedor, Amazon Bedrock y su endpoint de Mantle, Agent Platform de Google Cloud y Microsoft Foundry almacenan en caché el bloque de la misma manera que la Claude API.
Cuando tus solicitudes pasan por un LLM gateway, un ANTHROPIC_BASE_URL personalizado o una sobrescritura de URL base del proveedor de nube como ANTHROPIC_BEDROCK_BASE_URL, lo que permanece en caché depende de cómo el gateway maneje los marcadores de cache_control que envía Claude Code:
- Los reenvía sin cambios: el bloque y tu conversación se almacenan en caché de la misma manera que en el endpoint propio del proveedor.
- Rechaza la solicitud marcada con un error
400que mencionacache_control: Claude Code reenvía la solicitud con el marcador movido fuera del bloque y hacia tu último mensaje de la conversación, y lo mantiene allí durante el resto de la conversación. El bloque se factura como entrada sin caché; tu conversación permanece en caché. - Elimina los marcadores mientras devuelve éxito: todo tu historial de conversación se factura como entrada sin caché en cada turno. Un gateway que convierte el contenido del sistema en forma de bloque a una cadena simple elimina el marcador de la misma manera.
Acciones que invalidan la caché
Estas acciones hacen que la siguiente solicitud pierda parte o toda la caché. Verás 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 durante la tarea una vez que sabes que tienen un costo. Un cambio de modelo puede parecer gratuito hasta que notas el turno más lento que sigue.- Cambiar modelos
- Cambiar el nivel de esfuerzo
- Activar el modo rápido
- Conectar o desconectar un servidor MCP
- Habilitar o deshabilitar un plugin
- Denegar una herramienta completa
- Compactar la conversación
- Acumular muchas imágenes
- Actualizar Claude Code
Cambiar modelos
Cada modelo tiene su propia 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 ejecutas /model en la terminal, Claude Code te pide que confirmes el cambio solo mientras la caché aún está activa y el nuevo modelo no es el que produjo la última respuesta. La caché permanece activa 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, la 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 la caché había expirado.
También puedes requerir esta confirmación u omitirla con un hook PreModelSwitch.
El ajuste de modelo opusplan se resuelve a Opus durante el modo plan y a Sonnet durante la ejecución, por lo que cada vez que activas o desactivas el modo plan es un cambio de modelo e inicia una caché nueva.
El cambio automático al modelo de respaldo en modelos Fable, Opus 5.5, Sonnet 5.5 y Opus 5 también es un cambio de modelo. Cuando un clasificador de seguridad marca una solicitud en una categoría que tiene un modelo de respaldo y Claude Code vuelve a ejecutar la solicitud en ese modelo, la sesión continúa allí.
Cuando el frontmatter de un skill o comando nombra un model diferente del modelo actual de la sesión, ese turno también es un cambio de modelo: la siguiente solicitud lee todo el historial de conversación sin aciertos de caché. El modelo de la sesión se reanuda en tu siguiente prompt. Un skill context: fork establece en su lugar el modelo del subagente bifurcado.
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 la caché aún está activa, Claude Code te pide que confirmes el cambio primero. En Opus 5.5, Sonnet 5.5, Haiku 5.5 y Fable 5.1 con una clave de API o una suscripción a Claude, cambiar el esfuerzo mantiene la caché, y Claude Code aplica el nuevo nivel sin preguntar. Esto no se aplica en Amazon Bedrock, en Agent Platform de Google Cloud, ni en un gateway de aplicaciones de Claude, ni cuando establecesCLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS o tu 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 a Claude también invalidaba la caché.
Activar el modo rápido
Habilitar el modo rápido agrega un encabezado de solicitud que es 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 activas el modo rápido mientras Claude está trabajando, la pérdida de caché del encabezado ocurre en la primera solicitud de tu siguiente turno. Esos tokens de entrada sin caché se facturan a tarifas de modo rápido, por lo que activarlo al inicio de una sesión cuesta menos que activarlo muy avanzada una sesión larga. Si tu modelo actual no admite el modo rápido, habilitar el modo rápido también cambia tu modelo, y ese cambio inicia una caché nueva 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 el ajuste de velocidad de la solicitud, que no es parte de la clave de caché. Desactivar el modo rápido, el cambio automático a velocidad estándar después de un rate limit, y activarlo nuevamente más tarde mantienen la caché. Si te quedas 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 la caché./clear y /compact restablecen esto, ya que reconstruyen la caché en esos puntos de todos modos.
Conectar o desconectar un servidor MCP
Las definiciones de herramientas se encuentran en la capa del prompt del sistema, por lo que la caché se invalida cuando el conjunto de definiciones de herramientas en la solicitud cambia entre turnos. Activar o desactivar 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 intacto el prefijo almacenado en caché. Que un cambio de servidor MCP haga esto depende de si la búsqueda de herramientas difiere las herramientas MCP de la sesión, el valor predeterminado en modelos compatibles:
- Herramientas diferidas: Claude Code mantiene la lista de herramientas de la primera solicitud de la conversación durante toda la conversación, por lo que un servidor que se conecta o desconecta a mitad de sesión no perturba nada ya almacenado en caché. Un servidor que termina de conectarse después de la primera solicitud proporciona sus herramientas como definiciones diferidas que Claude carga bajo demanda.
- Herramientas cargadas por adelantado: agregar una definición invalida la caché, y lo mismo ocurre al eliminar una a propósito. Esto se aplica cuando la búsqueda de herramientas está por debajo de su umbral
auto, deshabilitada o no disponible, como en los modelos de Agent Platform de Google Cloud anteriores a Opus 4.5, Sonnet 4.5 y Haiku 4.5, con un gatewayANTHROPIC_BASE_URLpersonalizado, o en un despliegue alojado en Azure de Microsoft Foundry una vez que Claude Code detecta que el despliegue rechaza la búsqueda de herramientas.
Cuando reanudas una conversación cuyas herramientas se cargan en el prefijo, uno de sus servidores MCP aún puede estar conectándose cuando sale la primera solicitud. Si la transcripción registró las definiciones de herramientas de ese servidor, esa solicitud las incluye tal como se registraron, por lo que no cambia cuando el servidor termina de conectarse con las mismas herramientas.
Editar tu configuración de MCP no cambia la 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.