设置文件和优先级

​

设置文件及其影响范围

​

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

• ~/.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 命令的”是的，不要再问”）时，它会写入 .claude/settings.local.json。一些 /config 选项，包括显示提示，保存到 .claude/settings.local.json 而不是用户文件。

​

与你的团队共享设置

​

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

• Claude Code 也会写入它。 当 Claude 要求运行 Bash 命令的权限，你选择”是的，不要再问”时，Claude Code 将该权限批准保存为此处的 allow 规则。
• 除非你手动创建，否则你不需要 gitignore 它。 Claude Code 第一次在不已忽略它的 git 仓库中写入文件时，它会将 **/.claude/settings.local.json 添加到你的全局 git 排除文件中，因此该文件在每个仓库中都不会进入你的提交。该文件是 core.excludesFile（当你的全局 git 配置将其设置为绝对路径或 ~ 前缀路径时）；否则是 $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 Code 将损坏的文件复制到 ~/.claude/backups/.claude.json.corrupted.<timestamp> 并询问是否退出并手动修复它或重置为默认配置；-p 运行打印错误并退出。要恢复您之前的状态，复制回 ~/.claude/backups/ 中最近五个 .claude.json.backup.<timestamp> 文件之一，Claude Code 在写入文件前保存。

​

设置优先级

1. 托管设置：您的组织部署的设置，通过 managed-settings.json 文件、MDM 策略或来自 claude.ai 控制台的服务器管理设置。您设置的任何内容都不会覆盖它们：您使用 --settings 传递的键不会覆盖相同的托管键，--model 等标志仅从您的组织允许的模型中选择。托管 model 设置每个会话启动的模型，您仍然可以使用 /model 切换；锁定是 availableModels，它限制 /model、--model 和您自己文件中的 model 键。当您的组织传递多个托管来源时，托管层内的优先级的规则说 Claude Code 从每个读取什么。
2. 命令行参数：您在从终端启动 claude 时传递的标志，用于一个会话；请参阅为一个会话更改设置。Claude Code 使用与其他级别相同的规则将您使用 --settings <file-or-json> 传递的 JSON 与您的设置文件合并：它在此处设置的键优先于本地、项目或用户设置中的相同键，省略的键保持较低级别的值。
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 尊重任何文件的限制值，因此项目 true 用于 disableClaudeAiConnectors 保持开启；请参阅托管设置优先级的例外。
• 文件无法设置该值。 permissions.defaultMode 值 auto 和 bypassPermissions 不从项目或本地设置生效；改为在用户或托管设置中设置它们，或为一个会话传递 --permission-mode。在 v2.1.257 之前，bypassPermissions 从任何文件生效。 env 块中的遥测导出变量也不从项目或本地设置生效，除了少数关闭值。Claude Code 在 env 中忽略的变量列出变量和这些值。
• 文件损坏。 无效的 JSON 或拒绝的值使 Claude Code 跳过文件或条目；请参阅修复损坏的设置文件。

​

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

​

托管更改还没有到达您

​

提交的键不到达队友

• Claude Code 忽略存储库文件中的键。 在设置索引的作用域列中查找 User, local, or managed、User or managed、Managed 或 Global config。这些键永远不会从共享文件应用，除了少数几个存储库文件仍然可以关闭的。每个这些条目在其作用域行上说明。Global config 键仅从 ~/.claude.json 应用。 在 env 键内，遥测导出变量也永远不会从共享文件应用，除了少数关闭值；请参阅Claude Code 在 env 中忽略的变量。
• 键等待信任。 permissions.allow 规则、permissions.additionalDirectories、extraKnownMarketplaces 和大多数 env 值仅在每个队友信任文件夹后应用。在那之前他们仍然看到提示并不从文件声明的市场获得插件。deny 和 ask 规则立即应用。

​

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

• 您在权限提示上选择了”是的，不要再问”但仍然为相同的工具获得提示。 该选择将 allow 规则保存到您的本地文件，本地的 allow 规则不优先于项目或托管文件中的 ask 规则；权限规则如何组合解释顺序。在 VS Code 扩展中，批准卡让您选择目标文件，包括项目的共享文件，这改变了每个人的规则；在 CLI 中，Claude Code 仅写入您的本地文件。
• 您的组织的允许规则仍然与您的一起应用。 这是预期的：Claude Code 跨作用域合并 permissions.allow，除非您的组织设置 allowManagedPermissionRulesOnly。

​

托管设置优先级的例外

​

云会话中的设置

• 共享项目设置 (.claude/settings.json)：在一个存储库的会话中读取，因为该文件是克隆的一部分，会话在其中启动。在那里提交设置以在这些会话中应用它。具有多个存储库的会话在克隆上方启动，因此从每个存储库的 .claude/settings.json 仅读取 enabledPlugins 和 extraKnownMarketplaces 键，而不是权限规则、hooks、env 或其他键。这些两个键声明的市场和插件仍然不在云会话中加载。
• 用户和项目本地设置 (~/.claude/settings.json 和 .claude/settings.local.json)：不读取。两者都保持在您的机器上，本地文件不在克隆中。
• 托管设置：仅服务器管理设置到达云会话；您设备上的 managed-settings.json 文件或 MDM 配置文件不会。自托管环境也读取其运行器镜像中的托管设置文件。Claude Code 如何组合托管来源说该文件何时适用。
• /config：在您的浏览器中的 claude.ai/code，打开您的 claude.ai 设置的 Claude Code 部分而不是更改值。要为云会话更改设置，在环境上设置环境变量，或在具有一个存储库的会话中，将键提交到该存储库的 .claude/settings.json。

​

接下来是什么

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