Impostazioni di Claude Code

​

Ambiti di configurazione

​

Ambiti disponibili

​

Quando utilizzare ogni ambito

• Politiche di sicurezza che devono essere applicate a livello organizzativo
• Requisiti di conformità che non possono essere ignorati
• Configurazioni standardizzate distribuite da IT/DevOps

• Preferenze personali che desideri ovunque (temi, impostazioni dell’editor)
• Strumenti e plugin che utilizzi in tutti i progetti
• Chiavi API e autenticazione (archiviate in modo sicuro)

• Impostazioni condivise dal team (permessi, hooks, MCP servers)
• Plugin che l’intero team dovrebbe avere
• Standardizzazione degli strumenti tra i collaboratori

• Override personali per un progetto specifico
• Test delle configurazioni prima di condividerle con il team
• Impostazioni specifiche della macchina che non funzioneranno per altri

​

Come interagiscono gli ambiti

1. Managed (più alta): non può essere ignorata da nulla
2. Argomenti della riga di comando: override temporanei della sessione
3. Local: ignora le impostazioni di progetto e utente
4. Project: ignora le impostazioni utente
5. User (più bassa): si applica quando nient’altro specifica l’impostazione

​

Cosa utilizza gli ambiti

​

File di impostazioni

• Le impostazioni utente sono definite in ~/.claude/settings.json e si applicano a tutti i progetti.
• Le impostazioni di progetto vengono salvate nella directory del tuo progetto:
  • .claude/settings.json per le impostazioni che vengono controllate nel controllo del codice sorgente e condivise con il tuo team
  • .claude/settings.local.json per le impostazioni che non vengono controllate, utili per preferenze personali e sperimentazione. Quando Claude Code crea .claude/settings.local.json, configura git per ignorare il file. Se crei il file tu stesso, aggiungilo al tuo gitignore manualmente.
• Impostazioni gestite: Per le organizzazioni che necessitano di controllo centralizzato, Claude Code supporta più meccanismi di distribuzione per le impostazioni gestite. Tutti utilizzano lo stesso formato JSON e non possono essere ignorati dalle impostazioni utente o di progetto:
  • Impostazioni gestite dal server: consegnate da remoto al momento dell’accesso, sia dai server di Anthropic tramite la console di amministrazione claude.ai che da un gateway di app Claude auto-ospitato. Vedi impostazioni gestite dal server.
  • Politiche MDM/a livello di sistema operativo: consegnate tramite la gestione nativa dei dispositivi su macOS e Windows:
    • macOS: dominio delle preferenze gestite com.anthropic.claudecode. Le chiavi di primo livello del plist rispecchiano managed-settings.json, con impostazioni annidate come dizionari e array come array plist. Distribuisci tramite profili di configurazione in Jamf, Iru (Kandji) o strumenti MDM simili.
    • Windows: chiave di registro HKLM\SOFTWARE\Policies\ClaudeCode con un valore Settings (REG_SZ o REG_EXPAND_SZ) contenente JSON (distribuito tramite Criteri di gruppo o Intune)
    • Windows (a livello utente): HKCU\SOFTWARE\Policies\ClaudeCode (priorità di politica più bassa, utilizzata solo quando non esiste alcuna fonte a livello di amministratore)
  • Basate su file: managed-settings.json e managed-mcp.json distribuite alle directory di sistema:
    • macOS: /Library/Application Support/ClaudeCode/
    • Linux e WSL: /etc/claude-code/
    • Windows: C:\Program Files\ClaudeCode\
    Il percorso Windows legacy C:\ProgramData\ClaudeCode\managed-settings.json non è più supportato a partire da v2.1.75. Gli amministratori che hanno distribuito impostazioni in quella posizione devono migrare i file a C:\Program Files\ClaudeCode\managed-settings.json.
    Le impostazioni gestite basate su file supportano anche una directory drop-in in managed-settings.d/ nella stessa directory di sistema insieme a managed-settings.json. Questo consente ai team separati di distribuire frammenti di politica indipendenti senza coordinare le modifiche a un singolo file. Seguendo la convenzione systemd, managed-settings.json viene unito per primo come base, quindi tutti i file *.json nella directory drop-in vengono ordinati alfabeticamente e uniti in cima. I file successivi ignorano quelli precedenti per i valori scalari; gli array vengono concatenati e deduplicati; gli oggetti vengono uniti in profondità. I file nascosti che iniziano con . vengono ignorati. Usa prefissi numerici per controllare l’ordine di unione, ad esempio 10-telemetry.json e 20-security.json.
  Vedi impostazioni gestite e Configurazione MCP gestita per i dettagli. Questo repository include modelli di distribuzione iniziali per Jamf, Iru (Kandji), Intune e Criteri di gruppo. Usa questi come punti di partenza e adattali alle tue esigenze.
  Le distribuzioni gestite possono anche limitare le aggiunte del marketplace dei plugin utilizzando strictKnownMarketplaces. Per ulteriori informazioni, vedi Restrizioni del marketplace gestito.
• Altra configurazione è archiviata in ~/.claude.json. Questo file contiene la tua sessione OAuth, configurazioni dei MCP server per gli ambiti utente e locale, stato per-progetto (strumenti consentiti, impostazioni di fiducia), e varie cache. I MCP server con ambito di progetto sono archiviati separatamente in .mcp.json.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}

​

Quando gli edits hanno effetto

• model: usa /model per cambiare durante la sessione
• outputStyle: parte del prompt di sistema, che viene ricostruito su /clear o riavvio

​

Voci non valide nelle impostazioni gestite

• Le sessioni interattive mostrano una finestra di dialogo all’avvio che elenca le voci non valide.
• Le esecuzioni headless con -p stampano un riepilogo su stderr.
• claude doctor elenca ogni voce non valida con la sua fonte e il campo.

​

Impostazioni disponibili

​

Impostazioni di configurazione globale

​

Impostazioni worktree

​

Impostazioni di permesso

​

Sintassi della regola di permesso

​

Impostazioni sandbox

​

Prefissi di percorso sandbox

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "deniedDomains": ["uploads.github.com"],
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  }
}

• Impostazioni sandbox.filesystem (mostrate sopra): Controllano i percorsi al confine della sandbox a livello di sistema operativo. Queste restrizioni si applicano a tutti i comandi dei sottoprocessi (ad es., kubectl, terraform, npm), non solo agli strumenti di file di Claude.
• Regole di permesso: Usa le regole allow/deny Edit per controllare l’accesso dello strumento di file di Claude, le regole deny Read per bloccare le letture, e le regole allow/deny WebFetch per controllare i domini di rete. I percorsi da queste regole vengono anche uniti nella configurazione della sandbox.

​

Impostazioni di attribuzione

• I commit utilizzano i git trailers (come Co-Authored-By) per impostazione predefinita, che possono essere personalizzati o disabilitati
• Le descrizioni delle pull request sono testo semplice

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
    "pr": ""
  }
}

​

Impostazioni di suggerimento file

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

{"query": "src/comp"}

src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx

#!/bin/bash
query=$(cat | jq -r '.query')
# Sostituisci your-repo-file-index con il tuo comando di ricerca file
your-repo-file-index --query "$query" | head -20

​

Badge di link nel footer

{
  "footerLinksRegexes": [
    {
      "type": "regex",
      "pattern": "\\b(?<key>PROJ-\\d+)\\b",
      "url": "https://issues.example.com/browse/{key}",
      "label": "{key}"
    }
  ]
}

​

Configurazione hook

• Gli hook gestiti e gli hook SDK vengono caricati
• Gli hook dai plugin forzatamente abilitati nelle impostazioni gestite enabledPlugins vengono caricati. Questo consente agli amministratori di distribuire hook controllati tramite un marketplace organizzativo mentre blocca tutto il resto. La fiducia viene concessa dall’ID completo plugin@marketplace, quindi un plugin con lo stesso nome da un marketplace diverso rimane bloccato
• Gli hook utente, di progetto e di tutti gli altri plugin vengono bloccati

{
  "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}

{
  "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}

​

Calcola le impostazioni gestite con un policy helper

{
  "managedSettings": {
    "permissions": { "deny": ["Read(//etc/secrets/**)"] }
  },
  "claudeMd": "# Organization context\n...",
  "appendSystemPrompt": "Always cite the internal style guide."
}

​

Precedenza delle impostazioni

1. Impostazioni gestite (gestite dal server, politiche MDM/a livello di sistema operativo, o impostazioni gestite)
   • Politiche distribuite da IT tramite consegna dal server, profili di configurazione MDM, politiche di registro, o file di impostazioni gestite
   • Non possono essere ignorate da nessun altro livello, inclusi gli argomenti della riga di comando
   • All’interno del livello gestito, la precedenza è: policyHelper output, che quando configurato è l’unica fonte gestita utilizzata > remoto (impostazioni gestite dal server di claude.ai o gateway di app Claude-consegnate) > politiche MDM/a livello di sistema operativo > basate su file (managed-settings.d/*.json + managed-settings.json) > registro HKCU (solo Windows). Viene utilizzata una sola fonte gestita; le fonti non si uniscono tra i livelli, con un’eccezione: le chiavi di blocco sandbox sandbox.network.allowManagedDomainsOnly e sandbox.filesystem.allowManagedReadPathsOnly, con i loro elenchi di autorizzazione associati, allowAllClaudeAiMcps, e i percorsi binari sandbox sandbox.bwrapPath e sandbox.socatPath vengono onorati quando qualsiasi fonte gestita controllata dall’amministratore li imposta; il livello HKCU scrivibile dall’utente è escluso. All’interno del livello basato su file, i file drop-in e il file base vengono uniti insieme.
   • Gli host di incorporamento come Claude Desktop possono fornire politica tramite l’opzione SDK managedSettings. Per impostazione predefinita, questo viene ignorato quando è presente una fonte gestita distribuita da un amministratore: impostazioni gestite dal server, una politica MDM o a livello di sistema operativo, o un file di impostazioni gestite. Il fallback del registro HKCU scrivibile dall’utente non conta come una fonte gestita distribuita da un amministratore. Gli amministratori possono acconsentire impostando parentSettingsBehavior a "merge". I valori dell’embedder vengono filtrati in modo che possano stringere la politica gestita ma non allentarla.
2. Argomenti della riga di comando
   • Override temporanei per una sessione specifica. JSON passato tramite --settings <file-or-json> si unisce con le impostazioni basate su file utilizzando le stesse regole degli altri livelli: una chiave impostata qui ignora la stessa chiave nelle impostazioni locale, di progetto o utente, e omettere una chiave lascia il valore del livello inferiore in posizione
3. Impostazioni di progetto locale (.claude/settings.local.json)
   • Impostazioni personali specifiche del progetto
4. Impostazioni di progetto condivise (.claude/settings.json)
   • Impostazioni di progetto condivise dal team nel controllo del codice sorgente
5. Impostazioni utente (~/.claude/settings.json)
   • Impostazioni globali personali

​

Verifica le impostazioni attive

​

Punti chiave sul sistema di configurazione

• File di memoria (CLAUDE.md): Contengono istruzioni e contesto che Claude carica all’avvio
• File di impostazioni (JSON): Configurano permessi, variabili di ambiente e comportamento dello strumento
• Skills: Prompt personalizzati che possono essere invocati con /skill-name o caricati automaticamente da Claude
• MCP server: Estendono Claude Code con strumenti e integrazioni aggiuntivi
• Precedenza: Le configurazioni di livello superiore (Managed) ignorano quelle di livello inferiore (User/Project)
• Ereditarietà: Le impostazioni vengono unite tra gli ambiti; i valori scalari da ambiti con priorità più alta ignorano, e gli array si concatenano, con due eccezioni descritte nella Nota di unione di array

​

Prompt di sistema

​

Esclusione di file sensibili

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Read(./build)"
    ]
  }
}

​

Configurazione subagent

• Subagent utente: ~/.claude/agents/, disponibili in tutti i tuoi progetti
• Subagent di progetto: .claude/agents/, specifici del tuo progetto e condivisibili con il tuo team

​

Configurazione plugin

​

Impostazioni plugin

{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  }
}

​

enabledPlugins

• Impostazioni utente (~/.claude/settings.json): Preferenze personali dei plugin
• Impostazioni di progetto (.claude/settings.json): Plugin specifici del progetto condivisi con il team
• Impostazioni locali (.claude/settings.local.json): Override per macchina, gitignored quando Claude Code lo crea
• Impostazioni gestite (managed-settings.json): Override della politica a livello organizzativo che blocca l’installazione in tutti gli ambiti e nasconde il plugin dal marketplace

{
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true,
    "experimental-features@personal": false
  }
}

​

extraKnownMarketplaces

1. I membri del team vengono invitati a installare il marketplace quando fidano della cartella
2. I membri del team vengono quindi invitati a installare i plugin da quel marketplace
3. Gli utenti possono saltare i marketplace o i plugin indesiderati (archiviati nelle impostazioni utente)
4. L’installazione rispetta i confini di fiducia e richiede il consenso esplicito

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/security/plugins.git"
      }
    }
  }
}

• github: Repository GitHub (utilizza repo)
• git: Qualsiasi URL git (utilizza url)
• directory: Percorso del filesystem locale (utilizza path, solo per lo sviluppo)
• hostPattern: Modello regex per abbinare gli host del marketplace (utilizza hostPattern)
• settings: marketplace inline dichiarato direttamente in settings.json senza un repository ospitato separato (utilizza name e plugins)

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "settings",
        "name": "team-tools",
        "plugins": [
          {
            "name": "code-formatter",
            "source": {
              "source": "github",
              "repo": "acme-corp/code-formatter"
            }
          }
        ]
      }
    }
  }
}

​

strictKnownMarketplaces

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux e WSL: /etc/claude-code/managed-settings.json
• Windows: C:\Program Files\ClaudeCode\managed-settings.json

• Disponibile solo nelle impostazioni gestite (managed-settings.json)
• Non può essere ignorato da impostazioni utente o di progetto (precedenza più alta)
• Applicato prima delle operazioni di rete e filesystem, quindi le fonti bloccate non vengono mai eseguite
• Utilizza la corrispondenza esatta per le specifiche della fonte (incluso ref, path per le fonti git), tranne hostPattern e pathPattern, che utilizzano la corrispondenza regex

• undefined (predefinito): nessuna restrizione, quindi gli utenti possono aggiungere qualsiasi marketplace
• Array vuoto []: blocco completo, quindi gli utenti non possono aggiungere nuovi marketplace
• Elenco di fonti: gli utenti possono aggiungere solo i marketplace che corrispondono esattamente

1. Repository GitHub:

{ "source": "github", "repo": "acme-corp/approved-plugins" }
{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }

2. Repository Git:

{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }
{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }
{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }

3. Marketplace basati su URL:

{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }
{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }

4. Pacchetti NPM:

{ "source": "npm", "package": "@acme-corp/claude-plugins" }
{ "source": "npm", "package": "@acme-corp/approved-marketplace" }

5. Percorsi di file:

{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }

6. Percorsi di directory:

{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }

7. Corrispondenza del modello host:

{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com$" }

• github: corrisponde sempre a github.com
• git: estrae il nome host dall’URL (supporta sia i formati HTTPS che SSH)
• url: estrae il nome host dall’URL
• npm, file, directory: non supportati per la corrispondenza del modello host

8. Corrispondenza del modello di percorso:

{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }
{ "source": "pathPattern", "pathPattern": ".*" }

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    },
    {
      "source": "npm",
      "package": "@acme-corp/compliance-plugins"
    }
  ]
}

{
  "strictKnownMarketplaces": []
}

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

• Il repo o url deve corrispondere esattamente
• Il campo ref deve corrispondere esattamente (o entrambi non essere definiti)
• Il campo path deve corrispondere esattamente (o entrambi non essere definiti)

// Queste sono DIVERSE fonti:
{ "source": "github", "repo": "acme-corp/plugins" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }

// Anche queste sono DIVERSE:
{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }
{ "source": "github", "repo": "acme-corp/plugins" }

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ]
}

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ],
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

• Le restrizioni vengono controllate prima di qualsiasi richiesta di rete o operazione del filesystem
• Quando bloccato, gli utenti vedono messaggi di errore chiari che indicano che la fonte è bloccata dalla politica gestita
• La restrizione si applica all’aggiunta del marketplace e all’installazione, aggiornamento, aggiornamento e auto-aggiornamento dei plugin. Un marketplace aggiunto prima che la politica fosse impostata non può essere utilizzato per installare o aggiornare plugin una volta che la sua fonte non corrisponde più all’elenco di autorizzazione
• Le impostazioni gestite hanno la precedenza più alta e non possono essere ignorate

​

strictPluginOnlyCustomization

{
  "strictPluginOnlyCustomization": ["skills", "hooks"]
}

​

Gestione dei plugin

• Sfoglia i plugin disponibili dai marketplace
• Installa/disinstalla plugin
• Abilita/disabilita plugin
• Visualizza i dettagli del plugin (skills, agenti, hooks forniti)
• Aggiungi/rimuovi marketplace

​

Variabili di ambiente

​

Strumenti disponibili per Claude

​

Vedi anche

• Permissions: sistema di permessi, sintassi delle regole, modelli specifici dello strumento e politiche gestite
• Authentication: configura l’accesso degli utenti a Claude Code
• Debug your configuration: diagnostica il motivo per cui un’impostazione, un hook o un server MCP non sta avendo effetto
• Troubleshoot installation and login: installazione, autenticazione e problemi di piattaforma