claude code 的setting文件详解

一、Claude Code settings 配置分级规则（全局 + 项目两级）

不是必须每个项目新建配置，分 2 级配置，优先级：项目本地 > 全局配置

1. 全局配置（全 Mac 所有项目共用）
   路径：~/.claude/settings.json，所有 Java / 其他项目默认继承这份配置（模型、API、权限、读取规则统一生效）
2. 项目级配置（仅当前项目生效，覆盖全局）
   在单个 Java 项目根目录新建文件夹 .claude/，下放：

• settings.json：项目公共配置（可提交 Git）
• settings.local.json：私有配置（API 密钥、私密配置，必须写入.gitignore 禁止提交代码仓库） 

✅ 优先级：

 

项目/.claude/settings.local.json > 项目/.claude/settings.json > ~/.claude/settings.json(全局)

二、配置能干两件核心事：① 指定大模型 ② 控制文件读取 / 操作权限

1. 模型配置：自定义默认使用 DeepSeek / 原生 Claude 任意模型

通过env环境变量字段固定模型；

2. 权限配置：allowed_paths / denied_paths 管控 AI 能读哪些代码、禁止访问配置 / 密钥文件

• allowed_paths：白名单，AI 仅能读取配置目录内代码
• denied_paths：黑名单，禁止读取 yml 密钥、配置文件、敏感资源

三、实战场景：中通财务 NC 会计引擎项目（finance-nc-accounting-engine）

 

需求：

 

1. 全局默认用 deepseek-v4-flash 免费模型；
2. 本财务项目单独指定付费 deepseek-v4-pro [1m]；
3. 限制 AI：只允许读取 src 业务代码，禁止读取 resources 下数据库密钥 yml、配置文件，禁止读取本地环境变量配置；
4. API 密钥统一放在项目 settings.local.json（不上传 Git）

 

 

1、项目完整目录结构（Java Maven 多模块项目）

finance-nc-accounting-engine/           # 项目根目录
├── .claude/                            # 项目专属Claude配置文件夹
│   ├── settings.json                   # 项目通用配置(模型/读写白名单，可提交git)
│   └── settings.local.json              # 私有配置(API KEY，禁止提交git)
├── .gitignore                          # 配置忽略 .claude/settings.local.json
├── pom.xml                             # 父工程pom
├── finance-nc-accounting-engine-core/   # core核心模块
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/zto/...            # Java业务代码（白名单：允许AI读取）
│       └── resources/                  # 黑名单：禁止读取数据库配置yml
│           ├── application.yml
│           ├── db-config.yml  # 含数据库账号密码，禁止AI访问
│           └── secret.properties
├── finance-nc-accounting-engine-task/   # 定时任务模块
│   ├── pom.xml
│   └── src/
└── README.md

 

.gitignore 补充配置（关键：避免密钥上传）

# Claude私有密钥配置，禁止提交
.claude/settings.local.json

2、文件 1：项目 /.claude/settings.json（通用配置，可提交 Git，指定模型 + 读写权限）

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    // 当前项目强制使用 deepseek-v4-pro[1m]，覆盖全局默认flash
    "ANTHROPIC_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-v4-flash",
    "CLAUDE_CODE_EFFORT_LEVEL": "max"
  },
  // 权限规则：白名单：AI仅能访问src源码目录
  "allowed_paths": [
    "./finance-nc-accounting-engine-core/src",
    "./finance-nc-accounting-engine-task/src"
  ],
  // 黑名单：禁止读取配置、密钥文件
  "denied_paths": [
    "**/resources/*.yml",
    "**/resources/*.properties",
    "**/*.env",
    "./.claude/settings.local.json"
  ],
  // 额外限制：禁止AI执行rm/删除类高危shell命令
  "denied_commands": ["rm", "rm -rf", "drop table"]
}

3、文件 2：项目 /.claude/settings.local.json（私有密钥，不上 Git）

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-f52e0xxxxxxxxxxxxgc42"
  }
}

4、全局配置～/.claude/settings.json（所有新项目默认配置） 

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    // 全局默认免费flash模型，新项目没项目配置就用这个
    "ANTHROPIC_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-v4-flash"
  }
}

四、配置生效逻辑说明 

1. 当前财务项目：优先读取项目/.claude/settings.json+local → 使用deepseek-v4-pro[1m]付费模型，AI 只能看 src 源码、碰不到 yml 密钥；
2. 新建另一个全新 Java 项目（无项目.claude 文件夹）：自动继承全局配置，默认deepseek-v4-flash免费模型；
3. 如果新项目想换回 pro：在新项目根目录新建.claude/settings.json覆写模型参数即可。

五、权限效果验证

当你在项目执行：分析一下这个项目架构

• ✅ AI 正常读取所有 src 下 Java 代码、Service、Mapper；
• ❌ AI 无法读取resources/db-config.yml里数据库账号密码，无法查看密钥配置，规避隐私泄露；
• ❌ AI 无法执行危险删除 shell 指令。

六、补充快捷操作 Mac 终端 

# 打开当前项目claude配置目录
open .claude
# 编辑全局配置
code ~/.claude/settings.json