SpyBara
Go Premium

settings.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 635 additions and 1062 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58

File di impostazioni e precedenza

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

<svg viewBox={0 0 ${W} ${H}} xmlns="http://www.w3.org/2000/svg"> Highest precedence {LEVELS.map((l, i) => { const y = TOP + i * (ROW + GAP); const x = cx - l.w / 2; const top = i === 0; return <rect x={x} y={y} width={l.w} height={ROW} rx={10} fill={top ? 'var(--sp-top-fill)' : 'var(--sp-fill)'} stroke={top ? 'var(--sp-top)' : 'var(--sp-stroke)'} strokeWidth={top ? 1.5 : 1} /> <text x={x + 14} y={y + 24} fontFamily={sans} fontSize="14" fontWeight="600" fill="var(--sp-text)">{l.n}. {l.name} <text x={x + 14} y={y + 43} fontFamily={mono} fontSize="11.5" fill="var(--sp-sub)">{l.file} <text x={x + l.w - 14} y={y + 24} textAnchor="end" fontFamily={sans} fontSize="12" fill="var(--sp-faint)">{l.who} ; })} <text x={cx} y={H - 10} textAnchor="middle" fontFamily={sans} fontSize="12.5" fontWeight="600" fill="var(--sp-sub)">Lowest precedence <line x1={W - 40} y1={TOP + 10} x2={W - 40} y2={H - 38} /> <path d={M ${W - 46} ${TOP + 18} L ${W - 40} ${TOP + 10} L ${W - 34} ${TOP + 18}} /> <text x={W - 40} y={H - 22} textAnchor="middle" fontFamily={sans} fontSize="10.5" fill="var(--sp-faint)">overrides
; };

export const SettingsScope = ({defaultSelected = 'project'}) => { const FILES = [{ id: 'user', path: '/.claude/settings.json' }, { id: 'project', path: 'acme-app/.claude/settings.json' }, { id: 'local', path: 'acme-app/.claude/settings.local.json' }, { id: 'managed', path: 'Managed settings', ring: 'managed-settings.json, MDM, or the claude.ai console' }]; const SHORT = { user: '/.claude/settings.json', project: 'acme-app/.claude/settings.json', local: 'acme-app/.claude/settings.local.json', managed: 'managed-settings.json, MDM, or the claude.ai console' }; const TILE_MARK = { project: 'settings.json', local: 'settings.local.json' }; const initial = FILES.some(f => f.id === defaultSelected) ? defaultSelected : 'project'; const [sel, setSel] = useState(initial); const [scale, setScale] = useState(1); const [isFullscreen, setIsFullscreen] = useState(false); const rootRef = useRef(null); const frameRef = useRef(null); const CANVAS_W = 862; const CANVAS_H = 240; useEffect(() => { const el = frameRef.current; if (!el) return; const measure = () => setScale(Math.min(1, el.clientWidth / CANVAS_W)); measure(); if (typeof ResizeObserver === 'undefined') { window.addEventListener('resize', measure); return () => window.removeEventListener('resize', measure); } const ro = new ResizeObserver(measure); ro.observe(el); return () => ro.disconnect(); }, []); useEffect(() => { const onFsChange = () => setIsFullscreen(!!document.fullscreenElement); document.addEventListener('fullscreenchange', onFsChange); return () => document.removeEventListener('fullscreenchange', onFsChange); }, []); const toggleFullscreen = () => { if (!rootRef.current) return; if (document.fullscreenElement) document.exitFullscreen(); else rootRef.current.requestFullscreen().catch(() => {}); }; const COVERAGE = { user: ['website', 'api', 'yacme'], project: ['yacme', 'tacme', 'cacme'], local: ['yacme'], managed: ['website', 'api', 'yacme', 'tacme', 'cacme'] }; const RINGS = { local: { l: 282, t: 50, w: 142, h: 124 }, project: { l: 282, t: 50, w: 560, h: 124 }, user: { l: 2, t: 34, w: 446, h: 198 }, managed: { l: 0, t: 32, w: 862, h: 204 } }; const TILES = [{ id: 'website', name: 'website/', left: 30, caption: '' }, { id: 'api', name: 'api/', left: 160, caption: '' }, { id: 'yacme', name: 'acme-app/', left: 290, caption: '' }, { id: 'tacme', name: 'acme-app/', left: 497, caption: sel === 'project' ? 'their clone, once you commit the file' : 'their clone' }, { id: 'cacme', name: 'acme-app/', left: 704, caption: sel === 'project' ? 'fresh clone, once you commit the file' : sel === 'managed' ? 'server-managed only' : 'fresh clone' }]; const FILE_AT = { user: { machine: 'you', tiles: [] }, project: { machine: null, tiles: ['yacme', 'tacme', 'cacme'] }, local: { machine: null, tiles: ['yacme'] }, managed: { machine: null, tiles: [] } }; const fileAt = FILE_AT[sel]; const coverage = COVERAGE[sel]; const ring = RINGS[sel]; const selFile = FILES.find(f => f.id === sel); const FolderIcon = ({open}) => ; const FileIcon = () => ; const CloudIcon = () => ; const LaptopIcon = () => ; return <div ref={rootRef} className={'ssc-root not-prose' + (isFullscreen ? ' ssc-fs' : '')}>

  <div className="ssc-head">
    <div className="ssc-files" role="group" aria-label="Settings file">
      {FILES.map(f => <button key={f.id} type="button" className="ssc-file ssc-mono" aria-pressed={f.id === sel} onClick={() => setSel(f.id)}>{f.path}</button>)}
    </div>
    <button type="button" className="ssc-fsbtn" onClick={toggleFullscreen} aria-label={isFullscreen ? 'Exit fullscreen' : 'Enter fullscreen'} title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}>{isFullscreen ? '⤡' : '⛶'}</button>
  </div>

  <div ref={frameRef} className="ssc-frame" style={{
height: CANVAS_H * scale + 'px'

}}> <div className="ssc-canvas" style={{ transform: 'scale(' + scale + ')' }}> <div className="ssc-machine" style={{ left: '10px', width: '430px' }} /> <span className="ssc-machine-label" style={{ left: '30px' }}>Your machine{fileAt.machine === 'you' && {selFile.path}} <div className="ssc-machine" style={{ left: '460px', width: '200px' }} /> <span className="ssc-machine-label" style={{ left: '470px' }}>A teammate’s machine <div className="ssc-machine" style={{ left: '682px', width: '170px' }} /> <span className="ssc-machine-label" style={{ left: '692px' }}>A cloud session

      {TILES.map(t => {
const on = coverage.includes(t.id);
return <div key={t.id} className={'ssc-tile' + (on ? ' ssc-on' : '')} style={{
  left: t.left + 'px'
}}>
            <div className="ssc-tile-name"><FolderIcon open={on} /><span className="ssc-mono">{t.name}</span></div>
            {t.caption && <div className="ssc-tile-caption">{t.caption}</div>}
            {fileAt.tiles.includes(t.id) && <span className="ssc-filemark ssc-mono" title={SHORT[sel]}><FileIcon />{TILE_MARK[sel]}</span>}
          </div>;

})}

      <div className="ssc-ring" style={{
left: ring.l + 'px',
top: ring.t + 'px',
width: ring.w + 'px',
height: ring.h + 'px'

}} /> <span className="ssc-ring-label ssc-mono" style={{ left: ring.l + 14 + 'px', top: ring.t - 26 + 'px' }}>{selFile.ring || selFile.path}

; };

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 ne è interessato

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 è interessato Usalo per
Utente ~/.claude/settings.json Voi, in ogni progetto su questa macchina Preferenze personali: tema, modalità editor, modello predefinito, vostre regole di permesso
Progetto condiviso .claude/settings.json Tutti coloro che lavorano nella cartella che lo contiene. In un repository git, committalo in modo che i compagni di squadra lo ottengano Permessi del team, hooks, plugin e le variabili di ambiente di cui il progetto ha bisogno
Progetto locale .claude/settings.local.json Voi, solo in questo 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
Gestito managed-settings.json e altre fonti gestite Tutti coloro a cui la vostra organizzazione lo distribuisce; nulla di quello che impostate lo ignora, a parte poche eccezioni sensibili alla sicurezza Politica di sicurezza e requisiti di conformità

Nella colonna File, ~/.claude è la cartella .claude nella vostra directory home, e un .claude nudo è la cartella .claude dentro il vostro progetto.

Confronta l'ambito di ogni file di impostazioni

Supponiamo che abbiate tre progetti sulla vostra macchina, website/, api/ e acme-app/, un compagno di squadra ha il suo clone di acme-app/, e avviate una sessione cloud su acme-app/.

Il grafico sottostante mostra a quali di quelle cartelle si applica un'impostazione quando avviate Claude Code da esse. Cliccate 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 compagno di squadra o nella sessione cloud
  • acme-app/.claude/settings.json: il vostro acme-app/. Raggiunge il clone del vostro compagno di squadra e la sessione cloud solo se committate il file al controllo della 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 ai vostri 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 vi accedete con il vostro account organizzativo. Solo le impostazioni gestite dal server raggiungono la sessione cloud

Trovate o create 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 voi.
  • Progetto condiviso: un progetto che già usa Claude Code potrebbe averne uno committato. Se no, createlo a .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 permesso, come "Sì, e non chiedere di nuovo" per un comando Bash. Poche opzioni /config, incluso Mostra suggerimenti, salvano in .claude/settings.local.json invece del 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.

Condividete le impostazioni con il vostro team

Committate .claude/settings.json in modo che tutti coloro che clonano il repository ottengano gli stessi permessi, hooks, telemetria e plugin. Ogni compagno di squadra può comunque ignorarlo per se stesso nel proprio .claude/settings.local.json, quindi le eccezioni personali non hanno bisogno di un commit. Per un file team completo, vedere impostazioni condivise di un team.

Parte di quello che committate attende fino a quando ogni compagno di squadra non fidia della cartella, e poche chiavi non hanno mai effetto da un file di repository; Risolvi i problemi di un'impostazione che non si applica copre entrambi.

Mantenete le impostazioni personali fuori da un repository

Per modificare un'impostazione per voi stessi in un progetto senza modificarla per i vostri compagni di squadra, salvatela in .claude/settings.local.json dentro il progetto. Claude Code applica quel file sopra il .claude/settings.json committato, quindi se il file del vostro team imposta "model": "claude-sonnet-5" e volete Opus, mettete "model": "claude-opus-4-8" nel vostro file locale e solo le vostre sessioni cambiano.

Tre cose da sapere sul file locale:

  • 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 quell'approvazione di permesso qui come una regola allow.
  • Non dovete gitignorarlo 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 a 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 allow 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 committato. Se il file è tracciato da git, il passaggio di fiducia si applica anche a esso; vedere Quando il vostro file di impostazioni locale ha bisogno di fiducia.

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 quell'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, usa 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 directory home, su Windows, o quando la radice del repository o la sua voce .git o .claude non è di proprietà del vostro 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 alla directory di lavoro primaria della sessione invece.

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ì insieme al file della radice; dove entrambi impostano la stessa chiave, il valore della radice si applica, e le regole di permesso 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 usare un file committato alla radice del repository, avviate Claude Code lì. Dopo che spostate la sessione con /cd, Claude Code legge entrambi i file di 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.

Verificate 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. 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 viene eseguito su questa macchina; Cosa uno sviluppatore può modificare copre i diritti di amministratore locale e gli strumenti diversi da Claude Code.

Le impostazioni gestite vi raggiungono attraverso i meccanismi di consegna sulla pagina delle impostazioni gestite, più comunemente:

In una sessione Cowork che viene eseguita 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. Dove e quando si applica una politica copre Cowork e le sessioni cloud.

Se siete l'amministratore, Configurate Claude Code per la vostra organizzazione vi guida attraverso la scelta di cosa applicare, e Distribuisci le impostazioni gestite copre la consegna e come confermare che una politica è in vigore.

Modificate un'impostazione

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
  • Le opzioni di configurazione globale: ~/.claude.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-4-8"}'

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. 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:

Confermate cosa è stato caricato

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.
  • 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.

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 usa 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 ignora la stessa chiave ovunque sotto.

In ordine, precedenza più alta prima:

  1. Impostazioni gestite: impostazioni che la vostra organizzazione distribuisce, da un file managed-settings.json, una politica MDM, o impostazioni gestite dal server dalla console claude.ai. Nulla di quello che impostate le ignora: una chiave che passate con --settings non ignora la stessa chiave gestita, e un flag come --model sceglie solo dai modelli che la vostra organizzazione consente. Un model gestito imposta il modello con cui ogni sessione inizia, e potete comunque cambiare con /model; il blocco è availableModels, che vincola /model, --model e la chiave model nei vostri file. Quando la vostra organizzazione fornisce più di una fonte gestita, le regole per precedenza all'interno del livello gestito dicono cosa Claude Code legge da ognuna.
  2. Argomenti della riga di comando: flag che passate quando avviate claude da un terminale, per una sessione; vedere Modificate un'impostazione per una sessione. Claude Code unisce JSON che passate con --settings <file-or-json> con i vostri file di impostazioni secondo le stesse regole degli altri livelli: prende una chiave che impostate qui sopra la stessa chiave nelle impostazioni locale, progetto o utente, e mantiene il valore di livello inferiore per una chiave che omettete.
  3. Impostazioni di progetto locale (.claude/settings.local.json): le vostre impostazioni personali per questo progetto.
  4. Impostazioni di progetto condivise (.claude/settings.json): impostazioni che il vostro team controlla nel controllo del codice sorgente.
  5. Impostazioni utente (~/.claude/settings.json): le vostre impostazioni personali per ogni progetto.

Le variabili di ambiente non sono un livello in questo stack. Quando un comportamento ha sia una variabile shell che una chiave di impostazioni, quale si applica è deciso per coppia, non per livello: ANTHROPIC_MODEL esportato nella vostra shell si applica sopra la chiave model da qualsiasi file, mentre ANTHROPIC_DEFAULT_MODEL si applica solo quando nessun file imposta model. La referenza delle variabili di ambiente dice quali chiavi hanno una coppia e quale Claude Code legge prima. Un blocco env dentro un file di impostazioni è una chiave ordinaria e segue i livelli sopra.

Per poche chiavi sensibili alla sicurezza, Claude Code onora un valore più rigoroso da un livello inferiore sopra un valore gestito; Eccezioni alla precedenza delle impostazioni gestite le elenca.

Gli elenchi si uniscono invece di ignorarsi

Quando impostate la stessa chiave di elenco, come permissions.allow, in più di un file, Claude Code combina gli elenchi invece di sceglierne uno, quindi 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 regole:

  • fallbackModel è una catena ordinata dove la posizione ha significato, quindi Claude Code prende l'intero valore dal file con la precedenza più alta che la 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 le impostazioni gestite, --settings e le impostazioni utente che la definisce, e ignora la chiave nelle impostazioni di progetto e locale. Richiede Claude Code v2.1.242 o successivo.
  • availableModels: quando le impostazioni gestite che Claude Code applica la definiscono, Claude Code applica quell'elenco così com'è e ignora le voci che aggiungete nelle impostazioni utente, progetto o locale, a meno che un'app che incorpora Claude Code non fornisca il suo elenco di modelli; vedere Eccezioni alla precedenza delle impostazioni gestite. Tra le fonti gestite l'elenco non si unisce mai neanche; 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 dice quale file il valore si applica a un modello.

Esempi di precedenza

Mentre Claude lavora, Claude Code mostra un suggerimento di una riga sotto lo spinner, come "Usate /config per modificare la vostra modalità di permesso predefinita (inclusa la modalità Piano)". Supponiamo che volete quei suggerimenti spenti, quindi impostate spinnerTipsEnabled a false in ~/.claude/settings.json. Ogni scenario sottostante è qualcosa che può riattivarli, e cosa potete fare al riguardo.

Le impostazioni del team ignorano le impostazioni personali

Il .claude/settings.json del vostro team lo imposta a true. Claude Code usa il valore del progetto perché il progetto condiviso si trova sopra l'utente, quindi vedete i suggerimenti in quel progetto e da nessun'altra parte.

Potete recuperare il vostro valore: aggiungete "spinnerTipsEnabled": false a .claude/settings.local.json in quel progetto. Il progetto locale si trova sopra il progetto condiviso, quindi le vostre sessioni lì smettono di mostrare i suggerimenti e le sessioni dei vostri compagni di squadra non cambiano.

Le impostazioni dell'organizzazione ignorano tutto

Le impostazioni gestite della vostra organizzazione lo impostano a true. Nulla di quello che mettete nelle impostazioni utente, progetto o locale spegne i suggerimenti, e neanche --settings. Gestito è il livello più alto.

Non potete recuperare il vostro valore. Eseguite /status per vedere quale fonte gestita si applica, e chiedete al vostro amministratore se la politica dovrebbe cambiare.

La riga di comando ignora i vostri file per una sessione

Avete avviato la sessione con claude --settings '{"spinnerTipsEnabled": true}'. La riga di comando si trova sopra ogni file tranne gestito, quindi quella sessione mostra i suggerimenti anche se i vostri file dicono false.

Recuperate il vostro valore nella sessione successiva; --settings dura una sessione e non scrive in alcun 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 ignora il valore delle impostazioni indipendentemente da quale file lo ha impostato: ANTHROPIC_MODEL ignora l'impostazione model, e --model ignora entrambi per una sessione.

Se potete recuperare il vostro valore dipende dalla chiave: annullate la variabile o eliminate il flag, e controllate la voce della chiave sulla referenza delle impostazioni e la riga della variabile sulla referenza delle variabili di ambiente per quale Claude Code usa.

Risolvete i problemi di un'impostazione che non si applica

Quando impostate una chiave e Claude Code non si comporta come se l'aveste fatto, iniziate con /status per vedere quali file ha caricato, quindi trovate il vostro sintomo sottostante. Debug della vostra configurazione copre i controlli più ampi, incluso un test di configurazione pulita.

Un valore che impostate è ignorato

Qualcos'altro imposta 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 vostra; lo stack dice quale. Un flag o una variabile di ambiente può anche ignorare la chiave per conto suo, deciso chiave per chiave; la voce della chiave sulla referenza delle impostazioni dice quale Claude Code usa, e la voce env copre un valore env gestito rispetto a un'esportazione shell.
  • Una chiave di sicurezza mantiene il suo valore rigoroso. Per poche chiavi Claude Code onora il valore restrittivo da qualsiasi file, quindi un progetto true per disableClaudeAiConnectors rimane acceso; vedere Eccezioni alla precedenza delle impostazioni gestite.
  • Il file non può impostare quel valore. I valori permissions.defaultMode auto e bypassPermissions non hanno effetto dalle impostazioni di progetto o locale; impostateli nelle impostazioni utente o gestite invece, o passate --permission-mode per una sessione. Prima della v2.1.257, bypassPermissions aveva effetto da qualsiasi file.
  • Il file è rotto. JSON non valido o un valore rifiutato fa sì che Claude Code salti il file o la voce; vedere Riparate un file di impostazioni rotto.

Una modifica che avete fatto in Claude Code è persa nelle nuove sessioni

Quando salvate una scelta per le nuove sessioni da dentro Claude Code, come un modello predefinito con /model, Claude Code la scrive nel vostro file di impostazioni utente, ~/.claude/settings.json. Se non potete 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 è persa nella successiva. Impostate la chiave nello strumento che genera il file, o sostituite il file con uno in cui potete scrivere.

Se potete scrivere nel file e la modifica comunque non dura, controllate se la modifica era solo per una sessione o un livello più alto imposta la stessa chiave. Per la chiave model, Una nuova sessione inizia su un modello diverso da quello che avete scelto elenca più cause.

Una modifica gestita non vi ha raggiunto

Le fonti gestite raggiungono una sessione in esecuzione secondo la pianificazione nella tabella di consegna, quindi riavviate prima la sessione. Se /status allora nomina una fonte diversa da quella che il vostro amministratore ha modificato, una fonte con priorità più alta si applica; Come Claude Code combina le fonti gestite fornisce l'ordine.

Una chiave committata 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. Cercate 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 autoContinueAtUsageLimit, che un file di repository può comunque spegnere: mentre il file imposta la chiave e nessun valore utente, --settings o gestito lo fa, Claude Code legge l'impostazione come spenta. Le chiavi Global config si applicano solo da ~/.claude.json.
  • 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 fidia della cartella. Fino ad allora vedono comunque i prompt e non ottengono i plugin da un marketplace che il file dichiara. Le regole deny e ask si applicano subito.

Le regole di permesso si combinano diversamente da come vi aspettate

  • Avete scelto "Sì, e non chiedere di nuovo" su un prompt di permesso ma ricevete comunque il prompt per lo stesso strumento. Quella scelta ha salvato una regola allow nel vostro file locale, e una regola allow lì non supera una regola ask da un file di progetto o gestito; come le regole di permesso si combinano spiega l'ordine. Nell'estensione VS Code la scheda di approvazione vi 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 vostro file locale.
  • Le regole allow della vostra organizzazione si applicano comunque insieme alle vostre. È previsto: Claude Code unisce permissions.allow tra gli ambiti, a meno che la vostra organizzazione non imposti allowManagedPermissionRulesOnly.

Eccezioni alla precedenza delle impostazioni gestite

Per poche chiavi sensibili alla sicurezza, Claude Code onora un valore restrittivo da un ambito che altrimenti non potrebbe ignorare le impostazioni gestite. Trovate la chiave in questa tabella per vedere quale valore onora e da dove.

Chiave Valore che Claude Code onora Note
disableClaudeAiConnectors true da qualsiasi ambito Onorato anche quando una fonte gestita imposta false
enableArtifact false da qualsiasi ambito, e disableArtifact: true da qualsiasi ambito Onorato anche quando una fonte gestita imposta true; nulla riattiva lo strumento Artifact. Richiede Claude Code v2.1.242 o successivo
isolatePeerMachines true da qualsiasi ambito Onorato anche quando una fonte gestita imposta false
remoteControlAtStartup false da .claude/settings.json o .claude/settings.local.json Onorato anche quando una fonte gestita imposta true; un progetto o locale true è ignorato
crossSessionInbound Un valore più rigoroso da .claude/settings.json o .claude/settings.local.json, sulla scala accept < hold < refuse Onorato sopra i valori gestiti, --settings e utente; un valore di progetto o locale che non è più rigoroso è ignorato
useAutoModeDuringPlan false da qualsiasi fonte gestita, --settings, ~/.claude/settings.json o .claude/settings.local.json Onorato anche quando la fonte gestita vincente imposta true; un false in .claude/settings.json è ignorato
syncClaudeAiSkills false da qualsiasi fonte gestita, --settings, ~/.claude/settings.json o .claude/settings.local.json Onorato anche quando la fonte gestita vincente imposta true; un false in .claude/settings.json è ignorato

Un'app che esegue Claude Code dentro se stessa e imposta CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST è anche un'eccezione. Claude Code prende la configurazione del modello di quell'app sopra le chiavi model, fallbackModel e modelOverrides da ogni fonte gestita, e sopra le variabili di selezione del modello in un blocco env gestito, come ANTHROPIC_MODEL e la famiglia ANTHROPIC_DEFAULT_*_MODEL. Claude Code mantiene un availableModels gestito in vigore a meno che l'app non fornisca il suo.

Impostazioni nelle sessioni cloud

Una sessione cloud, su Claude Code sul web o da claude --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, perché il file fa parte del clone. Committate un'impostazione lì per applicarla nelle sessioni 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.
  • Impostazioni gestite: solo le impostazioni gestite dal server raggiungono una sessione cloud; un file managed-settings.json o un profilo MDM sul vostro dispositivo no. 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: sul web, 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 committate la chiave al .claude/settings.json del repository.

Cosa si trasporta dalla vostra configurazione elenca il resto: CLAUDE.md, skills, MCP server, plugin e credenziali.

Cosa c'è dopo