Prompt-Caching für Coding-Agenten: Kosten und Cache-Brüche

Jeder Schritt einer Agentensitzung ist eine neue API-Anfrage: jede Nachricht, die Sie senden, und jeder Stapel von Tool-Ergebnissen, den der Agent zurücksendet. Das Modell speichert nichts zwischen den Anfragen, sodass der Agent alles erneut sendet: System-Prompt, Werkzeugdefinitionen, Projektanweisungen, die gesamte Konversation und dann den neuen Teil. Fast alles stimmt mit der vorherigen Anfrage überein, und durch schnelles Caching vermeidet der Anbieter eine doppelte Verarbeitung.

Claude Code verwaltet den Cache für Sie; Auf der API aktiviert ein cache_control-Feld der obersten Ebene das automatische Caching. Die Modelle von OpenAI, auf denen Codex CLI läuft, folgen der gleichen Präfixregel mit ihren eigenen Preisen und Lebensdauern. Die folgenden Zahlen stammen von Claude.

Ein genaues Präfix in einer festen Reihenfolge

Der Cache vergleicht den Anfang jeder Anfrage, das Präfix, mit dem, was sie kürzlich verarbeitet hat. Die Übereinstimmung ist genau: Ein geändertes Zeichen macht alles danach ungültig, und es gibt kein Caching pro Datei oder pro Abschnitt.

Das Präfix wird in einer festen Reihenfolge gelesen: Werkzeugdefinitionen, dann den System-Prompt, dann die Meldungen. Eine Änderung auf einer Ebene macht diese Ebene und alle darauf folgenden Ebenen ungültig. Wenn Sie eine Nachricht bearbeiten, bleiben die Tools und den System-Prompt im Cache. Wenn Sie eine Werkzeugdefinition ändern, passiert nichts.

Claude Code stellt das, was sich selten ändert, an die erste Stelle: seine Anweisungen und Tooldefinitionen, dann Ihren Projektkontext (CLAUDE.md, Speicher, Regeln) und dann die Konversation. In einer normalen Runde ist die gesamte vorherige Anfrage das Präfix und nur der letzte Austausch ist neu.

Was kostet ein Cache-Schreibvorgang und ein Cache-Lesevorgang?

Caching verändert den Preis der Eingabe, niemals die Antwort. Ab September 2026 berechnet Anthropic die Preise in Vielfachen des Basis-Input-Preises jedes Modells: Ein Cache-Schreibvorgang kostet das 1,25-fache des Basis-Inputs bei einer Lebensdauer von 5 Minuten und das Zweifache bei einer Lebensdauer von 1 Stunde, und ein Cache-Lesevorgang kostet ein Zehntel, außer bei Claude Fable 5.1 (0,025-mal) und Claude Opus 5,5 (0,05-mal). Alles nach dem letzten Cache-Punkt ist eine normale Eingabe.

Nehmen Sie einen 100.000-Token-Kontext von Claude Sonnet 5 mit seinem Listenpreis vom September 2026 von 2 US-Dollar pro Million Input-Token. Das Lesen aus dem Cache kostet 0,02 $ pro Anfrage. Ohne Caching 0,20 $. Wird nach einem Fehlschlag erneut geschrieben, 0,25 $ für die 5-Minuten-Lebensdauer oder 0,40 $ für die 1-Stunden-Lebensdauer: Ein Fehlschlag kostet mehr als überhaupt kein Cache, da ein Schreibvorgang teurer ist als die reine Eingabe.

Beim 5-Minuten-Tarif kostet ein Neuschreiben bei den meisten Modellen das 12,5-fache eines Lesevorgangs, beim Opus 5.5 das 25-fache und beim Fable 5.1 das 50-fache: Je günstiger der Lesevorgang, desto größer die Lücke. Ein 5-minütiger Schreibvorgang macht sich beim ersten Lesen bezahlt; Für einen einstündigen Schreibvorgang sind zwei erforderlich.

Fünf Minuten oder eine Stunde

Die Lebensdauer oder TTL gibt an, wie lange ein zwischengespeichertes Präfix ungenutzt bleibt und bei jedem Lesevorgang ohne zusätzliche Kosten zurückgesetzt wird. Die Uhr startet, wenn eine Anfrage beginnt, und nicht, wenn ihre Antwort endet: Wenn das Streamen einer Antwort vier Minuten dauert, hat die nächste Anfrage noch etwa eine Minute Zeit, um einen 5-Minuten-Cache wiederzuverwenden.

Ab September 2026 gewährt Claude Code dem Hauptgespräch eine Stunde bei einem Claude-Abonnement im Rahmen der enthaltenen Nutzung und fünf Minuten bei einem API-Schlüssel, einem Cloud-Anbieter oder sobald ein Abonnement Nutzungsguthaben in Anspruch nimmt. Subagenten erhalten in beiden Fällen standardmäßig fünf Minuten.

Um die Hauptkonversation auszuwählen, legen Sie promptCacheTtl in Ihren Einstellungen oder die Umgebungsvariable CLAUDE_CODE_PROMPT_CACHE_TTL auf 5m oder 1h (Claude Code v2.1.242 oder höher) fest. Die Stunde zahlt sich aus, wenn die Lücken zwischen den Anfragen fünf bis sechzig Minuten betragen: ein Meeting, eine Überprüfung, eine lange Wartezeit, auf die der Agent wartet. Bei Bursts, die nie fünf Minuten lang im Leerlauf sind, führt dies nur dazu, dass jeder Schreibvorgang mehr kostet.

$claude -p "hello" --output-format json

Was den Cache zerstört, ohne es Ihnen zu sagen

Ein Fehlschlag löst keinen Fehler aus: Die Umdrehung ist langsamer und die Verwendung zeigt einen großen Schreibvorgang an der Stelle an, an der ein Lesevorgang erfolgen sollte. Die üblichen Ursachen bei einem Coding-Agenten:

• →Wechselmodell. Jedes Modell verfügt über einen eigenen Cache, daher liest /model während der Task den gesamten Verlauf ohne Cache erneut. Dies gilt auch für einen Skill, der ein anderes Modell benennt, und einen Planmodus unter opusplan, der Opus und Sonnet vertauscht.
• →Aufwand ändern. Bei den meisten Modellen verfügt jede Leistungsstufe über einen eigenen Cache. Ab September 2026 behalten Opus 5.5 und Fable 5.1 es bei, mit einem API-Schlüssel oder einem Claude-Abonnement.
• →Werkzeugsatz wechseln. Werkzeugdefinitionen stehen an erster Stelle, daher macht das Hinzufügen oder Entfernen einer Werkzeugdefinition alles ungültig. Claude Code verzögert MCP-Tools standardmäßig und lädt sie bei Bedarf über die Tool-Suche, sodass Serveränderungen nicht im Präfix enthalten sind. Wenn Tools stattdessen im Voraus geladen werden, beispielsweise hinter einem benutzerdefinierten ANTHROPIC_BASE_URL-Gateway, unterbricht ein MCP-Server, der abstürzt oder sich selbstständig wieder verbindet, den Cache.
• →Alles, was sich zu Beginn der Eingabeaufforderung ändert. Ein Zeitstempel in der System-Prompt bedeutet, dass alles danach bei jeder Anfrage neu geschrieben und nie gelesen wird. Ein Claude-Code-Upgrade ändert normalerweise auch der System-Prompt, sodass die erste Sitzung nach einem Kaltstart erfolgt.
• →Pausieren über die Lebensdauer hinaus: standardmäßig fünf Minuten bei einem API-Schlüssel, eine Stunde bei einem Abonnement.

Warum die erste Anfrage nach einer Pause mehr kostet

Ein Fehlschlag wird einmalig bei der nächsten Anfrage bezahlt: Das gesamte Präfix wird erneut verarbeitet und mit der Schreibrate zurückgeschrieben, und die darauf folgenden Anfragen lesen erneut aus dem Cache. Aus diesem Grund ist die erste Nachricht nach einer Pause langsam und teuer, selbst wenn sie nur eine Zeile lang ist.

Die Komprimierung ist konstruktionsbedingt ein Fehlschlag und ein kostengünstiger Fehler, solange der Cache warm ist, da die zusammenfassende Anforderung den Verlauf aus dem Cache liest. Nach einer langen Pause liest es den gesamten Verlauf erneut, ohne dass es zwischengespeichert wird. Eine Sitzung, zu der Sie gerade zurückgekehrt sind, ist also der kostspielige Moment für die Komprimierung.

Die Gewohnheiten, die daraus folgen: Legen Sie zu Beginn ein Modell und einen Aufwand fest, beenden Sie eine Aufgabe, bevor Sie zurücktreten, und /clear, wenn das Thema wechselt, anstatt eine kalte Sitzung wieder aufzunehmen. Um eine Sackgasse zu vermeiden, übertrifft /rewind die Komprimierung: Es schneidet auf ein bereits zwischengespeichertes Präfix zurück. Bei Pro- und Max-Plänen bietet Claude Code an, nach einer langen Pause eine große Sitzung mit einer Zusammenfassung fortzusetzen.

So ermitteln Sie Ihre Cache-Trefferquote

Die API meldet drei Eingabezahlen pro Antwort: cache_read_input_tokens (aus dem Cache bereitgestellt), cache_creation_input_tokens (darin geschrieben) und input_tokens, das nur zählt, was nach dem letzten Cache-Punkt kam und daher in einer gut zwischengespeicherten Sitzung klein aussieht. Der Gesamteinsatz ist die Summe der drei.

Die Trefferquote ergibt sich aus den Cache-Lesevorgängen dividiert durch die Gesamtzahl. In einer langen, warmen Sitzung sollte der Großteil jeder Anfrage gelesen werden. Eine niedrige Rate ist bei kurzen Sitzungen normal, bei denen der erste Schreibvorgang einen großen Anteil aller Eingaben ausmacht; In einem langen Fall weist ein großer Schreibvorgang Runde für Runde auf eine Ursache aus der obigen Liste hin.

$/usage

Ab Version 2.1.260 nennt diese Zeile auch die wahrscheinliche Ursache des letzten Fehlers, wenn möglich, z. B. geänderte Werkzeugdefinitionen. Es deckt nur die Hauptkonversation ab: Ein Subagent verfügt über eine eigene Eingabeaufforderung und eigene Tools, sodass seine erste Anfrage niemals den Cache des übergeordneten Agenten liest. Auf der API zeigt die Seite „Nutzung“ der Konsole den Anteil der aus dem Cache gelesenen Eingaben an, und die Cache-Diagnose (in der Betaversion ab September 2026) meldet, wo zwei aufeinanderfolgende Anfragen voneinander abweichen.

Abonnement oder API: Wer zahlt für einen Fehlschlag?

Mit einem API-Schlüssel kostet ein Fehlschlag Geld, zu den in der Tabelle aufgeführten Raten, und es gibt Spielraum für die Ratenbegrenzung: Bei den meisten Claude-Modellen zählen Cache-Lesevorgänge nicht zum Grenzwert für Eingabe-Tokens pro Minute, Schreibvorgänge und nicht zwischengespeicherte Eingaben dagegen schon.

Bei einem Pro- oder Max-Plan gibt es keine Rechnung pro Token und die Dollarzahl in /usage ist eine Schätzung für API-Benutzer. Ein Fehlschlag wird stattdessen aus den Limits Ihres Plans bezahlt: In der Dokumentation von Claude Code werden Cache-Fehler als Gründe aufgeführt, warum eine lange Sitzung mehr davon verbraucht, als Ihre Aktivität vermuten lässt. Bei Pro-, Max-, Team- und Enterprise-Plänen fehlen die Pannenflags /usage, sobald sie ein Zehntel der letzten Nutzung erreichen.

Ein zwischengespeicherter Token ist immer noch ein Token

Selbst für ein Zehntel des Preises wird der gesamte Kontext bei jeder Anfrage erneut gelesen. Mit den Worten der Dokumentation von Claude Code wird eine einzeilige Frage in einer Sitzung, die den ganzen Tag geöffnet war, immer noch für das gesamte Gespräch genutzt. Die Gewohnheiten stapeln sich also: Halten Sie den Anfang des Prompts stabil, damit er im Cache bleibt, und halten Sie den Kontext klein, damit jeder Lesevorgang und jeder Fehlschlag wenig kostet.

Wenn Sie es lieber nicht manuell klein halten möchten, steuert capsul die Agent-CLI, bei der Sie bereits angemeldet sind, und sendet im Rahmen eines von Ihnen festgelegten Token-Budgets das, was die Aufgabe verlangt, und nicht das Repository. Es hört beim Budget auf und sagt, was es ausgelassen hat; Auf der Benchmark-Seite wird der gemessene Effekt pro Modell veröffentlicht, daneben werden Antwortprüfungen angezeigt.