Claude Code官方文档配置settings.json

Claude Code 配置完全指南 - settings.json 全局与项目级配置

使用全局和项目级设置以及环境变量配置 Claude Code。

发布于 2025年5月1日 · 阅读约 45 分钟

Claude Code 提供多种设置来配置其行为以满足您的需求。您可以在使用交互式 REPL 时运行 /config 命令来配置 Claude Code，这会打开一个选项卡式设置界面，您可以在其中查看状态信息并修改配置选项。

配置作用域

Claude Code 使用作用域系统来确定配置应用的位置以及与谁共享。了解作用域可以帮助您决定如何为个人使用、团队协作或企业部署配置 Claude Code。

可用作用域

作用域	位置	影响范围	与团队共享？
Managed	服务器管理的设置、plist / 注册表或系统级 `managed-settings.json`	机器上的所有用户	是（由 IT 部署）
User	`~/.claude/` 目录	您，跨所有项目	否
Project	存储库中的 `.claude/`	此存储库上的所有协作者	是（提交到 git）
Local	`.claude/settings.local.json`	您，仅在此存储库中	否（gitignored）

何时使用每个作用域

Managed 作用域用于：

必须在整个组织范围内强制执行的安全策略
无法被覆盖的合规要求
由 IT/DevOps 部署的标准化配置

User 作用域最适合：

您想在任何地方使用的个人偏好设置（主题、编辑器设置）
您在所有项目中使用的工具和插件
API 密钥和身份验证（安全存储）

Project 作用域最适合：

团队共享的设置（权限、hooks、MCP servers）
整个团队应该拥有的插件
跨协作者标准化工具

Local 作用域最适合：

特定项目的个人覆盖
在与团队共享之前测试配置
对其他人不适用的特定于机器的设置

作用域如何相互作用

当在多个作用域中配置相同的设置时，更具体的作用域优先：

Managed（最高）- 无法被任何内容覆盖
命令行参数 - 临时会话覆盖
Local - 覆盖项目和用户设置
Project - 覆盖用户设置
User（最低）- 当没有其他内容指定设置时应用

例如，如果在用户设置中允许某个权限，但在项目设置中拒绝，则项目设置优先，权限被阻止。

哪些功能使用作用域

作用域适用于许多 Claude Code 功能：

功能	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`（每个项目）
Plugins	`~/.claude/settings.json`	`.claude/settings.json`	`.claude/settings.local.json`
CLAUDE.md	`~/.claude/CLAUDE.md`	`CLAUDE.md` 或 `.claude/CLAUDE.md`	`CLAUDE.local.md`

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

设置文件

settings.json 文件是通过分层设置配置 Claude Code 的官方机制：

用户设置在 ~/.claude/settings.json 中定义，适用于所有项目。
项目设置保存在您的项目目录中：
- .claude/settings.json 用于检入源代码管理并与您的团队共享的设置
- .claude/settings.local.json 用于未检入的设置，适用于个人偏好和实验。Claude Code 将在创建 .claude/settings.local.json 时配置 git 以忽略它。
Managed 设置：对于需要集中控制的组织，Claude Code 支持多种 managed 设置的交付机制。所有机制都使用相同的 JSON 格式，无法被用户或项目设置覆盖：
- 服务器管理的设置：通过 Claude.ai 管理员控制台从 Anthropic 的服务器交付。请参阅服务器管理的设置。
- MDM/OS 级别策略：通过 macOS 和 Windows 上的本机设备管理交付：
  - macOS：com.anthropic.claudecode managed preferences 域。plist 的顶级键镜像 managed-settings.json，嵌套设置为字典，数组为 plist 数组。通过 Jamf、Iru (Kandji) 或类似 MDM 工具中的配置文件部署。
  - Windows：HKLM\SOFTWARE\Policies\ClaudeCode 注册表项，带有包含 JSON 的 Settings 值（REG_SZ 或 REG_EXPAND_SZ）（通过组策略或 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\
  ⚠️ 自 v2.1.75 起，不再支持旧的 Windows 路径 C:\ProgramData\ClaudeCode\managed-settings.json。已将设置部署到该位置的管理员必须将文件迁移到 C:\Program Files\ClaudeCode\managed-settings.json。
  
  基于文件的 managed 设置还支持在与 managed-settings.json 相同的系统目录中的 managed-settings.d/ 放入目录。这让独立的团队可以部署独立的策略片段，而无需协调对单个文件的编辑。
  
  遵循 systemd 约定，managed-settings.json 首先作为基础合并，然后放入目录中的所有 *.json 文件按字母顺序排序并合并在顶部。对于标量值，后面的文件覆盖前面的文件；数组被连接和去重；对象被深度合并。以 . 开头的隐藏文件被忽略。
  
  使用数字前缀来控制合并顺序，例如 10-telemetry.json 和 20-security.json。
请参阅 managed 设置和 Managed MCP 配置了解详情。

此存储库包含 Jamf、Iru (Kandji)、Intune 和组策略的启动部署模板。使用这些作为起点并根据您的需求进行调整。

ℹ️ Managed 部署还可以使用 strictKnownMarketplaces 限制插件市场添加。
其他配置存储在 ~/.claude.json 中。此文件包含您的 OAuth 会话、MCP server 配置（用于用户和本地作用域）、每个项目的状态（允许的工具、信任设置）和各种缓存。项目作用域的 MCP servers 单独存储在 .mcp.json 中。

ℹ️ Claude Code 自动创建配置文件的时间戳备份，并保留最近五个备份以防止数据丢失。

{
  "$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 设置的官方 JSON 架构。将其添加到您的 settings.json 可在 VS Code、Cursor 和任何其他支持 JSON 架构验证的编辑器中启用自动完成和内联验证。

已发布的架构会定期更新，可能不包括最近 CLI 版本中添加的设置，因此最近记录的字段上的验证警告不一定意味着您的配置无效。

可用设置

settings.json 支持多个选项。下表列出了关键设置（完整列表请参阅官方文档）：

键	描述	示例
`agent`	将主线程作为命名 subagent 运行。应用该 subagent 的系统提示、工具限制和模型	`"code-reviewer"`
`allowedChannelPlugins`	（仅 Managed 设置）可能推送消息的频道插件的允许列表	`[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]`
`allowedHttpHookUrls`	HTTP hooks 可能针对的 URL 模式的允许列表。支持 `*` 作为通配符	`["https://hooks.example.com/*"]`
`allowedMcpServers`	在 managed-settings.json 中设置时，用户可以配置的 MCP servers 的允许列表	`[{ "serverName": "github" }]`
`allowManagedHooksOnly`	（仅 Managed 设置）仅加载 managed hooks、SDK hooks 和强制启用的插件中的 hooks	`true`
`allowManagedMcpServersOnly`	（仅 Managed 设置）仅尊重来自 managed 设置的 `allowedMcpServers`	`true`
`allowManagedPermissionRulesOnly`	（仅 Managed 设置）防止用户和项目设置定义权限规则	`true`
`alwaysThinkingEnabled`	为所有会话默认启用扩展思考	`true`
`apiKeyHelper`	自定义脚本，在 `/bin/sh` 中执行，以生成身份验证值	`/bin/generate_temp_api_key.sh`
`attribution`	自定义 git 提交和拉取请求的归属	`{"commit": "🤖 Generated with Claude Code", "pr": ""}`
`autoMemoryDirectory`	自动内存存储的自定义目录	`"~/my-memory-dir"`
`autoMemoryEnabled`	启用自动内存	`false`
`autoMode`	自定义自动模式分类器	`{"soft_deny": ["$defaults", "Never run terraform apply"]}`
`autoScrollEnabled`	在全屏渲染中跟随新输出到对话底部	`false`
`autoUpdatesChannel`	遵循更新的发布渠道	`"stable"`
`availableModels`	限制用户可以选择的模型	`["sonnet", "haiku"]`
`awaySummaryEnabled`	在您离开终端几分钟后返回时显示单行会话回顾	`true`
`awsAuthRefresh`	修改 `.aws` 目录的自定义脚本	`aws sso login --profile myprofile`
`awsCredentialExport`	输出包含 AWS 凭证的 JSON 的自定义脚本	`/bin/generate_aws_grant.sh`
`blockedMarketplaces`	（仅 Managed 设置）市场源的阻止列表	`[{ "source": "github", "repo": "untrusted/plugins" }]`
`channelsEnabled`	（仅 Managed 设置）为组织允许 channels	`true`
`claudeMdExcludes`	加载内存时要跳过的 `CLAUDE.md` 文件的 Glob 模式	`["/vendor//CLAUDE.md"]`
`cleanupPeriodDays`	非活跃时间超过此期间的会话在启动时被删除（默认：30 天）	`20`
`companyAnnouncements`	在启动时显示给用户的公告	`["Welcome to Acme Corp!"]`
`defaultShell`	输入框 `!` 命令的默认 shell。接受 `"bash"` 或 `"powershell"`	`"powershell"`
`deniedMcpServers`	在 managed-settings.json 中设置时，明确阻止的 MCP servers 的拒绝列表	`[{ "serverName": "filesystem" }]`
`disableAllHooks`	禁用所有 hooks 和任何自定义状态行	`true`
`disableAutoMode`	设置为 `"disable"` 以防止自动模式被激活	`"disable"`
`disableDeepLinkRegistration`	设置为 `"disable"` 以防止 Claude Code 注册 `claude-cli://` 协议处理程序	`"disable"`
`disabledMcpjsonServers`	要拒绝的 `.mcp.json` 文件中特定 MCP servers 的列表	`["filesystem"]`
`disableRemoteControl`	禁用远程控制	`true`
`disableSkillShellExecution`	禁用 skills 中的内联 shell 执行	`true`
`editorMode`	输入提示的快捷键模式：`"normal"` 或 `"vim"`	`"vim"`
`effortLevel`	跨会话持久化努力级别	`"xhigh"`
`enableAllProjectMcpServers`	自动批准项目 `.mcp.json` 文件中定义的所有 MCP servers	`true`
`enabledMcpjsonServers`	要批准的 `.mcp.json` 文件中特定 MCP servers 的列表	`["memory", "github"]`
`env`	将应用于每个会话的环境变量	`{"FOO": "bar"}`
`fastModePerSessionOptIn`	当为 `true` 时，快速模式不会跨会话持久化	`true`
`feedbackSurveyRate`	概率（0–1）会话质量调查在符合条件时出现	`0.05`
`fileSuggestion`	为 `@` 文件自动完成配置自定义脚本	`{"type": "command", "command": "~/.claude/file-suggestion.sh"}`
`forceLoginMethod`	使用 `claudeai` 限制登录到 Claude.ai 账户，`console` 限制登录到 Claude Console	`claudeai`
`forceLoginOrgUUID`	要求登录属于特定组织	`"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"`
`forceRemoteSettingsRefresh`	（仅 Managed 设置）阻止 CLI 启动，直到从服务器新鲜获取远程 managed 设置	`true`
`gcpAuthRefresh`	当 GCP Application Default Credentials 过期时刷新它们的自定义脚本	`gcloud auth application-default login`
`hooks`	配置自定义命令以在生命周期事件处运行	参见 hooks 文档
`httpHookAllowedEnvVars`	HTTP hooks 可能插入到标头中的环境变量名称的允许列表	`["MY_TOKEN", "HOOK_SECRET"]`
`includeCoAuthoredBy`	已弃用：改用 `attribution`	`false`
`includeGitInstructions`	在 Claude 的系统提示中包含内置提交和 PR 工作流说明	`false`
`language`	配置 Claude 的首选响应语言	`"japanese"`
`minimumVersion`	防止后台自动更新和 `claude update` 安装低于此版本的版本	`"2.1.100"`
`model`	覆盖用于 Claude Code 的默认模型	`"claude-sonnet-4-6"`
`modelOverrides`	将 Anthropic 模型 ID 映射到特定于提供商的模型 ID	`{"claude-opus-4-6": "arn:aws:bedrock:..."}`
`otelHeadersHelper`	生成动态 OpenTelemetry 标头的脚本	`/bin/generate_otel_headers.sh`
`outputStyle`	配置输出样式以调整系统提示	`"Explanatory"`
`parentSettingsBehavior`	（仅 Managed 设置）控制嵌入主机进程提供的 managed 设置如何应用	`"merge"`
`permissions`	请参阅下表了解权限的结构
`plansDirectory`	自定义 Plan Mode 文件的存储位置	`"./plans"`
`pluginTrustMessage`	（仅 Managed 设置）在安装前显示的插件信任警告中附加的自定义消息	`"All plugins from our marketplace are approved by IT"`
`policyHelper`	管理员部署的可执行文件，在启动时动态计算 managed 设置	`{"path": "/usr/local/bin/claude-policy"}`
`preferredNotifChannel`	任务完成和权限提示通知的方法	`"terminal_bell"`
`prefersReducedMotion`	减少或禁用 UI 动画	`true`
`prUrlTemplate`	PR 徽章的 URL 模板	`"https://reviews.example.com/{owner}/{repo}/pull/{number}"`
`respectGitignore`	控制 `@` 文件选择器是否尊重 `.gitignore` 模式	`false`
`showClearContextOnPlanAccept`	在 Plan Mode 接受屏幕上显示”清除上下文”选项	`true`
`showThinkingSummaries`	在交互式会话中显示扩展思考摘要	`true`
`showTurnDuration`	在响应后显示轮次持续时间消息	`false`
`skillOverrides`	按 skill 名称键入的每个 skill 可见性覆盖	`{"legacy-context": "name-only", "deploy": "off"}`
`skipWebFetchPreflight`	跳过 WebFetch 域安全检查	`true`
`spinnerTipsEnabled`	在 Claude 工作时在微调器中显示提示	`false`
`spinnerTipsOverride`	使用自定义字符串覆盖微调器提示	`{ "excludeDefault": true, "tips": ["Use our internal tool X"] }`
`spinnerVerbs`	自定义在微调器中显示的操作动词	`{"mode": "append", "verbs": ["Pondering", "Crafting"]}`
`sshConfigs`	要在桌面环境下拉菜单中显示的 SSH 连接	`[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]`
`statusLine`	配置自定义状态行以显示上下文	`{"type": "command", "command": "~/.claude/statusline.sh"}`
`strictKnownMarketplaces`	（仅 Managed 设置）插件市场源的允许列表	`[{ "source": "github", "repo": "acme-corp/plugins" }]`
`syntaxHighlightingDisabled`	禁用 diffs、代码块和文件预览中的语法高亮	`true`
`teammateMode`	agent team 队友的显示方式	`"in-process"`
`terminalProgressBarEnabled`	在支持的终端中显示终端进度条	`false`
`tui`	终端 UI 渲染器：`"fullscreen"` 或 `"default"`	`"fullscreen"`
`useAutoModeDuringPlan`	Plan Mode 在自动模式可用时是否使用自动模式语义	`false`
`viewMode`	启动时的默认记录视图模式	`"verbose"`
`voice`	语音听写设置	`{ "enabled": true, "mode": "tap" }`
`voiceEnabled`	`voice.enabled` 的旧别名	`true`
`wslInheritsWindowsSettings`	（仅 Windows managed 设置）当为 `true` 时，WSL 上的 Claude Code 也从 Windows 策略链读取 managed 设置	`true`

全局配置设置

这些设置存储在 ~/.claude.json 中，而不是 settings.json。将它们添加到 settings.json 将触发架构验证错误。

ℹ️ v2.1.119 之前的版本也在此处而不是在 settings.json 中存储 autoScrollEnabled、editorMode、showTurnDuration、teammateMode 和 terminalProgressBarEnabled。

键	描述	示例
`autoConnectIde`	当 Claude Code 从外部终端启动时自动连接到运行的 IDE	`true`
`autoInstallIdeExtension`	从 VS Code 终端运行时自动安装 Claude Code IDE 扩展	`false`
`externalEditorContext`	当您使用 `Ctrl+G` 打开外部编辑器时，将 Claude 的上一个响应作为 `#` 注释上下文前置	`true`

Worktree 设置

配置 --worktree 如何创建和管理 git worktrees。

键	描述	示例
`worktree.baseRef`	新 worktrees 分支的参考。`"fresh"`（默认）从 `origin/<default-branch>` 分支。`"head"` 从您当前的本地 `HEAD` 分支	`"head"`
`worktree.symlinkDirectories`	要从主存储库符号链接到每个 worktree 的目录	`["node_modules", ".cache"]`
`worktree.sparsePaths`	通过 git sparse-checkout 在每个 worktree 中检出的目录	`["packages/my-app", "shared/utils"]`

要将 gitignored 文件（如 .env）复制到新的 worktrees，请在项目根目录中使用 .worktreeinclude 文件，而不是设置。

权限设置

键	描述	示例
`allow`	允许工具使用的权限规则数组	`[ "Bash(git diff *)" ]`
`ask`	在工具使用时要求确认的权限规则数组	`[ "Bash(git push *)" ]`
`deny`	拒绝工具使用的权限规则数组	`[ "WebFetch", "Bash(curl *)", "Read(./.env)" ]`
`additionalDirectories`	Claude 有权访问的额外工作目录	`[ "../docs/" ]`
`defaultMode`	打开 Claude Code 时的默认权限模式	`"acceptEdits"`
`disableBypassPermissionsMode`	设置为 `"disable"` 以防止激活 `bypassPermissions` 模式	`"disable"`
`skipDangerousModePermissionPrompt`	跳过通过 `--dangerously-skip-permissions` 进入 bypass permissions 模式前显示的确认提示	`true`

权限规则语法

权限规则遵循 Tool 或 Tool(specifier) 的格式。规则按顺序评估：首先是拒绝规则，然后是询问，最后是允许。第一个匹配的规则获胜。

快速示例：

规则	效果
`Bash`	匹配所有 Bash 命令
`Bash(npm run *)`	匹配以 `npm run` 开头的命令
`Read(./.env)`	匹配读取 `.env` 文件
`WebFetch(domain:example.com)`	匹配对 example.com 的获取请求

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

Sandbox 设置

配置高级 sandboxing 行为。Sandboxing 将 bash 命令与您的文件系统和网络隔离。请参阅沙箱化了解详情。

键	描述	示例
`enabled`	启用 bash sandboxing（macOS、Linux 和 WSL2）。默认：false	`true`
`failIfUnavailable`	如果 `sandbox.enabled` 为 true 但 sandbox 无法启动，则在启动时以错误退出	`true`
`autoAllowBashIfSandboxed`	当 sandboxed 时自动批准 bash 命令。默认：true	`true`
`excludedCommands`	应在 sandbox 外运行的命令	`["docker *"]`
`allowUnsandboxedCommands`	允许命令通过 `dangerouslyDisableSandbox` 参数在 sandbox 外运行	`false`
`filesystem.allowWrite`	sandboxed 命令可以写入的额外路径	`["/tmp/build", "~/.kube"]`
`filesystem.denyWrite`	sandboxed 命令无法写入的路径	`["/etc", "/usr/local/bin"]`
`filesystem.denyRead`	sandboxed 命令无法读取的路径	`["~/.aws/credentials"]`
`filesystem.allowRead`	在 `denyRead` 区域内重新允许读取的路径	`["."]`
`filesystem.allowManagedReadPathsOnly`	（仅 Managed 设置）仅尊重来自 managed 设置的 `filesystem.allowRead` 路径	`true`
`network.allowUnixSockets`	（仅 macOS）sandbox 中可访问的 Unix socket 路径	`["~/.ssh/agent-socket"]`
`network.allowAllUnixSockets`	允许 sandbox 中的所有 Unix socket 连接	`true`
`network.allowLocalBinding`	允许绑定到 localhost 端口（仅 macOS）	`true`
`network.allowMachLookup`	sandbox 可能查找的额外 XPC/Mach 服务名称（仅 macOS）	`["com.apple.coresimulator.*"]`
`network.allowedDomains`	允许出站网络流量的域数组。支持通配符	`["github.com", "*.npmjs.org"]`
`network.deniedDomains`	阻止出站网络流量的域数组	`["sensitive.cloud.example.com"]`
`network.allowManagedDomainsOnly`	（仅 Managed 设置）仅尊重来自 managed 设置的 `allowedDomains`	`true`
`network.httpProxyPort`	如果您想自带代理，使用的 HTTP 代理端口	`8080`
`network.socksProxyPort`	如果您想自带代理，使用的 SOCKS5 代理端口	`8081`
`enableWeakerNestedSandbox`	为无特权 Docker 环境启用较弱的 sandbox（仅 Linux 和 WSL2）	`true`
`enableWeakerNetworkIsolation`	（仅 macOS）允许在 sandbox 中访问系统 TLS 信任服务	`true`
`bwrapPath`	（仅 Managed 设置，Linux/WSL2）bubblewrap 二进制文件的绝对路径	`/opt/admin/bwrap`
`socatPath`	（仅 Managed 设置，Linux/WSL2）`socat` 二进制文件的绝对路径	`/opt/admin/socat`

Sandbox 路径前缀

filesystem.allowWrite、filesystem.denyWrite、filesystem.denyRead 和 filesystem.allowRead 中的路径支持这些前缀：

前缀	含义	示例
`/`	从文件系统根目录的绝对路径	`/tmp/build` 保持 `/tmp/build`
`~/`	相对于主目录	`~/.kube` 变为 `$HOME/.kube`
`./` 或无前缀	相对于项目设置的项目根目录，或相对于用户设置的 `~/.claude`	`./output` 在 `.claude/settings.json` 中解析为 `<project-root>/output`

较旧的 //path 前缀用于绝对路径仍然有效。如果您之前使用单斜杠 /path 期望项目相对解析，请切换到 ./path。此语法与读取和编辑权限规则不同，后者使用 //path 用于绝对和 /path 用于项目相对。Sandbox 文件系统路径使用标准约定：/tmp/build 是绝对路径。

配置示例：

{
  "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 设置（如上所示）：在 OS 级 sandbox 边界处控制路径。这些限制适用于所有子进程命令（例如 kubectl、terraform、npm），而不仅仅是 Claude 的文件工具。
权限规则：使用 Edit 允许/拒绝规则控制 Claude 的文件工具访问，Read 拒绝规则阻止读取，WebFetch 允许/拒绝规则控制网络域。这些规则中的路径也合并到 sandbox 配置中。

归属设置

Claude Code 为 git 提交和拉取请求添加归属。这些分别配置：

提交默认使用 git trailers（如 Co-Authored-By），可以自定义或禁用
拉取请求描述是纯文本

键	描述
`commit`	git 提交的归属，包括任何 trailers。空字符串隐藏提交归属
`pr`	拉取请求描述的归属。空字符串隐藏拉取请求归属

默认提交归属：

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

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

默认拉取请求归属：

🤖 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 设置为空字符串。

文件建议设置

为 @ 文件路径自动完成配置自定义命令。内置文件建议使用快速文件系统遍历，但大型 monorepos 可能受益于项目特定的索引，例如预构建的文件索引或自定义工具。

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

该命令使用与 hooks 相同的环境变量运行，包括 CLAUDE_PROJECT_DIR。它通过 stdin 接收包含 query 字段的 JSON：

{"query": "src/comp"}

将换行符分隔的文件路径输出到 stdout（当前限制为 15）：

src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx

示例：

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

Hook 配置

这些设置控制允许运行哪些 hooks 以及 HTTP hooks 可以访问什么。allowManagedHooksOnly 设置只能在 managed 设置中配置。URL 和环境变量允许列表可以在任何设置级别设置并跨源合并。

当 allowManagedHooksOnly 为 true 时的行为：

加载 Managed hooks 和 SDK hooks
从在 managed 设置 enabledPlugins 中强制启用的插件加载 Hooks。这让管理员通过组织市场分发经过审查的 hooks，同时阻止其他所有内容。信任由完整的 plugin@marketplace ID 授予，因此来自不同市场的同名插件保持被阻止
用户 hooks、项目 hooks 和所有其他插件 hooks 被阻止

限制 HTTP hook URL：

限制 HTTP hooks 可以针对的 URL。支持 * 作为匹配的通配符。定义数组后，针对不匹配 URL 的 HTTP hooks 被静默阻止。主机名匹配不区分大小写，忽略尾部 FQDN 点，匹配 DNS 语义。

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

限制 HTTP hook 环境变量：

限制 HTTP hooks 可以插入到标头值中的环境变量名称。每个 hook 的有效 allowedEnvVars 是其自己列表与此设置的交集。

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

使用策略助手计算 managed 设置

policyHelper 设置指向一个可执行文件，在启动时动态计算 managed 设置，因此管理员可以从设备状态、身份或远程服务而不是静态文件派生策略。从 MDM 或系统 managed-settings.json 文件配置它。Claude Code 在 policyHelper 出现在任何其他作用域时忽略它，包括用户设置、项目设置、HKCU 注册表配置单元和服务器管理的设置。

该设置接受这些键：

键	类型	描述
`path`	string	助手可执行文件的绝对路径
`timeoutMs`	number	在将运行视为失败之前等待助手多长时间
`refreshIntervalMs`	number	在后台重新运行助手的频率。设置为 `0` 以禁用刷新，或至少 `60000`

助手将 JSON 信封写入 stdout。将设置放在 managedSettings 键下而不是顶级，因为裸设置对象解析时 managedSettings 未定义并应用任何内容：

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

当助手发出 managedSettings 时，该对象替换该运行的基于文件的 managed 设置。当助手在启动时以非零状态退出时，Claude Code 打印错误并拒绝启动，因此需要中断恢复的助手应从其自己的缓存提供并以 0 退出。

设置优先级

设置按优先级顺序应用。从最高到最低：

Managed 设置（服务器管理、MDM/OS 级别策略或 managed 设置）
- 由 IT 通过服务器交付、MDM 配置文件、注册表策略或 managed 设置文件部署的策略
- 无法被任何其他级别覆盖，包括命令行参数
- 在 managed 层内，优先级为：server-managed > MDM/OS 级别策略 > 基于文件 > HKCU 注册表（仅 Windows）
命令行参数
- 特定会话的临时覆盖。通过 --settings <file-or-json> 传递的 JSON 使用与其他层相同的规则与基于文件的设置合并
本地项目设置（.claude/settings.local.json）
- 个人项目特定设置
共享项目设置（.claude/settings.json）
- 源代码管理中的团队共享项目设置
用户设置（~/.claude/settings.json）
- 个人全局设置

此层次结构确保组织策略始终被强制执行，同时仍允许团队和个人自定义其体验。无论您从 CLI、VS Code 扩展还是 JetBrains IDE 运行 Claude Code，相同的优先级都适用。

例如，如果您的用户设置允许 Bash(npm run *)，但项目的共享设置拒绝它，则项目设置优先，命令被阻止。

ℹ️ 数组设置跨作用域合并。 当相同的数组值设置（例如 sandbox.filesystem.allowWrite 或 permissions.allow）出现在多个作用域中时，数组被连接和去重，而不是替换。这意味着较低优先级的作用域可以添加条目而不覆盖由较高优先级作用域设置的条目，反之亦然。

验证活跃设置

在 Claude Code 中运行 /status 以查看哪些设置源处于活跃状态以及它们来自何处。输出显示每个配置层（managed、user、project）及其来源，例如 Enterprise managed settings (remote)、Enterprise managed settings (plist)、Enterprise managed settings (HKLM)、Enterprise managed settings (HKCU) 或 Enterprise managed settings (file)。如果设置文件包含错误，/status 会报告问题，以便您可以修复它。

配置系统的关键点

内存文件（CLAUDE.md）：包含 Claude 在启动时加载的说明和上下文
设置文件（JSON）：配置权限、环境变量和工具行为
Skills：可以使用 /skill-name 调用或由 Claude 自动加载的自定义提示
MCP servers：使用额外的工具和集成扩展 Claude Code
优先级：更高级别的配置（Managed）覆盖较低级别的配置（User/Project）
继承：设置被合并，更具体的设置添加到或覆盖更广泛的设置

系统提示

Claude Code 的内部系统提示未发布。要添加自定义说明，请使用 CLAUDE.md 文件或 --append-system-prompt 标志。

排除敏感文件

要防止 Claude Code 访问包含敏感信息（如 API 密钥、secrets 和环境文件）的文件，请在您的 .claude/settings.json 文件中使用 permissions.deny 设置：

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

这替代了已弃用的 ignorePatterns 配置。匹配这些模式的文件被排除在文件发现和搜索结果之外，这些文件上的读取操作被拒绝。

Subagent 配置

Claude Code 支持可在用户和项目级别配置的自定义 AI subagents。这些 subagents 存储为带有 YAML frontmatter 的 Markdown 文件：

用户 subagents：~/.claude/agents/ - 在所有项目中可用
项目 subagents：.claude/agents/ - 特定于您的项目，可与您的团队共享

Subagent 文件定义具有自定义提示和工具权限的专门 AI 助手。在 subagents 文档中了解有关创建和使用 subagents 的更多信息。

插件配置

Claude Code 支持一个插件系统，让您可以使用 skills、agents、hooks 和 MCP servers 扩展功能。插件通过市场分发，可以在用户和存储库级别配置。

插件设置

settings.json 中的插件相关设置：

{
  "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.json）：个人插件偏好
项目设置（.claude/settings.json）：与团队共享的项目特定插件
本地设置（.claude/settings.local.json）：每台机器的覆盖（未提交）
Managed 设置（managed-settings.json）：组织范围的策略覆盖，在所有作用域中阻止安装并从市场隐藏插件

ℹ️ 项目设置优先于用户设置，因此在 ~/.claude/settings.json 中将插件设置为 false 不会禁用项目的 .claude/settings.json 启用的插件。要在您的机器上选择退出项目启用的插件，请改为在 .claude/settings.local.json 中将其设置为 false。

由 managed 设置强制启用的插件无法以这种方式禁用，因为 managed 设置会覆盖本地设置。

示例：

{
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true,
    "experimental-features@personal": false
  }
}

`extraKnownMarketplaces`

定义应为存储库提供的额外市场。通常在存储库级别设置中使用，以确保团队成员有权访问所需的插件源。

当存储库包含 extraKnownMarketplaces 时：

当他们信任文件夹时，团队成员被提示安装市场
然后团队成员被提示从该市场安装插件
用户可以跳过不需要的市场或插件（存储在用户设置中）
安装尊重信任边界并需要明确同意

示例：

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/security/plugins.git"
      }
    }
  }
}

市场源类型：

github：GitHub 存储库（使用 repo）
git：任何 git URL（使用 url）
directory：本地文件系统路径（使用 path，仅用于开发）
hostPattern：正则表达式模式以匹配市场主机（使用 hostPattern）
settings：直接在 settings.json 中声明的内联市场，无需单独的托管存储库（使用 name 和 plugins）

`strictKnownMarketplaces`

仅 Managed 设置：控制用户允许添加和安装插件的插件市场。此设置只能在 managed 设置中配置，为管理员提供对市场源的严格控制。

Managed 设置文件位置：

macOS：/Library/Application Support/ClaudeCode/managed-settings.json
Linux 和 WSL：/etc/claude-code/managed-settings.json
Windows：C:\Program Files\ClaudeCode\managed-settings.json

关键特征：

仅在 managed 设置中可用
无法被用户或项目设置覆盖（最高优先级）
在网络/文件系统操作之前强制执行（被阻止的源永远不会执行）
对源规范使用精确匹配

允许列表行为：

undefined（默认）：无限制 - 用户可以添加任何市场
空数组 []：完全锁定 - 用户无法添加任何新市场
源列表：用户只能添加与之完全匹配的市场

配置示例：

示例：仅允许特定市场：

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    },
    {
      "source": "npm",
      "package": "@acme-corp/compliance-plugins"
    }
  ]
}

示例 - 禁用所有市场添加：

{
  "strictKnownMarketplaces": []
}

管理插件

使用 /plugin 命令以交互方式管理插件：

浏览市场中的可用插件
安装/卸载插件
启用/禁用插件
查看插件详情（提供的 skills、agents、hooks）
添加/删除市场

环境变量

环境变量让您可以控制 Claude Code 行为而无需编辑设置文件。任何变量也可以在 settings.json 中的 env 键下配置，以将其应用于每个会话或将其推出到您的团队。

请参阅环境变量参考了解完整列表。

Claude 可用的工具

Claude Code 可以访问一组用于读取、编辑、搜索、运行命令和编排 subagents 的工具。工具名称是您在权限规则和 hook 匹配器中使用的确切字符串。

请参阅工具参考了解完整列表和 Bash 工具行为详情。

另请参阅

权限：权限系统、规则语法、工具特定模式和 managed 策略
身份验证：设置用户对 Claude Code 的访问
调试您的配置：诊断为什么设置、hook 或 MCP 服务器没有生效
故障排除安装和登录：安装、身份验证和平台问题

本文翻译自 Anthropic Claude Code 官方文档，最近一次同步：2025-05-01。