Claude Code 设置¶

通过全局和项目级配置以及环境变量来定制 Claude Code 的行为。

Claude Code 提供丰富的配置选项来适应不同场景。 运行 /config 命令可以打开标签式设置界面，查看状态信息并修改配置。从 v2.1.181 开始，也可以直接传入 key=value 来修改单个选项而无需打开界面，例如 /config verbose=true。

配置作用域¶

Claude Code 采用分层作用域系统来决定配置的生效范围和共享方式。 理解作用域有助于在个人使用、团队协作和企业部署场景中做出正确的配置选择。

可用作用域¶

各作用域适用场景¶

Managed 作用域 适合：
- 组织级别必须强制执行的安全策略
- 不可被覆盖的合规要求
- 由 IT/DevOps 统一部署的标准化配置

User 作用域 适合：
- 希望在所有项目中生效的个人偏好（主题、编辑器设置）
- 跨项目使用的工具和插件
- API 密钥和认证信息（安全存储）

Project 作用域 适合：
- 团队共享设置（权限、hooks、MCP 服务器）
- 全团队应该使用的插件
- 在协作者之间标准化工具链

Local 作用域 适合：
- 针对特定项目的个人覆盖
- 共享给团队前先测试配置
- 不适用于其他人的机器特定设置

作用域优先级¶

同一配置出现在多个作用域时，按以下优先级从高到低生效：

1. Managed（最高）：不可被任何其他作用域覆盖
2. 命令行参数：临时会话覆盖
3. Local：覆盖 project 和 user 设置
4. Project：覆盖 user 设置
5. User（最低）：仅在其他作用域未指定时生效

例如，如果 user 设置将 spinnerTipsEnabled 设为 true，而 project 设置将其设为 false，则 project 的值生效。权限规则的行为有所不同——它们会跨作用域合并，而非覆盖。

各功能对应的存储位置¶

在 Windows 上，~/.claude 路径解析为 %USERPROFILE%\.claude。

Settings 文件¶

settings.json 是 Claude Code 的官方分层配置机制。

• 用户设置：定义在 ~/.claude/settings.json，应用于所有项目。
• 项目设置：存放在项目目录中：
• .claude/settings.json：提交到版本控制、与团队共享的设置

• .claude/settings.local.json：不提交的设置，适合个人偏好和实验。Claude Code 创建此文件时会自动将 **/.claude/settings.local.json 添加到全局 git excludes 文件（即 git config 中 core.excludesFile 指向的绝对路径或 ~ 路径，否则为 $XDG_CONFIG_HOME/git/ignore 或 ~/.config/git/ignore）；手动创建则需要自行添加到 gitignore。

  此文件定位在 git 仓库根目录，通过 worktree 解析到主 checkout。 这意味着同一仓库的子目录或 worktree 中启动的会话共享一份文件。在三种情况下文件留在启动目录：不在 git 仓库中、仓库根目录是你的 home 目录、以及 Agent SDK 会话。

  v2.1.211 之前，此文件始终保存在启动目录。Claude Code 仍会读取旧版本留下的 .claude/settings.local.json。当两处文件设置了同一个 key 时，仓库根目录的值优先，但两处的权限规则都会生效。

  Claude Code 还会将永久性的"不再询问"权限批准（如 Bash 命令批准）保存到此文件。

  由于此文件属于你个人而非仓库，其 allow 权限规则无需经过 workspace trust 步骤即可生效。 但如果仓库自行提供了该文件（例如提交到了版本控制），则 workspace trust 仍然适用。
  - 托管设置：面向需要集中管控的组织，Claude Code 支持多种下发机制。所有机制使用相同的 JSON 格式，且不可被用户或项目设置覆盖。
  - 其他配置：存储在 ~/.claude.json 中，包含 OAuth 会话、user 和 local 作用域的 MCP 服务器配置、按项目的状态（已允许的工具、信任设置）以及各种缓存。项目作用域的 MCP 服务器单独存储在 .mcp.json 中。

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": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}

示例中的 $schema 行指向 Claude Code settings 的官方 JSON schema。 将此行加入你的 settings.json 可以在 VS Code、Cursor 等支持 JSON schema 校验的编辑器中获得自动补全和内联验证。发布的 schema 定期更新，可能不包含最新 CLI 版本新增的设置，因此对于近期文档化的字段出现校验警告并不一定意味着你的配置无效。

提示：编辑 settings 文件后，在 Claude Code 中运行 /status 确认文件已被加载。Setting sources 行列出了当前会话加载的每个设置来源；来源在至少有一个设置成功加载后才出现，因此 JSON 格式错误的文件即使包含设置也不会出现在列表中。

配置何时生效¶

Claude Code 会监控 settings 文件并在文件变更时热重载，大部分配置修改无需重启即可在当前会话生效。 这涵盖 permissions、hooks、凭证助手（如 apiKeyHelper）等。热重载覆盖 user、project、local 和 managed 设置，每次检测到变更时会触发 ConfigChange hook。

以下配置在会话启动时读取一次，需要重启（或下次启动）才能生效：
- model：会话中可以用 /model 切换
- outputStyle：系统提示词的一部分，在 /clear 或重启时重建

所有可用配置项¶

settings.json 支持以下配置项：

权限配置¶

permissions 对象控制 Claude 可以免确认使用哪些工具。

权限规则使用 ToolName(pattern) 格式，* 为通配符。

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

权限合并规则¶

权限规则与标量设置不同，它们跨作用域合并而非覆盖。 所有作用域的规则会被组合在一起，deny 规则无论来自哪个作用域都优先于 allow 规则。

Hook 配置¶

hooks 设置用于在生命周期事件时运行自定义命令。

• allowedHttpHookUrls：限制 HTTP hooks 可访问的 URL（支持通配符模式）
• httpHookAllowedEnvVars：控制 HTTP hooks 可内插到头部的环境变量
• allowManagedHooksOnly 设为 true 时（仅 Managed），仅 managed hooks、SDK hooks 和 managed enabledPlugins 中强制启用的插件 hooks 被加载，用户和项目的 hooks 被阻止

署名设置¶

attribution 配置自定义 git 提交和 PR 的署名文本。

{
  "attribution": {
    "commit": "🤖 Generated with Claude Code",
    "pr": ""
  }
}

文件建议设置¶

fileSuggestion 为 @ 文件自动补全配置自定义脚本。

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

页脚链接徽章¶

footerLinksRegexes 在正则匹配轮次输出时渲染可点击的页脚徽章。 每个条目包含 pattern（正则）、url 模板（用命名捕获组中的 {name} 占位符填充）和可选 label。仅从 user、--settings 标志和 managed 设置读取。需要 v2.1.176+。

{
  "footerLinksRegexes": [
    {
      "type": "regex",
      "pattern": "\\b(?<key>PROJ-\\d+)\\b",
      "url": "https://issues.example.com/browse/{key}",
      "label": "{key}"
    }
  ]
}

托管设置部署¶

组织可通过多种机制部署不可覆盖的 managed 设置。

文件方式¶

注意：Windows 旧路径 C:\ProgramData\ClaudeCode\managed-settings.json 从 v2.1.75 起不再支持。

Drop-in 目录¶

managed-settings.json 旁的 managed-settings.d/ 目录支持独立策略片段：
- managed-settings.json 作为基础先合并
- 目录中所有 *.json 文件按字母排序后依次合并
- 标量值后覆盖前，数组串联并去重，对象深度合并
- 以 . 开头的隐藏文件被忽略
- 建议使用数字前缀控制顺序：10-telemetry.json、20-security.json

托管 MCP 配置¶

存储为同一系统目录下的 managed-mcp.json。

MDM / 操作系统级策略¶

服务端管理的设置¶

通过 Anthropic 服务器经 Claude.ai 管理控制台下发。

策略助手（Policy Helper）¶

{
  "policyHelper": {
    "path": "/usr/local/bin/claude-policy"
  }
}

管理员部署的可执行文件，在启动时动态计算 managed 设置。仅从 MDM 或系统级 managed-settings.json 中生效（v2.1.136+）。

无效 Managed 设置的行为¶

Managed 设置采用宽容解析策略。 当 managed 配置中某条目未通过 schema 校验时，Claude Code 剥离该条目、记录一条警告，并执行所有剩余有效策略。单个拼写错误不会导致组织策略整体失效。运行 /doctor 可列出被剥离的条目及其来源文件和字段。

此行为在三种交付机制中保持一致：服务端管理的设置、通过 MDM 部署的 plist 和注册表策略、以及 managed-settings.json 文件。需要 Claude Code v2.1.169+。

安全相关字段在值无效时采用安全失败策略（按字段单独处理而非整体剥离）：

requiredMinimumVersion 和 requiredMaximumVersion 采用安全开放策略：无效值被剥离而非强制执行，确保错误的策略推送不会阻止 Claude Code 启动。

校验错误在三个位置呈现：
- 交互式会话在启动时弹出对话框列出无效条目
- 使用 -p 的 headless 运行将摘要打印到 stderr
- claude doctor 列出每个无效条目及其来源和字段

建议在全面部署前，在测试机上运行 claude doctor 验证策略变更。

此宽容策略仅适用于 managed 设置。User、project 和 local 设置文件仍然严格：校验失败的文件会被整体拒绝并报告。

环境变量¶

env 设置中的环境变量应用于每个会话及其所有子进程。

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

常用环境变量参考¶