Claude Code Gateway-Kompatibilitätsleitfaden

• 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

• 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

​

API-Formate

​

Foundry und Claude Platform on AWS

​

Optionale Endpunkte und Startup-Traffic

• 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

​

Streaming

• 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

• 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

​

Wie die Verbindungsmethode das Verhalten des Clients ändert

• 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

​

Einstellungen für nicht erkannte Modell-IDs

• 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

​

Gateway-Hinweis-Header

• 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

• 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

​

Antwortheader

​

System-Prompt-Attributionsblock

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

• 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

​

Paare aus Beta-Header und Body-Feld

​

Automatische Wiederholung und Fehlerweiterleitung

• 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

​

Wiederholungsversuch ohne einen abgelehnten Beta-Wert

• 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

• 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

​

Deaktivieren Sie Pre-Release-Funktionen

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

• 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

​

Modellermittlung

​

Wenn die Ermittlung läuft

• 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

​

Request und Response

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

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

​

Auswahl-Einträge und Caching

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

​

Verwandte Ressourcen

• 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