为组织管理插件

托管设置让你决定 Claude Code 在组织每台机器上安装和允许哪些插件，用户无法覆盖。可以通过 claude.ai 管理控制台的服务端托管设置下发，或通过 MDM 或 managed-settings.json 做端点托管下发。本页面向管理员，这里的设置约束的是 Claude Code。注意：claude.ai 管理设置里的 Organization settings > Plugins & skills 是为成员的 claude.ai 账号打开插件，这些插件以同步插件的形式到达 Claude Code，它不设置本页的任何键。

各节按多数推行的顺序排列：要求所有人或按仓库使用插件、给容器和 CI 做种子、限制用户自己能添加什么、设置更新策略，然后审计安装情况。

预装并要求插件

市场是 Claude Code 从 git 仓库、URL 或本地路径获取的插件目录。在机器上注册了市场后，Claude Code 才能从中安装插件。要给整个机群安装插件，在托管设置里同时设置两个键：extraKnownMarketplaces 在每台机器上注册市场，enabledPlugins 指明要安装的插件。

选择下发方式

托管设置通过三种方式之一到达机器：

• 服务端托管设置：在 Organization settings > Claude Code > Managed settings 里以 JSON 设置插件键，需要 Claude 组织的 Owner 角色；云端会话会在安装插件前获取这些设置
• MDM 策略：macOS 上下发顶层键就是设置键的 plist；Windows 上把整个 JSON 文档作为字符串存入注册表值
• 托管设置文件：在平台的系统路径放 managed-settings.json，还可以在它旁边的 managed-settings.d/ 目录添加文件

你有 Claude for Teams 或 Enterprise 组织且设备并非全部纳入 MDM 时用服务端托管设置，否则用 MDM 策略或托管设置文件。默认情况下一台机器上只有这三个来源中的一个生效：Claude Code 用第一个下发了某策略键的来源，顺序是服务端托管设置、MDM 策略、托管设置文件；要应用每个来源，把 managedSourcesBehavior 设为 "merge"。

要求一个市场及其插件

把市场加到 extraKnownMarketplaces 下，以市场自己 marketplace.json 里的 name 为键；然后把每个插件以 plugin-name@marketplace-name 加到 enabledPlugins 下：

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

设置到达机器后，Claude Code 在用户下次会话开始时注册该市场并安装这两个插件。用户在 /plugin 里能看到它们，在自己范围里禁用其中一个也不会阻止它加载，因为托管设置优先。想在每个范围阻止某插件并在市场列表里隐藏它，改在托管 enabledPlugins 里把它设为 false。

autoUpdate 为 true 时市场及其插件在后台保持刷新，false 关闭；source 里 github 是几种来源类型之一：git 来源用 url 指向 GitLab 或内部主机，url 来源用托管的 marketplace.json 的地址。市场是私有 git 仓库时，每个用户需要读权限（git 市场的克隆用用户机器上的 git、已存储的凭据且不弹提示）；对没有 git 主机账号的用户用种子。托管条目还会覆盖来自其他来源的同名市场条目或 --plugin-dir 副本：托管市场条目替换较低优先级的同名条目，两个条目的字段不合并。Anthropic 官方市场 claude-plugins-official 在 enabledPlugins 把它的某个插件设为 true 时不需要 extraKnownMarketplaces 条目，name@claude-plugins-official 条目自己就声明了该市场。

按仓库要求插件

要覆盖某一个仓库的贡献者而不是整个机群，在该仓库的 .claude/settings.json 里设置 extraKnownMarketplaces 和 enabledPlugins。extraKnownMarketplaces 条目只在贡献者已信任的文件夹里生效：交互会话里只有贡献者接受该文件夹的工作区信任对话框后才注册市场；非交互 -p 运行里这些条目只在用户已交互地接受过信任的文件夹，或你在 ~/.claude.json 里设置了 hasTrustDialogAccepted 标志的文件夹里生效。市场按相对路径列出的插件在仓库的 extraKnownMarketplaces 条目生效后从市场副本加载；市场条目指向外部来源（如插件自己的 GitHub 仓库）的插件则不会因此安装。用带相对路径的本地 directory 或 file 来源时，路径相对于仓库的主检出解析，从 git worktree 运行时路径仍指向主检出。要推行带依赖的插件套装，把套装插件放进 enabledPlugins。

各入口何时应用插件键

在 -p 或 CI 运行里，市场和插件在后台安装，所以第一回合可能缺插件；设置 CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1 让运行在第一次查询之前等待安装。确认推行：在一台机器上启动 Claude Code 并运行 /plugin；在 CI 里用 --output-format stream-json --verbose 运行 claude -p，init 事件在 plugins 下列出已加载的插件。

给容器和 CI 做种子

对运行时无法克隆的容器镜像和 CI 运行器，在构建时预填一个插件目录，并用 CLAUDE_CODE_PLUGIN_SEED_DIR 指向它；Claude Code 在启动时注册种子里的市场并原地从种子加载插件缓存，不克隆。种子也服务于没有 git 主机账号的用户。在 CI/CD 里，从私有仓库安装插件前要配置 git 凭据助手（GitHub Actions 上把有市场仓库读权限的令牌导出为 GH_TOKEN，再运行 gh auth setup-git；默认 workflow 令牌只能访问当前仓库）。

1. 构建时安装到种子：把 CLAUDE_CODE_PLUGIN_CACHE_DIR 设为种子路径，使市场和插件安装到那里而不是 ~/.claude/plugins：

   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/plugins 布局相同：known_marketplaces.json、marketplaces/<name>/ 和 cache/<marketplace>/<plugin>/<version>/，可以挂载在与构建时不同的路径。

2. 让运行时指向种子：在容器环境里设置 CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed；用多个种子时，Unix 上用 :、Windows 上用 ; 分隔路径，Claude Code 用第一个含有给定市场或插件缓存的种子

3. 启用插件：种子里的插件不会自己启用，在托管设置或仓库的 .claude/settings.json 里为你想加载的每个种子插件设置 enabledPlugins

验证种子：在镜像里用 --output-format stream-json --verbose 运行 claude -p，init 事件的 plugins 列表里每个已加载插件的 path 应在种子之下。种子市场的规则：只读（Claude Code 从不写种子，并对种子市场强制关闭 autoUpdate）；种子条目优先（每次启动时，种子里声明的市场覆盖用户同名条目，用户用 claude plugin disable 退出种子插件，而不是移除市场）；更新和移除会失败（对种子市场不带 --scope 的 claude plugin marketplace update <name> 和 remove 失败并给出点名种子目录的消息）；策略仍适用（允许列表和阻止列表也检查种子市场记录的来源，所以要允许你构建种子所用的来源）。对没有出站 git 访问的机群，把种子与共享挂载上的 directory 或 file 市场来源结合，并同时设置 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1（它也关闭插件自动更新）。

限制用户能安装什么

托管的 strictKnownMarketplaces 允许列表和 blockedMarketplaces 阻止列表决定插件可以来自哪些市场来源（市场的来源是 Claude Code 获取它所用的 git 仓库、URL 或本地路径）。两个列表在任何东西下载之前和会话开始时都会应用：用户添加市场时，以及每次安装、更新、刷新和自动更新时；以及会话开始时对已安装的插件再次应用，所以市场来源不再匹配的已安装插件不会加载（/plugin 列出它，附 Marketplace "<name>" is not in the allowed marketplace list 之类的原因）。两个列表在哪里被强制取决于你在哪里设置：在 claude.ai 管理控制台里，Claude Code 在读取服务端托管设置的会话里强制两者，claude.ai 也会在组织里有人从 claude.ai 上的 git 仓库添加新市场时检查；在托管设置文件、OS 级策略或其他托管来源里，Claude Code 在读取那个来源的地方强制，claude.ai 不读它。设置了任何允许列表，或阻止列表点名了 skills-dir 之外的任何来源时，Claude Code 找不到其市场的插件不会加载，/plugin 显示策略错误而不是找不到的错误（常见情形是对已不存在市场的陈旧 enabledPlugins 条目）。

控制矩阵

表中除 enabledPlugins、syncClaudeAiPlugins 和 CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL 外都是托管设置：enabledPlugins 可在任何范围设置，托管设置会锁定它；syncClaudeAiPlugins 每个用户也可在自己的用户或本地设置里设置；最后一个是通过托管 env 块下发的环境变量。strictKnownMarketplaces 也可拼写为 allowedMarketplaces，extraKnownMarketplaces 也可拼写为 additionalMarketplaces（别名需要 Claude Code v2.1.232 或更高版本，旧客户端会忽略；混合机群读取的文件里请保留规范名；两种拼写都设置时规范键的值生效）。

用 strictKnownMarketplaces 的允许列表

把允许列表设为这些来源对象的列表（多数条目精确匹配，hostPattern 和 pathPattern 条目按正则匹配，github owner 通配符按 owner 匹配）：

• github：{ "source": "github", "repo": "your-org/approved-plugins" }，可带 ref 和 path
• github owner 通配符：{ "source": "github", "repo": "your-org/*" } 匹配该 owner 下的每个仓库；* 必须代表整个仓库名，*/plugins 和 your-org/tools-* 这样的条目被视为无效而不匹配任何东西
• 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" }
• hostPattern：{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }，对 github、git 和 url 来源的主机匹配；模式匹配主机名中的任何位置，所以像示例那样用 ^ 和 $ 锚定来匹配整个主机
• pathPattern：{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }，对 file 和 directory 来源的 path 匹配；以 ^ 开头来固定目录前缀，".*" 允许每个本地路径
• skills-dir：{ "source": "skills-dir" } 在设置了允许列表时让 skills 目录插件继续加载，并且不匹配任何市场

条目如何匹配：url 条目按其 url 值匹配，不比较 headers；对 github 和 git 条目，repo 或 url、ref 和 path 必须全部匹配，或双方都没有：没有 ref 的条目不覆盖带 ref: "main" 的来源；your-org/your-marketplace 条目不覆盖克隆同一仓库的 git URL；末尾斜杠、.git 后缀或用 ssh:// 代替 https:// 都是不同的值。同一个市场可以用多个 URL 克隆时，优先用 hostPattern 条目。通配符匹配在允许列表上区分大小写。

保持 skills 目录插件加载：设置了任何不含 { "source": "skills-dir" } 条目的允许列表，用户放在 ~/.claude/skills/ 或项目 .claude/skills/ 里带 .claude-plugin/plugin.json 的 skills 目录插件就会停止加载（普通 skills 不受影响）。claude.ai 托管的市场：允许和阻止列表按主机匹配 claude.ai 托管的市场，要允许或阻止，往 strictKnownMarketplaces 或 blockedMarketplaces 里加匹配 claude.ai 的 hostPattern 条目。全部锁死：空允许列表 [] 锁定每个市场来源，包括官方市场；这个锁定不涵盖从 claude.ai 同步的插件（要同时停止它们，在托管设置里把 syncClaudeAiPlugins 设为 false，或为你的组织关闭 Skills）。

用 blockedMarketplaces 的阻止列表

blockedMarketplaces 接受与 strictKnownMarketplaces 相同的来源对象且先检查，所以同时在两个列表里的来源被阻止。阻止列表匹配比允许列表宽：git URL 会被规范化，同一个 github.com 仓库的 git@ 和 https:// 形式、.git 后缀和末尾斜杠都匹配同一条目；github 条目也阻止等价的 git URL，反之亦然；owner/* 条目的 owner 比较不区分大小写；没有 ref 或 path 的条目阻止它匹配的仓库的每个 ref 和 path。这个条目阻止某个 GitHub owner 下的每个仓库：

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

这里的 { "source": "skills-dir" } 条目会让 skills 目录插件停止加载（用户和项目两个位置都是）；只点名这一个条目的阻止列表不算生效的限制，所以不会阻止找不到其市场的插件加载。

允许官方市场和你自己的

多数组织允许官方市场和自己的，并同时注册两者让每台机器都有。这个托管设置策略允许两个市场、注册两者、强制启用两个插件并拒绝 --plugin-dir：

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

在有这个策略的机器上，添加列表之外的任何来源（如 /plugin marketplace add https://example.com/other-marketplace.git）会失败，消息含 is blocked by enterprise policy 并列出允许的来源。要像这个策略那样用显式的 extraKnownMarketplaces 条目注册两个市场，而不要依赖允许列表或官方市场自行注册：允许列表不注册任何东西，extraKnownMarketplaces 条目才注册，且它自己必须通过允许列表（Claude Code 拒绝注册来源不匹配允许列表的托管市场）；官方市场只在交互终端会话里自行注册，且只在允许列表允许时（-p 运行或连到云端会话的终端从不注册它）；被阻止的尝试会被记住：如果一台机器曾运行在阻止官方市场的策略下（[] 锁定就是一例），Claude Code 记录这次被阻止的尝试，策略改变后不再重试。

设置更新策略

可以按市场、对整个机群、或通过发布渠道按用户组设置更新策略。

• 按市场开关自动更新：在托管的 extraKnownMarketplaces 条目上设置 "autoUpdate": true 或 false；托管条目设置了该字段，Claude Code 会拒绝用户的 /plugin 开关并报以 Auto-update for '<name>' is set by 开头的错误；托管条目没设该字段，用户的开关保持有效
• 整个机群关闭更新：在托管 env 块里设置 DISABLE_AUTOUPDATER（同一变量也会停止 Claude Code 自己的更新）：{ "env": { "DISABLE_AUTOUPDATER": "1" } }；要停止 Claude Code 自己的更新但保留插件自动更新，在同一块里加 "FORCE_AUTOUPDATE_PLUGINS": "1"。DISABLE_AUTOUPDATER 不涵盖 command 来源插件：Claude Code 每个会话都重新运行每个已启用插件的命令，输出变化时安装
• 给用户组分配发布渠道：要运行稳定和早期访问渠道，托管两个指向同一批插件不同 ref 的市场，然后通过各自独立的端点托管设置或网关策略给每个用户组自己的市场；管理控制台的服务端托管设置对每个组织只下发一个配置，所以不适用。方式：为每个组的设备部署单独的端点托管设置（如托管设置文件或 MDM 配置描述文件）；或为每个组定义一个 Claude apps gateway 策略（网关应用第一个匹配规则适合某用户的策略，所以要排序使每个用户到达自己组的策略，且该策略的 extraKnownMarketplaces 映射不与其他策略合并）。稳定组收到 stable-tools 市场，早期访问组收到 latest-tools 市场

推荐插件

市场所有者可以给条目附加 relevance 信号，让 Claude Code 在项目匹配时建议该插件。来自某个市场的建议只在以下条件都满足时出现：它已在用户机器上注册、你在托管设置的 pluginSuggestionMarketplaces 里列出它的名字、并在同一策略里声明了它的来源（可以是该市场的 extraKnownMarketplaces 条目，或其他方式）。

审计与审阅

OpenTelemetry 事件和 Analytics API 告诉你机群安装和运行了什么。在批准某个市场之前，先读「插件安全」了解插件能在机器上运行什么以及每个信任层级允许什么。

• OpenTelemetry 事件：claude_code.plugin_installed 记录每次安装，claude_code.plugin_loaded 记录会话开始时每个已启用的插件；两个事件都会对第三方插件和市场名称做脱敏或省略，除非设置 OTEL_LOG_TOOL_DETAILS=1
• Analytics API：在 Enterprise 套餐上，GET /v1/organizations/analytics/plugins 返回跨 Claude Code 和 Cowork 的每插件每天的安装和调用次数，可按用户或 RBAC 组分组

托管设置无法强制的事

这些来自安全评审的要求在当前设置 schema 里没有专用的键，最接近的现有控制是：

• 按用户或按组定向：每个插件键都适用于收到设置的每个用户；服务端托管设置对每个组织下发一个配置。按组策略要用单独的端点托管设置或网关策略
• 限制允许市场内部的条目：允许列表匹配的是市场来源。要阻止允许市场里的某个插件，在托管 enabledPlugins 里把它设为 false
• 隐藏 /plugin：没有键可以禁用该命令；最接近的等价做法是结合只点名你自己市场的允许列表、你提供的插件的托管 enabledPlugins 条目和 disableSideloadFlags
• 通过允许列表限制 --plugin-dir：允许列表不涵盖 --plugin-dir，disableSideloadFlags 才涵盖
• 通过这些键强制 claude.ai 的插件开关：Organization settings > Plugins & skills 不设置本页的键，成员和组织在那里打开的内容以同步插件的形式到达 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 并指出原因