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. Claude Code configurerà git per ignorare .claude/settings.local.json quando viene creato.
• 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 dai server di Anthropic tramite la console di amministrazione Claude.ai. 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 (distribuito tramite profili di configurazione in Jamf, Kandji o altri strumenti MDM)
    • 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.
  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 le tue preferenze (tema, impostazioni di notifica, modalità editor), 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"
  ]
}

​

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"],
      "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

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

   Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

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

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <[email protected]>",
    "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')
your-repo-file-index --query "$query" | head -20

​

Configurazione hook

• Gli hook gestiti e gli hook SDK vengono caricati
• Gli hook utente, di progetto e di plugin vengono bloccati

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

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

​

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 è: gestite dal server > politiche MDM/a livello di sistema operativo > file-based (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. All’interno del livello file-based, i file drop-in e il file base vengono uniti insieme.
2. Argomenti della riga di comando
   • Override temporanei per una sessione specifica
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 servers: 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, con impostazioni più specifiche che aggiungono o ignorano quelle più ampie

​

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 possono essere condivisi 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": "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 (non committati)

{
  "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 nessun’altra impostazione (precedenza più alta)
• Applicato PRIMA delle operazioni di rete/filesystem (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, che utilizza la corrispondenza regex

• undefined (predefinito): Nessuna restrizione - gli utenti possono aggiungere qualsiasi marketplace
• Array vuoto []: Blocco completo - 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://[email protected]/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

{
  "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 solo all’aggiunta di NUOVI marketplace; i marketplace precedentemente installati rimangono accessibili
• Le impostazioni gestite hanno la precedenza più alta e non possono essere ignorate

​

Gestione dei plugin

• Sfoglia i plugin disponibili dai marketplace
• Installa/disinstalla plugin
• Abilita/disabilita plugin
• Visualizza i dettagli del plugin (comandi, agenti, hook 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
• Troubleshooting: soluzioni per i problemi di configurazione comuni