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 创建此文件时会自动配置 git 忽略它；手动创建则需要自行添加到 gitignore。
• 托管设置：面向需要集中管控的组织，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"
  ]
}

配置何时生效¶

大部分配置修改后会被实时监控并重新加载，无需重启即可生效。 这包括 permissions、hooks、apiKeyHelper 等。

以下配置在会话启动时读取一次，需要重启才能生效：
- 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 设置的行为¶

安全相关字段在值无效时采用安全失败策略：

requiredMinimumVersion 和 requiredMaximumVersion 采用安全开放策略：无效值被剥离而非强制执行。

环境变量¶

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

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

常用环境变量参考¶