Configurare le impostazioni gestite dal server

Le impostazioni gestite dal server consentono agli amministratori di configurare centralmente Claude Code tramite un’interfaccia basata sul web su Claude.ai. I client di Claude Code ricevono automaticamente queste impostazioni quando gli utenti si autenticano con le credenziali della loro organizzazione. Questo approccio è progettato per le organizzazioni che non dispongono di infrastrutture di gestione dei dispositivi, o che hanno la necessità di gestire le impostazioni per gli utenti su dispositivi non gestiti.

Le impostazioni gestite dal server sono disponibili per i clienti di Claude for Teams e Claude for Enterprise.

Requisiti

Per utilizzare le impostazioni gestite dal server, è necessario:

Piano Claude for Teams o Claude for Enterprise
Claude Code versione 2.1.38 o successiva per Claude for Teams, o versione 2.1.30 o successiva per Claude for Enterprise
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 consegnate dai server di Anthropic al momento dell’autenticazione
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.

Configurare le impostazioni gestite dal server

Aprire la console di amministrazione

In Claude.ai, navigare a Admin Settings > Claude Code > Managed settings.

Definire le impostazioni

Aggiungere 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; vedere Limitazioni attuali per questo breve elenco. Questo include hooks, variabili di 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:

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

Per configurare il classificatore della modalità auto in modo che conosca quali repository, bucket e domini la vostra organizzazione ritiene affidabili:

{
  "autoMode": {
    "environment": [
      "Source control: github.example.com/acme-corp and all repos under it",
      "Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-ml-datasets",
      "Trusted internal domains: *.corp.example.com"
    ]
  }
}

Poiché gli hook eseguono comandi shell, gli utenti vedono una finestra di dialogo di approvazione della sicurezza prima che vengano applicati. 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.

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 all’avvio. È inoltre possibile verificare che le regole di autorizzazione gestite siano attive facendo eseguire a un utente /permissions per visualizzare le regole di autorizzazione effettive.

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 l’elenco completo. Qualsiasi impostazione non in tale elenco può comunque essere posizionata nelle impostazioni gestite e ha la precedenza più alta.

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.
Le configurazioni del server MCP non possono essere distribuite tramite impostazioni gestite dal server.
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.

Consegna 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. Nessun altro livello di impostazioni può sostituirle, inclusi gli argomenti della riga di comando. All’interno del livello gestito, la prima fonte che fornisce una configurazione non vuota vince. Le impostazioni gestite dal server vengono controllate per prime, quindi le impostazioni gestite dall’endpoint. Le fonti non si uniscono: se le impostazioni gestite dal server forniscono qualsiasi chiave, le impostazioni gestite dall’endpoint vengono ignorate completamente. Se le impostazioni gestite dal server non forniscono nulla, le impostazioni gestite dall’endpoint si applicano. Se cancellate la configurazione gestita dal server nella console di amministrazione con l’intenzione di tornare a una plist gestita dall’endpoint o a una politica del registro, tenete presente che le impostazioni memorizzate nella cache persistono sulle macchine client fino al prossimo recupero riuscito. Eseguite /status per vedere quale fonte gestita è attiva.

Comportamento di recupero e caching

Claude Code recupera le impostazioni dai server di Anthropic all’avvio e esegue il polling per gli aggiornamenti ogni ora durante le sessioni attive. Primo avvio senza impostazioni memorizzate nella cache:

Claude Code recupera le impostazioni in modo asincrono
Se il recupero non riesce, Claude Code continua senza impostazioni gestite
C’è una breve finestra prima che le impostazioni si carichino in cui le restrizioni non sono ancora applicate

Avvii successivi con impostazioni memorizzate nella cache:

Le impostazioni memorizzate nella cache si applicano immediatamente all’avvio
Claude Code recupera le impostazioni aggiornate in background
Le impostazioni memorizzate nella cache persistono attraverso i guasti di rete

Claude Code applica gli aggiornamenti delle impostazioni automaticamente senza un riavvio, ad eccezione delle impostazioni avanzate come la configurazione di OpenTelemetry, che richiedono un riavvio completo per avere effetto.

Applicare l’avvio fail-closed

Per impostazione predefinita, se il recupero delle impostazioni remote non riesce all’avvio, la CLI continua senza impostazioni gestite. Per gli ambienti in cui questa breve finestra non applicata è inaccettabile, impostare forceRemoteSettingsRefresh: true nelle impostazioni gestite. Quando questa impostazione è attiva, la CLI si blocca all’avvio fino a quando le impostazioni remote non vengono recuperate di recente. Se il recupero non riesce, la CLI esce piuttosto che procedere senza la politica. Questa impostazione si auto-perpetua: una volta consegnata dal server, viene anche memorizzata nella cache localmente in modo che gli avvii successivi applichino lo stesso comportamento anche prima del primo recupero riuscito di una nuova sessione. Per abilitare questa funzione, aggiungere la chiave alla configurazione delle impostazioni gestite:

{
  "forceRemoteSettingsRefresh": true
}

Prima di abilitare questa impostazione, assicurarsi che le politiche di rete consentano la connettività a api.anthropic.com. Se tale endpoint non è raggiungibile, la CLI esce all’avvio e gli utenti non possono avviare Claude Code. A partire dalla v2.1.139, i sottocomandi claude auth come claude auth login sono esenti da questo controllo, in modo che gli utenti possano autenticarsi nuovamente quando le credenziali scadute sono il motivo per cui il recupero delle impostazioni non riesce.

Finestre di dialogo di approvazione della sicurezza

Determinate impostazioni che potrebbero comportare rischi di sicurezza richiedono l’approvazione esplicita dell’utente prima di essere applicate:

Impostazioni dei comandi shell: impostazioni che eseguono comandi shell
Variabili di ambiente personalizzate: variabili non nell’elenco di sicurezza noto
Configurazioni di 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.

In modalità non interattiva con il flag -p, Claude Code salta le finestre di dialogo di sicurezza e applica le impostazioni senza approvazione dell’utente.

Disponibilità della piattaforma

Le impostazioni gestite dal server richiedono una connessione diretta a api.anthropic.com e non sono disponibili quando si utilizzano provider di modelli di terze parti:

Amazon Bedrock
Google Vertex AI
Microsoft Foundry
Endpoint API personalizzati tramite ANTHROPIC_BASE_URL o gateway LLM

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. Su dispositivi non gestiti, gli utenti con accesso amministratore o sudo possono modificare il binario di Claude Code, il filesystem, o la configurazione di rete.

Scenario	Comportamento
L’utente modifica il file di impostazioni memorizzato nella cache	Il file manomesso si applica all’avvio, ma le impostazioni corrette si ripristinano al prossimo recupero dal server
L’utente elimina il file di impostazioni memorizzato nella cache	Si verifica il comportamento del primo avvio: le impostazioni vengono recuperate in modo asincrono con una breve finestra non applicata
L’API non è disponibile	Le impostazioni memorizzate nella cache si applicano se disponibili, altrimenti le impostazioni gestite non vengono applicate fino al prossimo recupero riuscito. Con `forceRemoteSettingsRefresh: true`, la CLI esce invece di continuare, ad eccezione dei `claude auth` subcomandi
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`, o un `ANTHROPIC_BASE_URL` non predefinito

Per rilevare le modifiche della configurazione in fase di esecuzione, utilizzare gli hook ConfigChange per registrare le modifiche o bloccare le modifiche non autorizzate prima che abbiano effetto. 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:

Settings: riferimento di configurazione completo incluse tutte le impostazioni disponibili
Endpoint-managed settings: impostazioni gestite distribuite ai dispositivi dal reparto IT
Authentication: configurare l’accesso degli utenti a Claude Code
Security: salvaguardie di sicurezza e best practice

Configurazione e accesso

Distribuzione

Utilizzo e costi

Distribuzione dei plugin

Sicurezza e dati

Adozione

Configurare le impostazioni gestite dal server

Requisiti

Scegliere tra impostazioni gestite dal server e gestite dall’endpoint

Configurare le impostazioni gestite dal server

Verificare la consegna delle impostazioni

Controllo di accesso

Impostazioni solo gestite

Limitazioni attuali

Consegna delle impostazioni

Precedenza delle impostazioni

Comportamento di recupero e caching

Applicare l’avvio fail-closed

Finestre di dialogo di approvazione della sicurezza

Disponibilità della piattaforma

Registrazione di audit

Considerazioni sulla sicurezza

Vedere anche

Configurazione e accesso

Distribuzione

Utilizzo e costi

Distribuzione dei plugin

Sicurezza e dati

Adozione

Documentation Index

​Requisiti

​Scegliere tra impostazioni gestite dal server e gestite dall’endpoint

​Configurare le impostazioni gestite dal server

​Verificare la consegna delle impostazioni

​Controllo di accesso

​Impostazioni solo gestite

​Limitazioni attuali

​Consegna delle impostazioni

​Precedenza delle impostazioni

​Comportamento di recupero e caching

​Applicare l’avvio fail-closed

​Finestre di dialogo di approvazione della sicurezza

​Disponibilità della piattaforma

​Registrazione di audit

​Considerazioni sulla sicurezza

​Vedere anche

Requisiti

Scegliere tra impostazioni gestite dal server e gestite dall’endpoint

Configurare le impostazioni gestite dal server

Verificare la consegna delle impostazioni

Controllo di accesso

Impostazioni solo gestite

Limitazioni attuali

Consegna delle impostazioni

Precedenza delle impostazioni

Comportamento di recupero e caching

Applicare l’avvio fail-closed

Finestre di dialogo di approvazione della sicurezza

Disponibilità della piattaforma

Registrazione di audit

Considerazioni sulla sicurezza

Vedere anche