SpyBara
Go Premium

server-managed-settings.md 2026-10-06 23:59 UTC to 2026-10-07 20:01 UTC

This page contains 96 additions and 96 deletions.

2026
Thu 1 23:59 Sun 4 23:58 Wed 7 20:57

Configurare le impostazioni gestite dal server

Configurare centralmente Claude Code per la vostra organizzazione tramite impostazioni consegnate dal server, senza richiedere infrastrutture di gestione dei dispositivi.

Le impostazioni gestite dal server consentono ai proprietari dell'organizzazione di configurare centralmente Claude Code da Organization settings > Claude Code > Managed settings nella console claude.ai. I client di Claude Code recuperano automaticamente queste impostazioni quando gli utenti si autenticano con una credenziale idonea su una piattaforma dove la consegna gestita dal server è supportata. Consulta Disponibilità della piattaforma per le credenziali e le piattaforme che si qualificano.

Requisiti

Per utilizzare le impostazioni gestite dal server, è necessario:

  • Piano Claude for Teams o Claude for Enterprise
  • Il ruolo di Owner o Primary Owner nella vostra organizzazione Claude, per visualizzare e modificare la configurazione
  • Accesso di rete a api.anthropic.com

Scegliere tra impostazioni gestite dal server e gestite dall'endpoint

Claude Code supporta due approcci per la configurazione centralizzata. Le impostazioni gestite dal server forniscono la configurazione dai server di Anthropic. Le impostazioni gestite dall'endpoint vengono distribuite direttamente ai dispositivi tramite criteri nativi del sistema operativo (preferenze gestite macOS, registro Windows) o file di impostazioni gestiti.

Approccio Ideale per Modello di sicurezza
Impostazioni gestite dal server Organizzazioni senza MDM, o utenti su dispositivi non gestiti Impostazioni che Claude Code recupera dai server di Anthropic all'avvio e aggiorna ogni ora durante la sessione
Impostazioni gestite dall'endpoint Organizzazioni con MDM o gestione degli endpoint Impostazioni distribuite ai dispositivi tramite profili di configurazione MDM, criteri del registro, o file di impostazioni gestiti

Se i vostri dispositivi sono registrati in una soluzione MDM o di gestione degli endpoint, le impostazioni gestite dall'endpoint forniscono garanzie di sicurezza più forti perché il file di impostazioni può essere protetto dalla modifica dell'utente a livello del sistema operativo. Le impostazioni gestite dall'endpoint non raggiungono le sessioni cloud negli ambienti ospitati da Anthropic, quindi le organizzazioni i cui sviluppatori eseguono sessioni cloud dovrebbero configurare anche le impostazioni gestite dal server. Le sessioni in un ambiente self-hosted leggono anche il file di impostazioni gestite nell'immagine del runner. La precedenza delle impostazioni di seguito indica quando quel file si applica.

Configurare le impostazioni gestite dal server

1

Aprire la console di amministrazione

Nella console claude.ai, vai a Organization settings > Claude Code > Managed settings.

In un'organizzazione Team o Enterprise, se la pagina indica che non hai accesso, chiedi a un Owner o Primary Owner di apportare la modifica.

2

Definire le impostazioni

Aggiungi la configurazione come JSON. Tutte le impostazioni disponibili in settings.json sono supportate eccetto quelle limitate alla distribuzione delle politiche a livello del sistema operativo; consulta Limitazioni attuali per questo breve elenco. Questo include hook, variabili d'ambiente e impostazioni solo gestite come allowManagedPermissionRulesOnly.

Questo esempio applica un elenco di negazione delle autorizzazioni, impedisce agli utenti di ignorare le autorizzazioni e limita le regole di autorizzazione a quelle definite nelle impostazioni gestite. La regola Bash(curl *) corrisponde a curl come Claude lo scrive, non a /usr/bin/curl o sh -c 'curl …'; per l'applicazione della rete che non dipende dal testo del comando, aggiungere un blocco sandbox con allowManagedDomainsOnly.

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

Gli hook utilizzano lo stesso formato di settings.json.

Questo esempio esegue uno script di audit dopo ogni modifica di file in tutta l'organizzazione:

{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "/usr/local/bin/audit-edit.sh" }
]
}
]
}
}

Poiché gli hook eseguono comandi shell, gli utenti in sessioni interattive vedono una finestra di dialogo di approvazione della sicurezza prima che Claude Code li applichi.

Per configurare il classificatore della modalità auto in modo che conosca quali repository, bucket e domini la vostra organizzazione ritiene affidabili, fornire un blocco autoMode nello stesso modo; vedere Configurare la modalità auto per come le voci autoMode influenzano ciò che il classificatore blocca e avvertimenti importanti sui campi environment, allow, soft_deny e hard_deny.

3

Salvare e distribuire

Salvare le modifiche. I client di Claude Code ricevono le impostazioni aggiornate al prossimo avvio o ciclo di polling orario.

Verificare la consegna delle impostazioni

Per confermare che le impostazioni vengono applicate, chiedere a un utente di riavviare Claude Code. Se la configurazione include impostazioni che attivano la finestra di dialogo di approvazione della sicurezza, l'utente vede un prompt che descrive le impostazioni gestite la prossima volta che Claude Code le recupera: al prossimo avvio, o entro un'ora in una sessione interattiva in esecuzione. È inoltre possibile verificare che le regole di autorizzazione gestite siano attive facendo eseguire a un utente /permissions per visualizzare le regole di autorizzazione effettive.

Per verificare il risultato del recupero su una macchina specifica, fare in modo che l'utente esegua claude doctor e legga la riga Managed settings (remote). Richiede Claude Code v2.1.248 o successivo. La riga segnala uno di quattro risultati:

  • Le impostazioni consegnate sono state caricate
  • La vostra organizzazione non ha impostazioni gestite dal server configurate
  • Il recupero non è riuscito, con la causa e se una politica memorizzata nella cache si applica ancora
  • Claude Code ha saltato il recupero, con il motivo. Vedere Disponibilità della piattaforma per i provider e le configurazioni che lo saltano

Mentre il recupero è ancora in corso, la riga segnala questo invece.

In una sessione in esecuzione, /status mostra la stessa riga dopo un recupero non riuscito, e per alcune cause di recupero saltato, come una variabile del provider di terze parti o un ANTHROPIC_BASE_URL personalizzato esportato nella shell dell'utente.

Controllo di accesso

I seguenti ruoli possono gestire le impostazioni gestite dal server:

  • Primary Owner
  • Owner

Limitare l'accesso al personale di fiducia, poiché le modifiche alle impostazioni si applicano a tutti gli utenti dell'organizzazione.

Impostazioni solo gestite

La maggior parte delle chiavi di impostazioni funzionano in qualsiasi ambito. Un numero limitato di chiavi viene letto solo dalle impostazioni gestite e non ha alcun effetto quando posizionato nei file di impostazioni dell'utente o del progetto. Vedere impostazioni solo gestite per i controlli di autorizzazione e plugin, o leggere la colonna Scope dell'indice Tutte le impostazioni per l'insieme completo.

Limitazioni attuali

Le impostazioni gestite dal server hanno le seguenti limitazioni:

  • Le impostazioni si applicano uniformemente a tutti gli utenti dell'organizzazione. Le configurazioni per gruppo non sono ancora supportate.

  • Non è possibile distribuire un file managed-mcp.json tramite impostazioni gestite dal server. Distribuire invece le chiavi di politica allowedMcpServers e deniedMcpServers lì. Su Claude Code v2.1.259 o successivo, è inoltre possibile fornire server remoti con managedMcpServers, che accetta solo server http e sse e non assume il controllo esclusivo come fa il file.

    Claude Code legge un file managed-mcp.json distribuito nel suo percorso di sistema separatamente dal livello delle impostazioni gestite, quindi il file si applica ancora quando le impostazioni gestite dal server sono in vigore.

  • Le impostazioni limitate alle fonti delle politiche a livello del sistema operativo, come policyHelper e wslInheritsWindowsSettings, non vengono rispettate. Distribuirle invece tramite MDM o un file managed-settings.json di sistema. Un policyHelper distribuito in questo modo viene eseguito solo quando la sua fonte è quella selezionata in precedenza all'interno del livello gestito.

Distribuzione delle impostazioni

Precedenza delle impostazioni

Le impostazioni gestite dal server e le impostazioni gestite dall'endpoint occupano entrambe il livello più alto nella gerarchia delle impostazioni di Claude Code. Una chiave che imposti qui ha la precedenza sulla stessa chiave nei file di impostazioni dell'utente o in un valore --settings, salvo le eccezioni alla precedenza delle impostazioni gestite.

All'interno del livello gestito, Claude Code usa per impostazione predefinita la prima origine che fornisce almeno una chiave di policy, controllando prima le impostazioni gestite dal server e poi quelle gestite dall'endpoint, salvo le chiavi di eccezione descritte di seguito. Come Claude Code combina le origini gestite riporta la classifica completa, l'eccezione per le chiavi di controllo e l'opzione che applica tutte le origini.

Se l'origine selezionata è una policy MDM o un file di impostazioni gestite il cui policyHelper fornisce impostazioni gestite, l'output dell'helper sostituisce quell'origine come unica configurazione gestita per l'esecuzione. Claude Code non consulta un policyHelper configurato nelle impostazioni MDM o basate su file mentre le impostazioni gestite dal server forniscono una chiave di policy.

Se un recupero successivo rileva che le impostazioni gestite dal server sono state rimosse, Claude Code esegue subito quell'helper invece di attendere l'avvio successivo. La voce policyHelper descrive cosa succede quando quell'esecuzione non riesce.

Se cancelli la configurazione gestita dal server nella console di amministrazione con l'intento di ripiegare su una policy plist o del registro gestita dall'endpoint, tieni presente che le impostazioni nella cache restano sulle macchine client fino al successivo recupero riuscito, e le chiavi che si applicano solo all'avvio successivo, come model, restano in vigore finché ciascun client non viene riavviato. Esegui /status per vedere quale origine gestita è attiva.

Eccezioni per chiave tra le origini gestite

Queste chiavi sono eccezioni alla regola dell'assenza di merge:

  • Chiavi di blocco tra origini: un piccolo insieme di chiavi, come i blocchi dell'allowlist della sandbox, elencate nella pagina delle impostazioni gestite. Claude Code le rispetta quando una qualsiasi origine gestita controllata dall'amministratore le imposta; il livello del registro HKCU scrivibile dall'utente è escluso.

    Quando un policyHelper fornisce impostazioni gestite, il suo output è l'unica origine letta da questi controlli, salvo forceRemoteSettingsRefresh, che Claude Code legge direttamente dalle origini dell'amministratore all'avvio.

  • Il blocco env: a parte l'unità di telemetria e le variabili di routing associate a una chiave di credenziali, entrambe descritte di seguito, viene sottoposto a merge per chiave tra le origini controllate dall'amministratore. Per ciascuna variabile d'ambiente prevale l'origine con priorità più alta che la definisce, e le origini dell'amministratore di livello inferiore completano le variabili che le origini superiori lasciano non impostate. Una voce env gestita dall'endpoint si applica quindi ogni volta che la configurazione gestita dal server lascia quella variabile non impostata, o mentre un valore del server nella cache per essa è trattenuto in attesa di conferma da parte del server. Richiede Claude Code v2.1.223 o successivo. Prima della v2.1.223, Claude Code applica solo l'intero blocco env dell'origine selezionata.

    • Unità di telemetria: le chiavi dell'exporter OTEL_EXPORTER_OTLP_*, gli interruttori di acquisizione dei contenuti OTEL_LOG_*, OTEL_LOGS_EXPORTER e le variabili di tracing beta ENABLE_BETA_TRACING_DETAILED e BETA_TRACING_ENDPOINT seguono come unità l'origine più alta che ne imposta una qualsiasi. Anche un'origine che fornisce la chiave di credenziali otelHeadersHelper rivendica l'unità, ma applica queste variabili solo quando è l'origine selezionata: un'origine non selezionata che fornisce la chiave non ne contribuisce nessuna e impedisce comunque alle origini inferiori di completarle. In entrambi i casi, un endpoint dell'exporter proveniente da un'origine non può mai essere associato a credenziali provenienti da un'altra.
    • Routing associato alle credenziali: un'origine che associa variabili di routing a una chiave di credenziali valida solo per l'origine selezionata, come apiKeyHelper o otelHeadersHelper, contribuisce con quelle variabili di routing solo quando si aggiudica lo slot.

  • allowedProviders: un elenco impostato sulla macchina e un elenco gestito dal server si combinano come indicato nella nota sull'ambito della sua voce. Richiede Claude Code v2.1.285 o successivo

  • Chiavi di accesso al gateway: Claude Code non legge mai forceLoginGatewayUrl, gatewayInternalNetworks o il valore "gateway" di forceLoginMethod dalle impostazioni gestite dal server, quindi un valore lì né si applica né nasconde un valore impostato in una policy MDM o in un file di impostazioni gestite. La voce managedSourcesBehavior indica quale origine dell'amministratore sulla macchina li fornisce.

Comportamento di recupero e della cache

Claude Code recupera le impostazioni dai server di Anthropic all'avvio e verifica la presenza di aggiornamenti ogni ora durante le sessioni attive.

Un client che ha effettuato l'accesso tramite un gateway delle app Claude recupera le impostazioni dal gateway e attende quel recupero prima che la sessione inizi, quindi il recupero descritto negli elenchi seguenti non si applica a esso. Imporre un avvio fail-closed descrive cosa succede quando quel recupero non riesce.

Primo avvio senza impostazioni nella cache:

  • Quando uno sviluppatore accede all'avvio, ad esempio alla prima esecuzione o dopo /logout, Claude Code attende fino a cinque secondi il recupero prima di aprire la sessione. Quando la policy arriva in tempo, Claude Code la applica dalla prima schermata e vi mostra i tuoi companyAnnouncements. Quando il payload richiede l'approvazione di sicurezza, Claude Code termina l'attesa e applica il payload una volta che lo sviluppatore lo approva
  • In qualsiasi altro avvio, e quando quell'attesa di cinque secondi si esaurisce, Claude Code apre la sessione mentre il recupero continua, quindi trascorre un breve intervallo prima che le impostazioni vengano caricate e le restrizioni entrino in vigore
  • Se il recupero non riesce, Claude Code continua senza impostazioni gestite dal server e, nelle sessioni interattive, avvisa che non si applica alcuna policy remota; le impostazioni gestite dall'endpoint si applicano comunque. Se un'origine gestita imposta forceRemoteSettingsRefresh, Claude Code esce invece di continuare

Avvii successivi con impostazioni nella cache:

  • Le impostazioni nella cache si applicano immediatamente all'avvio, a eccezione dei valori modelPricing e managedMcpServers nella cache e delle variabili d'ambiente che Claude Code trattiene fino alla conferma del payload da parte del server
  • Un modelPricing nella cache non si applica finché il recupero della sessione non conferma il payload. Fino ad allora, i costi che gli sviluppatori vedono in /usage e nella riga di stato sono a prezzo di listino
  • Un blocco managedMcpServers nella cache non si applica finché il recupero della sessione non conferma il payload. Claude Code attende fino a 30 secondi quel recupero prima di connettere i server MCP. Se il recupero non riesce o va in timeout, la sessione inizia senza i server dell'organizzazione, /status lo segnala, e i server si connettono non appena un recupero successivo li conferma. Consulta Quando si connettono i server forniti per il comportamento completo, incluso il primo avvio. Richiede Claude Code v2.1.259 o successivo
  • Claude Code recupera le impostazioni aggiornate in background
  • Le impostazioni nella cache persistono in caso di errori di rete. Se il recupero all'avvio non riesce, Claude Code avvisa nelle sessioni interattive che è in vigore la policy nella cache
  • I valori trattenuti all'avvio restano trattenuti fino al primo recupero riuscito

Claude Code trattiene diverse categorie di variabili nel blocco env nella cache fino alla conferma del payload da parte del server per la sessione. In questo modo un valore di proxy, autorità di certificazione, endpoint o credenziali nella cache non può reindirizzare, intercettare o riautenticare il recupero delle impostazioni che conferma il payload. Questa protezione si applica solo alla cache delle impostazioni recuperate dal server: le impostazioni gestite dall'endpoint distribuite tramite MDM o managed-settings.json non sono interessate. Il trattenimento richiede Claude Code v2.1.198 o successivo; prima della v2.1.198, l'intero blocco env nella cache si applica all'avvio. Le categorie trattenute includono:

  • Configurazione di proxy e TLS, come HTTPS_PROXY, NODE_EXTRA_CA_CERTS e le variabili del certificato client mTLS CLAUDE_CODE_CLIENT_CERT e CLAUDE_CODE_CLIENT_KEY
  • Routing delle API e selezione del provider, inclusi ANTHROPIC_BASE_URL, le variabili di selezione del provider come CLAUDE_CODE_USE_BEDROCK e CLAUDE_CODE_USE_VERTEX, e gli URL degli endpoint del provider come ANTHROPIC_BEDROCK_BASE_URL
  • Credenziali di autenticazione, come ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN e CLAUDE_CODE_OAUTH_TOKEN
  • Il selettore della directory di configurazione CLAUDE_CONFIG_DIR
  • Selettori dell'origine delle credenziali e della directory di configurazione, in Claude Code v2.1.223 o successivo: le variabili di Workload Identity Federation come ANTHROPIC_FEDERATION_RULE_ID e ANTHROPIC_IDENTITY_TOKEN, i selettori del profilo e della directory di configurazione ANTHROPIC_PROFILE e ANTHROPIC_CONFIG_DIR, e le variabili delle directory del sistema operativo HOME, XDG_CONFIG_HOME, APPDATA e USERPROFILE

Claude Code legge le variabili di Workload Identity Federation e i selettori ANTHROPIC_PROFILE e ANTHROPIC_CONFIG_DIR solo all'avvio, quindi un valore fornito dal server per essi non cambia l'origine delle credenziali della sessione nemmeno dopo che il recupero è riuscito. Per fornire quei selettori in Claude Code v2.1.223 o successivo, usa le impostazioni gestite dall'endpoint come MDM o managed-settings.json. Per CLAUDE_CONFIG_DIR e le variabili delle directory del sistema operativo, la protezione è il trattenimento stesso: il valore nella cache resta fuori dall'ambiente fino alla conferma del payload da parte del server.

Ogni altra chiave nel blocco env nella cache si applica all'avvio. Una volta che il server conferma il payload, e dopo che lo hai approvato se richiede l'approvazione di sicurezza, le variabili trattenute si applicano per il resto della sessione.

Se la tua organizzazione ha bisogno di un proxy per raggiungere api.anthropic.com, il trattenimento riguarda solo il blocco env fornito dal server: un proxy impostato in un blocco env gestito dall'endpoint tramite MDM o managed-settings.json, nell'ambiente della shell o nelle impostazioni utente raggiunge il recupero delle impostazioni. L'origine gestita dall'endpoint richiede Claude Code v2.1.223 o successivo: il valore del proxy gestito dal server nella cache viene trattenuto fino alla conferma da parte del recupero, quindi il valore gestito dall'endpoint lo completa per chiave e raggiunge il recupero stesso. Prima della v2.1.223, usa l'ambiente della shell o le impostazioni utente in modo che il proxy si applichi insieme a un payload del server nella cache. Il primo avvio non ha cache, quindi per il recupero iniziale è comunque necessaria un'origine gestita dall'endpoint, l'ambiente della shell o le impostazioni utente.

Claude Code applica la maggior parte degli aggiornamenti delle impostazioni alle sessioni in esecuzione senza riavvio. Alcuni aggiornamenti si applicano solo all'avvio successivo, tra cui la configurazione dell'exporter OpenTelemetry, la chiave model e la rimozione di una variabile dal blocco env.

Voci non valide nelle impostazioni fornite

Quando una parte di un payload non supera la validazione dello schema, Claude Code mostra un errore di validazione e applica tutte le altre impostazioni valide; Voci non valide nelle impostazioni gestite indica cosa viene scartato e quali chiavi ripiegano su un valore più restrittivo. Richiede Claude Code v2.1.169 o successivo.

La distribuzione gestita dal server aggiunge questi comportamenti:

  • Un avvio che usa la cache in ~/.claude/remote-settings.json tratta le voci non valide come le ha trattate il recupero che ha scritto la cache:

    • Le voci che non hanno superato la validazione restano scartate.
    • Le chiavi che falliscono in modo chiuso mantengono i loro valori più restrittivi.
    • Un valore cleanupPeriodDays o desktopSessionCleanupPeriodDays non valido resta nella copia nella cache e non viene mai applicato.

  • Claude Code non applica nulla di un payload e lascia invariata la cache quando sono vere tutte e tre queste condizioni:

    • Ogni impostazione nel payload non supera la validazione.
    • Nessuna di esse ripiega su un valore più restrittivo.
    • Il payload contiene una chiave diversa da quelle due chiavi di conservazione.

    L'avviso all'avvio, /status e claude doctor segnalano allora il caricamento non riuscito con la causa no setting in the server response could be applied as written, e quella voce indica su quale policy viene eseguita la sessione. I client che impongono un avvio fail-closed escono invece all'avvio.

  • La finestra di dialogo di approvazione di sicurezza valuta il payload recuperato dopo la rimozione delle voci non valide, quindi una voce non valida rimossa non viene mai presentata per l'approvazione e non viene mai eseguita.

Per eseguire il debug dei problemi di distribuzione, esegui claude --debug-file <path> e cerca Remote settings nel log. Convalida una modifica del payload con claude doctor su una macchina di test prima di distribuirla all'organizzazione.

Imporre un avvio fail-closed

Per impostazione predefinita, se il recupero delle impostazioni remote non riesce all'avvio, la CLI continua con le impostazioni memorizzate nella cache dall'ultimo recupero riuscito, a eccezione dei valori che Claude Code trattiene fino al primo recupero riuscito. Su una macchina che non le ha mai recuperate, la CLI continua senza impostazioni gestite dal server e applica comunque eventuali impostazioni gestite dall'endpoint presenti sul dispositivo.

Per impedire ai client di avviarsi con impostazioni gestite dal server nella cache o assenti, imposta forceRemoteSettingsRefresh: true nelle impostazioni gestite.

I client che hanno effettuato l'accesso tramite un gateway delle app Claude attendono il recupero all'avvio indipendentemente da questa impostazione, e gestiscono un recupero non riuscito come segue:

  • Se il gateway risponde con un 401 a un avvio interattivo presidiato e questa impostazione è disattivata, il gateway ha terminato quell'accesso. Claude Code stampa Cloud gateway session expired — run /login to reconnect. e apre la sessione disconnessa dal gateway finché l'utente non esegue /login.
  • Quando il recupero non riesce in qualsiasi altro modo, o in qualsiasi altro tipo di avvio eccetto un sottocomando claude auth, il client esce con un errore.

Quando questa impostazione è attiva in una sessione che recupera le impostazioni gestite dal server, la CLI si blocca all'avvio finché le impostazioni remote non vengono recuperate di nuovo. Se il recupero non riesce, la CLI esce invece di procedere senza la policy. Questa impostazione si autoperpetua: una volta fornita dal server, viene anche memorizzata nella cache locale in modo che gli avvii successivi impongano lo stesso comportamento anche prima del primo recupero riuscito di una nuova sessione. Una sessione che non recupera le impostazioni gestite dal server si avvia senza attendere.

Per abilitarla, aggiungi la chiave alla configurazione delle impostazioni gestite:

{
  "forceRemoteSettingsRefresh": true
}

Puoi anche impostare questa chiave in un profilo MDM gestito dall'endpoint o in un file managed-settings.json di sistema per imporre il comportamento fail-closed al primo avvio, prima che arrivi qualsiasi payload del server. Questo flag è un'eccezione alla regola di precedenza descritta sopra: Claude Code lo rispetta quando una qualsiasi origine gestita controllata dall'amministratore lo imposta, anche se è presente un payload gestito dal server nella cache, quindi non trascura un valore fornito tramite MDM quando esistono impostazioni gestite dal server.

Quando un policyHelper fornisce impostazioni gestite, il suo output sostituisce ogni altra origine gestita per le chiavi che Claude Code legge dopo l'avvio. Per le origini da cui Claude Code legge questa chiave, consulta la sua voce nelle impostazioni. La voce policyHelper indica da quali origini Claude Code legge l'helper e quando viene eseguito.

Il recupero delle impostazioni invia anche un'intestazione Cache-Control: no-cache in modo che i proxy HTTP intermedi non restituiscano una risposta obsoleta.

Prima di abilitare questa impostazione, assicurati che le policy di rete consentano la connettività verso api.anthropic.com. Se quell'endpoint non è raggiungibile, la CLI esce all'avvio e gli utenti non possono avviare Claude Code.

I sottocomandi claude auth come claude auth login sono esenti da questo controllo e dall'uscita all'avvio del gateway, così gli utenti possono autenticarsi di nuovo quando il recupero delle impostazioni non riesce a causa di credenziali scadute.

Finestre di dialogo di approvazione di sicurezza

Alcune impostazioni che potrebbero comportare rischi per la sicurezza richiedono l'approvazione esplicita dell'utente prima che Claude Code le applichi in una sessione interattiva:

  • Impostazioni di comandi shell: impostazioni che eseguono comandi shell, come apiKeyHelper, statusLine e otelHeadersHelper
  • Impostazioni dei binari della sandbox: sandbox.bwrapPath, sandbox.socatPath e sandbox.ripgrep. Ciascuna di queste impostazioni punta a un eseguibile, e Claude Code esegue quell'eseguibile
  • Impostazioni di rete e di isolamento della sandbox: impostazioni della sandbox che consentono al proxy della sandbox di leggere, reindirizzare o autenticare il traffico, oppure che indeboliscono l'isolamento della sandbox: sandbox.network.tlsTerminate, sandbox.network.httpProxyPort, sandbox.network.socksProxyPort, sandbox.credentials, sandbox.allowAppleEvents, sandbox.enableWeakerNestedSandbox, sandbox.enableWeakerNetworkIsolation, sandbox.filesystem.disabled, sandbox.network.allowAllUnixSockets, sandbox.network.allowUnixSockets e sandbox.network.allowMachLookup. Un blocco sandbox.credentials che contiene solo regole deny non richiede approvazione, poiché limita la sandbox senza fornire credenziali al proxy. Prima della v2.1.251, Claude Code applicava queste impostazioni senza approvazione
  • Variabili d'ambiente personalizzate: variabili env fornite che richiedono l'approvazione dell'utente, come le variabili di proxy e di URL di base; consulta Variabili d'ambiente e finestra di dialogo di approvazione
  • Configurazioni degli hook: qualsiasi definizione di hook

Quando queste impostazioni sono presenti, gli utenti vedono una finestra di dialogo di sicurezza che spiega cosa viene configurato. Gli utenti devono approvare per procedere. Se un utente rifiuta le impostazioni, Claude Code esce.

Un CLAUDE.md gestito fornito tramite la chiave claudeMd non richiede approvazione, perché è un testo di istruzioni per Claude e non un comando eseguito da Claude Code. Claude Code controlla comunque i permessi per gli strumenti che Claude usa mentre segue quelle istruzioni. Prima della v2.1.260, anche un valore claudeMd richiedeva approvazione.

Memoria delle approvazioni

Claude Code registra la tua approvazione nella tua directory di configurazione, ~/.claude a meno che tu non imposti CLAUDE_CONFIG_DIR. Cosa registra dipende dalle credenziali usate dal recupero delle impostazioni:

  • Un accesso a claude.ai salvato da /login o claude auth login, oppure l'accesso alla Console senza chiave: un'approvazione per organizzazione, detenuta dall'account che ha approvato più di recente.

  • Un accesso tramite gateway delle app Claude: un'approvazione per gateway.

    Se esci e accedi di nuovo allo stesso gateway, Claude Code non mostra di nuovo la finestra di dialogo finché le impostazioni che richiedono approvazione restano invariate. Claude Code la mostra di nuovo quando quelle impostazioni cambiano, quando accedi a un gateway diverso e quando accetti un nuovo certificato per lo stesso gateway.

    Claude Code non salva alcuna approvazione per un gateway di sviluppo in loopback raggiunto tramite HTTP semplice, quindi la finestra di dialogo compare di nuovo dopo ogni accesso.

  • Qualsiasi altra credenziale, come una chiave API o CLAUDE_CODE_OAUTH_TOKEN: un'approvazione per le impostazioni fornite, conservata insieme alla copia delle impostazioni nella cache in quella directory di configurazione. Claude Code mostra di nuovo la finestra di dialogo quando le impostazioni che richiedono approvazione cambiano, e dopo che esegui /logout o claude auth logout, ciascuno dei quali elimina la copia nella cache.

Un'approvazione per sandbox.credentials o sandbox.network.tlsTerminate copre anche le voci di sandbox.network.allowedDomains in quelle stesse impostazioni fornite, perché entrambe le impostazioni agiscono su quell'allowlist. La finestra di dialogo compare di nuovo quando l'amministratore aggiunge o rimuove una di quelle voci, anche se sandbox.network.allowedDomains di per sé non richiede approvazione.

Con un accesso a claude.ai salvato:

  • Se esci e accedi di nuovo, o passi a un'altra organizzazione e poi torni, Claude Code non mostra di nuovo la finestra di dialogo finché quelle impostazioni restano invariate, a meno che nel frattempo un altro account non le abbia approvate per quell'organizzazione nella stessa directory di configurazione.
  • Se accedi alla stessa organizzazione con un account diverso, Claude Code mostra di nuovo la finestra di dialogo anche se le impostazioni sono invariate. L'approvazione di quell'account sostituisce la precedente, quindi quando torni all'account originale Claude Code mostra ancora una volta la finestra di dialogo.

Claude Code non può sempre mostrare la finestra di dialogo. Ciascun caso seguente indica quali impostazioni si applicano quando non può farlo e quando vedrai la finestra di dialogo la volta successiva:

  • Una sessione interattiva che non può mostrare la finestra di dialogo: Claude Code non applica le impostazioni fornite e mantiene le ultime impostazioni approvate. La finestra di dialogo compare nella sessione successiva in grado di mostrarla. Richiede Claude Code v2.1.211 o successivo.
  • claude install o claude update: Claude Code non mostra la finestra di dialogo durante nessuno dei due comandi. Il comando viene eseguito con le ultime impostazioni approvate, e la finestra di dialogo compare nella tua successiva sessione interattiva. Se Claude Code attende il recupero delle impostazioni all'avvio, ad esempio con forceRemoteSettingsRefresh impostato o in una distribuzione con gateway delle app Claude, mostra invece la finestra di dialogo durante il comando, e un'installazione eseguita da una pipe non riesce; consulta Raw mode is not supported durante l'installazione. Prima della v2.1.246, Claude Code tentava di mostrare la finestra di dialogo anche durante questi comandi.
  • Un errore chiude la finestra di dialogo prima che tu risponda: Claude Code non applica le impostazioni fornite e mantiene le ultime impostazioni approvate. Mostra di nuovo la finestra di dialogo nella sessione successiva in grado di mostrarla.
  • Un'esecuzione non interattiva, come claude -p, una sessione dell'Agent SDK o una sessione nel pannello della chat dell'estensione VS Code o nella scheda Code dell'app desktop: Claude Code non può mostrare la finestra di dialogo, quindi quando le impostazioni fornite richiederebbero approvazione, le applica solo per quell'esecuzione. Non le registra come approvate né le scrive nella cache locale, e la sessione interattiva successiva mostra la finestra di dialogo. Finché un utente non approva in una sessione interattiva, ogni esecuzione non interattiva recupera di nuovo le impostazioni all'avvio. Prima della v2.1.207, un'esecuzione non interattiva salvava le impostazioni come approvate, quindi le sessioni interattive successive non mostravano mai la finestra di dialogo per esse.

Variabili d'ambiente e finestra di dialogo di approvazione

Claude Code applica alcune variabili env fornite senza mostrare all'utente la finestra di dialogo di approvazione, tra cui:

  • Interruttori di funzionalità e comandi
  • Impostazioni di selezione e comportamento del modello, come ANTHROPIC_MODEL, DISABLE_PROMPT_CACHING e CLAUDE_CODE_EFFORT_LEVEL
  • Impostazioni della finestra di contesto e della compattazione, come DISABLE_AUTO_COMPACT
  • Opzioni dell'interfaccia del terminale e di accessibilità
  • Limiti numerici, budget e timeout

Altre variabili fornite possono richiedere l'approvazione dell'utente prima di entrare in vigore; un valore non vuoto di proxy, URL di base o OTEL_EXPORTER_OTLP_ENDPOINT la richiede sempre. Quando una variabile fornita richiede approvazione, la finestra di dialogo ne indica il nome, così l'utente vede esattamente cosa la policy chiede di impostare. Prima della v2.1.218, Claude Code applicava meno variabili senza chiedere all'utente, quindi impostazioni come DISABLE_AUTO_COMPACT attivavano la finestra di dialogo con qualsiasi valore non vuoto.

Claude Code decide se quattro interruttori relativi alla privacy richiedono approvazione in base al valore fornito anziché al nome della variabile: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_ERROR_REPORTING, DISABLE_TELEMETRY e DO_NOT_TRACK. Un valore truthy come 1 o true si limita a disattivare il tracciamento, la segnalazione o altro traffico non essenziale, quindi Claude Code lo applica senza chiedere all'utente. Per qualsiasi altro valore non vuoto, Claude Code mostra la finestra di dialogo. Prima della v2.1.218, tutte tranne DO_NOT_TRACK si applicavano senza approvazione con qualsiasi valore, e DO_NOT_TRACK attivava la finestra di dialogo con qualsiasi valore non vuoto.

Claude Code decide inoltre se API_FORCE_IDLE_TIMEOUT richiede approvazione in base al valore fornito: un valore truthy si limita ad attivare il timeout di inattività del corpo, quindi Claude Code lo applica senza chiedere all'utente. Per qualsiasi altro valore non vuoto, Claude Code mostra la finestra di dialogo. Prima della v2.1.248, qualsiasi valore non vuoto attivava la finestra di dialogo.

Anche la necessità di approvazione per ANTHROPIC_CUSTOM_HEADERS dipende dal valore fornito. Le intestazioni che si limitano a etichettare le richieste, come Accept-Language, si applicano senza la finestra di dialogo. Una riga che indica una credenziale, un selettore di organizzazione o tenant, un override di routing o di host, o un'intestazione che influisce sul comportamento delle API, come Authorization, X-Api-Key, Host, anthropic-beta o le intestazioni X-Amzn-Bedrock-*, richiede approvazione. Una riga richiede approvazione anche quando il suo nome non è un token di intestazione HTTP valido o il suo valore contiene un carattere che un'intestazione HTTP non può contenere. Il controllo individua parole all'interno del nome dell'intestazione, quindi anche X-Client-Version, che contiene client e version, richiede approvazione. Prima della v2.1.251, qualsiasi valore di ANTHROPIC_CUSTOM_HEADERS si applicava senza approvazione.

Un valore falsy come 0 o false per ENABLE_BETA_TRACING_DETAILED o OTEL_LOG_RAW_API_BODIES si applica senza la finestra di dialogo, perché si limita a disattivare il tracing dettagliato o l'acquisizione dei corpi grezzi delle API. Qualsiasi altro valore non vuoto per una delle due variabili richiede approvazione.

Disponibilità della piattaforma

Le impostazioni gestite dal server richiedono una connessione diretta a api.anthropic.com. La consegna richiede inoltre che la sessione si autentichi con una di queste credenziali:

  • Un accesso OAuth di Team o Enterprise
  • Un token OAuth fornito tramite CLAUDE_CODE_OAUTH_TOKEN
  • Una chiave API configurata direttamente
  • Un profilo Anthropic user_oauth, a meno che il profilo non imposti un base_url diverso dall'API Anthropic. Richiede Claude Code v2.1.257 o successivo.

Né le chiavi restituite da uno script apiKeyHelper né le credenziali di Workload Identity Federation attivano il recupero delle impostazioni.

In una sessione Cowork nell'app Claude Desktop, Claude Code non recupera le impostazioni gestite dal server dalla console di amministrazione claude.ai, anche quando l'utente accede con un account Team o Enterprise. Dove e quando si applica una policy copre quale policy raggiunge le sessioni Cowork sulla macchina dell'utente e le sessioni Cowork remote. claude.ai applica comunque i vostri elenchi strictKnownMarketplaces e blockedMarketplaces quando un utente Cowork aggiunge un marketplace da un repository git su claude.ai o da Customize nella scheda Cowork. Come funzionano le restrizioni descrive quel controllo.

Se esportate una variabile provider CLAUDE_CODE_USE_* o un ANTHROPIC_BASE_URL non predefinito nella vostra shell, Claude Code salta il recupero delle impostazioni per le vostre sessioni. claude doctor e /status segnalano il recupero saltato e la sua causa.

Non potete cancellare l'esportazione con un blocco env gestito dal server, perché il blocco arriva attraverso il recupero che l'esportazione impedisce. Un blocco env con impostazioni gestite dall'endpoint non ripristina il recupero neanche: Claude Code verifica l'idoneità prima di applicare i blocchi env gestiti, quindi il valore gestito dall'endpoint cambia la selezione del provider della sessione ma il recupero rimane saltato.

Per ripristinare la consegna gestita dal server, rimuovete l'esportazione dalla vostra shell, oppure impostate la variabile su "" nel blocco env delle impostazioni utente, che si applica prima della verifica dell'idoneità. Per applicare la policy senza fare affidamento sugli utenti per modificare le loro shell, consegnate le impostazioni attraverso il canale gestito dall'endpoint.

Per le distribuzioni Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry e Claude Platform on AWS, un gateway di app Claude auto-ospitato fornisce la consegna equivalente di impostazioni gestite da remoto: i client firmati dal gateway recuperano le impostazioni gestite dal gateway invece che da api.anthropic.com. La semantica degli errori differisce all'avvio: un client gateway che non riesce a raggiungere il gateway esce con un errore invece di ricadere sulle impostazioni memorizzate nella cache, mentre l'aggiornamento in background orario è fail-open su entrambi i canali.

Registrazione di audit

Gli eventi del registro di audit per le modifiche alle impostazioni sono disponibili tramite l'API di conformità o l'esportazione del registro di audit. Contattare il vostro team di account Anthropic per l'accesso.

Gli eventi di audit includono il tipo di azione eseguita, l'account e il dispositivo che ha eseguito l'azione, e riferimenti ai valori precedenti e nuovi.

Considerazioni sulla sicurezza

Le impostazioni gestite dal server forniscono l'applicazione centralizzata dei criteri, ma operano come un controllo lato client, non come un limite di sicurezza. Su dispositivi non gestiti, un utente non ha bisogno dell'accesso amministratore o sudo per aggirarli.

Scenario Comportamento
L'utente modifica il file di impostazioni memorizzato nella cache Il file manomesso si applica all'avvio, ad eccezione dei valori che Claude Code trattiene fino a quando il server non conferma il payload. Il prossimo recupero dal server ripristina le impostazioni corrette, ad eccezione dei valori che si applicano solo al prossimo avvio, come model o una variabile aggiunta al blocco env, che rimangono in vigore fino al riavvio
L'utente elimina il file di impostazioni memorizzato nella cache Si verifica il comportamento del primo avvio
L'utente esegue un binario Claude Code modificato Un utente che può eseguire un client modificato può aggirare qualsiasi controllo lato client
L'utente esegue una versione precedente di Claude Code Le versioni precedenti alle impostazioni gestite dal server non le recuperano o non le applicano
L'API non è disponibile Le impostazioni memorizzate nella cache si applicano se disponibili, ad eccezione dei valori che Claude Code trattiene fino a quando un recupero ha successo. Senza una cache, Claude Code non applica alcuna impostazione gestita dal server fino al prossimo recupero riuscito e applica comunque qualsiasi impostazione gestita dall'endpoint sul dispositivo. Con forceRemoteSettingsRefresh: true, la CLI esce invece di continuare, ad eccezione dei claude auth subcomandi. I client che hanno effettuato l'accesso tramite un gateway di app Claude escono all'avvio senza questa impostazione, con la stessa eccezione claude auth
L'utente si autentica con un'organizzazione diversa Le impostazioni non vengono consegnate per gli account al di fuori dell'organizzazione gestita
L'utente configura un provider di modelli di terze parti Le impostazioni gestite dal server vengono ignorate. Questo include l'impostazione di CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_MANTLE, CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_USE_FOUNDRY, CLAUDE_CODE_USE_ANTHROPIC_AWS, o un ANTHROPIC_BASE_URL non predefinito
Il traffico di rete viene intercettato o reindirizzato La convalida TLS disabilitata o il traffico intercettato può alterare le impostazioni che il client riceve

Per registrare le modifiche ai file di impostazioni locali, incluso managed-settings.json, utilizzare gli hook ConfigChange. Claude Code non li esegue quando arrivano le impostazioni gestite dal server o si aggiornano, o quando un profilo MDM o una politica del registro cambia, e un hook non può bloccare una modifica policy_settings.

Per limitare quali organizzazioni i vostri utenti possono accedere con le credenziali fornite dal client, consultare Enforce network-level access control with Tenant Restrictions nel Centro assistenza Claude. Per garanzie di applicazione più forti, utilizzare le impostazioni gestite dall'endpoint su dispositivi registrati in una soluzione MDM.

Vedere anche

Pagine correlate per la gestione della configurazione di Claude Code: