settings.json 配置

命令是手动动作，配置是持久化偏好。这一节把 Claude Code 三层 settings.json 讲透，让你的每一台机器、每一个项目都跑对应的规则。

三层配置的位置

Claude Code 一启动就会按固定顺序去读三个位置的 settings.json，然后合并成当前会话的最终配置。

用户级配置，跨所有项目共享，放在你的家目录：

~/.claude/settings.json

Windows 上等价路径是 %USERPROFILE%\.claude\settings.json。这里适合放和个人偏好相关的东西，比如你惯用的模型、通用的权限白名单、全局 hook。

项目共享配置，跟着项目仓库走，会被 commit 进 Git 让团队共用：

<project-root>/.claude/settings.json

这里适合放项目相关的规则，比如允许执行的 npm 脚本、项目专用的 MCP server、需要屏蔽读取的敏感目录。团队里每个人 clone 下来都会加载同一份。

项目私有配置，只对你自己生效，不进 Git：

<project-root>/.claude/settings.local.json

Claude Code 会自动把这个文件加进 .gitignore。这里适合放机器相关的信息，比如你本地的密钥文件路径、临时打开的高危权限、正在调试的 hook。

层级怎么选

一个字段该放哪一层，判断标准是它有没有跨机器复用价值。个人偏好放用户级，团队共识放项目共享，机器细节和敏感信息放项目私有。搞不清就先放项目私有，事后再往上迁最安全。

合并顺序与优先级

三层配置的加载顺序依次是用户级、项目共享、项目私有，后加载的覆盖前面的。也就是说：

• 优先级：项目私有 > 项目共享 > 用户
• 同一个字段被多层设置，取优先级最高的那份
• 数组类字段比如 permissions.allow，合并时是求并集不是覆盖，避免高层规则被静默丢掉

举个例子，你在用户级配置里默认允许 Bash(git status:*)，项目共享配置里额外允许 Bash(npm test:*)，最终这两条都生效。但如果用户级把 model 设成 Sonnet，项目共享里改成 Opus，那当前项目就用 Opus。

查看当前生效配置

不确定合并后到底是什么？在 REPL 里敲 /status 会打印当前加载的所有配置层以及最终生效值，排查配置冲突用它。

常用字段

下面按你最有可能改的字段一个一个讲，最后给一份完整示例。

model

指定默认使用的模型。可选值是 Anthropic 官方模型 ID，写全称避免歧义。

{
  "model": "claude-opus-4-7"
}

不填这一项时 Claude Code 会用官方默认策略（一般是当代主力 Sonnet）。想临时切换用 /model 命令即可，不必改配置。

permissions

权限规则，控制 Claude 能不能自动跑某些工具。详细语义在下一节展开，这里先看结构：

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Read(**)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(npm test:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push --force:*)",
      "Read(**/.env)"
    ]
  }
}

defaultMode 是启动时的权限模式，allow 是白名单，deny 是黑名单。deny 优先于 allow，冲突时以 deny 为准。

hooks

hook 是 Claude Code 在特定事件触发的脚本，比如提交前跑 lint、每次编辑后自动格式化。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write $CLAUDE_FILE" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "notify-send 'Claude 完成'" }
        ]
      }
    ]
  }
}

支持的事件包括 PreToolUse、PostToolUse、Stop、UserPromptSubmit 等。hook 输出会被 Claude Code 看到，能反过来影响后续行为，玩法很多，第六章会专门讲。

env

给 Claude 启动的子进程注入环境变量，一般用来切模型 endpoint、配代理、开调试。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-proxy.example.com",
    "HTTPS_PROXY": "http://127.0.0.1:7890",
    "CLAUDE_DEBUG": "1"
  }
}

这些变量只在 Claude Code 运行时生效，不会污染你系统环境。

apiKeyHelper

一段命令行脚本，用来动态获取 API key。适合公司环境里 key 存在 keychain、Vault、AWS Secrets Manager 里的场景。Claude Code 每次需要 key 时都会调用这段脚本拿最新值。

{
  "apiKeyHelper": "aws secretsmanager get-secret-value --secret-id anthropic-key --query SecretString --output text"
}

用这个字段的好处是 key 不会明文躺在磁盘上。

mcpServers

注册 MCP server，给 Claude 接入外部工具。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    }
  }
}

每个 server 一个 key，Claude Code 启动时会把它们全部拉起来，然后把工具挂到当前会话。第六章讲扩展的时候会详细展开。

完整示例

把上面所有字段拼在一起是这样。你可以直接复制到自己的项目里改。

{
  "model": "claude-opus-4-7",
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Read(**)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(npm test:*)",
      "Bash(npm run build:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push --force:*)",
      "Read(**/.env)",
      "Read(**/credentials/**)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write $CLAUDE_FILE" }
        ]
      }
    ]
  },
  "env": {
    "HTTPS_PROXY": "http://127.0.0.1:7890"
  },
  "apiKeyHelper": "cat ~/.secrets/anthropic-key.txt",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

敏感字段的放置层级

API key、Token、私有代理地址这些敏感字段务必写在 settings.local.json 里，不要写进项目共享的 settings.json。共享文件是要 commit 的，一旦提交上去就等于泄露到仓库历史里。

遇到 JSON 报错

Claude Code 加载 settings 时如果 JSON 语法错了，会启动失败并打印具体行号。手写容易漏逗号漏引号，建议用带 lint 的编辑器打开，或者干脆先在 jsonlint 校验一下再保存。

字段值的类型注意事项

写 settings.json 时几个常见坑：字符串必须用双引号，注释不合法（JSON 标准不支持 // 或 /* */，Claude Code 也不做额外解析），最后一个字段后面不能带逗号。想要注释效果就用一个虚拟字段代替，例如加一个 "_comment": "这一段是给团队 review 看的"，Claude Code 会忽略未知字段。数组类字段合并时按内容去重，你不用担心重复条目撑爆规则表。

在 CI 与自动化环境里的写法

跑在 CI 或 Docker 容器里的 Claude Code 一般没有交互界面，没法弹权限对话框。这种场景推荐把 settings.json 写死成明确的模式和白名单，避免默认询问导致进程挂起。举例：

{
  "model": "claude-sonnet-4-7",
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Read(**)",
      "Bash(git:*)",
      "Bash(npm:*)"
    ],
    "deny": [
      "Bash(rm -rf /:*)"
    ]
  }
}

再配合命令行的 -p 参数以非交互模式跑 Prompt，就能完全脚本化。CI 里千万不要把 --dangerously-skip-permissions 当默认，白名单写清楚更稳。

下一步

上面 permissions 那一段只是给了字段结构，规则怎么写、模式怎么切换、什么时候真的会拦下 Claude，下一节完整讲清楚。