Guide de compatibilité de la passerelle Claude Code

Maintenez une passerelle LLM compatible avec Claude Code : les points de terminaison qu'elle appelle, les en-têtes et champs de corps à transmettre, et ce qui se casse quand ils sont supprimés.

Cette page documente les requêtes que Claude Code envoie à une passerelle, y compris les points de terminaison qu'elle appelle, les en-têtes et champs de corps que la passerelle doit transmettre, et quelles fonctionnalités cessent de fonctionner si elle ne le fait pas. Elle est écrite pour les opérateurs configurant un produit de passerelle pour fonctionner avec Claude Code.

La passerelle des applications Claude, la passerelle auto-hébergée d'Anthropic, sert sa propre référence de point de terminaison à GET /protocol, couvrant les points de terminaison de connexion, d'inférence, de paramètres gérés, de découverte de modèles et de télémétrie de cette passerelle. C'est un document séparé de ce guide.

Cette page couvre :

• 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

Cette page utilise deux termes pour ce que votre passerelle fait avec chaque en-tête et champ de corps :

• 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

Tout ce qui n'est pas marqué comme transmettre inchangé est vôtre à consommer ou ignorer.

Formats d'API

Une passerelle doit exposer au moins l'un des formats d'API suivants aux clients Claude Code. Un client choisit un format et pointe Claude Code vers votre passerelle avec les variables dans la colonne Sélectionné par du tableau ci-dessous.

Google Cloud's Agent Platform est le point de terminaison Claude de Google Cloud, anciennement Vertex AI ; ses noms de variables conservent l'orthographe VERTEX.

Foundry et Claude Platform on AWS

Microsoft Foundry et la Claude Platform on AWS implémentent le format Anthropic Messages. Claude Code les route via leurs propres variables, ANTHROPIC_FOUNDRY_BASE_URL et ANTHROPIC_AWS_BASE_URL, mais une passerelle les frontalisant implémente la ligne Anthropic Messages ci-dessus. Une passerelle frontalisant Claude Platform on AWS doit également transférer l'en-tête anthropic-workspace-id, que cette plateforme exige sur chaque requête.

Points de terminaison optionnels et trafic de démarrage

Les points de terminaison de comptage de jetons sont les seuls optionnels : en leur absence, Claude Code revient à une estimation basée sur les caractères de l'utilisation du contexte.

Faites correspondre le chemin, pas l'URL complète :

• 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

Une passerelle voit également du trafic de démarrage au meilleur effort qu'elle peut rejeter sans rien casser. Une passerelle au format Anthropic Messages reçoit une sonde de préchauffage de connexion HEAD /api/hello, que Claude Code ignore quand un proxy HTTP ou un certificat client est configuré. Une passerelle au format Amazon Bedrock reçoit une requête GET /inference-profiles?type=SYSTEM_DEFINED et, quand le modèle configuré est un profil d'inférence, des recherches GET /inference-profiles/{profile}.

La vérification de disponibilité du mode rapide n'apparaît jamais dans les journaux de passerelle : elle appelle api.anthropic.com directement plutôt que de suivre ANTHROPIC_BASE_URL, donc sur un réseau qui bloque la sortie directe vers api.anthropic.com, le mode rapide peut signaler une erreur de connectivité tandis que l'inférence via la passerelle continue de fonctionner. La vérification de sécurité du domaine WebFetch appelle également api.anthropic.com directement. Utiliser le mode rapide derrière les proxies et les passerelles LLM couvre les variables qui le restaurent.

Streaming

Diffusez les réponses d'inférence en continu. Claude Code lit le flux au fur et à mesure de son arrivée, donc si votre passerelle met en mémoire tampon les réponses complètes avant de les relayer, Claude Code s'arrête.

Quand le client parle le format Amazon Bedrock, relayez le corps de réponse InvokeModelWithResponseStream et son en-tête Content-Type: application/vnd.amazon.eventstream sans modification, et ne convertissez pas le flux en événements envoyés par le serveur. Voir Erreurs de streaming derrière une passerelle ou un proxy.

Transférez également les pings de maintien de connexion. Sur les connexions via ANTHROPIC_BASE_URL ou ANTHROPIC_AWS_BASE_URL, Claude Code compte chaque octet que votre passerelle relaye, y compris les événements SSE ping et les lignes de commentaire, et abandonne un flux qui reste silencieux pendant 300 secondes par défaut. Les pings en amont sont le seul trafic pendant les pauses de réflexion prolongées, donc si votre passerelle les supprime ou les met en mémoire tampon, Claude Code abandonne le flux pendant ces pauses ; Tentatives automatiques couvre ce qu'un flux abandonné signale en fonction de la progression de la réponse. Un amont qui n'envoie aucun ping du tout, comme le flux d'événements binaires d'Amazon Bedrock, laisse ces pauses sans rien à relayer. Lors de la traduction à partir d'un tel amont, émettez vos propres événements ping pendant les silences. Les passerelles atteintes via ANTHROPIC_BEDROCK_BASE_URL, ANTHROPIC_VERTEX_BASE_URL, ou ANTHROPIC_FOUNDRY_BASE_URL ne sont pas enveloppées par ce chien de garde au niveau des octets, même quand elles relaient le format Anthropic Messages ; là, un délai d'inactivité de 5 minutes abandonne un flux silencieux à la place, et sur les connexions ANTHROPIC_BEDROCK_BASE_URL vous pouvez ajouter le chien de garde au niveau des octets avec CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK.

Incompatibilité de format avec l'amont

Le format que le client parle détermine ce que votre passerelle reçoit. Le mode de défaillance courant est une incompatibilité entre le format que le client envoie à votre passerelle et le format que le fournisseur amont derrière elle accepte.

• 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

Combler cette différence est le travail de votre passerelle. Passage des fonctionnalités décrit ce qui se casse quand ce n'est pas le cas.

Si votre amont est Amazon Bedrock ou Google Cloud's Agent Platform, vous pouvez éviter le pontage en exposant le format de ce fournisseur à la place. Router vers un fournisseur cloud via une passerelle montre la configuration du client pour ce format.

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

La façon dont un développeur se connecte à votre passerelle détermine les ID de modèle, les valeurs anthropic-beta et les champs de requête que Claude Code envoie, ainsi que les valeurs par défaut qu'il applique. Votre passerelle voit l'un des trois comportements clients suivants :

• 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

Le tableau ci-dessous compare les trois méthodes de connexion, un comportement par ligne. Il omet Microsoft Foundry et Claude Platform sur AWS, qui utilisent également le format Anthropic Messages mais que Claude Code atteint via leurs propres variables. Pour ceux-ci, consultez les pages Microsoft Foundry et Claude Platform sur AWS.

Pour les fonctionnalités que chaque connexion supporte et la télémétrie qu'elle envoie à Anthropic par défaut, consultez Disponibilité des fonctionnalités et Comportements par défaut selon le fournisseur d'API.

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

Deux paramètres côté client modifient ce que Claude Code suppose pour un ID de modèle qu'il ne reconnaît pas, quelle que soit la méthode de connexion utilisée par le développeur :

• 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

Claude Code inclut ces en-têtes sur les requêtes API. Les noms d'en-têtes ne sont pas sensibles à la casse sur le fil. Transmettez anthropic-version et anthropic-beta inchangés, plus anthropic-workspace-id lorsque l'amont est la Claude Platform on AWS ; le reste, la passerelle peut le consommer pour le routage, l'attribution et le suivi, et n'a pas besoin de le transmettre.

Les ID de sous-agent sont générés à nouveau pour chaque génération. Les agents coéquipiers, les membres nommés d'une équipe d'agents, réutilisent un ID stable basé sur le nom à travers les reconnexions. Dans les deux cas, l'ID identifie un agent, pas une personne ou un appareil, donc ne traitez pas l'en-tête d'ID d'agent comme un identifiant d'utilisateur.

Si vos développeurs définissent ANTHROPIC_CUSTOM_HEADERS, ces en-têtes apparaissent également sur les requêtes.

En-têtes d'indication de passerelle

Claude Code peut également envoyer des indications de routage : des faits par requête qu'une passerelle ou un routeur peut utiliser pour planifier, mettre en cache ou attribuer une requête. Nécessite Claude Code v2.1.273 ou ultérieur.

Le fait qu'une requête les porte dépend de l'endroit où Claude Code l'envoie :

• 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

Définir CLAUDE_CODE_GATEWAY_HINT_HEADERS à 0 arrête les en-têtes sur chaque connexion.

Les en-têtes ne portent que ce que les lignes ci-dessous énumèrent : vocabulaires fixes, noms d'outils et durées, jamais de texte d'invite ou de contenu de fichier. Chaque valeur est ASCII imprimable.

Avant d'analyser x-claude-code-prev-tool-durations, vérifiez comment Claude Code construit la valeur et ce qu'il omet :

• 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

Traitez les en-têtes et champs de corps comme des listes ouvertes, pas fermées. Claude Code gagne des capacités au fil des versions, et elles arrivent comme de nouvelles valeurs anthropic-beta, de nouveaux champs de corps de requête, et occasionnellement de nouveaux en-têtes anthropic-* ou x-claude-code-*.

Lors de la transmission à un amont au format Anthropic, transmettez les en-têtes de requête anthropic-* et les champs de corps de requête inchangés plutôt que de mettre en liste blanche ceux que vous voyez aujourd'hui. Une passerelle épinglée à une liste observée supprime l'en-tête ou le champ de la capacité suivante et la casse à la version qui l'introduit.

L'exception est un amont non-Anthropic tel qu'Amazon Bedrock ou Agent Platform de Google Cloud, où combler la différence de schéma est le travail de la passerelle ; consultez transmission des fonctionnalités.

En-têtes de réponse

Claude Code lit ces en-têtes de réponse pour détecter les flux bloqués, pour décider s'il faut relancer et quand, et pour afficher les limites d'utilisation. Le tableau liste ce qu'il faut retourner pour chacun. Transmettez également les corps de réponse d'erreur sans modification, afin que la récupération de rejet de capacité de Claude Code puisse correspondre à la formulation d'erreur en amont.

Bloc d'attribution du message système

Claude Code ajoute un bloc d'attribution court au message système contenant la version du client et une empreinte dérivée de la conversation. Le point de terminaison api.anthropic.com supprime le bloc avant le traitement lorsqu'il arrive inchangé comme premier bloc système, donc il n'affecte pas la mise en cache des invites de première partie. Tout autre amont le reçoit comme faisant partie de l'invite.

La suppression est positionnelle, donc elle ne fonctionne que lorsque la passerelle transfère le tableau system inchangé. Pour garder le bloc hors de l'invite sans perdre d'autre contenu 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.

La variable existe pour la compatibilité des passerelles et de la mise en cache tiers, et non comme contrôle de confidentialité : sur une connexion directe, la requête complète va à l'API Anthropic de toute façon. Lorsque ces deux conditions sont remplies, Claude Code conserve le bloc sur les requêtes du classificateur en mode auto même lorsque vous définissez la variable sur 0 :

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

Les requêtes du classificateur ignorent le reste du message système de Claude Code, donc sur ces requêtes le bloc est le seul marqueur dans le corps de la requête qui les identifie comme du trafic Claude Code. Lorsque l'une des conditions échoue, via une passerelle LLM, sur un fournisseur tiers, ou avec une identité de profil ou de fédération active, la définition de 0 supprime également le bloc des requêtes du classificateur. Avant v2.1.229, cette exception n'existait pas : la définition de 0 supprimait le bloc de ces requêtes du classificateur, et lorsque l'API refusait les requêtes non identifiées, le mode auto échouait sur chaque action qu'il envoyait au classificateur.

À partir de Claude Code v2.1.181, le bloc est stable pour la durée de vie d'une conversation lorsque les requêtes sont routées via une URL de base personnalisée, donc un cache d'invite côté passerelle basé sur le corps de requête complet fonctionne sans le désactiver, et tout fournisseur vers lequel votre passerelle transfère les requêtes reçoit un préfixe d'invite stable. Avant v2.1.181, le bloc incluait un jeton par requête qui changeait le début du message système à chaque requête. Sur ces versions, définissez CLAUDE_CODE_ATTRIBUTION_HEADER=0 lorsque votre passerelle fait l'une de ces choses :

• 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

Claude Code traite une passerelle ANTHROPIC_BASE_URL comme un point de terminaison au format Anthropic et lui envoie les en-têtes bêta et champs de corps de requête qu'il envoie à api.anthropic.com, sauf un petit ensemble de diagnostics et de valeurs par défaut réservés aux connexions directes, comme la valeur par défaut de streaming d'outils à grain fin couverte ci-dessous. Cet ensemble varie selon la version, donc ne dépendez pas de son contenu.

Les capacités qui ajoutent des champs de corps les associent à un en-tête bêta, et la paire voyage ensemble. Une passerelle qui supprime l'en-tête tout en transmettant le corps, ou transmet un corps au format Anthropic à un amont avec un schéma différent, produit des erreurs 400 dures ; seulement lorsque les deux moitiés sont absentes ensemble la fonctionnalité s'éteint silencieusement. Une passerelle qui réécrit ou rédige les corps de requête pour l'inspection du contenu casse l'appairage de la même manière que la suppression, donc inspectez sans modifier. Le tableau note où une fonctionnalité s'écarte de l'appairage.

Le streaming d'outils à grain fin est l'une des valeurs par défaut de connexion directe : il est désactivé par défaut chaque fois que les requêtes sont routées via une URL de base personnalisée, et une passerelle le reçoit lorsque les développeurs définissent CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1.

Les variables ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES déclarent les capacités du modèle uniquement dans les configurations du fournisseur : CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_USE_FOUNDRY, et CLAUDE_CODE_USE_MANTLE. Elles n'ont aucun effet derrière une passerelle ANTHROPIC_BASE_URL.

Nouvelle tentative automatique et transmission d'erreur

Ce que Claude Code fait après un rejet en amont dépend de ce qui a été rejeté :

• Lorsque l'amont rejette le champ thinking, un message système en milieu de conversation, ou le marqueur cache_control sur un tel message, Claude Code réessaie la requête et désactive la capacité rejetée pour le reste de la conversation
• 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 à cette URL de base laissent le conseiller de côté jusqu'à ce que Claude Code se termine, et /advisor n'est pas disponible pour le développeur pendant ce temps. 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
• Claude Code ne réessaie pas les rejets de gestion du contexte ou de champ de schéma d'outil, donc ces erreurs 400 atteignent le développeur

Le rejet bound to a different conversation provient de la vérification de pensée préservée de l'API, qui échoue lorsque le contenu system, tools, ou messages antérieurs diffère de la requête qui a produit la pensée. Une passerelle qui réécrit l'un de ces contenus peut causer le rejet lui-même ; Bibliothèques, proxies et passerelles couvre ce qu'il faut transmettre inchangé.

La logique de nouvelle tentative correspond à la formulation d'erreur de l'amont, donc transmettez les corps de réponse d'erreur inmodifiés. Une passerelle qui enveloppe les erreurs en amont dans sa propre enveloppe casse le chemin de récupération, même lorsqu'elle préserve le code d'état, sauf si le message de l'enveloppe porte un jeton capability_rejected: stable. La passerelle des applications Claude substitue ces jetons à la formulation d'erreur des fournisseurs de cloud, par exemple capability_rejected: prompt_too_long.

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

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 empêche Claude Code d'envoyer les capacités de pré-version et leurs champs de corps sur chaque fournisseur, y compris la gestion du contexte et les champs d'outil bêta. La variable n'affecte pas le raisonnement adaptatif, qui est sélectionné par modèle plutôt que par bêta. Elle ne supprime jamais la capacité OAuth que l'authentification par abonnement exige.

Sur Claude Code v2.1.227 ou ultérieur, votre organisation peut maintenir la recherche d'outils MCP activée sous cette variable via les paramètres gérés. Ce que Claude Code envoie avec ce remplacement en place dépend de la façon dont vous vous connectez :

• Sur une connexion directe, 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, et supprime le reste
• Sur un fournisseur de cloud, ou connecté via une passerelle des applications Claude, le remplacement n'a aucun effet

L'ensemble des capacités que Claude Code envoie augmente au fil des versions. Pour les chaînes d'en-tête bêta actuelles, consultez la référence des en-têtes bêta ; testez votre passerelle contre les nouvelles versions de Claude Code plutôt que de vous épingler à une liste observée.

Découverte des modèles

Lorsque ANTHROPIC_BASE_URL pointe vers une passerelle qui expose le format Messages Anthropic, Claude Code peut interroger le point de terminaison /v1/models de la passerelle au démarrage et ajouter les modèles retournés au sélecteur /model. Si vous ou votre administrateur définissez replaceBuiltInOptions dans une configuration modelPicker, Claude Code masque les modèles découverts du sélecteur.

Les développeurs l'activent en définissant CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, dans leur propre environnement ou via les paramètres gérés. La découverte est désactivée par défaut afin que les passerelles soutenues par une clé API partagée ne surface pas chaque modèle auquel la clé peut accéder à chaque utilisateur.

Quand la découverte s'exécute

La découverte s'applique uniquement au format Messages Anthropic. Elle ne s'exécute pas lorsque :

• 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

La découverte s'exécute toujours lorsque le trafic non essentiel est désactivé, car la requête ne va que vers votre passerelle. Avant v2.1.257, la découverte ne s'exécutait pas lorsque le trafic non essentiel était désactivé.

Requête et réponse

La requête est GET /v1/models?limit=1000 avec un délai d'expiration de 3 secondes par défaut, et toute redirection est traitée comme un échec afin que l'identifiant ne puisse pas fuir vers une cible de redirection. Une passerelle qui répond lentement que le délai d'expiration, ou une qui redirige /v1/models, même http vers https, échoue silencieusement la découverte ; servez le point de terminaison directement à l'URL de base configurée.

Pour donner à une passerelle lente plus de temps, définissez CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS. La variable nécessite Claude Code v2.1.269 ou version ultérieure.

Claude Code envoie la requête de découverte avec les deux en-têtes d'identifiant ci-dessous et omet un en-tête dont la valeur ne se résout pas. L'envoi des deux en-têtes nécessite Claude Code v2.1.248 ou version ultérieure. Les versions antérieures envoient uniquement Authorization lorsque ANTHROPIC_AUTH_TOKEN est défini et uniquement x-api-key sinon.

• Authorization : ANTHROPIC_AUTH_TOKEN comme jeton porteur, sinon la valeur apiKeyHelper comme jeton porteur. Dans ce cas, Claude Code attend que l'aide retourne avant d'envoyer la requête.
• 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.

Claude Code envoie également tous les en-têtes de ANTHROPIC_CUSTOM_HEADERS. Lorsqu'un en-tête personnalisé a une valeur non vide, Claude Code l'envoie à la place d'un en-tête intégré du même nom, en faisant correspondre les noms sans tenir compte de la casse.

Lorsqu'aucune valeur d'en-tête d'identifiant ne se résout, Claude Code ignore la découverte et écrit une ligne [gatewayDiscovery] skipped dans le journal de débogage d'une session claude --debug. Si vous fournissez un identifiant uniquement via ANTHROPIC_CUSTOM_HEADERS, Claude Code ignore toujours la découverte.

Claude Code lit id, le display_name optionnel et la description optionnelle de chaque entrée dans le tableau data de la réponse :

{
  "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 conserve une entrée lorsque son id contient claude ou anthropic n'importe où dans la chaîne, en faisant correspondre sans tenir compte de la casse, et ignore le reste. Les ID préfixés par le fournisseur tels que vertex_ai/claude-sonnet-4-6 ou bedrock/anthropic.claude-sonnet-4-5 passent le filtre ; un ID qui ne contient aucune des deux sous-chaînes ne le fait pas. Avant v2.1.223, Claude Code conservait une entrée uniquement lorsque son id commençait par claude ou anthropic, ce qui masquait les ID préfixés par le fournisseur.

Entrées du sélecteur et mise en cache

Le sélecteur est la liste de modèles interactive qui s'ouvre lorsqu'un développeur exécute /model dans Claude Code. Chaque entrée découverte utilise display_name comme nom lorsque la passerelle en envoie un qui diffère de l'id. Sinon, l'entrée affiche le nom du modèle lorsque Claude Code reconnaît l'id, et l'id lorsqu'il ne le reconnaît pas. Par exemple, une entrée avec l'id my-gateway-claude-sonnet-4-6 et aucun display_name apparaît comme Sonnet 4.6.

La découverte ajoute uniquement les modèles que le paramètre géré availableModels autorise.

Chaque entrée affiche également la description du modèle, réduite à une ligne. Une entrée sans description lit « Depuis la passerelle » à la place. Avant v2.1.257, chaque entrée découverte lisait « Depuis la passerelle ».

Un ID découvert n'obtient pas sa propre ligne lorsqu'il correspond à une ligne déjà dans le sélecteur :

• 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, un claude-sonnet-5 découvert s'effondre dans la ligne sonnet, et un claude-sonnet-4-6 découvert obtient toujours sa propre ligne. Avant v2.1.197, Claude Code ne fusionnait pas ces ID dans les lignes intégrées, donc claude-sonnet-5 obtenait également sa propre ligne « Depuis la passerelle ».

Les résultats sont mis en cache dans ~/.claude/cache/gateway-models.json, ou %USERPROFILE%\.claude\cache\gateway-models.json sur Windows, et actualisés à chaque démarrage. Si vous définissez CLAUDE_CONFIG_DIR, le cache se trouve sous ce répertoire à la place. Si la requête échoue ou la passerelle n'implémente pas /v1/models, le sélecteur revient à la liste mise en cache du démarrage précédent ou à la liste de modèles intégrée. Si votre passerelle sert les modèles Claude sous des alias qui ne correspondent pas au filtre de découverte, les développeurs peuvent ajouter ces alias manuellement avec les variables de configuration du modèle.

Ressources connexes

Pour le reste de l'ensemble de documentation de passerelle et les références API sous-jacentes :

• 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