第二章. 配置系统全解

本章学习路径

2.1. 配置作用域与优先级

上一章我们学会了用权限规则控制 Claude 的行为。但有个问题没解决：这些配置应该放在哪里？

“直接放在项目根目录不就行了？”

没那么简单。假设你有这样的需求：

• 有些配置是 个人偏好（比如你喜欢用 Opus 模型），不想影响团队其他人
• 有些配置是 团队规范（比如禁止读取 .env 文件），需要所有人遵守
• 有些配置是 临时实验（比如测试一个新的 Hook），不想提交到 Git

Claude Code 的四层配置体系就是为了解决这些问题。

2.1.1. 四层配置体系

Claude Code 的配置分为四个层级，从高到低依次是：

企业层的存放位置（不同操作系统）：

• macOS：/Library/Application Support/ClaudeCode/managed-settings.json
• Linux/WSL：/etc/claude-code/managed-settings.json
• Windows：C:\Program Files\ClaudeCode\managed-settings.json

“这四层有什么区别？”

核心区别在于 谁能看到 和 谁能覆盖。

2.1.2. 配置冲突解决规则

当同一个配置项在多个层级都有定义时，Claude Code 会按照 从高到低 的优先级来决定最终生效的值：

1

Enterprise（最高）> User > Project > Local（最低）

等等，这个顺序是不是反了？

没反。这里的 “优先级” 指的是 覆盖能力，而不是 “谁先被读取”。

举个例子：

• 企业层配置："disableBypassPermissionsMode": "disable"（禁用危险模式）
• 用户层配置："model": "opus"（使用 Opus 模型）
• 项目层配置："model": "sonnet"（使用 Sonnet 模型）

最终结果：

• 危险模式被禁用（企业层配置，无法覆盖）
• 模型使用 Sonnet（项目层覆盖了用户层）

“为什么企业层优先级最高？”

因为企业层是给 IT 管理员用的，用于强制执行安全策略。如果员工能随意覆盖企业配置，那安全策略就形同虚设了。

2.1.3. 何时用哪个作用域

这是最实用的部分——根据你的需求选择正确的配置位置：

实战示例：

“我想让所有项目默认使用 Sonnet 模型，但某个特定项目需要用 Opus。”

步骤 1：在用户层设置默认模型

1
2
3
4

# 编辑 ~/.claude/settings.json
{
  "model": "sonnet"
}

步骤 2：在特定项目的项目层覆盖

1
2
3
4

# 编辑 项目根目录/.claude/settings.json
{
  "model": "opus"
}

这样，其他项目都用 Sonnet，只有这个项目用 Opus。

2.1.4. 本节小结

四层配置体系的核心是 分层管理、按需覆盖：

2.2. settings.json 完全指南

上一节我们知道了配置文件应该放在哪里。现在来看看配置文件里 能写什么。

settings.json 是 Claude Code 的核心配置文件，支持几十个配置项。我们不会逐一讲解（那太无聊了），而是聚焦于 最常用、最实用 的几类配置。

2.2.1. 核心配置项详解

权限配置（permissions）

这个我们在第一章已经详细讲过，这里只做速查：

1
2
3
4
5
6
7

{
  "permissions": {
    "allow": ["Bash(npm test:*)"],
    "deny": ["Read(./.env)"],
    "defaultMode": "acceptEdits"
  }
}

模型配置（model）

指定 Claude Code 使用的默认模型：

1
2
3

{
  "model": "claude-sonnet-4-20250514"
}

可选值：

• sonnet —— 均衡之选（默认）
• opus —— 最强大脑
• haiku —— 快速响应

环境变量配置（env）

为 Claude Code 会话注入环境变量：

1
2
3
4
5
6
7

{
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "true",
    "CUSTOM_API_URL": "https://api.example.com"
  }
}

这些环境变量会在 Claude 执行 Bash 命令时生效。

公司公告（companyAnnouncements）

企业管理员可以配置启动时显示的公告：

1
2
3
4
5
6

{
  "companyAnnouncements": [
    "欢迎使用 Claude Code！请遵守公司代码规范。",
    "提醒：所有代码变更需要经过 Code Review。"
  ]
}

如果配置了多条公告，每次启动会随机显示一条。

2.2.2. 环境变量配置

除了在 settings.json 的 env 字段中配置，Claude Code 还支持通过系统环境变量来控制行为。

常用环境变量速查：

设置方式：

1
2
3
4
5
6
7

# 临时设置（仅当前会话）
export ANTHROPIC_MODEL=opus
claude`

# 永久设置（写入 shell 配置文件）
echo 'export ANTHROPIC_MODEL=opus' >> ~/.zshrc
source ~/.zshrc

2.2.3. 模型配置与切换

Claude Code 支持多种模型配置方式，灵活度很高。

方式 1：在 settings.json 中配置

1
2
3

{
  "model": "opus"
}

方式 2：启动时指定

1

claude --model opus

方式 3：会话中切换

1

› /model opus

方式 4：为不同任务配置不同模型

Claude Code 支持为子代理（Subagent）配置独立的模型：

1
2
3
4

{
  "model": "sonnet",
  "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
}

这样，主对话用 Sonnet，子代理用更快的 Haiku。

2.2.4. 本节小结

settings.json 的核心配置项：

2.3. 沙盒模式配置

上一章我们提到了 bypassPermissions 模式——让 Claude 完全自主执行。但这个模式太危险了，Claude 可以删除任何文件、执行任何命令。

“有没有一种方式，既能让 Claude 自主执行，又能限制它的破坏范围？”

有。这就是 沙盒一种隔离机制，限制程序只能在特定范围内操作 模式。

2.3.1. 沙盒模式的本质

沙盒模式的核心思想是：把 Claude 关在一个 “笼子” 里。

在这个笼子里，Claude 可以自由行动（不需要你确认每个操作），但它无法：

• 访问笼子外的文件系统
• 连接笼子外的网络地址

“这和 Docker 容器有什么区别？”

原理类似，但沙盒模式是 Claude Code 内置的轻量级隔离，不需要你额外安装 Docker。

2.3.2. 启用与配置

启用沙盒模式：

1

› /sandbox

或者在 settings.json 中配置：

1
2
3
4
5

{
  "sandbox": {
    "enabled": true
  }
}

完整配置示例：

1
2
3
4
5
6
7
8
9
10
11

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true
    }
  }
}

配置项解释：

2.3.3. 网络与文件系统隔离

文件系统隔离：

沙盒模式下，Claude 只能访问当前项目目录及其子目录。尝试访问项目外的文件会被拒绝。

“那如果我需要 Claude 访问 ~/.ssh/ 下的密钥呢？”

可以通过 network.allowUnixSockets 配置允许特定路径：

1
2
3
4
5
6
7
8

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"]
    }
  }
}

网络隔离：

沙盒模式下，Claude 的网络访问也受到限制。默认情况下，它无法访问外部网络。

如果你需要 Claude 访问特定的网络地址，可以通过权限规则配置：

1
2
3
4
5
6
7
8

{
  "permissions": {
    "allow": [
      "WebFetch(https://api.github.com/*)",
      "WebFetch(https://registry.npmjs.org/*)"
    ]
  }
}

2.3.4. 本节小结

沙盒模式是 “安全” 与 “效率” 的折中方案：

2.4. 本章总结与配置速查

本章我们深入学习了 Claude Code 的配置系统——从四层作用域到核心配置项，再到沙盒模式。核心思想是：分层管理、按需配置、安全优先。

2.4.1. 场景速查：遇到这些情况，直接用

场景 1：设置个人默认模型

编辑 ~/.claude/settings.json：

1
2
3

{
  "model": "opus"
}

场景 2：为团队项目配置统一规范

编辑 项目根目录/.claude/settings.json：

1
2
3
4
5
6
7
8

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

然后提交到 Git。

场景 3：临时测试一个配置，不想影响团队

编辑 项目根目录/.claude/settings.local.json：

1
2
3

{
  "model": "haiku"
}

这个文件会被 Git 忽略。

场景 4：启用沙盒模式，让 Claude 自主执行

1

› /sandbox

或在配置文件中：

1
2
3
4
5
6

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true
  }
}

场景 5：为 Claude 注入环境变量

1
2
3
4
5
6

{
  "env": {
    "NODE_ENV": "development",
    "API_BASE_URL": "https://dev.api.example.com"
  }
}