Distribuire un gateway LLM per la vostra organizzazione

​

Prerequisiti

• 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:
  • Per l’API Anthropic: una chiave API dalla Claude Console
  • Per un provider cloud: credenziali cloud con accesso ai modelli. Vedere i prerequisiti nella pagina Amazon Bedrock, Google Vertex AI o Microsoft Foundry
• Un modo per consegnare file di impostazioni alle macchine degli sviluppatori, come MDM o gestione della configurazione
  • Se non ne avete ancora uno, come le impostazioni raggiungono i dispositivi confronta le opzioni

​

Requisiti del gateway

• 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 invece di memorizzare l’intera risposta nel buffer
• 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
• 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

​

Passaggi di distribuzione

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

​

Confermare che il gateway instrada i vostri modelli

• <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

curl -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <gateway-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Invoke-RestMethod -Method Post -Uri "https://llm-gateway.example.com/v1/messages" `
  -Headers @{ "Authorization" = "Bearer <gateway-key>"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

​

Emettere credenziali per sviluppatori

curl -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <developer-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Invoke-RestMethod -Method Post -Uri "https://llm-gateway.example.com/v1/messages" `
  -Headers @{ "Authorization" = "Bearer <developer-key>"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

​

Testare Claude Code rispetto al gateway

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN="<developer-key>"

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

claude -p "Reply with one word: connected"

• 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

​

Distribuire la configurazione

​

Cosa distribuire

​

Distribuire tramite impostazioni gestite

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com"
  },
  "apiKeyHelper": "/usr/local/bin/get-gateway-key"
}

• L’app desktop legge l’instradamento del gateway solo dalla sua configurazione di inferenza di terze parti consegnata tramite MDM; distribuite quel file insieme alle impostazioni gestite in modo che le sessioni desktop instradino anche attraverso il gateway. Vedere la documentazione di configurazione di terze parti del desktop e la documentazione del gateway del desktop
• I runner CI hanno bisogno di ANTHROPIC_BASE_URL e della credenziale impostati nell’ambiente del runner
• WSL su macchine Windows gestite legge le impostazioni gestite di Windows solo quando wslInheritsWindowsSettings è true

​

Consegnare agli sviluppatori i valori da impostare loro stessi

• 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

​

Verificare la distribuzione

curl -N -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <developer-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'

$body = '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'
$body | curl.exe -N -X POST "https://llm-gateway.example.com/v1/messages" `
  -H "Authorization: Bearer <developer-key>" `
  -H "anthropic-version: 2023-06-01" `
  -H "content-type: application/json" `
  --data-binary '@-'

• 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

​

Mantenere il gateway

​

Risorse correlate

• Connettere Claude Code a un gateway LLM: i passaggi di configurazione rivolti agli sviluppatori, con configurazione per superficie e una tabella di risoluzione dei problemi che potete consegnare agli sviluppatori
• Riferimento del protocollo gateway: il contratto di rete per gli operatori del gateway, che copre endpoint, intestazioni da inoltrare e la tabella di pass-through delle funzionalità
• File di impostazioni e precedenza: come le impostazioni gestite, di progetto e utente si combinano, e dove va il file gestito su ogni piattaforma
• Configurare Claude Code per la vostra organizzazione: la distribuzione più ampia di cui questo gateway è una parte, inclusa l’applicazione delle politiche, la visibilità dell’utilizzo e la gestione dei dati