1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Connecter Claude Code à une passerelle LLM
6
7> Pointez Claude Code vers la passerelle LLM de votre organisation. Vérifiez si votre administrateur l'a déjà configurée, ou définissez vous-même l'URL de base et les identifiants pour la CLI, VS Code, GitHub Actions et l'Agent SDK, puis vérifiez la connexion et corrigez les erreurs de passerelle.
8
9Une [passerelle LLM](/fr/llm-gateway) 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.
10
11Cette 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](#check-for-an-existing-configuration), et [la configurer vous-même](#configure-claude-code-yourself) s'il ne l'a pas fait.
12
13<Note>
14 * Pour déployer une passerelle pour votre organisation, voir [Déployer une passerelle LLM](/fr/llm-gateway-rollout)
15 * Pour savoir ce que Claude Code envoie à une passerelle, voir la [référence du protocole de passerelle](/fr/llm-gateway-protocol)
16</Note>
17
18<h2 id="check-for-an-existing-configuration">
19 Vérifier une configuration existante
20</h2>
21
22Les administrateurs peuvent distribuer l'adresse de la passerelle et l'identifiant via les [paramètres gérés](/fr/settings#settings-files), la gestion des appareils, ou un [`apiKeyHelper`](#rotate-credentials-with-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 :
23
24<Steps>
25 <Step title="Démarrer Claude Code">
26 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](#configure-claude-code-yourself) ci-dessous.
27 </Step>
28
29 <Step title="Vérifier l'onglet Statut">
30 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 :
31
32 * `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](#configure-claude-code-yourself) ci-dessous.
33 * `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](#set-the-credential-variable).
34 </Step>
35
36 <Step title="Envoyer un message de test">
37 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.
38 </Step>
39</Steps>
40
41Si les deux lignes du menu `/status` semblent correctes mais que le message à Claude échoue, voir le [tableau de dépannage](#troubleshoot-gateway-errors).
42
43<h2 id="configure-claude-code-yourself">
44 Configurer Claude Code vous-même
45</h2>
46
47Pour configurer Claude Code pour la passerelle vous-même, vous avez besoin de votre équipe de passerelle :
48
49* L'URL de base de la passerelle
50* Un identifiant : une chaîne de clé ou de jeton, ou une commande qui en récupère un
51 * Si votre équipe de passerelle n'a pas dit quel type d'identifiant c'est, la section [variable d'identifiant](#set-the-credential-variable) ci-dessous couvre ce qu'il faut essayer
52
53Les sections ci-dessous couvrent la configuration dans l'ordre :
54
55* [Définir la variable d'identifiant](#set-the-credential-variable) et [définir l'URL de base](#set-the-base-url-and-credential) : les deux variables que chaque connexion de passerelle nécessite
56* [Vérifier la connexion](#verify-the-connection) : confirmer qu'elle fonctionne avant de persister quoi que ce soit
57* [Configurer chaque surface](#configure-each-surface) : si vous utilisez une surface autre que la CLI Claude Code, comme VS Code, voir comment la configurer avec vos identifiants de passerelle
58* [Configuration supplémentaire](#additional-configuration) : 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
59
60<h3 id="set-the-credential-variable">
61 Définir la variable d'identifiant
62</h3>
63
64Pour 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 :
65
66| Définir l'identifiant dans | Utiliser quand |
67| :------------------------------------------------------ | :---------------------------------------------------------------------------- |
68| `ANTHROPIC_AUTH_TOKEN` | Votre équipe de passerelle a dit ' bearer token ' ou ' Authorization header ' |
69| `ANTHROPIC_API_KEY` | Votre équipe de passerelle a dit ' API key ' ou ' x-api-key ' |
70| [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper) | L'identifiant tourne ou provient d'un coffre-fort |
71
72Si vous n'avez pas été informé du type, utilisez `ANTHROPIC_AUTH_TOKEN` ; la [demande de vérification](#verify-the-connection) ci-dessous montre comment savoir si vous devez basculer.
73
74<h3 id="set-the-base-url-and-credential">
75 Définir l'URL de base et l'identifiant
76</h3>
77
78Dé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](#set-the-credential-variable). Vous pouvez les définir [dans votre shell](#set-as-shell-environment-variables), ce qui dure une session de terminal, ou [dans un fichier de paramètres Claude Code](#set-in-a-settings-file), ce qui persiste partout où Claude Code s'exécute.
79
80Pour votre première connexion, commencez par les exports shell et exécutez la [demande de vérification](#verify-the-connection) avant de déplacer les valeurs vers un fichier de paramètres.
81
82<h4 id="set-as-shell-environment-variables">
83 Définir comme variables d'environnement shell
84</h4>
85
86Remplacez les valeurs par celles que votre équipe de passerelle vous a données :
87
88<Tabs>
89 <Tab title="Bash ou Zsh">
90 ```bash theme={null}
91 export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
92 export ANTHROPIC_AUTH_TOKEN=sk-gateway-key
93 ```
94 </Tab>
95
96 <Tab title="PowerShell">
97 ```powershell theme={null}
98 $env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
99 $env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"
100 ```
101 </Tab>
102</Tabs>
103
104Les 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.
105
106<h4 id="set-in-a-settings-file">
107 Définir dans un fichier de paramètres
108</h4>
109
110Pour 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](/fr/settings). Les fichiers de paramètres ont des portées différentes :
111
112* `~/.claude/settings.json` s'applique à tous vos projets. Sur Windows, le chemin est `%USERPROFILE%\.claude\settings.json`
113* `.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
114
115<Warning>
116 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.
117</Warning>
118
119Le bloc `env` ressemble au même dans l'un ou l'autre fichier :
120
121```json theme={null}
122{
123 "env": {
124 "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
125 "ANTHROPIC_AUTH_TOKEN": "sk-gateway-key"
126 }
127}
128```
129
130Quand 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.
131
132<h3 id="verify-the-connection">
133 Vérifier la connexion
134</h3>
135
136Avec 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](#set-as-shell-environment-variables) même si vous mettez aussi les valeurs dans un fichier de paramètres.
137
138<Tabs>
139 <Tab title="Bash ou Zsh">
140 ```bash theme={null}
141 curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
142 -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
143 -H "anthropic-version: 2023-06-01" \
144 -H "content-type: application/json" \
145 -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
146 ```
147 </Tab>
148
149 <Tab title="PowerShell">
150 ```powershell theme={null}
151 Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
152 -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
153 -ContentType "application/json" `
154 -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
155 ```
156 </Tab>
157</Tabs>
158
159Si 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.
160
161Une 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.
162
163<h4 id="confirm-in-claude-code">
164 Confirmer dans Claude Code
165</h4>
166
167Démarrez `claude` à partir du même shell pour qu'il hérite des exports, envoyez un message, et exécutez `/status`.
168
169Sur 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.
170
171Si le message échoue, ou `/status` n'affiche pas l'URL de la passerelle, voir le [tableau de dépannage](#troubleshoot-gateway-errors) ci-dessous.
172
173<h3 id="how-the-credential-variable-maps-to-a-header">
174 Comment la variable d'identifiant mappe à un en-tête
175</h3>
176
177Chaque 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.
178
179<h3 id="conflicts-with-an-existing-login">
180 Conflits avec une connexion existante
181</h3>
182
183Une 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.
184
185Exé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](#troubleshoot-gateway-errors) pour savoir laquelle supprimer. Pour effacer une connexion sauvegardée afin que seul l'identifiant de passerelle reste, exécutez `/logout`.
186
187<h2 id="configure-each-surface">
188 Configurer chaque surface
189</h2>
190
191La 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.
192
193<h3 id="vs-code-extension">
194 Extension VS Code
195</h3>
196
197Définissez les variables de passerelle pour l'[extension VS Code](/fr/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.
198
199```json theme={null}
200{
201 "claudeCode.environmentVariables": [
202 { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
203 { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-gateway-key" }
204 ]
205}
206```
207
208<h3 id="desktop-app">
209 Application de bureau
210</h3>
211
212L'application de bureau lit le routage de passerelle à partir d'une [configuration distribuée par l'administrateur](https://claude.com/docs/cowork/3p/gateway), 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](/fr/llm-gateway-rollout#distribute-through-managed-settings).
213
214Si 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](#verify-the-connection).
215
216<h3 id="github-actions">
217 GitHub Actions
218</h3>
219
220[Claude Code GitHub Actions](/fr/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`.
221
222Pour une passerelle `x-api-key`, définissez l'URL de base dans `env` et passez la clé de passerelle comme entrée :
223
224```yaml theme={null}
225env:
226 ANTHROPIC_BASE_URL: https://llm-gateway.example.com
227
228steps:
229 - uses: anthropics/claude-code-action@v1
230 with:
231 anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}
232```
233
234Pour 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 :
235
236```yaml theme={null}
237env:
238 ANTHROPIC_BASE_URL: https://llm-gateway.example.com
239 ANTHROPIC_AUTH_TOKEN: ${{ secrets.GATEWAY_API_KEY }}
240
241steps:
242 - uses: anthropics/claude-code-action@v1
243 with:
244 anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}
245```
246
247Pour 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](/fr/github-actions) et le [README](https://github.com/anthropics/claude-code-action#readme) de l'action.
248
249<h3 id="agent-sdk">
250 Agent SDK
251</h3>
252
253L'[Agent SDK](/fr/agent-sdk/overview) 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 :
254
255* 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.
256* 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.
257
258<CodeGroup>
259 ```ts TypeScript theme={null}
260 const result = query({
261 prompt: "...",
262 options: {
263 env: {
264 ...process.env,
265 ANTHROPIC_BASE_URL: "https://llm-gateway.example.com",
266 ANTHROPIC_AUTH_TOKEN: process.env.GATEWAY_KEY,
267 },
268 },
269 })
270 ```
271
272 ```python Python theme={null}
273 options = ClaudeAgentOptions(
274 env={
275 "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
276 "ANTHROPIC_AUTH_TOKEN": os.environ["GATEWAY_KEY"],
277 }
278 )
279 ```
280</CodeGroup>
281
282<h3 id="slack-web-and-remote-control">
283 Slack, web et Remote Control
284</h3>
285
286[Claude Code dans Slack](/fr/slack) et [Claude Code sur le web](/fr/claude-code-on-the-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.
287
288[Remote Control](/fr/remote-control) et [la dictée vocale](/fr/voice-dictation) 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.
289
290<h2 id="additional-configuration">
291 Configuration supplémentaire
292</h2>
293
294Ces 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](#troubleshoot-gateway-errors) en appellent un.
295
296<h3 id="send-additional-headers">
297 Envoyer des en-têtes supplémentaires
298</h3>
299
300Certaines 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`](/fr/env-vars) avec une paire `Name: Value` par ligne. L'exemple ci-dessous ajoute un en-tête de routage nommé `X-Org-Route` :
301
302<Tabs>
303 <Tab title="Bash ou Zsh">
304 ```bash theme={null}
305 export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"
306 ```
307 </Tab>
308
309 <Tab title="PowerShell">
310 ```powershell theme={null}
311 $env:ANTHROPIC_CUSTOM_HEADERS = "X-Org-Route: prod"
312 ```
313 </Tab>
314</Tabs>
315
316Vous 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 :
317
318```json theme={null}
319{
320 "env": {
321 "ANTHROPIC_CUSTOM_HEADERS": "X-Org-Route: prod\nX-Tenant: acme"
322 }
323}
324```
325
326<h3 id="add-gateway-models-to-the-model-picker">
327 Ajouter des modèles de passerelle au sélecteur de modèle
328</h3>
329
330La 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.
331
332Activez-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.
333
334Pour 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. {/* min-version: 2.1.129 */}
335
336Les 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](/fr/llm-gateway-protocol#model-discovery).
337
338<h3 id="rotate-credentials-with-apikeyhelper">
339 Faire tourner les identifiants avec apiKeyHelper
340</h3>
341
342Un `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.
343
344Utilisez 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](#set-the-credential-variable) est tout ce dont vous avez besoin et vous pouvez ignorer cette section.
345
346L'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](/fr/settings) :
347
348<Tabs>
349 <Tab title="Bash ou Zsh">
350 Par exemple, un script qui lit à partir d'un coffre-fort :
351
352 ```bash theme={null}
353 #!/bin/bash
354 vault kv get -field=api_key secret/llm-gateway/claude-code
355 ```
356
357 Référencez son chemin dans `~/.claude/settings.json` :
358
359 ```json theme={null}
360 {
361 "apiKeyHelper": "~/bin/get-gateway-key.sh"
362 }
363 ```
364 </Tab>
365
366 <Tab title="PowerShell">
367 Par exemple, un script qui lit à partir d'un coffre-fort :
368
369 ```powershell theme={null}
370 vault kv get -field=api_key secret/llm-gateway/claude-code
371 ```
372
373 Référencez l'invocation PowerShell dans `%USERPROFILE%\.claude\settings.json`, en échappant les barres obliques inverses dans la chaîne JSON :
374
375 ```json theme={null}
376 {
377 "apiKeyHelper": "powershell -NoProfile -File C:\\scripts\\get-gateway-key.ps1"
378 }
379 ```
380 </Tab>
381</Tabs>
382
383Claude 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.
384
385La 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.
386
387<h3 id="route-to-a-cloud-provider-through-a-gateway">
388 Router vers un fournisseur cloud via une passerelle
389</h3>
390
391Ces 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.
392
393Utilisez-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](#verify-the-connection) ci-dessus a retourné JSON, vous pouvez ignorer cette section.
394
395Dé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é.
396
397<h4 id="amazon-bedrock">
398 Amazon Bedrock
399</h4>
400
401<Tabs>
402 <Tab title="Bash ou Zsh">
403 ```bash theme={null}
404 export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock
405 export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
406 export CLAUDE_CODE_USE_BEDROCK=1
407 ```
408 </Tab>
409
410 <Tab title="PowerShell">
411 ```powershell theme={null}
412 $env:ANTHROPIC_BEDROCK_BASE_URL = "https://llm-gateway.example.com/bedrock"
413 $env:CLAUDE_CODE_SKIP_BEDROCK_AUTH = "1"
414 $env:CLAUDE_CODE_USE_BEDROCK = "1"
415 ```
416 </Tab>
417</Tabs>
418
419<h4 id="google-vertex-ai">
420 Google Vertex AI
421</h4>
422
423<Tabs>
424 <Tab title="Bash ou Zsh">
425 ```bash theme={null}
426 export ANTHROPIC_VERTEX_BASE_URL=https://llm-gateway.example.com/vertex
427 export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
428 export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
429 export CLAUDE_CODE_USE_VERTEX=1
430 export CLOUD_ML_REGION=us-east5
431 ```
432 </Tab>
433
434 <Tab title="PowerShell">
435 ```powershell theme={null}
436 $env:ANTHROPIC_VERTEX_BASE_URL = "https://llm-gateway.example.com/vertex"
437 $env:ANTHROPIC_VERTEX_PROJECT_ID = "your-gcp-project-id"
438 $env:CLAUDE_CODE_SKIP_VERTEX_AUTH = "1"
439 $env:CLAUDE_CODE_USE_VERTEX = "1"
440 $env:CLOUD_ML_REGION = "us-east5"
441 ```
442 </Tab>
443</Tabs>
444
445<h4 id="microsoft-foundry">
446 Microsoft Foundry
447</h4>
448
449Mettez 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.
450
451<Tabs>
452 <Tab title="Bash ou Zsh">
453 ```bash theme={null}
454 export ANTHROPIC_FOUNDRY_BASE_URL=https://llm-gateway.example.com/foundry
455 export ANTHROPIC_FOUNDRY_API_KEY=sk-gateway-key
456 export CLAUDE_CODE_USE_FOUNDRY=1
457 ```
458 </Tab>
459
460 <Tab title="PowerShell">
461 ```powershell theme={null}
462 $env:ANTHROPIC_FOUNDRY_BASE_URL = "https://llm-gateway.example.com/foundry"
463 $env:ANTHROPIC_FOUNDRY_API_KEY = "sk-gateway-key"
464 $env:CLAUDE_CODE_USE_FOUNDRY = "1"
465 ```
466 </Tab>
467</Tabs>
468
469<h4 id="claude-platform-on-aws">
470 Claude Platform sur AWS
471</h4>
472
473Voir [Claude Platform sur AWS](/fr/claude-platform-on-aws) pour l'ID d'espace de travail.
474
475<Tabs>
476 <Tab title="Bash ou Zsh">
477 ```bash theme={null}
478 export ANTHROPIC_AWS_BASE_URL=https://llm-gateway.example.com/anthropic-aws
479 export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
480 export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
481 export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
482 ```
483 </Tab>
484
485 <Tab title="PowerShell">
486 ```powershell theme={null}
487 $env:ANTHROPIC_AWS_BASE_URL = "https://llm-gateway.example.com/anthropic-aws"
488 $env:ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN"
489 $env:CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH = "1"
490 $env:CLAUDE_CODE_USE_ANTHROPIC_AWS = "1"
491 ```
492 </Tab>
493</Tabs>
494
495<h2 id="troubleshoot-gateway-errors">
496 Dépanner les erreurs de passerelle
497</h2>
498
499Ce 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 :
500
501| Erreur | Cause | Correction |
502| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
503| 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 |
504| 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](#set-the-credential-variable), et régénérez la clé à la passerelle si elle a été révoquée |
505| `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](/fr/errors#automatic-retries) | 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](#verify-the-connection), qui échoue immédiatement avec la même cause, et confirmez l'URL et le chemin réseau avec votre équipe de passerelle |
506| `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](#verify-the-connection) ; corrigez la route de passerelle qui retourne du non-JSON |
507| 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](/fr/llm-gateway-protocol#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 |
508| 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](/fr/model-config) 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` |
509| 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 |
510| 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](#add-gateway-models-to-the-model-picker) ou ajoutez des noms avec les variables de [configuration de modèle](/fr/model-config) |
511| Claude Code vous demande de vous connecter même si le [test curl](#verify-the-connection) 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 |
512| `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` |
513| `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 |
514| `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 |
515| Erreurs de certificat ou TLS comme `SSL certificate verification failed` ou `Self-signed certificate detected`, quand le [test curl](#verify-the-connection) 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](/fr/network-config#ca-certificate-store) |
516
517Si 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](/fr/errors#authentication-errors).
518
519<h2 id="related-resources">
520 Ressources connexes
521</h2>
522
523* [Aperçu des passerelles LLM](/fr/llm-gateway) : ce qu'est une passerelle et comment elle interagit avec les abonnements claude.ai
524* [Déployer une passerelle LLM pour votre organisation](/fr/llm-gateway-rollout) : la liste de contrôle orientée administrateur pour déployer et distribuer la configuration de passerelle
525* [Référence du protocole de passerelle](/fr/llm-gateway-protocol) : ce que Claude Code envoie à une passerelle, y compris les en-têtes et les champs que la passerelle doit transférer
526* [Paramètres](/fr/settings) : où vivent les fichiers de paramètres et comment le bloc `env` est lu
527* [Authentification](/fr/authentication) : comment les variables d'identifiant, `apiKeyHelper`, et la connexion OAuth interagissent
