Skip to main content
Questa pagina guida un amministratore nella distribuzione di un gateway LLM per Claude Code. Presuppone che abbiate un prodotto gateway distribuito che soddisfi i requisiti del gateway. La distribuzione o l’operazione di qualsiasi prodotto specifico non è trattata qui; distribuite il vostro seguendo la documentazione del fornitore.

​
Prerequisiti

Per completare la distribuzione, avrete bisogno di:
  • Un gateway distribuito sulla vostra infrastruttura, che serve HTTPS all’indirizzo esatto che distribuirete agli sviluppatori, non a un indirizzo che vi reindirizza, e configurato per instradare i nomi dei modelli Claude al vostro provider
  • Una credenziale del provider per il gateway da inoltrare con:
  • Un modo per consegnare file di impostazioni alle macchine degli sviluppatori, come MDM o gestione della configurazione

​
Requisiti del gateway

Qualunque prodotto fornisca il gateway, deve:
  • Accettare un formato API supportato: uno dei formati nella tabella dei formati API. I passaggi di distribuzione di seguito presuppongono l’API Anthropic Messages a POST /v1/messages, che la maggior parte dei gateway serve
  • Trasmettere le risposte in streaming: passare gli eventi inviati dal server così come arrivano, inclusi i ping keep-alive, invece di memorizzare l’intera risposta nel buffer; streaming spiega cosa il buffering o i ping rimossi interrompono
  • Instradare i nomi dei modelli Claude: mappare ogni nome che gli sviluppatori usano a un modello upstream. Claude Code invia un nome di modello come claude-sonnet-4-6 in ogni richiesta; nella maggior parte dei prodotti gateway il mapping è un elenco di modelli o una tabella di instradamento nella configurazione del gateway stesso
  • Inoltrare intestazioni e corpo invariati: passare anthropic-beta, anthropic-version e il corpo della richiesta in entrambe le direzioni; la tabella di pass-through delle funzionalità mappa ciascuno alla funzionalità che si interrompe senza di esso
  • Restituire gli errori upstream non modificati: il recupero automatico di Claude Code corrisponde alla formulazione dell’errore, quindi avvolgere gli errori nel proprio envelope del gateway lo interrompe, a meno che l’envelope del messaggio non contenga uno dei token capability_rejected: che un gateway di Claude apps sostituisce per la formulazione dell’errore dei provider cloud
  • Esentare il percorso dall’ispezione WAF del corpo della richiesta: i prompt di Claude Code contengono codice sorgente e tag in stile XML che corrispondono alle regole del corpo dello scripting tra siti; un WAF davanti al gateway restituisce 403 su sessioni reali mentre le brevi richieste di test passano
Facoltativamente, servire GET /v1/models in modo che Claude Code possa popolare il selettore di modelli dal vostro gateway con model discovery.

​
Passaggi di distribuzione

La distribuzione richiede cinque passaggi, ciascuno con un checkpoint:
  1. Confermare che il gateway instrada i vostri modelli
  2. Emettere a ogni sviluppatore una credenziale
  3. Testare Claude Code rispetto al gateway
  4. Distribuire l’URL di base e le credenziali
  5. Verificare da una macchina sviluppatore
I passaggi coinvolgono tre credenziali diverse e i checkpoint le nominano per segnaposto in modo che possiate dire quale sia responsabile quando qualcosa fallisce:

​
Confermare che il gateway instrada i vostri modelli

Il vostro gateway dovrebbe già essere configurato con la vostra credenziale del provider, in ascolto al suo URL di base e inoltro delle richieste all’API del vostro provider. Testate che il percorso funzioni da capo a fondo con una richiesta minima, sostituendo due valori dalla vostra distribuzione:
  • <gateway-key> è qualunque credenziale vi consenta di chiamare il gateway in questo momento: una chiave amministrativa, una chiave di test o la vostra chiave sviluppatore personale se ne avete già emessa una. Non tutti i prodotti gateway hanno una credenziale amministrativa separata; se il vostro non ne ha una, emettete prima una chiave sviluppatore per voi stessi in Emettere credenziali per sviluppatori
  • model è un nome di modello Claude che il vostro gateway è configurato per instradare. L’esempio usa claude-sonnet-4-6; sostituite un nome che avete configurato
Checkpoint: un 200 con un campo content significa che il gateway ha raggiunto il provider con quel nome di modello. Un 404 significa che quel nome non è instradato al gateway; un 401 dal provider significa che la credenziale del provider del gateway è sbagliata. Ripetete la richiesta una volta per ogni nome di modello Claude nella configurazione di instradamento del vostro gateway. Un nome che il gateway non instrada restituisce 404 a qualsiasi sviluppatore che lo seleziona, quindi testate ogni nome prima della distribuzione.
Evitate di servire il gateway dietro un reindirizzamento. Un reindirizzamento può eliminare il corpo della richiesta o rimuovere l’intestazione della credenziale sulle richieste di inferenza, e model discovery tratta qualsiasi reindirizzamento come un fallimento in modo che la credenziale non possa trapelare a una destinazione di reindirizzamento.

​
Emettere credenziali per sviluppatori

Ogni sviluppatore ha bisogno della propria chiave gateway per autenticarsi. Create una credenziale per sviluppatore al gateway, seguendo la documentazione di gestione delle credenziali del vostro prodotto. Confermate che una chiave appena emessa funzioni rispetto al gateway con la stessa richiesta di Confermare che il gateway instrada i vostri modelli, sostituendo <gateway-key> con la nuova <developer-key>:
Checkpoint: un 200 con un campo content significa che la chiave dello sviluppatore raggiunge il gateway e il gateway la inoltra. Un 401 qui, quando il passaggio precedente ha avuto successo, significa che la chiave dello sviluppatore è sbagliata o non ha ancora avuto effetto al gateway. Emettere una chiave per sviluppatore piuttosto che una chiave condivisa è ciò che rende possibile l’attribuzione dell’utilizzo per sviluppatore e l’offboarding individuale. La variabile di ambiente che contiene la chiave dipende da quale intestazione il gateway legge. Per un gateway che controlla le credenziali nell’intestazione Authorization: Bearer, gli sviluppatori impostano la loro chiave in ANTHROPIC_AUTH_TOKEN. Per un gateway che legge le chiavi dall’intestazione x-api-key, gli sviluppatori impostano invece ANTHROPIC_API_KEY; la tabella delle credenziali copre il mapping.

​
Testare Claude Code rispetto al gateway

Eseguite Claude Code attraverso il gateway voi stessi prima di distribuire qualcosa, usando la stessa configurazione che la distribuzione consegnerà a livello di flotta. Digitate questi direttamente in un terminale, non in un file .env o di impostazioni; durano solo per questa sessione di terminale, quindi chiuderla restituisce la vostra macchina alla sua configurazione normale. Usate ANTHROPIC_API_KEY invece di ANTHROPIC_AUTH_TOKEN se il vostro gateway legge l’intestazione x-api-key:
Quindi inviate un prompt una tantum attraverso il gateway:
Checkpoint: il prompt restituisce una risposta e la richiesta appare nel log del gateway come un POST al percorso /v1/messages con stato 200. Claude Code aggiunge una stringa di query come ?beta=true, quindi abbinate il percorso, non l’URL completo. Due messaggi di errore puntano in direzioni diverse:
  • Not logged in: controllate il log del gateway per distinguere le due cause. Se è vuoto, nessuna credenziale ha raggiunto la sessione e nessuna richiesta ha lasciato la macchina; rieseguite le esportazioni nella shell da cui state testando. Se mostra una richiesta rifiutata con x-api-key nel corpo 401, il gateway si aspetta chiavi in quell’intestazione invece; passate a ANTHROPIC_API_KEY
  • Failed to authenticate. API Error: 401 significa che una credenziale è stata inviata e rifiutata, e il log del gateway dice dove: un 401 che nomina api.anthropic.com o l’endpoint del vostro provider significa che il gateway ha raggiunto l’upstream ma la sua credenziale del provider è stata rifiutata, quindi la chiave dello sviluppatore ha funzionato e la credenziale del provider che il gateway detiene è sbagliata o un segnaposto
Un URL di base sbagliato o irraggiungibile produce un sintomo diverso: Claude Code ritenta la connessione con backoff e può stare senza output per diversi minuti prima di segnalare un errore. Se il comando sembra bloccarsi, controllate il log del gateway invece di aspettare; nessuna richiesta in arrivo significa che ANTHROPIC_BASE_URL non punta al gateway.

​
Distribuire la configurazione

Ogni macchina sviluppatore ha bisogno dell’indirizzo del gateway e di una credenziale. Potete distribuirli centralmente tramite impostazioni gestite, in modo che gli sviluppatori non configurino nulla, o consegnate agli sviluppatori i valori da impostare loro stessi.

​
Cosa distribuire

Lo stesso insieme di variabili si applica qualunque percorso scegliate. La maggior parte delle distribuzioni ha bisogno solo di ANTHROPIC_BASE_URL e di una credenziale; includete le righe condizionali quando la vostra configurazione del gateway lo richiede.

​
Distribuire tramite impostazioni gestite

Consegnate le variabili attraverso il blocco env di un file di impostazioni gestite, spinto da MDM, criterio di registro o gestione della configurazione:
Aggiungete le variabili condizionali dalla tabella allo stesso blocco env. Un ANTHROPIC_BASE_URL gestito è applicato e non può essere sovrascritto da un’esportazione di shell di uno sviluppatore, poiché Claude Code lo applica sopra l’ambiente del processo e le impostazioni di priorità inferiore. Non includete forceLoginMethod o forceLoginOrgUUID nelle impostazioni gestite insieme a una credenziale gateway. Una delle due chiavi, con qualsiasi valore, blocca ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN e apiKeyHelper all’avvio, e gli sviluppatori non possono procedere. Vedono This machine's managed settings require a first-party login, o Administrator policy requires a Cloud gateway sign-in sotto un valore "gateway". La consegna di impostazioni gestite dal server richiede una connessione diretta a api.anthropic.com, quindi non raggiunge le sessioni instradate dal gateway. Le distribuzioni gateway utilizzano questo percorso di impostazioni gestite basato su file, che applica le stesse chiavi. Per la credenziale, distribuite un comando apiKeyHelper nel file di impostazioni gestite come mostrato sopra; il comando si autentica al vostro archivio di segreti come sviluppatore locale, quindi ogni macchina riceve la propria chiave. In alternativa, consegnate a ogni sviluppatore la sua chiave attraverso il vostro processo di segreti esistente e fate loro impostare ANTHROPIC_AUTH_TOKEN loro stessi. Alcuni ambienti hanno bisogno di consegna separata:

​
Consegnare agli sviluppatori i valori da impostare loro stessi

Se non avete la distribuzione di impostazioni gestite in atto, inviate a ogni sviluppatore ciò di cui ha bisogno per seguire la pagina di connessione:
  • L’URL del gateway
  • La loro credenziale personale
  • Quale variabile mettere la credenziale in: ANTHROPIC_AUTH_TOKEN per un gateway bearer-token, o ANTHROPIC_API_KEY per un gateway x-api-key. Dire agli sviluppatori quale uno risparmia loro il trial-and-error descritto nella pagina di connessione
  • Qualsiasi variabile condizionale dalla tabella Cosa distribuire, con i loro valori
La pagina di connessione guida gli sviluppatori attraverso l’impostazione di ciascuno. Checkpoint: su una macchina sviluppatore, claude avvia una sessione senza mostrare la schermata di accesso, poiché la credenziale distribuita soddisfa l’autenticazione. Quindi eseguite /status e aprite la scheda Status: la riga Anthropic base URL mostra l’indirizzo del gateway, e per la distribuzione gestita la riga Setting sources include impostazioni gestite. Una schermata di accesso, o una riga Anthropic base URL mancante, significa che la configurazione non ha raggiunto la macchina.

​
Verificare la distribuzione

Confermate che tutto funzioni da una macchina sviluppatore, non dall’host del gateway, in modo che il test copra il percorso di rete che gli sviluppatori usano. Inviate una richiesta in streaming, che controlla l’endpoint, il pass-through dello streaming e l’instradamento del modello in una volta:
Dovreste vedere le righe data: arrivare in modo incrementale. L’intera risposta che arriva in una volta dopo una pausa significa che il gateway sta memorizzando nel buffer, il che blocca Claude Code; un 404 significa che il nome del modello non è instradato. Ripetete per nome di modello. Quindi avviate claude e inviate un messaggio. Ogni sintomo in questo passaggio ha una causa:
  • Un prompt di accesso significa un divario di credenziale. Eseguite /status e aprite la scheda Status: quando la riga Setting sources non include impostazioni gestite, la distribuzione non ha raggiunto la macchina; quando lo fa, la credenziale dello sviluppatore non è stata consegnata, quindi impostate ANTHROPIC_AUTH_TOKEN o apiKeyHelper
  • Gli errori Failed to authenticate significano che il gateway sta rifiutando le richieste; il suo log dice quale credenziale ha fallito. Un rifiuto che il gateway registra stesso nomina la chiave dello sviluppatore, mentre un 401 da api.anthropic.com o dall’endpoint del vostro provider significa che la credenziale del provider che il gateway detiene è stata rifiutata
  • Un prompt di approvazione una tantum per la chiave è previsto al primo utilizzo quando il gateway si aspetta chiavi nell’intestazione x-api-key, impostata come ANTHROPIC_API_KEY. Con ANTHROPIC_AUTH_TOKEN, nessun prompt appare e la variabile prende il controllo silenziosamente; un accesso claude.ai precedentemente salvato è inattivo per quella sessione
Se la vostra organizzazione usa fast mode, eseguite /fast qui anche: il controllo di disponibilità chiama api.anthropic.com direttamente piuttosto che seguire l’URL di base del gateway, quindi una sessione instradata dal gateway può segnalare fast mode come non disponibile o disabilitato anche se l’inferenza funziona. Usare fast mode dietro proxy e gateway LLM mappa ogni messaggio alla variabile che lo ripristina, distribuita con il resto della configurazione. Infine, controllate i log del gateway per il messaggio che avete inviato: la credenziale identifica lo sviluppatore, e l’intestazione x-claude-code-session-id raggruppa le richieste per sessione. Se le funzionalità falliscono con i sintomi di risoluzione dei problemi, il gateway sta rimuovendo intestazioni o riscrivendo errori; vedere i requisiti del gateway sopra.

​
Mantenere il gateway

Dopo la distribuzione, tre tipi di cambiamento raggiungono il gateway nel tempo. Ciascuno ha un sintomo da osservare e un’azione da intraprendere. Quando dimensionate i limiti di velocità per chiave, tenete conto del client che ritenta i fallimenti transitori, incluse le risposte 429, fino a 10 volte con backoff, onorando Retry-After. Mantenete la guida di compatibilità come riferimento per ciò che ogni versione di Claude Code invia.

​
Plan Claude Code version upgrades

Alcuni comportamenti di Claude Code sono incorporati nella versione installata piuttosto che impostati al vostro gateway, quindi spostare gli sviluppatori a una nuova versione può cambiare il comportamento in tutta la vostra distribuzione anche quando la configurazione del gateway non è cambiata. Per controllare quando ciò accade, fissate gli sviluppatori a una versione testata con requiredMaximumVersion, o con DISABLE_UPDATES se distribuite Claude Code attraverso il vostro canale. Prima di aumentare il pin, leggete la voce changelog della nuova versione e testatela rispetto al gateway. Quando testate una versione, le nuove intestazioni o i campi di richiesta che il gateway rifiuta appaiono come gli errori 400 descritti in Maintain the gateway. La tabella seguente copre i cambiamenti dipendenti dalla versione che non producono un errore, con l’impostazione che mantiene ciascuno costante tra gli aggiornamenti.