Claude Code settings.json e variabili d’ambiente: URL di base, token di autenticazione e modello

Claude Code legge la configurazione dai file di impostazioni JSON e dalle variabili d’ambiente. Per usarlo tramite un gateway anziché tramite l’API di Anthropic, servono due variabili, ANTHROPIC_BASE_URL e un token, e in genere anche un modello. Le variabili sono semplici. A confondere è dove inserirle, perché la stessa variabile può trovarsi nel profilo della shell, in diversi file settings.json e nelle impostazioni di VS Code.

Questa guida parte da una configurazione funzionante, poi spiega dove si trovano i file, quale valore prevale e quali errori è probabile incontrare. È stata verificata rispetto alla documentazione di Anthropic e testata con AIHubMix su Claude Code 2.1.304 il 20 ottobre 2026. Gli esempi usano AIHubMix come gateway; qualsiasi endpoint compatibile con Anthropic si configura allo stesso modo.

In breve

• Il tuo file personale delle impostazioni è ~/.claude/settings.json, oppure %USERPROFILE%\.claude\settings.json su Windows.
• Per un gateway, inserisci ANTHROPIC_BASE_URL (senza /v1) e ANTHROPIC_AUTH_TOKEN nel blocco env di quel file.
• Un valore nel blocco env di un file delle impostazioni prevale sulla stessa variabile esportata nella shell.
• Una volta impostato un token, le richieste non usano più il tuo abbonamento Claude e vengono addebitate dal gateway.
• L’estensione di VS Code richiede le stesse variabili nella propria impostazione claudeCode.environmentVariables.

Una configurazione AIHubMix funzionante

1. Crea una chiave nella console AIHubMix.
2. Inserisci questo contenuto in ~/.claude/settings.json. Se il file non esiste, crealo.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-aihubmix-key"
  },
  "model": "claude-sonnet-5-5"
}

3. Esegui un rapido test:

claude -p "1+1, output only the answer"

4. Avvia claude in un progetto. Nell’intestazione sotto il logo dovrebbe apparire qualcosa come Sonnet 5.5 · API Usage Billing, mentre /status mostra il gateway sulla riga Anthropic base URL.

Due dettagli sono importanti. L’URL di base è l’indirizzo principale: Claude Code aggiunge autonomamente /v1/messages, quindi un URL che termina in /v1 compromette tutte le richieste. Inoltre, AIHubMix usa gli ID dei modelli di Anthropic, come claude-sonnet-5-5, quindi le scorciatoie sonnet, opus e haiku funzionano senza configurazioni aggiuntive.

La riga $schema è facoltativa. Permette a VS Code, Cursor e altri editor di segnalare gli errori nel file mentre digiti.

Puoi anche esportare le stesse due variabili nella shell, ma è meglio inserirle in un file delle impostazioni: lo leggono tutti i terminali, le estensioni dell’IDE e gli agenti in background.

Dove si trovano i file delle impostazioni

Non inserire mai un token nel file .claude/settings.json del progetto, perché viene incluso nei commit git. Usa il tuo file utente o .claude/settings.local.json.

I file delle impostazioni devono essere JSON validi. Un commento // o una virgola finale fa sì che Claude Code ignori l’intero file, token compreso, e mostri la schermata di accesso invece del gateway.

Non confonderli con ~/.claude.json, un singolo file nella cartella home. Questo memorizza lo stato interno di Claude Code, come l’accesso e i server MCP, e di rado è necessario modificarlo.

Quale valore prevale

Quando più file impostano lo stesso valore, si applica la precedenza delle impostazioni di Anthropic, in ordine decrescente:

1. Impostazioni gestite dalla tua organizzazione
2. --settings dalla riga di comando, solo per la sessione corrente
3. .claude/settings.local.json
4. .claude/settings.json
5. ~/.claude/settings.json

Per le variabili d’ambiente c’è un’altra regola: una variabile nel blocco env di un file delle impostazioni sovrascrive la stessa variabile proveniente dalla shell. Quindi un export ANTHROPIC_BASE_URL=... in ~/.zshrc non ha effetto se la variabile è impostata anche in un file delle impostazioni. Gli strumenti per cambiare provider in genere scrivono in ~/.claude/settings.json, ed è per questo che prevalgono sulla shell.

In Claude Code, /status elenca i file caricati nella riga Setting sources.

ANTHROPIC_AUTH_TOKEN o ANTHROPIC_API_KEY

Usa la variabile letta dal tuo gateway. AIHubMix accetta entrambe, e la sua guida a Claude Code usa ANTHROPIC_AUTH_TOKEN, che è anche la scelta più semplice. Non lasciarle impostate entrambe. Claude Code invierebbe entrambi gli header e AIHubMix controlla prima x-api-key: nel nostro test, una chiave valida in settings.json ha comunque restituito un errore 401 perché nella shell era esportata una vecchia ANTHROPIC_API_KEY. Il blocco env sovrascrive solo le variabili che imposta, quindi quando cambi configurazione rimuovi la vecchia chiave dal profilo della shell.

Che succede al tuo abbonamento Claude? Secondo la guida di Anthropic ai gateway, una volta impostata una variabile token o API key, le richieste la usano al posto dell’accesso a claude.ai e il gateway addebita i costi per token. Le credenziali restano salvate e tornano in uso quando rimuovi la variabile. Se imposti solo ANTHROPIC_BASE_URL, senza un token, continui a usare il tuo abbonamento.

Scegliere il modello

La pagina di Anthropic sulla configurazione dei modelli indica questo ordine, dal più prioritario:

1. /model <name> durante una sessione
2. claude --model <name> all’avvio
3. La variabile ANTHROPIC_MODEL
4. La chiave model in un file delle impostazioni

/model salva la tua scelta come nuovo valore predefinito. Se però è impostata ANTHROPIC_MODEL, ogni nuova sessione si avvia di nuovo con quel modello. Se cambi spesso modello, imposta la chiave model e non impostare ANTHROPIC_MODEL. Se non imposti un modello da nessuna parte, Claude Code usa Opus 5.5.

ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL e ANTHROPIC_DEFAULT_HAIKU_MODEL cambiano il modello associato a ciascuna scorciatoia. Ti servono solo se vuoi che una scorciatoia punti a un altro modello, ad esempio per mantenere sonnet su una versione precedente.

AIHubMix offre anche modelli di altri fornitori allo stesso indirizzo, ma Anthropic non supporta Claude Code con modelli non-Claude, quindi alcune funzionalità potrebbero non funzionare.

Quando hanno effetto le modifiche

Claude Code monitora i file delle impostazioni e la maggior parte delle modifiche salvate, compreso il blocco env, si applica alla sessione in corso. La chiave model, le variabili rimosse e le esportazioni della shell richiedono un riavvio. In caso di dubbio, riavvia Claude Code.

L’estensione di VS Code

L’estensione legge gli stessi file delle impostazioni, ma prima dell’avvio verifica l’accesso tramite la propria impostazione claudeCode.environmentVariables. Ecco perché VS Code può chiederti di accedere anche se la CLI funziona. Apri Preferences: Open User Settings (JSON) dalla Command Palette e aggiungi:

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://aihubmix.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-your-aihubmix-key" }
  ]
}

Poi esegui Developer: Reload Window. Per altre opzioni, consulta la documentazione di Anthropic per VS Code. L’app Claude Desktop è separata: non legge né settings.json né queste variabili.

Altre variabili utili

Puoi inserirle tutte nel blocco env. L’elenco completo si trova nel riferimento alle variabili d’ambiente di Anthropic.

Errori comuni e relativo significato

Not logged in · Please run /login, oppure la schermata di accesso al primo avvio
Claude Code non ha trovato un token. Controlla tre cose: un errore JSON che gli ha fatto ignorare il file, l’assenza di ANTHROPIC_AUTH_TOKEN oppure un token presente solo in un file del progetto. La procedura di accesso viene eseguita prima che vengano caricate le impostazioni del progetto, quindi sposta il token in ~/.claude/settings.json.

Invalid or malformed JSON
Il file indicato nel messaggio contiene un commento, una virgola finale o un altro errore di sintassi, quindi nessuna delle sue impostazioni è stata applicata.

There's an issue with the selected model (...)
L’ID del modello è errato oppure l’URL di base termina in /v1 e la richiesta è stata inviata a /v1/v1/messages. Se l’ID del modello sembra corretto, controlla prima l’URL.

API Error: 400 con This model ID is incorrect
AIHubMix non dispone di un modello con quell’ID e il messaggio ripete l’ID ricevuto. Di solito si tratta di un errore di battitura. Copia di nuovo l’ID dall’elenco dei modelli AIHubMix.

Failed to authenticate. API Error: 401 invalid key: ...
AIHubMix non accetta la chiave. Il messaggio termina con gli ultimi sei caratteri della chiave ricevuta: confrontali con la fine del tuo token. PI_KEY significa che al posto di una chiave reale è stato incollato il segnaposto AIHUBMIX_API_KEY. In tutti gli altri casi, di solito è stata inviata una vecchia ANTHROPIC_API_KEY dalla shell. Se invece il messaggio dice this key is not enabled, verifica nella console AIHubMix che la chiave sia abilitata e disponga di credito.

auth may not work as expected
Sono attivi sia una variabile token sia un accesso salvato a claude.ai. Esegui /logout per continuare a usare il gateway, oppure rimuovi la variabile per tornare al tuo abbonamento.

Claude Code doesn't recognize the model ...
È un avviso, non un errore: la richiesta viene comunque inviata, ma Claude Code presume una finestra di contesto da 200K token. Se l’ID appartiene a un modello Claude più recente, claude update risolve il problema.

Con una chiave non valida, sembra bloccarsi
Claude Code riprova le richieste non riuscite fino a 10 volte. In un test con una chiave che non funzionava mai, claude -p ha continuato a riprovare per circa tre minuti. Riduci CLAUDE_CODE_MAX_RETRIES per visualizzare prima l’errore.

Se vuoi usare una sola chiave per Claude in Claude Code e per OpenAI, Google e altri fornitori negli altri strumenti, AIHubMix rende disponibile l’API Anthropic all’indirizzo https://aihubmix.com. A Claude Code basta il file delle impostazioni qui sopra.

Domande frequenti

Dove si trova settings.json di Claude Code?
Il tuo file personale è ~/.claude/settings.json, oppure %USERPROFILE%.claude\settings.json su Windows. Un progetto può avere anche .claude/settings.json, condiviso tramite git, e .claude/settings.local.json, riservato a te. Claude Code non li crea durante l’installazione.

settings.json ha la precedenza sulle variabili d’ambiente?
Sì. Un valore nel blocco env di un file di impostazioni sovrascrive la stessa variabile esportata nella shell. Le variabili che il file non imposta, come una vecchia ANTHROPIC_API_KEY, continuano a provenire dalla shell.

È meglio usare ANTHROPIC_AUTH_TOKEN o ANTHROPIC_API_KEY?
Usa quella letta dal tuo gateway. ANTHROPIC_AUTH_TOKEN invia un token Bearer e non richiede approvazione. Per AIHubMix, ANTHROPIC_AUTH_TOKEN è la scelta documentata. Non impostarle entrambe: AIHubMix legge prima x-api-key, quindi una ANTHROPIC_API_KEY obsoleta causa un errore 401.

ANTHROPIC_BASE_URL deve terminare con /v1?
No. Claude Code aggiunge /v1/messages autonomamente. Per AIHubMix, usa https://aihubmix.com.

Devo riavviare Claude Code dopo aver modificato settings.json?
La maggior parte delle modifiche, incluse quelle alle variabili d’ambiente, viene applicata al salvataggio. La chiave del modello e le esportazioni nella shell richiedono un riavvio. Riavviare è la scelta più sicura.

Perché VS Code mi chiede di accedere se la CLI funziona?
Prima di avviarsi, l’estensione controlla che sia stato effettuato l’accesso tramite l’impostazione claudeCode.environmentVariables, e i valori in ~/.claude/settings.json non sono disponibili per questo controllo. Aggiungi lì l’URL di base e il token, poi ricarica la finestra.

Impostare ANTHROPIC_BASE_URL utilizza il mio abbonamento Claude?
Solo se non è impostato alcun token. Se ANTHROPIC_AUTH_TOKEN o ANTHROPIC_API_KEY è impostato, le richieste usano quella chiave e il gateway applica una tariffa per token.

Fonti

• File di impostazioni e precedenza, Anthropic
• Variabili d’ambiente, Anthropic
• Connettere Claude Code a un gateway LLM, Anthropic
• Configurazione del modello, Anthropic
• Guida all’integrazione di Claude Code, AIHubMix