Administrar plugins de Claude Code para su organización

​

Pre-install and require plugins

​

Choose a delivery mechanism

• Server-managed settings: establezca las claves de plugin como JSON en Organization settings > Claude Code > Managed settings. Requiere un Owner role en su organización Claude. Una sesión en la nube obtiene esta configuración antes de instalar plugins.
• MDM policies: en macOS, entregue un plist cuyas claves de nivel superior sean las claves de configuración. En Windows, almacene todo el documento JSON como una cadena en un valor de registro. El dominio plist y la clave de registro están en Where each mechanism stores the policy.
• Managed settings file: coloque un managed-settings.json en la ruta del sistema de la plataforma. También puede agregar archivos al directorio drop-in managed-settings.d/ junto a él. Las rutas de archivo por plataforma están en Where each mechanism stores the policy, y las reglas de fusión drop-in están en 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 el marketplace y sus plugins actualizándose en segundo plano, y false lo desactiva. Consulte Set update policy.
• source: github es uno de varios tipos de fuente. Una fuente git toma una url para GitLab o un host interno, y una fuente url toma la dirección de un marketplace.json alojado. Cada forma de fuente está en la marketplace reference.

• Marketplaces: una entrada de marketplace administrada reemplaza una entrada de menor precedencia con el mismo nombre, y los campos de las dos entradas no se fusionan.
• Copias --plugin-dir: --plugin-dir carga un plugin desde un directorio local para una sesión. Para lo que sucede cuando el nombre de esa copia coincide con un plugin que su enabledPlugins administrado nombra, consulte Name conflicts.

​

Require plugins per repository

• Sesiones interactivas: Claude Code registra el marketplace solo después de que el colaborador acepta el workspace trust dialog para esa carpeta.
• Ejecuciones no interactivas -p: las entradas se aplican solo en una carpeta cuya confianza el usuario ya aceptó interactivamente, o cuya bandera hasTrustDialogAccepted establece en ~/.claude.json.

​

When each surface applies the plugin keys

​

Confirm the rollout

• En una máquina: inicie Claude Code y ejecute /plugin. El marketplace y los plugins se enumeran.
• En CI: ejecute claude -p con --output-format stream-json --verbose. El evento init enumera los plugins cargados bajo 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: Claude Code nunca escribe en el seed y fuerza autoUpdate apagado para marketplaces de seed.
• Las entradas de seed tienen precedencia: en cada inicio, un marketplace declarado en el seed sobrescribe la entrada del usuario con el mismo nombre. Los usuarios optan por no participar en un plugin de seed con claude plugin disable, no eliminando el marketplace.
• La actualización y eliminación fallan: claude plugin marketplace update <name> y remove sin --scope en un marketplace de seed fallan con un mensaje que nombra el directorio del seed.
• La política aún se aplica: la allowlist y blocklist verifican la fuente registrada de un marketplace de seed también. Permita la fuente desde la que compiló el seed.

​

Restrict what users can install

• Antes de una descarga: las listas se aplican cuando un usuario agrega un marketplace y en cada instalación, actualización, actualización y auto-actualización.
• Al inicio de la sesión: las listas se aplican nuevamente a los plugins que ya están instalados, por lo que un plugin instalado cuya fuente de marketplace ya no coincide no se carga. /plugin lo enumera con Marketplace "<name>" is not in the allowed marketplace list o Marketplace "<name>" is blocked by enterprise policy.

• La consola de administración de claude.ai: Claude Code aplica ambas listas en las sesiones que leen configuración administrada por servidor. claude.ai también las verifica cuando alguien en su organización agrega un nuevo marketplace desde un repositorio git en claude.ai, o desde Customize en la aplicación de escritorio de Claude fuera de su pestaña Code. Eso cubre un marketplace que un miembro agrega para su propia cuenta y uno agregado para toda la organización bajo Organization settings > Plugins. claude.ai rechaza un repositorio que la allowlist no admite o que la blocklist nombra. No vuelve a verificar un marketplace que se agregó en cualquiera de los dos lugares antes de establecer las listas, y no verifica plugins cargados.
• Un archivo de configuración administrada, política de nivel de SO u otra fuente administrada: Claude Code aplica ambas listas donde lee esa fuente. claude.ai no la lee.

​

Control matrix

• enabledPlugins: puede establecerla en cualquier alcance, y la configuración administrada la bloquea.
• syncClaudeAiPlugins: cada usuario también puede establecerla en su propia configuración de usuario o local. Consulte su alcance en la referencia de configuración.
• CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: esta es una variable de entorno que entrega a través del bloque env administrado que se muestra bajo Turn updates off for the whole fleet.

​

Aliases for the marketplace keys

• Version: los alias requieren Claude Code v2.1.232 o posterior, y los clientes más antiguos los ignoran. En un archivo que una flota mixta lee, mantenga los nombres canónicos.
• Ambas grafías establecidas: cuando un archivo establece ambas grafías, se aplica el valor de la clave canónica.

​

Allowlist with strictKnownMarketplaces

• github: { "source": "github", "repo": "your-org/approved-plugins" }, con ref y path opcionales.
• Comodín de propietario de github: { "source": "github", "repo": "your-org/*" } coincide con cada repositorio bajo ese propietario. El * debe representar el nombre completo del repositorio. Claude Code ignora entradas como */plugins y your-org/tools-* como inválidas, por lo que no coinciden con nada. Requiere Claude Code v2.1.223 o posterior.
• git: { "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }, con ref y path opcionales.
• url: { "source": "url", "url": "https://plugins.example.com/marketplace.json" }, con headers opcionales.
• file y directory: { "source": "file", "path": "/opt/marketplace/marketplace.json" } o { "source": "directory", "path": "/opt/marketplace/plugins" }, con rutas absolutas.
• hostPattern: { "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }, coincidido contra el host de fuentes github, git y url. El patrón coincide en cualquier lugar del nombre de host, así que anclelo con ^ y $ como se muestra para coincidir con el host completo. Una fuente github siempre cuenta como github.com. Use una entrada hostPattern para un GitHub Enterprise Server o host GitLab donde los desarrolladores crean sus propios marketplaces. La página GHES tiene el ejemplo trabajado.
• pathPattern: { "source": "pathPattern", "pathPattern": "^/opt/approved/" }, coincidido contra la path de fuentes file y directory. El patrón coincide en cualquier lugar de la ruta, así que comience con ^ para fijar un prefijo de directorio. ".*" permite cada ruta local.
• skills-dir: { "source": "skills-dir" } mantiene skills-directory plugins cargándose mientras se establece una allowlist, y no coincide con ningún marketplace.

​

How entries match

• Una entrada sin ref no cubre una fuente con ref: "main".
• Una entrada para your-org/your-marketplace no cubre una URL git que clona el mismo repositorio.
• Una barra diagonal final, un sufijo .git o ssh:// en lugar de https:// es un valor diferente. Cuando un marketplace puede clonarse por más de una URL, prefiera una entrada hostPattern.

​

Keep skills-directory plugins loading

​

Marketplaces hosted on claude.ai

​

Lock every source out

​

Blocklist with blockedMarketplaces

• Las URLs de Git se canonicalizan, por lo que las formas git@ y https://, sufijos .git y barras diagonales finales de un repositorio github.com coinciden con la misma entrada.
• Una entrada github también bloquea la URL git equivalente, y viceversa.
• Para una entrada owner/*, la comparación de propietario no distingue mayúsculas de minúsculas.
• Una entrada sin ref o path bloquea cada ref y path de los repositorios que coincide.

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

• La allowlist no registra nada: una entrada extraKnownMarketplaces lo hace, y debe pasar la allowlist. Claude Code rechaza registrar un marketplace administrado cuya fuente la allowlist no coincide.
• El marketplace oficial se registra a sí mismo solo en una sesión de terminal interactiva: incluso allí, se registra solo cuando la allowlist lo permite. Una ejecución -p o una terminal adjunta a una sesión en la nube nunca lo registra.
• Un intento bloqueado se recuerda: si una máquina alguna vez se ejecutó bajo una política que bloqueaba el marketplace oficial, Claude Code registra el intento bloqueado y no lo reintenta después de que cambia la política. Un bloqueo [] es una política de ese tipo. Esa máquina lo registra nuevamente solo a través de una entrada extraKnownMarketplaces como la de esta política, una entrada enabledPlugins para uno de sus plugins, o un /plugin marketplace add manual.

​

Set update policy

​

Turn auto-update on or off per marketplace

• Si la entrada administrada establece el campo, Claude Code rechaza el toggle /plugin del usuario con un error que comienza Auto-update for '<name>' is set by.
• Si la entrada administrada deja el campo sin establecer, el toggle del usuario persiste.

​

Turn updates off for the whole fleet

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

​

Assign release channels to user groups

• Implemente configuración administrada por punto final separada, como un archivo de configuración administrada o un perfil MDM, en los dispositivos de cada grupo. Para verificar si el archivo o perfil por grupo se aplica en un dispositivo que también tiene una fuente de toda la organización, consulte How Claude Code combines managed sources.
• Defina una política de puerta de enlace de aplicaciones Claude por grupo. La puerta de enlace aplica la primera política cuya regla de coincidencia se ajusta a un usuario, así que ordene las políticas para que cada usuario llegue a la política de su grupo. El mapa extraKnownMarketplaces de esa política no se fusiona con el de ninguna otra política, así que enumere cada marketplace que el grupo necesita en él, no solo su 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

• Orientación por usuario o por grupo: cada clave de plugin se aplica a cada usuario que recibe la configuración. La configuración administrada por servidor entrega una configuración por organización. Para política por grupo, use configuración administrada por punto final separada o políticas de puerta de enlace, como bajo Assign release channels to user groups.
• Restricción de entradas dentro de un marketplace permitido: la allowlist coincide con fuentes de marketplace. Para bloquear un plugin de un marketplace permitido, establézcalo en false en enabledPlugins administrado.
• Ocultación de /plugin: ninguna clave desactiva el comando. El equivalente más cercano combina una allowlist que nombra solo su marketplace, entradas enabledPlugins administradas para los plugins que suministra, y disableSideloadFlags.
• Cierre de --plugin-dir a través de la allowlist: la allowlist no cubre --plugin-dir. disableSideloadFlags lo hace.
• Aplicación de los toggles de plugin de claude.ai a través de estas claves: Organization settings > Plugins & skills no establece las claves en esta página. Lo que los miembros y su organización activan allí llega a la CLI como synced plugins, que tienen sus propios controles.

​

Troubleshoot policy

• El archivo administrado no se analizó: cuando un managed-settings.json no es JSON válido, Claude Code rechaza iniciar e imprime un error que nombra el archivo. Un archivo que se analiza pero tiene una entrada inválida mantiene el resto de su política. Consulte Invalid entries in managed settings.
• La fuente administrada no se cargó: ejecute /status y busque Enterprise managed settings en la línea Setting sources. Si falta, la fuente no se cargó.
• Un usuario reporta blocked by enterprise policy: el mensaje nombra el marketplace o su fuente. Para una allowlist, también enumera las fuentes permitidas. Las entradas orientadas al usuario están en Troubleshoot plugins.
• Un plugin que el usuario deshabilitó en ~/.claude/settings.json aún se carga: otra fuente de configuración lo re-habilitó, como una entrada enabledPlugins administrada que lo fuerza-habilita. /plugin y claude plugin list muestran Disabled in ~/.claude/settings.json but still loads con esa fuente de configuración.

​

Next steps

• Marketplace reference: los valores source que extraKnownMarketplaces, strictKnownMarketplaces y blockedMarketplaces aceptan
• Host and maintain a marketplace: ejecute el marketplace al que apunta su política
• Plugin security and trust: lo que un plugin puede hacer en una máquina y cómo revisar uno antes de instalar
• Server-managed settings: entregue estas claves desde la consola de administración de claude.ai
• Troubleshoot plugins: los mensajes que ven los usuarios cuando la política los bloquea