Routen von Claude-Code-Datenverkehr anhand von Header statt durch Lesen der Anfrage
Erfahren Sie, wie die opt-in-Gateway-Hint-Header von Claude Code es einem LLM-Gateway ermöglichen, Caches anhand von Anfrage-Metadaten zu priorisieren, zu budgetieren und zu verwalten, ohne die Prompt-Texte analysieren zu müssen.
Wenn ein Unternehmen den Datenverkehr von Claude Code über eine LLM-Gateway-Plattform leitet, muss diese Plattform für jede Anfrage vor dem Weiterleiten Entscheidungen treffen: Welchen Upstream zu verwenden, in welche Warteschlange einzutreten, welches Rate-Limit-System anzuwenden und welche Priorität zuzuweisen. Bis vor Kurzem waren die Informationen, die diese Entscheidungen untermauern, nur im Anfragekörper zu finden – also in Ihren Prompts, den Inhalten der Dateien, den Ergebnissen der Tools sowie im CLAUDE.md-Datei. In einer kürzlichen Version von Claude Code wurden zusätzliche, frei wählbare Anfrage-Header hinzugefügt, die diese Informationen auf das Anfragenvelope verlagern. Im Folgenden erfahren Sie, welche Entscheidungen durch jeden Header getroffen werden können, wie sich ein Proxy verhält, wenn er sie nutzen kann, und wo Sie ihnen weiterhin nicht trauen sollten.
Warum Gateways letztendlich Ihre Prompts lesen
Die Prüfung des Inhalts ist keine theoretische Frage; so funktionieren viele Router heutzutage. Semantische Router wie der vLLM Semantic Router extrahieren die Benutzeranfrage, fügen sie mit einem BERT-ähnlichen Modell zusammen und vergleichen den resultierenden Vektor mit Referenzvektoren, um die Anfrage zu klassifizieren. Router, die für eine geringe Latenz optimiert sind, können den Modellnamen bereits aus dem ersten Kilobyte heraus erkennen und den Rest streamen, doch jeder Router, der eine Klassifizierung durchführen muss, muss den gesamten Inhalt puffern und überprüfen.
Diese Prüfung ist das Produktmerkmal und macht den Gateway zudem zu einer weitaus sensibleren Vertrauensgrenze, als sein bescheidener Name vermuten lässt. Er erkennt – und kann potenziell speichern – alles, was der Agent eines Entwicklers sendet.
Claude Code 2.1.273 vom 15. September 2026 im Changelog fügte fünf Header hinzu, die sich an Gateway-Betreiber richten. Insgesamt dienen sie weniger als Funktionalitäten zur Überwachbarkeit denn als Mindestmetadaten, die ein Gateway benötigt, um als Scheduler zu fungieren, ohne gleichzeitig als Leser tätig zu werden.
Die Grenzen der ursprünglichen Identifikations-Header
Vor 2.1.273 dokumentierte der Kompatibilitätsleitfaden für Gateways drei Claude Code-Header, die alle Identifikatoren waren:
+--------------------------------+---------------------------------+
| HEADER | WHAT IT IS |
+--------------------------------+---------------------------------+
| x-claude-code-session-id | which session |
| x-claude-code-agent-id | which subagent (if any) |
| x-claude-code-parent-agent-id | which agent spawned it |
+--------------------------------+---------------------------------+
|
v
good for GROUPING after the fact
useless for DECIDING before forwarding
Die Dokumentation sieht ihre Verwendung zur Aggregation vor: Die Sitzungs-ID ermöglicht es, alles zusammenzufassen, was eine Sitzung sendet, ohne die Inhalte parsen zu müssen, und die Agent-ID in Kombination mit der Sitzungs-ID ermöglicht es, Kosten den parallel laufenden Agenten zuzuordnen. Das ist Buchhaltung. Damit reicht es für ein Kosten-Dashboard, aber nicht für die Planung. Dass eine Anfrage von der Sitzung abc und dem Agenten def stammt, sagt nichts darüber aus, wie teuer sie sein wird, wie lange sie dauern wird oder ob es sich lohnt zu warten. Jeder Gateway, der intelligenter als ein einfacher Zähler sein wollte, musste daher den Inhalt der Anfrage öffnen.
Die fünf neuen Hinweis-Header
Laut dem Changelog führte Version 2.1.273 fünf Header ein, die alle zusammen mit CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 aktiviert wurden. Zwei beschreiben den Aufrufer (x-claude-code-agent-type und x-claude-code-request-class), einer beschreibt aktuelle Zeitangaben (x-claude-code-prev-tool-durations), und ein Paar beschreibt Kontextumschreibungen (x-claude-code-context-compacted zusammen mit x-claude-code-compaction).
Eine wichtige Einschränkung: Zum Zeitpunkt der Erstellung zeigt die Tabelle der Anfrage-Header im Kompatibilitätsleitfaden für Gateways immer noch nur die drei Identifikations-Header, und die Variable fehlt in der Referenz zu Umgebungsvariablen. Die Namen der Header stammen aus dem Changelog, doch ihre Wertformate sind bisher nicht dokumentiert. Alles, was hier beschrieben wird, bezieht sich darauf, welche Entscheidungen ein Gateway aufgrund jedes Headers treffen kann – nicht auf ein garantiertes Übertragungsformat. Prüfen Sie Ihren eigenen Datenverkehr, bevor Sie auf bestimmte Werte vertrauen, und überprüfen Sie die aktuellen Dokumentationen, die möglicherweise bereits aktualisiert wurden.
Gegruppiert nach der Entscheidung, die jeder Header ermöglicht:
+---------------------------+------------------------------------------+
| HEADER | DECISION IT UNBLOCKS AT THE EDGE |
+---------------------------+------------------------------------------+
| request-class | is this a real turn, or a small |
| | internal call? -> priority, cheap pool |
+---------------------------+------------------------------------------+
| agent-type | which kind of subagent is asking |
| | -> per-agent-type budgets and quotas |
+---------------------------+------------------------------------------+
| prev-tool-durations | how long the last tools took |
| | -> timeout and retry window sizing |
+---------------------------+------------------------------------------+
| compaction | this turn IS the summarization call |
| | -> never count it as user latency |
+---------------------------+------------------------------------------+
| context-compacted | the prefix just changed under you |
| | -> do not expect a cache hit this turn |
+---------------------------+------------------------------------------+
Kurz gesagt:
- request-class trennt echte Konversationswechsel von kleinen internen Aufrufen, sodass Sie die erstgenannten priorisieren und die letzteren an einen günstigeren Pool senden können.
- agent-type gibt an, welche Art von Unteragent aufruft, wodurch Budgets und Quoten pro Agent-Typ festgelegt werden können.
- prev-tool-durations berichtet über die Dauer der kürzlich durchgeführten Tool-Aufrufe, was bei der Einstellung von Timeout-Werten und Wiederholungsfenstern hilft.
- compaction kennzeichnet die Anfrage, die selbst eine Zusammenfassung durchführt, sodass sie niemals zur für den Benutzer sichtbaren Latenz beiträgt.
- context-compacted signalisiert, dass der Konversations-Präfix gerade neu geschrieben wurde, weshalb kein Cache-Erfolg erwartet wird.
Das ist keine neue Information. Ein Gateway könnte bereits die Anfragenklasse ermitteln, indem es den vollständigen Claude Code-Systemprompt von einem vereinfachten Klassifizierungs Prompt unterscheidet, den Agententyp aus dem Agentenabschnitt des Systemprompts ableitet und die Komprimierung anhand der Struktur des Nachrichtenarrays erkennt. Die Header verraten nichts Zusätzliches über Sie. Was sich ändert, ist der Preis des Wissens: Anstatt bis zu einem Megabyte Quellcode zu analysieren, liest das Gateway nur einen kurzen String aus den Headern.
Dieselbe Routing-Regel, vor und nach
Nehmen wir ein konkretes Ziel: Die Hintergrundzusammenfassung an einen günstigeren Pool leiten. Ohne Hinweise muss der Proxy das Gespräch puffern und analysieren, um anschließend aus seinem Inhalt zu schließen:
// BEFORE: the router has to read the conversation to classify it
const body = await readEntireBody(req); // buffers the whole prompt
const parsed = JSON.parse(body); // your files are now in gateway memory
const sys = flattenSystemBlocks(parsed.system);
const isBackground =
sys.includes("summarize the conversation") ||
parsed.messages.length > COMPACT_THRESHOLD;
und erst danach den gepufferten Inhalt weiterleiten:
route(isBackground ? "cheap-pool" : "interactive-pool", body);
Dieser Ansatz weist drei Probleme auf, von am geringsten bis zum ernstesten. Das Buffern des gesamten Inhalts zerstört die Latenz beim Streaming. Die Abgleichung anhand der Wortwahl des Prompts ist anfällig, da sich diese Wortwahl zwischen den verschiedenen Claude Code-Versionen ändert. Am schlimmsten ist, dass der vollständige Text Ihres Repositoriums nun in dem Prozessspeicher der Routing-Schicht liegt – in deren Heap-Dumps und vermutlich auch in den Logs –, einem Ort, der auf keiner Architekturdarstellung zu finden ist und den niemand als schützenswert erachtet hat.
Mit den Hinweistags legt der Router zwei Werte aus dem Envelope ab:
// AFTER: the router decides on the envelope and never touches the body
const cls = req.headers["x-claude-code-request-class"];
const comp = req.headers["x-claude-code-compaction"];
und leitet den unveränderten Anfrages stream weiter. Wie der Kommentar im Auszug bemerkt, dienen die literalen Wertzeichen nur zur Veranschaulichung, da das Format noch nicht dokumentiert ist:
// value strings below are illustrative: confirm them against your own
// traffic, since the wire format is not documented yet
const isBackground = Boolean(comp) || cls === "background";route(isBackground ? "cheap-pool" : "interactive-pool", req); // streams through
Es gibt weder Pufferung noch JSON-Parser und auch keine Anfragen, die im Speicher gehalten werden. Der Kompatibilitätsleitfaden erlaubt bereits dieses Muster: Abgesehen von anthropic-workspace-id, anthropic-beta und anthropic-version werden Header als Eingaben beschrieben, die das Gateway zur Verfolgung, Zuordnung oder Routierung verwenden kann und nicht unbedingt weitergeleitet werden müssen. Diese Hinweise sind so konzipiert, dass sie beim Gateway enden; da das Modell sie niemals sieht, können sie einfach und kostengünstig bleiben.
Das Komprimierungs-Paar ist ein Caching-Signal
Zwei der Header scheinen überflüssig zu sein, beantworten aber unterschiedliche Fragen. Der erste, x-claude-code-compaction, wird bei der Anfrage gesetzt, die die Zusammenfassung erzeugt. Der zweite, x-claude-code-context-compacted, tritt bei späteren Anfragen auf, nachdem bereits eine Komprimierung stattgefunden hat.
Der Unterschied ist wichtig, sobald man einen Cache verwendet. Die Cache-Schlüssel für Anfragen bestehen aus Präfixen, die aus Tools, anschließend dem Systemprompt und dann den Nachrichten zusammengesetzt werden; dadurch wird jede Änderung am Anfang des Präfixes alles danach ungültig. Cache-Schreibvorgänge sind außerdem teurer als Cache-Lesevorgänge, wodurch unnötige Schreibvorgänge reine Kosten darstellen. Die Komprimierung ist der größte Faktor, der in einer normalen Sitzung zu Ungültigkeitsfällen führt: Sie ersetzt die angesammelte Historie durch eine Zusammenfassung, wodurch per Definition ein völlig neues Präfix entsteht.
turn N turn N+1 (compaction) turn N+2
+---------+ +------------------+ +------------------+
| prefix | | compaction: 1 | | context- |
| stable | --> | rewrites history | --> | compacted: 1 |
| cache | | EXPECT A MISS | | new prefix is |
| hits | | bill it as | | now the stable |
+---------+ | background | | one, re-warm it |
+------------------+ +------------------+
Ein Gateway, das seinen eigenen Cache verwaltet, aber nichts über die Komprimierung weiß, verhält sich bei der Komprimierungsphase so schlecht wie möglich: Es führt eine vollständige Abfrage durch, scheitert dabei, speichert einen Eintrag für ein Präfix, das bereits in der nächsten Phase veraltet sein wird, und meldet anschließend einen sinkenden Trefferanteil, der als Defekt untersucht wird. Mit den Header-Informationen kann es die Abfrage bei der Komprimierungsanfrage überspringen, diesen Aufruf als Hintergrundarbeit verbuchen und das neue Präfix absichtlich in der folgenden Phase „aufwärmen“, wenn es zum stabilen Präfix wird.
Hinweise sind Klientenbehauptungen, keine Zugangsdaten
Sowohl das Changelog als auch der Variablename beziehen sich auf diese Hinweis-Header – und dabei spielt das Wort eine entscheidende Rolle. Ein Hinweis ist eine unüberprüfte Behauptung des Clients. Der Wert von x-claude-code-request-class ist das, was Claude Code zur Übermittlung wählt; keine übergeordnete Komponente prüft diesen Wert.
Nehmen wir an, Ihr Gateway belohnt Anfragen mit dem Label „Hintergrund“ durch reduzierte Gebühren, höhere Quoten oder lockere Geschwindigkeitsbeschränkungen. Dann trifft eine vom Client bereitgestellte Zeichenkette heimlich die Entscheidung über die Autorisierung. Ein Entwickler, der seine Shell-Umgebung anpasst, oder jeder, der einen kleinen lokalen Proxy vor dem Gateway betreibt, kann wählen, welches Label die großzügigste Behandlung erhält. Hinweise eignen sich gut für das Anstellen in Warteschlangen, Entscheidungen bezüglich des Caches und die Messung der Latenz, aber niemals zur Entscheidung darüber, was ein Aufrufer zu erhalten hat.
Das zweite praktische Problem ist die Einführung. Die Header sind standardmäßig deaktiviert, es sei denn, sie werden ausdrücklich aktiviert – was die richtige Wahl für Metadaten ist, die die Sitzungsstruktur an eine Middlebox offenbaren. Angesichts ihrer Abwesenheit in den Umgebungsvariablen zum Zeitpunkt der Erstellung ist es unwahrscheinlich, dass in vielen Installationen diese Header aktiviert sind. In einer Organisation müssen sie in der Regel über verwaltete Einstellungen von einem Administrator eingeführt werden, der auf eine einzige Zeile im Changelog aufmerksam geworden ist.
Einführungsplan für Gateway-Betreiber
Falls Ihr Team ein Gateway für den Verkehr von Claude Code betreibt, sieht ein vorsichtiger Einführungsweg wie folgt aus:
- Activieren Sie
CLAUDE_CODE_GATEWAY_HINT_HEADERS=1für eine kleine Pilotgruppe. - Protokollieren Sie alle fünf Header etwa eine Woche lang, ohne etwas damit zu unternehmen.
- Vergleichen Sie ihre Werte mit den Entscheidungen, die Ihr aktueller Klassifikator zur Analyse der Inhalte trifft.
Der Vorteil ist ein deutlich geringerer Einflussbereich: Der Quellcode Ihrer Entwickler muss nicht mehr durch das Speichermedium der Routierungsstufe laufen, und es wird nur eine Umgebungsvariable benötigt.
Zusammenfassung
Die Überschriften selbst sind spezifisch für Claude Code, doch die daraus abgeleitete Designlehre gilt für jede Agentenplattform. Jede Schicht, die vor einem Agenten platziert wird, muss Anfragen klassifizieren, bevor sie weitergeleitet werden, und es gibt nur zwei Möglichkeiten, dies zu tun: Die Antwort aus dem Payload ableiten oder sie als explizite Metadaten erhalten. Das Ableiten funktioniert zwar immer, hinterlässt aber stets eine Kopie sensibler Inhalte in einem Komponenten, der keinen Grund hatte, sie zu speichern. Ein Kanal für explizite Metadaten erfordert zwar mehr anfängliches Design, ist aber die einzige Lösung, bei der der Zwischenhändler richtig weiterleiten kann, ohne jemals die Daten selbst zu erhalten. Für einen umfassenderen Überblick darüber, was ein Gateway bietet, siehe die Übersicht zum LLM-Gateway in den Claude Code-Dokumenten.