Wie Claude Code Prompt Caching nutzt

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 und führt nur neue Arbeit für das Geänderte durch. 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. 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: 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, einschließlich Inhalte wie Ausgabestil, die am Anfang der Session festgelegt sind. 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 sind überhaupt nicht Teil des Prompt-Textes, daher erscheinen sie nicht in der Ebenen-Tabelle. Sie verhalten sich unterschiedlich beim Caching:

• Modell: Der Cache wird nach Modell verschlüsselt, daher hat jedes Modell seinen eigenen Cache. Das Wechseln von Modellen berechnet die gesamte Anfrage neu, auch wenn der Inhalt identisch ist. Siehe Modelle wechseln unten.
• Effort Level: nicht Teil des Cache-Schlüssels oder des Prompts, daher hat das Ändern mid-session keine Auswirkung auf den Cache.

​

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
• Bedrock oder Vertex AI: Der Cache lebt in der Serving-Infrastruktur Ihres Cloud-Providers
• Foundry: Anfragen werden an Anthropics Infrastruktur weitergeleitet
• 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

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 oder eine MCP-Wiederverbindung können sich kostenlos anfühlen, bis Sie den langsameren Turn bemerken, der folgt.

• Modelle wechseln
• Verbinden oder Trennen eines MCP-Servers
• Ein ganzes Tool ablehnen
• Konversation komprimieren
• Claude Code aktualisieren

​

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. 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.

​

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 MCP-Tools, die Claude zur Verfügung stehen, zwischen Turns ändert. Die häufigste Ursache ist ein MCP-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. MCP Tool Search reduziert, wie viel jedes Tool zum Präfix beiträgt, indem vollständige Tool-Definitionen aufgeschoben werden, aber die Menge der Tool-Namen muss stabil bleiben, damit der Cache gültig bleibt.

​

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. Tool-Definitionen sitzen in der System-Prompt-Ebene, daher macht das Hinzufügen oder Entfernen einer dieser Regeln mid-session den Cache auf die gleiche Weise ungültig wie ein MCP-Server, der sich verbindet oder trennt. Die Änderung wird beim nächsten Turn wirksam, egal ob Sie sie über /permissions hinzufügen oder durch direktes Bearbeiten einer Einstellungsdatei. Nur ein bloßer Tool-Name oder die äquivalente Bash(*) Form hat diese Auswirkung. 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.

​

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 eine einmalige Anfrage mit demselben System-Prompt, Tools und History wie Ihre Konversation, plus eine Zusammenfassungsanweisung, die als letzte Benutzernachricht angehängt wird. Da sie Ihr Präfix teilt, liest diese Anfrage den vorhandenen Cache, anstatt die vollständige Historie neu zu verarbeiten. Der größte Teil der Komprimierungszeit geht in die Generierung der Zusammenfassung, nicht in einen Cache-Miss. Der Turn, der folgt, baut den Konversations-Cache nur für die viel kürzere Zusammenfassung neu auf, daher ist der Post-Komprimierungs-Turn nicht der langsame Teil.

​

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 oder das Ändern des Ausgabestils, sind auch der Grund, warum eine Einstellungsänderung auf einen Neustart wartet, um angewendet zu werden.

• Dateien in Ihrem Repository bearbeiten
• CLAUDE.md mid-session bearbeiten
• Ausgabestil ändern
• Permission Mode ändern
• Skills und Commands aufrufen
• Ausführen von /recap
• Konversation zurückspulen
• Einen Subagent spawnen

​

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.

​

Ausgabestil ändern

Ausgabestil ist Teil des System-Prompts, den Claude Code einmal am Session-Start liest. Das Ändern über /config oder die outputStyle-Einstellung mid-session macht den Cache nicht ungültig, aber die Änderung wird auch nicht angewendet. Claude verwendet weiterhin den Stil, der am Session-Start geladen wurde. Der neue Stil wird beim nächsten /clear oder Neustart geladen.

​

Permission Mode ändern

Das Wechseln zwischen Permission Modes, z. B. von Standard zu Accept Edits, ändert den System-Prompt oder Tool-Definitionen nicht, daher sind Mode-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 Mode-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. 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. Claude Code wählt die TTL für Sie basierend auf Ihrer Authentifizierung, und Sie können sie mit Umgebungsvariablen überschreiben.

​

Bei einem Claude-Abonnement

Bei einem Claude-Abonnement fordert Claude Code die eine-Stunden-TTL automatisch an. Die Nutzung ist in Ihrem Plan enthalten, anstatt pro Token abgerechnet zu werden, daher kostet die längere TTL Sie nichts extra und beeinflusst nur, wie lange Ihr Cache warm bleibt. Wenn Sie das Nutzungslimit Ihres Plans überschritten haben und Claude Code auf Nutzungsguthaben zurückgreift, wird diese Nutzung für Sie abgerechnet, daher senkt Claude Code die TTL automatisch auf fünf Minuten.

​

Bei einem API-Schlüssel oder Drittanbieter-Provider

Bei einem API-Schlüssel, Bedrock, Vertex, Foundry oder Claude Platform on AWS zahlen Sie die Pro-Token-Raten, daher bleibt die TTL standardmäßig bei den günstigeren fünf Minuten. Um sich für die eine-Stunden-TTL anzumelden, setzen Sie ENABLE_PROMPT_CACHING_1H=1. Bei 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 Bedrock-Dokumentation.

​

TTL überschreiben

Setzen Sie FORCE_PROMPT_CACHING_5M=1, um die fünf-Minuten-TTL unabhängig von der Authentifizierung zu erzwingen. Dies ist nützlich, wenn Sie das Cache-Verhalten mit einem bestimmten Modell oder Provider debuggen, die beiden TTLs vergleichen oder ein in verwalteten Einstellungen gesetztes ENABLE_PROMPT_CACHING_1H überschreiben.

​

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: 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 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. Er baut seinen eigenen Cache auf, beginnend ohne Cache-Hits bei seinem ersten Aufruf und wärmend über seine eigenen Turns. Subagents verwenden die fünf-Minuten-TTL auch bei einem Abonnement, da die automatische eine-Stunden-TTL für die Hauptkonversation gilt. 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 seine erste Anfrage den Cache des Parents. Der Komprimierungs-Zusammenfassungsaufruf, der in Konversation komprimieren beschrieben wird, verwendet denselben Präfix-Sharing-Ansatz.

​

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: 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.

​

Verwandte Ressourcen

• Lektionen aus dem Aufbau von Claude Code: Prompt Caching ist alles: die Designrationale für Plan Mode, aufgeschobenes Tool-Laden und Komprimierung
• Erkunden Sie das Kontextfenster: was in den Kontext geladen wird und wann
• Token-Nutzung reduzieren: Strategien jenseits von Caching zur Verwaltung der Kontextgröße
• Kosten verfolgen und reduzieren: Cache-Token-Verfolgung und TTL-Konfiguration für Agent SDK-Aufrufer
• Prompt Caching: der zugrunde liegende API-Mechanismus, Breakpoints und Preisgestaltung