Guide de compatibilité de la passerelle Claude Code

• Formats d’API et les points de terminaison à servir pour chacun
• Comportement du client par méthode de connexion : comment les ID de modèle, les valeurs anthropic-beta, les champs de requête et les valeurs par défaut diffèrent entre les formats et une connexion de passerelle des applications Claude
• En-têtes de requête : lesquels doivent atteindre l’amont et lesquels votre passerelle peut consommer
• En-têtes de réponse : ce qu’il faut retourner pour que la détection de blocage, les tentatives et l’affichage des limites d’utilisation fonctionnent
• Le bloc d’attribution du message système et comment il interagit avec la mise en cache des invites
• Passage des fonctionnalités : ce qui se casse quand les en-têtes ou les champs de corps sont supprimés
• Découverte de modèles

• Transmettre inchangé : le passer à l’amont octet par octet
• Consommer : la passerelle peut le lire pour le routage, l’attribution ou le traçage et n’a pas besoin de le transmettre

​

Formats d’API

​

Foundry et Claude Platform on AWS

​

Points de terminaison optionnels et trafic de démarrage

• Les requêtes d’inférence sont envoyées à /v1/messages?beta=true
• La méthode Google Cloud’s Agent Platform ajoute des suffixes au chemin du modèle de l’éditeur, comme dans /projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict

​

Streaming

• Si votre passerelle met une réponse en mémoire tampon jusqu’à ce qu’elle soit complète, Claude Code se bloque.
• Claude Code attend la séquence d’événements complète de chaque réponse, dans l’ordre, jusqu’aux événements finaux message_delta et message_stop. Si le corps se termine proprement après le début d’un bloc de contenu mais avant ce message_delta final, Claude Code traite la réponse comme une connexion interrompue. La réponse ci-dessus peut être incomplète décrit ce que l’utilisateur voit alors, et Tentatives automatiques indique quand Claude Code réémet plutôt la requête.
• Quand un garde-fou Amazon Bedrock bloque une réponse, les événements que Bedrock envoie peuvent référencer un bloc de contenu dont le content_block_stop est déjà arrivé, et Claude Code compte sur leur réception tels qu’ils ont été envoyés. AWS Guardrails décrit comment cette réponse se termine.
• Claude Code abandonne une réponse en streaming dès qu’aucun octet ne l’atteint pendant une durée supérieure à son délai d’inactivité de streaming. Pendant une longue pause de réflexion, les événements SSE ping en amont peuvent être les seuls octets sur le flux, donc une passerelle qui les supprime ou les met en mémoire tampon peut déclencher ce délai au milieu d’une réponse. Une passerelle qui traduit à partir d’un amont sans pings, comme le flux d’événements binaires d’Amazon Bedrock, présente la même lacune à moins d’émettre ses propres événements ping.
• Sur le format Amazon Bedrock InvokeModel, Claude Code lit la réponse /model/{model}/invoke-with-response-stream comme le corps binaire application/vnd.amazon.eventstream que Bedrock renvoie, et ne peut plus l’analyser dès qu’une passerelle le convertit en événements envoyés par le serveur ou réécrit cet en-tête Content-Type. Erreurs de streaming derrière une passerelle ou un proxy décrit ce que l’utilisateur voit alors.

​

Incompatibilité de format avec l’amont

• Quand le client parle le format Amazon Bedrock ou Google Cloud’s Agent Platform, Claude Code envoie uniquement le sous-ensemble de son ensemble complet de capacités que ces fournisseurs acceptent
• Quand le client parle le format Anthropic Messages, Claude Code envoie l’ensemble complet, même si votre passerelle relaye vers un amont Amazon Bedrock ou Google Cloud’s Agent Platform

​

Comment la méthode de connexion modifie le comportement du client

• Format Amazon Bedrock ou Agent Platform : le développeur définit CLAUDE_CODE_USE_BEDROCK=1 avec ANTHROPIC_BEDROCK_BASE_URL, ou CLAUDE_CODE_USE_VERTEX=1 avec ANTHROPIC_VERTEX_BASE_URL, pointant vers votre passerelle. Claude Code utilise les ID de modèle, les champs de requête et les valeurs par défaut de ce fournisseur.
• Format Anthropic Messages : le développeur définit ANTHROPIC_BASE_URL sur votre passerelle. Claude Code traite la passerelle comme l’API Claude et ne peut pas déterminer vers quel upstream vous transférez.
• Connexion à la passerelle des applications Claude : le développeur se connecte à une passerelle des applications Claude. Cette passerelle utilise le format Anthropic Messages mais peut router vers n’importe quel upstream, donc Claude Code envoie uniquement les valeurs anthropic-beta et les hypothèses de capacités de modèle qu’Amazon Bedrock et Agent Platform acceptent également.

​

Requêtes et valeurs par défaut selon la méthode de connexion

​

Paramètres pour les ID de modèle non reconnus

• Fenêtre de contexte : Claude Code suppose 200K, ou 1M lorsque l’ID porte [1m]. Pour déclarer la vraie fenêtre, consultez Corriger la fenêtre pour une passerelle ou un ID de modèle personnalisé
• Capacités : pour donner à un alias de passerelle les capacités du modèle derrière lui, mappez l’ID Anthropic de ce modèle à votre alias avec une entrée modelOverrides dans les paramètres que vous distribuez. Pour savoir où les variables ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES s’appliquent, consultez transmission des fonctionnalités

​

En-têtes de requête

​

En-têtes d’indication de passerelle

• Connexion directe à l’API Anthropic : envoyée par défaut
• URL de base personnalisée : désactivée par défaut, car un proxy qui rejette les en-têtes inconnus échouerait la requête. Pour les recevoir, définissez CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 pour vos développeurs, par exemple dans le bloc env des paramètres gérés
• Tout autre backend, y compris Amazon Bedrock, Agent Platform de Google Cloud, Microsoft Foundry et Claude Platform on AWS : envoyée uniquement lorsque CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 est défini

• Entrées : une par appel d’outil qui s’est exécuté, dans l’ordre où son résultat a été collecté, en millisecondes entières
• Limite : Claude Code envoie au maximum 32 entrées et 4 KB, en conservant les premières entrées
• Codage : les noms d’outils sont codés en pourcentage, couvrant %, ;, =, virgule, espace et tout caractère en dehors d’ASCII imprimable
• Analyse : divisez sur ;, puis sur =, et décodez chaque nom
• Absence : les appels de compaction, les requêtes latérales et la première requête d’une nouvelle invite ne la portent jamais. Ne lisez pas un en-tête manquant comme un tour qui n’a exécuté aucun outil
• Temps : chacun exclut les invites de permission et les hooks, et les appels d’outils parallèles rapportent chacun leur propre temps, donc les entrées ne s’ajoutent pas à l’écart entre les requêtes

​

Transmettre comme listes ouvertes

​

En-têtes de réponse

​

Bloc d’attribution du message système

• Transférez le tableau system exactement tel que reçu, en gardant le bloc en premier : ajouter un autre bloc système, réorganiser le tableau ou le convertir en une seule chaîne annule la suppression, et le bloc atteint alors le modèle et la clé du cache d’invite.
• Gardez le bloc dans sa propre entrée de tableau : le point de terminaison traite un bloc fusionné qui commence par l’en-tête d’attribution comme une attribution dans son intégralité et supprime tout ce qui y est fusionné, y compris le reste du message système.
• Si votre passerelle doit remodeler le contenu système, définissez CLAUDE_CODE_ATTRIBUTION_HEADER=0 pour que Claude Code omette le bloc. Anthropic et les points de terminaison Claude des fournisseurs de cloud lisent le bloc pour l’attribution, donc omettez-le au niveau du client plutôt que de le supprimer ou de le déplacer dans la passerelle.

• Les requêtes vont à api.anthropic.com, avec ANTHROPIC_BASE_URL non défini ou nommant cet hôte et aucun fournisseur tiers sélectionné.
• Les identifiants actifs ne sont pas une identité de profil Anthropic ou une identité de fédération.

• Implémente un cache d’invite basé sur le corps de la requête.
• Transfère les requêtes à un fournisseur tiers tel qu’Amazon Bedrock, Microsoft Foundry ou la plateforme Agent de Google Cloud, au format Messages Anthropic ou au format propre du fournisseur, où le préfixe changeant réduit la réutilisation du cache d’invite sur ce fournisseur.

​

Transmission des fonctionnalités

​

Paires d’en-tête bêta et de champ de corps

​

Nouvelle tentative automatique et transmission d’erreur

• Lorsqu’une erreur 400 indique que la valeur enabled ou adaptive de thinking.type n’est pas prise en charge, Claude Code réessaie une fois avec l’autre type et conserve le champ thinking. Les requêtes ultérieures à ce modèle conservent le type modifié jusqu’à ce que Claude Code se termine. Avant v2.1.121, Claude Code ne réessayait pas, donc thinking.type.enabled is not supported atteignait le développeur
• Lorsque l’amont rejette une entrée role: "system" dans messages, Claude Code réessaie une fois sans ces messages système en milieu de conversation et transporte plutôt leur texte dans des messages utilisateur. Les requêtes ultérieures de la conversation conservent cette forme jusqu’à ce que le développeur exécute /clear ou que la conversation soit compactée
• Lorsque l’amont rejette uniquement le marqueur cache_control sur un message système en milieu de conversation, Claude Code conserve les messages système et réessaie une fois avec le marqueur déplacé. Le marqueur est placé sur la dernière entrée de messages qui n’est pas un message système, dans cette nouvelle tentative et dans les requêtes ultérieures jusqu’à ce que Claude Code se termine
• Lorsque l’amont rejette une signature de pensée, y compris avec un 400 dont le message dit que le bloc est bound to a different conversation, Claude Code supprime les blocs de pensée antérieurs de la requête, réessaie, et les garde hors de chaque requête ultérieure. Les nouvelles réponses incluent toujours la pensée
• Lorsque la passerelle ou son amont rejette l’entrée de l’outil conseiller dans tools comme un type d’outil non reconnu, Claude Code réessaie la requête une fois sans cette entrée et sa valeur anthropic-beta. Les requêtes ultérieures les omettent. Claude Code reconnaît ce rejet par une réponse 400 ou 422 dont le message nomme le type d’outil après Input tag, comme Input tag 'advisor_20260301'. Avant v2.1.280, Claude Code ne réessayait pas ce rejet
• Lorsque l’amont rejette output_config.effort ou sa valeur anthropic-beta, la passerelle voit la requête une nouvelle fois sans eux. Les requêtes ultérieures les omettent. Votre passerelle ne nécessite aucune modification si elle transmet l’erreur 400 de l’amont sans la modifier et que le message :
  • Nomme output_config.effort avec Extra inputs are not permitted
  • Indique que le modèle ne prend pas en charge le paramètre d’effort
  • Commence par Unexpected value(s) et liste effort-2025-11-24 pour l’en-tête anthropic-beta. Nécessite v2.1.310 ou ultérieur. Les développeurs dont ANTHROPIC_BETAS liste cette valeur continuent de l’envoyer et de recevoir l’erreur 400, donc demandez-leur de supprimer cette entrée
• Lorsque l’amont rejette le champ context_management ou sa valeur anthropic-beta, la passerelle voit la requête une nouvelle fois sans eux. Les requêtes ultérieures les omettent. Claude Code reconnaît ce rejet par son message, par exemple un message contenant context_management: Extra inputs are not permitted. Avant v2.1.304, Claude Code ne réessayait pas ce rejet
• Lorsqu’une erreur 400 rejette nommément une autre valeur anthropic-beta, la passerelle voit la requête une nouvelle fois sans elle si la nouvelle tentative couvre cette valeur
• Lorsque l’amont rejette un champ d’outil bêta autre que defer_loading, tel que strict, l’erreur 400 atteint le développeur. Avant cela, la passerelle peut voir la requête de nouveau sans les champs de recherche d’outils. Pour arrêter l’envoi de tels champs, demandez aux développeurs de définir CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

​

Réessayer sans une valeur bêta rejetée

• La phrase de l’API : la phrase Unexpected value(s) qui liste la valeur pour l’en-tête anthropic-beta
• Un jeton beta_header: : capability_rejected: beta_header: suivi de la valeur, un jeton capability_rejected:

• Une valeur disposant de sa propre nouvelle tentative, comme le conseiller ou la recherche d’outils : la passerelle voit plutôt la nouvelle tentative propre à cette capacité
• Une valeur que Claude Code ne reconnaît pas : une valeur qu’un développeur a définie via ANTHROPIC_BETAS reste sur chaque requête, de sorte que les requêtes du développeur continuent d’échouer avec l’erreur 400. Demandez au développeur de supprimer cette entrée
• Un simple invalid beta flag : Claude Code devine quelle valeur l’amont a rejetée. Si la requête portait une valeur qu’il soupçonne, la passerelle voit la requête de nouveau sans cette valeur. Si l’erreur 400 atteint encore le développeur, faites en sorte que votre passerelle nomme la valeur rejetée sous l’une de ces formes

​

Combien de temps une valeur bêta rejetée reste omise

​

Réessayer sans la recherche d’outils

​

Désactiver les capacités de pré-version

• La gestion du contexte et son champ de corps context_management
• Les champs de schéma d’outil bêta, tels que strict et defer_loading. Les champs d’outil standard name, description, input_schema et cache_control sont conservés
• Le champ de sortie structurée output_config.format. Nécessite Claude Code v2.1.287 ou ultérieur
• Le champ output_config.task_budget
• La recherche d’outils MCP, de sorte que chaque outil MCP se charge dès le départ, sauf si votre organisation la maintient activée via les paramètres gérés

• Les valeurs anthropic-beta pour le contexte étendu, la réflexion entrelacée et l’effort, que les fournisseurs de cloud acceptent également
• Le champ output_config.effort de premier niveau. Nouvelle tentative automatique et transmission d’erreur couvre le cas d’un amont qui le rejette
• Le champ thinking du raisonnement adaptatif, qui n’a pas d’en-tête bêta
• Les entrées role: "system" qui portent les messages système en milieu de conversation
• La valeur anthropic-beta OAuth que l’authentification par abonnement exige
• Les valeurs d’en-tête et champs de corps que les développeurs ajoutent eux-mêmes via ANTHROPIC_BETAS ou CLAUDE_CODE_EXTRA_BODY

• Sur une connexion directe sans la configuration HIPAA, ou via une passerelle définie avec ANTHROPIC_BASE_URL, Claude Code continue d’envoyer l’en-tête bêta de recherche d’outils, les champs d’outil defer_loading et les blocs tool_reference
• Sur un fournisseur de cloud, ou connecté via une passerelle des applications Claude, le remplacement n’a aucun effet
• Dans une session qui reçoit la configuration HIPAA, le remplacement n’a aucun effet et la recherche d’outils reste désactivée

​

Découverte des modèles

​

Quand la découverte s’exécute

• Toute variable de fournisseur CLAUDE_CODE_USE_* est définie, même si ANTHROPIC_BASE_URL est également défini
• ANTHROPIC_BASE_URL n’est pas défini ou pointe vers api.anthropic.com

​

Requête et réponse

• Authorization : ANTHROPIC_AUTH_TOKEN comme jeton porteur, sinon la valeur apiKeyHelper comme jeton porteur.
• x-api-key : la clé API que Claude Code a résolue, telle que ANTHROPIC_API_KEY. Lorsqu’une valeur d’aide est la seule identifiant, cet en-tête la porte également, de sorte que la valeur arrive dans les deux en-têtes.

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

​

Entrées du sélecteur et mise en cache

• Même ID : l’ID découvert correspond exactement à l’ID d’une ligne existante, ou les deux ID sont des orthographes de la même version Fable.
• Même modèle qu’un alias intégré : lorsqu’un ID explicite découvert nomme le modèle auquel un alias intégré se résout actuellement, le sélecteur affiche uniquement la ligne d’alias. Par exemple, tandis que sonnet se résout en claude-sonnet-5-5, un claude-sonnet-5-5 découvert est fusionné dans la ligne sonnet, et un claude-sonnet-5 découvert obtient toujours sa propre ligne.

​

Ressources connexes

• Aperçu des passerelles : ce qu’est une passerelle et comment choisir entre la passerelle Claude apps et un autre produit
• Autres passerelles LLM : comment déployer une passerelle que votre organisation exécute et comment elle interagit avec les abonnements claude.ai
• Déployer une passerelle LLM pour votre organisation : la liste de contrôle d’administration qui utilise ce guide
• Connecter Claude Code à une passerelle LLM : configuration par développeur et le tableau de dépannage
• Référence des en-têtes bêta : l’ensemble actuel des valeurs anthropic-beta
• API Messages : le format API qu’une passerelle au format Anthropic implémente