---
title: "配置 Claude Code"
description: "Claude Code 配置不是只改一个 settings.json。先分清 managed、user、project、local 四个作用域，再决定权限、环境变量、Hooks、MCP、插件和记忆放哪里。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-08"
---

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

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

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

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

```text
~/.claude/settings.json
```

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

这会出问题。

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

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

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

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

官方 [Claude Code settings](https://code.claude.com/docs/en/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。

> [!TIP]
> **一句话判断**：别人 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 本身也是更强边界。

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

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

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

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

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

这很重要。

假设 managed 有：

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

user 又加：

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

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

这解释了一个常见误判：

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

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

> [!IMPORTANT]
> **一句话记住**：数组配置会合并；想禁止，用 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 文件。

另一个关键文件是：

```text
~/.claude.json
```

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

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

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

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

```json
{
  "$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"
}
```

这个例子表达三层意思：

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

> [!TIP]
> **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，不提交。

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

## 8. 敏感文件怎么处理

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

常见写法：

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

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

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

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

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

> [!WARNING]
> **不要把 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：

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

> [!CAUTION]
> **Managed 是组织边界，不是个人偏好**：一旦放到 managed，普通用户和项目都不能覆盖。不要把会随项目变化的规则写成全组织策略。

## 10. 怎么确认配置生效

不要靠猜。

先看：

```text
/status
```

它会显示当前加载的 settings source、认证方式和关键状态。如果某个 settings 文件 JSON 错误，也能在这里暴露。

权限问题看：

```text
/permissions
```

记忆和规则问题看：

```text
/memory
```

安装和环境健康看：

```bash
claude doctor
```

配置排障顺序：

<Steps>

<Step>
### `/status` 看 settings 文件是否真的被加载
不要凭感觉。先确认 source 列表里出现你改的那个文件，再讨论字段是不是写对。
</Step>

<Step>
### 检查 JSON 结构
JSON 语法错误（多/少逗号、引号不闭合）会让整个文件被忽略；schema 红线只是提醒，未必是真错。
</Step>

<Step>
### 看 scope 和优先级
你改的是 user，但 project 或 managed 已经写了同名规则就会覆盖。优先级：managed > 命令行 > local > project > user。
</Step>

<Step>
### 检查数组合并
`permissions.allow` / `sandbox.allowWrite` / `enabledPlugins` 等数组跨 scope 是拼接去重，不是替换。空数组通常清不掉低优先级。
</Step>

<Step>
### 按能力继续定位
权限相关 → `/permissions`；记忆相关 → `/memory`；安装/环境相关 → `claude doctor`。
</Step>

<Step>
### 重开 session 验证
某些字段（如 `defaultMode`、`autoUpdatesChannel`）只在新会话生效。改完先 exit 再 `claude` 进。
</Step>

</Steps>

> [!TIP]
> **排障口诀**：先确认文件被加载，再确认谁覆盖谁，最后才看具体字段是不是写错。

## 11. 常见坑

- 团队规则写进 user：只有你生效，别人复现不了。应放 project。
- 本机路径写进 project：别人 clone 后失效。应放 local。
- 密钥写进 settings：可能泄露到仓库或日志。应放凭据系统 / secret。
- 用空数组想清掉别的 scope（作用域）：结果仍然合并。应使用 deny 或 managed。
- 不看 `/status`：容易误判配置没生效。先看 source。
- 忽略 managed：反复改 user 也无效。找管理员或看 policy。
- 把项目规则全写 JSON：难读、难维护。写 `CLAUDE.md`。
- 共享 `~/.claude.json`：会泄露会话和状态。只共享项目文件。

## 12. 本章自检

试着用自己的话回答：

1. 为什么写配置前要先判断这条规则属于谁？对应 §1-§2。
2. managed、local、project、user 的优先级是什么？对应 §3。
3. 为什么空数组通常不能清掉低优先级 scope 的 allow？对应 §4。
4. `.claude/settings.json`、`.mcp.json`、`CLAUDE.md` 分别适合放什么？对应 §5-§7。
5. 为什么 `permissions.deny` 不能替代 sandbox？对应 §8。

> [!IMPORTANT]
> **过关标准**：你能拿一条真实配置，判断它应该放 user、project、local 还是 managed，并能用 `/status` 解释它为什么生效或没生效。

<details id="glossary">
<summary><b>本篇术语速查表</b></summary>

- Settings：设置。控制 Claude Code 行为的层级配置。
- Scope：作用域。配置归属和生效范围。
- Managed：管理员配置。组织或机器级强制策略，不能被覆盖。
- User：用户配置。当前用户所有项目的默认配置。
- Project：项目配置。仓库共享配置，应该提交给团队。
- Local：本地配置。当前仓库当前机器私有配置，不提交。
- Precedence：优先级。多个 scope（作用域）同时存在时谁覆盖谁。
- Array merge：数组合并。数组字段跨 scope 拼接去重，不是替换。
- `~/.claude.json`：全局状态文件。保存 OAuth、MCP user/local、project state 和缓存。
- `CLAUDE.md`：项目说明文件。存放项目规则、偏好和长期上下文。
- Managed policy：管理策略。企业级强制约束，如禁用 bypass 或限制 marketplace。
- JSON schema：JSON 模式。给编辑器补全和校验 settings 的 schema。

</details>

## 官方来源

- [Claude Code settings](https://code.claude.com/docs/en/settings)
- [Debug your configuration](https://code.claude.com/docs/en/debug-your-config)
- [Server-managed settings](https://code.claude.com/docs/en/server-managed-settings)
- [Explore the .claude directory](https://code.claude.com/docs/en/claude-directory)
- [Configure permissions](https://code.claude.com/docs/en/permissions)

## 接下来去哪

<Cards>
  <Card href="/docs/claude-code/official/01-core-capabilities/permissions" title="管理权限" description="Settings 里最常用、也最容易出风险的是 permissions（权限）。下一章专门讲 allow、ask、deny 和权限模式。" />
  <Card href="/docs/claude-code/official/00-getting-started/platforms" title="选择平台与集成（上一篇）" description="不同入口会影响配置在哪里生效。CLI、Desktop、Web、Remote Control 的边界要先分清。" />
  <Card href="/docs/claude-code/understanding/11-permissions" title="深度理解：权限怎么管" description="如果想看更完整的权限心智模型，可以先读理解篇的 Permissions。" />
</Cards>

如果只记一个判断：**配置不是把所有开关写进一个 JSON，而是把个人、团队、本机和组织边界写到正确的 scope（作用域）里。**
