Claude Code Gateway-Kompatibilitätsleitfaden

Halten Sie ein LLM-Gateway mit Claude Code kompatibel: die Endpunkte, die es aufruft, die Header und Body-Felder, die weitergeleitet werden müssen, und was bricht, wenn sie entfernt werden.

Diese Seite dokumentiert die Anfragen, die Claude Code an ein Gateway sendet, einschließlich der Endpunkte, die es aufruft, der Header und Body-Felder, die das Gateway weiterleiten muss, und welche Funktionen nicht mehr funktionieren, wenn diese nicht weitergeleitet werden. Sie ist für Betreiber geschrieben, die ein Gateway-Produkt für die Zusammenarbeit mit Claude Code konfigurieren.

Das Claude Apps Gateway, Anthropics selbstgehostetes Gateway, stellt seine eigene Endpunkt-Referenz unter GET /protocol bereit, die die Sign-in-, Inference-, verwalteten Einstellungen-, Modellerkennungs- und Telemetrie-Endpunkte dieses Gateways abdeckt. Es ist ein separates Dokument von diesem Leitfaden.

[!NOTE]

• Um ein vorhandenes oder Gateway eines Drittanbieters für Ihre Organisation bereitzustellen, siehe Rollout eines LLM-Gateways
• Wenn Sie ein einzelner Entwickler sind, der Claude Code mit einem Ihnen gegebenen Anmeldedaten bei einem Gateway authentifiziert, siehe Claude Code mit einem LLM-Gateway verbinden

Diese Seite behandelt:

• API-Formate und die Endpunkte, die für jedes bereitgestellt werden müssen
• Client-Verhalten nach Verbindungsmethode: wie sich Modell-IDs, anthropic-beta-Werte, Anforderungsfelder und Standardwerte zwischen den Formaten und einer Claude Apps Gateway-Anmeldung unterscheiden
• Anforderungs-Header: welche den Upstream erreichen müssen und welche Ihr Gateway verbrauchen kann
• Antwort-Header: was zurückgegeben werden muss, damit Stall-Erkennung, Wiederholungen und die Anzeige von Nutzungslimits funktionieren
• Der System-Prompt-Attributionsblock und wie er mit Prompt-Caching interagiert
• Feature-Weitergabe: was bricht, wenn Header oder Body-Felder entfernt werden
• Modellermittlung

Diese Seite verwendet zwei Begriffe für das, was Ihr Gateway mit jedem Header und Body-Feld tut:

• Unverändert weiterleiten: es byte-für-byte an den Upstream weitergeben
• Verbrauchen: das Gateway kann es zum Routing, zur Zuordnung oder zum Tracing lesen und muss es nicht weiterleiten

Alles, das nicht als unverändert weitergeleitet markiert ist, können Sie verbrauchen oder ignorieren.

API-Formate

Ein Gateway muss mindestens eines der folgenden API-Formate für Claude Code-Clients bereitstellen. Ein Client wählt ein Format aus und verweist Claude Code auf Ihr Gateway mit den Variablen in der Spalte „Ausgewählt von“ der folgenden Tabelle.

Google Cloud's Agent Platform ist Google Clouds Claude-Endpunkt, ehemals Vertex AI; seine Variablennamen behalten die Schreibweise VERTEX.

Foundry und Claude Platform on AWS

Microsoft Foundry und die Claude Platform on AWS implementieren das Anthropic Messages-Format. Claude Code leitet zu ihnen über ihre eigenen Variablen weiter, ANTHROPIC_FOUNDRY_BASE_URL und ANTHROPIC_AWS_BASE_URL, aber ein Gateway, das eines von beiden frontet, implementiert die Anthropic Messages-Zeile oben. Ein Gateway, das die Claude Platform on AWS frontet, muss auch den Header anthropic-workspace-id weitergeleitet, den diese Plattform bei jeder Anfrage erfordert.

Optionale Endpunkte und Startup-Traffic

Token-Counting-Endpunkte sind die einzigen optionalen: Wenn sie fehlen, greift Claude Code auf eine zeichenbasierte Schätzung der Kontextnutzung zurück.

Gleichen Sie den Pfad ab, nicht die vollständige URL:

• Inferenzanfragen werden an /v1/messages?beta=true gesendet
• Die Google Cloud's Agent Platform-Methode hängt Suffixe an den Publisher-Modellpfad an, wie in /projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict

Ein Gateway sieht auch Best-Effort-Startup-Traffic, den es ablehnen kann, ohne etwas zu unterbrechen. Ein Anthropic Messages-Format-Gateway empfängt eine HEAD /api/hello Verbindungs-Aufwärm-Sonde, die Claude Code überspringt, wenn ein HTTP-Proxy oder ein Client-Zertifikat konfiguriert ist. Ein Amazon Bedrock-Format-Gateway empfängt eine GET /inference-profiles?type=SYSTEM_DEFINED Anfrage und, wenn das konfigurierte Modell ein Inferenzprofil ist, GET /inference-profiles/{profile} Lookups.

Sitzungen, die über ein Gateway laufen, sind nicht für die HIPAA-Konfiguration zugelassen. Prüfen Sie, wie sich Entwickler anmelden und verbinden listet auf, welche Anmelde- und Verbindungsmethoden es sind. Siehe Die HIPAA-Konfiguration hinter einem Gateway.

Die Fast Mode Verfügbarkeitsprüfung erscheint niemals in Gateway-Protokollen: Sie ruft api.anthropic.com direkt auf, anstatt ANTHROPIC_BASE_URL zu folgen, sodass in einem Netzwerk, das direkten Ausgang zu api.anthropic.com blockiert, Fast Mode einen Konnektivitätsfehler melden kann, während die Inferenz durch das Gateway weiterhin funktioniert. Die WebFetch-Domänensicherheitsprüfung ruft auch api.anthropic.com direkt auf. Verwenden Sie Fast Mode hinter Proxys und LLM-Gateways behandelt die Variablen, die es wiederherstellen.

Streaming

Claude Code liest jede Streaming-Inferenzantwort Ereignis für Ereignis, während sie ankommt. Daher beeinflusst die Art, wie Ihr Gateway den Stream weiterleitet, was der Benutzer sieht:

• Wenn Ihr Gateway eine Antwort puffert, bis sie vollständig ist, stockt Claude Code.
• Claude Code erwartet die vollständige Ereignissequenz jeder Antwort, in der richtigen Reihenfolge, bis zu den abschließenden Ereignissen message_delta und message_stop. Wenn der Body sauber endet, nachdem ein Inhaltsblock begonnen hat, aber vor diesem abschließenden message_delta, behandelt Claude Code die Antwort als unterbrochene Verbindung. Die obige Antwort kann unvollständig sein beschreibt, was der Benutzer dann sieht, und Automatische Wiederholungen erklärt, wann Claude Code die Anfrage stattdessen erneut sendet.
• Wenn eine Amazon Bedrock-Guardrail eine Antwort blockiert, können die Ereignisse, die Bedrock sendet, auf einen Inhaltsblock verweisen, dessen content_block_stop bereits angekommen ist, und Claude Code ist darauf angewiesen, sie so zu empfangen, wie sie gesendet wurden. AWS Guardrails beschreibt, wie diese Antwort endet.
• Claude Code bricht eine Streaming-Antwort ab, sobald länger als sein Streaming-Leerlauf-Timeout keine Bytes ankommen. Während einer langen Denkpause können die SSE-ping-Ereignisse des Upstreams die einzigen Bytes im Stream sein, sodass ein Gateway, das sie entfernt oder puffert, diesen Timeout mitten in einer Antwort auslösen kann. Ein Gateway, das von einem Upstream ohne Pings übersetzt, etwa dem binären Event-Stream von Amazon Bedrock, hat dieselbe Lücke, sofern es keine eigenen ping-Ereignisse ausgibt.
• Beim Amazon Bedrock InvokeModel-Format liest Claude Code die Antwort von /model/{model}/invoke-with-response-stream als den binären application/vnd.amazon.eventstream-Body, den Bedrock zurückgibt, und kann ihn nicht mehr parsen, sobald ein Gateway ihn in Server-Sent Events konvertiert oder diesen Content-Type-Header umschreibt. Streaming-Fehler hinter einem Gateway oder Proxy beschreibt, was der Benutzer dann sieht.

Format-Nichtübereinstimmung mit dem Upstream

Welches Format der Client spricht, bestimmt, was Ihr Gateway empfängt. Der häufige Fehlermodus ist eine Nichtübereinstimmung zwischen dem Format, das der Client an Ihr Gateway sendet, und dem Format, das der Upstream-Provider dahinter akzeptiert.

• Wenn der Client das Amazon Bedrock- oder Google Cloud's Agent Platform-Format spricht, sendet Claude Code nur die Teilmenge seines vollständigen Funktionssatzes, die diese Provider akzeptieren
• Wenn der Client das Anthropic Messages-Format spricht, sendet Claude Code den vollständigen Satz, auch wenn Ihr Gateway an einen Amazon Bedrock- oder Google Cloud's Agent Platform-Upstream weiterleitet

Diese Differenz zu überbrücken ist die Aufgabe Ihres Gateways. Feature-Durchleitung beschreibt, was bricht, wenn es nicht funktioniert.

Wenn Ihr Upstream Amazon Bedrock oder Google Cloud's Agent Platform ist, können Sie die Überbrückung vermeiden, indem Sie stattdessen das Format dieses Providers bereitstellen. Route zu einem Cloud-Provider über ein Gateway zeigt die Client-Konfiguration für dieses Format.

Wie die Verbindungsmethode das Verhalten des Clients ändert

Die Art und Weise, wie ein Entwickler sich mit Ihrem Gateway verbindet, bestimmt, welche Modell-IDs, anthropic-beta-Werte und Anforderungsfelder Claude Code sendet, und welche Standardwerte er anwendet. Ihr Gateway sieht eines von drei Client-Verhaltensweisen:

• Amazon Bedrock oder Agent Platform-Format: Der Entwickler setzt CLAUDE_CODE_USE_BEDROCK=1 mit ANTHROPIC_BEDROCK_BASE_URL oder CLAUDE_CODE_USE_VERTEX=1 mit ANTHROPIC_VERTEX_BASE_URL, die auf Ihr Gateway verweisen. Claude Code verwendet die Modell-IDs, Anforderungsfelder und Standardwerte dieses Anbieters.
• Anthropic Messages-Format: Der Entwickler setzt ANTHROPIC_BASE_URL auf Ihr Gateway. Claude Code behandelt das Gateway als die Claude API und kann nicht erkennen, an welchen Upstream Sie weiterleiten.
• Claude Apps Gateway-Anmeldung: Der Entwickler meldet sich bei einem Claude Apps Gateway an. Dieses Gateway spricht das Anthropic Messages-Format, kann aber an jeden Upstream weiterleiten, daher sendet Claude Code nur die anthropic-beta-Werte und Modell-Funktionsannahmen, die Amazon Bedrock und Agent Platform ebenfalls akzeptieren.

Anforderungen und Standardwerte nach Verbindungsmethode

Die folgende Tabelle vergleicht die drei Verbindungsmethoden, ein Verhalten pro Zeile. Sie lässt Microsoft Foundry und Claude Platform on AWS aus, die ebenfalls das Anthropic Messages-Format verwenden, aber die Claude Code über ihre eigenen Variablen erreicht. Für diese siehe die Seiten Microsoft Foundry und Claude Platform on AWS.

Für die Funktionen, die jede Verbindung unterstützt, und die Telemetrie, die sie standardmäßig an Anthropic sendet, siehe Feature-Verfügbarkeit und Standardverhalten nach API-Anbieter.

Einstellungen für nicht erkannte Modell-IDs

Zwei clientseitige Einstellungen ändern, was Claude Code für eine Modell-ID annimmt, die es nicht erkennt, unabhängig davon, welche Verbindungsmethode der Entwickler verwendet:

• Kontextfenster: Claude Code nimmt 200K an, oder 1M, wenn die ID [1m] trägt. Um das echte Fenster zu deklarieren, siehe Korrigieren Sie das Fenster für eine Gateway- oder benutzerdefinierte Modell-ID
• Funktionen: Um einem Gateway-Alias die Funktionen des dahinter liegenden Modells zu geben, ordnen Sie die Anthropic-ID dieses Modells Ihrem Alias mit einem modelOverrides-Eintrag in den Einstellungen zu, die Sie verteilen. Für den Ort, an dem die Variablen ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES gelten, siehe Feature Pass-Through

Request-Header

Claude Code enthält diese Header bei API-Anfragen. Header-Namen sind auf dem Draht case-insensitiv. Leiten Sie anthropic-version und anthropic-beta unverändert weiter, plus anthropic-workspace-id, wenn das Upstream die Claude Platform on AWS ist; der Rest kann vom Gateway zum Routing, zur Zuordnung und zum Tracing verbraucht werden und muss nicht weitergeleitet werden.

Subagenten-IDs werden bei jedem Spawn neu generiert. Teamkollegen-Agenten, die benannten Mitglieder eines Agenten-Teams, verwenden eine stabile namensbasierte ID über Wiederverbindungen hinweg. In beiden Fällen identifiziert die ID einen Agenten, keine Person oder ein Gerät, daher behandeln Sie den Agenten-ID-Header nicht als Benutzerkennung.

Wenn Ihre Entwickler ANTHROPIC_CUSTOM_HEADERS setzen, erscheinen diese Header auch bei Anfragen.

Gateway-Hinweis-Header

Claude Code kann auch Routing-Hinweise senden: anfragespezifische Fakten, die ein Gateway oder Router zum Planen, Zwischenspeichern oder Zuordnen einer Anfrage verwenden kann. Erfordert Claude Code v2.1.273 oder später.

Ob eine Anfrage diese trägt, hängt davon ab, wohin Claude Code sie sendet:

• Direkte Verbindung zur Anthropic API: standardmäßig gesendet
• Benutzerdefinierte Basis-URL: standardmäßig deaktiviert, da ein Proxy, der unbekannte Header ablehnt, die Anfrage fehlschlagen würde. Um sie zu erhalten, setzen Sie CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 für Ihre Entwickler, zum Beispiel im env Block von verwalteten Einstellungen
• Jedes andere Backend, einschließlich Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry und Claude Platform on AWS: nur gesendet, wenn CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 gesetzt ist

Das Setzen von CLAUDE_CODE_GATEWAY_HINT_HEADERS auf 0 stoppt die Header bei jeder Verbindung.

Die Header enthalten nur das, was die folgenden Zeilen auflisten: feste Vokabulare, Tool-Namen, Dauern und eine zufällige Prompt-Kennung, niemals Prompt-Text oder Dateiinhalte. Jeder Wert ist druckbares ASCII.

Bevor Sie x-claude-code-prev-tool-durations analysieren, überprüfen Sie, wie Claude Code den Wert erstellt und was es auslässt:

• Einträge: einer pro Tool-Aufruf, der lief, in der Reihenfolge, in der sein Ergebnis erfasst wurde, in ganzen Millisekunden
• Obergrenze: Claude Code sendet höchstens 32 Einträge und 4 KB, wobei die ersten Einträge beibehalten werden
• Kodierung: Tool-Namen sind prozentual kodiert, abdeckend %, ;, =, Komma, Leerzeichen und jedes Zeichen außerhalb druckbarem ASCII
• Analyse: auf ; teilen, dann auf =, und jeden Namen dekodieren
• Abwesenheit: Komprimierungsaufrufe, Seitenanfragen und die erste Anfrage eines neuen Prompts tragen ihn niemals. Lesen Sie einen fehlenden Header nicht als einen Zug, der keine Tools lief
• Zeiten: jede schließt Berechtigungsprompts und Hooks aus, und parallele Tool-Aufrufe berichten jeweils ihre eigene Zeit, daher addieren sich die Einträge nicht zur Lücke zwischen Anfragen

Weiterleitung als offene Listen

Behandeln Sie die Header und Body-Felder als offene Listen, nicht als geschlossene. Claude Code gewinnt Funktionen über Versionen hinweg, und sie kommen als neue anthropic-beta Werte, neue Request-Body-Felder und gelegentlich neue anthropic-* oder x-claude-code-* Header an.

Beim Weiterleiten an ein Anthropic-Format-Upstream leiten Sie anthropic-* Request-Header und Request-Body-Felder unverändert durch, anstatt die heute beobachteten zu allowlisten. Ein Gateway, das an eine beobachtete Liste gepinnt ist, löscht den Header oder das Feld der nächsten Funktion und bricht es bei der Veröffentlichung, die es einführt.

Die Ausnahme ist ein Nicht-Anthropic-Upstream wie Amazon Bedrock oder Google Cloud Agent Platform, wo die Überbrückung der Schemadifferenz die Aufgabe des Gateways ist; siehe Funktionsdurchleitung.

Antwortheader

Claude Code liest diese Antwortheader, um stagnierende Streams zu erkennen, um zu entscheiden, ob und wann erneut versucht werden soll, und um Nutzungslimits anzuzeigen. Die Tabelle listet auf, was für jeden Header zurückgegeben werden soll. Leiten Sie auch Fehlerantworttexte unverändert weiter, damit Claude Code's Fehlertoleranz bei Funktionsablehnung die Fehlerformulierung des Upstream-Systems abgleichen kann.

System-Prompt-Attributionsblock

Claude Code stellt einen kurzen Attributionsblock dem System-Prompt voran, der die Client-Version und einen Fingerabdruck aus dem Gespräch enthält. Der api.anthropic.com Endpunkt löscht den Block vor der Verarbeitung, wenn er unverändert als erster System-Block ankommt, daher beeinflusst er nicht das First-Party-Prompt-Caching. Jedes andere Upstream empfängt ihn als Teil des Prompts.

Das Löschen ist positionsbezogen, daher funktioniert es nur, wenn das Gateway das system Array unverändert weiterleitet. Um den Block aus dem Prompt zu halten, ohne andere System-Inhalte zu verlieren:

• Leiten Sie das system Array genau wie empfangen weiter, wobei Sie den Block an erster Stelle halten: Das Voranstellen eines weiteren System-Blocks, das Neuordnen des Arrays oder das Konvertieren in einen einzelnen String besiegt das Löschen, und der Block erreicht dann das Modell und den Prompt-Cache-Schlüssel.
• Halten Sie den Block in seinem eigenen Array-Eintrag: Der Endpunkt behandelt einen zusammengeführten Block, der mit dem Attributions-Header beginnt, als Attribution in ihrer Gesamtheit und löscht alles, das darin zusammengeführt wurde, einschließlich des restlichen System-Prompts.
• Wenn Ihr Gateway System-Inhalte umgestalten muss, setzen Sie CLAUDE_CODE_ATTRIBUTION_HEADER=0, damit Claude Code den Block auslässt. Anthropic und die Claude-Endpunkte der Cloud-Provider lesen den Block zur Zuordnung, daher lassen Sie ihn auf der Client-Seite aus, anstatt ihn im Gateway zu löschen oder zu verschieben.

Die Variable existiert für Gateway- und Third-Party-Caching-Kompatibilität, nicht als Datenschutzkontrolle: Bei einer direkten Verbindung geht die vollständige Anfrage ohnehin an die Anthropic API. Wenn beide dieser Bedingungen erfüllt sind, behält Claude Code den Block bei Auto-Modus Klassifizierungsanfragen bei, auch wenn Sie die Variable auf 0 setzen:

• Die Anfragen gehen an api.anthropic.com, wobei ANTHROPIC_BASE_URL nicht gesetzt ist oder diesen Host benennt und kein Third-Party-Provider ausgewählt ist.
• Die aktive Anmeldedaten sind keine Anthropic-Profile oder Verbundsanmeldedaten.

Klassifizierungsanfragen überspringen den Rest des System-Prompts von Claude Code, daher ist der Block bei diesen Anfragen der einzige Marker im Request-Body, der sie als Claude Code Traffic identifiziert. Wenn eine der Bedingungen fehlschlägt, über ein LLM-Gateway, bei einem Third-Party-Provider oder mit aktiven Profile- oder Verbundsanmeldedaten, entfernt das Setzen von 0 den Block auch aus Klassifizierungsanfragen. Vor v2.1.229 existierte diese Ausnahme nicht: Das Setzen von 0 entfernte den Block aus diesen Klassifizierungsanfragen, und wenn die API die nicht identifizierten Anfragen ablehnte, schlug der Auto-Modus bei jeder Aktion fehl, die er an den Klassifizierer sendete.

Ab Claude Code v2.1.181 ist der Block für die Lebensdauer eines Gesprächs stabil, wenn Anfragen durch eine benutzerdefinierte Basis-URL geleitet werden, daher funktioniert ein Gateway-seitiger Prompt-Cache, der auf dem vollständigen Request-Body basiert, ohne ihn zu deaktivieren, und jeder Provider, an den Ihr Gateway Anfragen weiterleitet, empfängt ein stabiles Prompt-Präfix. Vor v2.1.181 enthielt der Block ein Pro-Request-Token, das den Anfang des System-Prompts bei jeder Anfrage änderte. Bei diesen Versionen setzen Sie CLAUDE_CODE_ATTRIBUTION_HEADER=0, wenn Ihr Gateway eines der folgenden Dinge tut:

• Implementiert einen Prompt-Cache, der auf dem Request-Body basiert.
• Leitet Anfragen an einen Third-Party-Provider wie Amazon Bedrock, Microsoft Foundry oder Google Cloud's Agent Platform weiter, im Anthropic Messages Format oder im eigenen Format des Providers, wobei das sich ändernde Präfix die Prompt-Cache-Wiederverwendung bei diesem Provider reduziert.

Funktionsdurchleitung

Claude Code behandelt ein ANTHROPIC_BASE_URL Gateway als einen Anthropic-Format-Endpunkt und sendet ihm die Beta-Header und Request-Body-Felder, die es an api.anthropic.com sendet, außer einer kleinen Menge von Diagnosen und Standardwerten, die für direkte Verbindungen reserviert sind, wie z. B. der unten behandelte Fine-Grained-Tool-Streaming-Standard. Diese Menge variiert je nach Version, daher verlassen Sie sich nicht auf ihren Inhalt.

Fine-Grained Tool Streaming ist einer der Direct-Connection-Standardwerte: Es ist standardmäßig aus, wenn Anfragen durch eine benutzerdefinierte Basis-URL geleitet werden, und ein Gateway empfängt es, wenn Entwickler CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1 setzen.

Paare aus Beta-Header und Body-Feld

Funktionen, die Body-Felder hinzufügen, paaren sie mit einem Beta-Header, und das Paar wird gemeinsam übertragen. Ein Gateway, das den Header entfernt, während es den Body durchleitet, oder einen Anthropic-Format-Body an ein Upstream mit einem anderen Schema weiterleitet, erzeugt 400-Fehler. Wenn beide Hälften zusammen fehlen, schaltet sich die Funktion stillschweigend aus.

Ein Gateway, das Request-Bodies zur Inhaltsüberprüfung umschreibt oder redigiert, bricht die Paarung auf die gleiche Weise wie das Entfernen, daher überprüfen Sie ohne Änderung. Die Tabelle vermerkt, wo eine Funktion von der Paarung abweicht.

Die ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES Variablen deklarieren Modellkapazitäten nur in den Provider-Konfigurationen: CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_USE_FOUNDRY und CLAUDE_CODE_USE_MANTLE. Sie haben keine Auswirkung hinter einem ANTHROPIC_BASE_URL Gateway.

Automatische Wiederholung und Fehlerweiterleitung

Wenn das Upstream eine dieser Funktionen ablehnt, kann Claude Code die Anfrage selbstständig erneut versuchen, wobei der abgelehnte Teil entfernt oder geändert wird:

• Wenn ein 400 besagt, dass der thinking.type-Wert enabled oder adaptive nicht unterstützt wird, versucht Claude Code die Anfrage einmal mit dem jeweils anderen Typ erneut und behält das thinking-Feld bei. Spätere Anfragen an dieses Modell verwenden den gewechselten Typ weiter, bis Claude Code beendet wird. Vor v2.1.121 versuchte Claude Code die Anfrage nicht erneut, sodass thinking.type.enabled is not supported den Entwickler erreichte
• Wenn das Upstream einen role: "system"-Eintrag innerhalb von messages ablehnt, versucht Claude Code die Anfrage einmal ohne diese Systemnachrichten mitten in der Konversation erneut und überträgt deren Text stattdessen in Benutzernachrichten. Spätere Anfragen in der Konversation behalten diese Form bei, bis der Entwickler /clear ausführt oder die Konversation komprimiert wird
• Wenn das Upstream nur den cache_control-Marker auf einer Systemnachricht mitten in der Konversation ablehnt, behält Claude Code die Systemnachrichten bei und versucht die Anfrage einmal mit verschobenem Marker erneut. Der Marker wird auf den letzten Eintrag in messages gesetzt, der keine Systemnachricht ist, sowohl bei diesem Wiederholungsversuch als auch bei späteren Anfragen, bis Claude Code beendet wird
• Wenn das Upstream eine Thinking-Signatur ablehnt, einschließlich mit einem 400 dessen Nachricht besagt, dass der Block bound to a different conversation ist, entfernt Claude Code frühere Thinking-Blöcke aus der Anfrage, versucht erneut und hält sie aus jeder späteren Anfrage heraus. Neue Antworten enthalten immer noch Thinking
• Wenn das Gateway oder sein Upstream den Advisor-Tool Eintrag in tools als einen nicht erkannten Tool-Typ ablehnt, versucht Claude Code die Anfrage einmal ohne diesen Eintrag und seinen anthropic-beta Wert erneut. Spätere Anfragen lassen sie weg. Claude Code erkennt diese Ablehnung durch eine 400 oder 422 Antwort, deren Nachricht den Tool-Typ nach Input tag benennt, wie z. B. Input tag 'advisor_20260301'. Vor v2.1.280 wiederholte Claude Code diese Ablehnung nicht
• Wenn das Upstream output_config.effort oder seinen anthropic-beta-Wert ablehnt, sieht das Gateway die Anfrage noch einmal ohne diese. Spätere Anfragen lassen sie weg. Ihr Gateway benötigt keine Änderung, wenn es das 400 des Upstreams unverändert weiterleitet und die Nachricht:
  • output_config.effort zusammen mit Extra inputs are not permitted nennt
  • besagt, dass das Modell den Effort-Parameter nicht unterstützt
  • mit Unexpected value(s) beginnt und effort-2025-11-24 für den anthropic-beta-Header aufführt. Erfordert v2.1.310 oder später. Entwickler, deren ANTHROPIC_BETAS den Wert enthält, senden ihn weiterhin und erhalten den 400-Fehler; lassen Sie sie diesen Eintrag entfernen
• Wenn das Upstream das context_management Feld oder seinen anthropic-beta Wert ablehnt, sieht das Gateway die Anfrage noch einmal ohne diese. Spätere Anfragen lassen sie weg. Claude Code erkennt diese Ablehnung an ihrer Nachricht, zum Beispiel einer, die context_management: Extra inputs are not permitted enthält. Vor v2.1.304 wiederholte Claude Code diese Ablehnung nicht
• Wenn ein 400 einen anderen anthropic-beta-Wert namentlich ablehnt, sieht das Gateway die Anfrage noch einmal ohne ihn, sofern der Wiederholungsversuch diesen Wert abdeckt
• Wenn das Upstream ein anderes Beta-Tool-Feld als defer_loading ablehnt, etwa strict, erreicht der 400-Fehler den Entwickler. Zuvor kann das Gateway die Anfrage erneut ohne die Tool-Search-Felder sehen. Um das Senden solcher Felder zu unterbinden, lassen Sie Entwickler CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 setzen

Die bound to a different conversation Ablehnung kommt von der API-Überprüfung für preserved thinking, die fehlschlägt, wenn system, tools oder frühere messages Inhalte sich von der Anfrage unterscheiden, die das Thinking produziert hat. Ein Gateway, das einen dieser Inhalte umschreibt, kann die Ablehnung selbst verursachen; Libraries, proxies, and gateways behandelt, was unverändert durchgeleitet werden muss.

Der Großteil dieser Wiederholungslogik gleicht die Fehlerformulierung des Upstreams ab, daher leiten Sie Fehler-Response-Bodies unverändert weiter. Ein Gateway, das Upstream-Fehler in seine eigene Hülle einwickelt, bricht den Wiederherstellungspfad, auch wenn es den Statuscode beibehält, es sei denn, die Nachricht der Hülle trägt ein stabiles capability_rejected: Token. Claude Apps Gateway ersetzt diese Tokens für Cloud-Provider-Fehlerformulierungen, zum Beispiel capability_rejected: prompt_too_long.

Wiederholungsversuch ohne einen abgelehnten Beta-Wert

Wenn ein 400 einen anthropic-beta-Wert, den dieser Wiederholungsversuch abdeckt, namentlich ablehnt, sieht das Gateway die Anfrage noch einmal ohne ihn. Spätere Anfragen lassen den Wert weg. Die meisten abgedeckten Werte erfordern v2.1.314 oder später.

Ihr Gateway benötigt keine Änderung, wenn die Nachricht des von ihm zurückgegebenen 400 den Wert in einer dieser Formen enthält:

• Der Satz der API: der Unexpected value(s)-Satz, der den Wert für den anthropic-beta-Header aufführt
• Ein beta_header:-Token: capability_rejected: beta_header: gefolgt vom Wert, ein capability_rejected:-Token

Der Wiederholungsversuch deckt Fälle wie einen Wert mit eigenem Wiederholungsversuch, einen Wert, den Claude Code nicht erkennt, oder eine Nachricht, die keinen Wert nennt, nicht ab:

• Ein Wert mit eigenem Wiederholungsversuch, etwa Advisor oder Tool Search: Das Gateway sieht stattdessen den eigenen Wiederholungsversuch dieser Funktion
• Ein Wert, den Claude Code nicht erkennt: Ein Wert, den ein Entwickler über ANTHROPIC_BETAS gesetzt hat, bleibt in jeder Anfrage, sodass die Anfragen des Entwicklers weiterhin mit dem 400-Fehler fehlschlagen. Lassen Sie den Entwickler den Eintrag entfernen
• Ein bloßes invalid beta flag: Claude Code rät, welchen Wert das Upstream abgelehnt hat. Wenn die Anfrage einen Wert enthielt, auf den es dabei tippt, sieht das Gateway die Anfrage erneut ohne diesen Wert. Wenn der 400-Fehler den Entwickler dennoch erreicht, lassen Sie Ihr Gateway den abgelehnten Wert in einer dieser Formen nennen

Wie lange ein abgelehnter Beta-Wert weggelassen wird

Wiederholungsversuch ohne Tool Search

Ab v2.1.305 sendet Claude Code eine Anfrage erneut ohne defer_loading-Felder und tool_reference-Blöcke, nachdem ein 400 oder 422 eingetroffen ist, der Tool Search nennt oder dessen Ursache Claude Code nicht erkennt. Nach einem erfolgreichen Wiederholungsversuch lassen auch spätere Anfragen in dieser Konversation sie weg.

Die Anfragen des Entwicklers funktionieren ohne Änderung am Gateway weiter, wobei seine MCP-Tools vorab geladen werden. Wenn Claude Code Tool Search erneut versucht, sieht das Gateway eine weitere abgelehnte Anfrage gefolgt von ihrem Wiederholungsversuch. Für Tool Search selbst erwartet Claude Code, dass das Gateway die defer_loading-Felder und tool_reference-Blöcke zusammen mit ihrem anthropic-beta-Wert weiterleitet.

Deaktivieren Sie Pre-Release-Funktionen

Wenn Ihr Gateway oder sein Upstream Pre-Release-anthropic-beta-Werte oder die damit gepaarten Body-Felder ablehnt und Sie nicht beide Hälften weiterleiten können, lassen Sie Entwickler CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 setzen. Ist die Variable gesetzt, sendet Claude Code keine Pre-Release-Funktionen und die damit gepaarten anthropic-beta-Werte mehr, darunter:

• Kontextverwaltung und ihr context_management Body-Feld
• Die Beta-Tool-Schema-Felder wie strict und defer_loading. Die Standard-Tool-Felder name, description, input_schema und cache_control bleiben erhalten
• Das Feld output_config.format für strukturierte Ausgaben. Erfordert Claude Code v2.1.287 oder später
• Das Feld output_config.task_budget
• MCP Tool Search, sodass jedes MCP-Tool vorab geladen wird, es sei denn, Ihre Organisation hält es über verwaltete Einstellungen aktiviert

Die Variable entfernt nicht jeden anthropic-beta-Wert. Unverändert bleiben unter anderem:

• Die anthropic-beta-Werte für erweiterten Kontext, verschachteltes Denken und Aufwand, die auch Cloud-Provider akzeptieren
• Das Feld output_config.effort auf oberster Ebene. Automatische Wiederholungsversuche und Fehlerweiterleitung behandelt ein Upstream, das es ablehnt
• Das thinking Feld für Adaptive Reasoning, das keinen Beta-Header hat
• Die role: "system"-Einträge, die Systemnachrichten mitten in der Konversation enthalten
• Der OAuth-anthropic-beta-Wert, den die Abonnement-Authentifizierung benötigt
• Header-Werte und Body-Felder, die Entwickler selbst über ANTHROPIC_BETAS oder CLAUDE_CODE_EXTRA_BODY hinzufügen

Wenn eine Host-Plattform, die Claude Code einbettet, CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST setzt, stoppt CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS nicht Auto-Mode-Sitzungen auf Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry oder einem Claude Apps Gateway davon, den Server um Classifier Review zu bitten. Diese Überprüfung fügt einen anthropic-beta Wert und ein safeguards Request-Feld hinzu. Setzen Sie CLAUDE_CODE_AUTO_MODE_SERVER=0, um es dort zu stoppen.

Auf Claude Code v2.1.227 oder später kann Ihre Organisation MCP Tool-Suche unter dieser Variable durch verwaltete Einstellungen aktiviert halten. Was Claude Code mit dieser Außerkraftsetzung sendet, hängt davon ab, wie Sie sich verbinden:

• Bei einer direkten Verbindung ohne die HIPAA-Konfiguration oder durch ein Gateway mit ANTHROPIC_BASE_URL sendet Claude Code weiterhin den Tool-Search-Beta-Header, defer_loading Tool-Felder und tool_reference Blöcke
• Bei einem Cloud-Provider oder angemeldet durch ein Claude Apps Gateway, hat die Außerkraftsetzung keine Auswirkung
• In einer Sitzung, die die HIPAA-Konfiguration erhält, hat die Überschreibung keine Auswirkung und MCP Tool Search bleibt deaktiviert

Die Menge der Funktionen, die Claude Code sendet, wächst über Versionen. Für aktuelle Beta-Header-Zeichenketten siehe die Beta-Headers-Referenz; testen Sie Ihr Gateway gegen neue Claude Code-Versionen, anstatt an eine beobachtete Liste zu pinnen.

Modellermittlung

Wenn ANTHROPIC_BASE_URL auf ein Gateway verweist, das das Anthropic Messages-Format bereitstellt, kann Claude Code beim Startup den /v1/models Endpunkt des Gateways abfragen und die zurückgegebenen Modelle zur /model Auswahl hinzufügen. Wenn Sie oder Ihr Administrator replaceBuiltInOptions in einer modelPicker Konfiguration setzen, blendet Claude Code die ermittelten Modelle aus der Auswahl aus.

Entwickler aktivieren dies durch Setzen von CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, in ihrer eigenen Umgebung oder durch verwaltete Einstellungen. Die Ermittlung ist standardmäßig aus, damit Gateways, die von einem gemeinsamen API-Schlüssel unterstützt werden, nicht jedes Modell, auf das der Schlüssel zugreifen kann, jedem Benutzer anzeigen.

Wenn die Ermittlung läuft

Die Ermittlung gilt nur für das Anthropic Messages-Format. Sie läuft nicht, wenn:

• Eine beliebige CLAUDE_CODE_USE_* Provider-Variable gesetzt ist, auch wenn ANTHROPIC_BASE_URL auch gesetzt ist
• ANTHROPIC_BASE_URL nicht gesetzt ist oder auf api.anthropic.com verweist

Die Ermittlung läuft weiterhin, wenn nicht wesentlicher Traffic deaktiviert ist, da die Anfrage nur an Ihr Gateway geht. Vor v2.1.257 lief die Ermittlung nicht, während nicht wesentlicher Traffic deaktiviert war.

Request und Response

Die Anfrage ist GET /v1/models?limit=1000 mit einem 3-Sekunden-Timeout, und jede Umleitung wird als Fehler behandelt, daher können die Anmeldedaten nicht an ein Umleitungsziel durchsickern. Ein Gateway, das langsamer antwortet als das Timeout, oder eines, das /v1/models umleitet, auch http zu https, schlägt die Ermittlung stillschweigend fehl; stellen Sie den Endpunkt direkt unter der konfigurierten Basis-URL bereit.

Um einem langsamen Gateway mehr Zeit zu geben, setzen Sie CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS. Die Variable erfordert Claude Code v2.1.269 oder später.

Claude Code sendet die Ermittlungsanfrage mit beiden Anmeldedaten-Headern unten und lässt einen Header weg, dessen Wert sich nicht auflöst. Das Senden beider Header erfordert Claude Code v2.1.248 oder später. Frühere Versionen senden nur Authorization, wenn ANTHROPIC_AUTH_TOKEN gesetzt ist, und nur x-api-key andernfalls.

• Authorization: ANTHROPIC_AUTH_TOKEN als Bearer-Token, andernfalls der apiKeyHelper Wert als Bearer-Token.
• x-api-key: der API-Schlüssel, den Claude Code aufgelöst hat, wie ANTHROPIC_API_KEY. Wenn ein Helper-Wert die einzige Anmeldedaten ist, trägt dieser Header ihn auch, daher kommt der Wert in beiden Headern an.

Claude Code sendet auch alle Header von ANTHROPIC_CUSTOM_HEADERS. Wenn ein benutzerdefinierter Header einen nicht leeren Wert hat, sendet Claude Code ihn anstelle eines eingebauten Headers mit demselben Namen, wobei die Namen Groß- und Kleinschreibung ignoriert werden.

Wenn sich der Wert keines Anmeldedaten-Headers auflöst, überspringt Claude Code die Ermittlung und schreibt eine [gatewayDiscovery] skipped Zeile in das Debug-Protokoll einer claude --debug Sitzung. Wenn Sie eine Anmeldedaten nur über ANTHROPIC_CUSTOM_HEADERS bereitstellen, überspringt Claude Code weiterhin die Ermittlung.

Claude Code liest id, den optionalen display_name und die optionale description aus jedem Eintrag im data Array der Response:

{
  "data": [
    {
      "id": "claude-sonnet-4-6",
      "display_name": "Claude Sonnet 4.6",
      "description": "Default model for everyday coding tasks"
    },
    { "id": "claude-opus-4-8" }
  ]
}

Claude Code behält einen Eintrag, wenn sein id claude oder anthropic irgendwo in der Zeichenkette enthält, wobei Groß- und Kleinschreibung ignoriert wird, und ignoriert den Rest. Provider-Präfix-IDs wie vertex_ai/claude-sonnet-4-6 oder bedrock/anthropic.claude-sonnet-4-5 bestehen den Filter; eine ID, die keine der beiden Teilzeichenketten enthält, nicht. Vor v2.1.223 behielt Claude Code einen Eintrag nur, wenn sein id mit claude oder anthropic begann, was Provider-Präfix-IDs verbarg.

Auswahl-Einträge und Caching

Die Auswahl ist die interaktive Modelliste, die sich öffnet, wenn ein Entwickler /model in Claude Code ausführt. Jeder ermittelte Eintrag verwendet display_name als seinen Namen, wenn das Gateway einen sendet, der sich vom id unterscheidet. Andernfalls zeigt der Eintrag den Namen des Modells, wenn Claude Code die id erkennt, und die id, wenn nicht. Zum Beispiel erscheint ein Eintrag mit der id my-gateway-claude-sonnet-4-6 und ohne display_name als Sonnet 4.6.

Die Ermittlung fügt nur Modelle hinzu, die die availableModels verwaltete Einstellung erlaubt.

Jeder Eintrag zeigt auch die description des Modells, auf eine Zeile zusammengefasst. Ein Eintrag ohne description liest stattdessen „From gateway“. Vor v2.1.257 las jeder ermittelte Eintrag „From gateway“.

Eine ermittelte ID erhält keine eigene Zeile, wenn sie einer Zeile in der Auswahl bereits entspricht:

• Gleiche ID: die ermittelte ID entspricht genau der ID einer vorhandenen Zeile, oder die beiden IDs sind Schreibweisen derselben Fable Version.
• Gleiches Modell wie ein eingebauter Alias: wenn eine ermittelte explizite ID das Modell benennt, zu dem ein eingebauter Alias derzeit aufgelöst wird, zeigt die Auswahl nur die Alias-Zeile. Zum Beispiel, während sonnet zu claude-sonnet-5-5 aufgelöst wird, wird eine ermittelte claude-sonnet-5-5 in die sonnet Zeile zusammengefasst, und eine ermittelte claude-sonnet-5 erhält immer noch ihre eigene Zeile.

Ergebnisse werden in ~/.claude/cache/gateway-models.json oder %USERPROFILE%\.claude\cache\gateway-models.json unter Windows zwischengespeichert und bei jedem Startup aktualisiert. Wenn Sie CLAUDE_CONFIG_DIR setzen, lebt der Cache stattdessen unter diesem Verzeichnis. Wenn die Anfrage fehlschlägt oder das Gateway /v1/models nicht implementiert, fällt die Auswahl auf die zwischengespeicherte Liste aus dem vorherigen Startup oder auf die eingebaute Modelliste zurück. Wenn Ihr Gateway Claude-Modelle unter Aliasen bereitstellt, die nicht dem Ermittlungsfilter entsprechen, können Entwickler diese Aliase manuell mit den Modellkonfigurationsvariablen hinzufügen.

Verwandte Ressourcen

Für den Rest der Gateway-Dokumentationsserie und die zugrunde liegenden API-Referenzen:

• Gateway-Übersicht: was ein Gateway ist und wie Sie zwischen Claude Apps Gateway und einem anderen Produkt wählen
• Andere LLM-Gateways: wie Sie ein Gateway bereitstellen, das Ihre Organisation betreibt, und wie es mit claude.ai-Abonnements interagiert
• LLM-Gateway für Ihre Organisation bereitstellen: die Admin-Checkliste, die diesen Leitfaden verwendet
• Claude Code mit einem LLM-Gateway verbinden: Pro-Entwickler-Konfiguration und die Fehlerbehebungstabelle
• Beta-Headers-Referenz: der aktuelle Satz von anthropic-beta Werten
• Messages API: das API-Format, das ein Anthropic-Format-Gateway implementiert