Claude Code 的配置体系基于一个5级优先级链，从企业策略到个人偏好逐层覆盖。本文将系统解析 settings.json 的 80+ 设置项、权限模式（allow/ask/deny）、Hooks 与 MCP 服务器集成，并说明如何通过环境变量和 CLI 启动标志进行精细控制。

Claude Code Settings 完整配置指南：80+ 设置项、权限、Hooks、MCP 详解 #

Claude Code 的行为由其配置文件 settings.json 驱动，这些文件分布在不同的位置，形成一个层级清晰的配置系统。掌握这套系统是实现从“随意编码”到结构化代理工程工作流的关键一步。本文将深入拆解 settings.json 的所有核心部分。

1. 设置的5级优先级链 #

Claude Code 的配置并非单一来源，而是按照明确的优先级顺序合并。下表列出了从高到低的5个层级：

重要规则：

• deny 规则拥有最高安全优先级，无法被更低优先级的 allow 或 ask 规则覆盖。
• 数组类型的设置（如 permissions.allow）在各个作用域间是合并并去重的，而不是替换。
• Managed settings 通过多种方式下发（服务器管理、MDM 配置、注册表策略、文件部署），并且在 Managed 内部也有优先级（server-managed > MDM/OS 策略 > 文件 > HKCU 注册表）。

2. 核心配置项概览 #

在 .claude/settings.json 的根层级，有数十个通用设置项控制 Claude Code 的基础行为。

示例：

{
  "model": "opus",
  "agent": "code-reviewer",
  "language": "japanese",
  "cleanupPeriodDays": 60,
  "alwaysThinkingEnabled": true
}

此外，还有用于组织计划文件和自动记忆存储目录的设置：

• plansDirectory: /plan 命令输出的存储目录。
• autoMemoryDirectory: 自定义自动记忆存储目录。

3. 权限系统详解 #

权限系统是控制 Claude Code 行为安全边界的核心，通过 permissions 对象进行配置。

权限模式 (defaultMode) #

三种规则类型 #

权限规则分为三类，评估顺序为：deny → ask → allow，第一个匹配的规则生效。

• allow: 无需提示即允许工具使用。
• ask: 需要用户确认。
• deny: 阻止工具使用（最高优先级）。

工具权限语法 #

不同的工具有不同的匹配语法。例如：

• Bash(command pattern): Bash(npm run *), Bash(git *)。
• Read(path pattern): Read(.env), Read(./secrets/**)。
• Edit(path pattern) / Write(path pattern): Edit(src/**)。
• MCP(server:tool): MCP(github:*)。

路径模式支持绝对路径 (//)、主目录相对 (~/)、项目根相对 (/) 和相对路径 (./) 四种前缀。

示例配置：

{
  "permissions": {
    "allow": ["Edit(*)", "Bash(npm run *)", "mcp__*"],
    "ask": ["Bash(rm *)", "Bash(git push *)"],
    "deny": ["Read(.env)", "Read(./secrets/**)"],
    "additionalDirectories": ["../shared-libs/"]
  }
}

4. Hooks 集成 #

Hooks 允许你在 Claude Code 的生命周期关键节点执行自定义脚本或触发操作。相关的设置键包括 hooks (主要配置对象)、disableAllHooks 和 allowManagedHooksOnly。关于所有 27 种事件、声音通知系统等完整细节，请参阅独立的 Claude Code Hooks 完整指南。

5. MCP 服务器配置 #

MCP (Model Context Protocol) 服务器为 Claude Code 扩展了能力。配置主要在 settings.json 的 mcpServers 字段和 .mcp.json 文件中完成。

关键设置项 #

自 v2.1.121 起，你可以在 .mcp.json 的单个服务器条目中设置 "alwaysLoad": true，使该服务器的工具在会话开始时立即加载，而不是延迟加载。

6. 沙箱 (Sandbox) 配置 #

沙箱通过 sandbox 对象配置，为 Bash 命令提供安全隔离环境。

7. 其他重要设置类别 #

Claude Code 的设置体系远不止上述几类，还包括：

• Plugins (enabledPlugins, extraKnownMarketplaces): 配置插件和市场。
• 模型配置 (model): 指定默认使用的 AI 模型。
• 显示与 UX (viewMode, tui): 控制界面显示模式，如 "focus" 或 "fullscreen"。
• AWS & Cloud Credentials: 通过 env 字段配置云服务凭证。
• Attribution (attribution): 自定义 Git 提交和 PR 的归属消息。

要查看完整的 80+ 设置项分类表格，请参考源仓库的 Settings Best Practice 文档。

8. 环境变量配置 (env) #

settings.json 中的 env 字段允许你配置超过 180 个环境变量，避免了编写包装脚本的麻烦。这些变量控制着从临时目录、Shell 行为到各种功能开关的方方面面。

示例：

{
  "env": {
    "CLAUDE_CODE_TMPDIR": "/tmp/claude-custom",
    "MAX_THINKING_TOKENS": "16000",
    "CLAUDE_CODE_SHELL": "zsh"
  }
}

9. CLI 启动标志与设置覆盖 #

命令行启动标志提供了最高优先级的临时覆盖能力。根据 CLI 启动标志参考，标志可分为 16 大类，其中直接与设置相关的包括：

• Settings Override:

  • --settings <PATH|JSON>: 加载指定路径或 JSON 字符串的设置文件。
  • --setting-sources <LIST>: 以逗号分隔的列表指定要加载的源（user, project, local）。
  • --disable-slash-commands: 为本次会话禁用所有技能和斜杠命令。

• Permissions & Security:

  • --permission-mode <MODE>: 以指定的权限模式启动（如 plan, bypassPermissions）。
  • --allowedTools <TOOLS>: 指定无需提示即可执行的工具。

这些标志可以与 settings.json 协同工作，实现灵活的临时配置调整。

10. 如何验证你的配置 #

1. 创建/修改文件: 在对应层级（用户、项目、本地）创建或编辑 .claude/settings.json。
2. 运行验证: 启动新的 Claude Code 会话。观察权限提示、可用工具列表或模型选择是否符合预期。
3. 检查合并结果: 使用 /config 命令或 claude doctor 可以查看当前生效的部分配置和诊断信息。
4. 调试模式: 使用 --debug 标志启动，可以查看详细的加载和决策日志，帮助定位配置问题。

FAQ #

Q: 如果不同层级的 permissions.allow 规则冲突了怎么办？ A: 规则不会冲突，而是会合并。所有层级的 allow 规则会被汇总到一个列表中，Claude Code 检查时会遍历这个合并后的列表。

Q: auto 权限模式和 bypassPermissions 模式有什么区别？ A: bypassPermissions 是完全跳过权限检查，对受保护路径的写入仍会提示。auto 模式则会在后台运行一个分类器进行安全检查，自动批准大多数操作，但对高风险操作仍会提示或阻止。

Q: 环境变量 env 和直接在 Shell 中设置有什么不同？ A: 在 settings.json 的 env 中设置的变量作用域更清晰，与项目配置绑定，并且可以被 Managed 策略管理。直接在 Shell 中设置的变量是全局的，可能会影响其他应用程序，且不易共享和版本控制。

Q: 如何查看当前会话实际加载了哪些设置？ A: 可以使用 --debug 启动标志，日志中会显示设置的加载来源和合并过程。也可以在交互模式中尝试使用 /config 命令。