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 su tutti i progetti
• Chiavi API e autenticazione (archiviate in modo sicuro)

• Impostazioni condivise dal team (permessi, hook, server MCP)
• 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. Gestito (massima) - non può essere ignorato da nulla
2. Argomenti della riga di comando - override temporanei della sessione
3. Locale - ignora le impostazioni di progetto e utente
4. Progetto - ignora le impostazioni utente
5. Utente (minima) - 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 file managed-settings.json e managed-mcp.json che possono essere distribuiti alle directory di sistema:
  • macOS: /Library/Application Support/ClaudeCode/
  • Linux e WSL: /etc/claude-code/
  • Windows: C:\Program Files\ClaudeCode\
  Questi sono percorsi a livello di sistema (non directory home dell’utente come ~/Library/...) che richiedono privilegi di amministratore. Sono progettati per essere distribuiti da amministratori IT.
  Vedi Impostazioni gestite e Configurazione MCP gestita per i dettagli.
  Le distribuzioni gestite possono anche limitare aggiunte al 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 del server MCP per ambiti utente e locale, stato per progetto (strumenti consentiti, impostazioni di fiducia) e varie cache. I server MCP con ambito di progetto sono archiviati separatamente in .mcp.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 dei permessi

​

Sintassi della regola di permesso

​

Ordine di valutazione delle regole

1. Regole Deny vengono controllate per prime
2. Regole Ask vengono controllate per seconde
3. Regole Allow vengono controllate per ultime

​

Corrispondenza di tutti gli usi di uno strumento

​

Utilizzo di specifier per il controllo granulare

​

Pattern con wildcard

{
  "permissions": {
    "allow": [
      "Bash(npm run:*)",
      "Bash(git commit:*)",
      "Bash(docker compose:*)"
    ],
    "deny": [
      "Bash(git push:*)",
      "Bash(rm -rf:*)"
    ]
  }
}

{
  "permissions": {
    "allow": [
      "Bash(git * main)",
      "Bash(* --version)"
    ]
  }
}

​

Impostazioni della sandbox

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "network": {
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "deny": [
      "Read(.envrc)",
      "Read(~/.aws/**)"
    ]
  }
}

• Utilizza le regole di negazione Read per bloccare Claude dalla lettura di file o directory specifici
• Utilizza le regole di consentimento Edit per consentire a Claude di scrivere in directory oltre la directory di lavoro corrente
• Utilizza le regole di negazione Edit per bloccare le scritture in percorsi specifici
• Utilizza le regole di consentimento/negazione WebFetch per controllare quali domini di rete Claude può accedere

​

Impostazioni di attribuzione

• I commit utilizzano git trailer (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.5 <[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 degli hook

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

{
  "allowManagedHooksOnly": true
}

​

Precedenza delle impostazioni

1. Impostazioni gestite (managed-settings.json)
   • Politiche distribuite da IT/DevOps alle directory di sistema
   • Non possono essere ignorate dalle impostazioni utente o di progetto
2. Argomenti della riga di comando
   • Override temporanei per una sessione specifica
3. Impostazioni di progetto locale (.claude/settings.local.json)
   • Impostazioni di progetto personali specifiche
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

​

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 d’ambiente e comportamento dello strumento
• Skill: Prompt personalizzati che possono essere invocati con /skill-name o caricati automaticamente da Claude
• Server MCP: Estendono Claude Code con strumenti e integrazioni aggiuntivi
• Precedenza: Le configurazioni di livello superiore (Gestite) ignorano quelle di livello inferiore (Utente/Progetto)
• Eredità: 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 dei subagenti

• Subagenti utente: ~/.claude/agents/ - Disponibili su tutti i tuoi progetti
• Subagenti di progetto: .claude/agents/ - Specifici per il tuo progetto e possono essere condivisi con il tuo team

​

Configurazione dei plugin

​

Impostazioni dei 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)

​

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 dalle impostazioni utente o di progetto (massima precedenza)
• 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)

• 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 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" }

{
  "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": []
}

• Il repo o url deve corrispondere esattamente
• Il campo ref deve corrispondere esattamente (o entrambi essere non definiti)
• Il campo path deve corrispondere esattamente (o entrambi essere non 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" }
    }
  }
}

• Le restrizioni vengono controllate PRIMA di qualsiasi richiesta di rete o operazione di filesystem
• Quando bloccate, 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 massima precedenza 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 d’ambiente

​

Strumenti disponibili per Claude

​

Comportamento dello strumento Bash

• La directory di lavoro persiste: Quando Claude cambia la directory di lavoro (ad esempio, cd /path/to/dir), i successivi comandi Bash verranno eseguiti in quella directory. Puoi utilizzare CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 per ripristinare la directory del progetto dopo ogni comando.
• Le variabili d’ambiente NON persistono: Le variabili d’ambiente impostate in un comando Bash (ad esempio, export MY_VAR=value) non sono disponibili nei successivi comandi Bash. Ogni comando Bash viene eseguito in un ambiente shell fresco.

conda activate myenv
# o: source /path/to/venv/bin/activate
claude

export CLAUDE_ENV_FILE=/path/to/env-setup.sh
claude

conda activate myenv
# o: source /path/to/venv/bin/activate
# o: export MY_VAR=value

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{
        "type": "command",
        "command": "echo 'conda activate myenv' >> \"$CLAUDE_ENV_FILE\""
      }]
    }]
  }
}

​

Estensione degli strumenti con hook

​

Vedi anche

• Identity and Access Management - Panoramica del sistema di permessi e come interagiscono le regole allow/ask/deny
• Regole di permesso specifiche dello strumento - Pattern dettagliati per gli strumenti Bash, Read, Edit, WebFetch, MCP e Task, incluse le limitazioni di sicurezza
• Impostazioni gestite - Configurazione della politica gestita per le organizzazioni
• Risoluzione dei problemi - Soluzioni per i problemi di configurazione comuni