配置系统

Configuration System

Claude Code 的配置系统提供了灵活的多层级配置管理，支持通过配置文件、环境变量和命令行参数进行自定义。

settings.json 三个层级

Three Levels of settings.json

Claude Code 的配置文件采用三层层级结构，与 CLAUDE.md 的层级逻辑一致。

层级结构

优先级（从高到低）:

┌────────────────────────────────────────────┐
│  本地级 .claude/settings.local.json        │  ← 最高优先级
│  不提交到 Git，个人本地覆盖                  │
├────────────────────────────────────────────┤
│  项目级 .claude/settings.json              │  ← 中等优先级
│  提交到 Git，团队共享                       │
├────────────────────────────────────────────┤
│  用户级 ~/.claude/settings.json            │  ← 最低优先级
│  全局配置，适用于所有项目                    │
└────────────────────────────────────────────┘

用户级配置

User-Level Configuration

文件路径：~/.claude/settings.json

json

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm test)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)"
    ]
  },
  "env": {
    "CLAUDE_CODE_MAX_TURNS": "50"
  }
}

项目级配置

Project-Level Configuration

文件路径：.claude/settings.json（项目根目录下）

json

{
  "permissions": {
    "allow": [
      "Bash(pnpm *)",
      "Bash(docker compose *)",
      "Bash(prisma *)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(DROP TABLE)",
      "Bash(git push --force)"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  }
}

本地级配置

Local-Level Configuration

文件路径：.claude/settings.local.json

json

{
  "permissions": {
    "allow": [
      "Bash(kubectl *)"
    ]
  },
  "env": {
    "DATABASE_URL": "postgresql://localhost:5433/mydb",
    "REDIS_URL": "redis://localhost:6380"
  }
}

配置合并规则

配置项	合并行为
permissions.allow	合并所有层级的列表
permissions.deny	合并所有层级的列表（deny 优先于 allow）
env	高优先级覆盖低优先级
其他配置项	高优先级覆盖低优先级

常用配置项

Common Configuration Options

配置项速查表

配置项	类型	说明	默认值
`permissions.allow`	string[]	允许的工具和命令	`[]`
`permissions.deny`	string[]	拒绝的工具和命令	`[]`
`env`	object	环境变量	`{}`
`mcpServers`	object	MCP 服务器配置	`{}`
`hooks`	object	事件钩子配置	`{}`

权限配置示例

json

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Glob",
      "Grep",
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(pnpm *)",
      "Bash(node *)",
      "Bash(npx *)",
      "Bash(cat *)",
      "Bash(ls *)",
      "Bash(find *)",
      "Bash(echo *)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(git push --force *)",
      "Bash(sudo *)",
      "Bash(curl * | bash)",
      "Bash(wget * | bash)"
    ]
  }
}

MCP 服务器配置

json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_TOKEN": "your-token-here"
      }
    },
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/mydb"
      ]
    }
  }
}

环境变量

Environment Variables

Claude Code 支持通过环境变量进行配置，适用于 CI/CD 和自动化场景。

核心环境变量

环境变量	说明	示例值
`ANTHROPIC_API_KEY`	Anthropic API 密钥	`sk-ant-api03-...`
`CLAUDE_CODE_MAX_TURNS`	非交互模式最大轮次	`50`
`CLAUDE_CODE_USE_BEDROCK`	使用 AWS Bedrock	`1`
`CLAUDE_CODE_USE_VERTEX`	使用 Google Vertex AI	`1`
`CLAUDE_MODEL`	指定默认模型	`claude-sonnet-4-20250514`
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	禁用非必要网络请求	`1`

AWS Bedrock 相关

环境变量	说明	示例值
`CLAUDE_CODE_USE_BEDROCK`	启用 Bedrock	`1`
`AWS_REGION`	AWS 区域	`us-east-1`
`AWS_ACCESS_KEY_ID`	AWS 访问密钥 ID	`AKIA...`
`AWS_SECRET_ACCESS_KEY`	AWS 秘密访问密钥	`wJalr...`
`AWS_SESSION_TOKEN`	AWS 临时会话令牌	`FwoG...`
`ANTHROPIC_MODEL`	Bedrock 模型 ID	`anthropic.claude-sonnet-4-20250514-v1:0`

Google Vertex AI 相关

环境变量	说明	示例值
`CLAUDE_CODE_USE_VERTEX`	启用 Vertex AI	`1`
`CLOUD_ML_REGION`	GCP 区域	`us-east5`
`ANTHROPIC_VERTEX_PROJECT_ID`	GCP 项目 ID	`my-project-123`
`GOOGLE_APPLICATION_CREDENTIALS`	服务账户密钥路径	`/path/to/key.json`

设置环境变量的方式

bash

# 方式 1: 命令行直接设置
export ANTHROPIC_API_KEY="sk-ant-api03-..."
claude

# 方式 2: 在 .env 文件中（Claude Code 不自动读取）
# 需要通过 direnv 或 dotenv 加载

# 方式 3: 在 settings.json 的 env 中配置
# ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_MAX_TURNS": "100"
  }
}

# 方式 4: 在 shell 配置文件中
# ~/.bashrc 或 ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-api03-..."

模型选择配置

Model Selection

Claude Code 支持多种方式选择和切换 AI 模型。

命令行参数

bash

# 使用 --model 参数指定模型
claude --model claude-sonnet-4-20250514

# 使用环境变量
CLAUDE_MODEL=claude-sonnet-4-20250514 claude

对话中切换

bash

# 使用 /model 命令
> /model
当前模型: claude-sonnet-4-20250514

可用模型:
  1. claude-sonnet-4-20250514
  2. claude-sonnet-4-20250514
  3. claude-haiku-35-20241022

> /model claude-sonnet-4-20250514
已切换到: claude-sonnet-4-20250514

快速模式切换

bash

# /fast 切换到更快的模型
> /fast
已切换到快速模式

# /slow 切换回标准模型
> /slow
已切换到标准模式

模型选择建议

场景	推荐模型	原因
复杂架构设计	Opus	最强推理能力
日常开发	Sonnet	速度和质量平衡
简单问答	Haiku (/fast)	响应速度快
代码审查	Sonnet	足够细致
大规模重构	Opus/Sonnet	需要强推理

API Provider 配置

API Provider Configuration

Claude Code 支持三种 API 提供商：Anthropic Direct、AWS Bedrock 和 Google Vertex AI。

Anthropic Direct（默认）

最简单的配置方式，直接使用 Anthropic API：

bash

# 设置 API 密钥
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# 启动 Claude Code
claude

配置文件方式：

json

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-api03-..."
  }
}

AWS Bedrock

适合已有 AWS 基础设施的企业用户：

bash

# 环境变量配置
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="wJalr..."

# 如果使用 AWS SSO
aws sso login --profile my-profile
export AWS_PROFILE=my-profile
export CLAUDE_CODE_USE_BEDROCK=1

# 启动
claude

Bedrock 配置注意事项：

注意事项	说明
模型可用性	需要在 AWS 控制台启用模型访问
区域支持	不是所有区域都支持所有模型
定价	按 AWS Bedrock 定价计费
IAM 权限	需要 `bedrock:InvokeModel` 权限

Google Vertex AI

适合已有 GCP 基础设施的企业用户：

bash

# 环境变量配置
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=my-project-123

# 使用应用默认凭据
gcloud auth application-default login

# 或使用服务账户
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

# 启动
claude

Vertex AI 配置注意事项：

注意事项	说明
API 启用	需要在 GCP 控制台启用 Vertex AI API
区域	推荐 us-east5（模型可用性最好）
定价	按 GCP Vertex AI 定价计费
配额	可能需要申请配额提升

Provider 对比

特性	Anthropic Direct	AWS Bedrock	Google Vertex
设置复杂度	低	中	中
企业合规	-	高	高
数据驻留	美国	可选区域	可选区域
计费方式	按量付费	AWS 账单	GCP 账单
SLA	标准	AWS SLA	GCP SLA
模型可用性	最新	略有延迟	略有延迟

配置文件完整示例

Complete Configuration Examples

个人开发者配置

json

// ~/.claude/settings.json
{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Glob",
      "Grep",
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(node *)",
      "Bash(npx *)",
      "Bash(pnpm *)",
      "Bash(ls *)",
      "Bash(cat *)",
      "Bash(find *)",
      "Bash(mkdir *)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(sudo *)",
      "Bash(git push --force *)"
    ]
  }
}

团队项目配置

json

// .claude/settings.json (提交到 Git)
{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Glob",
      "Grep",
      "Bash(pnpm *)",
      "Bash(docker compose *)",
      "Bash(prisma *)",
      "Bash(git *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(DROP *)",
      "Bash(TRUNCATE *)"
    ]
  },
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/devdb"
      }
    }
  }
}

CI/CD 配置

bash

#!/bin/bash
# ci-claude.sh - CI 环境中使用 Claude Code

export ANTHROPIC_API_KEY="${CLAUDE_API_KEY}"
export CLAUDE_CODE_MAX_TURNS=30
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# 代码审查
claude -p "审查最近一次提交的代码质量" \
  --model claude-sonnet-4-20250514 \
  --dangerously-skip-permissions

# 生成变更日志
claude -p "根据最近 10 次提交生成变更日志" \
  --model claude-sonnet-4-20250514 \
  --dangerously-skip-permissions

/config 命令

The /config Command

在对话中使用 /config 命令可以查看和修改部分配置。

bash

# 查看当前配置
> /config

# 配置概览:
配置层级:
  用户级: ~/.claude/settings.json (已加载)
  项目级: .claude/settings.json (已加载)
  本地级: .claude/settings.local.json (未找到)

当前模型: claude-sonnet-4-20250514
权限规则: 12 条 allow, 3 条 deny
MCP 服务器: 2 个已连接

配置调试

Configuration Debugging

常见问题排查

bash

# 检查 API 密钥是否设置
echo $ANTHROPIC_API_KEY

# 检查配置文件是否存在
ls -la ~/.claude/settings.json
ls -la .claude/settings.json
ls -la .claude/settings.local.json

# 验证 JSON 格式
cat ~/.claude/settings.json | python -m json.tool

# 检查 Bedrock 配置
aws sts get-caller-identity  # 验证 AWS 凭据
aws bedrock list-foundation-models --region us-east-1  # 验证模型可用性

# 检查 Vertex 配置
gcloud auth application-default print-access-token  # 验证 GCP 凭据

配置问题自检清单

检查项	命令	期望结果
API 密钥	`echo $ANTHROPIC_API_KEY`	非空
配置格式	`python -m json.tool < settings.json`	无错误
文件权限	`ls -la settings.json`	可读
AWS 凭据	`aws sts get-caller-identity`	正确的账户
GCP 凭据	`gcloud auth list`	正确的账户

小结

Summary

Claude Code 的配置系统设计围绕以下原则：

层级覆盖 - 三层配置从全局到局部逐步细化
安全优先 - deny 规则始终优先于 allow
灵活适配 - 支持多种 API 提供商和部署方式
团队协作 - 项目级配置可共享，本地级配置私有

建议从简单配置开始，根据需要逐步添加更多规则。使用 /config 命令可以随时查看当前生效的配置。

配置系统 ​

settings.json 三个层级 ​

层级结构 ​

用户级配置 ​

项目级配置 ​

本地级配置 ​

配置合并规则 ​

常用配置项 ​

配置项速查表 ​

权限配置示例 ​

MCP 服务器配置 ​

环境变量 ​

核心环境变量 ​

AWS Bedrock 相关 ​

Google Vertex AI 相关 ​

设置环境变量的方式 ​

模型选择配置 ​

命令行参数 ​

对话中切换 ​

快速模式切换 ​

模型选择建议 ​

API Provider 配置 ​

Anthropic Direct（默认） ​

AWS Bedrock ​

Google Vertex AI ​

Provider 对比 ​

配置文件完整示例 ​

个人开发者配置 ​

团队项目配置 ​

CI/CD 配置 ​

/config 命令 ​

配置调试 ​

常见问题排查 ​

配置问题自检清单 ​

小结 ​

配置系统

settings.json 三个层级

层级结构

用户级配置

项目级配置

本地级配置

配置合并规则

常用配置项

配置项速查表

权限配置示例

MCP 服务器配置

环境变量

核心环境变量

AWS Bedrock 相关

Google Vertex AI 相关

设置环境变量的方式

模型选择配置

命令行参数

对话中切换

快速模式切换

模型选择建议

API Provider 配置

Anthropic Direct（默认）

AWS Bedrock

Google Vertex AI

Provider 对比

配置文件完整示例

个人开发者配置

团队项目配置

CI/CD 配置

/config 命令

配置调试

常见问题排查

配置问题自检清单

小结