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

Comment Claude Code utilise le prompt caching

Claude Code gère le prompt caching automatiquement. Découvrez pourquoi un changement de modèle déclenche un tour lent sans cache, ce que coûte /compact, pourquoi les modifications de CLAUDE.md ne s'appliquent pas en cours de session, et comment vérifier votre taux de cache hit.

Le prompt caching rend Claude Code plus rapide et plus rentable. Sans caching, l'API retraiterait votre historique complet à chaque tour. Avec le caching, elle réutilise ce qu'elle a déjà traité, facture la relecture au taux de cache, et ne traite complètement que ce qui a changé.

Claude Code gère le prompt caching pour vous, sauf si vous le désactivez. Il est néanmoins utile de comprendre comment fonctionne le prompt caching, car certaines actions invalident le cache et rendent la réponse suivante plus lente et plus coûteuse pendant qu'il se reconstruit. Cette page couvre les actions qui le font, pourquoi certains paramètres attendent un redémarrage pour s'appliquer, et comment vérifier les performances du cache quand l'utilisation semble élevée.

Comment le cache est organisé

Chaque fois que vous envoyez un message dans Claude Code, il effectue une nouvelle requête API. Le modèle ne se souvient de rien entre les requêtes, donc Claude Code renvoie le contexte complet : le prompt système, votre contexte de projet, chaque message antérieur et résultat d'outil, et votre nouveau message. Le nouveau contenu est ajouté à la fin, ce qui signifie que la plupart de chaque requête est identique à celle précédente. Le prompt caching est la façon dont l'API évite de retraiter la partie qui n'a pas changé.

L'API met en cache en faisant correspondre le début de chaque requête, appelé le préfixe, avec le contenu qu'elle a récemment traité. À un tour normal, le préfixe est la requête entière précédente et seul l'échange le plus récent est nouveau. La correspondance est exacte, donc un changement n'importe où dans le préfixe recalcule tout ce qui suit. Il n'y a pas de caching par fichier ou par segment. Voir comment fonctionne le prompt caching dans la référence API pour le mécanisme sous-jacent.

Quatre tours affichés sous forme de barres horizontales croissantes. La requête de chaque tour contient tout ce qui provient du tour précédent plus l'échange le plus récent ajouté à la fin. Aux tours deux et trois, le préfixe inchangé est lu à partir du cache et seul le nouvel échange est traité. Au tour quatre, le prompt système a changé, donc le préfixe ne correspond plus et la requête entière est retraitée et écrite. Quatre tours affichés sous forme de barres horizontales croissantes. La requête de chaque tour contient tout ce qui provient du tour précédent plus l'échange le plus récent ajouté à la fin. Aux tours deux et trois, le préfixe inchangé est lu à partir du cache et seul le nouvel échange est traité. Au tour quatre, le prompt système a changé, donc le préfixe ne correspond plus et la requête entière est retraitée et écrite.

Pour tirer le meilleur parti de la correspondance de préfixe, Claude Code organise chaque requête de sorte que le contenu qui change rarement entre les tours vient en premier :

Couche Contenu Change quand
Prompt système Instructions principales, définitions d'outils, style de sortie L'ensemble des définitions d'outils chargées change, vous changez de style de sortie, ou Claude Code est mis à niveau
Contexte du projet CLAUDE.md, mémoire automatique, règles non délimitées La session démarre, ou après /clear ou /compact
Conversation Vos messages, les réponses de Claude, les résultats d'outils À chaque tour

Un changement à la couche conversation laisse le prompt système et le contexte du projet en cache. Un changement au prompt système invalide tout, car tout le contenu ultérieur se trouve maintenant derrière un préfixe différent. La troisième colonne donne les déclencheurs courants plutôt qu'une liste exhaustive, et les sections ci-dessous couvrent l'ensemble complet.

La règle de correspondance de préfixe explique la plupart des comportements sur cette page. Le mode plan et le chargement de compétences, par exemple, ajoutent leurs instructions comme messages de conversation, de sorte que le préfixe en cache reste intact.

Deux paramètres n'apparaissent pas dans le tableau des couches mais affectent toujours ce qui reste en cache :

  • Modèle : chaque modèle a son propre cache. Changer de modèle recalcule la requête entière même quand le contenu est identique. Voir Changer de modèle ci-dessous.
  • Niveau d'effort : sur la plupart des modèles, chaque niveau d'effort a son propre cache, donc changer d'effort en cours de session recalcule la requête entière. Sur Fable 5.1 avec une clé API ou un abonnement Claude, le cache reste intact par défaut. Voir Changer le niveau d'effort ci-dessous.

Où vit le cache

Le caching se produit côté serveur, dans l'infrastructure qui sert votre modèle. L'endroit où cela se trouve dépend de la façon dont vous vous authentifiez :

  • Clé API, abonnement Claude, ou Claude Platform on AWS : le cache vit dans l'infrastructure d'Anthropic, accessible via l'API Claude
  • Amazon Bedrock ou Google Cloud's Agent Platform : le cache vit dans l'infrastructure de service de votre fournisseur cloud
  • Microsoft Foundry : dépend de l'option d'hébergement du déploiement. Les déploiements hébergés sur Azure sont servis sur l'infrastructure Azure ; les déploiements hébergés sur Anthropic sont servis sur l'infrastructure d'Anthropic
  • ANTHROPIC_BASE_URL personnalisé ou passerelle LLM : le cache vit là où vos requêtes sont transférées, et le fonctionnement du caching dépend de la passerelle

Claude Code ajoute également le contexte système en cours de conversation, comme les avis de changement de fichier, et marque ce bloc pour la mise en cache sur chaque fournisseur et connexion.

Au point de terminaison propre du fournisseur, Amazon Bedrock et son point de terminaison Mantle, Google Cloud's Agent Platform, et Microsoft Foundry mettent en cache le bloc de la même manière que l'API Claude.

Quand vos requêtes passent par une passerelle LLM, un ANTHROPIC_BASE_URL personnalisé, ou un remplacement d'URL de base du fournisseur cloud tel que ANTHROPIC_BEDROCK_BASE_URL, ce qui reste en cache dépend de la façon dont la passerelle gère les marqueurs cache_control que Claude Code envoie :

  • Les transmet inchangés : le bloc et votre conversation se mettent en cache de la même manière qu'au point de terminaison propre du fournisseur.
  • Rejette la requête marquée avec une erreur 400 nommant cache_control : Claude Code renvoie la requête avec le marqueur déplacé du bloc vers votre dernier message de conversation, et le garde là pour le reste de la conversation. Le bloc est facturé comme entrée non mise en cache ; votre conversation reste mise en cache.
  • Supprime les marqueurs tout en retournant le succès : l'intégralité de votre historique de conversation est facturée comme entrée non mise en cache à chaque tour. Une passerelle qui convertit le contenu du système sous forme de bloc en une chaîne simple supprime le marqueur de la même manière.

Pour ce que chaque fournisseur stocke et traite, voir utilisation des données. Où que le cache vive, les entrées expirent après une période d'inactivité, et Durée de vie du cache ci-dessous couvre le TTL et comment l'étendre.

Actions qui invalident le cache

Ces actions font que la requête suivante manque une partie ou la totalité du cache. Vous voyez un tour plus lent et plus coûteux une seule fois, après quoi le nouveau préfixe est mis en cache. La plupart d'entre elles sont évitables en cours de tâche une fois que vous savez qu'elles ont un coût. Un changement de modèle peut sembler gratuit jusqu'à ce que vous remarquiez le tour plus lent qui suit.

Changer de modèle

Chaque modèle a son propre cache. Changer avec /model signifie que la requête suivante lit l'historique de conversation entier sans cache hits, même si le contenu est identique.

Quand vous exécutez /model au terminal, Claude Code vous demande de confirmer le changement uniquement tant que le cache est encore chaud. Le cache reste chaud pendant une durée de vie du cache après que Claude Code ait envoyé une dernière requête dans cette conversation ou que Claude ait répondu. Une fois ce délai écoulé, le cache a expiré, donc Claude Code bascule sans demander.

Avant la v2.1.238, Claude Code ne vérifiait pas la durée de vie du cache et demandait même après l'expiration du cache.

Vous pouvez également exiger cette confirmation ou l'ignorer avec un hook PreModelSwitch.

Le paramètre de modèle opusplan se résout en Opus pendant le mode plan et Sonnet pendant l'exécution, donc chaque basculement de mode plan est un changement de modèle et démarre un cache frais.

Le basculement automatique du modèle sur Fable 5.1, Fable 5 et Opus 5 est également un changement de modèle. Quand un classificateur de sécurité signale une requête et que la catégorie signalée a un modèle de secours, Claude Code réexécute la requête sur ce modèle et la session continue là.

Modifier le niveau d'effort

Sur la plupart des modèles, modifier le niveau d'effort en cours de session signifie que la requête suivante lit l'historique de conversation entier sans cache hits. Tant que le cache est encore chaud, Claude Code vous demande de confirmer le changement d'abord.

Sur Fable 5.1 avec une clé API ou un abonnement Claude, modifier l'effort conserve le cache, et Claude Code applique le nouveau niveau sans demander. Cela ne s'applique pas sur Amazon Bedrock, Google Cloud's Agent Platform, ou une passerelle d'applications Claude, ou quand vous définissez CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS ou que votre organisation a une configuration HIPAA.

Avant la v2.1.260, modifier l'effort sur Fable 5.1 avec une clé API ou un abonnement Claude invalidait également le cache.

Activer le mode rapide

L'activation du mode rapide ajoute un en-tête de requête qui fait partie de la clé de cache, donc la première requête que Claude Code envoie avec le mode rapide activé lit l'historique de conversation entier sans cache hits. Claude Code définit cet en-tête une fois quand un tour commence et le conserve pour tout le tour, donc quand vous activez le mode rapide pendant que Claude travaille, le cache miss de l'en-tête se produit sur la première requête de votre tour suivant. Ces jetons d'entrée non mis en cache sont facturés aux tarifs du mode rapide, c'est pourquoi l'activer au début d'une session coûte moins cher que de l'activer profondément dans une longue session. Si votre modèle actuel ne supporte pas le mode rapide, l'activation du mode rapide bascule également votre modèle, et ce changement démarre un cache frais en soi à partir de la requête suivante du tour en cours.

Le coût s'applique une fois par conversation. Après le premier tour en mode rapide, Claude Code continue d'envoyer l'en-tête et varie uniquement le paramètre de vitesse de la requête, qui ne fait pas partie de la clé de cache. Désactiver le mode rapide, le basculement automatique vers la vitesse standard après une limite de débit, et le réactiver plus tard conservent tous le cache. Si vous épuisez vos crédits d'utilisation en cours de session, Claude Code réessaie chaque requête en mode rapide rejetée à la vitesse standard de la même manière, donc ce basculement conserve également le cache. /clear et /compact réinitialisent cela, puisqu'ils reconstruisent le cache à ces points de toute façon.

Connecter ou déconnecter un serveur MCP

Les définitions d'outils se trouvent dans la couche du prompt système, donc le cache s'invalide quand l'ensemble des définitions d'outils dans la requête change entre les tours. Basculer l'outil conseiller est une exception : sa définition se trouve après le point de rupture du cache, donc activer ou désactiver /advisor conserve le préfixe mis en cache intact. Qu'un changement de serveur MCP fasse cela dépend de si ses outils sont différés par la recherche d'outils ou chargés dans le préfixe :

  • Outils différés, la valeur par défaut sur les modèles supportés : un serveur qui se connecte, se déconnecte, ou change sa liste d'outils n'ajoute que du nouveau contenu et ne perturbe rien de ce qui est déjà en cache.
  • Outils chargés dans le préfixe : tout changement à leur égard invalide le cache. Cela se produit quand la recherche d'outils n'est pas disponible ou est désactivée, comme sur les modèles Google Cloud's Agent Platform antérieurs à la génération Claude 4.5, avec une passerelle ANTHROPIC_BASE_URL personnalisée, ou sur un déploiement Microsoft Foundry hébergé sur Azure une fois que Claude Code détecte que le déploiement rejette la recherche d'outils. Cela se produit également pour un serveur ou un outil marqué alwaysLoad, et pour les définitions conservées en avant par le chargement basé sur le seuil.

Quand les outils se chargent dans le préfixe, la cause la plus courante d'une invalidation est un serveur qui se connecte ou se déconnecte en cours de session, ce qui peut se produire sans aucune action de votre part : le processus d'un serveur stdio se termine, une session HTTP expire, ou un serveur se reconnecte automatiquement après une défaillance transitoire. Un serveur connecté peut également envoyer une mise à jour d'outil dynamique qui change sa liste d'outils.

Éditer votre configuration MCP ne change pas le cache en soi. La nouvelle configuration ne prend effet qu'après un redémarrage, c'est à ce moment que le serveur se connecte ou se déconnecte.

Activer ou désactiver un plugin

Quand vous activez ou désactivez un plugin, ce que le changement coûte dépend des types de composants que le plugin fournit. Les cas ci-dessous couvrent chaque type de composant, quand Claude Code applique le changement, et ce qui se passe quand vous désactivez un plugin à nouveau dans la même session.

Composants de plugin qui conservent le cache

Claude Code n'invalide jamais le cache pour les skills, commandes, agents, hooks, moniteurs ou thèmes d'un plugin. Il ajoute leur contenu après la conversation existante, donc la requête suivante paie pour ce contenu et lit toujours tout ce qui le précède à partir du cache.

Plugins qui fournissent des serveurs MCP

Quand vous activez ou désactivez un plugin qui fournit des serveurs MCP, Claude Code suit les mêmes règles que quand vous connectez ou déconnectez un serveur MCP :

  • Si Claude Code diffère les outils du serveur, il conserve le cache.
  • Si Claude Code les charge dans le préfixe, la requête suivante relit la conversation entière.

Plugins d'intelligence de code

Quand vous activez un plugin d'intelligence de code, Claude obtient l'outil LSP.

Quand les changements de plugin s'appliquent

Claude Code applique un changement de plugin quand vous exécutez /reload-plugins ou démarrez une nouvelle session. Vous payez le coût, qu'il s'agisse d'annonces ajoutées ou d'une relecture complète, au premier tour après l'application du changement, pas quand vous exécutez /plugin enable ou /plugin disable. Claude Code peut également appliquer un changement de son propre chef dans trois cas :

  • Pour un plugin avec une source command, Claude Code peut recharger le plugin lui-même.
  • Quand vous installez un plugin à partir de l'interface /plugin, Claude Code peut l'activer pendant l'installation. Claude Code vous indique dans le résumé d'installation s'il l'a fait ou s'il faut exécuter /reload-plugins.
  • Quand vous déplacez la session avec /cd sur v2.1.246 ou ultérieur, Claude Code applique les plugins que les paramètres du nouveau répertoire activent dans le cadre du déplacement, sans l'avertissement de relecture complète qui accompagne un /reload-plugins.

Quand vous exécutez /reload-plugins et que le rechargement déclencherait une relecture complète, Claude Code affiche un avertissement et n'applique pas le rechargement. Réexécutez-le avec --force pour appliquer le rechargement de toute façon.

Plugins que vous activez puis désactivez dans une session

Quand vous désactivez un plugin que vous avez activé plus tôt dans la session, Claude Code restaure la forme de requête précédente. Si ce préfixe se trouve toujours dans sa durée de vie du cache, la requête suivante lit l'entrée de cache plus ancienne au lieu de la reconstruire.

Refuser un outil entier

Ajouter un nom d'outil simple comme Bash ou WebFetch comme règle de refus supprime cet outil du contexte de Claude entièrement. Claude Code charge les définitions d'outils intégrés dans la couche du prompt système, donc ajouter ou supprimer l'une de ces règles en cours de session invalide le cache. Claude Code applique le changement à la requête suivante, que vous l'ajoutiez via /permissions ou en éditant un fichier de paramètres directement. Cela inclut une règle que vous ajoutez via /permissions au milieu d'un tour.

Seule une règle de refus qui correspond à la position du nom d'outil a cet effet : un nom d'outil simple, la forme équivalente Bash(*), ou un glob de nom d'outil comme "*". Un glob qui correspond uniquement aux outils MCP, comme "mcp__*", supprime ces outils de la même manière mais laisse le cache intact quand les outils correspondants sont différés, la valeur par défaut, puisque les définitions différées n'étaient jamais dans le préfixe mis en cache. Les règles de refus délimitées comme Bash(rm *), et toutes les règles d'autorisation et de demande, ne changent pas les outils que Claude voit. Claude Code les vérifie quand Claude tente un appel, laissant le préfixe intact.

Modifier le style de sortie

Le style de sortie fait partie du prompt système. Quand vous changez de style en cours de session avec /config ou le paramètre outputStyle, Claude utilise le nouveau style à partir de votre message suivant, et cette requête lit l'historique de conversation entier sans cache hits. Pour garder ce coût petit, changez de style avant votre premier message dans une session ou juste après /clear ou /compact, quand il y a peu ou pas d'historique de conversation à relire.

Avant la v2.1.251, un changement de style en cours de session conservait le cache mais ne s'appliquait qu'après avoir exécuté /clear ou démarré une nouvelle session.

Compacter la conversation

La compaction remplace votre historique de messages par un résumé. Par conception, cela invalide la couche conversation, puisque la requête suivante a un nouvel historique plus court qui ne partage pas de préfixe avec l'ancien. Claude Code réutilise la couche du prompt système et recharge le contexte du projet à partir du disque, qui ne cache que si CLAUDE.md et la mémoire sont inchangés depuis le début de la session.

Pour produire le résumé, Claude Code envoie une requête unique avec le même prompt système, les mêmes outils et le même historique que votre conversation, plus une instruction de résumé ajoutée comme dernier message utilisateur. Tant que le cache est chaud, cette requête lit votre préfixe à partir du cache, donc une /compact en cours de session coûte une fraction de ce que la taille du contexte suggère et passe la plupart de son temps à générer le résumé.

Après une pause plus longue que la durée de vie du cache, il n'y a pas de cache à lire, donc la requête de résumé retraite l'historique complet en tant qu'entrée non mise en cache. C'est pourquoi /compact coûte le plus quand vous reprenez une ancienne session. Dans les deux cas, chaud et froid, le tour après compaction reconstruit le cache de conversation uniquement pour le résumé beaucoup plus court, donc ce tour n'est pas la partie lente.

Accumuler de nombreuses images

L'API limite le nombre d'images et de PDF que chaque requête peut contenir. Pour les chiffres actuels, voir Limites de requête dans la documentation de l'API. Claude Code limite également la taille totale des images et des PDF dans une requête, donc les grandes captures d'écran atteignent la limite avec moins d'images que les petites.

Quand la requête suivante dépasserait l'une ou l'autre limite, Claude Code supprime un lot des images et des PDF les plus anciens de ce qu'il envoie, ce qui libère de la place pour plus avant d'avoir besoin d'en supprimer à nouveau. Claude ne peut plus voir les images supprimées. Si Claude en a besoin à nouveau, partagez-la à nouveau.

Supprimer des images change les messages qui les contenaient, donc la requête suivante retraite la conversation à partir du plus ancien de ces messages. Parce que Claude Code supprime un lot à la fois, vous voyez un tour plus lent par lot plutôt qu'un avec chaque nouvelle capture d'écran.

Mettre à niveau Claude Code

Une nouvelle version de Claude Code met généralement à jour le prompt système ou les définitions d'outils, donc la première requête après une mise à niveau reconstruit le cache à partir du début. La mise à jour automatique télécharge les nouvelles versions en arrière-plan mais les applique au prochain lancement, jamais en cours de session, donc vous voyez cela comme un premier tour sans cache après redémarrage plutôt qu'une surprise pendant une session. Définissez DISABLE_AUTOUPDATER=1 pour contrôler quand les mises à niveau s'appliquent.

Actions qui conservent le cache

Ces actions ajoutent soit à la fin de la conversation, soit ne touchent pas du tout la requête. Certaines d'entre elles, comme éditer CLAUDE.md, conservent le cache pour la même raison que le changement ne parvient pas à la session en cours jusqu'à /clear, /compact, ou un redémarrage.

Éditer des fichiers dans votre référentiel

Le contenu des fichiers entre en contexte uniquement quand Claude les lit, et les lectures s'ajoutent à la conversation. Éditer un fichier que Claude a précédemment lu ne change pas rétroactivement la lecture antérieure dans l'historique. Au lieu de cela, Claude Code ajoute un <system-reminder> notant que le fichier a changé, et Claude le relit si nécessaire.

Éditer CLAUDE.md en cours de session

Vos fichiers CLAUDE.md au niveau de la racine du projet et au niveau utilisateur sont lus une fois au démarrage de la session et conservés en mémoire. Les éditer en cours de session n'invalide pas le cache, mais l'édition ne s'applique pas non plus. Claude continue de travailler avec la version qui a été chargée au démarrage de la session. Le nouveau contenu se charge au prochain /clear, /compact, ou redémarrage.

Les fichiers CLAUDE.md imbriqués dans les sous-répertoires et les règles avec frontmatter paths: se chargent plus tard, quand Claude lit pour la première fois un fichier correspondant. Éditer un avant qu'il se charge prend effet. Après son chargement, le contenu fait partie de l'historique de conversation, donc une édition en cours de session ne le change pas rétroactivement.

Changer le mode de permission

Basculer entre les modes de permission, comme du défaut à accepter les éditions, ne change pas le prompt système ou les définitions d'outils, donc les changements de mode sont sûrs pour le cache. L'exception est le mode plan avec le paramètre de modèle opusplan, qui bascule le modèle entre Opus et Sonnet quand vous entrez ou quittez le mode plan. Cela rend le basculement de mode un changement de modèle.

Invoquer des compétences et des commandes

Les compétences et les commandes injectent leurs instructions comme messages utilisateur au point d'invocation. Rien d'antérieur dans la conversation ne change.

Exécuter `/recap`

/recap génère un résumé pour l'affichage dans votre terminal. Contrairement à /compact, il ajoute le résumé comme sortie de commande plutôt que de remplacer votre historique de messages, de sorte que le préfixe en cache reste intact.

Rembobiner la conversation

/rewind tronque votre conversation jusqu'à un tour antérieur. L'historique restant est le même contenu à partir duquel le cache a été construit à ce moment, et les couches du prompt système et du contexte du projet sont inchangées, donc la requête suivante atteint l'entrée de cache antérieure. Chaque tour depuis a lu ce préfixe, ce qui a gardé l'entrée active même si le tour original était plus loin que le TTL.

Restaurer les points de contrôle de fichiers aux côtés de la conversation n'a aucun effet séparé sur le cache. Le contenu des fichiers entre en contexte uniquement quand Claude les lit, comme éditer des fichiers dans votre référentiel.

Durée de vie du cache

Les préfixes en cache expirent après une période d'inactivité. Chaque requête qui atteint le cache réinitialise le minuteur, de sorte que le cache reste actif tant que vous continuez à travailler. Après un écart assez long, la requête suivante recalcule l'entrée complète et rétablit le cache, ce qui est pourquoi le premier tour après s'être éloigné peut être notablement plus lent.

Sur un plan Pro ou Max, lorsque vous reprenez une grande session après une longue pause, Claude Code propose de reprendre à partir d'un résumé afin que les requêtes ultérieures ne portent pas l'historique complet.

Le time to live (TTL) contrôle la durée de l'écart que le cache survit. L'API en offre deux : un TTL de cinq minutes, et un TTL d'une heure qui garde le cache actif pendant les pauses plus longues mais facture les écritures de cache à un taux plus élevé. Le TTL plus long aide quand vous laissez une session inactive et y revenez, car vous évitez le retraitement qu'un préfixe expiré coûte. Cela coûte plus cher lors de courtes rafales de travail qui ne restent jamais inactives au-delà de cinq minutes, où le taux d'écriture plus élevé s'applique et la durée de vie du cache plus longue reste inutilisée.

Quel TTL chaque requête obtient

Claude Code décide du TTL par requête, et chaque requête se situe dans l'un de deux compartiments fixes :

  • Conversation principale : vos tours interactifs, les exécutions non interactives -p, et les tours Agent SDK, plus les assistants que Claude Code exécute en ligne avec eux
  • Tout le reste : les requêtes que Claude Code effectue en dehors de cette conversation, telles que les sous-agents, les workflows, les coéquipiers en processus, les forks, la compaction, et les titres de session

À moins que vous ne choisissiez vous-même un TTL, Claude Code demande le TTL d'une heure uniquement sur un abonnement Claude dans l'utilisation incluse de votre plan. Là, il demande l'heure pour la conversation principale, plus un petit ensemble de requêtes d'assistance que Anthropic contrôle côté serveur. Ce tableau donne le TTL par défaut de chaque compartiment selon les deux types de facturation.

Compartiment de requête Abonnement Claude, dans l'utilisation du plan Crédits d'utilisation, clé API, ou fournisseur cloud
Conversation principale Une heure Cinq minutes
Tout le reste Cinq minutes, sauf les requêtes d'assistance contrôlées par le serveur, qui obtiennent une heure Cinq minutes

Une fois que vous dépassez la limite d'utilisation de votre plan et que Claude Code puise dans les crédits d'utilisation, vous êtes facturé pour cette utilisation, donc Claude Code baisse la conversation principale au TTL de cinq minutes moins cher. Pour conserver le TTL d'une heure là, choisissez le TTL vous-même.

Choisissez le TTL vous-même

Vous pouvez définir un TTL pour l'un ou l'autre compartiment. Chaque contrôle prend 5m ou 1h, et Claude Code ignore toute autre valeur.

Les deux paramètres et les deux variables d'environnement nécessitent Claude Code v2.1.242 ou ultérieur. Si vous vous connectez avec une clé API ou utilisez un fournisseur cloud, définissez promptCacheTtl sur 1h pour donner à la conversation principale un cache d'une heure. Les requêtes en dehors de celle-ci conservent la valeur par défaut de cinq minutes jusqu'à ce que vous choisissiez également un TTL pour ce compartiment.

Lorsque plusieurs contrôles s'appliquent, Claude Code prend la première correspondance dans cet ordre :

  1. FORCE_PROMPT_CACHING_5M=1, qui force cinq minutes pour les deux compartiments
  2. La variable d'environnement du compartiment
  3. Le paramètre du compartiment
  4. Pour les requêtes d'un sous-agent, la valeur cacheTtl dans le champ frontmatter experimental du sous-agent, qui nécessite Claude Code v2.1.248 ou ultérieur. Claude Code ignore un 1h là tandis que votre abonnement Claude utilise des crédits d'utilisation
  5. ENABLE_PROMPT_CACHING_1H=1, qui demande une heure pour les deux compartiments
  6. La valeur par défaut pour le compartiment de la requête

Définissez FORCE_PROMPT_CACHING_5M=1 quand vous déboguez le comportement du cache, comparez les deux TTL, ou remplacez un TTL plus long défini dans les paramètres gérés.

Pour confirmer quel TTL les écritures de cache de votre conversation principale ont utilisé, exécutez claude -p "hello" --output-format json et lisez usage.cache_creation dans le résultat. Claude Code rapporte les écritures de cache d'une heure sous ephemeral_1h_input_tokens et les écritures de cache de cinq minutes sous ephemeral_5m_input_tokens.

Via une passerelle LLM que vous définissez avec ANTHROPIC_BASE_URL, une partie de la requête d'une heure voyage dans l'en-tête anthropic-beta, donc configurez la passerelle pour transférer cet en-tête inchangé. Le TTL d'une heure n'est pas disponible via la passerelle des applications Claude. Sur Amazon Bedrock, le support du prompt caching, la longueur minimale du préfixe cacheable, et la disponibilité du TTL d'une heure varient tous selon le modèle. Si les comptages de jetons de cache restent à zéro, vérifiez les modèles, régions et limites pris en charge dans la documentation Amazon Bedrock.

Portée du cache

Dans Claude Code, le cache est effectivement limité à une machine et un répertoire. Le prompt système intègre le répertoire de travail, la plateforme, le shell, la version du système d'exploitation, et les chemins de mémoire automatique, donc deux sessions dans des répertoires différents construisent des préfixes différents et manquent le cache de l'autre. Cela inclut les worktrees du même référentiel, puisque chaque worktree a son propre répertoire de travail.

Les sessions que vous exécutez en parallèle dans le même répertoire construisent des préfixes correspondants et lisent le cache de l'autre. Les sessions séquentielles partagent le préfixe uniquement quand l'instantané du statut git au démarrage correspond, puisque le prompt système capture également la branche et les commits récents.

Le cache API sous-jacent est plus large. Les caches sont isolés entre les organisations, et sur certains fournisseurs, entre les espaces de travail au sein d'une organisation. Dans ces limites, deux requêtes quelconques avec le même modèle et préfixe lisent le même cache. Pour les appelants du SDK Agent exécutant des flottes de processus automatisés, voir améliorer le prompt caching entre les utilisateurs et les machines pour supprimer les sections par machine du prompt système et partager le cache entre les machines.

Vérifier les performances du cache

Les performances du cache s'affichent comme deux comptages de jetons que l'API rapporte sur chaque réponse. Le moyen le plus direct de les regarder en direct est un script de ligne d'état qui lit l'objet current_usage :

Champ Signification
cache_creation_input_tokens Jetons écrits dans le cache à ce tour, facturés au taux d'écriture du cache
cache_read_input_tokens Jetons servis à partir du cache à ce tour, facturés à environ 10 % du taux d'entrée standard

Un ratio lecture-création élevé signifie que le caching fonctionne bien. Si la création reste élevée tour après tour, quelque chose change dans votre préfixe. La section Actions qui invalident le cache énumère les causes habituelles.

Pour un résumé par session, exécutez /usage. Après la première réponse de la conversation principale, Claude Code ajoute une ligne Prompt cache (main) au bloc Session, affichant le ratio de succès de la session, le nombre d'échecs et si le cache est chaud en ce moment. Un script de ligne d'état peut lire les mêmes chiffres à partir de l'objet prompt_cache. Les deux nécessitent Claude Code v2.1.251 ou ultérieur.

La ligne Prompt cache (main) nomme également la cause probable du dernier échec lorsque Claude Code peut en identifier une, par exemple likely cause: tool definitions changed. Le texte de cause probable nécessite Claude Code v2.1.260 ou ultérieur.

Pour la visibilité dans une organisation, l'exportateur OpenTelemetry rapporte les jetons de lecture et de création du cache par utilisateur et session. Voir Surveiller l'utilisation pour la référence des attributs de métrique et d'événement.

Sous-agents et le cache

Un sous-agent démarre sa propre conversation avec son propre prompt système et ensemble d'outils, séparé du parent. Sa première requête ne lit pas le cache du parent, car les deux préfixes diffèrent, et il réchauffe son propre cache à travers ses tours. Les sous-agents se situent en dehors du bucket TTL de la conversation principale, donc ils obtiennent cinq minutes même sur un abonnement jusqu'à ce que vous choisissiez un plus long.

Le cache du parent n'est pas affecté. Du côté du parent, l'appel du sous-agent et le résultat s'ajoutent à la conversation, laissant le préfixe du parent intact.

Un fork, en contraste, hérite du prompt système du parent, des outils, et de l'historique de conversation exactement, donc sa première requête lit le cache du parent.

D'autres requêtes peuvent également lire un préfixe qu'une requête antérieure a mis en cache :

  • Copies de session : une session que vous copiez avec /fork reçoit son instruction d'isolation en tant que message à la fin de la conversation copiée, donc le cache que la conversation originale a construit reste intact.
  • Compaction : l'appel de résumé décrit dans Compacter la conversation utilise la même approche de partage de préfixe.
  • Fan-outs de workflow : dans un fan-out de workflow d'agents de même préfixe, Claude Code retient tous sauf le premier pendant jusqu'à 5 secondes par défaut, donc leurs premières requêtes peuvent lire le préfixe que le premier agent a mis en cache.

Désactiver le prompt caching

Désactiver le caching est occasionnellement utile quand on débogue le comportement du caching avec un modèle ou un fournisseur spécifique. Pour l'éteindre, définissez l'une de ces variables d'environnement à 1 :

Variable Effet
DISABLE_PROMPT_CACHING Désactiver pour tous les modèles
DISABLE_PROMPT_CACHING_HAIKU Désactiver pour Haiku uniquement
DISABLE_PROMPT_CACHING_SONNET Désactiver pour Sonnet uniquement
DISABLE_PROMPT_CACHING_OPUS Désactiver pour Opus uniquement
DISABLE_PROMPT_CACHING_FABLE Désactiver pour Fable uniquement

Pour définir la politique de caching dans une organisation, mettez l'une de ces variables ou les variables TTL dans le bloc env des paramètres gérés. Pour un usage normal, laissez le caching activé.