File di impostazioni e precedenza

​

File di impostazioni e chi interessano

​

Confrontare l’ambito di ogni file di impostazioni

• ~/.claude/settings.json: ogni progetto sulla tua macchina, e nulla su quella del tuo collega o nella sessione cloud
• acme-app/.claude/settings.json: il tuo acme-app/. Raggiunge il clone del tuo collega e la sessione cloud solo se esegui il commit del file nel controllo di versione; finché non lo fai, è un file sul tuo disco come qualsiasi altro e nessun altro lo ha
• acme-app/.claude/settings.local.json: solo il tuo acme-app/. Claude Code lo aggiunge alle tue esclusioni git globali la prima volta che scrive il file, quindi rimane fuori dai tuoi commit; se crei il file manualmente, aggiungilo tu stesso a .gitignore
• Impostazioni gestite, che si tratti di un file managed-settings.json, di una politica MDM o di impostazioni gestite dal server dalla console claude.ai: ogni progetto su ogni macchina a cui la tua organizzazione le distribuisce, o a cui accedi con l’account della tua organizzazione. Solo le impostazioni gestite dal server raggiungono la sessione cloud

​

Trovare o creare i tuoi file di impostazioni

• Gestito: lo distribuisce la tua organizzazione. Non lo crei né lo modifichi tu.
• Progetto condiviso: un progetto che utilizza già Claude Code potrebbe averne uno sottoposto a commit. In caso contrario, crealo in .claude/settings.json nella cartella del progetto.
• Utente e Progetto locale: creali tu stesso, oppure lascia che sia Claude Code a crearli. Scrive ~/.claude/settings.json la prima volta che modifichi un’opzione nel menu /config che memorizza nelle impostazioni utente, come il tema, e .claude/settings.local.json la prima volta che dai un’approvazione permanente a una richiesta di permesso, come “Sì, e non chiedere di nuovo” per un comando Bash. Alcune opzioni di /config, tra cui Show tips, vengono invece salvate in .claude/settings.local.json anziché nel file utente.

​

Condividere le impostazioni con il tuo team

​

Tenere le impostazioni personali fuori da un repository

• Anche Claude Code lo scrive. Quando Claude chiede il permesso di eseguire un comando Bash e scegli “Sì, e non chiedere di nuovo”, Claude Code salva qui quell’approvazione del permesso come regola allow.
• Non devi aggiungerlo tu a gitignore, a meno che tu non l’abbia creato manualmente. La prima volta che Claude Code scrive il file in un repository git che non lo ignora già, aggiunge **/.claude/settings.local.json al tuo file di esclusioni git globale, così il file rimane fuori dai tuoi commit in ogni repository. Quel file è core.excludesFile quando la tua configurazione git globale lo imposta su un percorso assoluto o con prefisso ~; altrimenti è $XDG_CONFIG_HOME/git/ignore, oppure ~/.config/git/ignore quando XDG_CONFIG_HOME non è impostato. Se hai creato il file manualmente e Claude Code non vi ha ancora scritto, aggiungilo tu stesso a .gitignore.
• Le sue regole allow non attendono l’attendibilità finché il file resta non tracciato. Poiché il file è tuo e non del repository, Claude Code applica le sue regole allow senza il passaggio di attendibilità del workspace che richiede per il file sottoposto a commit. Se il file è tracciato da git, il passaggio di attendibilità si applica anche a esso; consulta Quando il tuo file di impostazioni locali richiede l’attendibilità.

​

Dove Claude Code mantiene il file locale in un repository git

• Quando il file resta invece accanto a .claude/settings.json: fuori da un repository git, quando la radice del repository è la tua directory home, su Windows, oppure quando la radice del repository o la sua voce .git o .claude non è di proprietà del tuo utente.
• I percorsi nel file non si ancorano alla radice del repository: una regola di permesso che inizia con / o un percorso sandbox relativo si ancora invece alla directory di lavoro primaria della sessione.

​

Verificare cosa impone la tua organizzazione

• Impostazioni gestite dal server, che Claude Code recupera dalla console di amministrazione claude.ai o da un gateway Claude apps self-hosted
• Politiche MDM o a livello di sistema operativo, e file managed-settings.json in una directory di sistema
• Un host di incorporamento come Claude Desktop, tramite l’opzione managedSettings dell’SDK; consulta Controllare le politiche da un host di incorporamento

​

Modificate un’impostazione

​

Usate il menu /config

• La maggior parte delle opzioni: ~/.claude/settings.json
• Poche opzioni, come Mostra suggerimenti: .claude/settings.local.json
• Le opzioni di configurazione globale: ~/.claude.json

​

Modificate un file di impostazioni

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

​

Modificate un’impostazione per una sessione

• --settings: passate una chiave come JSON, inline o come percorso a un file. Claude Code la applica sopra i vostri file utente, progetto e locale e sotto le impostazioni gestite. Può impostare qualsiasi chiave che il vostro file di impostazioni utente può impostare; non può impostare chiavi Managed o Global config.
• Un flag per quella chiave: alcune chiavi hanno il loro flag, come --model per model e --effort per effortLevel e modelSettings.
• Una variabile di ambiente: esportate la variabile accoppiata della chiave prima di eseguire claude, come ANTHROPIC_MODEL per model.

claude --settings '{"model": "claude-opus-5-5"}'

​

Quando gli edits hanno effetto

• model: usate /model per cambiare a metà sessione. Ogni modello ha la sua cache di prompt, quindi la prima richiesta dopo un cambio rilegge l’intera conversazione senza cache; vedere Cambio di modelli
• effortLevel e modelSettings: usate /effort per modificare lo sforzo a metà sessione

​

Confermate cosa è stato caricato

​

Riparate un file di impostazioni rotto

• Errore di impostazioni: un file utente, progetto o locale ha JSON non valido o un valore che lo schema rifiuta. All’inizio di una sessione interattiva Claude Code mostra un dialogo che vi permette di riparare il file con l’aiuto di Claude, uscire, o continuare senza le impostazioni rotte.
• Avviso di impostazioni: solo le voci individuali falliscono, come una regola di permesso malformata o un nome di evento hook sconosciuto. Claude Code salta quei valori e mantiene il resto del file in vigore.
• Impostazioni gestite: Claude Code continua a applicare il resto del file. Voci non valide nelle impostazioni gestite dice cosa scarta e quali chiavi ricadono a un valore più rigoroso fino a quando non le riparate. Per un documento di impostazioni gestite che non è JSON valido, vedere Il documento delle impostazioni gestite non potrebbe essere analizzato.
• Errore di configurazione: ~/.claude.json non può essere analizzato. Claude Code copia il file rotto a ~/.claude/backups/.claude.json.corrupted.<timestamp> e chiede se uscire e ripararlo manualmente o ripristinare la configurazione predefinita; un’esecuzione -p stampa l’errore e esce. Per recuperare il vostro stato precedente, copiate indietro uno dei cinque file .claude.json.backup.<timestamp> più recenti in ~/.claude/backups/, che Claude Code salva prima di scrivere il file.

​

Precedenza delle impostazioni

1. Impostazioni gestite: impostazioni che la tua organizzazione distribuisce tramite un file managed-settings.json, una policy MDM o le impostazioni gestite dal server dalla console di claude.ai. Niente nei tuoi file di impostazioni o in --settings sovrascrive una chiave gestita, e un flag come --model sceglie solo tra i modelli che la tua organizzazione consente. Un model gestito è un valore predefinito iniziale, non un blocco; i blocchi sono availableModels e deniedModels. Quando la tua organizzazione fornisce più di una fonte gestita, le regole sulla precedenza all’interno del livello gestito indicano cosa legge Claude Code da ciascuna.
2. Riga di comando: JSON che passi con --settings <file-or-json> quando avvii claude, solo per quella sessione; consulta Modificare un’impostazione per una sola sessione. Una chiave impostata lì sovrascrive la stessa chiave nei file di impostazioni di progetto e utente, e una chiave che ometti mantiene il valore di quei file. Altri flag, come --model, impostano una sola cosa per la sessione e non fanno parte di questo stack; la voce di una chiave nel riferimento delle impostazioni indica quali flag la sovrascrivono.
3. Impostazioni locali di progetto (.claude/settings.local.json): le tue impostazioni personali per questo progetto.
4. Impostazioni di progetto condivise (.claude/settings.json): impostazioni che il tuo team inserisce nel controllo del codice sorgente.
5. Impostazioni utente (~/.claude/settings.json): le tue impostazioni personali per ogni progetto.

​

Per le liste si esegue il merge invece della sovrascrittura

• fallbackModel è una catena ordinata in cui la posizione ha un significato, quindi Claude Code prende l’intero valore dal file con la precedenza più alta che lo definisce.
• modelPicker contiene un’unica lista ordinata di righe più un flag di sostituzione, quindi Claude Code non esegue mai il merge di righe provenienti da due fonti. Prende l’intero valore dalla fonte più alta che lo definisce tra impostazioni gestite, --settings e impostazioni utente, e ignora la chiave nelle impostazioni di progetto e locali. Richiede Claude Code v2.1.242 o successiva.
• availableModels: quando le impostazioni gestite applicate da Claude Code la definiscono, Claude Code applica quella lista così com’è e ignora le voci che aggiungi nelle impostazioni utente, di progetto o locali, a meno che un’app che incorpora Claude Code fornisca la propria lista di modelli; consulta Eccezioni alla precedenza delle impostazioni gestite. Nemmeno tra fonti gestite si esegue mai il merge della lista; come Claude Code combina le fonti gestite indica quale lista di fonte si applica. Tra ambiti non gestiti Claude Code esegue il merge degli array come di consueto.
• modelSettings: Claude Code la risolve un modello alla volta, insieme a effortLevel. La voce modelSettings indica quale valore di file si applica a un modello.

​

Esempi di precedenza

​

Le impostazioni del team sovrascrivono quelle personali

​

Le impostazioni dell’organizzazione sovrascrivono tutto

​

La riga di comando sovrascrive i tuoi file per una sessione

​

Un flag o una variabile d’ambiente imposta la stessa cosa

​

Risolvere i problemi di un’impostazione che non si applica

​

Un valore che hai impostato viene ignorato

• Un livello superiore la imposta. Un altro file di impostazioni, un flag --settings o una fonte gestita imposta la chiave sopra la tua; lo stack indica quale. Anche un flag o una variabile d’ambiente può sovrascrivere la chiave da solo, secondo una decisione presa chiave per chiave; la voce della chiave nel riferimento delle impostazioni indica quale usa Claude Code, e la voce env tratta il caso di un valore env gestito rispetto a un’esportazione della shell.
• Una chiave di sicurezza mantiene il suo valore restrittivo. Per alcune chiavi Claude Code rispetta il valore restrittivo proveniente da qualsiasi file, quindi un true di progetto per disableClaudeAiConnectors resta attivo; consulta Eccezioni alla precedenza delle impostazioni gestite.
• Il file non può impostare quel valore. I valori auto e bypassPermissions di permissions.defaultMode non hanno effetto dalle impostazioni di progetto o locali; impostali invece nelle impostazioni utente o gestite, oppure passa --permission-mode per una sessione. Prima della v2.1.257, bypassPermissions aveva effetto da qualsiasi file. Nemmeno una variabile di esportazione della telemetria in un blocco env ha effetto dalle impostazioni di progetto o locali, fatta eccezione per alcuni valori di disattivazione. Variabili che Claude Code ignora in env elenca le variabili e quei valori.
• Il file è danneggiato. Un JSON non valido o un valore rifiutato fa sì che Claude Code salti il file o la voce; consulta Correggere un file di impostazioni danneggiato.

​

Una modifica fatta in Claude Code va persa nelle nuove sessioni

​

Una modifica gestita non ti ha raggiunto

​

Una chiave inserita nel repository non raggiunge i colleghi

• Claude Code ignora la chiave in un file del repository. Cerca User, local, or managed, User or managed, User, Managed o Global config nella colonna Scope dell’indice delle impostazioni. Queste chiavi non si applicano mai dal file condiviso, fatta eccezione per alcune che un file del repository può comunque disattivare. Ciascuna di queste voci lo indica nella propria riga Scope. Le chiavi Global config si applicano solo da ~/.claude.json. Anche all’interno della chiave env, le variabili di esportazione della telemetria non si applicano mai dal file condiviso, fatta eccezione per alcuni valori di disattivazione; consulta Variabili che Claude Code ignora in env.
• La chiave attende l’attendibilità. Le regole permissions.allow, permissions.additionalDirectories, extraKnownMarketplaces e la maggior parte dei valori env si applicano solo dopo che ogni collega considera attendibile la cartella. Fino ad allora continuano a vedere richieste di permesso e non ricevono plugin da un marketplace dichiarato dal file. Le regole deny e ask si applicano immediatamente.

​

Le regole di permesso si combinano diversamente da come ti aspettavi

• Hai scelto “Yes, and don’t ask again” in una richiesta di permesso ma ricevi ancora richieste per lo stesso strumento. Quella scelta ha salvato una regola allow nel tuo file locale, e una regola allow lì non ha la precedenza su una regola ask proveniente da un file di progetto o gestito; come si combinano le regole di permesso spiega l’ordine. Nell’estensione VS Code la scheda di approvazione ti permette di scegliere il file di destinazione, incluso il file condiviso del progetto, il che modifica la regola per tutti; nella CLI, Claude Code scrive solo nel tuo file locale.
• Le regole allow della tua organizzazione si applicano ancora insieme alle tue. È il comportamento previsto: Claude Code esegue il merge di permissions.allow tra gli ambiti, a meno che la tua organizzazione imposti allowManagedPermissionRulesOnly.

​

Eccezioni alla precedenza delle impostazioni gestite

​

Impostazioni nelle sessioni cloud

• Thread cloud in un progetto: in un thread cloud in un progetto, nessuna delle regole di permesso, degli hook o di env del .claude/settings.json di un repository si applica, indipendentemente da quanti repository abbia il progetto. Cosa i thread prendono dai tuoi repository elenca cosa usare al loro posto.
• Impostazioni di progetto condivise (.claude/settings.json): lette in una sessione con un repository al di fuori dei thread di un progetto, perché il file fa parte del clone e la sessione inizia al suo interno. Esegui il commit di un’impostazione lì per applicarla in quelle sessioni.
• Impostazioni di progetto condivise con più repository: in un ambiente ospitato da Anthropic, una sessione con più repository inizia sopra i clone e legge solo le chiavi enabledPlugins e extraKnownMarketplaces dal .claude/settings.json di ogni repository, non le regole di permesso, gli hook, env o altre chiavi. I marketplace e i plugin che queste due chiavi dichiarano comunque non si caricano in una sessione cloud. Per un ambiente auto-ospitato, consulta quali impostazioni del repository si applicano.
• Impostazioni utente e di progetto locale (~/.claude/settings.json e .claude/settings.local.json): non lette. Entrambe rimangono sulla vostra macchina, e il file locale non è nel clone.
• Impostazioni gestite: un file managed-settings.json o un profilo MDM sul vostro dispositivo non raggiunge una sessione cloud. Le impostazioni gestite dal server della vostra organizzazione lo fanno; la copertura della superficie elenca quali sessioni cloud le ricevono. Un ambiente auto-ospitato legge anche il file di impostazioni gestite nella sua immagine di runner. Come Claude Code combina le fonti gestite dice quando quel file si applica.
• /config: nel tuo browser su claude.ai/code, apre la pagina delle impostazioni Code o Claude Code di claude.ai invece di modificare un valore. Per modificare un’impostazione per una sessione cloud, imposta una variabile d’ambiente sull’ambiente. In una sessione con un repository al di fuori dei thread di un progetto, puoi invece eseguire il commit della chiave nel .claude/settings.json di quel repository.

​

Cosa c’è dopo

• Tutte le impostazioni: ogni chiave, con dove la impostate e un esempio
• File di impostazioni di esempio: un file personale, un file team e un file gestito di un’organizzazione
• Configura i permessi: regole allow, ask e deny, e cosa Claude Code esegue senza chiedere
• Variabili di ambiente: le variabili che Claude Code legge e il blocco env
• Debug della vostra configurazione: quando un’impostazione non si applica
• Referenza della directory Claude: ogni file che Claude Code legge, inclusi subagent, MCP server, plugin e CLAUDE.md