<!-- title: Claude Code Settings全字段调优实战 -->

# Claude Code Settings全字段调优实战：五层配置体系从入门到精通

## 概述

本文系统解析Claude Code的`settings.json`配置体系，涵盖五层作用域优先级、全部可用字段、权限系统、环境变量注入、模型路由、沙箱隔离、Hooks集成与企业管理策略。适用于已有Claude Code基础使用经验、希望深度定制工作流的开发者与团队技术负责人。读完本文，你将能独立构建从个人开发到百人团队的全场景配置方案。

## 前置条件

- 已安装Claude Code CLI（v1.0+）
- 熟悉JSON配置文件基本语法
- 了解命令行环境变量概念
- 有至少一个项目的实际使用经验

---

## 一、五层配置作用域：谁优先、谁覆盖

Claude Code的配置系统遵循严格的优先级体系。理解这个层级，是解决"我的配置为什么不生效"的根本。


![图表1](images/claude-code-tutorial-r2-1248-mermaid-0.png)

> *图表 1*


### 1.1 五层作用域详解

| 优先级 | 作用域 | 文件位置 | 影响范围 | 是否共享 |
|--------|--------|----------|----------|----------|
| 1（最高） | Managed | 系统级目录 | 机器所有用户 | 是（IT部署） |
| 2 | CLI Flags | 命令行参数 | 仅当前会话 | 否 |
| 3 | Local | `.claude/settings.local.json` | 仅你、仅此项目 | 否（gitignore） |
| 4 | Project | `.claude/settings.json` | 所有协作者 | 是（提交到git） |
| 5（最低） | User | `~/.claude/settings.json` | 仅你、所有项目 | 否 |

**核心规则**：高优先级作用域的设置始终覆盖低优先级。IT部门在Managed层设置`deny`规则，没有任何用户或项目配置可以覆盖它。

### 1.2 Managed Settings的操作系统路径

Managed settings需要管理员权限，存放位置因操作系统不同：

| 操作系统 | 路径 |
|----------|------|
| macOS | `/Library/Application Support/Claude/managed-settings.json` |
| Linux | `/etc/claude-code/managed-settings.json` |
| Windows | `C:\ProgramData\Claude\managed-settings.json` |

该目录下有两个文件：`managed-settings.json`（设置）和`managed-mcp.json`（MCP服务器配置）。

### 1.3 何时用哪个作用域


![图表2](images/claude-code-tutorial-r2-1248-mermaid-1.png)

> *图表 2*


**实战决策速查**：
- 想禁止全团队访问`.env`文件 → Project Scope
- 想让公司的安全策略不可被员工绕过 → Managed Scope
- 想在自己的机器上覆盖团队配置 → Local Scope（优先级3高于4）
- 想临时测试一个新模型 → CLI Flags（`claude --model claude-sonnet-4-5-20250929`）

---

## 二、Settings.json全部字段分类解析

### 2.1 快速启用Schema自动补全

在任何`settings.json`文件的第一行加入：

```json
{
  "$schema": "https://json-schema.org/claude-code-settings.json",
  ...
}
```

这样在VS Code等编辑器中就能获得所有字段的自动补全和文档提示。

### 2.2 常规设置（General）

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `model` | string | 系统默认 | 主模型，如`claude-sonnet-4-5-20250929` |
| `smallModel` | string | claude-haiku | 轻量快速模型，用于简单任务 |
| `defaultMode` | string | — | 权限默认模式：`plan`/`autoEdit`/`fullAuto` |
| `autoCompact` | boolean | false | 上下文接近窗口上限时自动压缩 |
| `thinkingDepth` | string | — | 思考深度：`low`/`medium`/`high` |
| `language` | string | 系统语言 | 界面语言，如`zh-CN`、`en` |
| `theme` | string | 系统 | 终端主题：`light`/`dark`/`system` |
| `statusLine` | object | — | 状态栏配置 |

**model字段路由策略**：

```json
{
  "model": "claude-sonnet-4-5-20250929",
  "smallModel": "claude-haiku-4-5-20251001"
}
```

- `model`：主对话模型，处理复杂编码任务
- `smallModel`：文件搜索、简单补全等轻量任务

你还可以通过环境变量覆盖模型别名：

| 环境变量 | 用途 |
|----------|------|
| `ANTHROPIC_MODEL` | 覆盖默认主模型 |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Sonnet别名映射 |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Opus别名映射 |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Haiku别名映射 |
| `CLAUDE_CODE_SUBAGENT_MODEL` | 子Agent使用的模型 |

**thinkingDepth调优**：

```json
{
  "thinkingDepth": "high"
}
```

- `low`：快速响应，适合简单文件编辑
- `medium`：平衡速度与推理深度
- `high`：深度推理，适合架构设计、复杂调试

**autoCompact配置**：

当上下文接近token窗口上限时，自动压缩历史对话。对于长时间会话尤其有用：

```json
{
  "autoCompact": true
}
```

**statusLine状态栏配置**：

```json
{
  "statusLine": {
    "enabled": true,
    "showTokenCount": true,
    "showCost": true,
    "showModel": true
  }
}
```

### 2.3 权限系统（Permissions）

这是`settings.json`中最核心、最复杂的部分。

#### 权限结构

```json
{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git *)", "Read(*)", "Edit(*)"],
    "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)", "Bash(rm -rf *)"],
    "defaultMode": "plan",
    "additionalDirectories": ["/path/to/shared/repo"]
  }
}
```

#### 三种规则类型

| 类型 | 说明 | 示例 |
|------|------|------|
| `allow` | 自动批准，不再弹出确认 | `"Bash(npm test)"` |
| `deny` | 始终拒绝，不可执行 | `"Read(./.env)"` |
| `ask` | 每次弹出确认 | `"Bash(curl *)"` |

**规则评估顺序**：deny → ask → allow，第一个匹配的规则生效。

#### 通配符语法

| 规则 | 匹配内容 |
|------|----------|
| `Bash` | 所有Bash命令 |
| `Bash(npm run *)` | 所有以`npm run`开头的命令 |
| `Read(./.env)` | 精确匹配读取`.env`文件 |
| `Read(./secrets/**)` | 读取`secrets/`目录下所有文件 |
| `Edit(*)` | 编辑任何文件 |
| `WebFetch(domain:example.com)` | 抓取`example.com`的内容 |
| `MCP(server_name:tool_name)` | 使用指定MCP服务器的指定工具 |
| `Write(*)` | 写入任何文件 |

#### defaultMode三种模式


![图表3](images/claude-code-tutorial-r2-1248-mermaid-2.png)

> *图表 3*


- `plan`：Claude只给出方案，不执行任何操作。适合代码审查、学习场景
- `autoEdit`：Claude自动编辑文件，但执行Bash命令需确认。日常开发推荐
- `fullAuto`：全自动，包括Bash命令。CI/CD场景使用

#### additionalDirectories

允许Claude访问工作目录之外的路径：

```json
{
  "permissions": {
    "additionalDirectories": [
      "/home/user/shared-libs",
      "/opt/common-configs"
    ]
  }
}
```

### 2.4 环境变量注入（env）

`env`字段让你在settings中持久化环境变量，无需修改shell配置：

```json
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxx",
    "ANTHROPIC_MODEL": "claude-sonnet-4-5-20250929",
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-haiku-4-5-20251001",
    "NODE_ENV": "development",
    "DATABASE_URL": "postgresql://localhost:5432/dev"
  }
}
```

**优先级规则**：如果同一个变量同时在shell中export和在`env`字段中设置，shell环境变量优先。`env`中的值在Claude Code启动时注入，但不会覆盖已存在的环境变量。

#### 常用环境变量速查

| 变量 | 用途 |
|------|------|
| `ANTHROPIC_API_KEY` | API密钥 |
| `CLAUDE_CODE_USE_BEDROCK` | 通过AWS Bedrock路由 |
| `CLAUDE_CODE_USE_VERTEX` | 通过Google Vertex路由 |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 一键禁用遥测/自动更新/错误上报 |
| `DISABLE_AUTOUPDATER` | 禁用自动更新 |
| `DISABLE_TELEMETRY` | 禁用遥测 |
| `DISABLE_ERROR_REPORTING` | 禁用错误上报 |
| `MCP_TIMEOUT` | MCP服务器超时时间（ms） |

`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`是一个总开关，等同于同时设置`DISABLE_AUTOUPDATER`、`DISABLE_BUG_COMMAND`、`DISABLE_ERROR_REPORTING`和`DISABLE_TELEMETRY`。在离线或隐私敏感环境中非常有用。

### 2.5 沙箱设置（sandbox）

沙箱隔离控制Bash命令的执行环境：

```json
{
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false,
    "allowedCommands": ["git", "node", "npm", "python3"],
    "allowedDomains": ["github.com", "registry.npmjs.org"],
    "networkDisabled": false
  }
}
```

| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `enabled` | boolean | false | 是否启用沙箱 |
| `allowUnsandboxedCommands` | boolean | true | 是否允许非沙箱命令 |
| `allowedCommands` | array | — | 允许在沙箱中执行的命令白名单 |
| `allowedDomains` | array | — | 允许访问的网络域名白名单 |
| `networkDisabled` | boolean | false | 完全禁用网络访问 |

**注意**：文件系统和网络限制使用权限规则（`Read`、`Edit`、`WebFetch`），不是沙箱设置。沙箱主要控制Bash命令的隔离级别。

### 2.6 Git署名设置（attribution）

控制Claude Code在Git提交和PR中的署名行为：

```json
{
  "attribution": {
    "commit": "🤖 Generated with Claude Code\n\nCo-Authored-By: Claude <noreply@anthropic.com>",
    "pr": "Generated with [Claude Code](https://claude.com/claude-code)"
  }
}
```

| 字段 | 默认值 | 说明 |
|------|--------|------|
| `commit` | 含Co-Authored-By的文本 | 追加到git commit message的文本 |
| `pr` | 含链接的文本 | 追加到PR描述的文本 |

如果不需要署名，可以设为空字符串`""`。

### 2.7 Hooks配置（hooks）

Hooks是Claude Code生命周期事件中自动执行的脚本：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo 'Executing: $TOOL_INPUT' >> /tmp/claude-audit.log"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "npx prettier --write $FILE_PATH"
      }
    ],
    "Notification": [
      {
        "command": "curl -X POST https://hooks.slack.com/services/xxx -d '{\"text\": \"Claude Code task completed\"}'"
      }
    ],
    "Stop": [
      {
        "command": "osascript -e 'display notification \"Claude Code finished\" with title \"Task Done\"'"
      }
    ]
  },
  "disableAllHooks": false,
  "allowManagedHooksOnly": false
}
```

13个Hook事件类型：

| 事件 | 触发时机 | 典型用途 |
|------|----------|----------|
| `PreToolUse` | 工具调用前 | 命令审计、安全校验 |
| `PostToolUse` | 工具调用后 | 自动格式化、日志记录 |
| `Notification` | 通知触发时 | Slack/邮件通知 |
| `Stop` | 任务完成时 | 桌面通知、CI触发 |
| `SubagentStop` | 子Agent完成时 | 子任务结果汇总 |
| `PreCompact` | 上下文压缩前 | 保存重要信息 |
| `PostCompact` | 上下文压缩后 | 恢复关键上下文 |
| `SessionStart` | 会话开始时 | 环境初始化 |
| `UserPromptSubmit` | 用户提交消息时 | 输入预处理 |

相关控制字段：

| 字段 | 说明 |
|------|------|
| `disableAllHooks` | 全局禁用所有Hooks |
| `allowManagedHooksOnly` | 仅允许Managed层定义的Hooks（企业安全） |

### 2.8 MCP服务器设置

```json
{
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": ["memory", "github", "filesystem"],
  "disabledMcpjsonServers": ["dangerous-tool"]
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `enableAllProjectMcpServers` | boolean | 自动批准所有项目MCP服务器 |
| `enabledMcpjsonServers` | array | 指定批准的MCP服务器列表 |
| `disabledMcpjsonServers` | array | 指定拒绝的MCP服务器列表 |

**Managed层专属字段**：

```json
{
  "allowedMcpServers": [{"serverName": "github"}],
  "deniedMcpServers": [{"serverName": "filesystem"}]
}
```

### 2.9 插件设置（plugins）

```json
{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "linter@acme-tools": false
  },
  "extraKnownMarketplaces": [
    {
      "source": "github",
      "repo": "my-org/claude-plugins"
    }
  ]
}
```

| 字段 | 说明 |
|------|------|
| `enabledPlugins` | 按插件ID开关 |
| `extraKnownMarketplaces` | 额外的插件来源 |
| `strictKnownMarketplaces` | （Managed）限制允许的插件来源 |

### 2.10 认证与提供商设置

```json
{
  "apiProvider": "anthropic",
  "apiKeyHelper": "/path/to/token-refresh-script.sh"
}
```

| 字段 | 说明 | 可选值 |
|------|------|--------|
| `apiProvider` | API提供商 | `anthropic`/`bedrock`/`vertex` |
| `apiKeyHelper` | Token刷新脚本路径 | 可执行文件路径 |

对应环境变量：

| 变量 | 用途 |
|------|------|
| `CLAUDE_CODE_USE_BEDROCK` | 使用AWS Bedrock |
| `CLAUDE_CODE_USE_VERTEX` | 使用Google Vertex |
| `ANTHROPIC_API_KEY` | 直连Anthropic的密钥 |
| `AWS_REGION` | Bedrock区域 |
| `ANTHROPIC_AUTH_TOKEN` | OAuth token |

### 2.11 高级设置

| 字段 | 类型 | 说明 |
|------|------|------|
| `disableAllHooks` | boolean | 全局禁用Hooks |
| `allowManagedHooksOnly` | boolean | 仅允许Managed层Hooks |
| `allowManagedPermissionRulesOnly` | boolean | 仅允许Managed层权限规则 |
| `customFileSearchCommand` | string | 自定义文件搜索命令 |
| `enableAllProjectMcpServers` | boolean | 一键批准所有项目MCP |

`customFileSearchCommand`接收JSON输入`{"query": "src/comp"}`，输出换行分隔的文件路径（最多15条）。

---

## 三、配置合并与冲突解决

### 3.1 数组合并规则

设置不会简单替换。如果User Scope允许`Bash(git status)`，Project Scope允许`Bash(npm run lint)`，两条规则**同时生效**——`permissions`数组会合并。

### 3.2 同键冲突

如果同一个键在不同作用域有不同值，高优先级作用域的值胜出。

### 3.3 五个典型冲突场景

**场景1：跨作用域权限冲突**

User settings允许`Bash(curl *)`，但Project settings拒绝它。

→ Project Scope（优先级4）高于User Scope（优先级5），deny生效。

→ 如果你的机器确实需要curl，把allow规则放到`.claude/settings.local.json`。Local Scope（优先级3）高于Project Scope，你的allow覆盖项目的deny。

**场景2：Managed覆盖一切**

团队Project settings允许`Bash(rm -rf *)`，但IT部署了Managed deny。

→ Managed永远赢。这是安全合规的设计意图。

**场景3：测试新Hook**

想测试一个Hook但不影响团队。

→ 写入`.claude/settings.local.json`，仅对你生效。Claude Code自动配置git忽略`.local.`文件。

**场景4：环境变量冲突**

shell中export了`ANTHROPIC_MODEL`，settings.json的`env`中也设置了。

→ shell变量优先。settings中的`env`在启动时注入但不覆盖已存在的变量。

**场景5：CLI临时覆盖**

需要临时使用不同模型测试。

```bash
claude --model claude-opus-4-6
```

→ CLI Flags（优先级2）高于除Managed外所有作用域，仅当前会话生效。

---

## 四、完整配置文件对照表

| 功能 | User Scope | Project Scope | Local Scope |
|------|-----------|---------------|-------------|
| Settings | `~/.claude/settings.json` | `.claude/settings.json` | `.claude/settings.local.json` |
| Subagents | `~/.claude/agents/` | `.claude/agents/` | N/A |
| MCP服务器 | `~/.claude.json` | `.mcp.json` | `.claude.json`（per-project） |
| Plugins | `~/.claude/settings.json` | `.claude/settings.json` | `.claude/settings.local.json` |
| CLAUDE.md | `~/.claude/CLAUDE.md` | `CLAUDE.md` | `CLAUDE.local.md` |

---

## 五、实战案例：三级配置方案

### 5.1 个人开发者配置

`~/.claude/settings.json`：

```json
{
  "$schema": "https://json-schema.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "smallModel": "claude-haiku-4-5-20251001",
  "defaultMode": "autoEdit",
  "autoCompact": true,
  "thinkingDepth": "medium",
  "language": "zh-CN",
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm run *)",
      "Bash(npx *)",
      "Read(*)",
      "Edit(*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(rm -rf *)"
    ]
  },
  "env": {
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "true"
  },
  "attribution": {
    "commit": "Co-Authored-By: Claude <noreply@anthropic.com>"
  }
}
```

### 5.2 团队项目配置

`.claude/settings.json`（提交到git）：

```json
{
  "$schema": "https://json-schema.org/claude-code-settings.json",
  "defaultMode": "autoEdit",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test*)",
      "Bash(npm run build*)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Read(*)",
      "Edit(*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(~/.ssh/**)",
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Bash(wget *)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "npx prettier --write $FILE_PATH 2>/dev/null || true"
      }
    ],
    "Stop": [
      {
        "command": "npm run lint --silent 2>/dev/null || true"
      }
    ]
  },
  "attribution": {
    "commit": "Co-Authored-By: Claude <noreply@anthropic.com>",
    "pr": "Generated with [Claude Code](https://claude.com/claude-code)"
  }
}
```

### 5.3 企业Managed配置

`/etc/claude-code/managed-settings.json`：

```json
{
  "$schema": "https://json-schema.org/claude-code-settings.json",
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Bash(rm -rf *)",
      "Bash(curl * | *)",
      "Bash(wget *)",
      "Bash(docker rm *)",
      "Bash(kubectl delete *)"
    ]
  },
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false,
    "allowedDomains": [
      "github.com",
      "registry.npmjs.org",
      "pypi.org"
    ]
  },
  "allowManagedHooksOnly": true,
  "allowManagedPermissionRulesOnly": true,
  "disableAllHooks": false,
  "allowedMcpServers": [
    {"serverName": "github"},
    {"serverName": "memory"}
  ],
  "deniedMcpServers": [
    {"serverName": "filesystem"},
    {"serverName": "browser"}
  ],
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "company-approved/claude-plugins"
    }
  ]
}
```

---

## 六、70个环境变量分类速查

Claude Code识别约70个环境变量，其中约20个在日常工作流中频繁使用。

### 6.1 模型与路由

| 变量 | 用途 |
|------|------|
| `ANTHROPIC_MODEL` | 覆盖主模型 |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Sonnet别名（适合自定义模型） |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Opus别名 |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Haiku别名 |
| `CLAUDE_CODE_SUBAGENT_MODEL` | 子Agent模型 |

模型别名在组织运行自定义微调模型时特别有用——设置一次别名，所有会话自动生效。

### 6.2 云提供商

| 变量 | 用途 |
|------|------|
| `CLAUDE_CODE_USE_BEDROCK` | AWS Bedrock路由 |
| `CLAUDE_CODE_USE_VERTEX` | Google Vertex路由 |
| `AWS_REGION` | Bedrock区域 |
| `ANTHROPIC_BEDROCK_BASE_URL` | Bedrock自定义端点 |
| `ANTHROPIC_VERTEX_PROJECT_ID` | Vertex项目ID |
| `ANTHROPIC_VERTEX_REGION` | Vertex区域 |

### 6.3 隐私与网络

| 变量 | 用途 |
|------|------|
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 一键禁用所有非核心网络请求 |
| `DISABLE_AUTOUPDATER` | 禁用自动更新 |
| `DISABLE_BUG_COMMAND` | 禁用bug上报命令 |
| `DISABLE_ERROR_REPORTING` | 禁用错误上报 |
| `DISABLE_TELEMETRY` | 禁用遥测 |

`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`是总开关，在离线/高安全环境中首选。

### 6.4 MCP与超时

| 变量 | 用途 |
|------|------|
| `MCP_TIMEOUT` | MCP服务器超时（ms） |
| `MCP_TOOL_TIMEOUT` | 单个MCP工具超时（ms） |

运行重量级MCP服务器（数据库连接、浏览器自动化）时，建议显式设置超时。

---

## 七、配置调试与故障排查

### 7.1 配置不生效排查流程


![图表4](images/claude-code-tutorial-r2-1248-mermaid-3.png)

> *图表 4*


### 7.2 常见陷阱

**陷阱1：`.claude/`目录不存在**

手动创建：
```bash
mkdir -p .claude
```

**陷阱2：JSON语法错误**

settings.json必须是合法JSON。注释（`//`）不被支持。验证方法：

```bash
python3 -c "import json; json.load(open('.claude/settings.json'))"
```

**陷阱3：权限规则语法错误**

常见错误写法：
```json
"allow": ["npm test"]
```
正确写法：
```json
"allow": ["Bash(npm test)"]
```

权限规则必须以工具名开头（`Bash`、`Read`、`Edit`、`Write`、`WebFetch`、`MCP`）。

**陷阱4：local文件被意外提交**

Claude Code会自动在`.git/info/exclude`中添加忽略规则，但如果你的项目使用`.gitignore`管理，建议额外添加：

```
.claude/settings.local.json
.claude/CLAUDE.local.md
```

**陷阱5：env字段值必须是字符串**

```json
"env": {
  "SOME_FLAG": true
}
```
错误！必须是：
```json
"env": {
  "SOME_FLAG": "true"
}
```

### 7.3 使用/config交互式调试

在Claude Code会话中输入`/config`可以查看和修改当前生效的所有配置。这比手动检查多个文件更直观。

---

## 八、Settings与CLAUDE.md的关系

两者互补但不重叠：

| 维度 | settings.json | CLAUDE.md |
|------|--------------|-----------|
| 控制什么 | Claude**能做什么** | Claude**应该知道什么** |
| 格式 | JSON | Markdown |
| 内容 | 权限、工具、行为 | 知识、约定、上下文 |
| 级别 | 机器可执行规则 | 自然语言指令 |

最佳实践是两者配合使用：


![图表5](images/claude-code-tutorial-r2-1248-mermaid-4.png)

> *图表 5*


---

## 九、进阶技巧

### 9.1 利用Local Scope安全实验

想测试一个新Hook但不影响团队？写入`.claude/settings.local.json`。优先级3高于Project Scope的优先级4，你的实验配置优先生效，且不会被提交到git。

### 9.2 多模型路由降本

```json
{
  "model": "claude-sonnet-4-5-20250929",
  "smallModel": "claude-haiku-4-5-20251001",
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-haiku-4-5-20251001"
  }
}
```

这样主对话使用Sonnet处理复杂任务，子Agent和轻量操作使用Haiku，显著降低Token成本。

### 9.3 通过API Provider实现多云路由

```json
{
  "apiProvider": "bedrock",
  "env": {
    "AWS_REGION": "us-east-1"
  }
}
```

或通过Vertex：
```json
{
  "apiProvider": "vertex",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "my-project",
    "ANTHROPIC_VERTEX_REGION": "us-central1"
  }
}
```

### 9.4 自动格式化Hook

每次Edit操作后自动运行Prettier：

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ]
  }
}
```

### 9.5 安全审计Hook

记录所有Bash命令执行日志：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo \"[$(date '+%Y-%m-%d %H:%M:%S')] $CLAUDE_TOOL_INPUT\" >> /var/log/claude-audit.log"
      }
    ]
  }
}
```

### 9.6 完全离线/高安全环境配置

```json
{
  "env": {
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "true"
  },
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false,
    "networkDisabled": true
  },
  "permissions": {
    "deny": [
      "WebFetch(*)",
      "Read(./.env*)",
      "Read(~/.ssh/**)",
      "Bash(curl *)",
      "Bash(wget *)"
    ]
  }
}
```

---

## 十、配置迁移与版本管理建议

### 10.1 新项目快速初始化

创建一个模板脚本：

```bash
#!/bin/bash
mkdir -p .claude
cat > .claude/settings.json << 'SETTINGS'
{
  "$schema": "https://json-schema.org/claude-code-settings.json",
  "defaultMode": "autoEdit",
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git *)", "Read(*)", "Edit(*)"],
    "deny": ["Read(./.env)", "Read(./.env.*)", "Bash(rm -rf *)"]
  }
}
SETTINGS

cat > CLAUDE.md << 'CLAUDE'
# 项目说明
（在此填写项目技术栈、目录结构、开发规范）

# 构建命令
- 构建: `npm run build`
- 测试: `npm test`

# 编码规范
- TypeScript严格模式
- ESLint + Prettier
CLAUDE

echo ".claude/settings.local.json" >> .gitignore
echo "Claude Code配置已初始化！"
```

### 10.2 团队配置版本化

- `.claude/settings.json` → 提交到git，团队共享
- `.claude/settings.local.json` → gitignore，个人覆盖
- `CLAUDE.md` → 提交到git，项目知识
- `CLAUDE.local.md` → gitignore，个人偏好

### 10.3 Settings变更审查

团队项目的`.claude/settings.json`变更应该通过PR审查。建议在CLAUDE.md中加一条规则：

```markdown
# 重要规则
- 修改.claude/settings.json前必须创建PR并获得审批
- 禁止在project scope中添加Bash(rm *)相关allow规则
```

---

## 延伸阅读

- [Claude Code官方设置文档](https://code.claude.com/docs/en/settings) — 官方配置参考
- [Claude Code权限系统文档](https://code.claude.com/docs/en/permissions) — 权限规则完整说明
- [Claude Code企业管理部署](https://code.claude.com/docs/en/admin-setup) — Managed Settings部署指南
- [Managed-Settings Builder](https://managed-settings.net/) — 可视化生成企业安全策略
- [Claude Code Best Practice - Settings](https://github.com/shanraisshan/claude-code-best-practice/blob/main/best-practice/claude-settings.md) — 社区维护的配置最佳实践

## 参考来源

1. [Claude Code Settings - 官方文档](https://code.claude.com/docs/en/settings) — Anthropic官方settings.json配置参考，涵盖五层作用域和全部字段定义
2. [Claude Code Settings Reference (Complete Config Guide) - ClaudeFast](https://claudefa.st/blog/guide/settings-reference) — 社区维护的完整配置参考，包含70+环境变量和实战示例
3. [Claude Code settings.json 配置详解 - VincentQiao](https://blog.vincentqiao.com/claude-code-settings-intro/) — 中文系列文章，详解五层优先级、权限语法和合并逻辑
4. [Claude Code Settings.json完全配置指南 - gitsilence](https://blog.lacknb.cn/articles/2026/04/14/1776132862854.html) — 中文完整字段参考，含环境变量和认证配置
5. [Claude Code Enterprise Deployment - CodingNomads](https://codingnomads.com/claude-code-enterprise-deployment-policies-settings) — 企业部署策略对比与Managed Settings实战

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)