SpyBara
Go Premium

settings.md 2026-09-11 23:01 UTC to 2026-09-12 03:02 UTC

This page contains 57 additions and 54 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. 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:

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

  1. 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.
  2. 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.
  3. Impostazioni locali del 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.

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.

Per alcune chiavi sensibili alla sicurezza, Claude Code onora un valore più restrittivo da un livello inferiore rispetto a un valore gestito; Eccezioni alla precedenza delle impostazioni gestite le elenca.

Gli elenchi si uniscono invece di sostituirsi

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.
  • 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 rimane attivo; vedi 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 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.
  • 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.

Se puoi scrivere nel file e la modifica comunque non dura, controlla 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 hai scelto elenca più cause.

Una modifica gestita non ti ha raggiunto

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 autoContinueAtUsageLimit, che un file di repository può comunque disattivare: mentre il file imposta la chiave e nessun valore utente, --settings, o gestito lo fa, Claude Code legge l'impostazione come disattivata. 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 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.

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 true di progetto o locale viene ignorato
crossSessionInbound Un valore più restrittivo da .claude/settings.json o .claude/settings.local.json, sulla scala accept < hold < refuse Onorato rispetto ai valori gestiti, --settings, e utente; un valore di progetto o locale che non è più restrittivo viene 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 viene 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 viene ignorato
maxEffortLevel 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, 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