Gerenciar plugins do Claude Code para sua organização

​

Pre-install and require plugins

​

Choose a delivery mechanism

• Server-managed settings: defina as chaves de plugin como JSON em Organization settings > Claude Code > Managed settings. Requer uma função Owner na sua organização Claude. Uma sessão em nuvem busca essas configurações antes de instalar plugins.
• MDM policies: no macOS, entregue um plist cujas chaves de nível superior são as chaves de configurações. No Windows, armazene o documento JSON inteiro como uma string em um valor de registro. O domínio plist e a chave de registro estão em Where each mechanism stores the policy.
• Managed settings file: coloque um managed-settings.json no caminho do sistema da plataforma. Você também pode adicionar arquivos ao diretório drop-in managed-settings.d/ ao lado dele. Os caminhos de arquivo por plataforma estão em Where each mechanism stores the policy, e as regras de mesclagem drop-in estão em 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 mantém o marketplace e seus plugins atualizando em segundo plano, e false desativa isso. Veja Set update policy.
• source: github é um de vários tipos de fonte. Uma fonte git leva uma url para GitLab ou um host interno, e uma fonte url leva o endereço de um marketplace.json hospedado. Cada forma de fonte está na marketplace reference.

• Marketplaces: uma entrada de marketplace gerenciada substitui uma entrada de precedência mais baixa com o mesmo nome, e os campos das duas entradas não se mesclam.
• Cópias --plugin-dir: --plugin-dir carrega um plugin de um diretório local para uma sessão. Para o que acontece quando o nome dessa cópia corresponde a um plugin que seu enabledPlugins gerenciado nomeia, veja Name conflicts.

​

Require plugins per repository

• Sessões interativas: o Claude Code registra o marketplace apenas depois que o contribuidor aceita o workspace trust dialog para essa pasta.
• Execuções não-interativas -p: as entradas se aplicam apenas em uma pasta cuja confiança o usuário já aceitou interativamente, ou cuja flag hasTrustDialogAccepted você definiu em ~/.claude.json.

​

When each surface applies the plugin keys

​

Confirm the rollout

• Em uma máquina: inicie o Claude Code e execute /plugin. O marketplace e os plugins estão listados.
• Em CI: execute claude -p com --output-format stream-json --verbose. O evento init lista os plugins carregados sob plugins.

​

Seed containers and 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

• Read-only: o Claude Code nunca escreve no seed e força autoUpdate desligado para marketplaces de seed.
• Entradas de seed têm precedência: em cada inicialização, um marketplace declarado no seed sobrescreve a entrada do usuário com o mesmo nome. Os usuários desativam um plugin de seed com claude plugin disable, não removendo o marketplace.
• Atualizar e remover falham: claude plugin marketplace update <name> e remove sem --scope em um marketplace de seed falham com uma mensagem que nomeia o diretório do seed.
• A política ainda se aplica: a allowlist e blocklist verificam a fonte registrada de um marketplace de seed também. Permita a fonte de onde você construiu o seed.

​

Restringir o que os usuários podem instalar

• Antes de um download: as listas se aplicam quando um usuário adiciona um marketplace e em cada instalação, atualização, refresh e atualização automática.
• No início da sessão: as listas se aplicam novamente aos plugins que já estão instalados, de modo que um plugin instalado cuja fonte de marketplace não corresponde mais não é carregado. O /plugin o lista com Marketplace "<name>" is not in the allowed marketplace list ou Marketplace "<name>" is blocked by enterprise policy.

• O console de administração do claude.ai: o Claude Code aplica ambas as listas nas sessões que leem configurações gerenciadas pelo servidor. O claude.ai também as verifica quando qualquer pessoa da sua organização adiciona um novo marketplace a partir de um repositório git no claude.ai, ou a partir de Customize no aplicativo Claude Desktop fora da aba Code. Isso abrange um marketplace que um membro adiciona para a própria conta e um adicionado para toda a organização em Organization settings > Plugins. O claude.ai recusa um repositório que a allowlist não admite ou que a lista de bloqueio nomeia. Ele não verifica novamente um marketplace que foi adicionado em qualquer um desses lugares antes de você definir as listas, e não verifica plugins enviados por upload.
• Um arquivo de configurações gerenciadas, uma política no nível do sistema operacional ou outra fonte gerenciada: o Claude Code aplica ambas as listas onde lê essa fonte. O claude.ai não a lê.

​

Matriz de controle

• enabledPlugins: você pode defini-la em qualquer escopo, e as configurações gerenciadas a bloqueiam.
• syncClaudeAiPlugins: cada usuário também pode defini-la nas próprias configurações de usuário ou locais. Consulte o escopo dela na referência de configurações.
• CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: esta é uma variável de ambiente que você fornece por meio do bloco env gerenciado mostrado em Desativar atualizações para toda a frota.
• allowManagedModsOnly: esta é uma opção de um plugin integrado, que você define em pluginConfigs nas configurações gerenciadas. Consulte Impedir que mods instalados pelo usuário sejam carregados.

​

Aliases para as chaves de marketplace

• Versão: os aliases requerem o Claude Code v2.1.232 ou posterior, e clientes mais antigos os ignoram. Em um arquivo lido por uma frota mista, mantenha os nomes canônicos.
• Ambas as grafias definidas: quando um arquivo define ambas as grafias, o valor da chave canônica é aplicado.

​

Allowlist com strictKnownMarketplaces

• github: { "source": "github", "repo": "your-org/approved-plugins" }, com ref e path opcionais.
• Curinga de proprietário github: { "source": "github", "repo": "your-org/*" } corresponde a todos os repositórios desse proprietário. O * deve representar o nome inteiro do repositório. O Claude Code ignora entradas como */plugins e your-org/tools-* como inválidas, portanto elas não correspondem a nada. Requer o Claude Code v2.1.223 ou posterior.
• git: { "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }, com ref e path opcionais.
• url: { "source": "url", "url": "https://plugins.example.com/marketplace.json" }, com headers opcionais.
• file e directory: { "source": "file", "path": "/opt/marketplace/marketplace.json" } ou { "source": "directory", "path": "/opt/marketplace/plugins" }, com caminhos absolutos.
• hostPattern: { "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }, comparado com o host das fontes github, git e url. O padrão corresponde em qualquer parte do nome do host, então ancore-o com ^ e $ como mostrado para corresponder ao host inteiro. Uma fonte github sempre conta como github.com. Use uma entrada hostPattern para um host do GitHub Enterprise Server ou do GitLab onde os desenvolvedores criam os próprios marketplaces. A página do GHES tem o exemplo completo.
• pathPattern: { "source": "pathPattern", "pathPattern": "^/opt/approved/" }, comparado com o path das fontes file e directory. O padrão corresponde em qualquer parte do caminho, então inicie-o com ^ para fixar um prefixo de diretório. ".*" permite todos os caminhos locais.
• skills-dir: { "source": "skills-dir" } não corresponde a nenhum marketplace. Para saber o que ela faz, consulte Manter plugins de diretório de skills carregando.

​

Como as entradas correspondem

• Uma entrada sem ref não abrange uma fonte com ref: "main".
• Uma entrada para your-org/your-marketplace não abrange uma URL git que clona o mesmo repositório.
• Uma barra final, um sufixo .git ou ssh:// no lugar de https:// é um valor diferente. Quando um marketplace pode ser clonado por mais de uma URL, prefira uma entrada hostPattern.

​

Manter plugins de diretório de skills carregando

​

Marketplaces hospedados no claude.ai

​

Bloquear todas as fontes

​

Lista de bloqueio com blockedMarketplaces

• URLs git são canonicalizadas, então as formas git@ e https://, os sufixos .git e as barras finais de um mesmo repositório github.com correspondem todos à mesma entrada.
• Uma entrada github também bloqueia a URL git equivalente, e vice-versa.
• Para uma entrada owner/*, a comparação do proprietário não diferencia maiúsculas de minúsculas.
• Uma entrada sem ref ou path bloqueia todos os refs e caminhos dos repositórios aos quais corresponde.

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

​

Permitir o marketplace oficial e o seu próprio

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

• A allowlist não registra nada: uma entrada extraKnownMarketplaces registra, e ela própria deve passar pela allowlist. O Claude Code se recusa a registrar um marketplace gerenciado cuja fonte não corresponde à allowlist.
• O marketplace oficial se registra sozinho apenas em uma sessão interativa de terminal: mesmo assim, ele só se registra quando a allowlist o permite. Uma execução com -p ou um terminal conectado a uma sessão na nuvem nunca o registra.
• Uma tentativa bloqueada é lembrada: se uma máquina já foi executada sob uma política que bloqueava o marketplace oficial, o Claude Code registra a tentativa bloqueada e não tenta novamente depois que a política muda. Um bloqueio [] é uma dessas políticas. Essa máquina só o registra novamente por meio de uma entrada extraKnownMarketplaces como a desta política, de uma entrada enabledPlugins para um de seus plugins ou de um /plugin marketplace add manual.

​

Set update policy

​

Turn auto-update on or off per marketplace

• Se a entrada gerenciada define o campo, o Claude Code recusa o toggle /plugin do usuário com um erro que começa Auto-update for '<name>' is set by.
• Se a entrada gerenciada deixa o campo indefinido, o toggle do usuário persiste.

​

Turn updates off for the whole fleet

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

​

Assign release channels to user groups

• Implante configurações gerenciadas por endpoint separadas, como um arquivo de configurações gerenciadas ou um perfil MDM, para os dispositivos de cada grupo. Para verificar se o arquivo ou perfil por grupo se aplica em um dispositivo que também tem uma fonte de nível de organização, veja How Claude Code combines managed sources.
• Defina uma política de gateway de aplicativos Claude por grupo. Por padrão, o gateway aplica a primeira política cuja regra de correspondência se encaixa em um usuário, então ordene as políticas para que cada usuário chegue à política do seu grupo. O mapa extraKnownMarketplaces dessa política não se mescla com o de qualquer outra política, então liste cada marketplace que o grupo precisa nele, não apenas seu marketplace de canal.

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

​

Recommend plugins

​

Audit and review

​

OpenTelemetry events

​

Analytics API

​

Plan for what managed settings can’t enforce

• Direcionamento por usuário ou por grupo: cada chave de plugin se aplica a cada usuário que recebe as configurações. As configurações gerenciadas pelo servidor entregam uma configuração por organização. Para política por grupo, use configurações gerenciadas por endpoint separadas ou políticas de gateway, como sob Assign release channels to user groups.
• Restringindo entradas dentro de um marketplace permitido: a allowlist corresponde a fontes de marketplace. Para bloquear um plugin de um marketplace permitido, defina-o como false em enabledPlugins gerenciado.
• Ocultando /plugin: nenhuma chave desativa o comando. O equivalente mais próximo combina uma allowlist nomeando apenas seu marketplace, entradas enabledPlugins gerenciadas para os plugins que você fornece, e disableSideloadFlags.
• Controlando --plugin-dir através da allowlist: a allowlist não cobre --plugin-dir. disableSideloadFlags cobre.
• Aplicando os toggles de plugin do claude.ai através dessas chaves: Organization settings > Plugins & skills não define as chaves nesta página. O que os membros e sua organização ativam lá chega ao CLI como synced plugins, que têm seus próprios controles.

​

Troubleshoot policy

• O arquivo gerenciado não foi analisado: quando um managed-settings.json não é JSON válido, o Claude Code recusa iniciar e imprime um erro nomeando o arquivo. Um arquivo que analisa mas tem uma entrada inválida mantém o resto de sua política. Veja Invalid entries in managed settings.
• A fonte gerenciada não carregou: execute /status e procure por Enterprise managed settings na linha Setting sources. Se estiver faltando, a fonte não carregou.
• Um usuário relata blocked by enterprise policy: a mensagem nomeia o marketplace ou sua fonte. Para uma allowlist, também lista as fontes permitidas. As entradas voltadas para o usuário estão em Troubleshoot plugins.
• Um plugin que o usuário desativou em ~/.claude/settings.json ainda carrega: outra fonte de configurações o re-ativou, como uma entrada enabledPlugins gerenciada que o força-ativa. /plugin e claude plugin list mostram Disabled in ~/.claude/settings.json but still loads com essa fonte de configurações.

​

Next steps

• Marketplace reference: os valores source que extraKnownMarketplaces, strictKnownMarketplaces e blockedMarketplaces aceitam
• Host and maintain a marketplace: execute o marketplace que sua política aponta
• Plugin security and trust: o que um plugin pode fazer em uma máquina e como revisar um antes de instalar
• Manage mods for your organization: desative ou limite mods, os plugins que executam JavaScript dentro do Claude Code
• Server-managed settings: entregue essas chaves do console de administração do claude.ai
• Troubleshoot plugins: as mensagens que os usuários veem quando a política os bloqueia