Vai al contenuto principale
Le variabili d’ambiente possono controllare il comportamento di Claude Code come la selezione del modello, l’autenticazione, l’instradamento delle richieste e gli interruttori di funzionalità. Molti degli stessi comportamenti possono essere configurati anche tramite un file di impostazioni, un flag CLI o un comando in-sessione come /model. Questa pagina illustra come:

Impostare variabili d’ambiente

Una variabile che imposti nella tua shell dura per quella sessione di terminale, mentre una variabile in un file di impostazioni si applica ogni volta che claude viene eseguito.

Impostare variabili nella tua shell

Imposta la variabile prima di avviare claude:
Per impostarla per ogni sessione, aggiungi la riga export a ~/.bashrc, ~/.zshrc, o al file di profilo della tua shell.
La riga di assegnazione non stampa nulla in caso di successo. Per confermare che la variabile è impostata, stampala nella stessa shell:

Impostare variabili nei file di impostazioni

Aggiungi variabili sotto la chiave env in un file settings.json, creando il file se non esiste. Claude Code le legge direttamente dal file, quindi hanno effetto indipendentemente da come claude è stato avviato. Una sessione in esecuzione applica i valori nuovi e modificati al suo ambiente quando salvi il file, ma una funzionalità che legge le sue variabili una sola volta all’avvio, come il monitoraggio OpenTelemetry, mantiene i suoi valori di avvio fino a quando non riavvii. Rimuovere una variabile dal file non la annulla in una sessione in esecuzione; la rimozione ha effetto la prossima volta che avvii claude.
~/.claude/settings.json
Claude Code copia questi valori nel suo ambiente così come sono scritti. Nessuna shell li elabora, quindi abbreviazioni come ~ o $HOME restano come digitate. Per una variabile che accetta un percorso, come CLAUDE_CONFIG_DIR, scrivi il percorso assoluto: "CLAUDE_CONFIG_DIR": "/home/you/.claude-work". Il file che scegli controlla a chi si applicano le variabili: Vedi File di impostazioni per sapere dove si trova ogni file e Precedenza delle impostazioni per come si combinano quando più di uno imposta la stessa variabile.

Precedenza

Alcuni comportamenti hanno sia una variabile d’ambiente che una chiave di impostazioni dedicata, e quale Claude Code legge per primo differisce per chiave. Per ANTHROPIC_MODEL e CLAUDE_CODE_AUTO_CONNECT_IDE, Claude Code legge prima la variabile e utilizza l’impostazione model o autoConnectIde solo quando la variabile non è impostata. Per la coppia che stai impostando, controlla la riga della variabile di seguito e la voce della chiave nel riferimento delle impostazioni. Quando la stessa variabile è impostata sia nella tua shell che in un blocco env del file di impostazioni, nella maggior parte delle sessioni si applica il valore del file di impostazioni. Claude Code scrive ogni voce env nell’ambiente del processo, sostituendo il valore ereditato dalla shell. Come i valori env interagiscono con la tua shell descrive le sessioni che mantengono invece il valore ereditato, e l’impostazione env indica quando Claude Code li applica. Alcune variabili sono trattate come casi speciali; l’impostazione env elenca le eccezioni. In un file di impostazioni puoi impostare una variabile ma non puoi rimuoverne una. Per sovrascrivere una variabile che non puoi annullare, come una CLAUDE_CODE_USE_VERTEX obsoleta esportata da un profilo di shell che non controlli, impostala su una stringa vuota nel blocco env: "CLAUDE_CODE_USE_VERTEX": "". Claude Code tratta il valore vuoto come non impostato per la selezione del provider. I sottoprocessi ereditano comunque il valore vuoto. Tra i file di impostazioni, i valori env seguono la precedenza delle impostazioni, quindi una voce di impostazioni gestite sovrascrive la stessa variabile nelle impostazioni utente o progetto. Le impostazioni di progetto e locali non possono impostare alcune variabili, come CLAUDE_CONFIG_DIR e le variabili dell’esportatore OpenTelemetry. Le variabili che Claude Code ignora in env le elenca, insieme ai valori di disattivazione di OpenTelemetry che si applicano ancora. Il modo in cui una variabile d’ambiente interagisce con i flag CLI e i comandi in-session varia per funzionalità: --model e /model sovrascrivono ANTHROPIC_MODEL, mentre CLAUDE_CODE_EFFORT_LEVEL sovrascrive --effort e /effort. Quando una variabile interagisce con un’altra fonte di configurazione, la sua riga nell’elenco Variabili dichiara la precedenza o rimanda alla pagina che la documenta. Claude Code legge le variabili d’ambiente della shell all’avvio, quindi le modifiche ad esse hanno effetto la prossima volta che avvii claude. Le variabili impostate sotto la chiave env nei file di impostazioni vengono riapplicate a una sessione in esecuzione quando il file cambia, con l’eccezione valida solo all’avvio descritta in Impostare le variabili nei file di impostazioni.

Variabili

Le variabili numeriche come timeout, budget di token e numero di nuovi tentativi accettano la notazione scientifica e le grafie con separatore di cifre oltre alle cifre semplici, tranne dove la riga di una variabile indica che accetta solo cifre semplici. Ad esempio, Claude Code legge 2e3 come 2000 e 64_000 come 64000. Prima della v2.1.211, queste grafie potevano impostare silenziosamente un valore molto più piccolo, ad esempio 1e6 impostava un timeout a 1.
Per le variabili che attivano o disattivano un comportamento, imposta 1, true, yes o on per attivarlo e 0, false, no o off per disattivarlo, con qualsiasi combinazione di maiuscole e minuscole.Alcune variabili verificano solo se le hai impostate o meno, quindi qualsiasi valore non vuoto, incluso 0, attiva il comportamento, e lo disattivi rimuovendo la variabile o impostandola su un valore vuoto. Queste variabili funzionano in questo modo:
  • CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC
  • DISABLE_TELEMETRY
  • DISABLE_ERROR_REPORTING
  • CLAUDE_CODE_TMUX_TRUECOLOR
  • IS_DEMO
Anche la riga di ciascuna variabile indica la propria regola.
Sono supportate anche le variabili standard degli exporter OpenTelemetry (OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_HEADERS, OTEL_METRIC_EXPORT_INTERVAL, OTEL_RESOURCE_ATTRIBUTES e le varianti specifiche per segnale). Consulta Monitoraggio per i dettagli di configurazione. Imposta CLAUDE_CODE_ENABLE_TELEMETRY e le variabili OpenTelemetry che attivano l’esportazione, ne scelgono la destinazione o acquisiscono contenuti nella tua shell, nelle impostazioni utente o nelle impostazioni gestite. Claude Code le ignora nelle impostazioni di progetto e locali, a parte i valori di disattivazione descritti in quella sezione. OTEL_RESOURCE_ATTRIBUTES e le variabili per intervallo di esportazione, timeout e compressione, come OTEL_METRIC_EXPORT_INTERVAL, si applicano comunque dalle impostazioni di progetto e locali.

Cosa rimuove la pulizia dell’ambiente dei sottoprocessi

Quando imposti CLAUDE_CODE_SUBPROCESS_ENV_SCRUB su 1, Claude Code rimuove le credenziali dagli ambienti dei sottoprocessi che avvia, come i comandi Bash, gli hook e i server MCP stdio. Questo riduce ciò che un attacco di prompt injection può leggere. Il processo di Claude Code mantiene le credenziali per le proprie chiamate API. La pulizia riconosce una credenziale dal nome della variabile o dalla forma del suo valore, quindi usala come un livello insieme a regole di permesso ristrette, anziché come unico controllo. La tabella mostra cosa fa la pulizia con alcune variabili di esempio: Poiché la pulizia lascia invariato GITHUB_TOKEN, assegna a un job di GitHub Actions i permissions più ristretti di cui ha bisogno. Per rimuovere un token GitHub dai comandi Bash eseguiti in sandbox, aggiungi una voce deny in sandbox.credentials. Lascia la pulizia non impostata se un sottoprocesso ha bisogno di una delle variabili rimosse. Su Linux, la pulizia esegue inoltre i sottoprocessi Bash in un namespace PID isolato, in modo che non possano leggere gli ambienti dei processi host tramite /proc. Come effetto collaterale, ps, pgrep e kill non possono vedere i processi host né inviare loro segnali. Prima della v2.1.251, la pulizia rimuoveva ANTHROPIC_API_KEY e AWS_SECRET_ACCESS_KEY e lasciava invariate le altre variabili di esempio della tabella.

Funzionalità che richiedono il recupero dei feature flag

Claude Code attiva alcune funzionalità tramite feature flag che recupera da Anthropic. Claude Code salta questo recupero nelle seguenti sessioni:
  • Una sessione in cui imposti CLAUDE_CODE_DISABLE_FEATURE_FLAGS, DISABLE_TELEMETRY, DO_NOT_TRACK o CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC; la riga di ciascuna variabile nella tabella delle variabili indica quali valori disattivano il recupero
  • Una sessione su un provider di terze parti, come Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform o Microsoft Foundry, a meno che una piattaforma host che incorpora Claude Code non imposti CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST
  • Una sessione del gateway delle app Claude
Con il recupero disattivato, non puoi:

Prima sessione dopo un’installazione o un aggiornamento

Nella prima sessione dopo aver installato Claude Code, o dopo aver eseguito l’aggiornamento a una versione che aggiunge una funzionalità, una funzionalità controllata da flag può mancare. Quando Claude Code recupera i flag durante quella sessione, li salva sulla macchina, quindi la sessione successiva su quella macchina dispone della funzionalità. In configurazioni come queste, anche le sessioni successive alla prima si avviano senza flag recuperati di recente:
  • Un ambiente pulito a ogni esecuzione: se ogni esecuzione parte in un container CI, o in qualsiasi altro ambiente privo dei flag salvati da una sessione precedente, ogni esecuzione è una prima sessione
  • Un token del gateway senza chiave API: se ti autentichi con ANTHROPIC_AUTH_TOKEN e nessuna chiave API, e ANTHROPIC_BASE_URL punta a un host diverso da quello di Anthropic, come un gateway LLM, Claude Code non dispone di credenziali con cui recuperare i flag

Vedi anche