settings.json 配置详解：层级、常用字段、环境变量

settings.json 配置详解：层级、常用字段、环境变量

配置是 Claude Code 的操作系统

如果 CLAUDE.md 是给模型看的说明书，settings.json 就是给程序本身看的配置——模型选什么、权限怎么管、钩子挂哪里、界面长什么样，全在这里。理解 settings 的关键不是背字段（字段有一百多个，官方有完整参考），而是理解层级：同一个字段写在不同文件里，效果不同、影响的人也不同。

四层配置文件，各管一摊

层级	文件位置	影响谁	典型内容
用户级	`~/.claude/settings.json`	本机所有项目的你	主题、默认模型、个人权限规则
项目共享	`.claude/settings.json`（进 git）	本项目的所有人	团队权限、hooks、插件、env
项目本地	`.claude/settings.local.json`（gitignore）	本项目的你	个人覆盖、试错沙盘
企业托管	`managed-settings.json` 等系统路径	全组织的每个人	安全策略、合规要求

几个新手不知道的细节值得点出来。这些文件不是装完就有的——Claude Code 首次在 /config 菜单里改选项时才创建用户级文件，首次在权限弹窗选"不再询问"时才创建本地文件（并自动帮你加进全局 git excludes）。~/.claude.json 是第五个文件，但它归 Claude Code 自己管（登录态、MCP 配置、项目信任状态），你不需要手编。

优先级从高到低一句话记住：托管 > 命令行 > 本地 > 项目共享 > 用户。比如团队共享文件把模型设成了 Sonnet，你想用 Opus，不用去改共享文件吵架——在本地文件写 "model": "..." 覆盖即可，只影响你自己。

常用字段速查

一百多个字段里，日常真正高频的就这些：

字段	作用
`model`	默认模型
`effortLevel`	推理力度
`permissions`	allow / ask / deny 三类权限规则
`hooks`	各生命周期事件的钩子
`env`	会话环境变量
`statusLine`	自定义状态栏（本章末有专章）
`outputStyle`	默认输出样式
`autoUpdatesChannel`	更新通道 latest / stable
`cleanupPeriodDays`	会话转录保留天数（默认 30）
`includeGitInstructions`	是否注入内置 Git 指令
`attribution`	提交/PR 的归属尾注文本
`autoMemoryEnabled`	自动记忆开关

一份真实可用的个人配置长这样：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-5",
  "autoUpdatesChannel": "stable",
  "outputStyle": "Concise",
  "cleanupPeriodDays": 14,
  "env": {
    "DISABLE_TELEMETRY": "1"
  },
  "permissions": {
    "allow": ["Bash(npm run test*)", "Bash(git diff*)"],
    "deny": ["Read(./.env*)"]
  }
}

带上 $schema 那一行，VS Code 等编辑器会给字段自动补全和校验。注意 settings 是严格 JSON——注释、尾逗号都会导致文件解析失败，启动时会弹 Settings Error 让你修。

环境变量的特殊地位

env 块里写的是会话环境变量，它有三种来源：shell 里 export、settings 的 env 块、启动前临时设置。三者不构成统一优先级——具体哪边赢是逐对判定的。比如 ANTHROPIC_MODEL 这个 shell 变量会压过任何文件里的 model 键；而 ANTHROPIC_DEFAULT_MODEL 只在没有文件设置 model 时才生效。记不住就查官方环境变量参考里每个变量的说明。

两类变量有硬性限制要记住：遥测导出类变量在项目共享/本地文件里不生效（防篡改）；permissions.defaultMode 的 auto 和 bypassPermissions 值不能写在项目或本地文件里，只能放用户级或托管层，或用 --permission-mode 临时指定。这些限制都是为了防止"别人提交的仓库文件"悄悄改你的安全姿态。

改了怎么验证

配置调错的常见姿势是"改完不知道有没有生效"。标准流程三步：

# 1. 会话内看加载了哪些配置源
/status        # Setting sources 一行列出所有生效的文件

# 2. 终端里体检错误细节
claude doctor  # 列出被拒绝的条目、解析错误

# 3. 单次试一个值，不落盘
claude --settings '{"model": "claude-opus-5-5"}'

好消息是大部分编辑即时生效：权限、hooks、env 这类改动会被监听并热加载，不用重启会话。少数字段例外（如 model、effortLevel 只在启动时读），但它们都有对应的会话内命令 /model、/effort 可中途切换。

还有一层保险：个别安全敏感键支持"低层级收紧值压过托管放开值"——比如项目文件里 disableClaudeAiConnectors: true 就算托管层想开也关不掉你的关闭状态。设计哲学一以贯之：收紧永远比放开容易。

别配错地方：settings 与相邻文件分工

配置相关文件多，新手最容易"想改 A 却改了 B"。一张分工表定乾坤：

你想改什么	该动哪里
Claude 每会话该知道的项目知识	`CLAUDE.md`
允许/禁止哪些工具调用	`settings.json` 的 `permissions` 或 hooks
固定时机的自动化脚本	`settings.json` 的 `hooks`
会话环境变量	`settings.json` 的 `env`
个人偏好但不想进 git	`settings.local.json`
`/命令` 形式的流程	`.claude/skills/`
专用子代理	`.claude/agents/`
MCP 服务器	`.mcp.json`（团队）或 `~/.claude.json`（个人）
回复风格	`.claude/output-styles/`

单次会话的临时覆盖

试一个配置值不想落盘，有三种姿势，作用范围略有差别：

# 姿势一：--settings 传 JSON 或文件，压过用户/项目/本地文件，只在本次会话生效
claude --settings '{"model": "claude-opus-5-5"}'

# 姿势二：专用旗标，如 --model、--effort
claude --model claude-opus-5-5

# 姿势三：配对的环境变量，如 ANTHROPIC_MODEL
ANTHROPIC_MODEL=claude-opus-5-5 claude

--settings 适合临时试一组配置；旗标和环境变量则是"每键一对"的设计，哪个压过文件里的值要查该键的参考条目。反向操作也有：会话内改的设置（/config、/model）默认会写回你的用户设置作为新默认——按 s 可以只切本会话不落盘。

团队共享的注意事项

把 .claude/settings.json 提交进仓库前，两条纪律：第一，不是所有键都能从仓库文件生效——查官方设置参考里的 Scope 列，标着 User、Global config 的键写进去是无效的；第二，权限 allow 规则和环境变量要等每个同事"信任该文件夹"后才生效（deny 和 ask 立即生效），所以新人入职时第一次弹的信任框别随手划掉。

调试配置不生效的完整思路：先 /status 确认文件加载了，再查更高层级是否覆盖（企业托管 > 命令行 > 本地 > 共享 > 用户），最后 claude doctor 看被跳过的条目。完整字段参考见官方设置文档。

本章由 WorkBuddy 原创整理，事实性内容参考 Claude Code 官方文档。