Claude Code settings.json 配置指南：作用域、文件路径与常见设置 #

Claude Code 通过分层配置系统管理行为：用户级配置放在 ~/.claude/settings.json 影响所有项目，项目级 .claude/settings.json 提交 git 后团队共享，本地级 .claude/settings.local.json 仅限当前机器且不提交。企业托管配置（managed-settings.json）优先级最高且不可被用户覆盖。运行 /status 可快速查看当前会话加载了哪些配置来源。本文先说明各配置文件的选址和优先级，再依次列出权限、模型、沙箱、插件等常用配置项。

配置作用域 #

Claude Code 使用分层配置系统，不同位置的配置影响不同范围：

三种文件选哪个 #

• 用户级：自己常用的主题、跨项目的设置，不需要共享。
• 项目级：团队统一的权限规则、Hooks、MCP 服务器，需要所有人生效。
• 本地级：个人本地测试、不想影响团队的临时覆盖。

优先级（从高到低） #

1. 托管设置（不可被任何其他设置覆盖）
2. 命令行参数（临时会话覆盖）
3. 本地项目设置（.claude/settings.local.json）
4. 共享项目设置（.claude/settings.json）
5. 用户设置（~/.claude/settings.json）

数组类型的设置合并：当同一数组键（如 permissions.allow 或 sandbox.filesystem.allowWrite）在多个作用域中同时出现时，数组会进行拼接并去重，而不是用高优先级完全替换低优先级内容。

各作用域适用的配置类型 #

Windows 上 ~/.claude 对应 %USERPROFILE%\.claude。

配置文件详解 #

settings.json 文件结构 #

正式的配置机制是通过 settings.json 文件：

• 用户设置 ~/.claude/settings.json：所有项目生效。
• 项目设置 .claude/settings.json：提交到版本控制，团队共享。
• 本地项目设置 .claude/settings.local.json：不提交，适合个人偏好。Claude Code 会自动将其加入 .gitignore。
• 托管设置：企业通过服务器、MDM 或文件系统下发，格式与普通 settings.json 相同。

托管设置的部署方式：

• 服务器托管：通过 Claude.ai 管理后台下发，见服务器托管设置。
• MDM/OS 策略：
  • macOS：com.anthropic.claudecode 受管偏好域，通过配置描述文件部署（Jamf、Kandji 等）。
  • Windows：HKLM\SOFTWARE\Policies\ClaudeCode 注册表键，值 Settings 为 JSON 字符串（组策略或 Intune）。
  • Windows（用户级）：HKCU\SOFTWARE\Policies\ClaudeCode（最低策略优先级）。
• 文件系统：managed-settings.json 和 managed-mcp.json 部署到系统目录：
  • macOS：/Library/Application Support/ClaudeCode/
  • Linux 和 WSL：/etc/claude-code/
  • Windows：C:\Program Files\ClaudeCode\

旧版 Windows 路径 C:\ProgramData\ClaudeCode\managed-settings.json 自 v2.1.75 起不再支持，需迁移到新路径。

托管文件也支持 managed-settings.d/ 目录，放入多个 JSON 文件（按字母顺序合并）。例如使用数字前缀控制合并顺序：10-telemetry.json、20-security.json。合并规则：基本文件作为基础，drop-in 文件按字母顺序覆盖，标量值后覆盖前，数组拼接去重，对象深度合并。

详细内容见托管设置和托管 MCP 配置。

企业还可以通过 strictKnownMarketplaces 限制插件市场来源，见托管市场限制。

其他配置：OAuth 会话、MCP 服务器配置（用户和本地作用域）、项目信任状态等存储在 ~/.claude.json。项目级 MCP 服务器单独存在 .mcp.json。

Claude Code 自动创建配置文件的带时间戳备份，最多保留五份。

示例 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 行可在 VS Code 等编辑器中获得自动补全和内联验证。Schema 可能落后于最新 CLI 版本，偶尔的验证警告未必表示配置无效。

配置项的生效时机 #

Claude Code 会监控 settings 文件的变化，大多数键修改后立即生效，无需重启会话。包括 permissions、hooks、apiKeyHelper 等。修改会触发 ConfigChange 钩子。

以下键在会话启动时读取，需要在下次重启后才生效：

• model：使用 /model 可在会话中切换。
• outputStyle：属于系统提示的一部分，重启或执行 /clear 后重新构建。

全部可用设置项 #

全局配置项（存储在 ~/.claude.json） #

注意：这些键存储在 ~/.claude.json 而非 settings.json，直接添加到 settings.json 会触发 schema 验证错误。

Worktree 设置 #

要复制 gitignore 文件（如 .env）到新 worktree，使用项目根目录的 .worktreeinclude 文件 而不是设置项。

权限设置 #

权限规则语法 #

权限规则格式：Tool 或 Tool(specifier)。规则按顺序评估：先拒绝规则，再询问规则，最后允许规则。第一个匹配的规则生效。

快速示例：

完整的规则语法参考，包括通配符行为、特定工具模式（Read、Edit、WebFetch、MCP、Agent）以及 Bash 模式的安全限制，见权限规则语法。

沙箱设置 #

沙箱隔离 Bash 命令的文件系统和网络访问。见沙箱详情。

沙箱路径前缀 #

与 Read 和 Edit 权限规则不同，沙箱文件系统路径使用标准约定：/tmp/build 是绝对路径，./path 是项目相对路径。

沙箱配置示例：

{
  "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
    }
  }
}

文件系统和网络限制有两种配置方式，它们会被合并：

• sandbox.filesystem 设置：在操作系统沙箱边界控制路径。适用于所有子进程命令（如 kubectl、terraform、npm），不仅仅是 Claude 的文件工具。
• 权限规则：使用 Edit 允许/拒绝规则控制 Claude 文件工具访问，Read 拒绝规则阻止读取，WebFetch 允许/拒绝规则控制网络域名。这些规则中的路径也会合并到沙箱配置中。

归因设置 #

Claude Code 会自动添加 git 提交和 PR 的归因信息。提交默认使用 git trailers（如 Co-Authored-By），PR 描述为纯文本。

默认提交归因：

🤖 Generated with [Claude Code](https://claude.com/claude-code)

   Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

默认 PR 归因：

🤖 Generated with [Claude Code](https://claude.com/claude-code)

示例：

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
    "pr": ""
  }
}

attribution 设置优先于已废弃的 includeCoAuthoredBy。要隐藏所有归因，将 commit 和 pr 都设为空字符串。

文件建议设置 #

自定义 @ 文件路径自动补全命令：

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

命令通过 stdin 接收 JSON（例如 {"query": "src/comp"}），在 stdout 输出换行分隔的文件路径（最多15条）。

示例脚本：

#!/bin/bash
query=$(cat | jq -r '.query')
your-repo-file-index --query "$query" | head -20

Hook 配置 #

这些设置控制哪些钩子允许运行以及 HTTP 钩子可以访问什么。

allowManagedHooksOnly 为 true 时的行为：

• 加载托管钩子和 SDK 钩子。
• 加载托管设置 enabledPlugins 中强制启用的插件钩子。
• 用户钩子、项目钩子和所有其他插件钩子被阻止。

限制 HTTP 钩子 URL：使用 allowedHttpHookUrls。支持 * 通配符，域名匹配不区分大小写且忽略末尾 FQDN 点。

{
  "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}

限制 HTTP 钩子环境变量：使用 httpHookAllowedEnvVars。每个钩子的有效 allowedEnvVars 是其自身列表与此设置的交集。

{
  "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}

使用策略助手计算托管设置 #

policyHelper 指向一个可执行文件，启动时计算托管设置。只能从 MDM 或系统 managed-settings.json 中配置。其他作用域（包括用户设置、项目设置、HKCU 注册表、服务器托管设置）中忽略此键。

助手向 stdout 写入 JSON 信封。设置应放在 managedSettings 键下：

{
  "managedSettings": {
    "permissions": { "deny": ["Read(//etc/secrets/**)"] }
  },
  "claudeMd": "# Organization context\n...",
  "appendSystemPrompt": "Always cite the internal style guide."
}

当助手退出码非零时，Claude Code 打印错误并拒绝启动。需要高可靠性的助手应自行缓存并退出码 0。

设置优先级 #

从最高到最低：

1. 托管设置（服务器托管、MDM/OS 策略、文件系统托管）。同一层级内优先级：服务器托管 > MDM/OS 策略 > 文件系统（managed-settings.d/*.json + managed-settings.json）> HKCU（仅 Windows）。注意托管层内不合并，只使用一个来源。
2. 命令行参数：临时会话覆盖。通过 --settings <file-or-json> 传入的 JSON 与文件设置合并，同层覆盖的高优先级。
3. 本地项目设置（.claude/settings.local.json）
4. 共享项目设置（.claude/settings.json）
5. 用户设置（~/.claude/settings.json）

数组跨作用域合并：当同一数组值设置（如 sandbox.filesystem.allowWrite 或 permissions.allow）出现在多个作用域时，数组会被拼接去重，而不是被高优先级完全替换。

验证当前设置 #

在 Claude Code 中运行 /status，Status 标签页会列出当前会话加载的所有设置来源。如果设置了托管设置，会显示交付渠道（如 Enterprise managed settings (remote)、(plist)、(HKLM)、(HKCU)、(file)）。如果某个来源没有任何键，则不会显示。Config 标签页是一个编辑器，仅用于一组固定的开关（如主题、详细输出），并非查看 settings.json 内容。如果 settings 文件包含错误（如无效 JSON 或验证失败的值），/status 会报告问题。

排除敏感文件 #

使用 permissions.deny 阻止 Claude Code 读取敏感文件：

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Read(./build)"
    ]
  }
}

这会替代已废弃的 ignorePatterns 配置。

子代理配置 #

子代理存储为带 YAML frontmatter 的 Markdown 文件：

• 用户子代理：~/.claude/agents/，跨项目可用。
• 项目子代理：.claude/agents/，项目特定，可共享。

详情见子代理文档。

插件配置 #

插件系统通过市场分发技能、代理、钩子和 MCP 服务器。插件配置示例：

{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  }
}

enabledPlugins #

控制哪些插件启用。格式："plugin-name@marketplace-name": true/false。

• 用户设置/项目设置/本地设置：按优先级覆盖。
• 托管设置：组织级策略覆盖，阻止所有作用域的安装并隐藏插件。

项目设置优先级高于用户设置。要退出项目启用的插件，在 .claude/settings.local.json 中设为 false。托管设置强制启用的插件无法被禁用。

extraKnownMarketplaces #

定义额外的插件市场。通常在仓库级设置中使用，确保团队成员都可访问需要的插件来源。

市场来源类型：

• github：GitHub 仓库 (repo)
• git：任意 git URL (url)
• directory：本地文件系统路径 (path，仅开发)
• hostPattern：正则表达式匹配市场主机 (hostPattern)
• settings：直接在 settings.json 中声明的内联市场 (name、plugins)
• file：本地文件系统路径指向 marketplace.json
• url：URL 指向 marketplace.json
• npm：npm 包 (package)

每个市场条目可选 autoUpdate 布尔值。官方市场默认 true，其他 false。

strictKnownMarketplaces #

（仅托管设置）控制用户可添加和安装插件的市场来源。白名单行为：

• undefined（默认）：无限制
• 空数组 []：完全锁定
• 列表：只能添加精确匹配的市场

使用精确匹配（包括 ref、path）。hostPattern 和 pathPattern 使用正则匹配。

配置示例：允许特定市场、禁用所有市场、允许内部 git 服务器等。

比较 strictKnownMarketplaces 与 extraKnownMarketplaces #

strictPluginOnlyCustomization #

（仅托管）阻止技能、代理、钩子和 MCP 服务器来自用户和项目源，只能来自插件或托管设置。值可以是 true（锁定全部）或数组（只锁定列出的表面）。需 v2.1.82+。

管理插件 #

使用 /plugin 命令交互式管理。

环境变量 #

环境变量可以控制 Claude Code 行为而无需编辑配置文件。所有变量也可以在 settings.json 的 env 键中配置。完整列表见环境变量参考。

系统提示 #

Claude Code 的内部系统提示不公开。要添加自定义指令，使用 CLAUDE.md 文件或 --append-system-prompt 标志。

参见 #

• 权限：权限系统、规则语法、工具特定模式、托管策略。
• 认证：设置用户访问。
• 调试配置：诊断设置、钩子或 MCP 服务器不生效的原因。
• 安装与登录故障排除：安装、认证和平台问题。

常见问题 #

Claude Code 配置放哪个文件？settings.json、settings.local.json 和 managed-settings.json 有什么区别？ #

用户级配置放在 ~/.claude/settings.json，影响所有项目。项目级配置放在 .claude/settings.json，可提交到 git 与团队共享。本地级配置放在 .claude/settings.local.json，仅影响当前机器且不提交。企业托管配置通过 managed-settings.json 文件或 MDM 部署，优先级最高且不可被用户覆盖。

为什么我的 settings.json 配置不生效？如何排查？ #

先运行 /status 查看实际加载了哪些设置来源。检查当前工作目录是否项目根目录（否则项目设置不会加载）。确认 .claude/settings.local.json 是否覆盖了你想要的值。检查启动命令是否带了 --permission-mode 或 --model 等临时参数。如果企业部署了托管设置，某些配置可能被强制覆盖。修改后重启会话或 IDE 插件。

如何让团队共享 Claude Code 的权限规则和 MCP 配置？ #

将权限规则（permissions.allow/deny）、MCP 服务器白名单（enableAllProjectMcpServers 或 enabledMcpjsonServers）、钩子（hooks）等写入项目根目录的 .claude/settings.json 并提交到 git。个人本地覆盖应使用 .claude/settings.local.json。如果需要企业级统一管控，使用 managed-settings.json 部署托管设置。