Impostazioni di Claude Code

Configura Claude Code con impostazioni globali e a livello di progetto, e variabili di ambiente.

Claude Code offre una varietà di impostazioni per configurare il suo comportamento in base alle tue esigenze. Puoi configurare Claude Code eseguendo il comando /config quando utilizzi il REPL interattivo, che apre un'interfaccia Impostazioni con schede dove puoi visualizzare le informazioni di stato e modificare le opzioni di configurazione.

Ambiti di configurazione

Claude Code utilizza un sistema di ambiti per determinare dove si applicano le configurazioni e con chi vengono condivise. Comprendere gli ambiti ti aiuta a decidere come configurare Claude Code per uso personale, collaborazione di team o distribuzione aziendale.

Ambiti disponibili

Quando utilizzare ogni ambito

L'ambito Managed è per:

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

L'ambito User è migliore per:

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

L'ambito Project è migliore per:

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

L'ambito Local è migliore per:

• 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

Quando la stessa impostazione è configurata in più ambiti, gli ambiti più specifici hanno la precedenza:

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

Ad esempio, se un permesso è consentito nelle impostazioni utente ma negato nelle impostazioni di progetto, l'impostazione di progetto ha la precedenza e il permesso è bloccato.

Cosa utilizza gli ambiti

Gli ambiti si applicano a molte funzionalità di Claude Code:

Su Windows, i percorsi mostrati come ~/.claude si risolvono in %USERPROFILE%\.claude.

File di impostazioni

Il file settings.json è il meccanismo ufficiale per configurare Claude Code attraverso impostazioni gerarchiche:

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

    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.

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

La riga $schema nell'esempio sopra punta allo schema JSON ufficiale per le impostazioni di Claude Code. Aggiungerlo al tuo settings.json abilita l'autocompletamento e la convalida inline in VS Code, Cursor e qualsiasi altro editor che supporta la convalida dello schema JSON.

Lo schema pubblicato viene aggiornato periodicamente e potrebbe non includere le impostazioni aggiunte nei rilasci CLI più recenti, quindi un avviso di convalida su un campo documentato di recente non significa necessariamente che la tua configurazione non sia valida.

Impostazioni disponibili

settings.json supporta un numero di opzioni:

Impostazioni di configurazione globale

Queste impostazioni sono archiviate in ~/.claude.json piuttosto che in settings.json. Aggiungerle a settings.json attiverà un errore di convalida dello schema.

Impostazioni worktree

Configura come --worktree crea e gestisce i git worktrees.

Per copiare file gitignored come .env nei nuovi worktrees, usa un file .worktreeinclude nella radice del tuo progetto invece di un'impostazione.

Impostazioni di permesso

Sintassi della regola di permesso

Le regole di permesso seguono il formato Tool o Tool(specifier). Le regole vengono valutate in ordine: prima le regole di negazione, poi di richiesta, poi di autorizzazione. La prima regola corrispondente vince.

Esempi rapidi:

Per il riferimento completo della sintassi delle regole, incluso il comportamento dei caratteri jolly, i modelli specifici dello strumento per Read, Edit, WebFetch, MCP e Agent, e le limitazioni di sicurezza dei modelli Bash, vedi Sintassi della regola di permesso.

Impostazioni sandbox

Configura il comportamento avanzato del sandboxing. Il sandboxing isola i comandi bash dal tuo filesystem e dalla rete. Vedi Sandboxing per i dettagli.

Prefissi di percorso sandbox

I percorsi in filesystem.allowWrite, filesystem.denyWrite, filesystem.denyRead e filesystem.allowRead supportano questi prefissi:

Il prefisso più vecchio //path per i percorsi assoluti funziona ancora. Se in precedenza hai utilizzato il singolo slash /path aspettandoti una risoluzione relativa al progetto, passa a ./path. Questa sintassi differisce dalle regole di permesso Read e Edit, che utilizzano //path per assoluto e /path per relativo al progetto. I percorsi del filesystem sandbox utilizzano convenzioni standard: /tmp/build è un percorso assoluto.

Esempio di configurazione:

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

Le restrizioni del filesystem e della rete possono essere configurate in due modi che vengono uniti insieme:

• 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

Claude Code aggiunge attribuzione ai commit git e alle pull request. Questi vengono configurati separatamente:

• 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

Attribuzione predefinita del commit:

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

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

Attribuzione predefinita della pull request:

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

Esempio:

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

Impostazioni di suggerimento file

Configura un comando personalizzato per l'autocompletamento del percorso del file @. Il suggerimento di file incorporato utilizza l'attraversamento veloce del filesystem, ma i grandi monorepo potrebbero beneficiare dell'indicizzazione specifica del progetto come un indice di file pre-costruito o strumenti personalizzati.

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

Il comando viene eseguito con le stesse variabili di ambiente degli hooks, incluso CLAUDE_PROJECT_DIR. Riceve JSON tramite stdin con un campo query:

{"query": "src/comp"}

Restituisci i percorsi dei file separati da newline a stdout (attualmente limitati a 15):

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

Esempio:

#!/bin/bash
query=$(cat | jq -r '.query')
your-repo-file-index --query "$query" | head -20

Configurazione hook

Queste impostazioni controllano quali hook possono essere eseguiti e a cosa possono accedere gli hook HTTP. L'impostazione allowManagedHooksOnly può essere configurata solo nelle impostazioni gestite. Gli elenchi di autorizzazione degli URL e delle variabili di ambiente possono essere impostati a qualsiasi livello di impostazioni e si uniscono tra le fonti.

Comportamento quando allowManagedHooksOnly è true:

• 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

Limita gli URL degli hook HTTP:

Limita quali URL gli hook HTTP possono indirizzare. Supporta * come carattere jolly per la corrispondenza. Quando l'array è definito, gli hook HTTP che indirizzano URL non corrispondenti vengono silenziosamente bloccati. La corrispondenza del nome host non distingue tra maiuscole e minuscole e ignora un punto FQDN finale, corrispondendo alla semantica DNS.

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

Limita le variabili di ambiente degli hook HTTP:

Limita quali nomi di variabili di ambiente gli hook HTTP possono interpolare nei valori delle intestazioni. L'allowedEnvVars effettivo di ogni hook è l'intersezione del suo elenco e di questa impostazione.

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

Precedenza delle impostazioni

Le impostazioni si applicano in ordine di precedenza. Dal più alto al più basso:

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

Questa gerarchia garantisce che le politiche organizzative siano sempre applicate mentre consente comunque ai team e agli individui di personalizzare la loro esperienza. La stessa precedenza si applica se esegui Claude Code dalla CLI, dall'estensione VS Code, o da un IDE JetBrains.

Ad esempio, se le tue impostazioni utente consentono Bash(npm run *) ma le impostazioni condivise di un progetto lo negano, l'impostazione di progetto ha la precedenza e il comando viene bloccato.

Verifica le impostazioni attive

Esegui /status all'interno di Claude Code per vedere quali fonti di impostazioni sono attive e da dove provengono. L'output mostra ogni livello di configurazione (gestito, utente, progetto) insieme alla sua origine, come Enterprise managed settings (remote), Enterprise managed settings (plist), Enterprise managed settings (HKLM), Enterprise managed settings (HKCU), o Enterprise managed settings (file). Se un file di impostazioni contiene errori, /status segnala il problema in modo che tu possa risolverlo.

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, con impostazioni più specifiche che aggiungono o ignorano quelle più ampie

Prompt di sistema

Il prompt di sistema interno di Claude Code non è pubblicato. Per aggiungere istruzioni personalizzate, usa i file CLAUDE.md o il flag --append-system-prompt.

Esclusione di file sensibili

Per prevenire che Claude Code acceda a file contenenti informazioni sensibili come chiavi API, segreti e file di ambiente, usa l'impostazione permissions.deny nel tuo file .claude/settings.json:

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

Questo sostituisce la configurazione deprecata ignorePatterns. I file che corrispondono a questi modelli vengono esclusi dalla scoperta dei file e dai risultati della ricerca, e le operazioni di lettura su questi file vengono negate.

Configurazione subagent

Claude Code supporta subagent AI personalizzati che possono essere configurati sia a livello utente che di progetto. Questi subagent vengono archiviati come file Markdown con frontmatter YAML:

• 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

I file subagent definiscono assistenti AI specializzati con prompt personalizzati e permessi degli strumenti. Scopri di più sulla creazione e l'utilizzo dei subagent nella documentazione dei subagent.

Configurazione plugin

Claude Code supporta un sistema di plugin che ti consente di estendere la funzionalità con skills, agenti, hooks e MCP servers. I plugin vengono distribuiti tramite marketplace e possono essere configurati sia a livello utente che di repository.

Impostazioni plugin

Impostazioni relative ai plugin in settings.json:

{
  "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

Controlla quali plugin sono abilitati. Formato: "plugin-name@marketplace-name": true/false

Ambiti:

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

Esempio:

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

extraKnownMarketplaces

Definisce marketplace aggiuntivi che dovrebbero essere resi disponibili per il repository. Tipicamente utilizzato nelle impostazioni a livello di repository per garantire che i membri del team abbiano accesso alle fonti di plugin richieste.

Quando un repository include 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

Esempio:

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

Tipi di fonte del marketplace:

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

Usa source: 'settings' per dichiarare un piccolo set di plugin inline senza configurare un repository marketplace ospitato. I plugin elencati qui devono fare riferimento a fonti esterne come GitHub o npm. Devi comunque abilitare ogni plugin separatamente in enabledPlugins.

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

strictKnownMarketplaces

Solo impostazioni gestite: Controlla quali marketplace dei plugin gli utenti possono aggiungere e installare plugin da. Questa impostazione può essere configurata solo nelle impostazioni gestite e fornisce agli amministratori un controllo rigoroso sulle fonti del marketplace.

Posizioni dei file di impostazioni gestite:

• 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

Caratteristiche chiave:

• 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/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 e pathPattern, che utilizzano la corrispondenza regex

Comportamento dell'elenco di autorizzazione:

• 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

Tutti i tipi di fonte supportati:

L'elenco di autorizzazione supporta più tipi di fonte del marketplace. La maggior parte delle fonti utilizza la corrispondenza esatta, mentre hostPattern e pathPattern utilizzano la corrispondenza regex rispetto all'host del marketplace e al percorso del filesystem rispettivamente.

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

Campi: repo (obbligatorio), ref (facoltativo: ramo/tag/SHA), path (facoltativo: sottodirectory)

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

Campi: url (obbligatorio), ref (facoltativo: ramo/tag/SHA), path (facoltativo: sottodirectory)

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

Campi: url (obbligatorio), headers (facoltativo: intestazioni HTTP per l'accesso autenticato)

4. Pacchetti NPM:

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

Campi: package (obbligatorio, supporta pacchetti con scope)

5. Percorsi di file:

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

Campi: path (obbligatorio: percorso assoluto al file marketplace.json)

6. Percorsi di directory:

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

Campi: path (obbligatorio: percorso assoluto alla directory contenente .claude-plugin/marketplace.json)

7. Corrispondenza del modello host:

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

Campi: hostPattern (obbligatorio: modello regex per abbinare l'host del marketplace)

Utilizza la corrispondenza del modello host quando desideri consentire tutti i marketplace da un host specifico senza enumerare ogni repository individualmente. Questo è utile per le organizzazioni con server GitHub Enterprise o GitLab interni dove gli sviluppatori creano i loro marketplace.

Estrazione dell'host per tipo di fonte:

• 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": ".*" }

Campi: pathPattern (obbligatorio: modello regex abbinato al campo path delle fonti file e directory)

Utilizza la corrispondenza del modello di percorso per consentire marketplace basati su filesystem insieme alle restrizioni hostPattern per le fonti di rete. Imposta ".*" per consentire tutti i percorsi locali, o un modello più ristretto per limitare a directory specifiche.

Esempi di configurazione:

Esempio: consenti solo marketplace specifici:

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

Esempio - Disabilita tutte le aggiunte del marketplace:

{
  "strictKnownMarketplaces": []
}

Esempio: consenti tutti i marketplace da un server git interno:

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

Requisiti di corrispondenza esatta:

Le fonti del marketplace devono corrispondere esattamente affinché l'aggiunta di un utente sia consentita. Per le fonti basate su git (github e git), questo include tutti i campi facoltativi:

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

Esempi di fonti che NON corrispondono:

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

Confronto con extraKnownMarketplaces:

Differenza di formato:

strictKnownMarketplaces utilizza oggetti fonte diretti:

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

extraKnownMarketplaces richiede marketplace denominati:

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

Utilizzo di entrambi insieme:

strictKnownMarketplaces è un gate di politica: controlla cosa gli utenti possono aggiungere ma non registra alcun marketplace. Per limitare e pre-registrare un marketplace per tutti gli utenti, imposta entrambi in managed-settings.json:

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

Con solo strictKnownMarketplaces impostato, gli utenti possono comunque aggiungere il marketplace consentito manualmente tramite /plugin marketplace add, ma non è disponibile automaticamente.

Note importanti:

• 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

Vedi Restrizioni del marketplace gestito per la documentazione rivolta agli utenti.

Gestione dei plugin

Usa il comando /plugin per gestire i plugin in modo interattivo:

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

Scopri di più sul sistema di plugin nella documentazione dei plugin.

Variabili di ambiente

Le variabili di ambiente ti consentono di controllare il comportamento di Claude Code senza modificare i file di impostazioni. Qualsiasi variabile può anche essere configurata in settings.json sotto la chiave env per applicarla a ogni sessione o distribuirla al tuo team.

Vedi il riferimento delle variabili di ambiente per l'elenco completo.

Strumenti disponibili per Claude

Claude Code ha accesso a un set di strumenti per leggere, modificare, cercare, eseguire comandi e orchestrare subagent. I nomi degli strumenti sono le stringhe esatte che utilizzi nelle regole di permesso e nei matcher degli hook.

Vedi il riferimento degli strumenti per l'elenco completo e i dettagli del comportamento dello strumento Bash.

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