Claude Code 设置

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

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

配置范围

Claude Code 使用范围系统来确定配置的适用位置和共享对象。了解范围有助于你决定如何为个人使用、团队协作或企业部署配置 Claude Code。

可用范围

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

何时使用每个范围

托管范围适用于：

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

用户范围最适合：

你到处都想要的个人偏好（主题、编辑器设置）
你跨所有项目使用的工具和插件
API 密钥和认证（安全存储）

项目范围最适合：

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

本地范围最适合：

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

范围如何交互

当同一设置出现在多个范围中时，Claude Code 按优先级顺序应用：

托管（最高）- 不能被任何东西覆盖
命令行参数 - 临时会话覆盖
本地 - 覆盖项目和用户设置
项目 - 覆盖用户设置
用户（最低）- 当没有其他指定时应用

例如，如果你的用户设置将 spinnerTipsEnabled 设为 true，项目设置将其设为 false，则项目值适用。权限规则表现不同，因为它们跨范围合并而非覆盖。

什么使用范围

功能	用户位置	项目位置	本地位置
设置	`~/.claude/settings.json`	`.claude/settings.json`	`.claude/settings.local.json`
子 Agent	`~/.claude/agents/`	`.claude/agents/`	无
MCP 服务器	`~/.claude.json`	`.mcp.json`	`~/.claude.json`（按项目）
插件	`~/.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 在创建时会配置 git 忽略 .claude/settings.local.json。
托管设置：对于需要集中控制的组织，Claude Code 支持多种交付机制：
- 服务器管理的设置：通过 Claude.ai 管理控制台从 Anthropic 服务器交付。
- MDM/操作系统级策略：通过 macOS 和 Windows 上的原生设备管理交付：
  - macOS：com.anthropic.claudecode 托管偏好域
  - Windows：HKLM\SOFTWARE\Policies\ClaudeCode 注册表项
  - 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.json 旁边的同一系统目录中的 managed-settings.d/ 插入目录。
  遵循 systemd 约定，managed-settings.json 首先作为基础合并，然后插入目录中的所有 *.json 文件按字母顺序排序并合并到上面。后面的文件覆盖标量值的前面文件；数组被连接并去重；对象被深度合并。以 . 开头的隐藏文件被忽略。
  使用数字前缀控制合并顺序，例如 10-telemetry.json 和 20-security.json。
其他配置存储在 ~/.claude.json。此文件包含你的 OAuth 会话、用户和本地范围的 MCP 服务器配置、按项目状态（允许的工具、信任设置）和各种缓存。项目范围的 MCP 服务器单独存储在 .mcp.json 中。

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

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

编辑何时生效

Claude Code 监视你的设置文件并在更改时重新加载，因此大多数键的编辑无需重启即可应用于运行中的会话。这包括 permissions、hooks 和凭证助手如 apiKeyHelper。重新加载涵盖用户、项目、本地和托管设置，ConfigChange Hook 为每个检测到的更改触发。

少数键在会话开始时读取一次，在下次重启时应用：

model：使用 /model 在会话中切换
outputStyle：系统提示的一部分，在 /clear 或重启时重建

可用设置

settings.json 支持多个选项：

键	描述	示例
`agent`	将主线程作为命名子 Agent 运行	`"code-reviewer"`
`allowedChannelPlugins`	（托管）可推送消息的通道插件白名单	`[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]`
`allowedHttpHookUrls`	HTTP Hook 可能目标的 URL 模式白名单	`["https://hooks.example.com/*"]`
`allowedMcpServers`	在 managed-settings.json 中设置时，用户可配置的 MCP 服务器白名单	`[{ "serverName": "github" }]`
`allowManagedHooksOnly`	（托管）仅加载托管 Hook、SDK Hook 和强制启用的插件 Hook	`true`
`allowManagedMcpServersOnly`	（托管）仅应用管理员定义的 MCP 服务器白名单	`true`
`allowManagedPermissionRulesOnly`	（托管）仅应用托管设置中的规则	`true`
`alwaysThinkingEnabled`	默认为所有会话启用扩展思考	`true`
`apiKeyHelper`	生成认证值的自定义脚本	`/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`	（托管）市场来源黑名单	`[{ "source": "github", "repo": "untrusted/plugins" }]`
`channelsEnabled`	（托管）为组织允许通道	`true`
`claudeMd`	（托管）作为组织管理记忆注入的 CLAUDE.md 风格指令	`"Always run make lint before committing."`
`claudeMdExcludes`	要跳过的 CLAUDE.md 文件的 glob 模式或绝对路径	`["/vendor//CLAUDE.md"]`
`cleanupPeriodDays`	超过此时间段的会话文件在启动时删除（默认：30）	`20`
`companyAnnouncements`	启动时向用户显示的公告	`["Welcome to Acme Corp!"]`
`defaultShell`	输入框 `!` 命令的默认 shell	`"powershell"`
`deniedMcpServers`	（托管）明确阻止的 MCP 服务器黑名单	`[{ "serverName": "filesystem" }]`
`disableAgentView`	关闭后台 Agent 和 Agent 视图	`true`
`disableAllHooks`	禁用所有 Hook 和自定义状态行	`true`
`disableAutoMode`	阻止自动模式被激活	`"disable"`
`disableDeepLinkRegistration`	阻止注册 `claude-cli://` 协议处理器	`"disable"`
`disabledMcpjsonServers`	要拒绝的 `.mcp.json` 文件中的特定 MCP 服务器列表	`["filesystem"]`
`disableRemoteControl`	禁用远程控制（最低 v2.1.128）	`true`
`disableSkillShellExecution`	禁用技能和自定义命令的内联 shell 执行	`true`
`editorMode`	输入提示的键绑定模式	`"vim"`
`effortLevel`	跨会话持久化努力级别	`"xhigh"`
`enableAllProjectMcpServers`	自动批准项目 `.mcp.json` 中定义的所有 MCP 服务器	`true`
`enabledMcpjsonServers`	要批准的 `.mcp.json` 中的特定 MCP 服务器列表	`["memory", "github"]`
`env`	应用于每个会话和子进程的环境变量	`{"FOO": "bar"}`
`fastModePerSessionOptIn`	为 true 时，快速模式不跨会话持久	`true`
`feedbackSurveyRate`	会话质量调查出现的概率（0-1）	`0.05`
`fileSuggestion`	为 `@` 文件自动补全配置自定义脚本	`{"type": "command", "command": "~/.claude/file-suggestion.sh"}`
`forceLoginMethod`	限制登录为 `claudeai` 或 `console`	`claudeai`
`forceLoginOrgUUID`	要求登录属于特定组织	`"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"`
`forceRemoteSettingsRefresh`	（托管）阻止 CLI 启动直到远程托管设置被最新获取	`true`
`gcpAuthRefresh`	刷新 GCP Application Default Credentials 的自定义脚本	`gcloud auth application-default login`
`hooks`	配置在生命周期事件运行的自定义命令	参见 hooks 文档
`httpHookAllowedEnvVars`	HTTP Hook 可能插值的环境变量名白名单	`["MY_TOKEN", "HOOK_SECRET"]`
`includeCoAuthoredBy`	已弃用：改用 `attribution`	`false`
`includeGitInstructions`	在系统提示中包含内置提交和 PR 工作流指令	`false`
`language`	配置 Claude 的首选响应语言	`"japanese"`
`maxSkillDescriptionChars`	每个技能描述文本的字符上限（最低 v2.1.105）	`2048`
`minimumVersion`	阻止安装低于此版本的下限	`"2.1.100"`
`model`	覆盖要使用的默认模型	`"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`	（托管）控制父级提供的设置行为（最低 v2.1.133）	`"merge"`
`permissions`	权限规则结构	参见下表
`plansDirectory`	自定义计划文件存储位置	`"./plans"`
`pluginTrustMessage`	（托管）附加到插件信任警告的自定义消息	`"All plugins from our marketplace are approved by IT"`
`policyHelper`	管理员部署的可执行文件，动态计算托管设置（最低 v2.1.136）	`{"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`	在计划接受屏幕上显示"清除上下文"选项	`true`
`showThinkingSummaries`	在交互式会话中显示扩展思考摘要	`true`
`showTurnDuration`	在响应后显示回合持续时间消息	`false`
`skillListingBudgetFraction`	为技能列表保留的上下文窗口比例（最低 v2.1.105）	`0.02`
`skillOverrides`	每个技能的可见性覆盖（最低 v2.1.129）	`{"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`	（托管）插件市场来源白名单	`[{ "source": "github", "repo": "acme-corp/plugins" }]`
`syntaxHighlightingDisabled`	在差异、代码块和文件预览中禁用语法高亮	`true`
`teammateMode`	Agent 团队队友的显示方式	`"in-process"`
`terminalProgressBarEnabled`	在支持的终端中显示终端进度条	`false`
`tui`	终端 UI 渲染器	`"fullscreen"`
`useAutoModeDuringPlan`	计划模式在可用时是否使用自动模式语义	`false`
`viewMode`	启动时的默认转录视图模式	`"verbose"`
`voice`	语音听写设置	`{ "enabled": true, "mode": "tap" }`
`voiceEnabled`	`voice.enabled` 的旧别名	`true`
`wslInheritsWindowsSettings`	（Windows 托管）WSL 从 Windows 策略链读取托管设置	`true`

全局配置设置

这些设置存储在 ~/.claude.json 而非 settings.json 中。将它们添加到 settings.json 会触发模式验证错误。

键	描述	示例
`autoConnectIde`	从外部终端启动时自动连接到运行中的 IDE	`true`
`autoInstallIdeExtension`	从 VS Code 终端运行时自动安装 Claude Code IDE 扩展	`false`
`externalEditorContext`	用 `Ctrl+G` 打开外部编辑器时，将 Claude 的上一个响应作为 `#` 注释的上下文前置	`true`
`teammateDefaultModel`	Agent 团队队友在 spawn 提示未指定时的默认模型	`"sonnet"`

Worktree 设置

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

键	描述	示例
`worktree.baseRef`	新 worktree 从哪个 ref 分支（`"fresh"` 或 `"head"`）	`"head"`
`worktree.symlinkDirectories`	从主仓库符号链接到每个 worktree 的目录	`["node_modules", ".cache"]`
`worktree.sparsePaths`	通过 git sparse-checkout 检出的目录	`["packages/my-app", "shared/utils"]`
`worktree.bgIsolation`	后台会话的隔离模式（最低 v2.1.143）	`"none"`

要将 .env 等 gitignored 文件复制到新 worktree，使用项目根目录中的 .worktreeinclude 文件而非设置。

权限设置

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

权限规则语法

权限规则遵循格式 Tool 或 Tool(specifier)。规则按顺序评估：先 deny 规则，然后 ask，然后 allow。第一个匹配的规则生效。

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

沙箱设置

配置高级沙箱行为。沙箱将 bash 命令与你的文件系统和网络隔离。

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

沙箱路径前缀

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

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

配置示例：

json

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "*.example.com"]
    }
  }
}

Windows 沙箱设置

Claude Code 目前不支持原生 Windows 上的沙箱。上面记录的沙箱设置仅适用于 macOS、Linux 和 WSL2。

归属设置

自定义 git 提交和拉取请求的归属：

键	描述	示例
`attribution.commit`	添加到 Claude 生成的提交的页脚。设为 `""` 可完全抑制	`"... Generated with Claude Code"`
`attribution.pr`	添加到 Claude 生成的拉取请求的页脚。设为 `""` 可完全抑制	`"Created with Claude Code"`

json

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

文件建议设置

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

json

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

脚本接收部分路径作为 $1，应每行输出一个建议。

Hook 配置

配置在生命周期事件运行的自定义命令。参见 Hook 文档了解格式和可用事件。

设置优先级

设置跨范围按此优先级顺序合并：

托管（最高优先级）
命令行参数
本地
项目
用户（最低优先级）

权限规则跨范围合并而非覆盖——所有范围的所有 allow、ask 和 deny 规则被组合。托管设置可以使用 allowManagedPermissionRulesOnly 来限制哪些范围可以定义权限规则。

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

policyHelper 设置（最低 v2.1.136）指定管理员部署的可执行文件，在启动时动态计算托管设置。仅从 MDM 或系统 managed-settings.json 文件中接受。可执行文件应输出匹配托管设置格式的 JSON 到 stdout。

json

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

策略助手在启动时运行，其输出与静态托管设置合并，策略助手的输出优先。

Claude Code 设置 ​

配置范围 ​

可用范围 ​

何时使用每个范围 ​

范围如何交互 ​

什么使用范围 ​

设置文件 ​

编辑何时生效 ​

可用设置 ​

全局配置设置 ​

Worktree 设置 ​

权限设置 ​

权限规则语法 ​

沙箱设置 ​

沙箱路径前缀 ​

Windows 沙箱设置 ​

归属设置 ​

文件建议设置 ​

Hook 配置 ​

设置优先级 ​

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

Claude Code 设置

配置范围

可用范围

何时使用每个范围

范围如何交互

什么使用范围

设置文件

编辑何时生效

可用设置

全局配置设置

Worktree 设置

权限设置

权限规则语法

沙箱设置

沙箱路径前缀

Windows 沙箱设置

归属设置

文件建议设置

Hook 配置

设置优先级

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