部署托管设置

​

部署托管设置文件

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true
}

​

选择交付机制

• 交付控制：policyHelper、wslInheritsWindowsSettings 和 managedSourcesBehavior
• 网关登录密钥：forceLoginGatewayUrl、gatewayInternalNetworks 和 forceLoginMethod 的 "gateway" 值

​

策略应用的位置和时间

• 表面：在开发者的机器上，终端、VS Code 和 JetBrains 扩展、桌面应用的 Code 选项卡和Agent SDK会话读取所有这些源。Agent SDK 会话即使在 settingSources 排除用户、项目和本地文件时也加载托管设置。
• 云会话：Anthropic 托管环境中的会话不读取设备的 MDM 配置文件或文件，因此其策略必须来自服务器托管设置。自托管环境中的会话也读取其运行器镜像中的托管设置文件，默认情况下仅当服务器托管设置不交付策略密钥时，除了Claude Code 从每个管理源读取的密钥。Claude Code 如何组合托管源涵盖了适用于两者的选择加入。
• Claude Tag 会话：Claude Tag会话在云环境中运行，但不接收服务器托管设置。在自托管环境中，它们仍然读取运行器镜像中的托管设置文件。在Claude Tag 管理员设置中配置 Claude Tag 本身。
• 协作会话：Claude Desktop 应用中的协作在 Claude Code 上运行其会话。在协作会话中，Claude Code 永远不会从 claude.ai 管理控制台获取服务器托管设置，即使用户使用 Team 或 Enterprise 帐户登录，因此应用的策略取决于会话运行的位置：
  • 在用户的机器上：默认情况下，协作会话中的 Claude Code 读取该设备上的 MDM 或操作系统级策略和托管设置文件，因此在那里部署策略。
  • 在完整 VM 沙箱中：当您的 Claude Desktop 托管配置设置 requireCoworkFullVmSandbox 时，Claude Code 在虚拟机内运行，其中设备的 MDM 策略和托管设置文件不存在。
  • 远程协作会话：这些在 Anthropic 托管的虚拟机上运行，其中 Claude Code 没有设备策略可读。
  无论会话在何处运行，claude.ai 在任何人从 claude.ai 上的 git 存储库或从协作选项卡中的自定义添加市场时，都会自行应用管理控制台的 strictKnownMarketplaces 和 blockedMarketplaces 列表。限制如何工作描述了该检查。表面覆盖表比较了协作与其他表面。
• 运行会话：大多数更改在交付机制表中的计划上到达运行会话，无需重启。
  • 对 forceRemoteSettingsRefresh、requiredMinimumVersion 和某些用户可编辑密钥的更改在下一个会话启动时生效。
  • 新的或更改的 policyHelper 条目在下一次启动时生效。如果服务器托管设置在该启动时遮蔽了助手，助手会在获取报告这些设置被删除时立即运行。
• 需要批准的更改：除了等待下一次启动的更新，对需要批准的设置（如钩子或 env 变量）的服务器托管更改等待开发者在交互式会话中接受对话，并在 IDE 扩展或 Agent SDK 托管的会话中应用当前运行。其他服务器托管更改在下一次轮询时应用。
• 长期会话：保持打开数周的会话仍然可能滞后于推出。requiredMinimumVersion阻止过时的二进制文件启动，不会结束已经运行的会话。

​

每个机制存储策略的位置

• 服务器托管：Anthropic 的服务器或您的网关持有策略。Claude Code 保留一个本地缓存，在启动时应用它，并在每次成功获取时替换。
• macOS 配置文件：com.anthropic.claudecode 托管首选项域。使用与 managed-settings.json 相同的顶级密钥，嵌套设置为字典，列表为 plist 数组。
• Windows HKLM 注册表：JSON 作为 HKLM\SOFTWARE\Policies\ClaudeCode 下名为 Settings 的 REG_SZ 或 REG_EXPAND_SZ 值。
• 基于文件：managed-settings.json、可选的 managed-settings.d/ 目录和 managed-mcp.json 在系统目录中：macOS 上的 /Library/Application Support/ClaudeCode/、Linux 和 WSL 上的 /etc/claude-code/，以及 Windows 上的 C:\Program Files\ClaudeCode\。Claude Code 不读取旧版 Windows 路径 C:\ProgramData\ClaudeCode\managed-settings.json。
• Windows HKCU 注册表：HKCU\SOFTWARE\Policies\ClaudeCode 下的相同 Settings 值。

​

跨团队拆分基于文件的策略

• 单个值，例如 "model": "opus" 或 "cleanupPeriodDays": 7：后面文件的值替换前面的值
• 列表，例如 permissions.deny 或 sandbox.network.allowedDomains：两个列表组合，删除重复项
• 嵌套块，例如 env 或 sandbox：两个块逐个密钥合并，每个密钥内遵循这些相同的规则
• fallbackModel：后面的链整体替换前面的链
• extraKnownMarketplaces 和 managedMcpServers：具有相同名称的后面条目整体替换前面的条目
• modelPicker：后面的阵容整体替换前面的阵容

​

Claude Code 如何组合托管源

• "first-wins"，默认值：Claude Code 使用提供至少一个策略键的最高排名源，并忽略其余源，而不是合并它们，除了 从每个管理员源读取的键 中的键。Claude Code 不会对跳过的源显示警告；/status 命名它使用的源和跳过的源。
• "merge"：Claude Code 应用每个提供策略键的管理员源，并按键的类型组合它们：在大多数键上，较高排名源的值适用，列表合并，锁采用最严格的值。组合每个托管源 说明在哪里设置键以及每种键的组合方式。需要 Claude Code v2.1.242 或更高版本。

• 策略键：除了两个控制键 wslInheritsWindowsSettings 和 managedSourcesBehavior 之外的任何设置键。仅包含这些键的托管设置文件或 MDM 策略不计数，Claude Code 会移至下一个源。
• 管理员源：下面前三个源之一。HKCU 注册表是用户可写的，不是管理员源。

1. 远程设置，从 claude.ai 作为 服务器管理的设置 或通过 Claude 应用网关 交付。Claude Code 仅在会话使用 符合条件的登录或密钥 直接向 Anthropic 的 API 进行身份验证，或使用 /login 登录网关时才获取此源。在其他提供商上，或当 ANTHROPIC_BASE_URL 指向 Anthropic 的 API 以外的地方时，它从下一个源开始
2. MDM 或操作系统级策略：macOS plist 或 HKLM 注册表键
3. 托管设置文件，managed-settings.d/*.json 和 managed-settings.json 合并在一起
4. HKCU 注册表，在 Windows 上，以及在 WSL 上一旦 HKLM 注册表或 Windows 托管设置文件打开 wslInheritsWindowsSettings 并且 HKCU 值也设置它时。Claude Code 仅在 其上方没有存在的管理员文档 且没有 主机提供的父设置 提供限制性键时才读取它

​

管理员文档何时算作存在

• 它将任何策略键设置为非 null 值，即使是 Claude Code 无法读取的值
• 它是存在但无法读取的 HKLM 值、托管设置文件或 managed-settings.d 目录

​

从每个管理员源读取的键

• sandbox.network.allowManagedDomainsOnly 和 sandbox.filesystem.allowManagedReadPathsOnly：任何管理员源中的 true 都会打开锁。当锁打开时，Claude Code 会合并它锁定的允许列表，sandbox.network.allowedDomains 与 WebFetch(domain:...) 允许规则，或 sandbox.filesystem.allowRead，跨每个管理员源。没有锁时，Claude Code 将允许列表视为任何其他键，因此在 "first-wins" 下，未选定的管理员源的允许列表被忽略
• allowAllClaudeAiMcps
• allowManagedMcpServersOnly：任何管理员源中的 true 都会打开 MCP 允许列表锁。当锁打开时，托管的 allowedMcpServers 列表来自设置一个的最高排名管理员源。服务器管理的列表替换较低源的列表，而不是与其组合。 如果没有管理员源设置列表，每个通过拒绝列表的服务器都会加载，除非 父设置 提供列表。 没有锁时，Claude Code 从它应用的托管源读取 allowedMcpServers，因此在 "first-wins" 下，未选定的管理员源的列表被忽略。需要 Claude Code v2.1.273 或更高版本
• deniedMcpServers 和 disableClaudeAiConnectors：任何管理员源中的条目或 true 都会应用。需要 Claude Code v2.1.273 或更高版本
• 沙箱二进制路径 sandbox.bwrapPath 和 sandbox.socatPath
• 沙箱 ripgrep 二进制文件，sandbox.ripgrep
• sandbox.filesystem.disabled 和 sandbox.network.strictAllowlist
• useAutoModeDuringPlan、syncClaudeAiSkills 和 syncClaudeAiPlugins，其中任何管理员源的 false 都会关闭该行为。开发人员的用户或本地设置中的 false 也会关闭它；每个键只能拒绝
• enableArtifact，其中任何管理员源的 false 都会关闭 Artifact 工具。开发人员的用户、项目或本地设置中的 false 也会关闭它，没有源会将其打开；请参阅 哪些较低级别的值仍然计数。需要 Claude Code v2.1.242 或更高版本
• maxEffortLevel，其中任何管理员源中的最低上限适用。如果开发人员在自己的设置或使用 --settings 中设置了较低的上限，Claude Code 会应用该上限；没有源可以提高上限。需要 Claude Code v2.1.267 或更高版本
• attribution 中的提交预告片选择退出，或在已弃用的 includeCoAuthoredBy 中，来自任何层级
• forceRemoteSettingsRefresh
• env，跨管理员源按变量合并：每个变量来自定义它的最高优先级源，因此较低源填充较高源未设置的变量。少数变量遵循自己的规则；跨托管源的每个键异常 命名每一个。需要 Claude Code v2.1.223 或更高版本。在 v2.1.223 之前，Claude Code 仅应用选定源的整个 env 块

​

组合每个托管源

​

使用辅助程序计算策略

• 发出的 managedSettings 对象是会话的唯一托管设置，包括对于 它否则从每个管理员源读取的键，除了 forceRemoteSettingsRefresh，它有自己的启动规则

​

让嵌入主机添加策略

• 当任何管理员源设置 allowManagedPermissionRulesOnly 时，Claude Code 会删除 父提供的 权限允许规则和 additionalDirectories，即使较高优先级源未设置该键。该键对您自己的权限规则的影响来自 Claude Code 应用的托管设置，或来自您选择合并的父设置
• Claude Code 强制执行它应用的托管设置中的 forceLoginOrgUUID 或 allowedMcpServers 值，并阻止父提供的值。在 MCP 允许列表锁之外，Claude Code 不应用的较低管理员源中的值既不应用也不阻止父的值。 在 Claude Code v2.1.273 或更高版本上，当 allowManagedMcpServersOnly 打开时，来自设置一个的最高排名管理员源的 allowedMcpServers 列表应用并阻止父的，作为 跨源键。父的列表仅在没有管理员源设置一个时应用。managedSourcesBehavior 条目说明在 "merge" 下哪个源提供每个键。在 v2.1.223 之前，任何管理员源中的值都会阻止父的值
• 对于 availableModels，Claude Code 强制执行它应用的托管设置中的值并阻止父提供的列表
• 对于 strictKnownMarketplaces，Claude Code 同样强制执行它应用的托管设置中的列表并阻止父提供的列表。父的列表仅在没有应用的托管源设置一个时应用。需要 Claude Code v2.1.282 或更高版本
• 对于 allowedProviders，选定的托管源 中的列表会阻止父提供的列表；在选择启用 managedSourcesBehavior "merge" 时，任何管理员源中的列表都会阻止父提供的列表。需要 Claude Code v2.1.285 或更高版本
• 父提供的 blockedMarketplaces 除了托管源设置的任何阻止列表外还适用。需要 Claude Code v2.1.282 或更高版本

​

当仅应用托管规则时保持 Cowork 文件夹访问

{
  "allowManagedPermissionRulesOnly": true,
  "permissions": {
    "allow": [
      "Edit(~/CoworkProjects/**)"
    ]
  }
}

​

开发人员可以更改什么

• 会话的模型：托管的 model 是默认值，不是锁。--model 和 ANTHROPIC_MODEL 仍然为该会话选择模型，因此部署 availableModels 来限制选择。
• 会话的自动压缩窗口：托管的 autoCompactWindow 也是默认值。--autocompact 标志和 CLAUDE_CODE_AUTO_COMPACT_WINDOW 变量仍然为该会话设置 自动压缩窗口。
• 本地管理员权限：作为机器上的管理员的开发人员可以编辑托管源本身，这就是为什么 MDM 工具可以按计划重新部署配置文件或文件，以及为什么 HKLM 注册表和 macOS 托管首选项域存在。
• 服务器管理的缓存：服务器管理的设置来自 Anthropic 的服务器，对本地缓存的编辑 仅持续到下一次成功获取。
• 其他工具：托管设置仅绑定 Claude Code。从另一个工具调用 API 的开发人员不在它们下。

​

检查策略是否生效

​

在 /status 中读取源

• (remote)：来自 claude.ai 或网关的服务器管理的设置
• (plist) 或 (HKLM)：MDM 或操作系统策略
• (file)、(drop-ins) 或 (file + drop-ins)：managed-settings.json、drop-in 目录或两者
• (remote + file, merged) 或其他以 , merged 结尾的列表：您的组织组合每个托管源，Claude Code 将列出的源合并到策略中。较低的源仍然可以提供 env 变量而不出现在列表中。需要 Claude Code v2.1.242 或更高版本
• (HKCU)：用户可写的注册表回退
• (parent process)：嵌入主机提供的限制性设置
• (helper)：由选定的 MDM 或文件源配置的 policyHelper

• 该行缺失：Claude Code 未找到传递策略密钥的托管源。 如果您部署了托管设置文件，请检查它是否位于操作系统的路径中，以及它是否包含策略密钥而不仅仅是控制密钥。不是有效 JSON 的文件不会产生这种状态；Claude Code 拒绝启动。 当您改为通过服务器管理的设置部署时，运行 claude doctor，它报告获取结果。
• 该行命名的源不是您部署的源：存在更高优先级的源，Claude Code 忽略了您的源，Skipped sources 列出了它。Claude Code 如何组合托管源给出了顺序。

​

查找 Claude Code 丢弃的条目

• 托管设置文件或 drop-in 文件：文件不是有效的 JSON，或其顶级不是对象
• MDM plist：macOS 的 plutil 报告 plist 格式错误，或其转换的内容不是 JSON 对象
• HKLM 注册表值：Settings 值不是字符串、为空或不包含 JSON 对象

• 缺少的文件、配置文件或注册表值不是失败；Claude Code 在没有该源的情况下运行。
• 空的托管设置文件计为 {}。
• 用户可写的 HKCU 注册表密钥中的格式错误的值永远不会阻止启动。Claude Code 在 /status 和 claude doctor 中将其报告为通知。

• 如果操作系统拒绝了读取，例如在仅限 root 的文件上，每个会话都会在没有该源的策略的情况下启动。/status 和 claude doctor 记录失败，使用 -p 运行也会将其打印到 stderr。
• 对于任何其他读取失败，例如 I/O 错误，每个会话在启动时以联系管理员的消息退出。

• 交互式会话在启动时显示一个对话框，列出无效条目。
• 使用 -p 的非交互式运行将摘要打印到 stderr。
• claude doctor 列出每个无效条目及其源和字段。

​

失败关闭的密钥

• null 删除该密钥。
• 无效的 disableAllHooks，即使是带引号的布尔值，也会被丢弃并带有警告，因为强制执行 true 也会卸载您自己的托管设置部署的 hook。
• 对于规则涵盖的每个其他布尔密钥，字符串 "true" 或 "false" 读取为该布尔值，在 /status 中带有通知，要求您删除引号。

• 其中的锁（例如 permissions.disableBypassPermissionsMode）读取为其限制性值。
• 无效的 permissions.defaultMode 读取为 default。
• 当 permissions 中的 deny 或 ask 列表根本无法读取时，Claude Code 扣留 allow 和 additionalDirectories，因此授予永远不会应用而没有写在旁边的限制。报告命名每个扣留的授予和无法读取的列表。
• 在 autoMode 中，无法读取的 soft_deny 或 hard_deny 列表，或丢失无效条目的列表，以相同方式扣留 allow 和 environment。

​

sandbox 内的无效值

• 如果您将布尔密钥设置为带引号的 "true" 或 "false"，该值计为该布尔值。而不是警告，/status 显示一个通知，要求您删除引号。
• 如果 failIfUnavailable 无效，Claude Code 会丢弃该值而不是将其视为 true，因此无法读取的值永远不会停止整个设备群中的会话启动。
• Claude Code 将每个其他无效布尔值视为保持沙箱最严格的值，直到您修复它。打开沙箱或其限制之一的密钥（例如 enabled 或 network.allowManagedDomainsOnly）计为 true。放松它的密钥（例如 allowUnsandboxedCommands）计为 false。
• 在 credentials 外的列表中，例如 excludedCommands 或 network.allowedDomains，Claude Code 会丢弃无效条目并保留列表的其余部分。不是数组的列表或没有有效条目的列表根本不适用。
• 当 network.deniedDomains 或其中任何条目无效时，Claude Code 也会扣留 network.allowedDomains，因此托管允许列表在您修复拒绝列表之前不会授予任何内容。
• 当 filesystem.denyRead、filesystem.denyWrite 或其中任何条目无效时，Claude Code 也会扣留 filesystem.allowRead 和 filesystem.allowWrite，直到您修复拒绝列表。

​

仅托管源可以设置的密钥

​

为您的组织关闭遥测

{
  "env": {
    "DISABLE_TELEMETRY": "1"
  }
}

​

另请参阅

• 为您的组织设置 Claude Code：决定要强制执行什么以及如何强制执行
• 服务器托管设置：从 claude.ai 控制台或网关交付策略
• 托管 MCP 配置：控制开发者可以使用哪些 MCP 服务器
• 所有设置：每个密钥，以及托管源是否可以设置它
• 示例设置文件：显示托管密钥形状的完整 managed-settings.json