Gestire i plugin Claude Code per la tua organizzazione

​

Pre-install and require plugins

​

Choose a delivery mechanism

• Server-managed settings: imposta le chiavi del plugin come JSON in Organization settings > Claude Code > Managed settings. Richiede un Owner role nella tua organizzazione Claude. Una sessione cloud recupera queste impostazioni prima di installare i plugin.
• MDM policies: su macOS, consegna un plist le cui chiavi di livello superiore sono le chiavi delle impostazioni. Su Windows, archivia l’intero documento JSON come stringa in un valore di registro. Il dominio plist e la chiave di registro sono in Where each mechanism stores the policy.
• Managed settings file: posiziona un managed-settings.json nel percorso di sistema della piattaforma. Puoi anche aggiungere file alla directory drop-in managed-settings.d/ accanto ad esso. I percorsi dei file per piattaforma sono in Where each mechanism stores the policy, e le regole di merge drop-in sono in Split a file-based policy across teams.

​

Which managed source applies on a machine

​

Require a marketplace and its plugins

{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": { "source": "github", "repo": "your-org/your-marketplace" },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "code-formatter@your-marketplace": true,
    "deploy-helper@your-marketplace": true
  }
}

• autoUpdate: true mantiene il marketplace e i suoi plugin aggiornati in background, e false lo disattiva. Vedi Set update policy.
• source: github è uno di diversi tipi di fonte. Una fonte git accetta un url per GitLab o un host interno, e una fonte url accetta l’indirizzo di un marketplace.json ospitato. Ogni forma di fonte è nel marketplace reference.

• Marketplaces: una voce di marketplace gestita sostituisce una voce di precedenza inferiore con lo stesso nome, e i campi delle due voci non si uniscono.
• Copie --plugin-dir: --plugin-dir carica un plugin da una directory locale per una sessione. Per ciò che accade quando il nome di quella copia corrisponde a un plugin che il tuo enabledPlugins gestito nomina, vedi Name conflicts.

​

Require plugins per repository

• Sessioni interattive: Claude Code registra il marketplace solo dopo che il contributore accetta il workspace trust dialog per quella cartella.
• Esecuzioni non interattive -p: le voci si applicano solo in una cartella la cui fiducia l’utente ha già accettato interattivamente, o il cui flag hasTrustDialogAccepted hai impostato in ~/.claude.json.

​

When each surface applies the plugin keys

​

Confirm the rollout

• On one machine: start Claude Code and run /plugin. The marketplace and the plugins are listed.
• In CI: run claude -p with --output-format stream-json --verbose. The init event lists the loaded plugins under plugins.

​

Contenitori seed e CI

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/your-marketplace
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install code-formatter@your-marketplace

• Sola lettura: Claude Code non scrive mai nel seed e forza autoUpdate disattivato per i marketplace seed.
• Le voci seed hanno la precedenza: ad ogni avvio, un marketplace dichiarato nel seed sovrascrive la voce dell’utente con lo stesso nome. Gli utenti escludono un plugin seed con claude plugin disable, non rimuovendo il marketplace.
• L’aggiornamento e la rimozione non riescono: claude plugin marketplace update <name> e remove senza --scope su un marketplace seed non riescono con un messaggio che nomina la directory del seed.
• La policy si applica comunque: il allowlist e blocklist controllano anche la fonte registrata di un marketplace seed. Consenti la fonte da cui hai compilato il seed.

​

Limitare ciò che gli utenti possono installare

• Prima di un download: gli elenchi si applicano quando un utente aggiunge un marketplace e ad ogni installazione, aggiornamento, refresh e auto-aggiornamento.
• All’avvio della sessione: gli elenchi si applicano di nuovo ai plugin già installati, quindi un plugin installato la cui fonte di marketplace non corrisponde più non si carica. /plugin lo elenca con Marketplace "<name>" is not in the allowed marketplace list o Marketplace "<name>" is blocked by enterprise policy.

• La console di amministrazione claude.ai: Claude Code applica entrambi gli elenchi nelle sessioni che leggono le impostazioni gestite dal server. claude.ai li controlla anche quando chiunque nella vostra organizzazione aggiunge un nuovo marketplace da un repository git su claude.ai, o da Customize nell’app Claude Desktop al di fuori della scheda Code. Questo copre un marketplace che un membro aggiunge per il proprio account e uno aggiunto per l’intera organizzazione in Organization settings > Plugins. claude.ai rifiuta un repository che l’elenco consentito non ammette o che l’elenco bloccato nomina. Non ri-controlla un marketplace che è stato aggiunto in uno dei due posti prima di impostare gli elenchi, e non controlla i plugin caricati.
• Un file di impostazioni gestite, una policy a livello di sistema operativo o un’altra fonte gestita: Claude Code applica entrambi gli elenchi dove legge quella fonte. claude.ai non la legge.

​

Control matrix

• enabledPlugins: potete impostarla in qualsiasi ambito, e le impostazioni gestite la bloccano.
• syncClaudeAiPlugins: ogni utente può anche impostarla nelle proprie impostazioni utente o locali. Vedere il suo ambito nel riferimento delle impostazioni.
• CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: questa è una variabile di ambiente che consegnate attraverso il blocco env gestito mostrato in Disattivare gli aggiornamenti per l’intera flotta.

​

Alias per le chiavi di marketplace

• Versione: gli alias richiedono Claude Code v2.1.232 o successivo, e i client più vecchi li ignorano. In un file che una flotta mista legge, mantenete i nomi canonici.
• Entrambe le ortografie impostate: quando un file imposta entrambe le ortografie, il valore della chiave canonica si applica.

​

Allowlist con strictKnownMarketplaces

• github: { "source": "github", "repo": "your-org/approved-plugins" }, con ref e path opzionali.
• Wildcard del proprietario github: { "source": "github", "repo": "your-org/*" } corrisponde a ogni repository sotto quel proprietario. L’* deve rappresentare l’intero nome del repository. Claude Code ignora voci come */plugins e your-org/tools-* come non valide, quindi non corrispondono a nulla. Richiede Claude Code v2.1.223 o successivo.
• git: { "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }, con ref e path opzionali.
• url: { "source": "url", "url": "https://plugins.example.com/marketplace.json" }, con headers opzionali.
• file e directory: { "source": "file", "path": "/opt/marketplace/marketplace.json" } o { "source": "directory", "path": "/opt/marketplace/plugins" }, con percorsi assoluti.
• hostPattern: { "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }, confrontato con l’host delle fonti github, git e url. Il pattern corrisponde ovunque nel nome host, quindi ancoratelo con ^ e $ come mostrato per corrispondere all’intero host. Una fonte github conta sempre come github.com. Usate una voce hostPattern per un host GitHub Enterprise Server o GitLab dove gli sviluppatori creano i propri marketplace. La pagina GHES ha l’esempio elaborato.
• pathPattern: { "source": "pathPattern", "pathPattern": "^/opt/approved/" }, confrontato con il path delle fonti file e directory. Il pattern corrisponde ovunque nel percorso, quindi iniziatelo con ^ per fissare un prefisso di directory. ".*" consente ogni percorso locale.
• skills-dir: { "source": "skills-dir" } mantiene il caricamento dei plugin skills-directory mentre è impostato un elenco consentito, e non corrisponde a nessun marketplace.

​

Come le voci corrispondono

• Una voce senza ref non copre una fonte con ref: "main".
• Una voce per your-org/your-marketplace non copre un URL git che clona lo stesso repository.
• Una barra finale, un suffisso .git o ssh:// al posto di https:// è un valore diverso. Quando un marketplace può essere clonato da più di un URL, preferite una voce hostPattern.

​

Mantenere il caricamento dei plugin skills-directory

​

Marketplace ospitati su claude.ai

​

Bloccare ogni fonte

​

Blocklist con blockedMarketplaces

• Gli URL Git sono canonicizzati, quindi i moduli git@ e https://, i suffissi .git e le barre finali di un repository github.com corrispondono tutti alla stessa voce.
• Una voce github blocca anche l’URL git equivalente, e viceversa.
• Per una voce owner/*, il confronto del proprietario è insensibile alle maiuscole.
• Una voce senza ref o path blocca ogni ref e path dei repository che corrisponde.

{
  "blockedMarketplaces": [
    { "source": "github", "repo": "untrusted-org/*" }
  ]
}

​

Consentire il marketplace ufficiale e il vostro

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" },
    { "source": "github", "repo": "your-org/*" },
    { "source": "skills-dir" }
  ],
  "extraKnownMarketplaces": {
    "claude-plugins-official": {
      "source": { "source": "github", "repo": "anthropics/claude-plugins-official" }
    },
    "your-marketplace": {
      "source": { "source": "github", "repo": "your-org/your-marketplace" }
    }
  },
  "enabledPlugins": {
    "code-formatter@your-marketplace": true,
    "deploy-helper@your-marketplace": true
  },
  "disableSideloadFlags": true
}

• L’elenco consentito non registra nulla: una voce extraKnownMarketplaces lo fa, e deve essa stessa passare l’elenco consentito. Claude Code rifiuta di registrare un marketplace gestito la cui fonte l’elenco consentito non corrisponde.
• Il marketplace ufficiale si registra solo in una sessione di terminale interattiva: anche lì, si registra solo quando l’elenco consentito lo consente. Un’esecuzione -p o un terminale collegato a una sessione cloud non lo registra mai.
• Un tentativo bloccato viene ricordato: se una macchina ha mai eseguito una policy che bloccava il marketplace ufficiale, Claude Code registra il tentativo bloccato e non ritenta dopo il cambio di policy. Un blocco [] è una tale policy. Quella macchina lo registra di nuovo solo attraverso una voce extraKnownMarketplaces come quella in questa policy, una voce enabledPlugins per uno dei suoi plugin, o un /plugin marketplace add manuale.

​

Impostare la politica di aggiornamento

​

Attivare o disattivare l’aggiornamento automatico per marketplace

• Se la voce gestita imposta il campo, Claude Code rifiuta l’interruttore /plugin dell’utente con un errore che inizia con Auto-update for '<name>' is set by.
• Se la voce gestita lascia il campo non impostato, l’interruttore dell’utente persiste.

​

Disattivare gli aggiornamenti per l’intera flotta

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

​

Assegnare canali di rilascio ai gruppi di utenti

• Distribuire impostazioni gestite da endpoint separate, come un file di impostazioni gestite o un profilo MDM, ai dispositivi di ogni gruppo. Per verificare se il file o il profilo per gruppo si applica su un dispositivo che ha anche un’origine a livello di organizzazione, consultare Come Claude Code combina le origini gestite.
• Definire una politica gateway delle app Claude per ogni gruppo. Il gateway applica la prima politica la cui regola di corrispondenza si adatta a un utente, quindi ordinare le politiche in modo che ogni utente raggiunga la politica del suo gruppo. La mappa extraKnownMarketplaces di quella politica non si unisce con quella di nessun’altra politica, quindi elencare ogni marketplace di cui il gruppo ha bisogno in essa, non solo il suo marketplace del canale.

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": { "source": "github", "repo": "your-org/stable-tools" }
    }
  }
}

​

Consigliare plugin

​

Audit and review

​

OpenTelemetry events

​

Analytics API

​

Piano per ciò che le impostazioni gestite non possono applicare

• Targeting per utente o per gruppo: ogni chiave plugin si applica a ogni utente che riceve le impostazioni. Le impostazioni gestite dal server forniscono una configurazione per organizzazione. Per la politica per gruppo, utilizzare impostazioni gestite da endpoint separate o politiche gateway, come in Assegnare canali di rilascio ai gruppi di utenti.
• Limitazione delle voci all’interno di un marketplace consentito: l’elenco consentito corrisponde alle fonti del marketplace. Per bloccare un plugin da un marketplace consentito, impostarlo su false in enabledPlugins gestito.
• Nascondere /plugin: nessuna chiave disabilita il comando. L’equivalente più vicino combina un elenco consentito che nomina solo il vostro marketplace, voci enabledPlugins gestite per i plugin che fornite, e disableSideloadFlags.
• Controllare --plugin-dir attraverso l’elenco consentito: l’elenco consentito non copre --plugin-dir. disableSideloadFlags lo fa.
• Applicare gli interruttori plugin claude.ai attraverso queste chiavi: Impostazioni organizzazione > Plugins & skills non imposta le chiavi su questa pagina. Ciò che i membri e la vostra organizzazione attivano lì raggiunge la CLI come plugin sincronizzati, che hanno i loro propri controlli.

​

Risoluzione dei problemi della policy

• Il file gestito non è stato analizzato: quando un managed-settings.json non è un JSON valido, Claude Code rifiuta di avviarsi e stampa un errore che nomina il file. Un file che viene analizzato ma ha una voce non valida mantiene il resto della sua policy. Vedere Voci non valide nelle impostazioni gestite.
• La fonte gestita non è stata caricata: eseguire /status e cercare Enterprise managed settings nella riga Setting sources. Se manca, la fonte non è stata caricata.
• Un utente segnala blocked by enterprise policy: il messaggio nomina il marketplace o la sua fonte. Per un allowlist, elenca anche le fonti consentite. Le voci rivolte all’utente si trovano su Risoluzione dei problemi dei plugin.
• Un plugin che l’utente ha disabilitato in ~/.claude/settings.json continua a caricarsi: un’altra fonte di impostazioni lo ha riabilitato, ad esempio una voce enabledPlugins gestita che lo forza ad abilitarsi. /plugin e claude plugin list mostrano Disabled in ~/.claude/settings.json but still loads con quella fonte di impostazioni.

​

Next steps

• Marketplace reference: the source values extraKnownMarketplaces, strictKnownMarketplaces, and blockedMarketplaces accept
• Host and maintain a marketplace: run the marketplace your policy points at
• Plugin security and trust: what a plugin can do on a machine and how to review one before installing
• Server-managed settings: deliver these keys from the claude.ai admin console
• Troubleshoot plugins: the messages users see when policy blocks them