Passa al contenuto principale

settings.json: il sistema di configurazione

Intermedio

settings.json è dove risiede la configurazione di Claude Code — permessi, hook, variabili d'ambiente, valori predefiniti del modello e altro. Capire i livelli è la chiave.

What you'll learn
  • Lo stack di precedenza a cinque livelli, e quale file vince quando due di essi impostano la stessa chiave
  • Perché le variabili d'ambiente non sono un livello, e cosa significa per ANTHROPIC_MODEL
  • In quale file mettere un'impostazione: convenzione di team versionata, override personale o esperimento di una sola sessione
  • Le quattro sezioni che modificherai davvero, e dove ciascuna è documentata in profondità
  • Come modificare senza rompere il file, e cosa non deve mai finire in un file di impostazioni versionato

I livelli (dal più alto per precedenza)​

Quando la stessa chiave è impostata in più punti, Claude Code usa il valore del livello più alto che la imposta:

Guided walkthrough1 of 5
  1. managed-settings.json, una policy MDM o le impostazioni gestite dal server dalla console claude.ai. Nulla di ciò che imposti le sovrascrive (salvo alcune eccezioni sensibili per la sicurezza).
Le variabili d'ambiente non sono un livello

Stanno fuori da questo stack e si risolvono chiave per chiave. Ad esempio ANTHROPIC_MODEL prevale sulla chiave model di qualsiasi file, mentre ANTHROPIC_DEFAULT_MODEL si applica solo quando nessun file imposta model.

Committa il file condiviso, ignora quello locale

Metti le convenzioni di team in .claude/settings.json (sotto controllo di versione). Metti gli aggiustamenti personali e i percorsi specifici della macchina in .claude/settings.local.json (escluso da git). Questo mantiene il team coerente senza imporre le tue preferenze agli altri.

Cosa imposterai comunemente​

  • permissions — regole allow/ask/deny. Vedi Permessi.
  • hooks — comandi che vengono eseguiti in corrispondenza di eventi del ciclo di vita. Vedi Hook.
  • env — variabili d'ambiente per la sessione.
  • Valori predefiniti di modello / comportamento — ad esempio il modello preferito.

Modificare in sicurezza​

  • Mantieni un JSON valido (una virgola finale lo rompe).
  • Preferisci regole di permesso ristrette a quelle ampie.
  • Non mettere mai segreti in un file sotto controllo di versione — usa riferimenti env o un gestore di segreti.

Prova un'impostazione per una sola sessione senza scriverla in nessun file

claude --settings '{"permissions":{"allow":["Bash(git log *)"]}}'

File di partenza pronti da copiare si trovano in Ricette per hook e settings.json. Quando un file è malformato o una chiave non fa ciò che ti aspetti, claude doctor stampa gli errori di validazione dei file di impostazioni senza avviare una sessione — vedi la pagina sulla CLI per questo e per --safe-mode.

Verifica te stesso​

Check yourself

0/3
  1. Il file .claude/settings.json versionato nel tuo repository imposta un modello, e il tuo ~/.claude/settings.json ne imposta uno diverso. Quale si applica?
  2. Dove va messo un percorso assoluto specifico della macchina?
  3. Quale affermazione sulle variabili d'ambiente è corretta?
Key takeaways
  • Cinque livelli, una regola: vince il livello più alto che imposta una chiave. Il gestito è assoluto; le impostazioni utente sono le più deboli.
  • File versionato per le convenzioni di team, file locale per i valori personali e specifici della macchina, --settings per un esperimento usa e getta.
  • Le variabili d'ambiente non sono un livello. Controlla la regola di ciascuna variabile invece di presumere una posizione nello stack.
  • I segreti non vanno mai in un file di impostazioni versionato.
  • Quando un'impostazione sembra ignorata, esegui claude doctor per gli errori di validazione prima di cambiare altro.

Avanti​