Distribuire impostazioni gestite

​

Distribuire un file di impostazioni gestite

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true
}

​

Scegli un meccanismo di consegna

• Delivery controls: policyHelper, wslInheritsWindowsSettings, e managedSourcesBehavior
• Gateway login keys: forceLoginGatewayUrl e il valore "gateway" di forceLoginMethod

​

Dove e quando una policy si applica

• Surfaces: sulla macchina dello sviluppatore, il terminale, le estensioni VS Code e JetBrains, la scheda Code dell’app desktop, e le sessioni Agent SDK leggono tutte queste fonti. Le sessioni Agent SDK caricano impostazioni gestite anche quando settingSources esclude i file utente, progetto e locale.
• Cloud sessions: una sessione in un ambiente ospitato da Anthropic non legge un profilo MDM o file del dispositivo, quindi la policy per essa deve provenire da impostazioni server-managed. Una sessione in un ambiente auto-ospitato legge anche il file di impostazioni gestite nella sua immagine runner, per impostazione predefinita solo quando le impostazioni server-managed non distribuiscono una chiave di policy, a parte le chiavi che Claude Code legge da ogni fonte admin. How Claude Code combines managed sources copre l’opt-in che applica entrambi.
• Cowork sessions: Cowork nell’app Claude Desktop esegue le sue sessioni su Claude Code. In una sessione Cowork, Claude Code non recupera mai impostazioni server-managed dalla console admin claude.ai, anche quando l’utente accede con un account Team o Enterprise, quindi quale policy si applica dipende da dove viene eseguita la sessione:
  • Sulla macchina dell’utente: per impostazione predefinita, Claude Code in una sessione Cowork legge la policy MDM o a livello di sistema operativo e il file di impostazioni gestite su quel dispositivo, quindi distribuisci la policy lì.
  • In una sandbox VM completa: quando la tua configurazione gestita di Claude Desktop imposta requireCoworkFullVmSandbox, Claude Code viene eseguito all’interno di una macchina virtuale dove la policy MDM del dispositivo e il file di impostazioni gestite non sono presenti.
  • Remote Cowork sessions: queste vengono eseguite su VM gestite da Anthropic, dove Claude Code non ha policy del dispositivo da leggere.
  La tabella surface coverage confronta Cowork con le altre surface.
• Running sessions: la maggior parte dei cambiamenti raggiunge una sessione in esecuzione secondo la pianificazione nella tabella del meccanismo di consegna, senza un riavvio.
  • I cambiamenti a forceRemoteSettingsRefresh, requiredMinimumVersion, e alcune chiavi modificabili dall’utente hanno effetto al prossimo avvio della sessione.
  • Una voce policyHelper nuova o modificata ha effetto al prossimo avvio, tranne che un helper oscurato all’avvio da impostazioni server-managed viene eseguito non appena un fetch segnala che quelle impostazioni sono state rimosse.
• Changes that need approval: a parte gli aggiornamenti che aspettano il prossimo avvio, un cambiamento server-managed a un’impostazione che ha bisogno di approvazione, come un hook o una variabile env, aspetta che lo sviluppatore accetti la finestra di dialogo in una sessione interattiva, e si applica per l’esecuzione corrente in una sessione che un’estensione IDE o l’Agent SDK ospita. Gli altri cambiamenti server-managed si applicano al prossimo polling.
• Long-lived sessions: una sessione lasciata aperta per settimane può ancora rimanere indietro rispetto a un rollout. requiredMinimumVersion blocca un binario obsoleto dall’avvio e non termina una sessione già in esecuzione.

​

Dove ogni meccanismo archivia la policy

• Server-managed: i server di Anthropic, o il tuo gateway, contengono la policy. Claude Code mantiene una cache locale che applica all’avvio e sostituisce ad ogni fetch riuscito.
• macOS configuration profile: il dominio delle preferenze gestite com.anthropic.claudecode. Usa le stesse chiavi di livello superiore di managed-settings.json, con impostazioni nidificate come dizionari e liste come array plist.
• Windows HKLM registry: il JSON come valore REG_SZ o REG_EXPAND_SZ denominato Settings sotto HKLM\SOFTWARE\Policies\ClaudeCode.
• File-based: managed-settings.json, una directory opzionale managed-settings.d/, e managed-mcp.json nella directory di sistema: /Library/Application Support/ClaudeCode/ su macOS, /etc/claude-code/ su Linux e WSL, e C:\Program Files\ClaudeCode\ su Windows. Claude Code non legge il percorso Windows legacy C:\ProgramData\ClaudeCode\managed-settings.json.
• Windows HKCU registry: lo stesso valore Settings sotto HKCU\SOFTWARE\Policies\ClaudeCode.

​

Dividi una policy basata su file tra i team

• Single values, come "model": "opus" o "cleanupPeriodDays": 7: il valore del file successivo sostituisce quello precedente
• Lists, come permissions.deny o sandbox.network.allowedDomains: le due liste si combinano, con i duplicati rimossi
• Nested blocks, come env o sandbox: i due blocchi si uniscono chiave per chiave, e ogni chiave all’interno segue queste stesse regole
• fallbackModel: la catena successiva sostituisce quella precedente completamente
• extraKnownMarketplaces e managedMcpServers: una voce successiva con lo stesso nome sostituisce quella precedente completamente
• modelPicker: la lineup successiva sostituisce quella precedente completamente

​

Come Claude Code combina le fonti gestite

• "first-wins", l’impostazione predefinita: Claude Code usa la fonte con il ranking più alto che distribuisce almeno una chiave di policy e ignora il resto piuttosto che unirle, a parte le poche chiavi in Keys read from every admin source. Claude Code non mostra alcun avviso per le fonti che salta; /status nomina la fonte che ha usato e quelle che ha saltato.
• "merge": Claude Code applica ogni fonte admin che distribuisce una chiave di policy e le combina per tipo di chiave: sulla maggior parte delle chiavi il valore della fonte con ranking più alto si applica, le liste si uniscono, e i lock prendono il valore più restrittivo. Compose every managed source dice dove impostare la chiave e come ogni tipo di chiave si combina. Richiede Claude Code v2.1.242 o successivo.

• Policy key: qualsiasi chiave di impostazioni diversa dalle due chiavi di controllo, wslInheritsWindowsSettings e managedSourcesBehavior. Un file di impostazioni gestite o una policy MDM che contiene solo quelli non conta, e Claude Code passa alla fonte successiva.
• Admin source: una delle prime tre fonti sottostanti. Il registro HKCU è scrivibile dall’utente e non è uno.

1. Impostazioni remote, consegnate da claude.ai come server-managed settings o da un Claude apps gateway. Claude Code recupera questa fonte solo quando la sessione si autentica all’API di Anthropic direttamente con un login o chiave idonei, o accede a un gateway con /login. Su altri provider, o quando ANTHROPIC_BASE_URL punta da qualche parte diversa dall’API di Anthropic, inizia dalla fonte successiva
2. Policy MDM o a livello di sistema operativo: il plist macOS o la chiave di registro HKLM
3. File di impostazioni gestite, managed-settings.d/*.json e managed-settings.json uniti insieme
4. Il registro HKCU, su Windows, e su WSL una volta che il registro HKLM o il file di impostazioni gestite Windows attiva wslInheritsWindowsSettings e il valore HKCU lo imposta anche. Claude Code lo legge solo quando nessuna fonte sopra di esso distribuisce una chiave di policy e nessuna host-supplied parent settings fornisce una chiave restrittiva

​

Chiavi lette da ogni fonte admin

• sandbox.network.allowManagedDomainsOnly e sandbox.filesystem.allowManagedReadPathsOnly: un true in qualsiasi fonte admin attiva il lock. Mentre un lock è attivo, Claude Code unisce l’allowlist che blocca, sandbox.network.allowedDomains insieme alle regole di autorizzazione WebFetch(domain:...), o sandbox.filesystem.allowRead, attraverso ogni fonte admin. Senza il lock, Claude Code tratta l’allowlist come qualsiasi altra chiave, quindi sotto "first-wins" l’allowlist di una fonte admin non selezionata viene ignorata
• allowAllClaudeAiMcps
• I percorsi binari sandbox sandbox.bwrapPath e sandbox.socatPath
• Il binario sandbox ripgrep, sandbox.ripgrep
• sandbox.filesystem.disabled e sandbox.network.strictAllowlist
• useAutoModeDuringPlan e syncClaudeAiSkills, dove un false da qualsiasi fonte admin disattiva il comportamento. Un false nelle impostazioni utente o locale dello sviluppatore lo disattiva anche; ogni chiave può solo negare
• enableArtifact, dove un false da qualsiasi fonte admin disattiva lo Artifact tool. Un false nelle impostazioni utente, progetto o locale dello sviluppatore lo disattiva anche, e nessuna fonte lo riattiva; vedi which lower-level values still count. Richiede Claude Code v2.1.242 o successivo
• Un opt-out di commit-trailer in attribution, o nel deprecato includeCoAuthoredBy, da qualsiasi livello
• forceRemoteSettingsRefresh
• env, unito per variabile attraverso le fonti admin: ogni variabile proviene dalla fonte con priorità più alta che la definisce, quindi le fonti inferiori riempiono le variabili che quelle superiori lasciano non impostate. Poche variabili seguono le loro stesse regole; Per-key exceptions across managed sources nomina ognuna. Richiede Claude Code v2.1.223 o successivo. Prima di v2.1.223, Claude Code applicava solo il blocco env completo della fonte selezionata

​

Componi ogni fonte gestita

​

Calcola la policy con un programma helper

• L’oggetto managedSettings emesso è l’unica impostazione gestita per la sessione, incluso per le chiavi che altrimenti legge da ogni fonte admin, a parte forceRemoteSettingsRefresh, che ha la sua stessa regola di avvio

​

Lascia che un host di embedding aggiunga policy

• Quando qualsiasi fonte admin imposta allowManagedPermissionRulesOnly, Claude Code elimina le regole di autorizzazione allow fornite da parent e additionalDirectories mentre le legge, anche quando una fonte con ranking più alto lascia la chiave non impostata. L’effetto della chiave sulle tue stesse regole di autorizzazione proviene dalle impostazioni gestite che Claude Code applica, o dalle impostazioni parent che hai scelto di unire
• Claude Code applica il valore forceLoginOrgUUID o allowedMcpServers nelle impostazioni gestite che applica e blocca uno fornito da parent. Un valore in una fonte admin inferiore che Claude Code non applica né si applica né blocca quello del parent. La voce managedSourcesBehavior dice quale fonte fornisce ogni chiave sotto "merge". Prima di v2.1.223, un valore in qualsiasi fonte admin bloccava quello del parent
• Un valore availableModels segue la stessa regola di allowedMcpServers

​

Mantieni l’accesso alla cartella Cowork quando si applicano solo regole gestite

{
  "allowManagedPermissionRulesOnly": true,
  "permissions": {
    "allow": [
      "Edit(~/CoworkProjects/**)"
    ]
  }
}

​

Cosa uno sviluppatore può cambiare

• Il modello per una sessione: un model gestito è un default, non un lock. --model e ANTHROPIC_MODEL scelgono ancora il modello per quella sessione, quindi distribuisci availableModels per limitare la scelta.
• Diritti admin locali: uno sviluppatore che è un amministratore sulla macchina può modificare la fonte gestita stessa, motivo per cui gli strumenti MDM possono ridistribuire il profilo o il file su una pianificazione e motivo per cui il registro HKLM e il dominio delle preferenze gestite macOS esistono.
• La cache server-managed: le impostazioni server-managed provengono dai server di Anthropic, e una modifica alla cache locale dura solo fino al prossimo fetch riuscito.
• Altri strumenti: le impostazioni gestite vincolano solo Claude Code. Uno sviluppatore che chiama l’API da un altro strumento non è sotto di loro.

​

Verifica che una policy sia in vigore

​

Leggi la fonte in /status

• (remote): impostazioni server-managed da claude.ai o un gateway
• (plist) o (HKLM): una policy MDM o del sistema operativo
• (file), (drop-ins), o (file + drop-ins): managed-settings.json, la directory drop-in, o entrambi
• (remote + file, merged), o un altro elenco che termina in , merged: la tua organizzazione compone ogni fonte gestita, e Claude Code ha unito le fonti elencate nella policy. Una fonte inferiore può ancora fornire variabili env senza apparire nell’elenco. Richiede Claude Code v2.1.242 o successivo
• (HKCU): il fallback del registro scrivibile dall’utente
• (parent process): un host di embedding ha fornito impostazioni restrittive
• (helper): un policyHelper configurato dalla fonte MDM o file selezionata

• La riga manca: Claude Code non ha trovato alcuna fonte gestita che distribuisca una chiave di policy. Se hai distribuito un file di impostazioni gestite, controlla che si trovi al percorso per il sistema operativo e che contenga una chiave di policy piuttosto che solo le chiavi di controllo. Un file che non è JSON valido non produce questo stato; Claude Code rifiuta di avviarsi invece. Quando hai distribuito tramite impostazioni server-managed, esegui claude doctor, che segnala l’esito del fetch.
• La riga nomina una fonte diversa da quella che hai distribuito: una fonte con priorità più alta è presente e Claude Code ha ignorato la tua, e Skipped sources l’elenca. How Claude Code combines managed sources fornisce l’ordine.

​

Trova voci che Claude Code ha eliminato

• File di impostazioni gestite o file drop-in: il file non è JSON valido, o il suo livello superiore non è un oggetto
• MDM plist: il plutil di macOS segnala il plist malformato, o il suo contenuto convertito non è un oggetto JSON
• Valore di registro HKLM: il valore Settings non è una stringa, è vuoto, o non contiene un oggetto JSON

• Un file, profilo, o valore di registro assente non è un fallimento; Claude Code viene eseguito senza quella fonte.
• Un file di impostazioni gestite vuoto conta come {}.
• Un valore malformato nella chiave di registro HKCU scrivibile dall’utente non blocca mai l’avvio. Claude Code lo segnala come un avviso in /status e claude doctor invece.

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

​

Chiavi che falliscono chiuse

​

Chiavi che solo una fonte gestita può impostare

​

Disattivare la telemetria per la vostra organizzazione

{
  "env": {
    "DISABLE_TELEMETRY": "1"
  }
}

​

Vedi anche

• Set up Claude Code for your organization: decidi cosa applicare e come
• Server-managed settings: distribuisci policy dalla console claude.ai o da un gateway
• Managed MCP configuration: controlla quali server MCP gli sviluppatori possono usare
• All settings: ogni chiave, con se una fonte gestita può impostarla
• Example settings files: un managed-settings.json completo che mostra la forma delle chiavi gestite