Modifica le impostazioni di Claude Code, scegli l'ambito a cui appartiene una chiave, verifica la modifica e scopri quale valore Claude Code utilizza quando una chiave è impostata in più posizioni.
export const SettingsPrecedence = () => {
const LEVELS = [{
n: 1,
name: 'Managed settings',
file: 'managed-settings.json, MDM, or the claude.ai console',
who: 'Your organization',
w: 390
}, {
n: 2,
name: 'Command line',
file: 'claude --settings',
who: 'You, this session',
w: 420
}, {
n: 3,
name: 'Project local',
file: '.claude/settings.local.json',
who: 'You, this project',
w: 480
}, {
n: 4,
name: 'Shared project',
file: '.claude/settings.json',
who: 'Everyone in the project',
w: 540
}, {
n: 5,
name: 'User',
file: '~/.claude/settings.json',
who: 'You, every project',
w: 600
}];
const W = 760;
const ROW = 58;
const GAP = 8;
const TOP = 34;
const H = TOP + LEVELS.length * (ROW + GAP) + 30;
const cx = W / 2;
const mono = 'var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace)';
const sans = 'var(--font-sans, system-ui, -apple-system, sans-serif)';
return
Le impostazioni sono le chiavi JSON che modificano il comportamento di Claude Code: quale modello avvia, cosa può eseguire senza chiedere, quali file non può leggere, come appare nel vostro terminale e cosa la vostra organizzazione applica.
Claude Code legge le impostazioni da file di impostazioni JSON come ~/.claude/settings.json. Le cerca in pochi percorsi, e il file da cui legge un'impostazione decide a chi si applica. Questa pagina copre quei file: quale usare per un'impostazione, come modificare un'impostazione e confermare che è stata applicata, e quale valore Claude Code utilizza quando la stessa chiave è impostata in più di un file. Configura i permessi copre cosa Claude Code può eseguire senza chiedere e come scrivere regole allow, ask e deny.
File di impostazioni e chi interessano
Claude Code legge le impostazioni da quattro file, e un'organizzazione può anche fornire impostazioni gestite dalla console claude.ai. Ogni fonte ha un ambito: l'insieme di persone e progetti a cui si applica un'impostazione salvata in essa, che sia solo voi, tutti in un progetto, o tutti nella vostra organizzazione.
Ambito
File
Chi interessa
Usarlo per
Utente
~/.claude/settings.json
Voi, in ogni progetto su questa macchina
Preferenze personali: tema, modalità editor, modello predefinito, vostre regole di autorizzazione personali
Progetto condiviso
.claude/settings.json
Tutti coloro che lavorano nella cartella che lo contiene. In un repository git, eseguite il commit in modo che i vostri colleghi lo ottengano
Autorizzazioni del team, hooks, plugins, e le variabili di ambiente di cui il progetto ha bisogno
Progetto locale
.claude/settings.local.json
Voi, in questo solo progetto. Claude Code lo mantiene fuori da git quando crea il file; se lo create manualmente, aggiungetelo a .gitignore voi stessi
Override personali per un progetto, e test prima di condividere
Tutti coloro a cui la vostra organizzazione lo distribuisce; nulla di quello che impostate lo sostituisce, a parte poche eccezioni sensibili alla sicurezza
Requisiti di politica di sicurezza e conformità
Nella colonna File, ~/.claude è la cartella .claude nella vostra home directory, e un .claude semplice è la cartella .claude all'interno del vostro progetto.
Confrontare l'ambito di ogni file di impostazioni
Supponiamo che abbiate tre progetti sulla vostra macchina, website/, api/, e acme-app/, un vostro collega ha il suo clone di acme-app/, e avviate una sessione cloud su acme-app/.
Il grafico sottostante mostra in quali di quelle cartelle si applica un'impostazione quando avviate Claude Code da esse. Fate clic su un file di impostazioni per vedere le cartelle che raggiunge.
~/.claude/settings.json: ogni progetto sulla vostra macchina, e nulla su quella del vostro collega o nella sessione cloud
acme-app/.claude/settings.json: il vostro acme-app/. Raggiunge il clone del vostro collega e la sessione cloud solo se eseguite il commit del file nel controllo di versione; fino a quando non lo fate, è un file sul vostro disco come qualsiasi altro e nessun altro lo ha
acme-app/.claude/settings.local.json: il vostro acme-app/ solo. Claude Code lo aggiunge alle vostre esclusioni git globali la prima volta che scrive il file, quindi rimane fuori dai vostri commit; se create il file manualmente, aggiungetelo a .gitignore voi stessi
Impostazioni gestite, che sia un file managed-settings.json, una politica MDM, o impostazioni gestite dal server dalla console claude.ai: ogni progetto su ogni macchina a cui la vostra organizzazione lo distribuisce, o a cui accedete con il vostro account organizzativo. Solo le impostazioni gestite dal server raggiungono la sessione cloud
Trovare o creare i vostri file di impostazioni
L'installazione di Claude Code non crea alcun file di impostazioni. Se la vostra macchina o il vostro progetto ne ha già uno, è venuto da una di queste fonti:
Gestito: la vostra organizzazione lo distribuisce. Non lo create o modificate.
Progetto condiviso: un progetto che già utilizza Claude Code potrebbe averne uno sottoposto a commit. Se no, createlo in .claude/settings.json nella cartella del progetto.
Utente e Progetto locale: createli voi stessi, o lasciate che Claude Code li crei. Scrive ~/.claude/settings.json la prima volta che cambiate un'opzione nel menu /config che memorizza nelle impostazioni utente, come il tema, e .claude/settings.local.json la prima volta che date un'approvazione permanente su un prompt di autorizzazione, come "Sì, e non chiedere di nuovo" per un comando Bash. Poche opzioni /config, incluso Show tips, vengono salvate in .claude/settings.local.json invece che nel file utente.
Claude Code mantiene anche un quinto file, ~/.claude.json, che scrive per se stesso; non dovete modificarlo. Contiene la vostra sessione di accesso, configurazioni MCP server, stato per progetto come decisioni di fiducia, e le chiavi di configurazione globale che /config scrive per voi.
Condividere le impostazioni con il vostro team
Eseguite il commit di .claude/settings.json in modo che tutti coloro che clonano il repository ottengano le stesse autorizzazioni, hooks, e plugins. Ogni collega può comunque sostituirlo per se stesso nel proprio .claude/settings.local.json, quindi le eccezioni personali non hanno bisogno di un commit. Per un file team completo, vedete le impostazioni condivise di un team.
Mantenere le impostazioni personali fuori da un repository
Per cambiare un'impostazione per voi stessi in un progetto senza cambiarla per i vostri colleghi, salvatela in .claude/settings.local.json all'interno del progetto. Claude Code applica quel file sopra il .claude/settings.json sottoposto a commit, quindi se il file del vostro team imposta "model": "claude-sonnet-5" e volete Opus, mettete "model": "claude-opus-5-5" nel vostro file locale e solo le vostre sessioni cambiano.
Claude Code scrive anche in questo file, lo mantiene fuori dai vostri commit, e applica le sue regole di autorizzazione senza il passaggio di fiducia:
Claude Code lo scrive anche. Quando Claude chiede il permesso di eseguire un comando Bash e scegliete "Sì, e non chiedere di nuovo", Claude Code salva quella approvazione di autorizzazione qui come una regola allow.
Non dovete gitignore voi stessi, a meno che non l'abbiate 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 vostro file di esclusioni git globale, quindi il file rimane fuori dai vostri commit in ogni repository. Quel file è core.excludesFile quando la vostra configurazione git globale lo imposta su un percorso assoluto o con prefisso ~; altrimenti è $XDG_CONFIG_HOME/git/ignore, o ~/.config/git/ignore quando XDG_CONFIG_HOME non è impostato. Se avete creato il file manualmente e Claude Code non ha ancora scritto in esso, aggiungetelo a .gitignore voi stessi.
Le sue regole di autorizzazione non attendono la fiducia mentre il file rimane non tracciato. Poiché il file è vostro e non del repository, Claude Code applica le sue regole allow senza il passaggio workspace trust che richiede per il file sottoposto a commit. Se il file è tracciato da git, il passaggio di fiducia si applica anche ad esso; vedete When your local settings file needs trust.
Dove Claude Code mantiene il file locale in un repository git
Quando Claude chiede il permesso di eseguire un comando Bash e scegliete "Sì, e non chiedere di nuovo", Claude Code salva quella approvazione come una regola allow in .claude/settings.local.json. Se avviate Claude Code in una sottodirectory di un repository git, legge e scrive quel file alla radice del repository e applica l'approvazione in tutto il repository. In un worktree, utilizza il file alla radice del checkout principale.
Due regole qualificano la posizione della radice:
Quando il file rimane con .claude/settings.json invece: fuori da un repository git, quando la radice del repository è la vostra home directory, su Windows, o quando la radice del repository o la sua voce .git o .claude non è di proprietà del vostro utente.
Prima della v2.1.211, Claude Code manteneva il file nella directory di avvio. Legge ancora un file che una versione precedente ha lasciato lì accanto al file radice; dove entrambi impostano la stessa chiave, il valore della radice si applica, e le regole di autorizzazione da entrambi i file si applicano. L'helper resolveSettings() dell'Agent SDK legge sempre il file dalla directory di avvio.
Claude Code legge il .claude/settings.json condiviso dalla directory di lavoro primaria della sessione, quindi per utilizzare un file sottoposto a commit alla radice del repository, avviate Claude Code lì. Dopo aver spostato la sessione con /cd, Claude Code legge entrambi i file del progetto dalla nuova directory invece, posizionando il file locale secondo le stesse regole. Leggerli dalla directory in cui vi siete spostati richiede Claude Code v2.1.246 o successivo.
Verificare cosa la vostra organizzazione applica
Se la vostra organizzazione gestisce Claude Code, alcune impostazioni sono decise per voi e nulla di quello che mettete nei vostri file cambia loro. Per vedere quali, eseguite /status: la riga Setting sources nomina la fonte gestita che si applica a voi. Le impostazioni gestite si applicano ovunque Claude Code funzioni su questa macchina; What a developer can change copre i diritti di amministratore locale e gli strumenti diversi da Claude Code.
Le impostazioni gestite vi raggiungono attraverso i delivery mechanisms sulla pagina delle impostazioni gestite, più comunemente:
In una sessione Cowork che funziona sulla vostra macchina nell'app Claude Desktop, Claude Code non recupera le impostazioni gestite dal server dalla console di amministrazione claude.ai, e legge la politica distribuita al vostro dispositivo a meno che la configurazione Claude Desktop della vostra organizzazione non imposti requireCoworkFullVmSandbox. Where and when a policy applies copre Cowork e le sessioni cloud.
Potete modificare un'impostazione dal menu /config, modificando un file di impostazioni, o per una sessione dalla riga di comando.
Il prompt di sistema di Claude Code non è pubblicato. Per dare a Claude istruzioni permanenti, usate i file CLAUDE.md o il flag --append-system-prompt.
Usate il menu /config
Eseguite /config dentro Claude Code e aprite la scheda Config. Elenca un breve insieme di opzioni personali come tema, modalità editor e output dettagliato, non ogni chiave di impostazioni. Selezionate un'opzione per modificarla; Claude Code la salva per voi:
La maggior parte delle opzioni: ~/.claude/settings.json
Poche opzioni, come Mostra suggerimenti: .claude/settings.local.json
Per impostare un'opzione senza il menu, passate key=value, come /config verbose=true.
Modificate un file di impostazioni
Aprite il file di impostazioni per l'ambito che volete nel vostro editor e aggiungete o modificate una chiave. I file di impostazioni sono JSON rigoroso: un commento // o una virgola finale è un errore di sintassi, e Claude Code segnala il file come un Errore di impostazioni al prossimo avvio. Ad esempio, per permettere a Claude Code di eseguire i vostri comandi lint e test senza chiedere e impedirgli di leggere file .env, aggiungete questo a ~/.claude/settings.json:
{"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {"allow": ["Bash(npm run lint)",
"Bash(npm run test *)"],
"deny": ["Read(./.env)",
"Read(./.env.*)"]}}
Ogni voce sotto permissions è una regola che nomina uno strumento e cosa può fare; Configura i permessi spiega la sintassi. La riga $schema punta allo schema JSON pubblicato per le impostazioni di Claude Code, che vi dà l'autocompletamento e la convalida inline in VS Code, Cursor e qualsiasi altro editor che supporta lo schema JSON. Lo schema può rimanere indietro rispetto ai rilasci CLI più recenti, quindi un avviso di convalida su una chiave documentata di recente non significa che la vostra configurazione non sia valida.
Dopo aver salvato, eseguite /status dentro Claude Code per confermare che il file è stato caricato; Conferma cosa è stato caricato dice cosa mostra la riga Setting sources e come un file rotto è segnalato.
Per un file personale completo, file team e file organizzativo, ognuno mostrato con un commento su ogni chiave che imposta, vedere i file di impostazioni di esempio.
Modificate un'impostazione per una sessione
Per provare un valore senza salvarlo, impostatelo quando avviate Claude Code. Il valore si applica a quella sessione e i vostri file di impostazioni rimangono come erano. Avete tre modi per farlo:
--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.
Ogni voce della chiave sulla referenza delle impostazioni elenca i suoi override per-sessione e quale ha la precedenza, quindi controllate la voce per la chiave che volete modificare.
I comandi che eseguite dentro una sessione per lo più salvano la vostra scelta: quando modificate un'impostazione in /config, Claude Code la scrive nei vostri file di impostazioni, e /model salva il valore come vostro predefinito per le nuove sessioni.
Se premete s nel selettore /model, Claude Code cambia il modello senza salvarlo come vostro predefinito utente. Regola il livello di sforzo dice quali /effort Claude Code salva come vostro predefinito per il modello che state usando e quali si applicano solo alla sessione corrente.
Ad esempio, per avviare una sessione su Opus senza modificare il vostro predefinito:
claude --settings'{"model": "claude-opus-5-5"}'
Quando gli edits hanno effetto
Claude Code osserva i vostri file di impostazioni e li ricarica quando cambiano, quindi applica la maggior parte degli edits alla sessione in esecuzione senza un riavvio, inclusi gli edits a permissions, hooks e helper di credenziali come apiKeyHelper. Claude Code anche carica un file di impostazioni che create a metà sessione se la sua cartella esisteva quando la sessione è iniziata. Per la cartella .claude/ del progetto, carica il file anche quando create la cartella nella stessa sessione.
Il ricaricamento copre le impostazioni utente, progetto, locale e gestite, e Claude Code esegue l'hook ConfigChange per ogni modifica di file di impostazioni che rileva, non per le impostazioni gestite che arrivano da MDM o dalla console claude.ai. Le impostazioni gestite che arrivano attraverso MDM o dalla console claude.ai raggiungono una sessione in esecuzione secondo una pianificazione piuttosto che al salvataggio; la tabella di consegna la fornisce per fonte.
Claude Code legge alcune chiavi solo una volta, all'avvio della sessione, quindi un edit a una di esse non raggiunge la sessione in esecuzione. Le chiavi lato amministratore che attendono anche un riavvio, come requiredMinimumVersion, sono elencate sotto dove e quando si applica una politica. Quelle che è più probabile che modifichiate a metà sessione:
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
Eseguite /status dentro Claude Code per vedere quali fonti di impostazioni sono attive. La scheda Status include una riga Setting sources che elenca ogni file di impostazioni che Claude Code ha caricato per la sessione corrente, come User settings o Project local settings. Quando le impostazioni gestite sono in vigore, la voce delle impostazioni gestite mostra tra parentesi come hanno raggiunto la vostra macchina.
La riga conferma quali file Claude Code ha letto; non mostra quale file ha fornito ogni chiave. Per elencare le voci che Claude Code ha rifiutato, eseguite claude doctor; per un modello che le impostazioni di progetto o gestite impostano, l'intestazione di avvio nomina il file che lo ha impostato. /status e /config aprono lo stesso dialogo su schede diverse, e la scheda Config non è una visualizzazione dei contenuti del vostro settings.json.
Riparate un file di impostazioni rotto
Se digitate male JSON o impostate una chiave a un valore che Claude Code non accetta, Claude Code ve lo dice all'inizio di una sessione interattiva. Quello che mostra dipende da quanto del file è interessato:
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.
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.
Dopo aver continuato, eseguite /status per vedere i file interessati e claude doctor per i dettagli di ogni errore.
Un'esecuzione -p non mostra dialogo. A meno che un documento di impostazioni gestite non possa essere analizzato, Claude Code salta il file rotto o i valori e continua con il resto, quindi dopo un'esecuzione -p che ignora un'impostazione, eseguite claude doctor per vedere cosa ha scartato.
Precedenza delle impostazioni
Quando la stessa chiave appare in più di un posto, Claude Code utilizza il valore dal livello più alto che la imposta. Lo stack sottostante mostra i livelli, il più alto in alto; una chiave a un livello più alto sostituisce la stessa chiave ovunque al di sotto.
In ordine, dalla precedenza più alta in primo luogo:
Impostazioni gestite: impostazioni che la tua organizzazione distribuisce, tramite un file managed-settings.json, una policy MDM, o impostazioni gestite dal server dalla console claude.ai. Nulla di quello che imposti le sostituisce: una chiave che passi con --settings non sostituisce la stessa chiave gestita, e un flag come --model sceglie solo dai modelli che la tua organizzazione consente. Un model gestito imposta il modello con cui inizia ogni sessione, e puoi comunque passare a /model; il blocco è availableModels, che vincola /model, --model, e la chiave model nei tuoi file. Quando la tua organizzazione fornisce più di una fonte gestita, le regole per la precedenza all'interno del livello gestito dicono cosa Claude Code legge da ciascuna.
Argomenti della riga di comando: flag che passi quando avvii claude da un terminale, per una sessione; vedi Cambia un'impostazione per una sessione. Claude Code unisce il JSON che passi con --settings <file-or-json> con i tuoi file di impostazioni secondo le stesse regole degli altri livelli: prende una chiave che imposti qui rispetto alla stessa chiave nelle impostazioni locali, di progetto o utente, e mantiene il valore di livello inferiore per una chiave che ometti.
Impostazioni locali del progetto (.claude/settings.local.json): le tue impostazioni personali per questo progetto.
Impostazioni di progetto condivise (.claude/settings.json): impostazioni che il tuo team inserisce nel controllo del codice sorgente.
Impostazioni utente (~/.claude/settings.json): le tue impostazioni personali per ogni progetto.
Le variabili di ambiente non sono un livello in questo stack. Quando un comportamento ha sia una variabile di shell che una chiave di impostazione, quale si applica è deciso per coppia, non per livello: ANTHROPIC_MODEL esportato nella tua shell si applica rispetto alla chiave model da qualsiasi file, mentre ANTHROPIC_DEFAULT_MODEL si applica solo quando nessun file imposta model. Il riferimento delle variabili di ambiente dice quali chiavi hanno una coppia e quale Claude Code legge per primo. Un blocco env all'interno di un file di impostazioni è una chiave ordinaria e segue i livelli sopra.
Quando imposti la stessa chiave di elenco, come permissions.allow, in più di un file, Claude Code combina gli elenchi invece di sceglierne uno, così ogni file può aggiungere voci senza rimuovere quelle di un altro file. Quattro chiavi che contengono elenchi di modelli o voci per modello seguono le loro proprie regole:
fallbackModel è una catena ordinata in cui la posizione ha significato, quindi Claude Code prende l'intero valore dal file con la precedenza più alta che lo definisce.
modelPicker contiene un elenco ordinato di righe più un flag di sostituzione, quindi Claude Code non unisce mai righe da due fonti. Prende l'intero valore dal più alto tra impostazioni gestite, --settings, e impostazioni utente che lo definisce, e ignora la chiave nelle impostazioni di progetto e locali. Richiede Claude Code v2.1.242 o successivo.
availableModels: quando le impostazioni gestite che Claude Code applica lo definiscono, Claude Code applica quell'elenco così com'è e ignora le voci che aggiungi nelle impostazioni utente, di progetto o locali, a meno che un'app che incorpora Claude Code non fornisca il suo elenco di modelli; vedi Eccezioni alla precedenza delle impostazioni gestite. Tra le fonti gestite l'elenco non si unisce mai; come Claude Code combina le fonti gestite dice quale elenco della fonte si applica. Tra gli ambiti non gestiti Claude Code unisce gli array come al solito.
modelSettings: Claude Code lo risolve un modello alla volta, insieme a effortLevel. La voce modelSettings indica quale valore del file si applica a un modello.
Esempi di precedenza
Mentre Claude lavora, Claude Code mostra un suggerimento di una riga sotto lo spinner, come "Usa /config per cambiare la tua modalità di autorizzazione predefinita (inclusa Plan Mode)". Supponiamo che tu voglia disattivare questi suggerimenti, quindi imposti spinnerTipsEnabled a false in ~/.claude/settings.json. Ogni scenario sottostante è qualcosa che può riattivarli, e cosa puoi fare al riguardo.
Le impostazioni del team sostituiscono le impostazioni personali
Il .claude/settings.json del tuo team lo imposta a true. Claude Code utilizza il valore del progetto perché il progetto condiviso si trova sopra l'utente, quindi vedi i suggerimenti in quel progetto e da nessun'altra parte.
Puoi recuperare il tuo valore: aggiungi "spinnerTipsEnabled": false a .claude/settings.local.json in quel progetto. Il progetto locale si trova sopra il progetto condiviso, quindi le tue sessioni lì smettono di mostrare suggerimenti e le sessioni dei tuoi compagni di squadra non cambiano.
Le impostazioni dell'organizzazione sostituiscono tutto
Le impostazioni gestite della tua organizzazione lo impostano a true. Nulla di quello che metti nelle impostazioni utente, di progetto o locali disattiva i suggerimenti, e nemmeno --settings. Gestito è il livello più alto.
Non puoi recuperare il tuo valore. Esegui /status per vedere quale fonte gestita si applica, e chiedi al tuo amministratore se la policy dovrebbe cambiare.
La riga di comando sostituisce i tuoi file per una sessione
Hai avviato la sessione con claude --settings '{"spinnerTipsEnabled": true}'. La riga di comando si trova sopra ogni file tranne gestito, quindi quella sessione mostra suggerimenti anche se i tuoi file dicono false.
Recuperi il tuo valore nella sessione successiva; --settings dura una sessione e non scrive in nessun file.
Un flag o una variabile di ambiente imposta la stessa cosa
Alcune chiavi hanno un flag della riga di comando o una variabile di ambiente che sostituisce il valore delle impostazioni indipendentemente da quale file lo ha impostato: ANTHROPIC_MODEL sostituisce l'impostazione model, e --model sostituisce entrambi per una sessione.
Se puoi recuperare il tuo valore dipende dalla chiave: annulla l'impostazione della variabile o elimina il flag, e controlla la voce della chiave nel riferimento delle impostazioni e la riga della variabile nel riferimento delle variabili di ambiente per sapere quale Claude Code utilizza.
Risolvi i problemi di un'impostazione che non si applica
Quando imposti una chiave e Claude Code non si comporta come se l'avessi fatto, inizia con /status per vedere quali file ha caricato, quindi trova il tuo sintomo di seguito. Debug della tua configurazione copre i controlli più ampi, incluso un test di configurazione pulita.
Un valore che hai impostato viene ignorato
Qualcos'altro sta impostando la stessa chiave, il file non può impostare quel valore, o il file non è stato caricato:
Un livello più alto lo imposta. Un altro file di impostazioni, un flag --settings, o una fonte gestita imposta la chiave sopra la tua; lo stack dice quale. Un flag o una variabile di ambiente può anche sostituire la chiave di per sé, deciso chiave per chiave; la voce della chiave nel riferimento delle impostazioni dice quale Claude Code utilizza, e la voce env copre un valore env gestito rispetto a un'esportazione di shell.
Il file non può impostare quel valore. I valori permissions.defaultModeauto e bypassPermissions non hanno effetto dalle impostazioni di progetto o locali; impostali invece nelle impostazioni utente o gestite, o passa --permission-mode per una sessione. Prima della v2.1.257, bypassPermissions aveva effetto da qualsiasi file.
Una variabile di esportazione telemetria in un blocco env non ha effetto dalle impostazioni di progetto o locali nemmeno, a parte alcuni valori off. Variabili che Claude Code ignora in env elenca le variabili e quei valori.
Il file è rotto. JSON non valido o un valore rifiutato fa sì che Claude Code salti il file o la voce; vedi Ripara un file di impostazioni rotto.
Una modifica che hai fatto in Claude Code viene persa nelle nuove sessioni
Quando salvi una scelta per le nuove sessioni dall'interno di Claude Code, come un modello predefinito con /model, Claude Code la scrive nel tuo file di impostazioni utente, ~/.claude/settings.json. Se non puoi scrivere in quel file, ad esempio perché un altro strumento lo genera o lo collega a una copia di sola lettura, la modifica si applica alla sessione corrente e scompare nella successiva. Imposta la chiave nello strumento che genera il file, o sostituisci il file con uno in cui puoi scrivere.
Le fonti gestite raggiungono una sessione in esecuzione secondo la pianificazione nella tabella di consegna, quindi riavvia prima la sessione. Se /status quindi nomina una fonte diversa da quella che il tuo amministratore ha modificato, una fonte con priorità più alta si applica; Come Claude Code combina le fonti gestite fornisce l'ordine.
Una chiave impegnata non raggiunge i compagni di squadra
Due cose impediscono a una chiave in .claude/settings.json di applicarsi per tutti coloro che la clonano:
Claude Code ignora la chiave in un file di repository. Cerca User, local, or managed, User or managed, Managed, o Global config nella colonna Scope dell'indice delle impostazioni. Quelle chiavi non si applicano mai dal file condiviso, a parte alcuni che un file di repository può comunque disattivare. Ciascuna di quelle voci lo dice sulla sua riga Scope. Le chiavi Global config si applicano solo da ~/.claude.json.
All'interno della chiave env, le variabili di esportazione telemetria non si applicano mai dal file condiviso nemmeno, a parte alcuni valori off; vedi Variabili che Claude Code ignora in env.
La chiave attende la fiducia. Le regole permissions.allow, permissions.additionalDirectories, extraKnownMarketplaces, e la maggior parte dei valori env si applicano solo dopo che ogni compagno di squadra affida la cartella. Fino ad allora vedono ancora i prompt e non ottengono plugin da un marketplace che il file dichiara. Le regole deny e ask si applicano subito.
Le regole di autorizzazione si combinano diversamente da quanto ti aspettavi
Hai scelto "Sì, e non chiedere di nuovo" su un prompt di autorizzazione ma ricevi comunque un prompt per lo stesso strumento. Quella scelta ha salvato una regola allow nel tuo file locale, e una regola allow lì non supera una regola ask da un file di progetto o gestito; come si combinano le regole di autorizzazione 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, che cambia la regola per tutti; nella CLI, Claude Code scrive solo nel tuo file locale.
Le regole di autorizzazione della tua organizzazione si applicano ancora insieme alle tue. È previsto: Claude Code unisce permissions.allow tra gli ambiti, a meno che la tua organizzazione non imposti allowManagedPermissionRulesOnly.
Eccezioni alla precedenza delle impostazioni gestite
Per alcune chiavi i cui valori limitano una sessione, Claude Code onora un valore restrittivo da un ambito che altrimenti non potrebbe sostituire le impostazioni gestite. Trova la chiave in questa tabella per vedere quale valore onora e da dove.
Un limite inferiore da qualsiasi ambito, incluso --settings
Onorato anche quando le impostazioni gestite che Claude Code applica impostano un limite superiore; si applica il limite più basso. Richiede Claude Code v2.1.267 o successivo
Un'app che esegue Claude Code al suo interno e imposta CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST è anche un'eccezione. Claude Code prende la configurazione del modello di quell'app rispetto alle chiavi model, fallbackModel, modelPicker, e modelOverrides da ogni fonte gestita, e rispetto alle variabili di selezione del modello in un blocco env gestito, come ANTHROPIC_MODEL e la famiglia ANTHROPIC_DEFAULT_*_MODEL. Claude Code mantiene un elenco di autorizzazione availableModels gestito in vigore a meno che l'app non fornisca il suo.
Impostazioni nelle sessioni cloud
Una sessione cloud viene eseguita in un ambiente cloud su un clone fresco del vostro repository, non sulla vostra macchina. Questo cambia quali impostazioni la raggiungono:
Impostazioni di progetto condivise (.claude/settings.json): lette in una sessione con un repository, perché il file fa parte del clone e la sessione inizia al suo interno. Committate un'impostazione lì per applicarla in quelle sessioni. Una sessione con più repository inizia sopra i clone e legge solo i tasti enabledPlugins e extraKnownMarketplaces da ogni .claude/settings.json del repository, non le regole di permesso, gli hook, env o altre chiavi. I marketplace e i plugin che questi due tasti dichiarano ancora non si caricano in una sessione cloud.
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.
/config: nel vostro browser su claude.ai/code, apre la sezione Claude Code delle vostre impostazioni claude.ai invece di modificare un valore. Per modificare un'impostazione per una sessione cloud, impostate una variabile di ambiente sull'ambiente, o in una sessione con un repository, committate la chiave al .claude/settings.json di quel repository.
452 Condividere le impostazioni con il vostro team452 Condividere le impostazioni con il vostro team
453</h3>453</h3>
454454
455Eseguite il commit di `.claude/settings.json` in modo che tutti coloro che clonano il repository ottengano le stesse autorizzazioni, hooks, telemetria, e plugins. Ogni collega può comunque sostituirlo per se stesso nel proprio `.claude/settings.local.json`, quindi le eccezioni personali non hanno bisogno di un commit. Per un file team completo, vedete [le impostazioni condivise di un team](/docs/it/settings-example#a-teams-shared-settings).455Eseguite il commit di `.claude/settings.json` in modo che tutti coloro che clonano il repository ottengano le stesse autorizzazioni, hooks, e plugins. Ogni collega può comunque sostituirlo per se stesso nel proprio `.claude/settings.local.json`, quindi le eccezioni personali non hanno bisogno di un commit. Per un file team completo, vedete [le impostazioni condivise di un team](/docs/it/settings-example#a-teams-shared-settings).
456456
457Parte di quello che eseguite il commit attende fino a quando ogni collega [non si fida della cartella](/docs/it/permissions#project-allow-rules-and-workspace-trust), e poche chiavi non hanno mai effetto da un file di repository; [Troubleshoot a setting that doesn't apply](#common-cases) copre entrambi.457Parte di quello che eseguite il commit attende fino a quando ogni collega [non si fida della cartella](/docs/it/permissions#project-allow-rules-and-workspace-trust), e poche chiavi non hanno mai effetto da un file di repository; [Troubleshoot a setting that doesn't apply](#common-cases) copre entrambi.
458458
743* **Un livello più alto lo imposta.** Un altro file di impostazioni, un flag `--settings`, o una fonte gestita imposta la chiave sopra la tua; lo [stack](#settings-precedence) dice quale. Un flag o una variabile di ambiente può anche sostituire la chiave di per sé, deciso chiave per chiave; la voce della chiave nel [riferimento delle impostazioni](/docs/it/settings-reference) dice quale Claude Code utilizza, e la [voce `env`](/docs/it/settings-reference#env) copre un valore `env` gestito rispetto a un'esportazione di shell.743* **Un livello più alto lo imposta.** Un altro file di impostazioni, un flag `--settings`, o una fonte gestita imposta la chiave sopra la tua; lo [stack](#settings-precedence) dice quale. Un flag o una variabile di ambiente può anche sostituire la chiave di per sé, deciso chiave per chiave; la voce della chiave nel [riferimento delle impostazioni](/docs/it/settings-reference) dice quale Claude Code utilizza, e la [voce `env`](/docs/it/settings-reference#env) copre un valore `env` gestito rispetto a un'esportazione di shell.
744* **Una chiave di sicurezza mantiene il suo valore restrittivo.** Per alcune chiavi Claude Code onora il valore restrittivo da qualsiasi file, quindi un `true` di progetto per [`disableClaudeAiConnectors`](/docs/it/settings-reference#disableclaudeaiconnectors) rimane attivo; vedi [Eccezioni alla precedenza delle impostazioni gestite](#exceptions-to-managed-settings-precedence).744* **Una chiave di sicurezza mantiene il suo valore restrittivo.** Per alcune chiavi Claude Code onora il valore restrittivo da qualsiasi file, quindi un `true` di progetto per [`disableClaudeAiConnectors`](/docs/it/settings-reference#disableclaudeaiconnectors) rimane attivo; vedi [Eccezioni alla precedenza delle impostazioni gestite](#exceptions-to-managed-settings-precedence).
745* **Il file non può impostare quel valore.** I valori [`permissions.defaultMode`](/docs/it/settings-reference#permissions-defaultmode) `auto` e `bypassPermissions` non hanno effetto dalle impostazioni di progetto o locali; impostali invece nelle impostazioni utente o gestite, o passa `--permission-mode` per una sessione. Prima della v2.1.257, `bypassPermissions` aveva effetto da qualsiasi file.745* **Il file non può impostare quel valore.** I valori [`permissions.defaultMode`](/docs/it/settings-reference#permissions-defaultmode) `auto` e `bypassPermissions` non hanno effetto dalle impostazioni di progetto o locali; impostali invece nelle impostazioni utente o gestite, o passa `--permission-mode` per una sessione. Prima della v2.1.257, `bypassPermissions` aveva effetto da qualsiasi file.
746
747 Una variabile di esportazione telemetria in un blocco [`env`](/docs/it/settings-reference#env) non ha effetto dalle impostazioni di progetto o locali nemmeno, a parte alcuni valori off. [Variabili che Claude Code ignora in `env`](/docs/it/settings-reference#variables-claude-code-ignores-in-env) elenca le variabili e quei valori.
746* **Il file è rotto.** JSON non valido o un valore rifiutato fa sì che Claude Code salti il file o la voce; vedi [Ripara un file di impostazioni rotto](#fix-a-broken-settings-file).748* **Il file è rotto.** JSON non valido o un valore rifiutato fa sì che Claude Code salti il file o la voce; vedi [Ripara un file di impostazioni rotto](#fix-a-broken-settings-file).
766Due cose impediscono a una chiave in `.claude/settings.json` di applicarsi per tutti coloro che la clonano:768Due cose impediscono a una chiave in `.claude/settings.json` di applicarsi per tutti coloro che la clonano:
767769
768* **Claude Code ignora la chiave in un file di repository.** Cerca `User, local, or managed`, `User or managed`, `Managed`, o `Global config` nella colonna Scope dell'[indice delle impostazioni](/docs/it/settings-reference#settings-index). Quelle chiavi non si applicano mai dal file condiviso, a parte alcuni che un file di repository può comunque disattivare. Ciascuna di quelle voci lo dice sulla sua riga Scope. Le chiavi `Global config` si applicano solo da `~/.claude.json`.770* **Claude Code ignora la chiave in un file di repository.** Cerca `User, local, or managed`, `User or managed`, `Managed`, o `Global config` nella colonna Scope dell'[indice delle impostazioni](/docs/it/settings-reference#settings-index). Quelle chiavi non si applicano mai dal file condiviso, a parte alcuni che un file di repository può comunque disattivare. Ciascuna di quelle voci lo dice sulla sua riga Scope. Le chiavi `Global config` si applicano solo da `~/.claude.json`.
771
772 All'interno della chiave `env`, le variabili di esportazione telemetria non si applicano mai dal file condiviso nemmeno, a parte alcuni valori off; vedi [Variabili che Claude Code ignora in `env`](/docs/it/settings-reference#variables-claude-code-ignores-in-env).
769* **La chiave attende la fiducia.** Le regole `permissions.allow`, `permissions.additionalDirectories`, `extraKnownMarketplaces`, e la maggior parte dei valori [`env`](/docs/it/settings-reference#env) si applicano solo dopo che ogni compagno di squadra [affida la cartella](/docs/it/permissions#project-allow-rules-and-workspace-trust). Fino ad allora vedono ancora i prompt e non ottengono plugin da un marketplace che il file dichiara. Le regole `deny` e `ask` si applicano subito.773* **La chiave attende la fiducia.** Le regole `permissions.allow`, `permissions.additionalDirectories`, `extraKnownMarketplaces`, e la maggior parte dei valori [`env`](/docs/it/settings-reference#env) si applicano solo dopo che ogni compagno di squadra [affida la cartella](/docs/it/permissions#project-allow-rules-and-workspace-trust). Fino ad allora vedono ancora i prompt e non ottengono plugin da un marketplace che il file dichiara. Le regole `deny` e `ask` si applicano subito.