SpyBara
Go Premium

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

This page contains 149 additions and 47 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

Wie Claude Code Prompt Caching nutzt

Claude Code verwaltet Prompt Caching automatisch. Erfahren Sie, warum ein Modellwechsel einen langsamen unkachedten Turn auslöst, was /compact kostet, warum CLAUDE.md-Änderungen mid-session nicht angewendet werden, und wie Sie Ihre Cache-Hit-Rate überprüfen.

Prompt Caching macht Claude Code schneller und kostengünstiger. Ohne Caching würde die API Ihre vollständige Historie bei jedem Turn neu verarbeiten. Mit Caching nutzt sie das bereits Verarbeitete wieder, berechnet das erneute Lesen zum Cached-Token-Satz ab und verarbeitet vollständig nur das, was sich geändert hat.

Claude Code verwaltet Prompt Caching für Sie, es sei denn, Sie deaktivieren es. Es ist dennoch nützlich zu verstehen, wie Prompt Caching funktioniert, da einige Aktionen den Cache ungültig machen und die nächste Antwort langsamer und teurer machen, während er sich neu aufbaut. Diese Seite behandelt, welche Aktionen das sind, warum einige Einstellungen auf einen Neustart warten, um angewendet zu werden, und wie Sie die Cache-Leistung überprüfen, wenn die Nutzung hoch aussieht.

Wie der Cache organisiert ist

Jedes Mal, wenn Sie eine Nachricht in Claude Code senden, wird eine neue API-Anfrage gestellt. Das Modell merkt sich nichts zwischen Anfragen, daher sendet Claude Code den vollständigen Kontext erneut: den System-Prompt, Ihren Projektkontext, jede vorherige Nachricht und jedes Tool-Ergebnis sowie Ihre neue Nachricht. Neuer Inhalt wird am Ende angehängt, was bedeutet, dass der größte Teil jeder Anfrage identisch mit der vorherigen ist. Prompt Caching ist, wie die API vermeidet, den Teil neu zu verarbeiten, der sich nicht geändert hat.

Die API cached durch Abgleich des Anfangs jeder Anfrage, genannt das Präfix, gegen kürzlich verarbeitete Inhalte. Bei einem normalen Turn ist das Präfix die gesamte vorherige Anfrage und nur der neueste Austausch ist neu. Der Abgleich ist exakt, daher wird alles nach einer Änderung im Präfix neu berechnet. Es gibt kein Pro-Datei- oder Pro-Segment-Caching. Siehe wie Prompt Caching funktioniert in der API-Referenz für den zugrunde liegenden Mechanismus.

Vier Turns werden als wachsende horizontale Balken angezeigt. Die Anfrage jedes Turns enthält alles aus dem vorherigen Turn plus den neuesten Austausch am Ende angehängt. Bei den Turns zwei und drei wird das unveränderte Präfix aus dem Cache gelesen und nur der neue Austausch verarbeitet. Bei Turn vier hat sich der System-Prompt geändert, daher stimmt das Präfix nicht mehr überein und die gesamte Anfrage wird neu verarbeitet und geschrieben. Vier Turns werden als wachsende horizontale Balken angezeigt. Die Anfrage jedes Turns enthält alles aus dem vorherigen Turn plus den neuesten Austausch am Ende angehängt. Bei den Turns zwei und drei wird das unveränderte Präfix aus dem Cache gelesen und nur der neue Austausch verarbeitet. Bei Turn vier hat sich der System-Prompt geändert, daher stimmt das Präfix nicht mehr überein und die gesamte Anfrage wird neu verarbeitet und geschrieben.

Um das Beste aus dem Präfix-Abgleich herauszuholen, ordnet Claude Code jede Anfrage so, dass Inhalte, die sich zwischen Turns selten ändern, zuerst kommen:

Ebene Inhalt Ändert sich wenn
System-Prompt Kernanleitungen, Tool-Definitionen, Ausgabestil Der Satz der geladenen Tool-Definitionen ändert sich, Sie wechseln den Ausgabestil, oder Claude Code wird aktualisiert
Projektkontext CLAUDE.md, automatisches Memory, unscoped Rules Session startet, oder nach /clear oder /compact
Konversation Ihre Nachrichten, Claudes Antworten, Tool-Ergebnisse Jeden Turn

Eine Änderung der Konversationsebene lässt den System-Prompt und Projektkontext gecacht. Eine Änderung des System-Prompts macht alles ungültig, da der gesamte spätere Inhalt nun hinter einem anderen Präfix sitzt. Die dritte Spalte gibt häufige Auslöser statt einer vollständigen Liste an, und die Abschnitte unten behandeln den vollständigen Satz.

Die Präfix-Abgleich-Regel erklärt die meisten Verhaltensweisen auf dieser Seite. Plan Mode und Skill Loading hängen beispielsweise ihre Anweisungen als Konversationsnachrichten an, daher bleibt das gecachte Präfix intakt.

Zwei Einstellungen erscheinen nicht in der Ebenen-Tabelle, beeinflussen aber dennoch, was gecacht bleibt:

  • Modell: Jedes Modell hat seinen eigenen Cache. Das Wechseln von Modellen berechnet die gesamte Anfrage neu, auch wenn der Inhalt identisch ist. Siehe Modelle wechseln unten.
  • Effort Level: Bei den meisten Modellen hat jedes Effort Level seinen eigenen Cache, daher berechnet das Ändern mid-session die gesamte Anfrage neu. Bei Fable 5.1 mit einem API-Schlüssel oder einem Claude-Abonnement bleibt der Cache standardmäßig intakt. Siehe Effort Level ändern unten.

Wo der Cache lebt

Caching findet server-seitig in der Infrastruktur statt, die Ihr Modell bedient. Wo das ist, hängt davon ab, wie Sie sich authentifizieren:

  • API-Schlüssel, Claude-Abonnement oder Claude Platform on AWS: Der Cache lebt in Anthropics Infrastruktur, zugänglich über die Claude API
  • Amazon Bedrock oder Google Cloud's Agent Platform: Der Cache lebt in der Serving-Infrastruktur Ihres Cloud-Providers
  • Microsoft Foundry: Hängt von der Hosting-Option der Bereitstellung ab. Auf Azure bereitgestellte Deployments werden auf Azure-Infrastruktur bedient; auf Anthropic bereitgestellte Deployments werden auf Anthropics Infrastruktur bedient
  • Benutzerdefinierte ANTHROPIC_BASE_URL oder LLM Gateway: Der Cache lebt dort, wo Ihre Anfragen weitergeleitet werden, und ob Caching funktioniert, hängt vom Gateway ab

Claude Code hängt auch System-Kontext mid-conversation an, wie Dateiänderungsbenachrichtigungen, und markiert diesen Block zum Caching auf jedem Provider und jeder Verbindung.

Am eigenen Endpunkt des Providers cachen Amazon Bedrock und sein Mantle-Endpunkt, Google Clouds Agent Platform und Microsoft Foundry den Block auf die gleiche Weise wie die Claude API.

Wenn Ihre Anfragen durch ein LLM Gateway, eine benutzerdefinierte ANTHROPIC_BASE_URL oder eine Cloud-Provider-Base-URL-Überschreibung wie ANTHROPIC_BEDROCK_BASE_URL geleitet werden, hängt das, was gecacht bleibt, davon ab, wie das Gateway die cache_control-Marker handhabt, die Claude Code sendet:

  • Leitet sie unverändert weiter: Der Block und Ihre Konversation cachen auf die gleiche Weise wie am eigenen Endpunkt des Providers.
  • Lehnt die markierte Anfrage mit einem 400-Fehler ab, der cache_control nennt: Claude Code sendet die Anfrage erneut mit dem Marker, der vom Block auf Ihre letzte Konversationsnachricht verschoben wird, und behält ihn dort für den Rest der Konversation. Der Block wird als nicht gecachte Eingabe abgerechnet; Ihre Konversation bleibt gecacht.
  • Entfernt die Marker, während es Erfolg zurückgibt: Ihre gesamte Konversationshistorie wird auf jedem Turn als nicht gecachte Eingabe abgerechnet. Ein Gateway, das Block-Form-Systeminhalt in einen einfachen String konvertiert, lässt den Marker auf die gleiche Weise fallen.

Für das, was jeder Provider speichert und verarbeitet, siehe Datennutzung. Wo immer der Cache lebt, Einträge verfallen nach einer Inaktivitätsperiode, und Cache-Lebensdauer unten behandelt die TTL und wie Sie sie verlängern.

Aktionen, die den Cache ungültig machen

Diese Aktionen führen dazu, dass die nächste Anfrage einen Teil oder den gesamten Cache verfehlt. Sie sehen einen einmaligen langsameren, teureren Turn, danach wird das neue Präfix gecacht. Die meisten davon sind mid-task vermeidbar, sobald Sie wissen, dass sie Kosten haben. Ein Modellwechsel kann sich kostenlos anfühlen, bis Sie den langsameren Turn bemerken, der folgt.

Modelle wechseln

Jedes Modell hat seinen eigenen Cache. Das Wechseln mit /model bedeutet, dass die nächste Anfrage die gesamte Konversationshistorie ohne Cache-Hits liest, obwohl der Inhalt identisch ist.

Wenn Sie /model im Terminal ausführen, fordert Claude Code Sie auf, den Wechsel nur zu bestätigen, während der Cache noch warm ist. Der Cache bleibt warm für einen Cache-TTL nach dem letzten Request von Claude Code in dieser Konversation oder der letzten Antwort von Claude. Sobald diese Zeit verstrichen ist, ist der Cache abgelaufen, daher wechselt Claude Code ohne zu fragen.

Vor v2.1.238 prüfte Claude Code den Cache-TTL nicht und fragte auch nach dem Ablauf des Caches.

Sie können diese Bestätigung auch mit einem PreModelSwitch Hook erforderlich machen oder überspringen.

Die opusplan Modelleinstellung wird zu Opus während Plan Mode und Sonnet während der Ausführung aufgelöst, daher ist jeder Plan-Mode-Toggle ein Modellwechsel und startet einen frischen Cache.

Automatisches Modell-Fallback auf Fable 5.1, Fable 5 und Opus 5 ist auch ein Modellwechsel. Wenn ein Sicherheitsklassifizierer eine Anfrage kennzeichnet und die gekennzeichnete Kategorie ein Fallback-Modell hat, führt Claude Code die Anfrage auf diesem Modell erneut aus und die Session wird dort fortgesetzt.

Anstrengungsstufe ändern

Bei den meisten Modellen bedeutet das Ändern der Anstrengungsstufe mid-session, dass die nächste Anfrage die gesamte Konversationshistorie ohne Cache-Hits liest. Während der Cache noch warm ist, fordert Claude Code Sie auf, die Änderung zuerst zu bestätigen.

Bei Fable 5.1 mit einem API-Schlüssel oder Claude-Abonnement behält das Ändern der Anstrengung den Cache, und Claude Code wendet die neue Stufe ohne Nachfrage an. Dies gilt nicht auf Amazon Bedrock, Google Cloud's Agent Platform oder einem Claude-Apps-Gateway, oder wenn Sie CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS setzen oder Ihre Organisation eine HIPAA-Konfiguration hat.

Vor v2.1.260 machte das Ändern der Anstrengung auf Fable 5.1 mit einem API-Schlüssel oder Claude-Abonnement auch den Cache ungültig.

Fast Mode aktivieren

Das Aktivieren von Fast Mode fügt einen Request-Header hinzu, der Teil des Cache-Schlüssels ist, daher liest die erste Anfrage, die Claude Code mit aktiviertem Fast Mode sendet, die gesamte Konversationshistorie ohne Cache-Hits. Claude Code setzt diesen Header einmal, wenn ein Turn startet, und behält ihn für den ganzen Turn, daher wenn Sie Fast Mode aktivieren, während Claude arbeitet, tritt der Cache-Miss vom Header beim ersten Request Ihres nächsten Turns auf. Diese unkachedten Input-Token werden zu Fast-Mode-Raten abgerechnet, weshalb das Aktivieren zu Beginn einer Session weniger kostet als das Aktivieren tief in einer langen Session. Wenn Ihr aktuelles Modell Fast Mode nicht unterstützt, wechselt das Aktivieren von Fast Mode auch Ihr Modell, und dieser Wechsel startet von selbst einen frischen Cache beim nächsten Request im laufenden Turn.

Die Kosten fallen einmal pro Konversation an. Nach dem ersten Fast-Mode-Turn sendet Claude Code weiterhin den Header und variiert nur die Speed-Einstellung der Anfrage, die nicht Teil des Cache-Schlüssels ist. Das Ausschalten von Fast Mode, das automatische Fallback auf Standardgeschwindigkeit nach einem Rate Limit und das spätere Wiedereinschalten behalten den Cache. Wenn Sie Nutzungsguthaben mid-session aufbrauchen, wiederholt Claude Code jeden abgelehnten Fast-Mode-Request auf die gleiche Weise mit Standardgeschwindigkeit, daher behält auch dieses Fallback den Cache. /clear und /compact setzen dies zurück, da sie den Cache an diesen Punkten ohnehin neu aufbauen.

Verbinden oder Trennen eines MCP-Servers

Tool-Definitionen sitzen in der System-Prompt-Ebene, daher wird der Cache ungültig, wenn sich die Menge der Tool-Definitionen in der Anfrage zwischen Turns ändert. Das Umschalten des Advisor-Tools ist eine Ausnahme: Seine Definition sitzt nach dem Cache-Breakpoint, daher behält das Aktivieren oder Deaktivieren von /advisor das gecachte Präfix intakt. Ob eine MCP-Server-Änderung dies bewirkt, hängt davon ab, ob ihre Tools durch Tool-Suche aufgeschoben werden oder in das Präfix geladen werden:

  • Aufgeschobene Tools, die Standardeinstellung auf unterstützten Modellen: Ein Server, der sich verbindet, trennt oder seine Tool-Liste ändert, hängt nur neue Inhalte an und stört nichts, das bereits gecacht ist.
  • Tools, die in das Präfix geladen werden: Jede Änderung daran macht den Cache ungültig. Dies geschieht, wenn Tool-Suche nicht verfügbar oder deaktiviert ist, z. B. auf Google Cloud's Agent Platform-Modellen früher als die Claude 4.5-Generation, mit einem benutzerdefinierten ANTHROPIC_BASE_URL-Gateway, oder auf einer Microsoft Foundry-Bereitstellung auf Azure, sobald Claude Code erkennt, dass die Bereitstellung Tool-Suche ablehnt. Es geschieht auch für einen Server oder ein Tool, das als alwaysLoad markiert ist, und für Definitionen, die von schwellenwertbasiertem Laden im Voraus beibehalten werden.

Wenn Tools in das Präfix geladen werden, ist die häufigste Ursache einer Ungültigmachung ein Server, der sich mid-session verbindet oder trennt, was ohne Ihre Aktion geschehen kann: Ein Stdio-Server-Prozess beendet sich, eine HTTP-Session läuft ab, oder ein Server verbindet sich automatisch nach einem vorübergehenden Fehler wieder. Ein verbundener Server kann auch ein dynamisches Tool-Update pushen, das seine Tool-Liste ändert.

Das Bearbeiten Ihrer MCP-Konfiguration ändert den Cache nicht von selbst. Die neue Konfiguration wird erst nach einem Neustart wirksam, wenn sich der Server verbindet oder trennt.

Ein Plugin aktivieren oder deaktivieren

Wenn Sie ein Plugin aktivieren oder deaktivieren, hängen die Kosten der Änderung davon ab, welche Komponententypen das Plugin bereitstellt. Die folgenden Fälle behandeln jeden Komponententyp, wann Claude Code die Änderung anwendet, und was geschieht, wenn Sie ein Plugin später in der gleichen Session wieder deaktivieren.

Plugin-Komponenten, die den Cache behalten

Claude Code macht den Cache niemals ungültig für die Skills, Commands, Agents, Hooks, Monitore oder Themes eines Plugins. Es hängt deren Inhalt nach der vorhandenen Konversation an, daher zahlt die nächste Anfrage für diesen Inhalt und liest alles davor immer noch aus dem Cache.

Plugins, die MCP-Server bereitstellen

Wenn Sie ein Plugin aktivieren oder deaktivieren, das MCP-Server bereitstellt, folgt Claude Code den gleichen Regeln wie beim Verbinden oder Trennen eines MCP-Servers:

  • Wenn Claude Code die Tools des Servers aufschiebt, behält es den Cache.
  • Wenn Claude Code sie in das Präfix lädt, liest die nächste Anfrage die gesamte Konversation neu.

Code-Intelligence-Plugins

Wenn Sie ein Code-Intelligence-Plugin aktivieren, erhält Claude das LSP-Tool.

Wann Plugin-Änderungen angewendet werden

Claude Code wendet eine Plugin-Änderung an, wenn Sie /reload-plugins ausführen oder eine neue Session starten. Sie zahlen die Kosten, ob angehängte Ankündigungen oder ein vollständiges Neueinlesen, beim ersten Turn nach dem Anwenden der Änderung, nicht wenn Sie /plugin enable oder /plugin disable ausführen. Claude Code kann eine Änderung auch in drei Fällen von selbst anwenden:

  • Für ein Plugin mit einer command-Quelle kann Claude Code das Plugin selbst neu laden.
  • Wenn Sie ein Plugin aus der /plugin-Schnittstelle installieren, kann Claude Code es während der Installation aktivieren. Claude Code teilt Ihnen in der Installationszusammenfassung mit, ob es das tat oder ob Sie /reload-plugins ausführen sollen.
  • Wenn Sie die Session mit /cd verschieben auf v2.1.246 oder später, wendet Claude Code die Plugins an, die die Einstellungen des neuen Verzeichnisses aktivieren, als Teil der Verschiebung, ohne die vollständige Neueinlese-Warnung, die /reload-plugins hält.

Wenn Sie /reload-plugins ausführen und das Neustart würde ein vollständiges Neueinlesen auslösen, zeigt Claude Code eine Warnung an und wendet das Neustart nicht an. Führen Sie es mit --force erneut aus, um das Neustart trotzdem anzuwenden.

Plugins, die Sie aktivieren und dann in einer Session deaktivieren

Wenn Sie ein Plugin deaktivieren, das Sie früher in der Session aktiviert haben, stellt Claude Code die vorherige Request-Form wieder her. Wenn dieses Präfix noch innerhalb seiner Cache-Lebensdauer liegt, liest die nächste Anfrage stattdessen den älteren Cache-Eintrag, anstatt ihn neu zu erstellen.

Ein ganzes Tool ablehnen

Das Hinzufügen eines bloßen Tool-Namens wie Bash oder WebFetch als Ablehnungsregel entfernt dieses Tool vollständig aus Claudes Kontext. Claude Code lädt integrierte Tool-Definitionen in die System-Prompt-Ebene, daher macht das Hinzufügen oder Entfernen einer dieser Regeln mid-session den Cache ungültig. Claude Code wendet die Änderung beim nächsten Request an, egal ob Sie die Regel über /permissions hinzufügen oder durch direktes Bearbeiten einer Einstellungsdatei. Das schließt eine Regel ein, die Sie über /permissions in der Mitte eines Turns hinzufügen.

Nur eine Ablehnungsregel, die in der Tool-Name-Position passt, hat diese Auswirkung: ein bloßer Tool-Name, die äquivalente Bash(*) Form, oder ein Tool-Name-Glob wie "*". Ein Glob, der nur MCP-Tools passt, z. B. "mcp__*", entfernt diese Tools auf die gleiche Weise, behält aber den Cache intakt, wenn die gefundenen Tools aufgeschoben sind, die Standardeinstellung, da aufgeschobene Definitionen nie im gecachten Präfix waren. Scoped Ablehnungsregeln wie Bash(rm *) und alle Allow- und Ask-Regeln ändern nicht, welche Tools Claude sieht. Claude Code prüft sie, wenn Claude einen Aufruf versucht, wobei das Präfix intakt bleibt.

Ausgabestil ändern

Ausgabestil ist Teil des System-Prompts. Wenn Sie Stile mid-session mit /config oder der outputStyle-Einstellung wechseln, verwendet Claude den neuen Stil ab Ihrer nächsten Nachricht, und dieser Request liest die gesamte Konversationshistorie ohne Cache-Hits. Um diese Kosten klein zu halten, wechseln Sie Stile vor Ihrer ersten Nachricht in einer Session oder direkt nach /clear oder /compact, wenn es wenig oder keine Konversationshistorie zum Neueinlesen gibt.

Vor v2.1.251 behielt ein mid-session Stil-Wechsel den Cache, aber wurde nicht angewendet, bis Sie /clear ausführten oder eine neue Session starteten.

Konversation komprimieren

Komprimierung ersetzt Ihre Nachrichtenhistorie durch eine Zusammenfassung. Dies macht absichtlich die Konversationsebene ungültig, da die nächste Anfrage eine neue, kürzere Historie hat, die kein Präfix mit der alten teilt. Claude Code nutzt die System-Prompt-Ebene wieder und lädt den Projektkontext von der Festplatte neu, was nur Cache-Hits, wenn CLAUDE.md und Memory seit dem Session-Start unverändert sind.

Um die Zusammenfassung zu erstellen, sendet Claude Code einen separaten Request mit demselben System-Prompt, Tools und History wie Ihre Konversation, plus eine Zusammenfassungsanweisung, die als letzte Benutzernachricht angehängt wird. Während der Cache warm ist, liest dieser Request Ihr Präfix aus dem Cache, daher kostet ein mid-session /compact einen Bruchteil dessen, was die Kontextgröße nahelegt, und verbringt die meiste Zeit mit der Generierung der Zusammenfassung.

Nach einer Pause länger als die Cache-Lebensdauer gibt es keinen Cache mehr zum Lesen, daher verarbeitet der Zusammenfassungs-Request die vollständige Historie als unkachedten Input neu. Dies ist der Grund, warum /compact am meisten kostet, wenn Sie eine alte Session fortsetzen. In beiden Fällen, warm und kalt, baut der Turn nach der Komprimierung den Konversations-Cache nur für die viel kürzere Zusammenfassung neu auf, daher ist dieser Turn nicht der langsame Teil.

Viele Bilder sammeln

Die API begrenzt, wie viele Bilder und PDFs jeder Request tragen kann. Für die aktuellen Zahlen siehe Request-Limits in der API-Dokumentation. Claude Code begrenzt auch die Gesamtgröße der Bilder und PDFs in einem Request, daher erreichen große Screenshots das Limit mit weniger Bildern als kleine.

Wenn der nächste Request eines der Limits überschreiten würde, entfernt Claude Code einen Batch der ältesten Bilder und PDFs aus dem, was es sendet, was Platz für mehr schafft, bevor es wieder welche entfernen muss. Claude kann die entfernten Bilder nicht mehr sehen. Wenn Claude eines davon wieder braucht, teilen Sie es erneut.

Das Entfernen von Bildern ändert die Nachrichten, die sie hielten, daher verarbeitet der nächste Request die Konversation vom frühesten dieser Nachrichten an neu. Weil Claude Code einen Batch auf einmal entfernt, sehen Sie einen langsameren Turn pro Batch statt einen mit jedem neuen Screenshot.

Claude Code aktualisieren

Eine neue Claude Code-Version aktualisiert typischerweise den System-Prompt oder Tool-Definitionen, daher baut die erste Anfrage nach einem Upgrade den Cache von oben auf. Auto-Update lädt neue Versionen im Hintergrund herunter, wendet sie aber beim nächsten Start an, nie mid-session, daher sehen Sie dies als einen unkachedten ersten Turn nach dem Neustart statt als Überraschung während einer Session. Setzen Sie DISABLE_AUTOUPDATER=1, um zu kontrollieren, wann Upgrades angewendet werden.

Aktionen, die den Cache behalten

Diese Aktionen hängen entweder am Ende der Konversation an oder berühren die Anfrage überhaupt nicht. Einige davon, wie das Bearbeiten von CLAUDE.md, behalten den Cache aus demselben Grund, aus dem die Änderung die laufende Sitzung nicht erreicht, bis /clear, /compact oder ein Neustart erfolgt.

Dateien in Ihrem Repository bearbeiten

Dateiinhalte treten in den Kontext nur ein, wenn Claude sie liest, und Lesevorgänge hängen an der Konversation an. Das Bearbeiten einer Datei, die Claude zuvor gelesen hat, ändert nicht rückwirkend das frühere Lesen in der Historie. Stattdessen hängt Claude Code eine <system-reminder> an, die bemerkt, dass die Datei geändert wurde, und Claude liest sie erneut, wenn nötig.

CLAUDE.md mid-session bearbeiten

Ihre Projekt-Root- und Benutzer-Level-CLAUDE.md-Dateien werden einmal am Session-Start gelesen und im Speicher gehalten. Das Bearbeiten von ihnen mid-session macht den Cache nicht ungültig, aber die Bearbeitung wird auch nicht angewendet. Claude arbeitet weiterhin mit der Version, die am Session-Start geladen wurde. Der neue Inhalt wird beim nächsten /clear, /compact oder Neustart geladen.

Verschachtelte CLAUDE.md-Dateien in Unterverzeichnissen und Rules mit paths: Frontmatter werden später geladen, wenn Claude zum ersten Mal eine passende Datei liest. Das Bearbeiten einer vor dem Laden hat Auswirkungen. Nach dem Laden ist der Inhalt Teil der Konversationshistorie, daher ändert eine mid-session-Bearbeitung ihn nicht rückwirkend.

Berechtigungsmodus ändern

Das Wechseln zwischen Berechtigungsmodi, z. B. von Manual zu Accept Edits, ändert den System-Prompt oder Tool-Definitionen nicht, daher sind Modus-Wechsel Cache-sicher. Die Ausnahme ist Plan Mode mit der opusplan Modelleinstellung, die das Modell zwischen Opus und Sonnet wechselt, wenn Sie Plan Mode betreten oder verlassen. Das macht den Modus-Toggle zu einem Modellwechsel.

Skills und Commands aufrufen

Skills und Commands injizieren ihre Anweisungen als Benutzernachrichten am Punkt der Aufrufe. Nichts früher in der Konversation ändert sich.

Ausführen von `/recap`

/recap generiert eine Zusammenfassung zur Anzeige in Ihrem Terminal. Im Gegensatz zu /compact hängt es die Zusammenfassung als Befehlsausgabe an, anstatt Ihre Nachrichtenhistorie zu ersetzen, daher bleibt das gecachte Präfix intakt.

Konversation zurückspulen

/rewind schneidet Ihre Konversation auf einen früheren Turn zurück. Die verbleibende Historie ist derselbe Inhalt, aus dem der Cache zu diesem Punkt gebaut wurde, und die System-Prompt- und Projektkontext-Ebenen sind unverändert, daher trifft die nächste Anfrage den früheren Cache-Eintrag. Jeder Turn seitdem hat dieses Präfix gelesen, das den Eintrag warm hielt, auch wenn der ursprüngliche Turn länger her war als die TTL.

Das Wiederherstellen von Datei-Checkpoints zusammen mit der Konversation hat keine separate Auswirkung auf den Cache. Dateiinhalte treten in den Kontext nur ein, wenn Claude sie liest, dasselbe wie Dateien in Ihrem Repository bearbeiten.

Cache-Lebensdauer

Gecachte Präfixe verfallen nach einer Inaktivitätsperiode. Jede Anfrage, die den Cache trifft, setzt den Timer zurück, daher bleibt der Cache warm, solange Sie arbeiten. Nach einer langen genug Pause berechnet die nächste Anfrage die vollständige Eingabe neu und stellt den Cache wieder her, weshalb der erste Turn nach einer Pause noticeably langsamer sein kann.

Bei einem Pro- oder Max-Plan bietet Claude Code beim Fortsetzen einer großen Sitzung nach einer langen Pause die Möglichkeit, von einer Zusammenfassung fortzufahren, damit spätere Anfragen nicht die vollständige Historie tragen.

Die Time to Live (TTL) kontrolliert, wie lange eine Pause der Cache überlebt. Die API bietet zwei: eine fünf-Minuten-TTL und eine eine-Stunden-TTL, die den Cache durch längere Pausen warm hält, aber Cache-Schreibvorgänge zu einer höheren Rate abrechnet. Die längere TTL hilft, wenn Sie eine Sitzung untätig lassen und später zu ihr zurückkehren, da Sie die Neuverarbeitung eines abgelaufenen Präfix sparen. Sie kostet mehr bei kurzen Arbeitsphasen, die nie länger als fünf Minuten untätig sind, wo die höhere Schreibrate gilt und die längere Cache-Lebensdauer ungenutzt bleibt.

Welche TTL jede Anfrage erhält

Claude Code entscheidet die TTL pro Anfrage, und jede Anfrage fällt in einen von zwei festen Buckets:

  • Hauptkonversation: Ihre interaktiven Turns, nicht-interaktive -p-Läufe und Agent SDK Turns, plus die Helfer, die Claude Code inline mit ihnen ausführt
  • Alles andere: die Anfragen, die Claude Code außerhalb dieser Konversation macht, wie Subagenten, Workflows, In-Process-Teammates, Forks, Komprimierung und Sitzungstitel

Sofern Sie nicht selbst eine TTL wählen, fordert Claude Code die eine-Stunden-TTL nur bei einem Claude-Abonnement innerhalb der in Ihrem Plan enthaltenen Nutzung an. Dort fordert es die Stunde für die Hauptkonversation an, plus eine kleine Menge von Helfer-Anfragen, die Anthropic serverseitig kontrolliert. Diese Tabelle gibt die Standard-TTL jedes Buckets unter beiden Arten der Abrechnung an.

Anfrage-Bucket Claude-Abonnement, innerhalb der Plan-Nutzung Nutzungsguthaben, API-Schlüssel oder Cloud-Provider
Hauptkonversation Eine Stunde Fünf Minuten
Alles andere Fünf Minuten, außer den serverseitig kontrollierten Helfer-Anfragen, die eine Stunde erhalten Fünf Minuten

Sobald Sie das Nutzungslimit Ihres Plans überschreiten und Claude Code auf Nutzungsguthaben zurückgreift, wird diese Nutzung für Sie abgerechnet, daher senkt Claude Code die Hauptkonversation auf die günstigere fünf-Minuten-TTL. Um die eine-Stunden-TTL dort zu behalten, wählen Sie die TTL selbst.

Wählen Sie die TTL selbst

Sie können eine TTL für jeden Bucket setzen. Jedes Steuerelement nimmt 5m oder 1h an, und Claude Code ignoriert jeden anderen Wert.

Beide Einstellungen und beide Umgebungsvariablen erfordern Claude Code v2.1.242 oder später. Wenn Sie sich mit einem API-Schlüssel anmelden oder einen Cloud-Provider verwenden, setzen Sie promptCacheTtl auf 1h, um der Hauptkonversation einen einstündigen Cache zu geben. Anfragen außerhalb davon behalten die fünf-Minuten-Standard, bis Sie auch für diesen Bucket eine TTL wählen.

Wenn mehr als ein Steuerelement zutrifft, nimmt Claude Code die erste Übereinstimmung in dieser Reihenfolge:

  1. FORCE_PROMPT_CACHING_5M=1, das fünf Minuten für beide Buckets erzwingt
  2. Die Umgebungsvariable des Buckets
  3. Die Einstellung des Buckets
  4. Für die Anfragen eines Subagenten der cacheTtl-Wert im experimental-Frontmatter-Feld des Subagenten, das Claude Code v2.1.248 oder später erfordert. Claude Code ignoriert ein 1h dort, während Ihr Claude-Abonnement Nutzungsguthaben verwendet
  5. ENABLE_PROMPT_CACHING_1H=1, das eine Stunde für beide Buckets anfordert
  6. Der Standard für den Bucket der Anfrage

Setzen Sie FORCE_PROMPT_CACHING_5M=1, wenn Sie das Cache-Verhalten debuggen, die beiden TTLs vergleichen oder eine längere TTL überschreiben, die in verwalteten Einstellungen gesetzt ist.

Um zu bestätigen, welche TTL die Cache-Schreibvorgänge Ihrer Hauptkonversation verwendet haben, führen Sie claude -p "hello" --output-format json aus und lesen Sie usage.cache_creation im Ergebnis. Claude Code meldet einstündige Cache-Schreibvorgänge unter ephemeral_1h_input_tokens und fünf-Minuten-Cache-Schreibvorgänge unter ephemeral_5m_input_tokens.

Durch ein LLM-Gateway, das Sie mit ANTHROPIC_BASE_URL setzen, reist ein Teil der einstündigen Anfrage im anthropic-beta-Header, daher konfigurieren Sie das Gateway, um diesen Header unverändert weiterzuleiten. Die eine-Stunden-TTL ist nicht über das Claude-Apps-Gateway verfügbar. Bei Amazon Bedrock variieren Prompt-Caching-Unterstützung, minimale cacheable Präfixlänge und eine-Stunden-TTL-Verfügbarkeit je nach Modell. Wenn Cache-Token-Zählungen bei Null bleiben, überprüfen Sie unterstützte Modelle, Regionen und Limits in der Amazon Bedrock-Dokumentation.

Cache-Umfang

In Claude Code ist der Cache effektiv auf einen Computer und ein Verzeichnis beschränkt. Der System-Prompt bettet das Arbeitsverzeichnis, die Plattform, die Shell, die OS-Version und Auto-Memory-Pfade ein, daher bauen zwei Sessions in verschiedenen Verzeichnissen unterschiedliche Präfixe auf und verfehlen den Cache des anderen. Das schließt Worktrees desselben Repositorys ein, da jeder Worktree sein eigenes Arbeitsverzeichnis hat.

Sessions, die Sie parallel im selben Verzeichnis ausführen, bauen passende Präfixe auf und lesen den Cache des anderen. Sequenzielle Sessions teilen das Präfix nur, wenn der Git-Status-Snapshot beim Start übereinstimmt, da der System-Prompt auch Branch und aktuelle Commits erfasst.

Der zugrunde liegende API-Cache ist breiter. Caches sind zwischen Organisationen isoliert, und bei einigen Providern zwischen Workspaces innerhalb einer Organisation. Innerhalb dieser Grenzen lesen zwei Anfragen mit demselben Modell und Präfix denselben Cache. Für Agent SDK-Aufrufer, die Flotten automatisierter Prozesse ausführen, siehe Prompt Caching über Benutzer und Maschinen verbessern, um die Pro-Maschinen-Abschnitte des System-Prompts zu unterdrücken und den Cache über Maschinen zu teilen.

Cache-Leistung überprüfen

Cache-Leistung zeigt sich als zwei Token-Zählungen, die die API bei jeder Antwort meldet. Der direkteste Weg, sie live zu beobachten, ist ein Statusline-Skript, das das current_usage-Objekt liest:

Feld Bedeutung
cache_creation_input_tokens Tokens, die in diesem Turn in den Cache geschrieben werden, abgerechnet zum Cache-Schreibsatz
cache_read_input_tokens Tokens, die in diesem Turn aus dem Cache bereitgestellt werden, abgerechnet zu etwa 10% des Standard-Input-Satzes

Ein hohes Lese-zu-Erstellungs-Verhältnis bedeutet, dass Caching gut funktioniert. Wenn die Erstellung Turn für Turn hoch bleibt, ändert sich etwas in Ihrem Präfix. Der Abschnitt Aktionen, die den Cache ungültig machen listet die üblichen Ursachen auf.

Für eine Zusammenfassung pro Session führen Sie /usage aus. Nach der ersten Antwort der Hauptkonversation fügt Claude Code eine Prompt cache (main)-Zeile zum Session-Block hinzu, die das Hit-Verhältnis der Session, die Anzahl der Misses und an, ob der Cache gerade warm ist. Ein Statusline-Skript kann die gleichen Zahlen aus dem prompt_cache-Objekt lesen. Beide erfordern Claude Code v2.1.251 oder später.

Die Prompt cache (main)-Zeile nennt auch die wahrscheinliche Ursache des letzten Miss, wenn Claude Code eine identifizieren kann, zum Beispiel likely cause: tool definitions changed. Der Text zur wahrscheinlichen Ursache erfordert Claude Code v2.1.260 oder später.

Für Sichtbarkeit über eine Organisation hinweg meldet der OpenTelemetry-Exporter Cache-Lese- und Erstellungs-Tokens pro Benutzer und Session. Siehe Nutzung überwachen für die Metrik- und Event-Attribut-Referenz.

Subagents und der Cache

Ein Subagent startet seine eigene Konversation mit seinem eigenen System-Prompt und Tool-Set, getrennt vom Parent. Sein erster Request liest den Cache des Parents nicht, weil sich die beiden Präfixe unterscheiden, und er wärmt seinen eigenen Cache über seine Turns auf. Subagents fallen außerhalb des Haupt-Konversations-TTL-Buckets, daher erhalten sie fünf Minuten auch bei einem Abonnement, bis Sie einen längeren wählen.

Der Cache des Parents ist unberührt. Von der Parent-Seite hängen der Aufruf und das Ergebnis des Subagents an die Konversation an, wobei das Parent-Präfix intakt bleibt.

Ein Fork erbt dagegen den System-Prompt, die Tools und die Konversationshistorie des Parents genau, daher liest sein erster Request den Cache des Parents.

Andere Requests können auch ein Präfix lesen, das ein früherer Request gecacht hat:

  • Session-Kopien: Eine Session, die Sie mit /fork kopieren, erhält ihre Isolationsanweisung als Nachricht am Ende der kopierten Konversation, daher bleibt der Cache, den die ursprüngliche Konversation aufgebaut hat, intakt.
  • Komprimierung: Der Zusammenfassungs-Call, der in Konversation komprimieren beschrieben wird, verwendet denselben Präfix-Sharing-Ansatz.
  • Workflow-Fan-Outs: Bei einem Workflow-Fan-Out von Agents mit gleichem Präfix hält Claude Code alle außer dem ersten standardmäßig bis zu 5 Sekunden lang, damit ihre ersten Requests das Präfix lesen können, das der erste Agent gecacht hat.

Prompt Caching deaktivieren

Das Deaktivieren von Caching ist gelegentlich nützlich, wenn Sie das Caching-Verhalten mit einem bestimmten Modell oder Provider debuggen. Um es auszuschalten, setzen Sie eine dieser Umgebungsvariablen auf 1:

Variable Effekt
DISABLE_PROMPT_CACHING Für alle Modelle deaktivieren
DISABLE_PROMPT_CACHING_HAIKU Nur für Haiku deaktivieren
DISABLE_PROMPT_CACHING_SONNET Nur für Sonnet deaktivieren
DISABLE_PROMPT_CACHING_OPUS Nur für Opus deaktivieren
DISABLE_PROMPT_CACHING_FABLE Nur für Fable deaktivieren

Um die Caching-Richtlinie über eine Organisation hinweg festzulegen, setzen Sie eine dieser oder die TTL-Variablen in den env-Block von verwalteten Einstellungen. Für normale Nutzung lassen Sie Caching aktiviert.