为您的组织管理 mods

• 排除用户自己的 mods，有或没有您自己的 mods：停止用户安装的 mods 加载
• 查看当您不做任何更改时用户会获得什么：了解默认情况下会发生什么
• 保持 mods 开启并设置其他限制：选择允许的程度

​

停止用户安装的 mods 加载

{
  "pluginConfigs": {
    "cc-plugin-sec-default@builtin": {
      "options": {
        "allowManagedModsOnly": true
      }
    }
  }
}

• 用户带来的任何 mod 都不会加载：这包括用户安装的插件中的 mod、使用 --plugin-dir 加载的 mod 以及Claude 在会话期间编写的 mod
• 您组织的 mods 仍然加载：计为您组织的 mod 不会被检查。所有其他 mod 都计为用户的 mod，不会加载。这包括您从 GitHub 或其他远程市场启用的插件中的 mod，以及您的组织为其成员在 claude.ai 上启用的 mod。如果没有计为您的 mod，则不会加载任何已安装的 mod。
• 用户无法撤销它：保护程序仅从托管设置读取选项，因此用户、项目或本地设置文件中的相同条目，或使用 --settings 传递的文件中的条目不会改变任何内容
• 文件或 MDM 策略涵盖每个提供商：当您以文件形式或通过 MDM 提供选项时，它在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的工作方式相同。对于从 claude.ai 管理控制台的交付，请参阅平台可用性
• 用户的其他自定义保持工作：他们设置文件中的 hooks、状态行和 /goal 不受影响
• 内置 mods 继续运行：内置于 Claude Code 的 mods，例如 AGENTS.md 支持，各有自己的开关

​

了解默认情况下会发生什么

• Mods 处于开启状态。 用户可以安装包含来自您的插件设置允许的任何市场的 mod 的插件，或使用 --plugin-dir 从目录加载一个。
• 内置保护程序首先运行。 Claude Code 在用户安装的每个 mod 之前加载一个名为 sec-default@builtin 的内置 mod。用户无法将其关闭。/plugin 和调试日志将其列为 cc-plugin-sec-default。保护程序在以下任一情况为真时加载：
  • 机器有托管设置
  • 用户使用 Team 或 Enterprise 计划登录到 Claude Code
  使用 API 密钥进行身份验证的用户，或通过 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry，仅在具有托管设置的机器上获得保护程序。
• 保护程序保护您管理的内容。 用户的 mod 无法更改您的托管 hooks 接收或决定的内容、系统提示、您的托管 CLAUDE.md 和其他托管说明、任何 mod 读取的设置内容，或您的托管 MCP 服务器的工具和描述。
• 允许所有其他内容。 保护程序不添加其他限制。用户的 mod 仍然可以读写文件、启动进程、发出网络请求、重写工具调用和提示、拒绝工具调用、批准否则会提示的工具调用，以及在界面中绘制，所有这些都具有该用户的权限。
• 拒绝规则和您的托管 hooks 优先。 保护程序加载的地方，用户的 mod 无法批准 deny 规则拒绝的调用，无论哪个设置文件持有该规则。来自托管设置中 PreToolUse hook 的块也是最终的。两者都适用于 Claude 的工具调用。两者都不适用于 mod 自己的 $.fs 和 $.process 调用：即使 Read(.env) 被拒绝，mod 仍然可以使用 $.fs.read 读取该文件或启动执行此操作的程序。要限制这些调用，请防止 mod 加载或在策略 mod 中挂接调用。
• 其他权限检查可以被覆盖。 批准工具调用的用户 mod 可以批准 ask 规则会提示的调用，或 PreToolUse hook 在托管设置外阻止的调用。在自动模式下，mod 批准的调用运行时不进行分类器检查。

​

了解哪些控制仍然适用

• 设置 hooks 继续工作。 设置文件和插件的 hooks/hooks.json 中的命令、HTTP、提示和代理 hooks 照常运行，与 mods 一起。关于它们的任何内容都没有被弃用。
• 拒绝规则在保护程序加载的地方优先。 用户的 mod 无法批准 deny 规则拒绝的调用，除非您设置 allowModsToOverrideDenyRules。
• 托管 hooks 首先运行。 托管设置中的 PreToolUse hook 在任何 mod 看到工具调用之前运行，其块是最终的。如果 mod 随后重写调用，您的托管 hooks 在重写的调用上再次运行，因此块仍然适用。来自其他设置文件和插件的 PreToolUse hooks 在最后一个 mod 之后运行，因此返回自己结果代替运行工具的 mod 会阻止这些运行。请参阅mods 运行的顺序。
• 网络策略涵盖 $.http.fetch。 如果您的组织关闭了网络获取，或为会话关闭了非必要的网络流量，Claude Code 会拒绝 mod 使用 $.http.fetch 发出的网络请求。该策略不涵盖 mod 使用 $.process.run 启动的程序。该程序使用用户自己的访问权限到达网络。
• 插件控制涵盖 mods。 Mod 是一个插件，因此限制用户可以安装的内容的设置，例如 strictKnownMarketplaces，决定它是否可以被安装。
• Mods 无法更改权限提示。 Mod 可以重新设置 Claude Code 界面的大部分样式，但不能更改权限提示，因此它无法更改提示显示的内容。Mod 仍然可以在提示出现之前批准或拒绝工具调用，如了解默认情况下会发生什么所述。
• 信任提示首先出现。 在用户尚未信任的目录中的交互式会话中，在他们回答信任提示之前，没有 mod 加载。
• --safe-mode 关闭已安装的 mods，包括您的。 使用 claude --safe-mode 启动会话以检查 mod 是否导致了问题。

​

决定是否保持 mods 开启

​

查看 mod 可以执行的操作

claude plugin validate ./some-mod

  ❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane}
  ❯ ./register.js calls: $.fs.read, $.http.fetch, $.store.set, $.ui.open

​

选择允许的程度

• allowManagedModsOnly：内置保护程序上的选项。用户自己的 mods 不加载，他们的设置 hooks、状态行和 /goal 继续工作。停止用户安装的 mods 加载列出了它涵盖的内容。
• allowManagedHooksOnly：更广泛的设置。仅您组织的 mods 和内置于 Claude Code 的 mods 加载。用户自己安装的 mod 不加载。该设置还阻止用户自己的设置文件中的 hooks。在设置之前，请阅读allowManagedHooksOnly 下运行什么。
• disableAllHooks：最广泛的设置。在托管设置中，它停止每个已安装插件中的 mods，包括您的，并关闭设置文件中的每个 hook，因此您的托管设置中的 PreToolUse hook 不再阻止任何内容。自定义状态行和 /goal 也停止工作。在设置之前，请阅读disableAllHooks。
• disableSideloadFlags：在启动时拒绝 --plugin-dir 和 --plugin-url，因此没有人从目录加载 mod，并防止 Claude 在会话期间编写的 mods 加载。该设置还拒绝 --agents 和 --mcp-config。在设置之前，请阅读disableSideloadFlags。

​

在内置保护程序上设置选项

• id 在这里有一个拼写：Claude Code 仅在 cc-plugin-sec-default@builtin 下读取选项。prependPlugins 也接受 sec-default@builtin，而 pluginConfigs 不接受。
• 仅托管设置计数：用户、项目或本地设置文件中的相同条目，或使用 --settings 传递的文件中的相同条目既不设置选项也不放松选项
• 保护程序必须加载：如果您设置 prependPlugins，在列表中命名保护程序。保护程序不加载的地方，两个选项都不适用。
• 保护程序失败关闭：如果保护程序无法读取托管设置，它会拒绝每个用户的 mod 加载。如果它无法检查用户的 mod 批准的调用的拒绝规则，它会拒绝该调用。

​

运行您组织自己的 mods

​

安装您组织的 mods 并设置顺序

• 托管的 enabledPlugins 将 mod 的插件设置为 true
• 托管设置通过绝对路径将插件的 marketplace 命名为用户机器上的目录。extraKnownMarketplaces 条目可以做到这一点，并且也为用户注册 marketplace。
• marketplace 通过相对路径列出插件，因此 Claude Code 从该目录就地加载它

/opt/acme/claude-plugins/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── acme-guard/
        ├── .claude-plugin/
        │   └── plugin.json
        └── hooks/
            ├── hooks.json
            └── register.js

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "acme-guard", "source": "./plugins/acme-guard", "description": "Acme policy mod" }
  ]
}

• prependPlugins：您的 mod 在任何用户 mod 之前看到每个事件，在之后看到每个结果。它可以更改事件、拒绝事件或跳过用户 mods。
• appendPlugins：您的 mod 在每个用户 mod 之后运行，因此它只看到这些 mods 传递的事件，以及它们传递的形式

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }
    }
  },
  "enabledPlugins": { "acme-guard@acme-tools": true },
  "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"]
}

• extraKnownMarketplaces：命名保存 acme-tools marketplace 的目录。path 是包含 .claude-plugin/marketplace.json 的目录的绝对路径。
• enabledPlugins：为接收这些托管设置的每个用户打开 acme-guard
• prependPlugins：将 acme-guard 放在第一位，内置保护放在第二位，都在用户安装的任何 mod 之前。Claude Code 遵循您列出的顺序。

• hooks module acme-guard@acme-tools loaded，带有 tier prepend：mod 计为您组织的，并首先运行
• 同一行带有 tier user：Claude Code 将其视为用户的 mod。第二行 prependPlugins names acme-guard@acme-tools, which is not an enabled managed plugin with a hooks module; skipped 表示列表跳过了它。

• 列表替换默认值：当您在托管设置中设置 prependPlugins 时，在其中命名 sec-default@builtin 以保留内置保护。保护是内置的，不需要 enabledPlugins 条目。
• 您自己的 id 必须计为您的：在托管设置中，Claude Code 跳过其插件不满足组织 mod 三个条件的 id
• 存储库无法设置它们：Claude Code 从托管设置读取两个设置，从不从存储库的设置文件读取。用户可以在 ~/.claude/settings.json 中设置它们以仅在没有托管设置的机器上对其自己的 mods 进行排序，并且仅当他们未使用 Team 或 Enterprise 计划登录时。在其他任何地方，Claude Code 忽略用户设置中的两个密钥。那里的列表既不添加也不删除内置保护。

​

使用您自己的 mod 强制执行策略

// 用户 mod 不得调用的方法，每个拼写为 namespace.method
const BLOCKED_CALLS = ['process.run', 'process.spawn']

export function register(on) {
  // 每次另一个 mod 即将加载时运行
  on('plugin.register', async ($, e, next) => {
    // 保留该 mod 代码中在阻止列表上的调用
    const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))
    if (e.tier === 'user' && blocked.length > 0) {
      // 返回 refuse 阻止 mod 加载，文本是原因
      return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }
    }
    // 让每个其他 mod 加载
    return next(e)
  })

  // 记录每个工具调用，然后让它继续不变
  on('tool.call', async ($, e, next) => {
    $.ui.log('audit tool.call ' + e.tool, { to: 'debug' })
    return next(e)
  })

  // 记录哪个 mod 写了文件，然后是路径，引用因为 mod 选择了它
  on('fs.write', async ($, e, next) => {
    $.ui.log('audit fs.write by ' + next.origin.plugin + ' ' + JSON.stringify(e.path), { to: 'debug' })
    return next(e)
  })
}

• plugin.register：决定另一个 mod 是否加载。它拒绝调用阻止方法的用户 mod，并传递每个其他 mod。
• tool.call：为每个工具调用向调试日志写入一行，例如 audit tool.call Bash，并且不改变任何内容
• fs.write：为每个 $.fs.write 调用另一个 mod 进行的写入一行，例如 audit fs.write by reader "/tmp/notes.md"，并且不改变任何内容。mod 的名称首先出现，路径被引用，因此 mod 选择的路径无法冒充该行的另一个字段。

• e.tier：mod 将运行的位置，prepend、user、append 或 builtin 之一。每个人安装的每个 mod 都是 user。
• e.uses.calls：mod 调用的 mods API 方法，每个拼写为 namespace.method，例如 process.run，不带 claude plugin validate 打印的 $.

​

当您的检查失败时拒绝 mods

const BLOCKED_CALLS = ['process.run', 'process.spawn']

// 与之前相同的检查，移到其自己的函数中
async function checkMod($, e, next) {
  const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))
  if (e.tier === 'user' && blocked.length > 0) {
    return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }
  }
  return next(e)
}

export function register(on) {
  // 处理程序仅在 checkMod 抛出或超过其时间限制时运行
  on('plugin.register', checkMod).catch(async ($, e, next) => {
    // 让您组织的 mods 和内置 mods 加载
    if (e.tier !== 'user') return next(e)
    // 拒绝无法检查的用户 mod
    return { refuse: 'Acme policy check failed, so this mod was not loaded' }
  })
}

​

后续步骤

• 插件安全：任何插件可以在用户机器上执行的操作，以及如何在安装前查看一个
• Mods 概述：什么是 mod 以及它与 hooks、skills 和 MCP 服务器的比较
• mods 运行的顺序：prependPlugins 和 appendPlugins 如何与用户的 mods 配合
• 设置和环境变量：本页命名的每个设置在一个表中