主题
06.8 Settings 配置全解
五层配置的优先级、常用键、以及"配置为什么不生效"的排查。
读完你能做什么：精确控制 Claude Code 的行为，并快速定位配置冲突。
一、五层配置优先级
Claude Code 的设置来自多个文件，从低到高优先级：
text
优先级（低 → 高）
1. 用户设置 ~/.claude/settings.json
2. 项目设置 .claude/settings.json （提交到 git）
3. 本地设置 .claude/settings.local.json （gitignore）
4. --settings 命令行指定的文件或内联 JSON
5. 管理策略设置 系统级路径（组织下发，最高，不可覆盖）高优先级覆盖低优先级的同名键；未指定的键保留低层的值。
管理策略设置在最顶层，个人无法覆盖 —— 这是企业管控的基础，见 10.3。
1.1 控制加载哪些层
bash
claude --setting-sources user,project # 只加载这两层
claude --safe-mode # 禁用所有自定义（排障）二、常用设置键
2.1 模型与推理
json
{
"model": "sonnet",
"fallbackModel": "haiku",
"effortLevel": "medium"
}2.2 权限
json
{
"permissions": {
"defaultMode": "acceptEdits",
"allow": ["Bash(npm *)", "Read", "Edit"],
"ask": ["Bash(git push *)"],
"deny": ["Bash(rm -rf *)", "Read(./.env*)"],
"additionalDirectories": ["../shared-lib"]
}
}详见 05.5。
2.3 Hooks
json
{
"hooks": {
"PostToolUse": [
{ "matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": ".claude/hooks/format.sh" }] }
]
}
}详见 06.5。
2.4 记忆
json
{
"autoMemoryEnabled": true,
"autoMemoryDirectory": "~/my-memory-dir",
"claudeMdExcludes": ["**/other-team/CLAUDE.md"]
}2.5 内联 CLAUDE.md（管理设置专用）
json
{
"claudeMd": "Always run `make lint` before committing.\nNever push to main."
}claudeMd 键只在管理/策略设置里生效。
2.6 沙箱与显示
json
{
"sandbox": { "enabled": true },
"teammateMode": "in-process",
"viewMode": "verbose"
}三、--settings 的两种用法
bash
# 指定一个设置文件
claude --settings ./ci-settings.json
# 内联 JSON（覆盖对应键，其他键保留）
claude --settings '{"model": "opus", "effortLevel": "high"}'内联设置只覆盖你指定的键，未提到的键仍从文件读取。文件必须是常规文件，不超过 2 MiB。
四、环境变量
有些行为通过环境变量控制（部分与设置键等价）：
| 环境变量 | 作用 |
|---|---|
ANTHROPIC_MODEL | 默认模型（被 --model 覆盖） |
CLAUDE_CODE_DISABLE_AUTO_MEMORY | 关闭自动记忆 |
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD | 加载附加目录的 CLAUDE.md |
CLAUDE_CODE_NEW_INIT | 启用交互式 /init |
CLAUDE_CODE_SKIP_PROMPT_HISTORY | 不保存会话 |
CLAUDE_CODE_USE_BEDROCK / CLAUDE_CODE_USE_VERTEX | 用 Bedrock / Vertex 承载 |
HTTPS_PROXY / HTTP_PROXY | 企业代理 |
MCP_TIMEOUT | MCP 启动超时 |
完整清单以官方 env-vars 文档为准。
五、配置不生效的排查流程
这是最高频的困扰。按顺序查：
步骤 1：设置文件是合法 JSON 吗
bash
claude doctor # 会报告 settings 文件的校验错误JSON 有语法错误（多余逗号、缺引号）时，整个文件可能被忽略。
步骤 2：是不是被高优先级层覆盖了
text
你在 ~/.claude/settings.json 设了 model: opus
但 .claude/settings.json 里设了 model: sonnet
→ 项目层覆盖用户层，实际用 sonnet用 --setting-sources 逐层排除定位：
bash
claude --setting-sources user "..." # 只用用户层，看行为步骤 3：是不是管理策略锁定了
管理策略设置不可被个人覆盖。如果某个设置怎么改都不生效，可能是组织策略。检查系统级路径或联系 IT。
步骤 4：是不是某个自定义搞坏了
bash
claude --safe-mode # 禁用所有自定义如果安全模式下正常，说明是某个 hook / skill / plugin / CLAUDE.md 的问题，逐个排查。
步骤 5：CLAUDE.md 到底加载了吗
text
> /context # 看 Memory files 一节见 05.6 第七节。
六、settings.json vs settings.local.json
settings.json | settings.local.json | |
|---|---|---|
| 是否提交 | 是，团队共享 | 否，Claude Code 保存时自动 gitignore |
| 放什么 | 团队一致的规则 | 你个人的偏好、本地路径 |
| 例子 | 团队的权限规则、hook | 你的模型偏好、本地 MCP |
约定：团队规范放 settings.json 并提交，个人偏好放 settings.local.json。
七、一套推荐的三文件配置
7.1 用户级（~/.claude/settings.json）
你个人跨所有项目的默认：
json
{
"model": "sonnet",
"fallbackModel": "haiku",
"effortLevel": "medium",
"autoMemoryEnabled": true
}7.2 项目级（<project>/.claude/settings.json，提交）
团队共享的规则：
json
{
"permissions": {
"defaultMode": "acceptEdits",
"allow": ["Bash(npm *)", "Bash(git status)", "Bash(git diff *)", "Read", "Edit", "Write"],
"ask": ["Bash(git push *)"],
"deny": ["Bash(rm -rf *)", "Read(./.env*)", "Bash(git push --force*)"]
},
"hooks": {
"PostToolUse": [
{ "matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": ".claude/hooks/format.sh" }] }
]
}
}7.3 个人项目级（<project>/.claude/settings.local.json，gitignore）
你在这个项目的私人偏好：
json
{
"model": "opus",
"permissions": {
"additionalDirectories": ["../my-local-scratch"]
}
}这里的 model: opus 会覆盖用户级的 sonnet，只对这个项目、只对你生效。
八、把配置纳入版本控制的策略
text
提交到 git（团队共享）：
.claude/settings.json —— 权限、hook、团队规则
.claude/CLAUDE.md —— 项目记忆
.claude/rules/ —— 分模块规则
.claude/skills/ —— 项目技能
.claude/agents/ —— 子代理
加入 .gitignore（个人/敏感）：
.claude/settings.local.json
CLAUDE.local.md
.claude/agent-memory-local/.gitignore 建议：
gitignore
.claude/settings.local.json
CLAUDE.local.md
.claude/agent-memory-local/
.claude/worktrees/