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# Connetti Claude Code a un gateway LLM
6
7> Indirizza Claude Code al gateway LLM della tua organizzazione. Verifica se il tuo amministratore lo ha già configurato, oppure imposta l'URL di base e le credenziali da solo per CLI, VS Code, GitHub Actions e Agent SDK, quindi verifica la connessione e risolvi gli errori del gateway.
8
9Un [gateway LLM](/it/llm-gateway) è un proxy che la tua organizzazione esegue tra Claude Code e il provider del modello. Quando la tua organizzazione ne utilizza uno, Claude Code si autentica al gateway con una credenziale che la tua organizzazione emette invece del tuo accesso personale a claude.ai.
10
11Questa pagina è per gli sviluppatori che eseguono Claude Code attraverso un gateway gestito dalla loro organizzazione. Copre due percorsi: [verificare se l'amministratore lo ha già configurato per te](#check-for-an-existing-configuration) e [configurarlo da solo](#configure-claude-code-yourself) quando non lo ha fatto.
12
13<Note>
14 * Per distribuire un gateway per la tua organizzazione, vedi [Distribuisci un gateway LLM](/it/llm-gateway-rollout)
15 * Per sapere cosa Claude Code invia a un gateway, vedi il [riferimento del protocollo gateway](/it/llm-gateway-protocol)
16</Note>
17
18<h2 id="check-for-an-existing-configuration">
19 Verifica di una configurazione esistente
20</h2>
21
22Gli amministratori possono distribuire l'indirizzo del gateway e la credenziale attraverso [impostazioni gestite](/it/settings#settings-files), gestione dei dispositivi, o un [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper), in modo che Claude Code le raccolga all'avvio senza che tu debba impostare nulla. Per verificare se la tua organizzazione lo ha già fatto:
23
24<Steps>
25 <Step title="Avvia Claude Code">
26 Esegui `claude`. Se si apre alla schermata di accesso invece di una sessione, nessuna credenziale del gateway è stata distribuita; [configurala da solo](#configure-claude-code-yourself) di seguito.
27 </Step>
28
29 <Step title="Controlla la scheda Status">
30 Se Claude Code ha avviato una sessione senza mostrare la schermata di accesso, esegui `/status`, apri la scheda **Status** e controlla due righe:
31
32 * `Anthropic base URL`: questa riga appare solo quando è impostato un indirizzo del gateway. Se non è presente, Claude Code non è indirizzato al gateway; [configuralo da solo](#configure-claude-code-yourself) di seguito.
33 * `Auth token` o `API key`: una riga che nomina `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, o un `apiKeyHelper` conferma che una credenziale del gateway è attiva. Una riga `Login method` che nomina un account claude.ai significa che la credenziale non è stata distribuita; [impostala da solo](#set-the-credential-variable).
34 </Step>
35
36 <Step title="Invia un messaggio di prova">
37 Chiudi il menu `/status` e invia qualsiasi prompt in Claude Code. Una risposta normale da Claude, senza errori, conferma che la connessione al gateway funziona.
38 </Step>
39</Steps>
40
41Se entrambe le righe nel menu `/status` sembrano corrette ma il messaggio a Claude fallisce, vedi la [tabella di risoluzione dei problemi](#troubleshoot-gateway-errors).
42
43<h2 id="configure-claude-code-yourself">
44 Configura Claude Code da solo
45</h2>
46
47Per configurare Claude Code per il gateway da solo, hai bisogno dal tuo team del gateway:
48
49* L'URL di base del gateway
50* Una credenziale: una stringa di chiave o token, o un comando che ne recupera una
51 * Se il tuo team del gateway non ha detto quale tipo di credenziale è, la sezione [variabile di credenziale](#set-the-credential-variable) di seguito copre cosa provare
52
53Le sezioni di seguito coprono la configurazione in ordine:
54
55* [Imposta la variabile di credenziale](#set-the-credential-variable) e [imposta l'URL di base](#set-the-base-url-and-credential): le due variabili di cui ogni connessione gateway ha bisogno
56* [Verifica la connessione](#verify-the-connection): conferma che funziona prima di persistere qualsiasi cosa
57* [Configura ogni superficie](#configure-each-surface): se stai utilizzando una superficie diversa dalla CLI di Claude Code, come VS Code, vedi come configurarla con le tue credenziali del gateway
58* [Configurazione aggiuntiva](#additional-configuration): variabili che alcuni gateway necessitano oltre all'URL di base e alla credenziale, come un'intestazione personalizzata, un helper di credenziale, scoperta di modelli, o un URL di base in formato provider. Imposta questi solo se il tuo amministratore li ha nominati
59
60<h3 id="set-the-credential-variable">
61 Imposta la variabile di credenziale
62</h3>
63
64Per autenticare Claude Code al gateway, imposta la tua credenziale in una variabile di ambiente. Quale variabile dipende da cosa il tuo team del gateway ti ha detto:
65
66| Imposta la credenziale in | Usa quando |
67| :------------------------------------------------------ | :----------------------------------------------------------------------- |
68| `ANTHROPIC_AUTH_TOKEN` | Il tuo team del gateway ha detto "bearer token" o "Authorization header" |
69| `ANTHROPIC_API_KEY` | Il tuo team del gateway ha detto "API key" o "x-api-key" |
70| [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper) | La credenziale ruota o proviene da un vault |
71
72Se non ti è stato detto quale tipo, usa `ANTHROPIC_AUTH_TOKEN`; la [richiesta di verifica](#verify-the-connection) di seguito mostra come dire se hai bisogno di cambiare.
73
74<h3 id="set-the-base-url-and-credential">
75 Imposta l'URL di base e la credenziale
76</h3>
77
78Imposta l'URL di base del gateway e la variabile di credenziale che hai scelto sopra come variabili di ambiente. Gli esempi usano `ANTHROPIC_AUTH_TOKEN`; sostituiscilo con `ANTHROPIC_API_KEY` se quella è [la variabile che hai scelto](#set-the-credential-variable). Puoi impostarli [nella tua shell](#set-as-shell-environment-variables), che dura per una sessione di terminale, o [in un file di impostazioni di Claude Code](#set-in-a-settings-file), che persiste ovunque Claude Code viene eseguito.
79
80Per la tua prima connessione, inizia con esportazioni di shell ed esegui la [richiesta di verifica](#verify-the-connection) prima di spostare i valori in un file di impostazioni.
81
82<h4 id="set-as-shell-environment-variables">
83 Imposta come variabili di ambiente della shell
84</h4>
85
86Sostituisci i valori con quelli che il tuo team del gateway ti ha dato:
87
88<Tabs>
89 <Tab title="Bash o 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
104Le esportazioni di shell si applicano solo a quella sessione di terminale e ai programmi avviati da essa; un editor lanciato dal dock o dal menu Start non le vedrà. Per farle persistere tra i nuovi terminali, aggiungi le stesse righe al tuo profilo di shell, come `~/.zshrc`, `~/.bashrc`, o il tuo `$PROFILE` di PowerShell, o usa un file di impostazioni invece.
105
106<h4 id="set-in-a-settings-file">
107 Imposta in un file di impostazioni
108</h4>
109
110Per fare in modo che la configurazione si applichi ovunque Claude Code viene eseguito senza dipendere dalla tua shell, imposta le variabili nel blocco `env` di un [file di impostazioni](/it/settings). I file di impostazioni hanno ambiti diversi:
111
112* `~/.claude/settings.json` si applica a tutti i tuoi progetti. Su Windows il percorso è `%USERPROFILE%\.claude\settings.json`
113* `.claude/settings.local.json` si applica a un progetto. Claude Code lo aggiunge al tuo gitignore quando crea il file; se lo crei tu stesso, aggiungilo al tuo gitignore manualmente prima in modo da non committere accidentalmente la tua credenziale
114
115<Warning>
116 Non mettere la credenziale nel `.claude/settings.json` di un progetto. Quel file è committato e condiviso con tutti coloro che clonano il repository.
117</Warning>
118
119Il blocco `env` ha lo stesso aspetto in entrambi i file:
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
130Quando sia un'esportazione di shell che un blocco `env` di file di impostazioni impostano la stessa variabile, il valore del file di impostazioni si applica. Esegui `/status` per vedere quale URL di base e fonte di credenziale Claude Code sta utilizzando.
131
132<h3 id="verify-the-connection">
133 Verifica la connessione
134</h3>
135
136Con le variabili esportate nella tua shell, invia una richiesta di un token al gateway direttamente. Questo conferma che l'URL e la credenziale funzionano prima di aprire Claude Code, quindi un fallimento punta al gateway piuttosto che alla tua configurazione. I comandi di seguito leggono le variabili di shell, quindi hanno bisogno delle [esportazioni di shell](#set-as-shell-environment-variables) anche se metti anche i valori in un file di impostazioni.
137
138<Tabs>
139 <Tab title="Bash o 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
159Se il tuo gateway si aspetta chiavi nell'intestazione `x-api-key`, sostituisci l'intestazione `Authorization` con `x-api-key: $ANTHROPIC_API_KEY` nel comando Bash, o la voce della tabella hash `"Authorization"` con `"x-api-key" = "$env:ANTHROPIC_API_KEY"` nel comando PowerShell.
160
161Una risposta JSON che inizia con `{"id":"msg_` e include un campo `"content":[...]` significa che il gateway è raggiungibile e la credenziale funziona. Un errore che nomina un modello sconosciuto prova comunque che l'URL e la credenziale funzionano, poiché il gateway ha autenticato la richiesta prima di rifiutare il nome del modello; non hai bisogno di trovare un modello che il tuo gateway serve per questo test. Un `401` significa che la credenziale è stata rifiutata: se hai indovinato la variabile, passa all'altra e ri-esporta.
162
163<h4 id="confirm-in-claude-code">
164 Conferma in Claude Code
165</h4>
166
167Avvia `claude` dalla stessa shell in modo che erediti le esportazioni, invia un messaggio, ed esegui `/status`.
168
169Nella scheda **Status**, la riga `Anthropic base URL` dovrebbe mostrare il tuo indirizzo del gateway, che conferma che le richieste vengono instradate lì; se la riga non è presente, la variabile non ha raggiunto la sessione. Una riga `Auth token` o `API key` che nomina la variabile che hai impostato conferma che la credenziale del gateway è attiva piuttosto che un accesso claude.ai salvato.
170
171Se il messaggio fallisce, o `/status` non mostra l'URL del gateway, vedi la [tabella di risoluzione dei problemi](#troubleshoot-gateway-errors) di seguito.
172
173<h3 id="how-the-credential-variable-maps-to-a-header">
174 Come la variabile di credenziale si mappa a un'intestazione
175</h3>
176
177Ogni variabile invia la credenziale in un'intestazione HTTP diversa: `ANTHROPIC_AUTH_TOKEN` in `Authorization: Bearer`, `ANTHROPIC_API_KEY` in `x-api-key`, e `apiKeyHelper` in entrambe. Una credenziale nella variabile sbagliata raggiunge il gateway in un'intestazione che non legge, e la richiesta fallisce con `401`. Se la richiesta di verifica ha restituito `401`, passa all'altra variabile e riprova.
178
179<h3 id="conflicts-with-an-existing-login">
180 Conflitti con un accesso esistente
181</h3>
182
183Una variabile di credenziale del gateway ha precedenza su un accesso claude.ai salvato o una chiave Console. Il tuo accesso claude.ai rimane salvato e inutilizzato mentre la variabile è impostata; annulla l'impostazione della variabile e Claude Code torna ad esso. Con `ANTHROPIC_AUTH_TOKEN`, la variabile ha precedenza immediatamente. Con `ANTHROPIC_API_KEY`, ti viene chiesto una volta in modalità interattiva di approvare la chiave prima che prenda il controllo.
184
185Esegui `/status` per confermare quale fonte di credenziale è attiva. Se l'avvio mostra un avviso di conflitto di autenticazione che nomina due fonti, vedi la prima riga della [tabella di risoluzione dei problemi](#troubleshoot-gateway-errors) per quale eliminare. Per cancellare un accesso salvato in modo che rimanga solo la credenziale del gateway, esegui `/logout`.
186
187<h2 id="configure-each-surface">
188 Configura ogni superficie
189</h2>
190
191La CLI legge le variabili di ambiente e i file di impostazioni di cui sopra. Le altre superfici sono l'estensione VS Code, l'app desktop, GitHub Actions, Agent SDK, e le superfici cloud come Slack e il web; le sezioni di seguito coprono se quelle impostazioni raggiungono ognuna.
192
193<h3 id="vs-code-extension">
194 Estensione VS Code
195</h3>
196
197Imposta le variabili del gateway per l'[estensione VS Code](/it/vs-code) in `claudeCode.environmentVariables`, nelle impostazioni utente di VS Code stesso aperte con il comando **Preferences: Open User Settings (JSON)**. L'estensione controlla le credenziali da questa impostazione prima di avviarsi, quindi è il posto affidabile per la credenziale del gateway; i valori in `~/.claude/settings.json` raggiungono il processo generato ma non il controllo di accesso dell'estensione stessa.
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 App desktop
210</h3>
211
212L'app desktop legge il routing del gateway da una [configurazione distribuita dall'amministratore](https://claude.com/docs/cowork/3p/gateway), non da `ANTHROPIC_BASE_URL` o `settings.json`. Se la tua organizzazione l'ha distribuita, l'app desktop instrada attraverso il gateway senza alcuna configurazione da parte tua; se no, usa la CLI del terminale o l'estensione VS Code per sessioni del gateway. Gli amministratori distribuiscono la configurazione come descritto nel [rollout dell'organizzazione](/it/llm-gateway-rollout#distribute-through-managed-settings).
213
214Se l'app desktop mostra `Gateway was unreachable`, l'app non ha potuto raggiungere l'URL di base configurato all'avvio; controlla l'URL e il percorso di rete con il [test curl di cui sopra](#verify-the-connection).
215
216<h3 id="github-actions">
217 GitHub Actions
218</h3>
219
220[Claude Code GitHub Actions](/it/github-actions) legge `ANTHROPIC_BASE_URL` e `ANTHROPIC_CUSTOM_HEADERS` dal blocco `env` del workflow. Passa la credenziale come input `anthropic_api_key` dell'azione; l'azione la imposta come `ANTHROPIC_API_KEY`, quindi raggiunge il gateway nell'intestazione `x-api-key`.
221
222Per un gateway `x-api-key`, imposta l'URL di base in `env` e passa la chiave del gateway come input:
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
234Per un gateway bearer-token, passa lo stesso segreto sia come input `anthropic_api_key` che come `ANTHROPIC_AUTH_TOKEN` nel blocco `env` del workflow. L'azione richiede `anthropic_api_key`, `CLAUDE_CODE_OAUTH_TOKEN`, o federazione dell'identità del carico di lavoro prima di avviare Claude Code, e non legge `ANTHROPIC_AUTH_TOKEN`, quindi l'input soddisfa quel controllo di avvio mentre la variabile env mette la chiave nell'intestazione `Authorization` che il gateway legge. La copia in `x-api-key` viene ignorata:
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
247Per le altre opzioni di autenticazione dell'azione, inclusi `CLAUDE_CODE_OAUTH_TOKEN` e federazione dell'identità del carico di lavoro, vedi [Claude Code GitHub Actions](/it/github-actions) e il [README](https://github.com/anthropics/claude-code-action#readme) dell'azione.
248
249<h3 id="agent-sdk">
250 Agent SDK
251</h3>
252
253L'[Agent SDK](/it/agent-sdk/overview) non ha opzioni specifiche del gateway; passa le variabili di ambiente al processo Claude Code che genera. Ogni SDK accetta un'opzione `env` che imposta l'ambiente del processo generato, e gli SDK TypeScript e Python lo trattano diversamente:
254
255* TypeScript: il processo generato eredita l'ambiente padre per impostazione predefinita, ma impostare `options.env` sostituisce completamente l'ambiente. Distribuisci `process.env` in esso per mantenere le tue variabili del gateway.
256* Python: `ClaudeAgentOptions(env=...)` si unisce sopra l'ambiente ereditato, quindi le variabili del gateway impostate nel processo padre si trasportano senza distribuire.
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 e Remote Control
284</h3>
285
286[Claude Code in Slack](/it/slack) e [Claude Code sul web](/it/claude-code-on-the-web) sono prodotti ospitati da Anthropic che usano sempre l'API di Anthropic; non fanno parte di una distribuzione del gateway. Le variabili del gateway impostate nella configurazione dell'ambiente di una sessione cloud non vengono applicate. Se il tuo traffico deve rimanere sul gateway, non abilitare queste superfici per quegli utenti.
287
288[Remote Control](/it/remote-control) e [dettatura vocale](/it/voice-dictation) si basano entrambi su un'identità claude.ai: Remote Control per accoppiare una sessione live con il tuo account, e dettatura vocale per raggiungere l'endpoint di trascrizione claude.ai. Non sono disponibili mentre `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, o un `apiKeyHelper` è attivo. Per usare uno di essi, annulla l'impostazione della credenziale del gateway e accedi con claude.ai invece; `/doctor` nomina la variabile da annullare.
289
290<h2 id="additional-configuration">
291 Configurazione aggiuntiva
292</h2>
293
294Queste impostazioni coprono casi oltre l'URL di base e la credenziale. Impostale solo se le istruzioni del tuo amministratore o la [tabella di risoluzione dei problemi](#troubleshoot-gateway-errors) ne richiedono una.
295
296<h3 id="send-additional-headers">
297 Invia intestazioni aggiuntive
298</h3>
299
300Alcuni gateway instradano o taggiano le richieste usando un'intestazione personalizzata oltre alla credenziale, ad esempio un identificatore di tenant o una chiave di instradamento. Per inviarne una, imposta [`ANTHROPIC_CUSTOM_HEADERS`](/it/env-vars) con una coppia `Name: Value` per riga. L'esempio di seguito aggiunge un'intestazione di instradamento denominata `X-Org-Route`:
301
302<Tabs>
303 <Tab title="Bash o 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
316Puoi anche impostare `ANTHROPIC_CUSTOM_HEADERS` nel blocco `env` di un file di impostazioni. Usa `\n` tra le coppie lì, poiché le stringhe JSON non possono estendersi su più righe:
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 Aggiungi modelli del gateway al selettore di modelli
328</h3>
329
330La scoperta di modelli interroga il gateway per il suo elenco di modelli all'avvio e aggiunge quei nomi al selettore `/model` insieme alle voci integrate.
331
332Abilitala se il tuo gateway serve nomi di modelli che non sono nell'elenco integrato di Claude Code e vuoi selezionarli dal selettore. Se i modelli integrati sono quelli che usi, non hai bisogno della scoperta; il tuo amministratore potrebbe anche averla già abilitata attraverso le impostazioni gestite.
333
334Per abilitarla, imposta `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` nella tua shell o nel blocco `env` di `~/.claude/settings.json`. La scoperta richiede Claude Code v2.1.129 o successivo. {/* min-version: 2.1.129 */}
335
336I modelli scoperti appaiono come voci `/model` aggiuntive etichettate `From gateway`. Per confermare che la scoperta è stata eseguita, avvia `claude --debug` e cerca le righe `[gatewayDiscovery]`: un successo registra quanti modelli sono stati memorizzati nella cache, e un `404`, timeout, o reindirizzamento viene registrato lì anche. Per quando la scoperta viene eseguita, cosa filtra, e il formato di risposta che i gateway servono, vedi il [riferimento della scoperta di modelli](/it/llm-gateway-protocol#model-discovery).
337
338<h3 id="rotate-credentials-with-apikeyhelper">
339 Ruota le credenziali con apiKeyHelper
340</h3>
341
342Un `apiKeyHelper` è un comando che Claude Code esegue per recuperare la tua credenziale del gateway, invece di leggerla da una variabile di ambiente statica.
343
344Usa un helper quando la credenziale scade secondo una pianificazione, proviene da un comando vault o SSO, o il tuo amministratore ti ha detto di configurarne uno. Se la tua credenziale è una stringa fissa che imposti una volta, la [variabile di credenziale](#set-the-credential-variable) è tutto ciò di cui hai bisogno e puoi saltare questa sezione.
345
346L'helper è qualsiasi comando di shell che stampa la credenziale corrente su stdout. Claude Code lo esegue attraverso la tua shell di sistema, quindi su Windows può essere un eseguibile o un'invocazione di PowerShell. Scrivi lo script, rendilo eseguibile, e referenzialo da `apiKeyHelper` nel tuo [file di impostazioni](/it/settings):
347
348<Tabs>
349 <Tab title="Bash o Zsh">
350 Ad esempio, uno script che legge da un vault:
351
352 ```bash theme={null}
353 #!/bin/bash
354 vault kv get -field=api_key secret/llm-gateway/claude-code
355 ```
356
357 Referenzia il suo percorso in `~/.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 Ad esempio, uno script che legge da un vault:
368
369 ```powershell theme={null}
370 vault kv get -field=api_key secret/llm-gateway/claude-code
371 ```
372
373 Referenzia l'invocazione di PowerShell in `%USERPROFILE%\.claude\settings.json`, sfuggendo i backslash nella stringa 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 memorizza nella cache l'output dell'helper per cinque minuti per impostazione predefinita e lo ri-esegue quando una richiesta restituisce HTTP 401. Per cambiare la durata della cache, imposta `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` in millisecondi, ad esempio `CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000` per 15 minuti.
384
385Il valore dell'helper viene inviato sia nell'intestazione `Authorization` che in `x-api-key`, quindi funziona qualunque intestazione il tuo gateway legga.
386
387<h3 id="route-to-a-cloud-provider-through-a-gateway">
388 Instrada a un provider cloud attraverso un gateway
389</h3>
390
391Queste configurazioni indirizzano Claude Code a un gateway attraverso una variabile di URL di base specifica del provider al posto di `ANTHROPIC_BASE_URL`. I gateway Bedrock e Vertex accettano i formati di richiesta nativi di quei provider; i gateway Foundry e Claude Platform su AWS accettano il formato Anthropic Messages e differiscono solo in quale variabile di URL di base li raggiunge.
392
393Usane una solo se il tuo team del gateway ha specificamente nominato Bedrock, Vertex, Foundry, o Claude Platform su AWS. Se la [richiesta di verifica](#verify-the-connection) di cui sopra ha restituito JSON, puoi saltare questa sezione.
394
395Imposta il blocco per il provider che il tuo team del gateway ha nominato. Le variabili skip-auth dicono a Claude Code di non firmare le richieste con le credenziali del provider, poiché il gateway le detiene. Se il gateway ha bisogno del suo proprio token, aggiungi `ANTHROPIC_AUTH_TOKEN` dopo il blocco, tranne per Foundry, che usa `ANTHROPIC_FOUNDRY_API_KEY` come mostrato.
396
397<h4 id="amazon-bedrock">
398 Amazon Bedrock
399</h4>
400
401<Tabs>
402 <Tab title="Bash o 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 o 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
449Metti la credenziale del gateway in `ANTHROPIC_FOUNDRY_API_KEY`; viene inviata al gateway come intestazione `x-api-key`. `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` non si applica qui: senza una chiave API, il client Foundry fallisce ogni richiesta prima che lasci la macchina.
450
451<Tabs>
452 <Tab title="Bash o 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 su AWS
471</h4>
472
473Vedi [Claude Platform su AWS](/it/claude-platform-on-aws) per l'ID dell'area di lavoro.
474
475<Tabs>
476 <Tab title="Bash o 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 Risolvi gli errori del gateway
497</h2>
498
499Questi sono gli errori più comuni quando si esegue Claude Code attraverso un gateway, con la causa dal lato del gateway e la correzione:
500
501| Errore | Causa | Correzione |
502| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
503| Un avviso di avvio che nomina due fonti di credenziale e termina con `auth may not work as expected`. Le versioni più vecchie mostrano `Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set` invece. | Una credenziale del gateway e un accesso salvato sono entrambi attivi; la variabile viene utilizzata per le richieste, ma l'accesso stantio può causare un comportamento di autenticazione inaspettato | Annulla l'impostazione della variabile per usare l'accesso salvato, o esegui `/logout` per usare la credenziale del gateway |
504| Errori `401` che nominano un token non valido o non riconosciuto | La credenziale non è una che il gateway ha emesso, o è in un'intestazione che il gateway non legge | Conferma che la variabile corrisponde al tuo tipo di credenziale nella [tabella di credenziale](#set-the-credential-variable), e rigenera la chiave al gateway se è stata revocata |
505| `Unable to connect to API (ConnectionRefused)`, o `(ECONNREFUSED)` da installazioni npm, spesso dopo una pausa silenziosa mentre Claude Code [riprova con backoff](/it/errors#automatic-retries) | Nulla ha risposto all'URL di base: l'indirizzo è sbagliato, o una VPN o firewall blocca il percorso al gateway | Esegui il [test curl di cui sopra](#verify-the-connection), che fallisce immediatamente con la stessa causa, e conferma l'URL e il percorso di rete con il tuo team del gateway |
506| `API returned an empty or malformed response (HTTP 200)` | Il gateway o un proxy intermedio ha restituito una risposta non-API, spesso una pagina di errore HTML o di accesso | Testa con la [richiesta curl di cui sopra](#verify-the-connection); correggi il percorso del gateway che restituisce non-JSON |
507| Errori `400` che nominano `context_management`, `Extra inputs are not permitted`, o altri campi non riconosciuti | Il gateway invia le richieste a un upstream che rifiuta i campi che Claude Code invia agli endpoint in formato Anthropic | Imposta `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`, che sopprime la maggior parte dei campi pre-release; vedi [feature pass-through](/it/llm-gateway-protocol#feature-pass-through). Alcuni beta non sono controllati da questo flag; per quelli, imposta la variabile provider `CLAUDE_CODE_USE_*` corrispondente in modo che Claude Code invii solo quello che quel provider accetta |
508| Errori `400` che nominano `thinking` o `adaptive`, come `Input tag 'adaptive' found` | La build del modello upstream non accetta il ragionamento adattivo, che Claude Code richiede per i modelli Claude 4.6 e successivi | Aggiorna l'upstream del gateway. Su Opus 4.6 e Sonnet 4.6, `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` funziona invece. Le variabili di capacità della [configurazione del modello](/it/model-config) si applicano solo alle configurazioni del provider, come `CLAUDE_CODE_USE_BEDROCK` e `CLAUDE_CODE_USE_VERTEX`, non dietro un gateway `ANTHROPIC_BASE_URL` |
509| Errori `400` che indicano un contesto o limite di token nelle parole del gateway stesso, come `ContextWindowExceededError` o `prompt token count of N exceeds the limit of M` | Il gateway applica un contesto più piccolo della finestra nativa del modello e riscrive l'errore upstream, quindi il compact-and-retry automatico, che corrisponde alla dicitura `prompt is too long` di Anthropic, non si attiva | Esegui `/compact` per recuperare la sessione. Per prevenirlo, imposta `CLAUDE_CODE_AUTO_COMPACT_WINDOW` al limite del gateway; il valore è bloccato ad almeno 100.000 token e al massimo la finestra di contesto del modello, quindi un limite del gateway inferiore a 100.000 non può essere abbinato e `/compact` rimane il recupero lì. Imposta anche `CLAUDE_CODE_MAX_OUTPUT_TOKENS` sotto il limite di output del modello del gateway |
510| Modelli mancanti dal selettore `/model` | I nomi dei modelli del gateway non sono nell'elenco integrato di Claude Code | Abilita la [scoperta di modelli del gateway](#add-gateway-models-to-the-model-picker) o aggiungi nomi con le variabili della [configurazione del modello](/it/model-config) |
511| Claude Code ti chiede di accedere anche se il [test curl](#verify-the-connection) ha successo | La CLI non ha una credenziale propria: un URL di base raggiungibile non è uno, e un blocco `env` nel `.claude/settings.json` o `.claude/settings.local.json` di un progetto si applica solo dopo la procedura guidata di primo avvio e il prompt di fiducia | Imposta `ANTHROPIC_AUTH_TOKEN` da qualche parte Claude Code legge prima della configurazione di primo avvio: un'esportazione di shell, il blocco `env` in `~/.claude/settings.json`, o impostazioni gestite |
512| `ANTHROPIC_API_KEY` è impostato ma ignorato, senza prompt | La chiave ha bisogno di un'approvazione una tantum nelle sessioni interattive, e una chiave precedentemente rifiutata viene ignorata senza chiedere di nuovo | Abilitala sotto `/config` con l'opzione `Use custom API key` |
513| `This machine's managed settings require a first-party login` | Le impostazioni gestite includono `forceLoginMethod` o `forceLoginOrgUUID`, che su Claude Code v2.1.146 e successivo non possono coesistere con `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, o `apiKeyHelper` | Il tuo amministratore deve rimuovere `forceLoginMethod` e `forceLoginOrgUUID` dalle impostazioni gestite per usare le credenziali del gateway, o rimuovere la credenziale del gateway per usare l'accesso di prima parte. I due non possono essere combinati |
514| `403` con un corpo HTML come `403 Forbidden`, quando i log del gateway stesso non mostrano alcuna richiesta ricevuta | Un web application firewall o reverse proxy davanti al gateway ha bloccato il corpo della richiesta prima che raggiungesse il gateway. I prompt di Claude Code includono tag di stile XML e codice sorgente che corrispondono alle regole del corpo dello scripting tra siti, quindi un breve test curl passa mentre una sessione reale no | Esenta il percorso `/v1/messages` del gateway dall'ispezione del corpo della richiesta. Su AWS WAF questa è la regola gestita `CrossSiteScripting_Body`; su nginx con ModSecurity è la regola del corpo OWASP CRS equivalente |
515| Errori di certificato o TLS come `SSL certificate verification failed` o `Self-signed certificate detected`, quando il [test curl](#verify-the-connection) ha successo | Il runtime di Claude Code non sta fidando della stessa autorità di certificazione che `curl` usa. Comune dietro proxy di ispezione TLS aziendale | Imposta `NODE_EXTRA_CA_CERTS` al percorso del bundle CA; vedi [archivio di certificati CA](/it/network-config#ca-certificate-store) |
516
517Se Claude Code ti chiede di accedere ripetutamente dopo aver rimosso la configurazione del gateway, la causa è solitamente l'archiviazione delle credenziali piuttosto che il gateway; vedi [errori di autenticazione](/it/errors#authentication-errors).
518
519<h2 id="related-resources">
520 Risorse correlate
521</h2>
522
523* [Panoramica dei gateway LLM](/it/llm-gateway): cos'è un gateway e come interagisce con gli abbonamenti a claude.ai
524* [Distribuisci un gateway LLM per la tua organizzazione](/it/llm-gateway-rollout): la checklist rivolta agli amministratori per distribuire e distribuire la configurazione del gateway
525* [Riferimento del protocollo gateway](/it/llm-gateway-protocol): cosa Claude Code invia a un gateway, incluse le intestazioni e i campi che il gateway deve inoltrar
526* [Impostazioni](/it/settings): dove si trovano i file di impostazioni e come viene letto il blocco `env`
527* [Autenticazione](/it/authentication): come le variabili di credenziale, `apiKeyHelper`, e l'accesso OAuth interagiscono
