配置 Claude Code

Claude Code 配置的第一原则不是“这个开关怎么写”，而是“这条规则属于谁”。个人偏好、团队约定、本机路径、企业策略放错位置，后面所有排障都会变成猜。——翔宇

这一章用 14 分钟换什么：入门章节已经完成安装、登录和平台选择。现在进入核心能力第一章：settings（设置）。读完你应该能判断一条配置该放 user、project、local 还是 managed，并知道怎么验证它真的生效。

1. 不要把所有东西都塞进 `settings.json`

新手一看到“配置 Claude Code”，很容易想到一个文件：

~/.claude/settings.json

然后把所有东西都写进去：个人偏好、团队规则、项目权限、本机路径、临时实验。

这会出问题。

假设你在个人 user settings 里写了：

{
  "permissions": {
    "allow": ["Bash(npm run *)"]
  }
}

这个规则会影响所有项目。个人练手项目没问题，但生产仓库可能不应该自动放行所有 npm run。你以为只是给自己省一次确认，实际是把一个项目的信任边界带到了所有项目。

第一性原理：settings（设置）不是“配置写在哪里都行”，而是用 scope（作用域）把“个人、项目、机器、组织”的责任边界分开。

官方 Claude Code settings 文档把配置拆成多个 scope（作用域）。先决定归属，再写配置。

2. 四个作用域：先问“谁应该拥有这条规则”

Claude Code 主要有四层配置作用域：

Managed：server-managed、MDM / registry、系统级 managed-settings.json。影响组织或机器上的用户，由 IT / 管理员下发。
User：~/.claude/。影响当前用户所有项目，不共享。
Project：仓库里的 .claude/。影响这个仓库所有协作者，应该提交到 git。
Local：.claude/settings.local.json。只影响当前仓库、当前机器、当前用户，通常 gitignored。

对应到中文开发者的判断：

个人主题、编辑器偏好、常用插件：放 User。
团队共同权限、Hooks、MCP 结构、项目标准：放 Project。
本机路径、临时实验、本地 credentials helper：放 Local。
企业安全策略、禁用 bypass、统一登录要求：放 Managed。

一句话判断：别人 clone 这个仓库后也应该遵守，就放 project；只有你自己用，就放 user 或 local；任何人都不许绕过，就放 managed。

判断问题	放置位置
组织强制、任何人都不能覆盖	Managed
团队协作者都要一致	Project
本机路径、临时实验、个人凭据 helper	Local
当前用户所有项目都要用	User
不确定、还在试验	Local

3. 优先级：谁能覆盖谁

同一个设置在多个 scope 出现时，官方优先级从高到低是：

优先级	来源	含义
1	Managed	最高，不能被用户、项目或命令行覆盖
2	Command line arguments	本次会话临时覆盖
3	Local project settings	当前机器当前仓库
4	Shared project settings	仓库共享配置
5	User settings	用户全局默认

比如：

User 允许 Bash(npm run *)
Project 拒绝 Bash(npm publish *)

最终 npm publish 仍然会被拒绝，因为 project 比 user 更具体，而且 deny 本身也是更强边界。

不要用 user scope 对抗 project / managed：如果项目或组织已经禁了某个行为，你改自己的 ~/.claude/settings.json 不会让它重新生效。

4. 数组不是替换，是合并

settings 里很多字段是数组，比如：

permissions.allow
permissions.deny
sandbox.filesystem.allowWrite
availableModels
allowedHttpHookUrls
enabledPlugins

官方文档强调：数组类设置跨 scope 是 concatenate and deduplicate，意思是拼接并去重，不是替换。

这很重要。

假设 managed 有：

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["/opt/company-tools"]
    }
  }
}

user 又加：

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["~/.kube"]
    }
  }
}

最终不是二选一，而是两个路径都在最终配置里。

这解释了一个常见误判：

{
  "permissions": {
    "allow": []
  }
}

空数组通常不能“清空下层 allow”。你想阻断某个能力，应写明确 deny，或者让管理员用 managed policy 约束。

一句话记住：数组配置会合并；想禁止，用 deny 或 managed policy，不要幻想空数组能擦掉别的 scope。

5. 这些文件分别管什么

Claude Code 不是只有一个配置文件。

常见对象的落点：

Settings：User 用 ~/.claude/settings.json，Project 用 .claude/settings.json，Local 用 .claude/settings.local.json。
Subagents：User 用 ~/.claude/agents/，Project 用 .claude/agents/；通常没有 Local 目录。
MCP servers：User / local state 常见在 ~/.claude.json，Project server 用 .mcp.json。
CLAUDE.md：User 可用 ~/.claude/CLAUDE.md，Project 用 CLAUDE.md 或 .claude/CLAUDE.md，Local 用 CLAUDE.local.md。
Plugins：User、Project、Local 都跟随对应 scope 的 settings 文件。

另一个关键文件是：

~/.claude.json

官方 settings 文档说明，它会保存 OAuth session、user / local scope MCP 配置、per-project state、allowed tools、trust settings 和各种缓存。

不要把 ~/.claude.json 当普通项目配置：它含有会话、信任状态和缓存。团队共享配置应该进仓库的 .claude/ 或 .mcp.json，不是复制你的全局状态文件。

6. 一个新手可用的 `settings.json`

建议给 settings.json 加 schema，方便编辑器补全和校验。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git diff *)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(npm publish *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf *)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  },
  "autoUpdatesChannel": "stable"
}

这个例子表达三层意思：

常规开发验证命令可以放行。
推送和发布要问。
密钥和高风险删除直接拒绝。

schema 只帮你发现格式问题：官方 schema 可能滞后于最新 CLI 字段。最近新增的字段被编辑器标红，不一定代表 Claude Code 不支持。

7. `settings.json` 适合管什么

常见配置可以分成几组。

适合放进 settings 的内容：

权限：permissions.allow、permissions.ask、permissions.deny、defaultMode。
环境变量：env。
沙盒：sandbox.filesystem、网络规则。
Hooks：hooks、allowedHttpHookUrls、httpHookAllowedEnvVars。
插件：enabledPlugins、extraKnownMarketplaces、strictKnownMarketplaces。
模型：model、availableModels、effortLevel。
更新：autoUpdatesChannel、minimumVersion。
登录约束：forceLoginMethod、forceLoginOrgUUID。
体验：language、editorMode、defaultShell、cleanupPeriodDays。

但它不应该承载所有东西。

不适合塞进 settings 的内容：

项目长期规则：写 CLAUDE.md 更适合。
MCP project server：写 .mcp.json 更清晰。
大段工作流说明：做 Skill。
密钥正文：用系统凭据、CI secret、vault 或环境变量。
临时路径：用 local，不提交。

边界：settings 管 Claude Code 行为开关；CLAUDE.md 管项目说明；Skill 管可复用流程；MCP 管外部工具连接。不要把它们都塞进一个 JSON。

8. 敏感文件怎么处理

官方文档建议用 permissions.deny 阻止读取敏感文件。

常见写法：

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

但这只是 Claude Code 工具层的限制。

如果你允许 Bash，子进程仍可能通过 shell 读取文件。比如一个脚本、测试或第三方工具可能自己读取 .env。

敏感文件治理至少有四层：

permissions.deny：阻止 Claude 的 Read / Edit 等工具直接访问。
Bash 权限规则：限制危险命令。
Sandbox：操作系统层限制 Bash 子进程读写。
系统文件权限：从根上限制谁能读。

不要把 deny 当沙盒：Read(./.env) 能防 Claude 直接读，不等于所有命令进程都读不到。高敏感项目要同时考虑 sandbox 和系统权限。

9. Managed settings：组织级强制策略

个人用户可以先跳过这一节，但团队和企业必须懂。

Managed settings 常见下发方式：

Server-managed settings：Claude.ai admin console 下发。
macOS MDM：com.anthropic.claudecode managed preferences domain。
Windows policy：HKLM\SOFTWARE\Policies\ClaudeCode。
文件式 macOS：/Library/Application Support/ClaudeCode/。
文件式 Linux / WSL：/etc/claude-code/。
文件式 Windows：C:\Program Files\ClaudeCode\。

Managed 适合强制：

禁用 bypass permissions。
限制登录组织。
限制可用模型。
限制 MCP server。
限制插件 marketplace。
只允许 managed permission rules。
只允许 managed hooks。

例如组织级禁止读 secrets：

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "disableBypassPermissionsMode": "disable"
  }
}