.png)
Claude Code 通过一组结构化的配置文件来管理其行为。配置文件分为多个层级，覆盖从个人偏好到团队协作再到企业级管控的不同场景。理解这些文件的作用和存放位置，是高效使用 Claude Code 的第一步。
核心配置文件一览
文件路径总表
配置文件的分层关系
Claude Code 的配置文件是按优先级分层的，高优先级覆盖低优先级：
Managed 层（最高，不可覆盖）
|-- 服务器下发设置（Claude.ai 管理员控制台）
|-- MDM/OS 策略（macOS plist / Windows 注册表）
|-- 系统目录文件（managed-settings.json + managed-settings.d/*.json）
|
命令行参数（临时覆盖）
|-- --settings 传入的 JSON
|
Local 层（个人项目覆盖）
|-- .claude/settings.local.json
|-- CLAUDE.local.md
|
Project 层（团队共享）
|-- .claude/settings.json
|-- .mcp.json
|-- .claude/agents/
|
User 层（最低，个人全局）
|-- ~/.claude/settings.json
|-- ~/.claude/CLAUDE.md
|-- ~/.claude/agents/
|-- ~/.claude.json
关键原则：Managed 设置在任何情况下都不可以被覆盖。数组和权限规则跨层级合并而非替换。标量值则遵循高层覆盖低层的规则。
按使用场景速查
配置文件自动备份
Claude Code 会自动创建配置文件的时间戳备份，并保留最近 5 个备份以防止数据丢失。如果你误改了配置，可以在对应配置文件的同目录下找到 .backup 后缀的备份文件。
以下我们详细介绍配置文件的详细介绍：
1. 配置作用域（Scope）系统
Claude Code 使用四层作用域系统来确定配置应用的位置和共享范围：
何时使用每个作用域
哪些功能使用作用域
💡 Windows 上
~/.claude解析为%USERPROFILE%\\.claude
2. 设置文件详解
2.1 设置文件层级
settings.json 配置层级（优先级从高到低）：
1️⃣ Managed（最高）
├── 服务器管理：Claude.ai 管理员控制台
├── MDM/OS 策略：
│ ├── macOS: com.anthropic.claudecode plist（通过 Jamf/Kandji 部署）
│ ├── Windows: HKLM\SOFTWARE\Policies\ClaudeCode 注册表项
│ └── Windows(用户级): HKCU\SOFTWARE\Policies\ClaudeCode
└── 基于文件：
├── macOS: /Library/Application Support/ClaudeCode/
├── Linux/WSL: /etc/claude-code/
└── Windows: C:\Program Files\ClaudeCode\
2️⃣ 命令行参数（临时会话覆盖）
3️⃣ Local 项目设置
└── .claude/settings.local.json（自动 gitignore）
4️⃣ Project 项目设置
└── .claude/settings.json（提交到 git）
5️⃣ User 用户设置（最低）
└── ~/.claude/settings.json
2.2 Managed 设置的交付机制
对于需要集中管控的组织，Claude Code 支持三种 managed 设置交付方式：
A. 服务器管理设置 — 通过 Claude.ai 管理员控制台从 Anthropic 服务器交付
B. MDM/OS 级别策略：
macOS：
com.anthropic.claudecode域，通过 Jamf、Kandji 等部署 plistWindows：
HKLM\SOFTWARE\Policies\ClaudeCode注册表项，通过组策略/Intune 部署
C. 基于文件 — 部署到系统目录：
macOS：
/Library/Application Support/ClaudeCode/Linux/WSL：
/etc/claude-code/Windows：
C:\Program Files\ClaudeCode\
⚠️ v2.1.75 起旧路径
C:\ProgramData\ClaudeCode\不再支持
Managed 设置还支持放入目录 managed-settings.d/，遵循 systemd 约定：
managed-settings.json先作为基础合并然后
managed-settings.d/*.json按字母顺序排序合并用数字前缀控制顺序，如
10-telemetry.json、20-security.json
2.3 标准 settings.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": [
"欢迎使用 Acme Corp！请查阅 docs.acme.com 的代码规范",
"提醒：所有 PR 必须经过 Code Review",
"新安全策略已生效"
]
}
💡
$schema行指向官方 JSON Schema，在 VS Code/Cursor 中启用自动完成和内联验证
2.4 其他配置文件
~/.claude.json— 存储 OAuth 会话、MCP server 配置（用户/本地作用域）、项目状态、缓存等.mcp.json— 项目作用域的 MCP servers 配置自动备份 — Claude Code 自动创建配置文件的时间戳备份，保留最近 5 个备份
3. 可用设置完整清单
3.1 核心行为设置
3.2 权限与安全设置
3.3 认证与云服务设置
3.4 内存与上下文设置
3.5 模型相关设置
3.6 遥测与监控设置
3.7 UI 与显示设置
3.8 MCP & 插件设置
3.9 Hook 与集成设置
3.10 Skills 设置
3.11 其他 Managed 专用设置
4. 全局配置设置（~/.claude.json）
这些设置存储在 ~/.claude.json 而不是 settings.json 中。
⚠️ v2.1.119 之前的版本在
~/.claude.json中存储autoScrollEnabled、editorMode、showTurnDuration、teammateMode和terminalProgressBarEnabled。新版本已迁移到settings.json。
5. Worktree 设置
配置 --worktree 如何创建和管理 git worktrees。
6. 权限设置
6.1 权限结构
6.2 权限模式
6.3 权限规则语法
规则格式：Tool 或 Tool(specifier)
规则按顺序评估：先 deny（拒绝）→ 再 ask（询问）→ 最后 allow（允许）
第一个匹配的规则获胜
快速示例：
6.4 排除敏感文件
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)",
"Read(./config/credentials.json)",
"Read(./build)"
]
}
}
这会替代已弃用的
ignorePatterns配置
7. Sandbox 设置
Sandboxing 将 bash 命令与文件系统和网络隔离，提供更强的安全保障。
7.1 基本设置
7.2 文件系统限制
7.3 网络限制
7.4 Sandbox 配置示例
{
"sandbox": {
"enabled": true,
"autoAllowBashIfSandboxed": true,
"excludedCommands": ["docker *"],
"filesystem": {
"allowWrite": ["/tmp/build", "~/.kube"],
"denyRead": ["~/.aws/credentials"]
},
"network": {
"allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
"deniedDomains": ["uploads.github.com"],
"allowUnixSockets": ["/var/run/docker.sock"],
"allowLocalBinding": true
}
}
}
8. 归属设置
控制 Claude Code 在 git 提交和 PR 中的归属信息。
{
"attribution": {
"commit": "Generated with AI\n\nCo-Authored-By: AI <[email protected]>",
"pr": ""
}
}
默认值：
提交：🤖 Generated with Claude Code
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
PR： 🤖 Generated with Claude Code
9. 文件建议设置
配置 @ 文件路径自动完成的自定义命令。对大型 monorepo 特别有用。
{
"fileSuggestion": {
"type": "command",
"command": "~/.claude/file-suggestion.sh"
}
}
自定义脚本示例：
#!/bin/bash
query=$(cat | jq -r '.query')
your-repo-file-index --query "$query" | head -20
脚本通过 stdin 接收 {"query": "src/comp"}，将换行符分隔的文件路径输出到 stdout。
10. Hook 配置
Hooks 允许在 Claude Code 的生命周期事件处运行自定义命令。
HTTP Hook URL 限制
{
"allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}
HTTP Hook 环境变量限制
{
"httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}
Managed Hooks Only（仅 Managed 设置）
当 allowManagedHooksOnly: true 时：
仅加载 managed hooks 和 SDK hooks
仅从 managed 设置强制启用的插件中加载 hooks
用户/项目/其他插件 hooks 全部被阻止
11. Subagent 配置
Subagent 是带有自定义提示和工具权限的专门 AI 助手，存储为 Markdown 文件：
用户 subagents：
~/.claude/agents/— 所有项目可用项目 subagents：
.claude/agents/— 特定于项目，可提交 git 共享
Subagent 文件使用 YAML frontmatter 定义系统提示和工具权限。
12. 插件配置
12.1 启用/禁用插件
{
"enabledPlugins": {
"code-formatter@team-tools": true,
"deployment-tools@team-tools": true,
"experimental-features@personal": false
}
}
12.2 添加额外市场源
{
"extraKnownMarketplaces": {
"acme-tools": {
"source": {
"source": "github",
"repo": "acme-corp/claude-plugins"
}
},
"security-plugins": {
"source": {
"source": "git",
"url": "https://git.example.com/security/plugins.git"
}
}
}
}
支持的市场源类型：
12.3 Managed 市场限制
仅 Managed 设置 — strictKnownMarketplaces：
undefined（默认）：无限制[]：完全锁定，用户无法添加任何市场源列表：用户只能添加完全匹配的市场
{
"strictKnownMarketplaces": [
{ "source": "github", "repo": "acme-corp/approved-plugins" },
{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }
]
}
13. 设置优先级
优先级顺序（从高到低）
1️⃣ Managed 设置（最高，不可覆盖）
├── 服务器管理 > MDM/OS 策略 > 基于文件（managed-settings.d + managed-settings.json）
└── Managed 层内只用一个源，源之间不合并
2️⃣ 命令行参数（临时覆盖）
└── --settings 传入的 JSON 覆盖下层
3️⃣ Local 项目设置（.claude/settings.local.json）
└── 个人覆盖
4️⃣ Project 项目设置（.claude/settings.json）
└── 团队共享
5️⃣ User 用户设置（~/.claude/settings.json）
└── 个人全局偏好（最低）
关键规则
标量值（string/number/boolean）：高层覆盖低层
数组值：跨作用域合并（concatenate + deduplicate），不替换
权限规则：跨作用域合并，不是覆盖
Managed 设置：任何情况下都不可以被覆盖
验证活跃设置
在 Claude Code 中运行 /status 查看当前活跃的设置源。Setting sources 行列出已加载的每一层。
14. 环境变量
环境变量可在 settings.json 的 env 字段中配置，以应用于每个会话或推送给团队。
{
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
"OTEL_METRICS_EXPORTER": "otlp",
"CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1"
}
}
详见环境变量参考文档。
15. 常用配置模板
15.1 个人开发者入门配置
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm *)",
"Bash(git *)",
"Bash(pnpm *)",
"Bash(yarn *)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)",
"Bash(rm -rf *)",
"Bash(curl *)"
]
},
"editorMode": "normal",
"language": "chinese",
"awaySummaryEnabled": true,
"showTurnDuration": true
}
15.2 团队项目配置（.claude/settings.json）
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm run test *)",
"Bash(npm run lint)",
"Bash(npm run build)",
"Bash(git *)"
],
"ask": [
"Bash(npm run deploy *)",
"Bash(git push origin main)"
],
"deny": [
"Read(./.env*)",
"Read(./**/secrets/**)",
"Bash(terraform apply *)"
],
"additionalDirectories": ["../shared-lib/"]
},
"env": {
"NODE_ENV": "development"
}
}
15.3 企业 Managed 配置（managed-settings.json）
{
"permissions": {
"deny": [
"Bash(curl *)",
"Bash(wget *)",
"Bash(ssh *)",
"Read(//etc/shadow)",
"Read(//etc/passwd)"
]
},
"allowManagedPermissionRulesOnly": true,
"allowManagedMcpServersOnly": true,
"channelsEnabled": true,
"claudeMd": "Always run \`make lint\` before committing. All code must pass security scan.",
"companyAnnouncements": [
"欢迎！请遵守公司代码规范。",
"安全提示：不要将 API 密钥提交到 Git。"
],
"strictKnownMarketplaces": [
{ "source": "github", "repo": "acme-corp/official-plugins" }
],
"disableAutoMode": "disable",
"forceLoginOrgUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
15.4 Sandbox 安全配置
{
"sandbox": {
"enabled": true,
"failIfUnavailable": true,
"autoAllowBashIfSandboxed": false,
"allowUnsandboxedCommands": false,
"filesystem": {
"allowWrite": ["/tmp"],
"denyRead": [
"/etc",
"~/.ssh",
"~/.aws",
"~/.config/gcloud"
]
},
"network": {
"allowedDomains": [
"github.com",
"*.npmjs.org",
"registry.npmjs.org",
"api.anthropic.com"
],
"allowLocalBinding": false
}
}
}
15.5 VS Code / JetBrains 用户配置
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"editorMode": "normal",
"viewMode": "default",
"autoScrollEnabled": true,
"terminalProgressBarEnabled": true,
"syntaxHighlightingDisabled": false,
"spinnerTipsEnabled": false,
"prefersReducedMotion": false
}
（对应 ~/.claude.json 中配置：）
{
"autoConnectIde": true,
"autoInstallIdeExtension": true,
"externalEditorContext": true
}