张雪迎 AI教程 2026-07-27

Claude Code settings.json 完整配置教程

AI 概述

本文详解Claude Code的settings.json配置方案，介绍三层配置文件路径与优先级：用户全局、项目共享、本地临时配置，并区分Git提交规范。讲解环境变量、权限管控、模型等核心字段，提供对接中转服务的完整配置样例。支持配置命令读写权限，可禁止高危操作、保护密钥文件。同时梳理配置不生效、权限弹窗等常见故障，给出实操规范，敏感密钥建议放置全局或本地配置，切勿提交代码仓库。

文章目录隐藏

一、settings.json 是干什么的？
二、配置文件位置（很重要）
三、如何创建和编辑配置文件
四、核心配置项讲解

1. env（环境变量）—— 最常用
2. permissions（权限控制）—— 强烈建议配置
3. model 相关

五、完整配置示例

示例 1：最简可用配置（推荐新手）
示例 2：带权限保护的推荐配置
示例 3：项目级配置（放在项目根目录的 .claude/settings.json）

六、常见问题

七、配置建议总结

很多小伙伴在用 Claude Code 都是直接输命令、裸跑默认配置，要么频繁弹窗授权、要么不小心误删文件、读取敏感配置，踩了一堆坑。还有不少国内小伙伴卡在 API 中转、模型适配、配置不生效这些问题上，网上的教程零散又杂乱，找不全完整的配置规则。

其实 Claude Code 绝大多数使用问题，根源都是没配置好 settings.json。这篇文章我把这套配置文件的层级规则、核心字段、权限管控、国内常用中转方案全部梳理透彻，没有冗余废话，都是实操能用的内容，大家直接对照复制修改，就能搞定全套配置，稳定上手 Claude Code。

一、settings.json 是干什么的？

Claude Code 的行为主要由 settings.json 控制，包括：

使用哪个模型；
API 地址和密钥（支持中转）；
工具权限（允许/禁止执行哪些命令、读哪些文件）；
环境变量；
其他行为偏好。

它比单纯设置环境变量更灵活，也更容易管理。

二、配置文件位置（很重要）

Claude Code 支持多层配置，优先级从高到低如下：

层级	路径	作用范围	是否提交 Git
本地覆盖	`.claude/settings.local.json`	仅当前项目 + 当前机器	否（通常 gitignore）
项目级	`.claude/settings.json`	当前项目（团队共享）	是
用户级	`~/.claude/settings.json`	所有项目（全局）	否

不同系统的用户级路径：

macOS / Linux：~/.claude/settings.json；
Windows：C:\Users\你的用户名\.claude\settings.json。

建议：

个人通用配置写在用户级（~/.claude/settings.json）；
团队统一规范写在项目级（.claude/settings.json）；
临时试验写在 settings.local.json。

三、如何创建和编辑配置文件

打开终端，执行：

# macOS / Linux
mkdir -p ~/.claude
# Windows PowerShell
mkdir $env:USERPROFILE\.claude

创建或编辑文件：

# macOS / Linux
vim ~/.claude/settings.json
# 或者用 VS Code
code ~/.claude/settings.json

Windows 直接用记事本或 VS Code 打开对应路径即可。

推荐在文件最上方加上 schema，编辑器会有自动提示和校验：
```
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}
```

四、核心配置项讲解

1. env（环境变量）—— 最常用

用于配置 API 地址、密钥、模型等。国内用户接中转或国产模型基本都写在这里。

"env": {
  "ANTHROPIC_BASE_URL": "https://你的中转地址",
  "ANTHROPIC_AUTH_TOKEN": "你的 API Key",
  "ANTHROPIC_MODEL": "模型名称"
}

2. permissions（权限控制）—— 强烈建议配置

控制 Claude 能做什么，防止误操作。

"permissions": {
  "allow": [
    "Bash(npm run *)",
    "Bash(git status)",
    "Bash(git diff *)",
    "Read",
    "Edit",
    "Write",
    "Grep",
    "Glob"
  ],
  "deny": [
    "Bash(rm -rf *)",
    "Bash(curl *)",
    "Bash(sudo *)",
    "Read(./.env)",
    "Read(./.env.*)",
    "Read(./secrets/**)"
  ]
}

规则说明：

deny 优先级最高；
支持通配符，比如 Bash(npm run *)；
读敏感文件（.env）建议直接 deny。

3. model 相关

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

也可以配合 env 里的模型变量一起用。

五、完整配置示例

示例 1：最简可用配置（推荐新手）

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的 DeepSeek 密钥",
    "ANTHROPIC_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro"
  }
}

示例 2：带权限保护的推荐配置

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥",
    "ANTHROPIC_MODEL": "deepseek-v4-pro"
  },
  "permissions": {
    "allow": [
      "Bash(npm *)",
      "Bash(pnpm *)",
      "Bash(yarn *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Read",
      "Edit",
      "Write",
      "Grep",
      "Glob"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Bash(sudo *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(~/.ssh/**)"
    ]
  }
}

示例 3：项目级配置（放在项目根目录的 .claude/settings.json）

适合团队统一规范：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(pnpm *)",
      "Bash(npm run *)",
      "Bash(git *)",
      "Read",
      "Edit",
      "Write"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}