Settings 配置体系

是什么

settings 是 Claude Code 的配置核心，通过分层 scope 体系管理个人偏好、项目共享配置和组织强制策略。理解 scope 优先级是正确配置 Claude Code 的基础。

核心机制

四个 Scope（优先级从高到低）

Scope	位置	影响范围	团队共享
Managed	server-managed / plist / registry / managed-settings.json	机器上所有用户	是（IT 部署）
Local	.claude/settings.local.json	仅自己，当前项目	否（gitignore）
Project	.claude/settings.json	所有协作者	是（git 提交）
User	~/.claude/settings.json	自己，所有项目	否

完整优先级：Managed > 命令行参数 > Local > Project > User

Managed Settings 下发机制

• Server-managed：Claude.ai admin console，认证时下发
• MDM/OS 策略：macOS plist（com.anthropic.claudecode）、Windows HKLM 注册表
• File-based：/Library/Application Support/ClaudeCode/managed-settings.json（macOS）、/etc/claude-code/managed-settings.json（Linux）
• Drop-in 目录：managed-settings.d/ 支持多团队独立部署策略片段，按字母顺序合并

settings.json 示例

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "deny": ["Bash(curl *)", "Read(./.env)"]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  },
  "model": "sonnet"
}

Array 设置的合并行为 permissions.allow 和 permissions.deny 跨 scope 合并（不覆盖），开发者可扩展 managed 列表但不能删除其中的条目。

其他配置文件

• ~/.claude.json：OAuth session、MCP server 配置、项目状态、各类缓存
• .mcp.json：项目级 MCP server 配置
• ~/.claude/keybindings.json：快捷键配置

关键细节

• Windows 路径：~/.claude 解析为 %USERPROFILE%\.claude
• 旧版 Windows 路径 C:\ProgramData\ClaudeCode\managed-settings.json 在 v2.1.75 后不再支持，需迁移到 C:\Program Files\ClaudeCode\
• Claude Code 自动为配置文件创建时间戳备份，保留最近 5 个
• /config 命令打开交互式配置界面

与其他概念的关联

• permissions - permissions 配置的详细语法
• server-managed-settings - server-managed 机制详解
• debug-your-config - 配置不生效时的排查方法

实践要点

• 团队共享配置放 .claude/settings.json（提交到 git）
• 个人实验性配置放 .claude/settings.local.json（自动 gitignore）
• 组织强制策略放 managed settings，不可被用户覆盖
• 使用 $schema 字段获得编辑器自动补全支持