Connecter Claude Code à une passerelle LLM

Une passerelle LLM est un proxy que votre organisation exécute entre Claude Code et le fournisseur de modèle. Lorsque votre organisation en utilise une, Claude Code s’authentifie auprès de la passerelle avec un identifiant que votre organisation émet au lieu de votre connexion personnelle claude.ai. Cette page est destinée aux développeurs exécutant Claude Code via une passerelle que leur organisation exploite. Elle couvre deux chemins : vérifier si votre administrateur l’a déjà configurée pour vous, et la configurer vous-même s’il ne l’a pas fait.

Pour déployer une passerelle pour votre organisation, voir Déployer une passerelle LLM
Pour savoir ce que Claude Code envoie à une passerelle, voir la référence du protocole de passerelle

Vérifier une configuration existante

Les administrateurs peuvent distribuer l’adresse de la passerelle et l’identifiant via les paramètres gérés, la gestion des appareils, ou un apiKeyHelper, de sorte que Claude Code les récupère au démarrage sans rien à configurer de votre côté. Pour vérifier si votre organisation l’a déjà fait :

Démarrer Claude Code

Exécutez claude. S’il s’ouvre sur l’écran de connexion au lieu d’une session, aucun identifiant de passerelle n’a été distribué ; configurez-le vous-même ci-dessous.

Vérifier l'onglet Statut

Si Claude Code a démarré une session sans afficher l’écran de connexion, exécutez /status, ouvrez l’onglet Status, et vérifiez deux lignes :

Anthropic base URL : cette ligne n’apparaît que lorsqu’une adresse de passerelle est définie. Si elle n’est pas là, Claude Code n’est pas pointé vers la passerelle ; configurez-le vous-même ci-dessous.
Auth token ou API key : une ligne nommant ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, ou un apiKeyHelper confirme qu’un identifiant de passerelle est actif. Une ligne Login method nommant un compte claude.ai à la place signifie que l’identifiant n’a pas été distribué ; définissez-le vous-même.

Envoyer un message de test

Fermez le menu /status et envoyez n’importe quel message dans Claude Code. Une réponse normale de Claude, sans erreur, confirme que la connexion à la passerelle fonctionne.

Si les deux lignes du menu /status semblent correctes mais que le message à Claude échoue, voir le tableau de dépannage.

Configurer Claude Code vous-même

Pour configurer Claude Code pour la passerelle vous-même, vous avez besoin de votre équipe de passerelle :

L’URL de base de la passerelle
Un identifiant : une chaîne de clé ou de jeton, ou une commande qui en récupère un
- Si votre équipe de passerelle n’a pas dit quel type d’identifiant c’est, la section variable d’identifiant ci-dessous couvre ce qu’il faut essayer

Les sections ci-dessous couvrent la configuration dans l’ordre :

Définir la variable d’identifiant et définir l’URL de base : les deux variables que chaque connexion de passerelle nécessite
Vérifier la connexion : confirmer qu’elle fonctionne avant de persister quoi que ce soit
Configurer chaque surface : si vous utilisez une surface autre que la CLI Claude Code, comme VS Code, voir comment la configurer avec vos identifiants de passerelle
Configuration supplémentaire : variables que certaines passerelles nécessitent au-delà de l’URL de base et de l’identifiant, comme un en-tête personnalisé, un assistant d’identifiant, la découverte de modèle, ou une URL de base au format fournisseur. Définissez-les uniquement si votre administrateur les a nommées

Définir la variable d’identifiant

Pour authentifier Claude Code auprès de la passerelle, définissez votre identifiant dans une variable d’environnement. Quelle variable dépend de ce que votre équipe de passerelle vous a dit :

Définir l’identifiant dans	Utiliser quand
`ANTHROPIC_AUTH_TOKEN`	Votre équipe de passerelle a dit ’ bearer token ’ ou ’ Authorization header ‘
`ANTHROPIC_API_KEY`	Votre équipe de passerelle a dit ’ API key ’ ou ’ x-api-key ‘
`apiKeyHelper`	L’identifiant tourne ou provient d’un coffre-fort

Si vous n’avez pas été informé du type, utilisez ANTHROPIC_AUTH_TOKEN ; la demande de vérification ci-dessous montre comment savoir si vous devez basculer.

Définir l’URL de base et l’identifiant

Définissez l’URL de base de la passerelle et la variable d’identifiant que vous avez choisie ci-dessus comme variables d’environnement. Les exemples utilisent ANTHROPIC_AUTH_TOKEN ; remplacez-le par ANTHROPIC_API_KEY si c’est la variable que vous avez choisie. Vous pouvez les définir dans votre shell, ce qui dure une session de terminal, ou dans un fichier de paramètres Claude Code, ce qui persiste partout où Claude Code s’exécute. Pour votre première connexion, commencez par les exports shell et exécutez la demande de vérification avant de déplacer les valeurs vers un fichier de paramètres.

Définir comme variables d’environnement shell

Remplacez les valeurs par celles que votre équipe de passerelle vous a données :

Bash ou Zsh
PowerShell

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-gateway-key

$env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"

Les exports shell s’appliquent uniquement à cette session de terminal et aux programmes lancés à partir de celle-ci ; un éditeur lancé depuis le dock ou le menu Démarrer ne les verra pas. Pour les faire persister dans les nouveaux terminaux, ajoutez les mêmes lignes à votre profil shell, comme ~/.zshrc, ~/.bashrc, ou votre $PROFILE PowerShell, ou utilisez plutôt un fichier de paramètres.

Définir dans un fichier de paramètres

Pour que la configuration s’applique partout où Claude Code s’exécute sans dépendre de votre shell, définissez les variables dans le bloc env d’un fichier de paramètres. Les fichiers de paramètres ont des portées différentes :

~/.claude/settings.json s’applique à tous vos projets. Sur Windows, le chemin est %USERPROFILE%\.claude\settings.json
.claude/settings.local.json s’applique à un projet. Claude Code l’ajoute à votre gitignore quand il crée le fichier ; si vous le créez vous-même, ajoutez-le à votre gitignore manuellement d’abord pour ne pas accidentellement valider votre identifiant

Ne mettez pas l’identifiant dans le .claude/settings.json d’un projet. Ce fichier est validé et partagé avec tous ceux qui clonent le référentiel.

Le bloc env ressemble au même dans l’un ou l’autre fichier :

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-gateway-key"
  }
}

Quand un export shell et un bloc env de fichier de paramètres définissent la même variable, la valeur du fichier de paramètres s’applique. Exécutez /status pour voir quelle URL de base et source d’identifiant Claude Code utilise.

Vérifier la connexion

Avec les variables exportées dans votre shell, envoyez une demande d’un jeton à la passerelle directement. Cela confirme que l’URL et l’identifiant fonctionnent avant d’ouvrir Claude Code, de sorte qu’une défaillance pointe vers la passerelle plutôt que votre configuration. Les commandes ci-dessous lisent les variables shell, elles ont donc besoin des exports shell même si vous mettez aussi les valeurs dans un fichier de paramètres.

Bash ou Zsh
PowerShell

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Si votre passerelle s’attend à des clés dans l’en-tête x-api-key, remplacez l’en-tête Authorization par x-api-key: $ANTHROPIC_API_KEY dans la commande Bash, ou l’entrée de table de hachage "Authorization" par "x-api-key" = "$env:ANTHROPIC_API_KEY" dans la commande PowerShell. Une réponse JSON qui commence par {"id":"msg_ et inclut un champ "content":[...] signifie que la passerelle est accessible et l’identifiant fonctionne. Une erreur nommant un modèle inconnu prouve toujours que l’URL et l’identifiant fonctionnent, puisque la passerelle a authentifié la demande avant de rejeter le nom du modèle ; vous n’avez pas besoin de trouver un modèle que votre passerelle sert pour ce test. Un 401 signifie que l’identifiant a été rejeté : si vous avez deviné la variable, basculez vers l’autre et réexportez.

Confirmer dans Claude Code

Démarrez claude à partir du même shell pour qu’il hérite des exports, envoyez un message, et exécutez /status. Sur l’onglet Status, la ligne Anthropic base URL devrait afficher votre adresse de passerelle, ce qui confirme que les demandes y sont routées ; si la ligne n’est pas là, la variable n’a pas atteint la session. Une ligne Auth token ou API key nommant la variable que vous avez définie confirme que l’identifiant de passerelle est actif plutôt qu’une connexion claude.ai sauvegardée. Si le message échoue, ou /status n’affiche pas l’URL de la passerelle, voir le tableau de dépannage ci-dessous.

Comment la variable d’identifiant mappe à un en-tête

Chaque variable envoie l’identifiant dans un en-tête HTTP différent : ANTHROPIC_AUTH_TOKEN dans Authorization: Bearer, ANTHROPIC_API_KEY dans x-api-key, et apiKeyHelper dans les deux. Un identifiant dans la mauvaise variable atteint la passerelle dans un en-tête qu’elle ne lit pas, et la demande échoue avec 401. Si la demande de vérification a retourné 401, basculez vers l’autre variable et réessayez. Une variable d’identifiant de passerelle prend précédence sur une connexion claude.ai sauvegardée ou une clé Console. Votre connexion claude.ai reste sauvegardée et inutilisée tandis que la variable est définie ; désactivez la variable et Claude Code revient à elle. Avec ANTHROPIC_AUTH_TOKEN, la variable prend précédence immédiatement. Avec ANTHROPIC_API_KEY, vous êtes invité une fois en mode interactif à approuver la clé avant qu’elle ne prenne le contrôle. Exécutez /status pour confirmer quelle source d’identifiant est active. Si le démarrage affiche un avertissement de conflit d’authentification nommant deux sources, voir la première ligne du tableau de dépannage pour savoir laquelle supprimer. Pour effacer une connexion sauvegardée afin que seul l’identifiant de passerelle reste, exécutez /logout.

Configurer chaque surface

La CLI lit les variables d’environnement et les fichiers de paramètres ci-dessus. Les autres surfaces sont l’extension VS Code, l’application de bureau, GitHub Actions, l’Agent SDK, et les surfaces cloud comme Slack et le web ; les sections ci-dessous couvrent si ces paramètres atteignent chacun.

Extension VS Code

Définissez les variables de passerelle pour l’extension VS Code dans claudeCode.environmentVariables, dans les propres paramètres utilisateur de VS Code ouverts avec la commande Preferences: Open User Settings (JSON). L’extension vérifie les identifiants de ce paramètre avant de lancer, c’est donc l’endroit fiable pour l’identifiant de passerelle ; les valeurs dans ~/.claude/settings.json atteignent le processus généré mais pas la vérification de connexion propre de l’extension.

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-gateway-key" }
  ]
}

Application de bureau

L’application de bureau lit le routage de passerelle à partir d’une configuration distribuée par l’administrateur, pas à partir de ANTHROPIC_BASE_URL ou settings.json. Si votre organisation l’a distribuée, l’application de bureau route via la passerelle sans configuration de votre côté ; sinon, utilisez la CLI de terminal ou l’extension VS Code pour les sessions de passerelle. Les administrateurs distribuent la configuration comme décrit dans le déploiement organisationnel. Si l’application de bureau affiche Gateway was unreachable, l’application n’a pas pu atteindre l’URL de base configurée au démarrage ; vérifiez l’URL et le chemin réseau avec le test curl ci-dessus.

GitHub Actions

Claude Code GitHub Actions lit ANTHROPIC_BASE_URL et ANTHROPIC_CUSTOM_HEADERS à partir du bloc env du workflow. Passez l’identifiant comme entrée anthropic_api_key de l’action ; l’action le définit comme ANTHROPIC_API_KEY, de sorte qu’il atteint la passerelle dans l’en-tête x-api-key. Pour une passerelle x-api-key, définissez l’URL de base dans env et passez la clé de passerelle comme entrée :

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

Pour une passerelle bearer-token, passez le même secret comme entrée anthropic_api_key et ANTHROPIC_AUTH_TOKEN dans le bloc env du workflow. L’action nécessite anthropic_api_key, CLAUDE_CODE_OAUTH_TOKEN, ou la fédération d’identité de charge de travail avant de lancer Claude Code, et elle ne lit pas ANTHROPIC_AUTH_TOKEN, de sorte que l’entrée satisfait cette vérification de lancement tandis que la variable d’environnement met la clé dans l’en-tête Authorization que la passerelle lit. La copie dans x-api-key est ignorée :

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com
  ANTHROPIC_AUTH_TOKEN: ${{ secrets.GATEWAY_API_KEY }}

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

Pour les autres options d’authentification de l’action, y compris CLAUDE_CODE_OAUTH_TOKEN et la fédération d’identité de charge de travail, voir Claude Code GitHub Actions et le README de l’action.

Agent SDK

L’Agent SDK n’a pas d’options spécifiques à la passerelle ; il transmet les variables d’environnement au processus Claude Code qu’il génère. Chaque SDK accepte une option env qui définit l’environnement du processus généré, et les SDK TypeScript et Python le traitent différemment :

TypeScript : le processus généré hérite de l’environnement parent par défaut, mais la définition de options.env remplace entièrement l’environnement. Propagez process.env dedans pour conserver vos variables de passerelle.
Python : ClaudeAgentOptions(env=...) fusionne au-dessus de l’environnement hérité, de sorte que les variables de passerelle définies dans le processus parent se transmettent sans propagation.

const result = query({
  prompt: "...",
  options: {
    env: {
      ...process.env,
      ANTHROPIC_BASE_URL: "https://llm-gateway.example.com",
      ANTHROPIC_AUTH_TOKEN: process.env.GATEWAY_KEY,
    },
  },
})

Slack, web et Remote Control

Claude Code dans Slack et Claude Code sur le web sont des produits hébergés par Anthropic qui utilisent toujours l’API d’Anthropic ; ils ne font pas partie d’un déploiement de passerelle. Les variables de passerelle définies dans la configuration d’environnement d’une session cloud ne sont pas appliquées. Si votre trafic doit rester sur la passerelle, n’activez pas ces surfaces pour ces utilisateurs. Remote Control et la dictée vocale dépendent tous deux d’une identité claude.ai : Remote Control pour appairer une session en direct avec votre compte, et la dictée vocale pour atteindre le point de terminaison de transcription claude.ai. Ils ne sont pas disponibles tandis que ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ou un apiKeyHelper est actif. Pour utiliser l’un ou l’autre, désactivez l’identifiant de passerelle et connectez-vous avec claude.ai à la place ; /doctor nomme la variable à désactiver.

Configuration supplémentaire

Ces paramètres couvrent les cas au-delà de l’URL de base et de l’identifiant. Définissez-les uniquement si les instructions de votre administrateur ou le tableau de dépannage en appellent un.

Envoyer des en-têtes supplémentaires

Certaines passerelles routent ou balisent les demandes en utilisant un en-tête personnalisé en plus de l’identifiant, par exemple un identifiant de locataire ou une clé de routage. Pour en envoyer un, définissez ANTHROPIC_CUSTOM_HEADERS avec une paire Name: Value par ligne. L’exemple ci-dessous ajoute un en-tête de routage nommé X-Org-Route :

Bash ou Zsh
PowerShell

export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"

$env:ANTHROPIC_CUSTOM_HEADERS = "X-Org-Route: prod"

Vous pouvez aussi définir ANTHROPIC_CUSTOM_HEADERS dans le bloc env d’un fichier de paramètres. Utilisez \n entre les paires là, puisque les chaînes JSON ne peuvent pas s’étendre sur plusieurs lignes :

{
  "env": {
    "ANTHROPIC_CUSTOM_HEADERS": "X-Org-Route: prod\nX-Tenant: acme"
  }
}

Ajouter des modèles de passerelle au sélecteur de modèle

La découverte de modèle interroge la passerelle pour sa liste de modèles au démarrage et ajoute ces noms au sélecteur /model à côté des entrées intégrées. Activez-la si votre passerelle sert des noms de modèle qui ne sont pas dans la liste intégrée de Claude Code et que vous voulez les sélectionner à partir du sélecteur. Si les modèles intégrés sont ce que vous utilisez, vous n’avez pas besoin de découverte ; votre administrateur peut aussi l’avoir déjà activée via les paramètres gérés. Pour l’activer, définissez CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 dans votre shell ou dans le bloc env de ~/.claude/settings.json. La découverte nécessite Claude Code v2.1.129 ou ultérieur. Les modèles découverts apparaissent comme des entrées /model supplémentaires étiquetées From gateway. Pour confirmer que la découverte a fonctionné, démarrez claude --debug et cherchez les lignes [gatewayDiscovery] : un succès enregistre combien de modèles ont été mis en cache, et un 404, un délai d’attente, ou une redirection y est aussi enregistré. Pour quand la découverte s’exécute, ce qu’elle filtre, et le format de réponse que les passerelles servent, voir la référence de découverte de modèle.

Faire tourner les identifiants avec apiKeyHelper

Un apiKeyHelper est une commande que Claude Code exécute pour récupérer votre identifiant de passerelle, au lieu de le lire à partir d’une variable d’environnement statique. Utilisez un assistant quand l’identifiant expire selon un calendrier, provient d’une commande de coffre-fort ou SSO, ou votre administrateur vous a dit de configurer un. Si votre identifiant est une chaîne fixe que vous définissez une fois, la variable d’identifiant est tout ce dont vous avez besoin et vous pouvez ignorer cette section. L’assistant est n’importe quelle commande shell qui imprime l’identifiant actuel sur stdout. Claude Code l’exécute via votre shell système, donc sur Windows il peut être un exécutable ou une invocation PowerShell. Écrivez le script, rendez-le exécutable, et référencez-le à partir de apiKeyHelper dans votre fichier de paramètres :

Bash ou Zsh
PowerShell

Par exemple, un script qui lit à partir d’un coffre-fort :

#!/bin/bash
vault kv get -field=api_key secret/llm-gateway/claude-code

Référencez son chemin dans ~/.claude/settings.json :

{
  "apiKeyHelper": "~/bin/get-gateway-key.sh"
}

Par exemple, un script qui lit à partir d’un coffre-fort :

vault kv get -field=api_key secret/llm-gateway/claude-code

Référencez l’invocation PowerShell dans %USERPROFILE%\.claude\settings.json, en échappant les barres obliques inverses dans la chaîne JSON :

{
  "apiKeyHelper": "powershell -NoProfile -File C:\\scripts\\get-gateway-key.ps1"
}

Claude Code met en cache la sortie de l’assistant pendant cinq minutes par défaut et la réexécute quand une demande retourne HTTP 401. Pour changer la durée de vie du cache, définissez CLAUDE_CODE_API_KEY_HELPER_TTL_MS en millisecondes, par exemple CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000 pour 15 minutes. La valeur de l’assistant est envoyée dans les en-têtes Authorization et x-api-key, de sorte qu’elle fonctionne quel que soit l’en-tête que votre passerelle lit.

Router vers un fournisseur cloud via une passerelle

Ces configurations pointent Claude Code vers une passerelle via une variable d’URL de base spécifique au fournisseur à la place de ANTHROPIC_BASE_URL. Les passerelles Bedrock et Vertex acceptent les formats de demande natifs de ces fournisseurs ; les passerelles Foundry et Claude Platform sur AWS acceptent le format Anthropic Messages et diffèrent uniquement par la variable d’URL de base qui les atteint. Utilisez-en une uniquement si votre équipe de passerelle a spécifiquement nommé Bedrock, Vertex, Foundry, ou Claude Platform sur AWS. Si la demande de vérification ci-dessus a retourné JSON, vous pouvez ignorer cette section. Définissez le bloc pour le fournisseur que votre équipe de passerelle a nommé. Les variables skip-auth disent à Claude Code de ne pas signer les demandes avec les identifiants du fournisseur, puisque la passerelle les détient. Si la passerelle a besoin de son propre jeton, ajoutez ANTHROPIC_AUTH_TOKEN après le bloc, sauf pour Foundry, qui utilise ANTHROPIC_FOUNDRY_API_KEY comme montré.

Amazon Bedrock

Bash ou Zsh
PowerShell

export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export CLAUDE_CODE_USE_BEDROCK=1

$env:ANTHROPIC_BEDROCK_BASE_URL = "https://llm-gateway.example.com/bedrock"
$env:CLAUDE_CODE_SKIP_BEDROCK_AUTH = "1"
$env:CLAUDE_CODE_USE_BEDROCK = "1"

Google Vertex AI

Bash ou Zsh
PowerShell

export ANTHROPIC_VERTEX_BASE_URL=https://llm-gateway.example.com/vertex
export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5

$env:ANTHROPIC_VERTEX_BASE_URL = "https://llm-gateway.example.com/vertex"
$env:ANTHROPIC_VERTEX_PROJECT_ID = "your-gcp-project-id"
$env:CLAUDE_CODE_SKIP_VERTEX_AUTH = "1"
$env:CLAUDE_CODE_USE_VERTEX = "1"
$env:CLOUD_ML_REGION = "us-east5"

Microsoft Foundry

Mettez l’identifiant de la passerelle dans ANTHROPIC_FOUNDRY_API_KEY ; il est envoyé à la passerelle comme en-tête x-api-key. CLAUDE_CODE_SKIP_FOUNDRY_AUTH ne s’applique pas ici : sans clé API, le client Foundry échoue chaque demande avant qu’elle ne quitte la machine.

Bash ou Zsh
PowerShell

export ANTHROPIC_FOUNDRY_BASE_URL=https://llm-gateway.example.com/foundry
export ANTHROPIC_FOUNDRY_API_KEY=sk-gateway-key
export CLAUDE_CODE_USE_FOUNDRY=1

$env:ANTHROPIC_FOUNDRY_BASE_URL = "https://llm-gateway.example.com/foundry"
$env:ANTHROPIC_FOUNDRY_API_KEY = "sk-gateway-key"
$env:CLAUDE_CODE_USE_FOUNDRY = "1"

Claude Platform sur AWS

Voir Claude Platform sur AWS pour l’ID d’espace de travail.

Bash ou Zsh
PowerShell

export ANTHROPIC_AWS_BASE_URL=https://llm-gateway.example.com/anthropic-aws
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
export CLAUDE_CODE_USE_ANTHROPIC_AWS=1

$env:ANTHROPIC_AWS_BASE_URL = "https://llm-gateway.example.com/anthropic-aws"
$env:ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN"
$env:CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH = "1"
$env:CLAUDE_CODE_USE_ANTHROPIC_AWS = "1"

Dépanner les erreurs de passerelle

Ce sont les erreurs les plus courantes lors de l’exécution de Claude Code via une passerelle, avec la cause côté passerelle et la correction :

Erreur	Cause	Correction
Un avertissement de démarrage nommant deux sources d’identifiant et se terminant par `auth may not work as expected`. Les versions plus anciennes affichent `Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set` à la place.	Un identifiant de passerelle et une connexion sauvegardée sont tous deux actifs ; la variable est utilisée pour les demandes, mais la connexion obsolète peut causer un comportement d’authentification inattendu	Désactivez la variable pour utiliser la connexion sauvegardée, ou exécutez `/logout` pour utiliser l’identifiant de passerelle
Erreurs `401` nommant un jeton invalide ou non reconnu	L’identifiant n’en est pas un que la passerelle a émis, ou il est dans un en-tête que la passerelle ne lit pas	Confirmez que la variable correspond à votre type d’identifiant dans le tableau d’identifiant, et régénérez la clé à la passerelle si elle a été révoquée
`Unable to connect to API (ConnectionRefused)`, ou `(ECONNREFUSED)` à partir des installations npm, souvent après une pause silencieuse tandis que Claude Code réessaie avec backoff	Rien n’a répondu à l’URL de base : l’adresse est mauvaise, ou un VPN ou un pare-feu bloque le chemin vers la passerelle	Exécutez le test curl ci-dessus, qui échoue immédiatement avec la même cause, et confirmez l’URL et le chemin réseau avec votre équipe de passerelle
`API returned an empty or malformed response (HTTP 200)`	La passerelle ou un proxy intermédiaire a retourné une réponse non-API, souvent une page d’erreur HTML ou de connexion	Testez avec la demande curl ci-dessus ; corrigez la route de passerelle qui retourne du non-JSON
Erreurs `400` nommant `context_management`, `Extra inputs are not permitted`, ou d’autres champs non reconnus	La passerelle transfère les demandes à un amont qui rejette les champs que Claude Code envoie aux points de terminaison au format Anthropic	Définissez `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`, qui supprime la plupart des champs de pré-version ; voir feature pass-through. Certaines betas ne sont pas fermées par ce drapeau ; pour celles-ci, définissez la variable de fournisseur `CLAUDE_CODE_USE_*` correspondante de sorte que Claude Code envoie uniquement ce que ce fournisseur accepte
Erreurs `400` nommant `thinking` ou `adaptive`, comme `Input tag 'adaptive' found`	La version du modèle en amont n’accepte pas le raisonnement adaptatif, que Claude Code demande pour les modèles Claude 4.6 et ultérieurs	Mettez à niveau l’amont de la passerelle. Sur Opus 4.6 et Sonnet 4.6, `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` fonctionne à la place. Les variables de capacité de configuration de modèle s’appliquent uniquement aux configurations de fournisseur, comme `CLAUDE_CODE_USE_BEDROCK` et `CLAUDE_CODE_USE_VERTEX`, pas derrière une passerelle `ANTHROPIC_BASE_URL`
Erreurs `400` indiquant une limite de contexte ou de jeton dans les propres termes de la passerelle, comme `ContextWindowExceededError` ou `prompt token count of N exceeds the limit of M`	La passerelle applique une fenêtre de contexte plus petite que celle native du modèle et réécrit l’erreur en amont, de sorte que la compaction automatique et la réessai, qui correspondent à la formulation `prompt is too long` d’Anthropic, ne se déclenchent pas	Exécutez `/compact` pour récupérer la session. Pour l’éviter, définissez `CLAUDE_CODE_AUTO_COMPACT_WINDOW` à la limite de la passerelle ; la valeur est limitée à au moins 100 000 jetons et au maximum la fenêtre de contexte du modèle, de sorte qu’une limite de passerelle inférieure à 100 000 ne peut pas être appariée et `/compact` reste la récupération là. Définissez aussi `CLAUDE_CODE_MAX_OUTPUT_TOKENS` en dessous de la limite de sortie du modèle de passerelle
Modèles manquants du sélecteur `/model`	Les noms de modèle de passerelle ne sont pas dans la liste intégrée de Claude Code	Activez la découverte de modèle de passerelle ou ajoutez des noms avec les variables de configuration de modèle
Claude Code vous demande de vous connecter même si le test curl réussit	La CLI n’a pas d’identifiant propre : une URL de base accessible n’en est pas une, et un bloc `env` dans le `.claude/settings.json` ou `.claude/settings.local.json` d’un projet s’applique uniquement après l’assistant de première exécution et l’invite de confiance	Définissez `ANTHROPIC_AUTH_TOKEN` quelque part que Claude Code lit avant la configuration de première exécution : un export shell, le bloc `env` dans `~/.claude/settings.json`, ou les paramètres gérés
`ANTHROPIC_API_KEY` est défini mais ignoré, sans invite	La clé a besoin d’une approbation unique dans les sessions interactives, et une clé précédemment refusée est ignorée sans demander à nouveau	Activez-la sous `/config` avec l’option `Use custom API key`
`This machine's managed settings require a first-party login`	Les paramètres gérés incluent `forceLoginMethod` ou `forceLoginOrgUUID`, qui sur Claude Code v2.1.146 et ultérieur ne peuvent pas coexister avec `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, ou `apiKeyHelper`	Votre administrateur doit supprimer `forceLoginMethod` et `forceLoginOrgUUID` des paramètres gérés pour utiliser les identifiants de passerelle, ou supprimer l’identifiant de passerelle pour utiliser la connexion de première partie. Les deux ne peuvent pas être combinés
`403` avec un corps HTML comme `403 Forbidden`, quand les propres journaux de la passerelle ne montrent aucune demande reçue	Un pare-feu d’application web ou un proxy inverse devant la passerelle a bloqué le corps de la demande avant qu’il n’atteigne la passerelle. Les messages Claude Code incluent des balises de style XML et du code source qui correspondent aux règles de corps de cross-site-scripting, de sorte qu’un test curl court réussit tandis qu’une session réelle ne le fait pas	Exemptez le chemin `/v1/messages` de la passerelle de l’inspection du corps de la demande. Sur AWS WAF, c’est la règle gérée `CrossSiteScripting_Body` ; sur nginx avec ModSecurity, ce sont les règles de corps OWASP CRS équivalentes
Erreurs de certificat ou TLS comme `SSL certificate verification failed` ou `Self-signed certificate detected`, quand le test curl réussit	L’exécution de Claude Code ne fait pas confiance à la même autorité de certification que `curl` utilise. Courant derrière les proxies d’inspection TLS d’entreprise	Définissez `NODE_EXTRA_CA_CERTS` au chemin du bundle CA ; voir CA certificate store

Si Claude Code vous demande de vous connecter à plusieurs reprises après la suppression de la configuration de passerelle, la cause est généralement le stockage d’identifiants plutôt que la passerelle ; voir erreurs d’authentification.

Aperçu des passerelles LLM : ce qu’est une passerelle et comment elle interagit avec les abonnements claude.ai
Déployer une passerelle LLM pour votre organisation : la liste de contrôle orientée administrateur pour déployer et distribuer la configuration de passerelle
Référence du protocole de passerelle : ce que Claude Code envoie à une passerelle, y compris les en-têtes et les champs que la passerelle doit transférer
Paramètres : où vivent les fichiers de paramètres et comment le bloc env est lu
Authentification : comment les variables d’identifiant, apiKeyHelper, et la connexion OAuth interagissent

​Vérifier une configuration existante

​Configurer Claude Code vous-même

​Définir la variable d’identifiant

​Définir l’URL de base et l’identifiant

​Définir comme variables d’environnement shell

​Définir dans un fichier de paramètres

​Vérifier la connexion

​Confirmer dans Claude Code

​Comment la variable d’identifiant mappe à un en-tête

​Conflits avec une connexion existante

​Configurer chaque surface

​Extension VS Code

​Application de bureau

​GitHub Actions

​Agent SDK

​Slack, web et Remote Control

​Configuration supplémentaire

​Envoyer des en-têtes supplémentaires

​Ajouter des modèles de passerelle au sélecteur de modèle

​Faire tourner les identifiants avec apiKeyHelper

​Router vers un fournisseur cloud via une passerelle

​Amazon Bedrock

​Google Vertex AI

​Microsoft Foundry

​Claude Platform sur AWS

​Dépanner les erreurs de passerelle

​Ressources connexes

Vérifier une configuration existante

Configurer Claude Code vous-même

Définir la variable d’identifiant

Définir l’URL de base et l’identifiant

Définir comme variables d’environnement shell

Définir dans un fichier de paramètres

Vérifier la connexion

Confirmer dans Claude Code

Comment la variable d’identifiant mappe à un en-tête

Conflits avec une connexion existante

Configurer chaque surface

Extension VS Code

Application de bureau

GitHub Actions

Agent SDK

Slack, web et Remote Control

Configuration supplémentaire

Envoyer des en-têtes supplémentaires

Ajouter des modèles de passerelle au sélecteur de modèle

Faire tourner les identifiants avec apiKeyHelper

Router vers un fournisseur cloud via une passerelle

Amazon Bedrock

Google Vertex AI

Microsoft Foundry

Claude Platform sur AWS

Dépanner les erreurs de passerelle

Ressources connexes