2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> 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.3> Use this file to discover all available pages before exploring further.
4 4
5# Configurazione del gateway LLM5# Gateway LLM
6 6
7> Scopri come configurare Claude Code per funzionare con soluzioni di gateway LLM. Copre i requisiti del gateway, la configurazione dell'autenticazione, la selezione del modello e la configurazione degli endpoint specifici del provider.7> Instrada Claude Code attraverso un gateway LLM per l'autenticazione centralizzata, il tracciamento dell'utilizzo e i controlli dei costi. Copre il collegamento di Claude Code a un gateway, il rollout per la tua organizzazione, cosa Claude Code invia a un gateway e come i gateway interagiscono con gli abbonamenti a claude.ai.
8 8
9I gateway LLM forniscono un livello proxy centralizzato tra Claude Code e i provider di modelli, spesso fornendo:9Un gateway LLM è un proxy che la tua organizzazione esegue tra Claude Code e un provider di modelli. Claude Code invia il traffico API al gateway, e il gateway lo inoltra al provider utilizzando una credenziale che la tua organizzazione controlla.
10 10
11* **Autenticazione centralizzata** - Punto singolo per la gestione delle chiavi API11Questa pagina copre:
12* **Tracciamento dell'utilizzo** - Monitora l'utilizzo tra team e progetti
13* **Controlli dei costi** - Implementa budget e limiti di velocità
14* **Registrazione di audit** - Traccia tutte le interazioni del modello per la conformità
15* **Instradamento dei modelli** - Passa da un provider all'altro senza modifiche al codice
16 12
17Questa pagina copre i requisiti del gateway e la configurazione per Claude Code CLI. Le distribuzioni Enterprise Desktop possono configurare i provider gateway tramite [impostazioni gestite](https://support.claude.com/it/articles/12622667-enterprise-configuration). L'app Claude Desktop può anche funzionare su un gateway self-hosted tramite l'[anteprima di ricerca Cowork on 3P](https://claude.com/docs/cowork/3p/gateway), che utilizza le proprie chiavi di configurazione.13* [Cosa fornisce un gateway](#what-a-gateway-provides)
18 14* [Come funzionano l'instradamento e le credenziali](#how-a-gateway-works)
19<h2 id="gateway-requirements">15* [I passaggi per eseguire il rollout](#roll-out-a-gateway)
20 Requisiti del gateway16* [Come i gateway interagiscono con gli abbonamenti a claude.ai](#subscriptions-and-gateways)
21</h2>17* [Cosa viene configurato separatamente dal gateway](#configure-separately-from-the-gateway)
22
23Affinché un gateway LLM funzioni con Claude Code, deve soddisfare i seguenti requisiti:
24
25**Formato API**
26
27Il gateway deve esporre ai client almeno uno dei seguenti formati API:
28
291. **Anthropic Messages**: `/v1/messages`, `/v1/messages/count_tokens`
30 * Deve inoltrare le intestazioni della richiesta: `anthropic-beta`, `anthropic-version`
31
322. **Bedrock InvokeModel**: `/invoke`, `/invoke-with-response-stream`
33 * Deve preservare i campi del corpo della richiesta: `anthropic_beta`, `anthropic_version`
34
353. **Vertex rawPredict**: `:rawPredict`, `:streamRawPredict`, `/count-tokens:rawPredict`
36 * Deve inoltrare le intestazioni della richiesta: `anthropic-beta`, `anthropic-version`
37
38Il mancato inoltro delle intestazioni o la mancata preservazione dei campi del corpo potrebbe causare una riduzione della funzionalità o l'impossibilità di utilizzare le funzionalità di Claude Code.
39 18
40<Note>19<Note>
41 Claude Code determina quali funzionalità abilitare in base al formato API. Quando si utilizza il formato Anthropic Messages con Bedrock o Vertex, potrebbe essere necessario impostare la variabile di ambiente `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`.20 - Se sei uno sviluppatore che si connette a un gateway esistente: [collega Claude Code al tuo gateway](/it/llm-gateway-connect)
21 - Se sei un amministratore che esegue il rollout di un gateway per la tua organizzazione: [distribuisci e distribuisci un gateway](/it/llm-gateway-rollout)
22 - Se stai configurando un prodotto gateway: il [riferimento del protocollo gateway](/it/llm-gateway-protocol)
42</Note>23</Note>
43 24
44**Intestazioni della richiesta**25<h2 id="what-a-gateway-provides">
45 26 Cosa fornisce un gateway
46Claude Code include le seguenti intestazioni su ogni richiesta API:
47
48| Intestazione | Descrizione |
49| :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
50| `X-Claude-Code-Session-Id` | Un identificatore univoco per la sessione Claude Code corrente. I proxy possono utilizzarlo per aggregare tutte le richieste API da una singola sessione senza analizzare il corpo della richiesta. |
51| `X-Claude-Code-Agent-Id` | Identificatore del subagent o del teammate che ha emesso la richiesta. Il vostro proxy può utilizzarlo per attribuire il costo API ai singoli subagent paralleli all'interno di una sessione, senza analizzare il corpo della richiesta. Presente solo per le richieste effettuate da un subagent o teammate in-process. |
52| `X-Claude-Code-Parent-Agent-Id` | Identificatore dell'agente che ha generato l'agente che effettua la richiesta. Utilizzatelo insieme a `X-Claude-Code-Agent-Id` per attribuire i costi API tra gli agenti annidati nel vostro proxy. Presente solo quando l'agente richiedente è stato a sua volta generato da un altro agente. |
53
54Entrambe le intestazioni dell'ID agente sono identificatori effimeri per spawn, non ID utente o dispositivo persistenti.
55
56Claude Code inoltre antepone un breve blocco di attribuzione al prompt di sistema contenente la versione del client e un'impronta digitale derivata dalla conversazione. L'API Anthropic rimuove questo blocco prima dell'elaborazione, quindi non influisce sulla memorizzazione nella cache del prompt di prima parte. Se il vostro gateway implementa la propria cache del prompt con chiave sul corpo della richiesta completo, impostate [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/it/env-vars) per ometterlo.
57
58<h2 id="configuration">
59 Configurazione
60</h2>27</h2>
61 28
62<h3 id="model-selection">29Un gateway offre alla tua organizzazione un unico posto per gestire:
63 Selezione del modello
64</h3>
65
66Per impostazione predefinita, Claude Code utilizza nomi di modelli standard per il formato API selezionato.
67 30
68Quando `ANTHROPIC_BASE_URL` punta a un gateway che espone il formato Anthropic Messages, Claude Code interroga l'endpoint `/v1/models` del gateway all'avvio e aggiunge i modelli restituiti al selettore `/model`. Impostare `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` per abilitare questa funzionalità. La scoperta è disabilitata per impostazione predefinita in modo che i gateway supportati da una chiave API condivisa non espongano ogni modello a cui la chiave può accedere a ogni utente. Ogni voce scoperta è etichettata "From gateway" e utilizza il campo `display_name` dalla risposta quando fornito. Ciò richiede Claude Code v2.1.129 o successivo.31* **Credenziali**: la chiave del provider rimane lato server; gli sviluppatori mantengono invece le credenziali del gateway
32* **Tracciamento dell'utilizzo**: attribuisci l'utilizzo per sviluppatore o team, indipendentemente da quale provider serve la richiesta
33* **Controlli dei costi**: applica budget e limiti di velocità in un unico posto
34* **Registrazione di audit**: registra ogni richiesta di modello per la conformità
35* **Cambio di provider**: cambia il provider nella configurazione del gateway, senza toccare le macchine degli sviluppatori
69 36
70La scoperta si applica solo al formato Anthropic Messages. Non viene eseguita per gli endpoint pass-through Bedrock o Vertex e non viene eseguita quando `ANTHROPIC_BASE_URL` non è impostato o punta a `api.anthropic.com`.37Tutti questi, tranne il cambio di provider, si applicano sia che l'upstream sia l'API di Anthropic che un [provider cloud](/it/third-party-integrations).
71 38
72La richiesta di scoperta si autentica nello stesso modo delle richieste di inferenza: invia `ANTHROPIC_AUTH_TOKEN` come token bearer, o `ANTHROPIC_API_KEY` come intestazione `x-api-key` quando nessun token di autenticazione è impostato, insieme a qualsiasi intestazione da `ANTHROPIC_CUSTOM_HEADERS`. Solo i modelli il cui ID inizia con `claude` o `anthropic` vengono aggiunti al selettore. I risultati vengono memorizzati nella cache in `~/.claude/cache/gateway-models.json` e aggiornati a ogni avvio. Se la richiesta non riesce o il gateway non implementa `/v1/models`, il selettore ritorna all'elenco memorizzato nella cache dall'avvio precedente o all'elenco di modelli integrato.39Il compromesso è che il gateway diventa un'infrastruttura che la tua organizzazione gestisce. Claude Code aggiunge funzionalità con ogni rilascio, e un gateway che non le inoltra interrompe le funzionalità corrispondenti, quindi il prodotto gateway deve essere mantenuto aggiornato man mano che Claude Code evolve. Il [riferimento del protocollo gateway](/it/llm-gateway-protocol) copre cosa inoltrare.
73 40
74Se il tuo gateway utilizza nomi di modelli che non corrispondono al filtro di scoperta, utilizza le variabili di ambiente documentate in [Configurazione del modello](/it/model-config) per aggiungerli manualmente.41<h2 id="how-a-gateway-works">
75 42 Come funziona un gateway
76<h2 id="litellm-configuration">
77 Configurazione di LiteLLM
78</h2>43</h2>
79 44
80<Warning>45Per impostazione predefinita, Claude Code invia richieste direttamente all'API di Anthropic su `api.anthropic.com`. Per instradare attraverso un gateway, imposta `ANTHROPIC_BASE_URL` all'indirizzo del gateway; Claude Code invia le stesse richieste lì invece. Il gateway autentica lo sviluppatore, allega la credenziale del provider della tua organizzazione e inoltra ogni richiesta a qualunque provider sia configurato.
81 Le versioni PyPI di LiteLLM 1.82.7 e 1.82.8 sono state compromesse con malware che ruba credenziali. Non installare queste versioni. Se le hai già installate:
82
83 * Rimuovi il pacchetto
84 * Ruota tutte le credenziali sui sistemi interessati
85 * Segui i passaggi di correzione in [BerriAI/litellm#24518](https://github.com/BerriAI/litellm/issues/24518)
86
87 LiteLLM è un servizio proxy di terze parti. Anthropic non approva, mantiene o controlla la sicurezza o la funzionalità di LiteLLM. Questa guida è fornita a scopo informativo e potrebbe diventare obsoleta. Utilizzala a tua discrezione.
88</Warning>
89
90<h3 id="prerequisites">
91 Prerequisiti
92</h3>
93
94* Claude Code aggiornato all'ultima versione
95* LiteLLM Proxy Server distribuito e accessibile
96* Accesso ai modelli Claude attraverso il provider scelto
97
98<h3 id="basic-litellm-setup">
99 Configurazione di base di LiteLLM
100</h3>
101
102**Configura Claude Code**:
103
104<h4 id="authentication-methods">
105 Metodi di autenticazione
106</h4>
107 46
108<h5 id="static-api-key">47`ANTHROPIC_BASE_URL` è la variabile di indirizzo per la maggior parte dei gateway. Un gateway che fronteggia un provider cloud specifico, come Bedrock, Vertex, Foundry o la Claude Platform su AWS, utilizza invece la variabile di URL di base di quel provider; [Formati API](/it/llm-gateway-protocol#api-formats) elenca quale variabile va con ogni configurazione.
109 Chiave API statica
110</h5>
111 48
112Metodo più semplice utilizzando una chiave API fissa:49<Frame>
50 <img src="https://mintcdn.com/claude-code/zIcIE_SQv4Z0Zbhc/images/llm-gateway-flow.svg?fit=max&auto=format&n=zIcIE_SQv4Z0Zbhc&q=85&s=490607d033d235694efb49a73a5b9e4b" alt="Diagramma che mostra Claude Code instradato attraverso un gateway LLM. In una zona di macchine sviluppatore, la CLI di Claude Code, l'estensione VS Code e i client SDK CI o Agent inviano richieste al gateway, con la variabile di URL di base per il formato API del gateway che punta ad esso e ogni sviluppatore che tiene una credenziale per sviluppatore, e l'app desktop raggiunge lo stesso gateway attraverso la configurazione distribuita dall'organizzazione. In una zona etichettata la tua infrastruttura, il gateway LLM gestisce l'autenticazione, il tracciamento dell'utilizzo, i budget e l'instradamento, e inoltra le richieste con la credenziale della tua organizzazione. In una zona di provider di modelli, una freccia solida porta al provider che configuri, mostrato come l'API di Anthropic, e frecce tratteggiate portano ad altre opzioni di provider, illustrate con Amazon Bedrock, Google Vertex AI e Microsoft Foundry come esempi." width="780" height="322" data-path="images/llm-gateway-flow.svg" />
51</Frame>
113 52
114```bash theme={null}53Due tipi di credenziale sono coinvolti:
115# Imposta nell'ambiente
116export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key
117 54
118# O nelle impostazioni di Claude Code55* **Credenziali sviluppatore**: ogni sviluppatore ne tiene una propria, emessa dal gateway. Autentica lo sviluppatore al gateway e lo identifica nel tracciamento dell'utilizzo
119{56* **Credenziale provider**: il gateway ne tiene una per il tuo account provider, condivisa da tutto il traffico inoltrato. Non esegui il provisioning delle chiavi del provider per sviluppatore
120 "env": {
121 "ANTHROPIC_AUTH_TOKEN": "sk-litellm-static-key"
122 }
123}
124```
125 57
126Questo valore verrà inviato come intestazione `Authorization`.58Il gateway inoltra ogni richiesta al provider che configuri, come l'API di Anthropic, [Amazon Bedrock](/it/amazon-bedrock), [Google Vertex AI](/it/google-vertex-ai), [Microsoft Foundry](/it/microsoft-foundry), o la [Claude Platform su AWS](/it/claude-platform-on-aws). Poiché Claude Code parla solo al gateway, la scelta del provider è la configurazione del gateway, non quella del client.
127 59
128<h5 id="dynamic-api-key-with-helper">60<h2 id="roll-out-a-gateway">
129 Chiave API dinamica con helper61 Esegui il rollout di un gateway
130</h5>62</h2>
131
132Per chiavi rotanti o autenticazione per utente:
133
1341. Crea uno script helper per la chiave API:
135
136```bash theme={null}
137#!/bin/bash
138# ~/bin/get-litellm-key.sh
139
140# Esempio: Recupera la chiave dal vault
141vault kv get -field=api_key secret/litellm/claude-code
142
143# Esempio: Genera token JWT
144jwt encode \
145 --secret="${JWT_SECRET}" \
146 --exp="+1h" \
147 '{"user":"'${USER}'","team":"engineering"}'
148```
149
1502. Configura le impostazioni di Claude Code per utilizzare l'helper:
151
152```json theme={null}
153{
154 "apiKeyHelper": "~/bin/get-litellm-key.sh"
155}
156```
157
1583. Imposta l'intervallo di aggiornamento del token:
159
160```bash theme={null}
161# Aggiorna ogni ora (3600000 ms)
162export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000
163```
164
165Questo valore verrà inviato come intestazioni `Authorization` e `X-Api-Key`. L'`apiKeyHelper` ha una precedenza inferiore rispetto a `ANTHROPIC_AUTH_TOKEN` o `ANTHROPIC_API_KEY`.
166
167<h4 id="unified-endpoint-recommended">
168 Endpoint unificato (consigliato)
169</h4>
170
171Utilizzando l'[endpoint in formato Anthropic](https://docs.litellm.ai/docs/anthropic_unified) di LiteLLM:
172
173```bash theme={null}
174export ANTHROPIC_BASE_URL=https://litellm-server:4000
175```
176
177**Vantaggi dell'endpoint unificato rispetto agli endpoint pass-through:**
178
179* Bilanciamento del carico
180* Fallback
181* Supporto coerente per il tracciamento dei costi e il tracciamento dell'utente finale
182
183<h4 id="provider-specific-pass-through-endpoints-alternative">
184 Endpoint pass-through specifici del provider (alternativa)
185</h4>
186
187<h5 id="claude-api-through-litellm">
188 Claude API attraverso LiteLLM
189</h5>
190
191Utilizzando l'[endpoint pass-through](https://docs.litellm.ai/docs/pass_through/anthropic_completion):
192 63
193```bash theme={null}64Quando sei pronto a eseguire il rollout di un gateway LLM alla tua organizzazione, la sequenza è la stessa indipendentemente dal prodotto gateway che scegli:
194export ANTHROPIC_BASE_URL=https://litellm-server:4000/anthropic
195```
196 65
197<h5 id="amazon-bedrock-through-litellm">661. Distribuisci il gateway e dagli la tua credenziale del provider, in modo che possa autenticare le richieste che inoltra.
198 Amazon Bedrock attraverso LiteLLM672. Emetti a ogni sviluppatore una credenziale del gateway, in modo che l'utilizzo sia attribuito allo sviluppatore e l'offboarding revoca una credenziale.
199</h5>683. Distribuisci la configurazione attraverso un [file di impostazioni gestite](/it/settings#settings-files) e il tuo strumento di segreti, in modo che ogni macchina riceva l'URL di base e una credenziale. Quando entrambi sono distribuiti, gli sviluppatori non configurano nulla. Se non hai la distribuzione delle impostazioni in atto, gli sviluppatori seguono la [pagina di connessione](/it/llm-gateway-connect) per impostare le variabili stessi.
694. Fai in modo che ogni sviluppatore [verifichi la configurazione in Claude Code](/it/llm-gateway-connect#check-for-an-existing-configuration), in modo che i problemi di distribuzione emergano prima che dipendano dal gateway.
200 70
201Utilizzando l'[endpoint pass-through](https://docs.litellm.ai/docs/pass_through/bedrock):71[Esegui il rollout di un gateway LLM per la tua organizzazione](/it/llm-gateway-rollout) esamina ogni passaggio e mostra i file di configurazione da distribuire a ogni passaggio. Il gateway è una parte della configurazione dell'organizzazione; per l'applicazione delle politiche, la visibilità dell'utilizzo e le decisioni sulla gestione dei dati, vedi [Configura Claude Code per la tua organizzazione](/it/admin-setup).
202 72
203```bash theme={null}73<h2 id="third-party-gateways">
204export ANTHROPIC_BEDROCK_BASE_URL=https://litellm-server:4000/bedrock74 Gateway di terze parti
205export CLAUDE_CODE_SKIP_BEDROCK_AUTH=175</h2>
206export CLAUDE_CODE_USE_BEDROCK=1
207```
208 76
209<h5 id="google-vertex-ai-through-litellm">77Qualsiasi gateway che espone un [formato API supportato](/it/llm-gateway-protocol#api-formats) funziona. Anthropic non approva, mantiene o controlla i prodotti gateway di terze parti. Distribuiscili seguendo la loro documentazione, quindi completa il lato Claude Code del rollout con i [passaggi di rollout](/it/llm-gateway-rollout).
210 Google Vertex AI attraverso LiteLLM
211</h5>
212 78
213Utilizzando l'[endpoint pass-through](https://docs.litellm.ai/docs/pass_through/vertex_ai):79<h2 id="subscriptions-and-gateways">
80 Abbonamenti e gateway
81</h2>
214 82
215```bash theme={null}83Mentre una [variabile di credenziale del gateway](/it/llm-gateway-connect#set-the-credential-variable) o `apiKeyHelper` è attiva, l'abbonamento a claude.ai di uno sviluppatore non viene utilizzato: la credenziale sostituisce l'accesso all'abbonamento per quella sessione, e i limiti di utilizzo dell'abbonamento non si applicano. Quel traffico viene fatturato per token a chiunque possieda la credenziale che il gateway inoltra, come l'account Anthropic Console della tua organizzazione, o il tuo account Bedrock, Vertex o Foundry quando il gateway instrada lì.
216export ANTHROPIC_VERTEX_BASE_URL=https://litellm-server:4000/vertex_ai/v1
217export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
218export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
219export CLAUDE_CODE_USE_VERTEX=1
220export CLOUD_ML_REGION=us-east5
221```
222 84
223<h5 id="claude-platform-on-aws-through-a-gateway">85Impostare solo `ANTHROPIC_BASE_URL`, senza una credenziale del gateway, non sostituisce l'abbonamento. Le richieste vengono comunque instradate attraverso il gateway, ma un accesso a claude.ai salvato rimane la credenziale attiva, quindi i suoi limiti di utilizzo e la fatturazione si applicano. I gateway che passano questo traffico ad Anthropic devono inoltrare la capacità OAuth in `anthropic-beta`; vedi il [riferimento delle intestazioni della richiesta](/it/llm-gateway-protocol#request-headers).
224 Claude Platform su AWS attraverso un gateway
225</h5>
226 86
227Instrada verso un gateway che inoltra all'endpoint [Claude Platform su AWS](/it/claude-platform-on-aws):87<h2 id="configure-separately-from-the-gateway">
88 Configura separatamente dal gateway
89</h2>
228 90
229```bash theme={null}91Un gateway determina dove vengono inviate le richieste API del modello. La selezione del modello, il resto del traffico di rete di Claude Code e i proxy aziendali sono configurati separatamente:
230export ANTHROPIC_AWS_BASE_URL=https://litellm-server:4000/anthropic-aws
231export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
232export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
233export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
234```
235 92
236Per informazioni più dettagliate, consulta la [documentazione di LiteLLM](https://docs.litellm.ai/).93* **Selezione del modello**: l'URL di base decide dove vanno le richieste, non quale modello le risponde. Scegli il modello con il comando `/model` o le variabili di ambiente del modello; vedi [come impostare il tuo modello](/it/model-config#setting-your-model)
94* **Traffico lato client**: i controlli della versione e la telemetria facoltativa del client, entrambi disabilitati con [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/it/env-vars), e il traffico di accesso quando è in uso un accesso a claude.ai o Console, vanno agli endpoint di aggiornamento e autenticazione di Anthropic piuttosto che al gateway. Vedi [requisiti di accesso alla rete](/it/network-config#network-access-requirements) per i domini
95* **Proxy aziendali**: un proxy impostato con `HTTPS_PROXY` si trova tra Claude Code e ogni server con cui parla, incluso il gateway. Se la tua rete richiede un proxy, configura entrambi; vedi [configurazione del proxy](/it/network-config#proxy-configuration)
237 96
238<h2 id="additional-resources">97<h2 id="related-pages">
239 Risorse aggiuntive98 Pagine correlate
240</h2>99</h2>
241 100
242* [Documentazione di LiteLLM](https://docs.litellm.ai/)101* [Collega Claude Code a un gateway LLM](/it/llm-gateway-connect): imposta l'URL di base e la credenziale sulla tua macchina, con configurazione per superficie e una tabella di risoluzione dei problemi
243* [Impostazioni di Claude Code](/it/settings)102* [Esegui il rollout di un gateway LLM per la tua organizzazione](/it/llm-gateway-rollout): la checklist dell'amministratore per distribuire un gateway, emettere credenziali sviluppatore e distribuire impostazioni gestite
244* [Configurazione della rete aziendale](/it/network-config)103* [Riferimento del protocollo gateway](/it/llm-gateway-protocol): cosa Claude Code invia a un gateway, per gli operatori che ne configurano uno, coprendo endpoint, intestazioni da inoltrare e pass-through delle funzionalità
245* [Panoramica delle integrazioni di terze parti](/it/third-party-integrations)104* [Configura Claude Code per la tua organizzazione](/it/admin-setup): le decisioni di rollout più ampie di cui un gateway è una parte, inclusa l'applicazione delle politiche e la visibilità dell'utilizzo
