配置体系¶

本文你会学到：

• 🏗️ 理解 Claude Code 五层配置优先级的含义和作用范围
• 📝 配置文件的位置与冲突解决规则
• ✅ 根据场景选择合适的配置层级
• 💡 配置最佳实践与常见陷阱

→ 更多内容请查看子页面：「CLAUDE.md 记忆文件」「Settings 与权限」「模型与输出风格」「高级配置」

🏗️ 为什么 Claude Code 的配置很重要？¶

想象一下：你刚入职一家公司，有公司制度（所有员工都要遵守）、部门规章（你所在部门的额外规则）、还有你个人的工作习惯。这三层规则共同决定了你「能做什么」和「该怎么做」。

Claude Code 的配置体系也是同样的道理——它有五层配置，从「管理员强制执行的安全策略」到「你个人的偏好」，层层叠加、逐级覆盖。理解这个体系，你就掌握了让 Claude Code 按你的意愿高效工作的钥匙。

graph TD
    A["🔴 Managed<br/>管理员强制"] --> B["🟠 CLI 参数<br/>单次会话"]
    B --> C["🟡 Local<br/>本地偏好"]
    C --> D["🔵 Project<br/>团队共享"]
    D --> E["⚪ User<br/>全局个人"]

    F["💡 实际场景"] --> A
    F --> G["禁用 Fast Mode<br/>禁止 rm -rf<br/>API 端点锁定"]
    F --> H["--model opus<br/>--permission-mode plan"]
    F --> I["个人工具白名单<br/>本地路径配置"]
    F --> J["团队编码规范<br/>共享 MCP 配置"]
    F --> K["全局语言偏好<br/>默认权限"]

    style A fill:transparent,stroke:#d32f2f,stroke-width:2px
    style B fill:transparent,stroke:#f57c00,stroke-width:2px
    style C fill:transparent,stroke:#fbc02d,stroke-width:1px
    style D fill:transparent,stroke:#0288d1,stroke-width:1px
    style E fill:transparent,stroke:#768390,stroke-width:1px
    style F fill:transparent,stroke:#7b1fa2,stroke-width:1px

数字越小优先级越高——左边的 Managed 像公司的「安全制度」，右边的 User 像你的「个人偏好」。当两层配置冲突时，高优先级覆盖低优先级。

📂 配置文件有哪几层？¶

五层优先级¶

Claude Code 的所有配置都遵循相同的优先级规则：数字越小优先级越高。

💡 把它想成 CSS 的优先级：!important > inline style > ID > class > tag。Managed 配置就像 !important，无论你怎么设置，它说了算。

📝 一些实用的配置项：

• autoScrollEnabled（v2.1.110 新增）：全屏模式下禁用对话自动滚动。当 Claude 输出很长而你正在回看上方内容时，关闭自动滚动可以防止页面自动跳到底部
• /config 设置持久化（v2.1.119 新增）：通过 /config 修改的设置（主题、编辑器模式、verbose 等）现在会持久化到 ~/.claude/settings.json，并参与项目/本地/策略覆盖优先级——之前这些设置只在当前会话生效，重启后就丢失了
• Auto mode $defaults（v2.1.118 新增）：在 autoMode.allow、autoMode.soft_deny 或 autoMode.environment 中使用 "$defaults" 可以在内置默认列表旁添加自定义规则，而不必全部手动重写
• Auto mode "Don't ask again"（v2.1.118 新增）：在 auto mode 选择加入提示中新增"不再询问"选项，确认后不再每次弹出
• --dangerously-skip-permissions 写入放宽（v2.1.121 改进）：不再提示对 .claude/skills/、.claude/agents/ 和 .claude/commands/ 目录的写入——这些目录本身就是 Claude 工作空间的组成部分
• --dangerously-skip-permissions 受保护路径范围扩展（v2.1.126 改进）：现在绕过对 .claude/、.git/、.vscode/、shell 配置文件等受保护路径的写入提示。不过灾难性删除命令仍会提示作为安全网，防止意外损坏关键文件
• Auto mode 错误提示增强（v2.1.128 改进）：当 auto mode 的安全分类器无法评估操作时，错误信息现在包含具体提示——建议重试、运行 /compact 释放上下文、或使用 --debug 模式运行

配置文件位置¶

每一层都有对应的配置文件路径：

⚠️ 注意：.claude/settings.local.json 和 .gitignore 默认会忽略本地配置文件，所以你的个人偏好不会意外提交到仓库。

💡 在 settings.json 文件头部添加 "$schema": "https://json.schemastore.org/claude-code-settings.json" 可以在 VS Code、Cursor 等编辑器中获得自动补全和内联验证。

全局配置（~/.claude.json）¶

部分设置存储在 ~/.claude.json 中（不是 settings.json），添加到 settings.json 会触发架构验证错误：

1
2
3
4
5

{
  "autoConnectIde": true,
  "autoInstallIdeExtension": true,
  "externalEditorContext": false
}

Worktree 设置¶

通过 worktree.* 配置 --worktree 如何创建和管理 git worktree，适用于大型 monorepo：

冲突解决规则¶

当多个层级对同一个配置项设置了不同的值时，高优先级覆盖低优先级。但有一个重要的例外：权限规则（permissions）是追加的，不是覆盖的。所有层级的 allow 规则会合并，而 deny 规则会从最严格的层级生效。v2.1.0 新增了通配符权限匹配（如 Bash(npm *)、Bash(* install)），让权限规则更灵活。

✅ 配置最佳实践¶

推荐的项目级配置¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(mvn test*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

推荐的 User 级配置¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "language": "chinese",
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit"
    ]
  }
}

💡 language 设置在 v2.1.0 中新增，用于配置 Claude 的回复语言。

主题方面，v2.1.111 新增了 "Auto (match terminal)" 主题选项，自动匹配终端的深色/浅色模式——你不再需要根据终端主题手动切换。从 /theme 命令中选择即可。

💡 命令行输入子命令时如果拼写接近但不正确，Claude Code 会自动建议最接近的子命令（v2.1.111 新增），比如输入 claude udpate 会提示 "你是想说 claude update？"。

配置层级选择指南¶

📝 小结：Claude Code 的配置体系由五层优先级构成——Managed > CLI > Local > Project > User。理解这个层级关系后，你就能精确控制 Claude Code 在不同场景下的行为。权限系统保障安全，沙箱机制提供隔离，模型配置和输出风格让你按需定制 Claude 的能力与风格。