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.

​

Restrict what users can install

• Antes de um download: as listas se aplicam quando um usuário adiciona um marketplace e em cada instalação, atualização, atualização e auto-atualização.
• No início da sessão: as listas se aplicam novamente aos plugins que já estão instalados, então um plugin instalado cuja fonte de marketplace não corresponde mais não carrega. /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 na sua organização adiciona um novo marketplace de um repositório git no claude.ai, ou de Customize no aplicativo Claude Desktop fora de sua aba Code. Isso cobre um marketplace que um membro adiciona para sua própria conta e um adicionado para toda a organização sob Organization settings > Plugins. O claude.ai recusa um repositório que a allowlist não admite ou que a blocklist nomeia. Ele não re-verifica um marketplace que foi adicionado em qualquer lugar antes de você definir as listas, e não verifica plugins carregados.
• Um arquivo de configurações gerenciadas, política de nível do SO ou outra fonte gerenciada: o Claude Code aplica ambas as listas onde lê essa fonte. O claude.ai não a lê.

​

Control matrix

• enabledPlugins: você pode defini-lo em qualquer escopo, e as configurações gerenciadas o bloqueiam.
• syncClaudeAiPlugins: cada usuário também pode defini-lo em suas próprias configurações de usuário ou local. Veja seu escopo na referência de configurações.
• CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: esta é uma variável de ambiente que você entrega através do bloco env gerenciado mostrado sob Turn updates off for the whole fleet.

​

Aliases for the marketplace keys

• Version: os aliases requerem Claude Code v2.1.232 ou posterior, e clientes mais antigos os ignoram. Em um arquivo que uma frota mista lê, mantenha os nomes canônicos.
• Ambas as grafias definidas: quando um arquivo define ambas as grafias, o valor da chave canônica se aplica.

​

Allowlist with strictKnownMarketplaces

• github: { "source": "github", "repo": "your-org/approved-plugins" }, com ref e path opcionais.
• Wildcard de proprietário github: { "source": "github", "repo": "your-org/*" } corresponde a cada repositório sob esse 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, então não correspondem a nada. Requer 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$" }, correspondido contra o host de fontes github, git e url. O padrão corresponde em qualquer lugar no nome do host, então ancorá-lo com ^ e $ como mostrado para corresponder ao host inteiro. Uma fonte github sempre conta como github.com. Use uma entrada hostPattern para um GitHub Enterprise Server ou host GitLab onde desenvolvedores criam seus próprios marketplaces. A página GHES tem o exemplo trabalhado.
• pathPattern: { "source": "pathPattern", "pathPattern": "^/opt/approved/" }, correspondido contra o path de fontes file e directory. O padrão corresponde em qualquer lugar no caminho, então comece-o com ^ para fixar um prefixo de diretório. ".*" permite cada caminho local.
• skills-dir: { "source": "skills-dir" } mantém skills-directory plugins carregando enquanto uma allowlist está definida, e não corresponde a nenhum marketplace.

​

How entries match

• Uma entrada sem ref não cobre uma fonte com ref: "main".
• Uma entrada para your-org/your-marketplace não cobre 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.

​

Keep skills-directory plugins loading

​

Marketplaces hosted on claude.ai

​

Lock every source out

​

Blocklist with blockedMarketplaces

• URLs de Git são canonicalizadas, então as formas git@ e https://, sufixos .git e barras finais de um repositório github.com todos correspondem à mesma entrada.
• Uma entrada github também bloqueia a URL git equivalente, e vice-versa.
• Para uma entrada owner/*, a comparação de proprietário é insensível a maiúsculas e minúsculas.
• Uma entrada sem ref ou path bloqueia cada ref e caminho dos repositórios que corresponde.

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

​

Allow the official marketplace and your own

{
  "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 faz, e ela mesma deve passar na allowlist. O Claude Code recusa registrar um marketplace gerenciado cuja fonte a allowlist não corresponde.
• O marketplace oficial se registra apenas em uma sessão de terminal interativa: mesmo lá, ele se registra apenas quando a allowlist o permite. Uma execução -p ou um terminal anexado a uma sessão em nuvem nunca o registra.
• Uma tentativa bloqueada é lembrada: se uma máquina já executou sob uma política que bloqueou o marketplace oficial, o Claude Code registra a tentativa bloqueada e não tenta novamente depois que a política muda. Um lockdown [] é uma tal política. Essa máquina o registra novamente apenas através de uma entrada extraKnownMarketplaces como a nesta política, uma entrada enabledPlugins para um de seus plugins, ou 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. 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
• 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