配置文件

Claude Code 的配置分散在几类文件里，各自管不同的东西：settings.json 管行为开关与权限，CLAUDE.md 管“给 Claude 的说明书”，.mcp.json 管项目级 MCP 服务器，~/.claude.json 管登录状态等杂项。理解它们各自的位置和优先级，能解决大部分“为什么我改了配置却没生效”的问题。

作用域总览

Claude Code 用统一的“作用域”体系决定一份配置对谁生效、要不要进代码仓库：

不同功能对应的具体文件路径：

Windows 上 ~/.claude 对应 %USERPROFILE%\.claude。

优先级与合并规则

同一个配置项在多处出现时，按下面顺序生效（从高到低）：

1. Managed（企业管控）—— 任何其它层级都无法覆盖，包括命令行参数
2. 命令行参数（如 --settings）—— 仅本次会话临时覆盖
3. Local(.claude/settings.local.json)
4. Project(.claude/settings.json)
5. User(~/.claude/settings.json）—— 兜底

标量值（字符串/数字/布尔）是“高优先级覆盖低优先级”；数组类配置（如 permissions.allow）则是跨层级拼接去重，而不是覆盖——例如企业策略里 allowWrite 设了 ["/opt/company-tools"]，你个人又加了 ["~/.kube"]，最终两条路径都生效。fallbackModel（有序降级链）和 managed 层设置的 availableModels 是例外，由最高优先级那一份文件整体决定，不做合并。

想知道当前会话实际加载了哪些配置来源，运行 /status，查看 Setting sources 一行；配置文件本身有 JSON 格式错误或校验失败，/doctor 会列出具体文件与错误详情。

settings.json

这是最核心的配置文件，支持权限规则、环境变量、hooks、状态栏、插件开关等几乎所有行为定制。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "deny": ["Bash(curl *)", "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

顶部的 $schema 指向官方 JSON Schema，在 VS Code / Cursor 等支持 JSON Schema 校验的编辑器里能获得自动补全和内联校验（schema 更新有滞后，新字段偶尔会被误报，不代表配置真的错了）。

何时生效

Claude Code 会监听配置文件变化并自动重新加载，permissions、hooks、apiKeyHelper 等大多数字段改完立刻在当前会话生效（ConfigChange hook 会为每次检测到的变化触发一次）。只有两个字段例外，改完要下次重启或用对应命令才生效：

• model —— 用 /model 临时切换
• outputStyle —— 属于系统提示词的一部分，只有 /clear 或重启会话时才会重建

常用字段精选

settings.json 支持的字段有几百个（权限、hooks、沙箱、插件、企业策略……），这里只列日常最常用的一批；完整列表见官方 Settings 文档。

权限规则速查

permissions.allow / ask / deny 是最常用的一组字段，规则格式为 Tool 或 Tool(specifier):

⚠️ v2.1.282 起，中间带 :* 的 Bash 规则（此前只有 --allowedTools 认、写在 settings 文件里会被跳过）对所有来源都生效，启动时会告警说明它怎么匹配；Skill(anthropic-skills:*) 这类技能规则在 v2.1.282 / v2.1.283 的变化见 Skills。

排除敏感文件是最常见的用法之一：

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)"
    ]
  }
}

CLAUDE.md：项目记忆

CLAUDE.md 是一份纯文本 markdown 文件，每次会话开始时都会被加载，用来存放“你不想每次重新口述一遍”的项目知识：构建/测试命令、代码规范、架构决策、目录约定。

存放位置与加载顺序

Claude Code 从当前工作目录往上逐级查找 CLAUDE.md/CLAUDE.local.md 并全部拼接进上下文（离工作目录越近的排在越后面，即“越具体的指令越靠后被读到”）；子目录下的 CLAUDE.md 则是按需加载——只有 Claude 读取该子目录下的文件时才会带上。

用 /init 可以自动生成初版 CLAUDE.md（已存在时则给出改进建议而非覆盖）；建议控制在 200 行以内，太长的文件会占用上下文并降低指令遵循度，长内容应该拆到 .claude/rules/ 里按需加载，而不是塞进主文件。

@ 导入与 AGENTS.md 兼容

CLAUDE.md 里可以用 @path/to/file 语法导入其它文件，启动时一并展开进上下文（最多 4 层递归，反引号包裹的 `@path` 不会被当作导入）：

参见 @README 了解项目概况，@package.json 查看可用的 npm 命令。

# 个人偏好
- @~/.claude/my-project-instructions.md

如果仓库已经在用 AGENTS.md 给其它编码工具用，不用重复维护两份，导入一下即可：

@AGENTS.md

## Claude Code 专属说明

`src/billing/` 下的改动一律先进计划模式。

🆕 v2.1.277+：项目里没有 CLAUDE.md 时，Claude Code 会直接读取 AGENTS.md 作为项目说明，这项行为可以在 /config 的「Project instructions」里修改。⚠️ v2.1.281 起 Bedrock、Vertex、Foundry、LLM 网关与关闭遥测的会话也支持（此前这些会话只读 CLAUDE.md）。已有 CLAUDE.md 的项目照旧读 CLAUDE.md，想同时用上 AGENTS.md 仍按上面的方式导入。

用 .claude/rules/ 拆分大型说明

大项目建议把 CLAUDE.md 拆成多个主题文件放进 .claude/rules/，每个文件一个主题，可选用 paths frontmatter 限定只在操作匹配文件时才加载，节省上下文：

---
paths:
  - "src/api/**/*.ts"
---

# API 开发规则

- 所有接口必须包含入参校验
- 统一使用标准错误响应格式

不带 paths 的规则和 .claude/CLAUDE.md 一样，每次都会加载。~/.claude/rules/ 则是个人级、跨项目生效的规则目录。

自动记忆（Auto Memory）

除了你手写的 CLAUDE.md，Claude 还会在工作过程中自己积累笔记——构建命令、调试心得、代码风格偏好等，不需要你手动维护。

• 存放位置：~/.claude/projects/<project>/memory/，以 MEMORY.md 为索引入口，配合若干主题文件
• 每次会话只加载 MEMORY.md 的前 200 行或 25KB（以先到者为准），主题文件按需读取
• 默认开启，可在 settings.json 里设 "autoMemoryEnabled": false 关闭，或在会话内用 /memory 切换
• 同一个 git 仓库的所有 worktree 共享同一份自动记忆，但不跨机器同步

自动记忆是纯 markdown，随时可以用 /memory 打开查看、编辑或删除。

.mcp.json：项目级 MCP 服务器

项目要用到的 MCP 服务器配置写在仓库根目录的 .mcp.json 里，和团队共享：

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

出于安全考虑，仓库自带的 .mcp.json 不会被自动信任启动——首次使用需要你在会话里手动批准。想提前在 settings.json 里声明批准/拒绝名单，用 enabledMcpjsonServers/disabledMcpjsonServers:

{
  "enabledMcpjsonServers": ["github", "memory"]
}

个人级、只在你本机生效的 MCP 服务器配置（以及 OAuth 会话）则存放在 ~/.claude.json 里，通常通过 claude mcp add//mcp 管理，不建议手动编辑。

⚠️ v2.1.274 起，.mcp.json（以及 settings、插件与 agent 文件）里 "type": "sdk" 的 MCP 条目会被跳过并告警：进程内服务器只有 SDK 宿主应用才能注册。

~/.claude.json：其它状态

这个文件保存的是“不属于团队共享配置”的杂项状态：OAuth 登录会话、用户/本机作用域的 MCP 服务器配置、每个项目的信任状态与已批准工具缓存等。Claude Code 会自动为配置文件创建带时间戳的备份并保留最近 5 份，避免误操作导致数据丢失。日常不需要手动改这个文件，出问题时优先用 claude doctor//doctor 诊断，而不是直接编辑。

企业级管控配置（简述）

面向组织统一下发的策略配置，不属于个人日常配置范围，这里只做提要：

• 服务端下发：通过 claude.ai 管理后台或自托管的 Claude apps 网关，登录时远程下发
• MDM / 系统策略：macOS 用 com.anthropic.claudecode 配置描述文件，Windows 用 HKLM\SOFTWARE\Policies\ClaudeCode 注册表项
• 文件下发：managed-settings.json（以及可选的 managed-settings.d/ 目录做策略分片）放在系统级目录（macOS /Library/Application Support/ClaudeCode/、Linux /etc/claude-code/、Windows C:\Program Files\ClaudeCode\)

这一层配置任何用户/项目/本机配置都无法覆盖，常用于强制安全策略（禁用 bypassPermissions、限制可用模型、企业级 CLAUDE.md 等），具体格式和字段与个人 settings.json 完全一致。另有几个只在托管层有意义的键：managedMcpServers（v2.1.259+，给全员下发 HTTP/SSE 类 MCP 服务器）、modelPricing（v2.1.243+，让 /cost 与遥测按合同单价计算；v2.1.271 起其中的 multiplier 可以大于 1，最高 10，用于加价后的内部分摊费率）。

🆕 v2.1.283 起多了两个按版本管控模型的托管键：availableModelsMatch 设为 "exact" 时，availableModels 里的每个模型 ID 只放行它点名的那个版本（"claude-opus-5" 不再顺带放行 Opus 5.5），新版本在列入名单前一直被挡住；deniedModels 点名封禁某些模型，即使 availableModels 允许也不行。两者写在用户、项目、本机设置或 --settings 里都会被忽略并告警：

{
  "availableModels": ["opus", "sonnet"],
  "deniedModels": ["claude-opus-5-5"]
}

🆕 v2.1.282 起还有 allowClaudeInChromeWithManagedMcp：让 claude --chrome 能与独占 MCP 控制的 managed-mcp.json 同时使用。

⚠️ v2.1.259 起托管设置文件、MDM plist 或注册表值无法解析时 Claude Code 直接拒绝启动并指出来源，不再静默地不执行策略。v2.1.271 起企业 managed-mcp.json 无法读取或解析时同样不会被忽略：它继续独占 MCP 控制（用户、项目与插件的服务器都不加载），并在启动时告警。

v2.1.282 起托管的 permissions、autoMode、worktree、attribution（v2.1.283 起还有 sandbox）里某个嵌套值不合法时，不再整块作废，其余部分照常生效；disableClaudeAiConnectors 这类布尔锁定键的值写错时，锁定照样生效，启动时点名这个键。⚠️ 同样从 v2.1.282 起，Windows 与 WSL 上的管理员策略（HKLM 或 managed-settings.json）存在但无效或读不了时，用户可写的 HKCU 与 WSL 的 /etc/claude-code 也不再生效。

排查配置问题

• /status —— 查看当前会话实际加载了哪些配置来源（Setting sources），配置文件有语法/校验错误时也会在这里列出受影响的文件
• /doctor —— 做一次安装与配置体检，给出每个问题的详细信息与来源，经你确认后直接修复
• /memory —— 确认 CLAUDE.md/CLAUDE.local.md/rules 是否被正确加载
• 指令没被遵守，优先检查：文件是否在会被加载的位置、指令是否够具体、多份 CLAUDE.md 之间是否有冲突