05-MDM 企业部署配置

MDM 企业部署配置

学习目标

本章将掌握 Claude Code 的企业部署配置规范，通过官方 MDM 部署模板，掌握：

• 设置优先级链的工作原理
• 5 种 MDM 部署方式的配置格式和约束
• ADMX 单行 JSON 和 Plist UUID 的关键细节
• 部署后的验证流程

---

前置知识

• 企业级安全策略与 MDM 部署

---

项目实践

设置优先级链

Managed Settings（企业强制，最高优先级）
    ↓ 不可被覆盖
Project Settings（项目级，写入 .claude/settings.json）
    ↓ 可被 Managed 覆盖
User Settings（用户级，写入 ~/.claude/settings.json）
    ↓ 可被 Managed/Project 覆盖
Local Settings（本地临时，写入 settings.local.json）

部署方式对比

1. managed-settings.json（跨平台）

最通用的部署方式，适用于所有平台：

{
  "permissions": {
    "disableBypassPermissionsMode": true
  }
}

部署到系统配置目录（具体路径见官方文档）。

2. macOS Plist（Jamf/Kandji）

用于 MDM 的 Custom Settings payload：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>permissions</key>
    <dict>
        <key>disableBypassPermissionsMode</key>
        <true/>
    </dict>
</dict>
</plist>

关键细节：

• 偏好域：com.anthropic.claudecode
• PayloadUUID 必须全局唯一（使用 uuidgen 生成）

3. macOS Mobileconfig（完整描述文件）

完整的配置描述文件，适用于本地测试或不接受 plist 的 MDM：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadIdentifier</key>
    <string>com.anthropic.claudecode.settings</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <!-- ... 完整的描述文件结构 ... -->
</dict>
</plist>

4. Windows PowerShell（Intune）

通过 Intune Platform Scripts 部署：

Set-ClaudeCodePolicy.ps1

$settingsJson = '{"permissions":{"disableBypassPermissionsMode":true}}'
$targetDir = "C:\Program Files\ClaudeCode"
New-Item -ItemType Directory -Force -Path $targetDir
$settingsJson | Out-File -FilePath "$targetDir\managed-settings.json" -Encoding UTF8

5. Windows ADMX/ADML（Group Policy）

通过 Group Policy 或 Intune ADMX 导入部署：

关键约束：

• 设置值为 REG_SZ（单行 JSON）
• 注册表路径：HKLM\SOFTWARE\Policies\ClaudeCode\Settings
• ADMX 定义策略，ADML 提供本地化字符串

部署后验证

部署完成后，在 Claude Code 中运行 /status 命令：

Setting sources:
  - Enterprise managed settings (plist)    # macOS
  - Enterprise managed settings (HKLM)     # Windows

确认来源出现在列表中，表示 Managed settings 已生效。

陷阱与对策

陷阱	表现	对策
ADMX 单行 JSON 含换行	注册表值截断，设置不完整	使用 json.dumps(data, separators=(',', ':')) 压缩
Plist PayloadUUID 重复	描述文件安装被拒绝	每次使用 uuidgen 生成新的 UUID
JSON 中的布尔值写成字符串	设置不生效	使用 true/false（JSON 布尔值），不是 "true"/"false"（字符串）
部署路径错误	Claude Code 找不到 managed-settings.json	参照官方文档中的系统配置目录路径

设计取舍

为什么提供 5 种部署方式？

企业使用不同的 MDM 平台（Jamf、Kandji、Intune、AD）。提供每种平台的原生格式，避免管理员自行转换格式时的错误。

为什么 ADMX 要求单行 JSON？

Group Policy 的 REG_SZ 类型是单行字符串，换行符会被转义或截断。多行 JSON 在这种限制下无法正确存储。

参考来源

• Claude Code Managed Settings 文档
• 源码: examples/mdm/ 目录下所有部署模板
• 源码: examples/settings/ 目录下所有配置示例