Chiave API di Claude Code — ANTHROPIC_API_KEY: come ottenerla, configurarla e quando usare invece claude setup-token

Claude Code ha bisogno di una chiave API per funzionare. Che tu stia configurando Claude Code per la prima volta o passando da un account Anthropic diretto a un gateway a tariffa fissa, la procedura prevede la generazione di una chiave, la configurazione di due variabili d'ambiente e la verifica della connessione.

Chiave API di Claude Code: in breve

Una chiave API di Claude Code è una normale chiave in formato Anthropic (sk-...) che Claude Code legge da ANTHROPIC_API_KEY. Puoi ottenerne una nella Claude Console (Impostazioni → Chiavi API, mostrata una sola volta) o nella dashboard di questo gateway (visibile in qualsiasi momento), esportarla e avviare Claude Code senza effettuare l'accesso dal browser. Con una chiave gateway devi anche impostare ANTHROPIC_BASE_URL sull'host del gateway. La configurazione è tutta qui; il resto di questa pagina approfondisce i dettagli: la differenza tra una chiave API, il token OAuth ottenuto da /login e una chiave di sessione di claude.ai, i passaggi per ciascun sistema operativo e gli errori più comuni.

Che cos'è una chiave API di Claude Code

Una chiave API di Claude Code è la credenziale di autenticazione che consente alla CLI di Claude Code di inviare richieste a un fornitore di modelli Claude. Senza di essa, ogni comando eseguito in Claude Code restituisce un errore di autenticazione. La chiave è una stringa che memorizzi in una variabile d'ambiente: ANTHROPIC_API_KEY (inviata come header x-api-key) oppure ANTHROPIC_AUTH_TOKEN (inviata come token Bearer). Entrambe funzionano con AI Prime Tech.

Quando usi un gateway come AI Prime Tech invece di Anthropic direttamente, la chiave proviene dalla dashboard del gateway anziché dalla Anthropic Console. Il formato della chiave può variare, ma la procedura di configurazione in Claude Code è identica: imposta la chiave nel tuo ambiente, indirizza l'URL di base al gateway e Claude Code gestisce il resto. La chiave è associata al saldo o all'abbonamento del tuo account gateway, non alla fatturazione di Anthropic.

Una chiave può essere usata contemporaneamente su più macchine e in più sessioni di Claude Code. Tuttavia, se condividi una chiave con un team, tutto l'utilizzo viene conteggiato nei limiti di frequenza e nel saldo dello stesso account. Per le configurazioni di team, genera dalla dashboard una chiave separata per ogni sviluppatore, in modo che il monitoraggio dell'utilizzo e i limiti di frequenza funzionino correttamente per ciascuna persona.

Chiave API e token OAuth a confronto — e che cos'è una "chiave di sessione"

Claude Code accetta due tipi di credenziali. Una chiave API (ANTHROPIC_API_KEY, oppure ANTHROPIC_AUTH_TOKEN inviata come token Bearer) comporta un addebito per token sul saldo API: è ciò che usi con un gateway. Un token OAuth proviene da un abbonamento Claude Pro o Max: /login all'interno di Claude Code ti consente di accedere, mentre claude setup-token genera un token di lunga durata che puoi inserire in un ambiente CI o su una macchina senza interfaccia grafica, così da utilizzare l'abbonamento anziché un saldo API.

Una "chiave di sessione Claude" non è nessuna delle due: è il cookie di sessione del browser di claude.ai, che alcuni client non ufficiali estraggono per interagire con l'interfaccia di chat. Non è una credenziale API, viola i termini del servizio per i consumatori, scade e può causare la sospensione dell'account. Se vuoi accedere tramite codice, usa una chiave API, ottenuta dalla console di Anthropic o da un gateway come questo.

Passaggio 1 — Ottieni la chiave: Claude Console o dashboard del gateway

Due servizi rilasciano una chiave accettata da Claude Code. Nella Claude Console (la piattaforma Claude all'indirizzo platform.claude.com), apri Impostazioni → Chiavi API, fai clic su Crea chiave, assegnale un nome e copia il valore segreto della chiave: la Console lo mostra una sola volta e in seguito elenca soltanto il nome e il prefisso, quindi per gestire le chiavi devi crearne una nuova anziché recuperare una precedente.

Claude Code richiede una chiave normale; una chiave API amministrativa è una credenziale diversa, destinata alla gestione di un'organizzazione, e non autentica le richieste. Poi esegui export ANTHROPIC_API_KEY=sk-ant-... nella tua shell e Claude Code la utilizzerà senza /login. Anthropic addebita i costi per token e richiede che sull'account sia già presente un metodo di pagamento.

Il percorso più rapido è una chiave gateway: registrati su aiprimetech.io, apri Chiavi API nella dashboard, fai clic su Crea e la chiave sarà visibile nella dashboard in qualsiasi momento: potrai copiarla di nuovo, rinominarla o revocarla quando vuoi. Ha lo stesso formato sk- e funziona con la stessa variabile; l'unico passaggio aggiuntivo è ANTHROPIC_BASE_URL, descritto nel passaggio 2.

A questo punto hai una chiave, ma nessun saldo. Aggiungi una piccola ricarica prima di effettuare una prova: la pagina dei modelli mostra cosa puoi ottenere con un dollaro per ciascun modello. In alternativa, scegli un piano illimitato su /plans/ se sai già che userai Claude Code tutto il giorno.

Passaggio 2 — Imposta le variabili d'ambiente

Claude Code legge due variabili d'ambiente per la configurazione del gateway: ANTHROPIC_BASE_URL e ANTHROPIC_API_KEY. Imposta ANTHROPIC_BASE_URL sull'host principale del gateway, senza alcun suffisso di percorso. L'SDK Anthropic aggiunge automaticamente /v1/messages: se includi /v1 nell'URL di base, le richieste raggiungeranno /v1/v1/messages e restituiranno errori 404.

Su Linux o macOS, aggiungi queste righe al profilo della tua shell (~/.bashrc, ~/.zshrc o ~/.profile): export ANTHROPIC_BASE_URL="https://aiprimetech.io" ed export ANTHROPIC_API_KEY="la-tua-chiave-qui". Su Windows, impostale come variabili d'ambiente di sistema tramite Impostazioni > Sistema > Impostazioni di sistema avanzate > Variabili d'ambiente, oppure aggiungile al tuo $PROFILE di PowerShell.

Per una configurazione specifica per progetto, crea un file .env nella directory principale del progetto con le stesse variabili. Claude Code carica i file .env dalla directory di lavoro e questi hanno la precedenza sulle variabili a livello di sistema. È utile se usi fornitori API diversi per progetti diversi. Assicurati di aggiungere .env al tuo .gitignore per evitare di includere accidentalmente la chiave nel controllo di versione.

Passaggio 3 — Verifica la connessione

Dopo aver impostato le variabili d'ambiente, apri una nuova sessione del terminale (in modo che le variabili vengano caricate) e avvia Claude Code. Digita un messaggio semplice, come 'Ciao, conferma che puoi rispondere.' Se ricevi una risposta da Claude, la configurazione funziona dall'inizio alla fine. La chiave è valida, l'URL di base è corretto e il gateway inoltra correttamente la tua richiesta a Claude.

Se la verifica non riesce, il messaggio di errore indica cosa è andato storto. Un errore 401 o 403 significa che la chiave API non è valida o è scaduta: copiala nuovamente dalla dashboard. Un errore 404 indica quasi sempre che l'URL di base è errato: controlla che non ci siano un suffisso /v1 aggiunto per errore o barre finali. Un errore di connessione rifiutata significa che il gateway non è raggiungibile: controlla le impostazioni di rete, VPN o firewall.

Puoi anche effettuare una verifica tramite codice, chiamando l'endpoint di stato del gateway con curl: curl -H 'Authorization: Bearer YOUR_KEY' https://aiprimetech.io/v1/models — restituisce l'elenco dei modelli disponibili se la chiave è valida. Se questo funziona ma Claude Code no, il problema riguarda il caricamento delle variabili d'ambiente, non la chiave o il gateway.

Passaggio 4 — Configura le preferenze dei modelli

Per impostazione predefinita, Claude Code usa le proprie selezioni di modelli integrate per ogni livello (Sonnet, Opus, Haiku). Puoi sostituirle con ulteriori variabili d'ambiente: ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL e ANTHROPIC_DEFAULT_FABLE_MODEL. Impostale sugli identificatori esatti dei modelli supportati dal gateway.

Per la maggior parte degli sviluppatori, è sufficiente impostare ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5 e ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6. Claude Code usa Sonnet per impostazione predefinita nella maggior parte delle interazioni e usa Opus quando lo selezioni tramite il comando /model o quando la modalità di pianificazione passa a un modello più potente. Il gateway supporta tutte le versioni attuali dei modelli Claude.

Abilita il rilevamento dei modelli del gateway impostando CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1. Questo indica a Claude Code di interrogare il gateway per conoscere i modelli disponibili, invece di usare un elenco predefinito nel codice. Imposta anche CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 per impedire che le richieste di telemetria vengano inviate al gateway: questo riduce il rumore e migliora leggermente la latenza delle richieste.

Risoluzione degli errori di autenticazione più comuni

Il problema più frequente è il mancato caricamento delle variabili d'ambiente. Dopo averle impostate nel tuo profilo, devi aprire un nuovo terminale: i terminali esistenti usano il vecchio ambiente. Su Windows, potrebbe essere necessario riavviare completamente l'applicazione del terminale, non soltanto aprire una nuova scheda. Verifica con echo $ANTHROPIC_BASE_URL (bash/zsh) o echo $env:ANTHROPIC_BASE_URL (PowerShell).

Se ricevi errori 'modello non trovato' nonostante una connessione valida, l'identificatore del modello non corrisponde a quelli offerti dal gateway. Gli ID dei modelli distinguono tra maiuscole e minuscole e sono specifici per ciascuna versione. Controlla la dashboard o l'endpoint /v1/models per conoscere gli identificatori esatti supportati. Tra gli errori comuni ci sono l'uso di 'claude-3-opus' al posto di 'claude-opus-4-6' e l'aggiunta di spazi superflui nel valore della variabile d'ambiente.

Controlla il saldo nella dashboard. Per continuare senza interruzioni, aggiungi credito a consumo oppure passa a un piano illimitato: 1 giorno ($9) o 1 settimana ($39) per accedere a tutti i modelli a tariffa fissa, senza fatturazione per token.

# Add to ~/.bashrc or ~/.zshrc:
export ANTHROPIC_BASE_URL="https://aiprimetech.io"
export ANTHROPIC_API_KEY="your-key-from-dashboard"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# Verify connection:
# $ source ~/.bashrc && claude
# Or test the gateway directly:
# $ curl -H "x-api-key: $ANTHROPIC_API_KEY" https://aiprimetech.io/v1/models

Domande frequenti

AI Prime Tech è un gateway API indipendente. Non è affiliato ad Anthropic, non è approvato da Anthropic e non è un suo rivenditore. Claude e i nomi dei modelli correlati sono marchi dei rispettivi proprietari.