{/* TRANSLATED — 已翻译为中文 */}
> ## 文档索引
> 在此获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后再进一步探索。
# 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` | 你，仅在此仓库中 | 否（gitignore） |
### 何时使用每个作用域
**管理作用域**适用于：
* 必须在全组织范围强制执行的安全策略
* 不能被覆盖的合规要求
* 由 IT/DevOps 部署的标准化配置
**用户作用域**最适合：
* 你想要到处使用的个人偏好（主题、编辑器设置）
* 你跨所有项目使用的工具和插件
* API 密钥和认证（安全存储）
**项目作用域**最适合：
* 团队共享设置（权限、钩子、MCP 服务器）
* 整个团队应该有的插件
* 跨协作者标准化工具
**本地作用域**最适合：
* 特定项目的个人覆盖
* 在与团队共享之前测试配置
* 对其他人不起作用的机器特定设置
### 作用域如何交互
当同一设置出现在多个作用域中时，Claude Code 按优先级顺序应用它们：
1. **管理**（最高）- 不能被任何内容覆盖
2. **命令行参数** - 临时会话覆盖
3. **本地** - 覆盖项目和用户设置
4. **项目** - 覆盖用户设置
5. **用户**（最低）- 当没有其他内容指定该设置时应用
例如，如果你的用户设置将 `spinnerTipsEnabled` 设置为 `true` 而项目设置将其设置为 `false`，则应用项目值。权限规则的行为不同，因为它们跨作用域合并而不是覆盖。参见[设置优先级](#settings-precedence)。
### 使用作用域的功能
作用域适用于许多 Claude Code 功能：
| 功能 | 用户位置 | 项目位置 | 本地位置 |
| :-------------- | :-------------------------- | :------------------------------ | :---------------------------- |
| **设置** | `~/.claude/settings.json` | `.claude/settings.json` | `.claude/settings.local.json` |
| **Subagents** | `~/.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 支持多种管理设置传递机制。所有使用相同的 JSON 格式，不能被用户或项目设置覆盖：
* **服务器管理设置**：通过 Claude.ai 管理控制台从 Anthropic 服务器传递。参见[服务器管理设置](/en/server-managed-settings)。
* **MDM/OS 级策略**：通过 macOS 和 Windows 上的原生设备管理传递：
* macOS：`com.anthropic.claudecode` 托管偏好设置域。plist 的顶级键映射 `managed-settings.json`，嵌套设置作为字典，数组作为 plist 数组。通过 Jamf、Iru (Kandji) 或类似 MDM 工具中的配置文件部署。
* Windows：`HKLM\SOFTWARE\Policies\ClaudeCode` 注册表键，包含 `Settings` 值（REG\_SZ 或 REG\_EXPAND\_SZ），其中包含 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 起不再支持。将设置部署到该位置的管理员必须将文件迁移到 `C:\Program Files\ClaudeCode\managed-settings.json`。
基于文件的管理设置还支持在与 `managed-settings.json` 相同的系统目录中的 `managed-settings.d/` 处的 drop-in 目录。这让不同团队可以部署独立的策略片段而无需协调对单个文件的编辑。
遵循 systemd 约定，`managed-settings.json` 首先作为基础合并，然后 drop-in 目录中的所有 `*.json` 文件按字母顺序排序并在其上合并。后面的文件覆盖前面的标量值；数组被连接和去重；对象被深度合并。以 `.` 开头的隐藏文件被忽略。
使用数字前缀控制合并顺序，例如 `10-telemetry.json` 和 `20-security.json`。
参见[管理设置](/en/permissions#managed-only-settings)和[管理 MCP 配置](/en/managed-mcp)了解详情。
此[仓库](https://github.com/anthropics/claude-code/tree/main/examples/mdm)包含 Jamf、Iru (Kandji)、Intune 和组策略的入门部署模板。将这些作为起点并根据需要调整。
管理部署还可以使用 `strictKnownMarketplaces` 限制**插件市场添加**。更多信息参见[管理市场限制](/en/plugin-marketplaces#managed-marketplace-restrictions)。
* **其他配置**存储在 `~/.claude.json` 中。此文件包含你的 OAuth 会话、用户和本地作用域的 [MCP 服务器](/en/mcp)配置、按项目状态（允许的工具、信任设置）和各种缓存。项目作用域的 MCP 服务器单独存储在 `.mcp.json` 中。
Claude Code 自动创建配置文件的时间戳备份，并保留最近的五个备份以防止数据丢失。
```JSON 示例 settings.json theme={null}
{
"$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 schema](https://json.schemastore.org/claude-code-settings.json)。将其添加到你的 `settings.json` 可以在 VS Code、Cursor 和任何支持 JSON schema 验证的编辑器中启用自动补全和内联验证。
发布的 schema 定期更新，可能不包括最近 CLI 版本中添加的设置，因此最近文档化字段上的验证警告不一定意味着你的配置无效。
### 编辑何时生效
Claude Code 监视你的设置文件并在它们更改时重新加载，因此对大多数键的编辑无需重启即可应用于运行中的会话。这包括 `permissions`、`hooks` 和凭证助手如 `apiKeyHelper`。重新加载涵盖用户、项目、本地和管理设置，每个检测到的更改都会触发 [`ConfigChange` 钩子](/en/hooks#configchange)。
少数键在会话启动时读取一次，在下次重启时应用：
* `model`：使用 [`/model`](/en/model-config#setting-your-model) 在会话中途切换
* [`outputStyle`](/en/output-styles)：系统提示的一部分，在 `/clear` 或重启时重建
### 可用设置
`settings.json` 支持许多选项：
| 键 | 描述 | 示例 |
| :-------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
| `agent` | 将主线程作为命名 subagent 运行。应用该 subagent 的系统提示、工具限制和模型。参见[显式调用 subagents](/en/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |
| `allowAllClaudeAiMcps` | （仅管理设置）与部署的 `managed-mcp.json` 一起加载 claude.ai 连接器，否则后者独占控制并抑制它们。参见[管理 MCP 配置](/en/managed-mcp) | `true` |
| `allowedChannelPlugins` | （仅管理设置）允许推送消息的频道插件白名单。设置后替换默认的 Anthropic 白名单。未定义 = 回退到默认值，空数组 = 阻止所有频道插件。需要 `channelsEnabled: true`。参见[限制可运行的频道插件](/en/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |
| `allowedHttpHookUrls` | HTTP 钩子可以目标指向的 URL 模式白名单。支持 `*` 作为通配符。设置后，不匹配 URL 的钩子被阻止。未定义 = 无限制，空数组 = 阻止所有 HTTP 钩子。数组跨设置源合并。参见[钩子配置](#hook-configuration) | `["https://hooks.example.com/*"]` |
| `allowedMcpServers` | 在 managed-settings.json 中设置时，用户可以配置的 MCP 服务器白名单。未定义 = 无限制，空数组 = 锁定。适用于所有作用域。拒绝列表优先。参见[管理 MCP 配置](/en/managed-mcp) | `[{ "serverName": "github" }]` |
| `allowManagedHooksOnly` | （仅管理设置）仅加载管理钩子、SDK 钩子和管理设置 `enabledPlugins` 中强制启用的插件的钩子。用户、项目和所有其他插件钩子被阻止。参见[钩子配置](#hook-configuration) | `true` |
| `allowManagedMcpServersOnly` | （仅管理设置）仅遵循管理设置中的 `allowedMcpServers`。`deniedMcpServers` 仍从所有源合并。用户仍然可以添加 MCP 服务器，但仅管理员定义的白名单适用。参见[管理 MCP 配置](/en/managed-mcp) | `true` |
| `allowManagedPermissionRulesOnly` | （仅管理设置）阻止用户和项目设置定义 `allow`、`ask` 或 `deny` 权限规则。仅应用管理设置中的规则。参见[仅管理设置](/en/permissions#managed-only-settings) | `true` |
| `alwaysThinkingEnabled` | 默认为所有会话启用[扩展思考](/en/model-config#extended-thinking)。通常通过 `/config` 命令配置而不是直接编辑。要强制关闭思考（无论此设置如何），在 `env` 中设置 [`CLAUDE_CODE_DISABLE_THINKING`](/en/env-vars) | `true` |
| `apiKeyHelper` | 自定义脚本，在 `/bin/sh` 中执行，生成认证值。此值将作为 `X-Api-Key` 和 `Authorization: Bearer` 头发送用于模型请求。使用 [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/en/env-vars) 设置刷新间隔 | `/bin/generate_temp_api_key.sh` |
| `attribution` | 自定义 git 提交和拉取请求的归属。参见[归属设置](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |
| `autoMemoryDirectory` | [自动记忆](/en/memory#storage-location)存储的自定义目录。接受绝对路径或 `~/` 前缀路径。接受来自策略和用户设置以及 `--settings` 标志。不接受来自项目或本地设置，因为克隆的仓库可能提供任一文件来将记忆写入重定向到敏感位置 | `"~/my-memory-dir"` |
| `autoMemoryEnabled` | 启用[自动记忆](/en/memory#enable-or-disable-auto-memory)。为 `false` 时，Claude 不从自动记忆目录读取或写入。默认：`true`。你也可以在会话期间使用 `/memory` 切换此设置。要通过环境变量禁用，在 `env` 中设置 [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/en/env-vars) | `false` |
| `autoMode` | 自定义[自动模式](/en/permission-modes#eliminate-prompts-with-auto-mode)分类器阻止和允许的内容。包含 `environment`、`allow`、`soft_deny` 和 `hard_deny` 的散文规则数组。在数组中包含字面字符串 `"$defaults"` 以在该位置继承内置规则。参见[配置自动模式](/en/auto-mode-config)。不从共享项目设置读取 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |
| `autoScrollEnabled` | 在[全屏渲染](/en/fullscreen)中，跟随新输出到对话底部。默认：`true`。在 `/config` 中显示为**自动滚动**。关闭时权限提示仍会滚动到视图中 | `false` |
| `autoUpdatesChannel` | 要跟随的更新发布频道。使用 `"stable"` 获取通常约一周前的版本并跳过有重大回归的版本，或使用 `"latest"`（默认）获取最新发布。要完全禁用自动更新，在 `env` 中设置 [`DISABLE_AUTOUPDATER`](/en/setup#disable-auto-updates) | `"stable"` |
| `availableModels` | 限制用户可以通过 `/model`、`--model` 或 `ANTHROPIC_MODEL` 选择的模型。不影响默认选项。参见[限制模型选择](/en/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |
| `awaySummaryEnabled` | 当你离开几分钟后返回终端时显示一行会话摘要。设置为 `false` 或在 `/config` 中关闭会话摘要以禁用。等同于 [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/en/env-vars) | `true` |
| `awsAuthRefresh` | 修改 `.aws` 目录的自定义脚本（参见[高级凭证配置](/en/amazon-bedrock#advanced-credential-configuration)） | `aws sso login --profile myprofile` |
| `awsCredentialExport` | 输出包含 AWS 凭证的 JSON 的自定义脚本（参见[高级凭证配置](/en/amazon-bedrock#advanced-credential-configuration)） | `/bin/generate_aws_grant.sh` |
| `blockedMarketplaces` | （仅管理设置）市场来源阻止列表。在市场添加和插件安装、更新、刷新和自动更新时强制执行，因此在策略设置之前添加的市场不能用于获取插件。阻止的来源在下载前检查，因此它们永远不会触及文件系统。参见[管理市场限制](/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |
| `channelsEnabled` | （仅管理设置）为组织允许[频道](/en/channels)。在 claude.ai Team 和 Enterprise 计划上，未设置或为 `false` 时频道被阻止。对于使用 API 密钥认证的 [Anthropic Console](/en/authentication#claude-console-authentication) 账户，频道默认允许，除非你的组织部署了管理设置，在这种情况下此键必须设置为 `true` | `true` |
| `claudeMd` | （仅管理设置）作为组织管理记忆注入的 CLAUDE.md 风格指令。仅在管理或策略设置中设置时被遵循，在用户、项目和本地设置中忽略。参见[组织范围的 CLAUDE.md](/en/memory#deploy-organization-wide-claude-md) | `"Always run make lint before committing."` |
| `claudeMdExcludes` | 加载[记忆](/en/memory)时要跳过的 `CLAUDE.md` 文件的 glob 模式或绝对路径。模式与绝对文件路径匹配。仅适用于用户、项目和本地记忆；管理策略文件不能被排除 | `["**/vendor/**/CLAUDE.md"]` |
| `cleanupPeriodDays` | 超过此时间段的会话文件在启动时删除（默认：30 天，最小 1）。设置为 `0` 会被验证错误拒绝。还控制启动时自动移除[孤立 subagent 工作树](/en/worktrees#clean-up-worktrees)的截止时间。要完全禁用对话记录写入，设置 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/en/env-vars) 环境变量，或在非交互模式（`-p`）中使用 `--no-session-persistence` 标志或 `persistSession: false` SDK 选项。 | `20` |
| `companyAnnouncements` | 启动时向用户显示的公告。如果提供多个公告，它们将随机循环显示。 | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |
| `defaultShell` | 输入框 `!` 命令的默认 shell。接受 `"bash"`（默认）或 `"powershell"`。设置 `"powershell"` 在 Windows 上通过 PowerShell 路由交互式 `!` 命令。需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。参见 [PowerShell 工具](/en/tools-reference#powershell-tool) | `"powershell"` |
| `deniedMcpServers` | 在 managed-settings.json 中设置时，明确阻止的 MCP 服务器拒绝列表。适用于所有作用域（包括管理服务器）。拒绝列表优先于允许列表。参见[管理 MCP 配置](/en/managed-mcp) | `[{ "serverName": "filesystem" }]` |
| `disableAgentView` | 设置为 `true` 以关闭[后台代理和代理视图](/en/agent-view)：`claude agents`、`--bg`、`/background` 和按需监督器。通常在[管理设置](/en/permissions#managed-settings)中设置。等同于将 `CLAUDE_CODE_DISABLE_AGENT_VIEW` 设置为 `1` | `true` |
| `disableAllHooks` | 禁用所有[钩子](/en/hooks)和任何自定义[状态栏](/en/statusline) | `true` |
| `disableAutoMode` | 设置为 `"disable"` 以阻止[自动模式](/en/permission-modes#eliminate-prompts-with-auto-mode)被激活。从 `Shift+Tab` 循环中移除 `auto` 并在启动时拒绝 `--permission-mode auto`。在[管理设置](/en/permissions#managed-settings)中最有用，用户不能覆盖它 | `"disable"` |
| `disableDeepLinkRegistration` | 设置为 `"disable"` 以阻止 Claude Code 在启动时向操作系统注册 `claude-cli://` 协议处理器。[深度链接](/en/deep-links)让外部工具可以打开带有预填提示的 Claude Code 会话。在协议处理器注册受限或单独管理的环境中很有用 | `"disable"` |
| `disabledMcpjsonServers` | 要拒绝的 `.mcp.json` 文件中特定 MCP 服务器的列表 | `["filesystem"` |
| `disableRemoteControl` | {/* min-version: 2.1.128 */}禁用[远程控制](/en/remote-control)：阻止 `claude remote-control`、`--remote-control` 标志、自动启动和会话内切换。通常放在[管理设置](/en/permissions#managed-settings)中用于每设备 MDM 强制执行，但在任何作用域下都有效。需要 Claude Code v2.1.128 或更高版本 | `true` |
| `disableSkillShellExecution` | 禁用来自用户、项目、插件或附加目录来源的[技能](/en/skills)和自定义命令中的 `` !`...` `` 和 ` ```! ` 块的内联 shell 执行。命令被替换为 `[shell command execution disabled by policy]` 而不是被运行。内置和管理技能不受影响。在[管理设置](/en/permissions#managed-settings)中最有用，用户不能覆盖它 | `true` |
| `editorMode` | 输入提示的键绑定模式：`"normal"` 或 `"vim"`。默认：`"normal"`。在 `/config` 中显示为**编辑器模式** | `"vim"` |
| `effortLevel` | 跨会话持久化[努力级别](/en/model-config#adjust-effort-level)。接受 `"low"`、`"medium"`、`"high"` 或 `"xhigh"`。使用这些值之一运行 `/effort` 时自动写入。`--effort` 和 [`CLAUDE_CODE_EFFORT_LEVEL`](/en/env-vars) 覆盖此会话的设置。参见[调整努力级别](/en/model-config#adjust-effort-level)了解支持的模型 | `"xhigh"` |
| `enableAllProjectMcpServers` | 自动批准项目 `.mcp.json` 文件中定义的所有 MCP 服务器 | `true` |
| `enabledMcpjsonServers` | 要批准的 `.mcp.json` 文件中特定 MCP 服务器的列表 | `["memory", "github"` |
| `env` | 应用于每个会话和 Claude Code 从中生成的子进程的环境变量。{/* min-version: 2.1.143 */}从 v2.1.143 起，此处设置的 `NO_COLOR` 和 `FORCE_COLOR` 传递给子进程但不更改 Claude Code 自己的界面颜色。在启动 `claude` 之前在 shell 中设置这些以更改界面颜色 | `{"FOO": "bar"}` |
| `fastModePerSessionOptIn` | 为 `true` 时，快速模式不跨会话持久化。每个会话以快速模式关闭开始，需要用户使用 `/fast` 启用它。用户的快速模式偏好仍会被保存。参见[要求每会话选择加入](/en/fast-mode#require-per-session-opt-in) | `true` |
| `feedbackSurveyRate` | [会话质量调查](/en/data-usage#session-quality-surveys)在符合条件时出现的概率（0-1）。设置为 `0` 以完全抑制，或在 `env` 中设置 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/en/env-vars)。在使用 Bedrock、Vertex 或 Foundry 时很有用，因为默认采样率不适用 | `0.05` |
| `fileSuggestion` | 配置 `@` 文件自动补全的自定义脚本。参见[文件建议设置](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |
| `forceLoginMethod` | 使用 `claudeai` 限制登录到 Claude.ai 账户，`console` 限制登录到 Claude Console（API 使用计费）账户。在管理设置中设置时，通过 API 密钥、`apiKeyHelper` 或第三方提供商认证的会话在启动时被阻止，因为两者都不能在没有第一方 OAuth 的情况下满足 | `claudeai` |
| `forceLoginOrgUUID` | 要求登录属于特定组织。接受单个 UUID 字符串（在登录期间也预选该组织），或 UUID 数组（接受任何列出的组织而不预选）。在管理设置中设置时，如果认证的账户不属于列出的组织则登录失败，通过 API 密钥、`apiKeyHelper` 或第三方提供商认证的会话在启动时被阻止，因为无法验证其组织成员资格。空数组失败关闭并以配置错误消息阻止登录 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 或 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |
| `forceRemoteSettingsRefresh` | （仅管理设置）阻止 CLI 启动直到从服务器最新获取远程管理设置。如果获取失败，CLI 退出而不是使用缓存或无设置继续。未设置时，启动继续而不等待远程设置。参见[失败关闭强制执行](/en/server-managed-settings#enforce-fail-closed-startup) | `true` |
| `gcpAuthRefresh` | 当 GCP 应用默认凭证过期或无法加载时刷新它们的自定义脚本。参见[高级凭证配置](/en/google-vertex-ai#advanced-credential-configuration) | `gcloud auth application-default login` |
| `hooks` | 配置在生命周期事件时运行的自定义命令。参见[钩子文档](/en/hooks)了解格式 | 参见 [hooks](/en/hooks) |
| `httpHookAllowedEnvVars` | HTTP 钩子可以插值到头中的环境变量名称白名单。设置后，每个钩子的有效 `allowedEnvVars` 是与此列表的交集。未定义 = 无限制。数组跨设置源合并。参见[钩子配置](#hook-configuration) | `["MY_TOKEN", "HOOK_SECRET"]` |
| `includeCoAuthoredBy` | **已弃用**：改用 `attribution`。是否在 git 提交和拉取请求中包含 `co-authored-by Claude` 署名（默认：`true`） | `false` |
| `includeGitInstructions` | 在 Claude 的系统提示中包含内置的提交和 PR 工作流指令以及 git 状态快照（默认：`true`）。设置为 `false` 以移除两者，例如当你使用自己的 git 工作流技能时。`CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` 环境变量设置时优先于此设置 | `false` |
| `language` | 配置 Claude 的首选响应语言（例如 `"japanese"`、`"spanish"`、`"french"`）。Claude 默认将使用此语言响应。还设置[语音听写](/en/voice-dictation#change-the-dictation-language)语言 | `"japanese"` |
| `maxSkillDescriptionChars` | {/* min-version: 2.1.105 */}每技能字符上限，限制 [skill listing](/en/skills#skill-descriptions-are-cut-short) 中 Claude 每回合看到的组合 `description` 和 `when_to_use` 文本（默认：`1536`）。超过此长度的文本被截断。提高以保持长描述完整，代价是每回合更多上下文；降低以在 [`skillListingBudgetFraction`](#available-settings) 下容纳更多技能。需要 Claude Code v2.1.105 或更高版本 | `2048` |
| `minimumVersion` | 阻止后台自动更新和 `claude update` 安装低于此版本的下限。通过 `/config` 从 `"latest"` 频道切换到 `"stable"` 时，会提示你留在当前版本或允许降级。选择停留会设置此值。在[管理设置](/en/permissions#managed-settings)中也很有用，用于固定组织范围的最低版本 | `"2.1.100"` |
| `model` | 覆盖 Claude Code 使用的默认模型。`--model` 和 [`ANTHROPIC_MODEL`](/en/model-config#environment-variables) 覆盖此会话的设置 | `"claude-sonnet-4-6"` |
| `modelOverrides` | 将 Anthropic 模型 ID 映射到提供商特定的模型 ID，如 Bedrock 推理配置文件 ARN。每个模型选择器条目在调用提供商 API 时使用其映射值。参见[按版本覆盖模型 ID](/en/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |
| `otelHeadersHelper` | 生成动态 OpenTelemetry 头的脚本。在启动时和定期运行。使用 [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/en/env-vars) 设置刷新间隔。参见[动态头](/en/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |
| `outputStyle` | 配置输出样式以调整系统提示。参见[输出样式文档](/en/output-styles) | `"Explanatory"` |
| `parentSettingsBehavior` | {/* min-version: 2.1.133 */}（仅管理设置）控制当管理部署的管理层也存在时，由嵌入主机进程（如 Agent SDK 或 IDE 扩展）编程提供的管理设置是否应用。`"first-wins"`：父提供的设置被丢弃，仅管理层应用。`"merge"`：父提供的设置在管理层下应用，经过过滤以收紧策略但不能放松。未部署管理层时无效。默认：`"first-wins"`。需要 Claude Code v2.1.133 或更高版本 | `"merge"` |
| `permissions` | 参见下方权限结构表。 | |
| `plansDirectory` | 自定义计划文件的存储位置。路径相对于项目根目录。默认：`~/.claude/plans` | `"./plans"` |
| `pluginTrustMessage` | （仅管理设置）附加到安装前显示的插件信任警告的自定义消息。使用此添加组织特定的上下文，例如确认来自内部市场的插件已审核。 | `"All plugins from our marketplace are approved by IT"` |
| `policyHelper` | {/* min-version: 2.1.136 */}管理员部署的可执行文件，在启动时动态计算管理设置。仅从 MDM 或系统 `managed-settings.json` 文件中被遵循。参见[使用策略助手计算管理设置](#compute-managed-settings-with-a-policy-helper)。需要 Claude Code v2.1.136 或更高版本 | `{"path": "/usr/local/bin/claude-policy"}` |
| `preferredNotifChannel` | 任务完成和权限提示通知的方法：`"auto"`、`"terminal_bell"`、`"iterm2"`、`"iterm2_with_bell"`、`"kitty"`、`"ghostty"` 或 `"notifications_disabled"`。默认：`"auto"`，在 iTerm2、Ghostty 和 Kitty 中发送桌面通知，在其他终端中不执行任何操作。设置 `"terminal_bell"` 在任何终端中响铃字符。在 `/config` 中显示为**通知**。参见[获取终端响铃或通知](/en/terminal-config#get-a-terminal-bell-or-notification) | `"terminal_bell"` |
| `prefersReducedMotion` | 为辅助功能减少或禁用 UI 动画（旋转器、闪光、闪烁效果） | `true` |
| `prUrlTemplate` | 页脚和工具结果摘要中显示的 PR 徽章的 URL 模板。从 `gh` 报告的 PR URL 中替换 `{host}`、`{owner}`、`{repo}`、`{number}` 和 `{url}`。用于将 PR 链接指向内部代码审查工具而不是 `github.com`。不影响 Claude 文本中的 `#123` 自动链接 | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |
| `respectGitignore` | 控制 `@` 文件选择器是否遵循 `.gitignore` 模式。为 `true`（默认）时，匹配 `.gitignore` 模式的文件被排除在建议之外 | `false` |
| `showClearContextOnPlanAccept` | 在计划接受屏幕上显示"清除上下文"选项。默认为 `false`。设置为 `true` 以恢复该选项 | `true` |
| `showThinkingSummaries` | 在交互式会话中显示[扩展思考](/en/model-config#extended-thinking)摘要。未设置或为 `false`（交互模式默认值）时，思考块被 API 编辑并显示为折叠存根。编辑仅更改你看到的内容，不更改模型生成的内容：要减少思考支出，[降低预算或禁用思考](/en/model-config#extended-thinking)。此设置在非交互模式（`-p`）、Agent SDK 或 IDE 扩展（如 VS Code）中无效 | `true` |
| `showTurnDuration` | 在响应后显示回合持续时间消息，例如 "Cooked for 1m 6s"。默认：`true`。在 `/config` 中显示为**显示回合持续时间** | `false` |
| `skillListingBudgetFraction` | {/* min-version: 2.1.105 */}为 Claude 每回合看到的 [skill listing](/en/skills#skill-descriptions-are-cut-short) 保留的模型上下文窗口比例（默认：`0.01` = 1%）。当列表超出预算时，最少使用技能的描述被折叠为裸名称，因此 Claude 仍然可以调用它们但不会看到原因。提高以保持更多描述可见，代价是每回合更多上下文。`/doctor` 显示当前截断计数和受影响的技能。需要 Claude Code v2.1.105 或更高版本 | `0.02` |
| `skillOverrides` | {/* min-version: 2.1.129 */}按技能名称键入的每技能可见性覆盖。值为 `"on"`、`"name-only"`、`"user-invocable-only"` 或 `"off"`。让你可以隐藏或折叠技能而无需编辑其 SKILL.md。不适用于插件技能，它们通过 `/plugin` 管理。`/skills` 菜单将这些写入 `.claude/settings.local.json`。参见[从设置覆盖技能可见性](/en/skills#override-skill-visibility-from-settings)。需要 Claude Code v2.1.129 或更高版本 | `{"legacy-context": "name-only", "deploy": "off"}` |
| `skipWebFetchPreflight` | 跳过[WebFetch 域名安全检查](/en/data-usage#webfetch-domain-safety-check)，该检查在获取前将每个请求的主机名发送到 `api.anthropic.com`。在阻止到 Anthropic 流量的环境中设置为 `true`，如 Bedrock、Vertex AI 或具有限制性出口的 Foundry 部署。跳过时，WebFetch 尝试任何 URL 而不咨询阻止列表 | `true` |
| `spinnerTipsEnabled` | 在 Claude 工作时在旋转器中显示提示。设置为 `false` 以禁用提示（默认：`true`） | `false` |
| `spinnerTipsOverride` | 使用自定义字符串覆盖旋转器提示。`tips`：提示字符串数组。`excludeDefault`：为 `true` 时仅显示自定义提示；为 `false` 或缺失时，自定义提示与内置提示合并 | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |
| `spinnerVerbs` | 自定义回合进行时显示的动作动词。将 `mode` 设置为 `"replace"` 仅使用你的动词，或 `"append"` 将它们添加到默认值 | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |
| `sshConfigs` | 在[桌面](/en/desktop#pre-configure-ssh-connections-for-your-team)环境下拉菜单中显示的 SSH 连接。每个条目需要 `id`、`name` 和 `sshHost`；`sshPort`、`sshIdentityFile` 和 `startDirectory` 是可选的。在管理设置中设置时，连接对用户是只读的。仅从管理和用户设置读取 | `[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]` |
| `statusLine` | 配置自定义状态栏以显示上下文。参见 [`statusLine` 文档](/en/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |
| `strictKnownMarketplaces` | （仅管理设置）插件市场来源白名单。未定义 = 无限制，空数组 = 锁定。在市场添加和插件安装、更新、刷新和自动更新时强制执行，因此在策略设置之前添加的市场不能用于获取插件。参见[管理市场限制](/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |
| `strictPluginOnlyCustomization` | （仅管理设置）阻止来自用户和项目来源的技能、代理、钩子和 MCP 服务器，使它们只能来自插件或管理设置。`true` 锁定所有四个表面；数组仅锁定命名的。参见 [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | `["skills", "hooks"]` |
| `syntaxHighlightingDisabled` | 禁用差异、代码块和文件预览中的语法高亮 | `true` |
| `teammateMode` | [代理团队](/en/agent-teams)队友的显示方式：`auto`（在 tmux 或 iTerm2 中选择分屏窗格，否则进程内）、`in-process` 或 `tmux`。`--teammate-mode` 覆盖此会话的设置。参见[选择显示模式](/en/agent-teams#choose-a-display-mode) | `"in-process"` |
| `terminalProgressBarEnabled` | 在支持的终端中显示终端进度条：ConEmu、Ghostty 1.2.0+ 和 iTerm2 3.6.6+。默认：`true`。在 `/config` 中显示为**终端进度条** | `false` |
| `tui` | 终端 UI 渲染器。使用 `"fullscreen"` 获取无闪烁的[备用屏幕渲染器](/en/fullscreen)和虚拟化回滚。使用 `"default"` 获取经典主屏幕渲染器。通过 `/tui` 设置。你也可以设置 [`CLAUDE_CODE_NO_FLICKER`](/en/env-vars) 环境变量 | `"fullscreen"` |
| `useAutoModeDuringPlan` | 计划模式在自动模式可用时是否使用自动模式语义。默认：`true`。不从共享项目设置读取。在 `/config` 中显示为"在计划期间使用自动模式" | `false` |
| `viewMode` | 启动时的默认对话记录视图模式：`"default"`、`"verbose"` 或 `"focus"`。设置时覆盖粘性的 `/focus` 选择。`--verbose` 标志覆盖此会话的设置 | `"verbose"` |
| `voice` | [语音听写](/en/voice-dictation)设置：`enabled` 开启听写，`mode` 选择 `"hold"` 或 `"tap"`，`autoSubmit` 在 hold 模式下键释放时发送提示。使用 `/voice` 运行时自动写入。需要 Claude.ai 账户 | `{ "enabled": true, "mode": "tap" }` |
| `voiceEnabled` | `voice.enabled` 的旧别名。优先使用 `voice` 对象 | `true` |
| `wslInheritsWindowsSettings` | （仅 Windows 管理设置）为 `true` 时，WSL 上的 Claude Code 除了 `/etc/claude-code` 外还从 Windows 策略链读取管理设置，Windows 源优先。仅在 HKLM 注册表键或 `C:\Program Files\ClaudeCode\managed-settings.json` 中设置时被遵循，两者都需要 Windows 管理员写入。要使 HKCU 策略也在 WSL 上应用，标志还必须在 HKCU 本身中设置。对原生 Windows 无效 | `true` |
### 全局配置设置
这些设置存储在 `~/.claude.json` 中而不是 `settings.json` 中。将它们添加到 `settings.json` 会触发 schema 验证错误。
v2.1.119 之前的版本也将 `autoScrollEnabled`、`editorMode`、`showTurnDuration`、`teammateMode` 和 `terminalProgressBarEnabled` 存储在这里而不是 `settings.json` 中。
| 键 | 描述 | 示例 |
| :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |
| `autoConnectIde` | 当 Claude Code 从外部终端启动时自动连接到运行中的 IDE。默认：`false`。在 VS Code 或 JetBrains 终端外部运行时在 `/config` 中显示为**自动连接到 IDE（外部终端）**。[`CLAUDE_CODE_AUTO_CONNECT_IDE`](/en/env-vars) 环境变量设置时覆盖此设置 | `true` |
| `autoInstallIdeExtension` | 当从 VS Code 终端运行时自动安装 Claude Code IDE 扩展。默认：`true`。在 VS Code 或 JetBrains 终端内运行时在 `/config` 中显示为**自动安装 IDE 扩展**。你也可以设置 [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/en/env-vars) 环境变量 | `false` |
| `externalEditorContext` | 当你使用 `Ctrl+G` 打开外部编辑器时，将 Claude 的上一个响应作为 `#` 注释上下文前置。默认：`false`。在 `/config` 中显示为**在外部编辑器中显示上次响应** | `true` |
| `teammateDefaultModel` | 当生成提示未指定时，[代理团队](/en/agent-teams)队友的默认模型。设置为模型别名如 `"sonnet"`，或 `null` 以继承负责人的当前 `/model` 选择。在 `/config` 中显示为**默认队友模型** | `"sonnet"` |
### 工作树设置
配置 `--worktree` 如何创建和管理工作树。
| 键 | 描述 | 示例 |
| :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------- |
| `worktree.baseRef` | 新工作树从哪个 ref 分支。`"fresh"`（默认）从 `origin/` 分支以获取匹配远程的干净树。`"head"` 从你当前的本地 `HEAD` 分支，因此未推送的提交和功能分支状态存在于工作树中。适用于 `--worktree`、`EnterWorktree` 工具和 subagent 隔离 | `"head"` |
| `worktree.symlinkDirectories` | 从主仓库链接到每个工作树的目录，以避免在磁盘上重复大目录。默认不链接任何目录 | `["node_modules", ".cache"]` |
| `worktree.sparsePaths` | 通过 git sparse-checkout 在每个工作树中检出的目录。仅列出的目录和根级文件被写入磁盘，在大型 monorepos 中更快 | `["packages/my-app", "shared/utils"]` |
| `worktree.bgIsolation` | {/* min-version: 2.1.143 */}[后台会话](/en/agent-view#how-file-edits-are-isolated)的隔离模式。`"worktree"`（默认）在主检出中阻止 `Edit`/`Write`，直到调用 `EnterWorktree`。`"none"` 让后台作业直接编辑工作副本。需要 Claude Code v2.1.143 或更高版本 | `"none"` |
要将 `.env` 等 gitignore 文件复制到新工作树中，使用项目根目录中的 [`.worktreeinclude` 文件](/en/worktrees#copy-gitignored-files-into-worktrees)而不是设置。
### 权限设置
| 键 | 描述 | 示例 |
| :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------ |
| `allow` | 允许工具使用的权限规则数组。参见下面的[权限规则语法](#permission-rule-syntax)了解模式匹配详情 | `[ "Bash(git diff *)" ]` |
| `ask` | 工具使用时要求确认的权限规则数组。参见下面的[权限规则语法](#permission-rule-syntax) | `[ "Bash(git push *)" ]` |
| `deny` | 拒绝工具使用的权限规则数组。使用此排除 Claude Code 访问敏感文件。参见[权限规则语法](#permission-rule-syntax)和 [Bash 权限限制](/en/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |
| `additionalDirectories` | 文件访问的额外[工作目录](/en/permissions#working-directories)。大多数 `.claude/` 配置[不会从这些目录发现](/en/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |
| `defaultMode` | 打开 Claude Code 时的默认[权限模式](/en/permission-modes)。有效值：`default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions`。{/* min-version: 2.1.142 */}从 Claude Code v2.1.142 起，在项目或本地设置（`.claude/settings.json`、`.claude/settings.local.json`）中设置时 `auto` 被忽略，因此仓库不能授予自己自动模式。改为在 `~/.claude/settings.json` 中设置。`--permission-mode` CLI 标志覆盖此会话的设置 | `"acceptEdits"` |
| `disableBypassPermissionsMode` | 设置为 `"disable"` 以阻止 `bypassPermissions` 模式被激活。这禁用 `--dangerously-skip-permissions` 命令行标志。通常放在[管理设置](/en/permissions#managed-settings)中以强制执行组织策略，但在任何作用域下都有效 | `"disable"` |
| `skipDangerousModePermissionPrompt` | 跳过通过 `--dangerously-skip-permissions` 或 `defaultMode: "bypassPermissions"` 进入绕过权限模式前显示的确认提示。在项目设置（`.claude/settings.json`）中设置时被忽略，以防止不受信任的仓库自动绕过提示 | `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 模式的安全限制，参见[权限规则语法](/en/permissions#permission-rule-syntax)。
### 沙箱设置
配置高级沙箱行为。沙箱将 bash 命令与你的文件系统和网络隔离。参见[沙箱](/en/sandboxing)了解详情。
| 键 | 描述 | 示例 |
| :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ |
| `enabled` | 启用 bash 沙箱（macOS、Linux 和 WSL2）。默认：false | `true` |
| `failIfUnavailable` | 如果 `sandbox.enabled` 为 true 但沙箱无法启动（缺少依赖或不支持的平台），在启动时以错误退出。为 false（默认）时，显示警告并以非沙箱方式运行命令。用于需要沙箱作为硬性门控的管理设置部署 | `true` |
| `autoAllowBashIfSandboxed` | 沙箱化时自动批准 bash 命令。默认：true | `true` |
| `excludedCommands` | 应在沙箱外运行的命令 | `["docker *"]` |
| `allowUnsandboxedCommands` | 允许命令通过 `dangerouslyDisableSandbox` 参数在沙箱外运行。设置为 `false` 时，`dangerouslyDisableSandbox` 逃生口被完全禁用，所有命令必须在沙箱中运行（或在 `excludedCommands` 中）。对需要严格沙箱化的企业策略有用。默认：true | `false` |
| `filesystem.allowWrite` | 沙箱化命令可以写入的额外路径。数组跨所有设置作用域合并：用户、项目和管理路径被组合，而不是替换。也与 `Edit(...)` 允许权限规则的路径合并。参见下面的[路径前缀](#sandbox-path-prefixes)。 | `["/tmp/build", "~/.kube"]` |
| `filesystem.denyWrite` | 沙箱化命令不能写入的路径。数组跨所有设置作用域合并。也与 `Edit(...)` 拒绝权限规则的路径合并。 | `["/etc", "/usr/local/bin"]` |
| `filesystem.denyRead` | 沙箱化命令不能读取的路径。数组跨所有设置作用域合并。也与 `Read(...)` 拒绝权限规则的路径合并。 | `["~/.aws/credentials"]` |
| `filesystem.allowRead` | 在 `denyRead` 区域内重新允许读取的路径。优先于 `denyRead`。数组跨所有设置作用域合并。使用此创建仅工作区的读取访问模式。 | `["."]` |
| `filesystem.allowManagedReadPathsOnly` | （仅管理设置）仅遵循管理设置中的 `filesystem.allowRead` 路径。`denyRead` 仍从所有源合并。默认：false | `true` |
| `network.allowUnixSockets` | （仅 macOS）沙箱中可访问的 Unix socket 路径。在 Linux 和 WSL2 上被忽略，那里 seccomp 过滤器无法检查 socket 路径；改为使用 `allowAllUnixSockets`。 | `["~/.ssh/agent-socket"]` |
| `network.allowAllUnixSockets` | 在沙箱中允许所有 Unix socket 连接。在 Linux 和 WSL2 上这是允许 Unix socket 的唯一方式，因为它跳过了否则会阻止 `socket(AF_UNIX, ...)` 调用的 seccomp 过滤器。默认：false | `true` |
| `network.allowLocalBinding` | 允许绑定到 localhost 端口（仅 macOS）。默认：false | `true` |
| `network.allowMachLookup` | 沙箱可以查找的额外 XPC/Mach 服务名称（仅 macOS）。支持单个尾随 `*` 进行前缀匹配。需要通过 XPC 通信的工具（如 iOS 模拟器或 Playwright）使用。 | `["com.apple.coresimulator.*"]` |
| `network.allowedDomains` | 允许出站网络流量的域名数组。支持通配符（例如 `*.example.com`）。 | `["github.com", "*.npmjs.org"]` |
| `network.deniedDomains` | 阻止出站网络流量的域名数组。支持与 `allowedDomains` 相同的通配符语法。两者匹配时优先于 `allowedDomains`。无论 `allowManagedDomainsOnly` 如何都从所有设置源合并。 | `["sensitive.cloud.example.com"]` |
| `network.allowManagedDomainsOnly` | （仅管理设置）仅遵循管理设置中的 `allowedDomains` 和 `WebFetch(domain:...)` 允许规则。用户、项目和本地设置中的域名被忽略。不允许的域名自动阻止而不提示用户。拒绝的域名仍从所有源遵循。默认：false | `true` |
| `network.httpProxyPort` | 如果你想使用自己的代理，使用的 HTTP 代理端口。如果未指定，Claude 将运行自己的代理。 | `8080` |
| `network.socksProxyPort` | 如果你想使用自己的代理，使用的 SOCKS5 代理端口。如果未指定，Claude 将运行自己的代理。 | `8081` |
| `enableWeakerNestedSandbox` | 为非特权 Docker 环境启用较弱的沙箱（仅 Linux 和 WSL2）。**降低安全性。** 默认：false | `true` |
| `enableWeakerNetworkIsolation` | （仅 macOS）允许在沙箱中访问系统 TLS 信任服务（`com.apple.trustd.agent`）。当使用带 MITM 代理和自定义 CA 的 `httpProxyPort` 时，`gh`、`gcloud` 和 `terraform` 等基于 Go 的工具需要此设置来验证 TLS 证书。**降低安全性**，因为打开了潜在的数据泄露路径。默认：false | `true` |
| `bwrapPath` | （仅管理设置，Linux/WSL2）bubblewrap (`bwrap`) 二进制文件的绝对路径。覆盖通过 `PATH` 的自动检测。仅从[管理设置](/en/settings#settings-precedence)中被遵循，不从用户或项目设置。在管理环境中 `bwrap` 安装在非标准位置时有用。 | `/opt/admin/bwrap` |
| `socatPath` | （仅管理设置，Linux/WSL2）用于沙箱网络代理的 `socat` 二进制文件的绝对路径。覆盖通过 `PATH` 的自动检测。仅从管理设置中被遵循。 | `/opt/admin/socat` |
#### 沙箱路径前缀
`filesystem.allowWrite`、`filesystem.denyWrite`、`filesystem.denyRead` 和 `filesystem.allowRead` 中的路径支持这些前缀：
| 前缀 | 含义 | 示例 |
| :----------------- | :---------------------------------------------------------- | :--------------------------------------------------------------------- |
| `/` | 从文件系统根目录开始的绝对路径 | `/tmp/build` 保持 `/tmp/build` |
| `~/` | 相对于主目录 | `~/.kube` 变为 `$HOME/.kube` |
| `./` 或无前缀 | 项目设置相对于项目根目录，用户设置相对于 `~/.claude` | `.claude/settings.json` 中的 `./output` 解析为 `/output` |
旧的 `//path` 绝对路径前缀仍然有效。如果你之前使用单斜杠 `/path` 期望项目相对解析，切换到 `./path`。此语法与 [Read 和 Edit 权限规则](/en/permissions#read-and-edit)不同，后者使用 `//path` 表示绝对路径，`/path` 表示项目相对路径。沙箱文件系统路径使用标准约定：`/tmp/build` 是绝对路径。
**配置示例：**
```json theme={null}
{
"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 提交和拉取请求添加归属。这些分别配置：
* 提交使用 [git trailers](https://git-scm.com/docs/git-interpret-trailers)（如 `Co-Authored-By`）默认，可以自定义或禁用
* 拉取请求描述是纯文本
| 键 | 描述 |
| :------- | :----------------------------------------------------------- |
| `commit` | git 提交的归属，包括任何 trailers。空字符串隐藏提交归属 |
| `pr` | 拉取请求描述的归属。空字符串隐藏拉取请求归属 |
**默认提交归属：**
```text theme={null}
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.6
```
**默认拉取请求归属：**
```text theme={null}
🤖 Generated with [Claude Code](https://claude.com/claude-code)
```
**示例：**
```json theme={null}
{
"attribution": {
"commit": "Generated with AI\n\nCo-Authored-By: AI ",
"pr": ""
}
}
```
`attribution` 设置优先于已弃用的 `includeCoAuthoredBy` 设置。要隐藏所有归属，将 `commit` 和 `pr` 设置为空字符串。
### 文件建议设置
为 `@` 文件路径自动补全配置自定义命令。内置文件建议使用快速文件系统遍历，但大型 monorepos 可能受益于项目特定的索引，如预构建的文件索引或自定义工具。
```json theme={null}
{
"fileSuggestion": {
"type": "command",
"command": "~/.claude/file-suggestion.sh"
}
}
```
该命令使用与[钩子](/en/hooks)相同的环境变量运行，包括 `CLAUDE_PROJECT_DIR`。它通过标准输入接收包含 `query` 字段的 JSON：
```json theme={null}
{"query": "src/comp"}
```
将换行分隔的文件路径输出到标准输出（当前限制为 15 个）：
```text theme={null}
src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx
```
**示例：**
```bash theme={null}
#!/bin/bash
query=$(cat | jq -r '.query')
your-repo-file-index --query "$query" | head -20
```
### 钩子配置
这些设置控制允许运行哪些钩子以及 HTTP 钩子可以访问什么。`allowManagedHooksOnly` 设置只能在[管理设置](#settings-files)中配置。URL 和环境变量白名单可以在任何设置级别设置并跨源合并。
**当 `allowManagedHooksOnly` 为 `true` 时的行为：**
* 管理钩子和 SDK 钩子被加载
* 管理设置 `enabledPlugins` 中强制启用的插件的钩子被加载。这让管理员可以通过组织市场分发已审核的钩子，同时阻止其他所有内容。信任通过完整的 `plugin@marketplace` ID 授予，因此来自不同市场的同名插件仍然被阻止
* 用户钩子、项目钩子和所有其他插件钩子被阻止
**限制 HTTP 钩子 URL：**
限制 HTTP 钩子可以目标指向的 URL。支持 `*` 作为通配符进行匹配。当数组已定义时，目标指向不匹配 URL 的 HTTP 钩子被静默阻止。主机名匹配不区分大小写并忽略尾随的 FQDN 点，匹配 DNS 语义。
```json theme={null}
{
"allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}
```
**限制 HTTP 钩子环境变量：**
限制 HTTP 钩子可以插值到头值中的环境变量名称。每个钩子的有效 `allowedEnvVars` 是其自身列表与此设置的交集。
```json theme={null}
{
"httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}
```
### 使用策略助手计算管理设置
`policyHelper` 设置指向在启动时计算管理设置的可执行文件，因此管理员可以从设备状态、身份或远程服务派生策略，而不是静态文件。从 MDM 或系统 `managed-settings.json` 文件配置它。Claude Code 在 `policyHelper` 出现在任何其他作用域时忽略它，包括用户设置、项目设置、HKCU 注册表配置单元和[服务器管理设置](/en/server-managed-settings)。
该设置接受以下键：
| 键 | 类型 | 描述 |
| ------------------- | ------ | -------------------------------------------------------------------------- |
| `path` | string | 助手可执行文件的绝对路径 |
| `timeoutMs` | number | 等待助手多长时间后将运行视为失败 |
| `refreshIntervalMs` | number | 在后台重新运行助手的频率。设置为 `0` 以禁用刷新，或至少 `60000` |
助手将 JSON 信封写入标准输出。将设置放在 `managedSettings` 键下而不是顶层，因为裸设置对象解析时 `managedSettings` 未定义且不应用任何内容：
```json theme={null}
{
"managedSettings": {
"permissions": { "deny": ["Read(//etc/secrets/**)"] }
},
"claudeMd": "# Organization context\n...",
"appendSystemPrompt": "Always cite the internal style guide."
}
```
当助手发出 `managedSettings` 时，该对象替换基于文件的管理设置用于本次运行。当助手在启动时以非零退出时，Claude Code 打印错误并拒绝启动，因此需要中断弹性的助手应从自己的缓存提供服务并以 `0` 退出。
### 设置优先级
设置按优先级顺序应用。从最高到最低：
1. **管理设置**（[服务器管理](/en/server-managed-settings)、[MDM/OS 级策略](#configuration-scopes)或[管理设置](/en/settings#settings-files)）
* IT 通过服务器传递、MDM 配置文件、注册表策略或管理设置文件部署的策略
* 不能被任何其他级别覆盖，包括命令行参数
* 在管理层内，优先级为：服务器管理 > MDM/OS 级策略 > 基于文件的（`managed-settings.d/*.json` + `managed-settings.json`）> HKCU 注册表（仅 Windows）。仅使用一个管理源；源不跨层合并。在基于文件的层内，drop-in 文件和基础文件合并在一起。
* 嵌入主机如 Claude Desktop 可以通过 SDK `managedSettings` 选项提供策略。默认情况下，当存在任何管理层时这被忽略。管理员可以通过将 [`parentSettingsBehavior`](#available-settings) 设置为 `"merge"` 来选择加入。嵌入器的值经过过滤，可以收紧管理策略但不能放松。
2. **命令行参数**
* 特定会话的临时覆盖。通过 `--settings ` 传递的 JSON 使用与其他层相同的规则与基于文件的设置合并：此处设置的键覆盖本地、项目或用户设置中的相同键，省略的键保留较低层的值
3. **本地项目设置**（`.claude/settings.local.json`）
* 个人项目特定设置
4. **共享项目设置**（`.claude/settings.json`）
* 源代码控制中的团队共享项目设置
5. **用户设置**（`~/.claude/settings.json`）
* 个人全局设置
此层次结构确保组织策略始终被强制执行，同时仍允许团队和个人自定义他们的体验。无论你从 CLI、[VS Code 扩展](/en/vs-code)还是 [JetBrains IDE](/en/jetbrains) 运行 Claude Code，相同的优先级都适用。
例如，如果你的用户设置将 `permissions.defaultMode` 设置为 `acceptEdits` 而项目的共享设置将其设置为 `default`，则应用项目值。下面的示例涵盖了数组值设置（如权限规则）如何组合。
**数组设置跨作用域合并。** 当相同的数组值设置（如 `sandbox.filesystem.allowWrite` 或 `permissions.allow`）出现在多个作用域中时，数组被**连接和去重**，而不是替换。这意味着较低优先级的作用域可以添加条目而不会覆盖较高优先级作用域设置的条目，反之亦然。例如，如果管理设置将 `allowWrite` 设置为 `["/opt/company-tools"]` 而用户添加 `["~/.kube"]`，则两个路径都包含在最终配置中。
### 验证活跃设置
在 Claude Code 内运行 `/status` 以查看哪些设置源处于活跃状态。状态标签包含一个 `Setting sources` 行，列出了 Claude Code 为当前会话加载的每个层，如 `User settings` 或 `Project local settings`。当[管理设置](/en/managed-settings)生效时，条目在括号中显示传递频道，例如 `Enterprise managed settings (remote)`、`(plist)`、`(HKLM)`、`(HKCU)` 或 `(file)`。层仅在该源加载了至少一个键时出现在列表中，因此空列表意味着未找到设置源。
`Setting sources` 行确认正在读取哪些源。它不显示哪个层提供了每个单独的键。同一对话框中的 Config 标签是固定开关集（如主题和详细输出）的编辑器，不是你的 `settings.json` 内容的视图。如果设置文件包含错误，如无效 JSON 或验证失败的值，`/status` 会报告问题以便你修复。
### 关于配置系统的关键要点
* **记忆文件（`CLAUDE.md`）**：包含 Claude 在启动时加载的指令和上下文
* **设置文件（JSON）**：配置权限、环境变量和工具行为
* **技能**：可以通过 `/skill-name` 调用或由 Claude 自动加载的自定义提示
* **MCP 服务器**：用额外的工具和集成扩展 Claude Code
* **优先级**：较高层级的配置（管理）覆盖较低层级的（用户/项目）
* **继承**：设置跨作用域合并；来自较高优先级作用域的标量值覆盖，数组连接
### 系统提示
Claude Code 的内部系统提示未发布。要添加自定义指令，使用 `CLAUDE.md` 文件或 `--append-system-prompt` 标志。
### 排除敏感文件
要阻止 Claude Code 访问包含敏感信息（如 API 密钥、密钥和环境文件）的文件，使用 `.claude/settings.json` 文件中的 `permissions.deny` 设置：
```json theme={null}
{
"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 文档](/en/sub-agents)中了解更多关于创建和使用 subagents 的信息。
## 插件配置
Claude Code 支持插件系统，让你可以通过技能、代理、钩子和 MCP 服务器扩展功能。插件通过市场分发，可以在用户和仓库级别配置。
### 插件设置
`settings.json` 中的插件相关设置：
```json theme={null}
{
"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-settings.json`）：组织范围的策略覆盖，阻止所有作用域的安装并从市场中隐藏插件
项目设置优先于用户设置，因此在 `~/.claude/settings.json` 中将插件设置为 `false` 不会禁用项目 `.claude/settings.json` 启用的插件。要在你的机器上退出项目启用的插件，改为在 `.claude/settings.local.json` 中将其设置为 `false`。
管理设置强制启用的插件不能以这种方式禁用，因为管理设置覆盖本地设置。
**示例**：
```json theme={null}
{
"enabledPlugins": {
"code-formatter@team-tools": true,
"deployment-tools@team-tools": true,
"experimental-features@personal": false
}
}
```
#### `extraKnownMarketplaces`
定义应为仓库提供的额外市场。通常在仓库级设置中使用，以确保团队成员可以访问所需的插件来源。
**当仓库包含 `extraKnownMarketplaces` 时**：
1. 团队成员在信任文件夹时被提示安装市场
2. 然后团队成员被提示安装来自该市场的插件
3. 用户可以跳过不需要的市场或插件（存储在用户设置中）
4. 安装遵循信任边界并需要明确同意
**示例**：
```json theme={null}
{
"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`）
每个市场条目还接受可选的 `autoUpdate` 布尔值。在 `source` 旁边设置 `"autoUpdate": true` 让 Claude Code 在启动时刷新该市场并更新其已安装的插件。省略时，官方 Anthropic 市场默认为 `true`，所有其他市场默认为 `false`。参见[配置自动更新](/en/discover-plugins#configure-auto-updates)。
使用 `source: 'settings'` 声明一小组内联插件而无需设置托管市场仓库。此处列出的插件必须引用外部来源如 GitHub 或 npm。你仍然需要在 `enabledPlugins` 中分别启用每个插件。
```json theme={null}
{
"extraKnownMarketplaces": {
"team-tools": {
"source": {
"source": "settings",
"name": "team-tools",
"plugins": [
{
"name": "code-formatter",
"source": {
"source": "github",
"repo": "acme-corp/code-formatter"
}
}
]
}
}
}
}
```
#### `strictKnownMarketplaces`
**仅管理设置**：控制用户可以从哪些插件市场来源添加和安装插件。此设置只能在[管理设置](/en/settings#settings-files)中配置，为管理员提供对市场来源的严格控制。
**管理设置文件位置**：
* **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-settings.json`）中可用
* 不能被用户或项目设置覆盖（最高优先级）
* 在网络/文件系统操作之前强制执行（被阻止的来源从不执行）
* 对来源规范使用精确匹配（包括 `ref`、git 来源的 `path`），但 `hostPattern` 和 `pathPattern` 使用正则表达式匹配
**白名单行为**：
* `undefined`（默认）：无限制 - 用户可以添加任何市场
* 空数组 `[]`：完全锁定 - 用户不能添加任何新市场
* 来源列表：用户只能添加精确匹配的市场
**所有支持的来源类型**：
白名单支持多种市场来源类型。大多数来源使用精确匹配，而 `hostPattern` 和 `pathPattern` 分别对市场主机和文件系统路径使用正则表达式匹配。
1. **GitHub 仓库**：
```json theme={null}
{ "source": "github", "repo": "acme-corp/approved-plugins" }
{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }
```
字段：`repo`（必需）、`ref`（可选：分支/标签/SHA）、`path`（可选：子目录）
2. **Git 仓库**：
```json theme={null}
{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }
{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }
{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }
```
字段：`url`（必需）、`ref`（可选：分支/标签/SHA）、`path`（可选：子目录）
3. **基于 URL 的市场**：
```json theme={null}
{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }
{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }
```
字段：`url`（必需）、`headers`（可选：用于认证访问的 HTTP 头）
基于 URL 的市场仅下载 `marketplace.json` 文件。它们不从服务器下载插件文件。基于 URL 的市场中的插件必须使用外部来源（GitHub、npm 或 git URL）而不是相对路径。对于使用相对路径的插件，使用基于 Git 的市场。参见[故障排除](/en/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)了解详情。
4. **NPM 包**：
```json theme={null}
{ "source": "npm", "package": "@acme-corp/claude-plugins" }
{ "source": "npm", "package": "@acme-corp/approved-marketplace" }
```
字段：`package`（必需，支持 scoped 包）
5. **文件路径**：
```json theme={null}
{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }
```
字段：`path`（必需：marketplace.json 文件的绝对路径）
6. **目录路径**：
```json theme={null}
{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }
```
字段：`path`（必需：包含 `.claude-plugin/marketplace.json` 的目录的绝对路径）
7. **主机名模式匹配**：
```json theme={null}
{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com$" }
```
字段：`hostPattern`（必需：匹配市场主机的正则表达式模式）
当你想允许来自特定主机的所有市场而不逐一列举每个仓库时，使用主机名模式匹配。这对于拥有内部 GitHub Enterprise 或 GitLab 服务器（开发者创建自己的市场）的组织很有用。
按来源类型的主机提取：
* `github`：始终匹配 `github.com`
* `git`：从 URL 提取主机名（支持 HTTPS 和 SSH 格式）
* `url`：从 URL 提取主机名
* `npm`、`file`、`directory`：不支持主机名模式匹配
8. **路径模式匹配**：
```json theme={null}
{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }
{ "source": "pathPattern", "pathPattern": ".*" }
```
字段：`pathPattern`（必需：与 `file` 和 `directory` 来源的 `path` 字段匹配的正则表达式模式）
使用路径模式匹配在对网络来源使用 `hostPattern` 限制的同时允许基于文件系统的市场。设置 `".*"` 以允许所有本地路径，或使用更窄的模式限制到特定目录。
**配置示例**：
示例：仅允许特定市场：
```json theme={null}
{
"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"
}
]
}
```
示例 - 禁用所有市场添加：
```json theme={null}
{
"strictKnownMarketplaces": []
}
```
示例：允许来自内部 git 服务器的所有市场：
```json theme={null}
{
"strictKnownMarketplaces": [
{
"source": "hostPattern",
"hostPattern": "^github\\.example\\.com$"
}
]
}
```
**精确匹配要求**：
市场来源必须**精确匹配**才能允许用户的添加。对于基于 git 的来源（`github` 和 `git`），这包括所有可选字段：
* `repo` 或 `url` 必须精确匹配
* `ref` 字段必须精确匹配（或两者都未定义）
* `path` 字段必须精确匹配（或两者都未定义）
**不匹配**的来源示例：
```json theme={null}
// 这些是不同的来源：
{ "source": "github", "repo": "acme-corp/plugins" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }
// 这些也是不同的：
{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }
{ "source": "github", "repo": "acme-corp/plugins" }
```
**与 `extraKnownMarketplaces` 比较**：
| 方面 | `strictKnownMarketplaces` | `extraKnownMarketplaces` |
| ------------------- | ------------------------------------ | ------------------------------------ |
| **目的** | 组织策略强制执行 | 团队便利性 |
| **设置文件** | 仅 `managed-settings.json` | 任何设置文件 |
| **行为** | 阻止非白名单添加 | 自动安装缺失的市场 |
| **强制执行时间** | 在网络/文件系统操作之前 | 在用户信任提示之后 |
| **可覆盖** | 否（最高优先级） | 是（被更高优先级设置覆盖） |
| **来源格式** | 直接来源对象 | 带嵌套来源的命名市场 |
| **用例** | 合规、安全限制 | 入职、标准化 |
**格式差异**：
`strictKnownMarketplaces` 使用直接来源对象：
```json theme={null}
{
"strictKnownMarketplaces": [
{ "source": "github", "repo": "acme-corp/plugins" }
]
}
```
`extraKnownMarketplaces` 需要命名的市场：
```json theme={null}
{
"extraKnownMarketplaces": {
"acme-tools": {
"source": { "source": "github", "repo": "acme-corp/plugins" }
}
}
}
```
**同时使用两者**：
`strictKnownMarketplaces` 是策略门控：它控制用户可以添加什么但不注册任何市场。要既限制又为所有用户预注册市场，在 `managed-settings.json` 中同时设置：
```json theme={null}
{
"strictKnownMarketplaces": [
{ "source": "github", "repo": "acme-corp/plugins" }
],
"extraKnownMarketplaces": {
"acme-tools": {
"source": { "source": "github", "repo": "acme-corp/plugins" }
}
}
}
```
仅设置 `strictKnownMarketplaces` 时，用户仍然可以通过 `/plugin marketplace add` 手动添加允许的市场，但它不会自动可用。
**重要说明**：
* 限制在任何网络请求或文件系统操作之前检查
* 被阻止时，用户看到明确的错误消息，表明来源被管理策略阻止
* 限制在市场添加和插件安装、更新、刷新和自动更新时强制执行。在策略设置之前添加的市场一旦其来源不再匹配白名单，就不能用于安装或更新插件
* 管理设置具有最高优先级，不能被覆盖
参见[管理市场限制](/en/plugin-marketplaces#managed-marketplace-restrictions)了解面向用户的文档。
#### `strictPluginOnlyCustomization`
**仅管理设置**：阻止来自用户和项目来源的技能、代理、钩子和 MCP 服务器，使它们只能来自插件或管理设置。将其与 `strictKnownMarketplaces` 结合以控制完整的自定义供应链：市场白名单控制用户可以安装哪些插件，此设置阻止不来自插件或管理设置的所有内容。
`strictPluginOnlyCustomization` 需要 Claude Code v2.1.82 或更高版本。早期版本忽略该键并继续加载用户和项目自定义，因此锁定在客户端更新之前不会被强制执行。
值为 `true` 以锁定所有四个表面，或命名要锁定的表面的数组：
```json theme={null}
{
"strictPluginOnlyCustomization": ["skills", "hooks"]
}
```
对于每个锁定的表面，Claude Code 跳过用户级和项目级来源，仅加载插件提供的和管理来源：
| 表面 | 锁定时阻止 | 仍然加载 |
| :------- | :-------------------------------------------------- | :--------------------------------------------------------- |
| `skills` | `~/.claude/skills/`、`.claude/skills/` | 插件技能、内置技能、管理策略目录中的技能 |
| `agents` | `~/.claude/agents/`、`.claude/agents/` | 插件代理、内置代理、管理策略目录中的代理 |
| `hooks` | 用户、项目和本地 `settings.json` 中的钩子 | 插件钩子、管理设置中的钩子 |
| `mcp` | `~/.claude.json` 和 `.mcp.json` 中的服务器 | 插件 MCP 服务器、[`managed-mcp.json`](/en/managed-mcp) 服务器 |
Claude Code 版本不识别的表面名称被忽略而不是使设置文件失败，因此你可以在所有客户端更新之前添加新的表面名称。
### 管理插件
使用 `/plugin` 命令交互式管理插件：
* 浏览市场的可用插件
* 安装/卸载插件
* 启用/禁用插件
* 查看插件详情（提供的技能、代理、钩子）
* 添加/移除市场
在[插件文档](/en/plugins)中了解更多关于插件系统的信息。
## 环境变量
环境变量让你无需编辑设置文件即可控制 Claude Code 行为。任何变量也可以在 [`settings.json`](#available-settings) 的 `env` 键下配置，以应用于每个会话或向你的团队推出。
参见[环境变量参考](/en/env-vars)了解完整列表。
## Claude 可用的工具
Claude Code 可以访问一组用于读取、编辑、搜索、运行命令和编排 subagents 的工具。工具名称是你在权限规则和钩子匹配器中使用的确切字符串。
参见[工具参考](/en/tools-reference)了解完整列表和 Bash 工具行为详情。
## 另请参阅
* [权限](/en/permissions)：权限系统、规则语法、工具特定模式和管理策略
* [认证](/en/authentication)：设置用户对 Claude Code 的访问
* [调试你的配置](/en/debug-your-config)：诊断设置、钩子或 MCP 服务器未生效的原因
* [安装和登录故障排除](/en/troubleshoot-install)：安装、认证和平台问题