设置文件与优先级

本页讲怎么修改 Claude Code 的设置、选择一个键应该放在哪个范围、验证修改是否生效，以及一个键在多处设置时 Claude Code 用哪个值。完整的键清单见官方的 All settings 页。

设置文件及其影响范围

Claude Code 读取四个设置文件，组织还可以从 claude.ai 控制台下发托管设置。每个来源有一个范围：保存在其中的设置适用于哪些人和项目——只是你、项目里的所有人，还是整个组织。

在「文件」列里，~/.claude 是你家目录下的 .claude 文件夹，单独的 .claude 是项目里的 .claude 文件夹。

举例来说：~/.claude/settings.json 影响你机器上的每个项目，而不影响队友的或云端会话；acme-app/.claude/settings.json 只有当你把它提交进版本控制，才会到达队友的克隆和云端会话。托管设置（无论是 managed-settings.json 文件、MDM 策略还是 claude.ai 控制台下发的服务器托管设置）影响你组织部署到的每台机器上的每个项目。

查找或创建你的设置文件

安装 Claude Code 不会创建任何设置文件。如果你的机器或项目已经有一个，它来自：托管（你的组织部署，你不创建也不编辑）；共享项目（已经使用 Claude Code 的项目可能提交了一个，没有的话在项目文件夹里创建 .claude/settings.json）；用户和项目本地（自己创建，或让 Claude Code 创建。你第一次在 /config 菜单里更改它存到用户设置里的选项（如主题）时，它会写 ~/.claude/settings.json）。

在 Windows 上，~/.claude 指 %USERPROFILE%\.claude。想把家目录文件放到别处，设置 CLAUDE_CONFIG_DIR。Claude Code 还会保留第五个它自己写的文件 ~/.claude.json，你不需要编辑它，里面有登录会话、MCP 服务器配置和按项目的状态（如信任决定）。

与团队共享设置

提交 .claude/settings.json，让每个克隆仓库的人都得到同样的权限、Hook 和插件。每位队友仍然可以在自己的 .claude/settings.local.json 里为自己覆盖，所以个人例外不需要提交。注意你提交的一些内容要等每位队友信任文件夹后才生效，还有少数键永远不会从仓库文件里生效。

让个人设置留在仓库之外

想只为自己在一个项目里改某个设置而不影响队友，把它存进项目里的 .claude/settings.local.json。Claude Code 把这个文件应用在已提交的 .claude/settings.json 之上，所以如果团队文件设了 "model": "claude-sonnet-5" 而你想要 Opus，把你的值放这里。Claude Code 也会写这个文件：当 Claude 请求权限运行 Bash 命令而你选「Yes, and don't ask again」时，Claude Code 会把这条权限批准作为 allow 规则保存在这里。第一次在尚未忽略它的 git 仓库里写这个文件时，Claude Code 会把 **/.claude/settings.local.json 加进你的全局 git excludes 文件。

修改设置

三种方式：/config 菜单、编辑设置文件、从命令行为单个会话修改。（Claude Code 的系统提示没有公开；想给 Claude 常驻指令，用 CLAUDE.md 文件或 --append-system-prompt 标志。）

用 /config 菜单

在 Claude Code 里运行 /config 并打开 Config 标签页。它列出一小组个人选项，如主题、编辑器模式和详细输出，而不是每个设置键。选择一个选项来修改，Claude Code 会替你保存：大多数选项存到 ~/.claude/settings.json；少数选项（如 Show tips）存到 .claude/settings.local.json；全局配置选项存到 ~/.claude.json。不用菜单设置某一项时，传 key=value，如 /config verbose=true。/config 是终端界面的一部分，VS Code 聊天面板和桌面应用不打开它。

编辑设置文件

在你的编辑器里打开想要的范围的设置文件，添加或修改一个键。设置文件是严格的 JSON：// 注释或尾逗号都是语法错误，Claude Code 在下次启动时把该文件报告为 Settings Error。例如让 Claude 无需询问就运行 lint 和测试命令，同时禁止读取 .env：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

permissions 下的每一项都是一条命名了工具及其可做之事的规则。$schema 这行指向 Claude Code 设置的已发布 JSON schema，可以在编辑器里获得自动补全和校验。保存后，在 Claude Code 里运行 /status 确认文件已加载。官方还有「示例设置文件」页，展示完整的个人、团队和组织文件，每个键都带注释。

为单个会话修改设置

想试一个值而不保存它，启动 Claude Code 时设置。值只对那个会话生效，设置文件保持原样。三种方式：

• --settings：以 JSON 传入键，内联或文件路径。Claude Code 把它应用在你的用户、项目和本地文件之上、托管设置之下
• 该键专用的标志：一些键有自己的标志，如 --model 对应 model，--effort 对应 effortLevel
• 环境变量：在运行 claude 之前导出该键对应的变量，如 ANTHROPIC_MODEL 对应 model

例如，在不更改默认值的情况下用 Opus 开一个会话：

claude --settings '{"model": "claude-opus-5-5"}'

何时生效

Claude Code 监视你的设置文件，在它们变化时重新加载，所以多数编辑无需重启就应用到运行中的会话，包括 permissions、hooks 和 apiKeyHelper 这类凭据助手。少数键只在会话开始时读取一次，对它们的编辑不会到达运行中的会话，例如 model（会话中途用 /model 切换）和 effortLevel（用 /effort 改）。

确认加载了什么

在 Claude Code 里运行 /status 查看哪些设置来源处于活动状态。Status 标签页里有一行 Setting sources，列出 Claude Code 为当前会话加载的每个设置文件。这一行确认 Claude Code 读了哪些文件，但不显示每个键由哪个文件提供。想列出被 Claude Code 拒绝的条目，运行 claude doctor。

修复损坏的设置文件

如果你把 JSON 打错了，或给某个键设了 Claude Code 不接受的值，Claude Code 会在交互式会话开始时告诉你：Settings Error（用户、项目或本地文件有无效 JSON 或 schema 拒绝的值，会弹出对话框让你在 Claude 的帮助下修复、退出或不带损坏设置继续）；Settings Warning（只有个别条目失败，如畸形的权限规则或未知的 Hook 事件名，Claude Code 跳过那些值并保留文件的其余部分）；Configuration error（~/.claude.json 无法解析，Claude Code 把坏文件复制到 ~/.claude/backups/.claude.json.corrupted.<timestamp>，并问你是退出手动修复还是重置为默认配置）。-p 运行不显示对话框，会跳过损坏的文件或值继续，之后运行 claude doctor 查看它丢掉了什么。

设置优先级

同一个键出现在多处时，Claude Code 使用设置它的最高层级的值。从高到低：

1. 托管设置：组织通过 managed-settings.json 文件、MDM 策略或 claude.ai 控制台的服务器托管设置部署。你设置的任何东西都不能覆盖它们：用 --settings 传的键也不能覆盖同一个托管键
2. 命令行参数：你在终端启动 claude 时为单个会话传的标志。用 --settings <file-or-json> 传的 JSON 按与其他层相同的规则与你的设置文件合并
3. 项目本地设置（.claude/settings.local.json）：你在这个项目里的个人设置
4. 共享项目设置（.claude/settings.json）：团队提交进源码管理的设置
5. 用户设置（~/.claude/settings.json）：你对每个项目的个人设置

环境变量不是这个栈里的一个层级。当某个行为既有 shell 变量又有设置键时，用哪个是逐对决定的：比如在 shell 里导出的 ANTHROPIC_MODEL 优先于任何文件里的 model 键。对少数安全敏感的键，Claude Code 会优先采用较低层级里更严格的值而不是托管值。

列表合并而不是覆盖：同一个列表键（如 permissions.allow）在多个文件里设置时，Claude Code 会合并列表，所以每个文件都可以添加条目而不删除其他文件的条目。四个保存模型列表或按模型条目的键遵循自己的规则（如 fallbackModel 是顺序有意义的有序链，取优先级最高文件里的整个值）。

优先级示例

Claude 工作时，Claude Code 会在旋转指示器下显示一行提示。假设你不想要这些提示，在 ~/.claude/settings.json 里把 spinnerTipsEnabled 设为 false：

• 团队设置覆盖个人设置：团队的 .claude/settings.json 把它设为 true，Claude Code 使用项目的值，因为共享项目高于用户，所以你在那个项目里能看到提示。你可以把自己的值拿回来：在该项目的 .claude/settings.local.json 里加 "spinnerTipsEnabled": false，项目本地高于共享项目，所以你在那里的会话不再显示提示，队友的不变
• 组织设置覆盖一切：组织的托管设置把它设为 true，你在用户、项目或本地设置里放的任何东西都无法关掉，--settings 也不行。运行 /status 看哪个托管来源适用，如果策略应该改，问你的管理员
• 命令行为单个会话覆盖你的文件：用 claude --settings '{"spinnerTipsEnabled": true}' 启动会话，命令行高于除托管外的每个文件，所以即使你的文件说 false，那个会话也显示提示；下个会话你的值就回来了
• 标志或环境变量设置同一件事：一些键有标志或环境变量，无论哪个文件设置了它，都覆盖设置的值，如 ANTHROPIC_MODEL 覆盖 model 设置，--model 在一个会话里覆盖两者

排查不生效的设置

设置了某个键而 Claude Code 没有按你设置的行为时，先用 /status 看它加载了哪些文件。你设置的值被忽略时：

• 更高层级设置了它：另一个设置文件、--settings 标志或托管来源在你之上设置了该键
• 安全键保持严格值：对少数键，Claude Code 采用任何文件里的限制性值，所以项目里设的 true（比如对 disableClaudeAiConnectors）保持开启
• 该文件无法设置该值：permissions.defaultMode 的 auto 和 bypassPermissions 值不会从项目或本地设置生效，要在用户或托管设置里设置，或用 --permission-mode 为一个会话传入

更广泛的检查（包括干净配置测试）见官方的「Debug your configuration」。

每个设置键的作用域、类型、默认值和用途见全部设置项。