Claude Code 的配置不是一个文件，而是一套 scope 系统。理解 Managed、User、Project、Local 四级配置，才能避免"为什么我的 settings 不生效"这类问题。
四种配置作用域
| Scope | 位置 | 影响谁 | 是否团队共享 |
|---|---|---|---|
| Managed | 系统级或服务器托管 | 机器上所有用户 | 是，由 IT 部署 |
| User | ~/.claude/ | 你，所有项目 | 否 |
| Project | .claude/ | 仓库所有协作者 | 是，提交到 Git |
| Local | .claude/settings.local.json | 你，当前仓库 | 否，gitignore |
什么时候用哪个？
Managed
适合组织强制策略：
- 安全策略
- 合规要求
- 禁止某些工具或命令
- 统一插件市场限制
- 企业级 MCP 配置
Managed 不能被用户或项目覆盖。
User
适合个人全局偏好：
- 主题
- 常用插件
- 全局 MCP 工具
- 个人编辑器偏好
- 跨项目通用设置
Project
适合团队共享配置：
- 项目权限规则
- 项目 Hooks
- 项目 MCP server
- 团队统一插件
- 仓库级标准配置
Local
适合个人实验和机器相关配置：
- 本地数据库 URL
- 个人 allow/deny 调整
- 本地调试变量
- 临时测试配置
优先级顺序
从高到低：
- Managed：最高，无法覆盖
- Command line arguments：当前会话临时覆盖
- Local：覆盖 Project 和 User
- Project：覆盖 User
- User：最低默认值
例子：
- User 设置
spinnerTipsEnabled: true - Project 设置
spinnerTipsEnabled: false
最终生效：false
但注意：权限规则不是简单覆盖，而是跨 scope 合并。这也是很多配置排查的关键。
Settings 文件位置
text
~/.claude/settings.json # User settings
.claude/settings.json # Project settings，提交到 Git
.claude/settings.local.json # Local settings，不提交Managed 文件位置：
text
macOS: /Library/Application Support/ClaudeCode/
Linux: /etc/claude-code/
Windows: C:\Program Files\ClaudeCode\文件名通常是：
managed-settings.jsonmanaged-mcp.json
settings.json 示例
json
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test *)",
"Read(~/.zshrc)"
],
"deny": [
"Bash(curl *)",
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
]
},
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
"OTEL_METRICS_EXPORTER": "otlp"
},
"companyAnnouncements": [
"Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
"Reminder: Code reviews required for all PRs"
]
}建议保留 $schema，可以让 VS Code、Cursor 等编辑器提供补全和校验。
哪些功能受 scope 影响？
| 功能 | User 位置 | Project 位置 | Local 位置 |
|---|---|---|---|
| Settings | ~/.claude/settings.json | .claude/settings.json | .claude/settings.local.json |
| Subagents | ~/.claude/agents/ | .claude/agents/ | 无 |
| MCP servers | ~/.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/CLAUDE.md | CLAUDE.local.md |
Managed settings 的部署方式
企业可以用三种方式部署：
- Server-managed settings：通过 Claude.ai admin console 下发
- MDM/OS policies：macOS plist、Windows registry
- File-based：系统目录下的
managed-settings.json
macOS MDM：com.anthropic.claudecode managed preferences domain。
Windows：HKLM\SOFTWARE\Policies\ClaudeCode，Settings 值存 JSON。
文件式部署支持 drop-in 目录：
text
managed-settings.json
managed-settings.d/
10-telemetry.json
20-security.json合并规则：
- 基础文件先加载
- drop-in 按文件名排序合并
- scalar 后者覆盖前者
- array 拼接并去重
- object 深度合并
团队最佳实践
项目仓库提交 .claude/settings.json
json
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm test *)",
"Bash(npm run lint)",
"Bash(git status)",
"Bash(git diff *)",
"Bash(gh pr view *)"
],
"deny": [
"Read(./.env*)",
"Read(./secrets/**)",
"Bash(git push --force*)",
"Bash(rm -rf *)"
]
}
}个人配置放 settings.local.json
json
{
"env": {
"DATABASE_URL": "postgresql://localhost:5432/myapp_dev"
},
"permissions": {
"allow": [
"Bash(npm run dev)",
"Bash(open http://localhost:3000)"
]
}
}gitignore
gitignore
.claude/settings.local.json
CLAUDE.local.md排查配置不生效
- 运行
/config查看当前设置 - 运行
/doctor检查配置和 MCP 状态 - 确认是否被 Managed 覆盖
- 检查 Local 是否覆盖 Project
- 权限规则注意是合并，不是普通覆盖
- 检查 JSON schema 是否报错
来源：Claude Code 官方文档 - Settings | 整理：ClaudeEagle