为您的组织管理 Claude Code plugins

​

预安装和要求插件

​

选择交付机制

• 服务器托管设置：在组织设置 > Claude Code > 托管设置处将插件键设置为 JSON。需要在您的 Claude 组织中具有所有者角色。云会话在安装插件之前获取这些设置。
• MDM 策略：在 macOS 上，交付一个 plist，其顶级键是设置键。在 Windows 上，将整个 JSON 文档作为字符串存储在注册表值中。plist 域和注册表键在每个机制存储策略的位置中。
• 托管设置文件：在平台的系统路径处放置 managed-settings.json。您也可以将文件添加到其旁边的 managed-settings.d/ 放入目录。每个平台的文件路径在每个机制存储策略的位置中，放入合并规则在跨团队拆分基于文件的策略中。

​

哪个托管源在机器上应用

​

要求市场及其插件

{
  "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 使市场及其插件在后台刷新，false 关闭它。请参阅设置更新策略。
• source：github 是几种源类型之一。git 源为 GitLab 或内部主机采用 url，url 源采用托管 marketplace.json 的地址。每个源形状在市场参考中。

• 市场：托管市场条目替换具有相同名称的较低优先级条目，两个条目的字段不合并。
• --plugin-dir 副本：--plugin-dir 为一个会话从本地目录加载插件。有关当该副本的名称与您的托管 enabledPlugins 命名的插件匹配时会发生什么，请参阅名称冲突。

​

按存储库要求插件

• 交互式会话：Claude Code 仅在贡献者接受该文件夹的工作区信任对话后注册市场。
• 非交互式 -p 运行 ：条目仅在贡献者已交互式接受其信任的文件夹中应用，或您在 ~/.claude.json 中设置其 hasTrustDialogAccepted 标志的文件夹中应用。

​

每个表面何时应用插件键

​

确认推出

• 在一台机器上：启动 Claude Code 并运行 /plugin。市场和插件被列出。
• 在 CI 中：使用 --output-format stream-json --verbose 运行 claude -p。init 事件在 plugins 下列出加载的插件。

​

为容器和 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

• 只读：Claude Code 从不写入播种并为播种市场强制 autoUpdate 关闭。
• 播种条目优先：在每次启动时，播种中声明的市场覆盖用户的同名条目。用户使用 claude plugin disable 选择退出播种插件，而不是通过删除市场。
• 更新和删除失败：claude plugin marketplace update <name> 和在播种市场上不带 --scope 的 remove 失败，并显示命名播种目录的消息。
• 策略仍然适用：允许列表和阻止列表也检查播种市场的记录源。允许您构建播种的源。

​

限制用户可以安装的内容

• 在下载之前：当用户添加市场以及在每次安装、更新、刷新和自动更新时应用列表。
• 在会话开始时：列表再次应用于已安装的插件，因此已安装的插件其市场源不再匹配不加载。/plugin 将其列为 Marketplace "<name>" is not in the allowed marketplace list 或 Marketplace "<name>" is blocked by enterprise policy。

• claude.ai 管理控制台：Claude Code 在读取服务器托管设置的会话中执行两个列表。claude.ai 也在您组织中的任何人从 git 存储库在 claude.ai 上添加新市场时检查它们，或从 Claude Desktop 应用外其 Code 选项卡的自定义中检查。这涵盖成员为自己的账户添加的市场和在组织设置 > 插件下为整个组织添加的市场。claude.ai 拒绝允许列表不允许或阻止列表命名的存储库。它不重新检查在您设置列表之前在任一位置添加的市场，也不检查上传的插件。
• 托管设置文件、OS 级策略或其他托管源：Claude Code 在读取该源的地方执行两个列表。claude.ai 不读取它。

​

控制矩阵

• enabledPlugins：您可以在任何范围内设置它，托管设置锁定它。
• syncClaudeAiPlugins：每个用户也可以在自己的用户或本地设置中设置它。请参阅其设置参考中的范围。
• CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL：这是一个环境变量，您通过关闭整个车队的更新下显示的托管 env 块交付。

​

市场键的别名

• 版本：别名需要 Claude Code v2.1.232 或更高版本，较旧的客户端忽略它们。在混合车队读取的文件中，保持规范名称。
• 两个拼写都设置：当文件设置两个拼写时，规范键的值应用。

​

使用 strictKnownMarketplaces 的允许列表

• github：{ "source": "github", "repo": "your-org/approved-plugins" }，带可选的 ref 和 path。
• github 所有者通配符：{ "source": "github", "repo": "your-org/*" } 匹配该所有者下的每个存储库。* 必须代表整个存储库名称。Claude Code 忽略诸如 */plugins 和 your-org/tools-* 之类的条目作为无效，因此它们不匹配任何内容。需要 Claude Code v2.1.223 或更高版本。
• git：{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }，带可选的 ref 和 path。
• url：{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }，带可选的 headers。
• file 和 directory：{ "source": "file", "path": "/opt/marketplace/marketplace.json" } 或 { "source": "directory", "path": "/opt/marketplace/plugins" }，带绝对路径。
• hostPattern：{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }，与 github、git 和 url 源的主机匹配。该模式在主机名中的任何地方匹配，因此如所示用 ^ 和 $ 锚定以匹配整个主机。github 源始终计为 github.com。对于开发人员创建自己的市场的 GitHub Enterprise Server 或 GitLab 主机，使用 hostPattern 条目。GHES 页面有工作示例。
• pathPattern：{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }，与 file 和 directory 源的 path 匹配。该模式在路径中的任何地方匹配，因此以 ^ 开头以固定目录前缀。".*" 允许每个本地路径。
• skills-dir：{ "source": "skills-dir" } 在设置允许列表时保持技能目录插件加载，并不匹配任何市场。

​

条目如何匹配

• 没有 ref 的条目不覆盖具有 ref: "main" 的源。
• your-org/your-marketplace 的条目不覆盖克隆相同存储库的 git URL。
• 尾部斜杠、.git 后缀或 ssh:// 代替 https:// 是不同的值。当市场可以通过多个 URL 克隆时，更喜欢 hostPattern 条目。

​

保持技能目录插件加载

​

在 claude.ai 上托管的市场

​

锁定每个源

​

使用 blockedMarketplaces 的阻止列表

• Git URL 被规范化，因此一个 github.com 存储库的 git@ 和 https:// 形式、.git 后缀和尾部斜杠都匹配相同的条目。
• github 条目也阻止等效的 git URL，反之亦然。
• 对于 owner/* 条目，所有者比较不区分大小写。
• 没有 ref 或 path 的条目阻止它匹配的存储库的每个 ref 和 path。

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

​

允许官方市场和您自己的

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

• 允许列表不注册任何内容：extraKnownMarketplaces 条目注册，它本身必须通过允许列表。Claude Code 拒绝注册其源允许列表不匹配的托管市场。
• 官方市场仅在交互式终端会话中注册自己：即使在那里，它也仅在允许列表允许时注册。-p 运行或附加到云会话的终端从不注册它。
• 阻止的尝试被记住：如果机器曾在阻止官方市场的策略下运行，Claude Code 记录阻止的尝试，并在策略更改后不重试。[] 锁定是一个这样的策略。该机器仅通过 extraKnownMarketplaces 条目（例如此策略中的条目）、其一个插件的 enabledPlugins 条目或手动 /plugin marketplace add 再次注册它。

​

设置更新策略

​

按市场打开或关闭自动更新

• 如果托管条目设置字段，Claude Code 拒绝用户的 /plugin 切换，错误以 Auto-update for '<name>' is set by 开头。
• 如果托管条目保留字段未设置，用户的切换持续。

​

关闭整个车队的更新

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

​

为用户组分配发布频道

• 将单独的端点托管设置（例如托管设置文件或 MDM 配置文件）部署到每个组的设备。要检查按组文件或配置文件是否在也有组织范围源的设备上应用，请参阅Claude Code 如何组合托管源。
• 为每个组定义一个Claude 应用网关策略。网关应用第一个匹配规则适合用户的策略，因此订购策略以便每个用户到达其组的策略。该策略的 extraKnownMarketplaces 映射不与任何其他策略的合并，因此在其中列出组需要的每个市场，而不仅仅是其频道市场。

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

​

推荐插件

​

审计和审查

​

OpenTelemetry 事件

​

Analytics API

​

规划托管设置无法执行的内容

• 按用户或按组目标：每个插件键应用于接收设置的每个用户。服务器托管设置为每个组织交付一个配置。对于按组策略，使用单独的端点托管设置或网关策略，如为用户组分配发布频道下所述。
• 限制允许市场内的条目：允许列表匹配市场源。要从允许的市场阻止一个插件，在托管 enabledPlugins 中将其设置为 false。
• 隐藏 /plugin：没有键禁用命令。最接近的等效项结合仅命名您的市场的允许列表、您提供的插件的托管 enabledPlugins 条目和 disableSideloadFlags。
• 通过允许列表门控 --plugin-dir：允许列表不覆盖 --plugin-dir。disableSideloadFlags 覆盖。
• 通过这些键执行 claude.ai 插件切换：组织设置 > 插件和技能不设置此页面上的键。成员和您的组织在那里打开的内容作为同步插件到达 CLI，它们有自己的控制。

​

策略故障排除

• 托管文件未解析：当 managed-settings.json 不是有效的 JSON 时，Claude Code 拒绝启动并打印命名文件的错误。解析但有一个无效条目的文件保持其策略的其余部分。请参阅托管设置中的无效条目。
• 托管源未加载：运行 /status 并在 Setting sources 行中查找 Enterprise managed settings。如果缺少，源未加载。
• 用户报告 blocked by enterprise policy：消息命名市场或其源。对于允许列表，它也列出允许的源。面向用户的条目在插件故障排除上。
• 用户在 ~/.claude/settings.json 中禁用的插件仍然加载：另一个设置源重新启用它，例如强制启用它的托管 enabledPlugins 条目。/plugin 和 claude plugin list 显示 Disabled in ~/.claude/settings.json but still loads 与该设置源。

​

后续步骤

• 市场参考：extraKnownMarketplaces、strictKnownMarketplaces 和 blockedMarketplaces 接受的 source 值
• 托管和维护市场：运行您的策略指向的市场
• 插件安全和信任：插件可以在机器上做什么以及在安装前如何审查一个
• 服务器托管设置：从 claude.ai 管理控制台交付这些键
• 插件故障排除：策略阻止用户时看到的消息