深度

Claude Code 配置完全指南：四级作用域、settings.json 字段与企业 MDM 部署

Claude Code 配置系统完全指南：四级作用域（Managed/User/Project/Local）优先级规则、settings.json 核心字段、Bash 和文件权限规则语法、沙箱 pathPrefixes 配置、各作用域文件位置，以及企业 MDM 部署（macOS plist/Windows 注册表/文件方式）。

2026/3/33分钟 阅读ClaudeEagle

Claude Code 的配置系统基于作用域（Scope）设计：从组织级的强制策略，到个人的本地偏好，每一层都有明确的覆盖规则。

四级作用域

作用域位置影响范围团队共享
ManagedMDM 策略、系统目录或服务器下发机器上所有用户是（IT 部署）
User~/.claude/你，跨所有项目否
Project.claude/（提交到 git）仓库所有协作者是
Local.claude/*.local.*（已 gitignore）仅你，仅此项目否

优先级规则

当同一设置在多个作用域中配置时，更具体的作用域优先：

  1. Managed（最高，无法被覆盖）
  2. 命令行参数（临时会话覆盖）
  3. Local（覆盖 Project 和 User）
  4. Project（覆盖 User）
  5. User（最低，仅在无其他配置时生效）

各作用域的适用场景

Managed：安全策略强制执行、合规要求、IT/DevOps 统一部署

User：个人全局偏好（主题、编辑器设置）、跨项目工具和插件、API Key

Project：团队共享设置（权限、Hooks、MCP 服务器）、标准化工具配置

Local：本地个人覆盖、配置测试、机器特定设置（不适合他人）

settings.json 核心配置

配置文件格式（支持 JSON Schema 校验）：

json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

权限规则语法

基础格式

工具名称(参数模式)

Bash 工具权限

json
"Bash(git diff *)"        // 允许所有 git diff 命令（* 前有空格）
"Bash(npm run test *)"    // 允许 npm run test 开头的命令
"Bash(curl *)"            // 拒绝所有 curl（在 deny 中）

注意空格：Bash(git diff *) 匹配 git diff HEAD，而 Bash(git diff*) 不加空格会意外匹配 git diff-index 等命令。

文件读写权限

json
"Read(~/.zshrc)"          // 允许读取特定文件
"Read(./.env)"            // 拒绝读取 .env
"Read(./secrets/**)"      // 拒绝读取 secrets 目录所有文件
"Write(./src/**)"         // 限制写入到 src 目录

沙箱配置

json
{
  "sandbox": {
    "enabled": true,
    "network": "none",
    "pathPrefixes": [
      { "path": "/tmp", "writable": true },
      { "path": "/usr/local", "writable": false }
    ]
  }
}

pathPrefixes 定义沙箱内哪些路径可读/可写，不在列表中的路径默认拒绝访问。

各作用域文件位置

功能User 位置Project 位置Local 位置
Settings~/.claude/settings.json.claude/settings.json.claude/settings.local.json
Subagents~/.claude/agents/.claude/agents/—
MCP servers~/.claude.json.mcp.json~/.claude.json（per-project）
CLAUDE.md~/.claude/CLAUDE.mdCLAUDE.mdCLAUDE.local.md

企业 Managed 部署

macOS（MDM / Jamf / Kandji）

通过 plist 推送 com.anthropic.claudecode 偏好域：

xml
<key>Settings</key>
<string>{"permissions":{"deny":["Bash(rm -rf *)"]}}</string>

Windows（组策略 / Intune）

注册表路径：HKLM\SOFTWARE\Policies\ClaudeCode

值名称：Settings（REG_SZ 或 REG_EXPAND_SZ），内容为 JSON 字符串。

文件方式

将 managed-settings.json 部署到：

  • macOS：/Library/Application Support/ClaudeCode/
  • Linux/WSL：/etc/claude-code/
  • Windows：C:\Program Files\ClaudeCode\

插件管理配置

json
{
  "enabledPlugins": ["security-tools", "code-review"],
  "strictKnownMarketplaces": true
}
  • enabledPlugins：启用的插件列表
  • strictKnownMarketplaces：仅允许从批准的市场安装插件（Managed 模式下有效）

验证当前生效配置

bash
/config        # 打开配置界面，查看所有设置
claude config  # 命令行查看

Claude Code 会自动为配置文件创建带时间戳的备份，保留最近 5 个版本。

原文：Claude Code settings | 来源：Anthropic 官方文档