设置文件和优先级

​

设置文件及其影响范围

​

比较每个设置文件的作用域

• ~/.claude/settings.json：您机器上的每个项目，而队友的机器上和云端会话中都不会生效
• acme-app/.claude/settings.json：您的 acme-app/。只有当您将该文件提交到版本控制后，它才会覆盖到队友的克隆和云端会话；在此之前，它只是您磁盘上的一个普通文件，其他人都没有它
• acme-app/.claude/settings.local.json：仅您的 acme-app/。Claude Code 第一次写入该文件时会将其添加到您的全局 git 排除项中，因此它不会进入您的提交；如果您手动创建该文件，请自行将其添加到 .gitignore
• 托管设置，无论是 managed-settings.json 文件、MDM 策略，还是来自 claude.ai 控制台的服务器托管设置：您的组织部署到的每台机器上的每个项目，或您使用组织账户登录的每台机器上的每个项目。只有服务器托管设置会覆盖到云端会话

​

查找或创建设置文件

• 托管：由您的组织部署。您无需创建或编辑它。
• 共享项目：已经使用 Claude Code 的项目可能已提交了该文件。如果没有，请在项目文件夹中的 .claude/settings.json 创建它。
• 用户和项目本地：您可以自行创建，也可以让 Claude Code 创建。当您第一次在 /config 菜单中更改存储在用户设置中的选项（例如主题）时，它会写入 ~/.claude/settings.json；当您第一次在权限提示上给予常设批准（例如对 Bash 命令选择”Yes, and don’t ask again”）时，它会写入 .claude/settings.local.json。少数 /config 选项（包括 Show tips）会保存到 .claude/settings.local.json，而不是用户文件。

​

与团队共享设置

​

将个人设置保留在仓库之外

• Claude Code 也会写入它。 当 Claude 请求运行 Bash 命令的权限而您选择”Yes, and don’t ask again”时，Claude Code 会将该权限批准作为 allow 规则保存在此处。
• 您无需自行将其加入 gitignore，除非您是手动创建的。 Claude Code 第一次在尚未忽略该文件的 git 仓库中写入它时，会将 **/.claude/settings.local.json 添加到您的全局 git 排除文件中，因此该文件在每个仓库中都不会进入您的提交。当您的全局 git 配置将 core.excludesFile 设置为绝对路径或以 ~ 开头的路径时，该排除文件就是 core.excludesFile；否则为 $XDG_CONFIG_HOME/git/ignore，或在未设置 XDG_CONFIG_HOME 时为 ~/.config/git/ignore。如果您手动创建了该文件且 Claude Code 尚未写入它，请自行将其添加到 .gitignore。
• 只要文件保持未跟踪状态，其允许规则就无需等待信任。 由于该文件属于您而不属于仓库，Claude Code 会应用其 allow 规则，而无需经过已提交文件所要求的工作区信任步骤。如果该文件被 git 跟踪，信任步骤同样适用于它；请参阅本地设置文件何时需要信任。

​

Claude Code 在 git 仓库中保存本地文件的位置

• 文件改为与 .claude/settings.json 放在一起的情况：在 git 仓库之外、仓库根目录是您的主目录时、在 Windows 上，或者仓库根目录或其 .git 或 .claude 条目不归您的用户所有时。
• 文件中的路径不以仓库根目录为锚点：以 / 开头的权限规则或相对沙箱路径改为以会话的主工作目录为锚点。

​

检查组织强制执行的内容

• 服务器托管设置，由 Claude Code 从 claude.ai 管理控制台或自托管的 Claude apps gateway 获取
• MDM 或操作系统级别的策略，以及系统目录中的 managed-settings.json 文件
• 嵌入主机（例如 Claude Desktop），通过 SDK managedSettings 选项提供；请参阅从嵌入主机控制策略

​

更改设置

​

使用 /config 菜单

• 大多数选项：~/.claude/settings.json
• 一些选项，如显示提示：.claude/settings.local.json
• 全局配置选项：~/.claude.json

​

编辑设置文件

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

​

为一个会话更改设置

• --settings：将键作为 JSON 传递，内联或作为文件路径。Claude Code 在您的用户、项目和本地文件上方以及托管设置下方应用它。它可以设置您的用户设置文件可以设置的任何键；它不能设置 Managed 或 Global config 键。
• 该键的标志：某些键有自己的标志，如 --model 用于 model 和 --effort 用于 effortLevel 和 modelSettings。
• 环境变量：在运行 claude 之前导出键的配对变量，如 ANTHROPIC_MODEL 用于 model。

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

​

编辑何时生效

• model：使用 /model 在会话中期切换。每个模型有自己的提示缓存，因此切换后的第一个请求重新读取整个对话未缓存；请参阅切换模型
• effortLevel 和 modelSettings：使用 /effort 在会话中期更改努力

​

确认已加载的内容

​

修复损坏的设置文件

• 设置错误：用户、项目或本地文件有无效的 JSON 或架构拒绝的值。在交互式会话启动时，Claude Code 显示一个对话框，让您在 Claude 的帮助下修复文件、退出，或在不加载这些损坏设置的情况下继续。
• 设置警告：仅单个条目失败，如格式错误的权限规则或未知的 hook 事件名称。Claude Code 跳过这些值并保持文件的其余部分生效。
• 托管设置：Claude Code 继续强制执行文件的其余部分。托管设置中的无效条目说明它删除什么以及哪些键回退到更严格的值，直到您修复它们。对于不是有效 JSON 的托管设置文档，请参阅托管设置文档无法解析。
• 配置错误：~/.claude.json 无法解析。claude -p 运行会退出，您的文件保持不变。请参阅 Configuration error in ~/.claude.json 以恢复较早的副本。Claude Code 将损坏的文件复制到 ~/.claude/backups/.claude.json.corrupted.<timestamp>，并在交互式会话中询问是退出并修复它，还是重置为默认配置。当文件为空且没有可恢复的备份时，Claude Code 以默认设置启动。

​

设置优先级

1. 托管设置：由您的组织部署的设置，通过 managed-settings.json 文件、MDM 策略或来自 claude.ai 控制台的服务器托管设置提供。您自己的设置文件或 --settings 中的任何内容都无法覆盖托管的键，而 --model 等标志只能从您的组织允许的模型中进行选择。托管的 model 只是初始默认值，而非锁定；起锁定作用的是 availableModels 和 deniedModels。当您的组织提供多个托管来源时，托管层级内的优先级规则说明了 Claude Code 从每个来源读取哪些内容。
2. 命令行：启动 claude 时通过 --settings <file-or-json> 传入的 JSON，仅对该会话有效；请参阅为单个会话更改设置。在此处设置的键会覆盖项目和用户设置文件中的同一个键，而未在此处设置的键则保留这些文件中的值。其他标志（例如 --model）只为会话设置一项内容，不属于此层级堆栈；设置参考中每个键的条目说明了哪些标志会覆盖该键。
3. 项目本地设置（.claude/settings.local.json）：您针对此项目的个人设置。
4. 共享项目设置（.claude/settings.json）：您的团队提交到源代码管理中的设置。
5. 用户设置（~/.claude/settings.json）：适用于所有项目的个人设置。

​

列表会合并而非覆盖

• fallbackModel 是一个有序链，其中位置具有意义，因此 Claude Code 会从定义了它的最高优先级文件中获取整个值。
• modelPicker 保存一个有序的行列表以及一个替换标志，因此 Claude Code 从不合并来自两个来源的行。它从托管设置、--settings 和用户设置中定义了该键的最高级别获取整个值，并忽略项目设置和本地设置中的该键。需要 Claude Code v2.1.242 或更高版本。
• availableModels：当 Claude Code 应用的托管设置定义了该键时，Claude Code 会原样应用该列表，并忽略您在用户、项目或本地设置中添加的条目，除非嵌入 Claude Code 的应用提供了自己的模型列表；请参阅托管设置优先级的例外情况。在多个托管来源之间，该列表同样不会合并；Claude Code 如何组合托管来源说明了采用哪个来源的列表。在非托管作用域之间，Claude Code 照常合并数组。
• modelSettings：Claude Code 会逐个模型解析该键，并结合 effortLevel 一起解析。modelSettings 条目说明了对某个模型采用哪个文件中的值。

​

优先级示例

​

团队设置覆盖个人设置

​

组织设置覆盖一切

​

命令行在单个会话中覆盖您的文件

​

标志或环境变量设置了同一项内容

​

排查未生效的设置

​

您设置的值被忽略

• 更高级别设置了该键。 另一个设置文件、--settings 标志或托管来源在高于您的级别设置了该键；层级堆栈说明了具体是哪一个。标志或环境变量也可以自行覆盖该键，这是按键逐一决定的；设置参考中该键的条目说明了 Claude Code 使用哪一个，而 env 条目介绍了托管 env 值与 shell 导出之间的关系。
• 安全键保持其严格值。 对于少数键，Claude Code 会采用任何文件中的限制性值，因此项目中为 disableClaudeAiConnectors 设置的 true 会保持生效；请参阅托管设置优先级的例外情况。
• 该文件无法设置该值。 permissions.defaultMode 的值 auto 和 bypassPermissions 在项目或本地设置中不会生效；请改为在用户设置或托管设置中设置它们，或者传入 --permission-mode 以用于单个会话。在 v2.1.257 之前，bypassPermissions 在任何文件中都会生效。 env 块中的遥测导出变量在项目或本地设置中同样不会生效，少数关闭值除外。Claude Code 在 env 中忽略的变量列出了这些变量及相应的值。
• 该文件已损坏。 无效的 JSON 或被拒绝的值会导致 Claude Code 跳过该文件或该条目；请参阅修复损坏的设置文件。

​

您在 Claude Code 中所做的更改在新会话中丢失

​

托管更改尚未应用到您这里

​

已提交的键未对队友生效

• Claude Code 会忽略仓库文件中的该键。 在设置索引的 Scope 列中查找 User, local, or managed、User or managed、User、Managed 或 Global config。这些键从不通过共享文件生效，但仓库文件仍可关闭其中的少数几个。每个此类条目都会在其 Scope 行中注明这一点。Global config 键仅在 ~/.claude.json 中生效。 在 env 键中，遥测导出变量同样从不通过共享文件生效，少数关闭值除外；请参阅Claude Code 在 env 中忽略的变量。
• 该键需要等待信任。 permissions.allow 规则、permissions.additionalDirectories、extraKnownMarketplaces 以及大多数 env 值仅在每位队友信任该文件夹之后才会生效。在此之前，他们仍会看到权限提示，也不会从该文件声明的市场获取插件。deny 和 ask 规则会立即生效。

​

权限规则的组合方式与您的预期不同

• 您在权限提示中选择了”Yes, and don’t ask again”，但对同一工具仍会收到提示。 该选择会将一条 allow 规则保存到您的本地文件中，而本地文件中的 allow 规则的优先级并不高于项目或托管文件中的 ask 规则；权限规则如何组合解释了其中的顺序。在 VS Code 扩展中，批准卡片允许您选择目标文件，包括项目的共享文件，这会为所有人更改该规则；在 CLI 中，Claude Code 只会写入您的本地文件。
• 您组织的允许规则仍会与您的规则一起生效。 这是预期行为：Claude Code 会跨作用域合并 permissions.allow，除非您的组织设置了 allowManagedPermissionRulesOnly。

​

托管设置优先级的例外情况

​

云会话中的设置

• 项目中的云端线程：在项目中的云端线程里，无论该项目包含多少个仓库，仓库 .claude/settings.json 中的权限规则、hook 和 env 均不适用。线程从您的仓库中获取哪些内容列出了可改用的方式。
• 共享项目设置（.claude/settings.json）：在项目线程之外只有一个仓库的会话中会被读取，因为该文件是克隆的一部分，且会话在其中启动。将设置提交到该文件中，即可在这些会话中应用。
• 包含多个仓库的共享项目设置：在 Anthropic 托管的环境中，包含多个仓库的会话会在各克隆的上层目录启动，并且只从每个仓库的 .claude/settings.json 中读取 enabledPlugins 和 extraKnownMarketplaces 这两个键，而不会读取权限规则、hook、env 或其他键。这两个键所声明的市场和插件仍然不会在云端会话中加载。对于自托管环境，请参阅应用哪个仓库的设置。
• 用户和项目本地设置 (~/.claude/settings.json 和 .claude/settings.local.json)：不读取。两者都保持在您的机器上，本地文件不在克隆中。
• 托管设置：您设备上的 managed-settings.json 文件或 MDM 配置文件不会到达云会话。您组织的服务器管理设置会；表面覆盖列出哪些云会话接收它们。自托管环境也读取其运行器镜像中的托管设置文件。Claude Code 如何组合托管来源说该文件何时适用。
• /config：在浏览器中的 claude.ai/code 上，它会打开您的 claude.ai Code 或 Claude Code 设置页面，而不是更改某个值。要为云端会话更改设置，请在环境上设置环境变量。在项目线程之外只有一个仓库的会话中，您也可以改为将该键提交到该仓库的 .claude/settings.json。

​

接下来是什么

• 所有设置：每个键，以及您在哪里设置它和示例
• 示例设置文件：个人文件、团队文件和组织的托管文件
• 配置权限：允许、询问和拒绝规则，以及 Claude Code 在不询问的情况下运行什么
• 环境变量：Claude Code 读取的变量和 env 块
• 调试您的配置：当设置不适用时
• Claude 目录参考：Claude Code 读取的每个文件，包括 subagents、MCP 服务器、插件和 CLAUDE.md