Documentation — Spybara

admin-setup.md +3 −2

Details

63 63

64默认情况下，WSL 仅读取 `/etc/claude-code` 处的 Linux 文件路径。要将您的 Windows 注册表和 `C:\Program Files\ClaudeCode` 策略扩展到同一台机器上的 WSL，请在这些仅限管理员的 Windows 来源之一中设置 [`wslInheritsWindowsSettings: true`](/zh-CN/settings#available-settings)。64默认情况下，WSL 仅读取 `/etc/claude-code` 处的 Linux 文件路径。要将您的 Windows 注册表和 `C:\Program Files\ClaudeCode` 策略扩展到同一台机器上的 WSL，请在这些仅限管理员的 Windows 来源之一中设置 [`wslInheritsWindowsSettings: true`](/zh-CN/settings#available-settings)。

65 65

66无论您选择哪种机制，托管值都优先于用户和项目设置。数组设置（如 `permissions.allow` 和 `permissions.deny`）合并来自所有源的条目，因此开发人员可以扩展托管列表但不能从中删除。66无论您选择哪种机制，托管值都优先于用户和项目设置。数组设置（如 `permissions.allow` 和 `permissions.deny`）合并来自所有源的条目，因此开发人员可以扩展托管列表但不能从中删除，但有 [两个例外](/zh-CN/settings#settings-precedence)，其中托管值替换较低层而不是合并：`fallbackModel` 和 `availableModels`。

67 67

68请参阅 [Server-managed settings](/zh-CN/server-managed-settings) 和 [Settings files and precedence](/zh-CN/settings#settings-files)。68请参阅 [Server-managed settings](/zh-CN/server-managed-settings) 和 [Settings files and precedence](/zh-CN/settings#settings-files)。

69 69

74托管设置可以锁定工具、沙箱执行、限制 MCP 服务器和插件源，以及控制哪些 hooks 运行。每一行都是一个控制表面，具有驱动它的设置键。74托管设置可以锁定工具、沙箱执行、限制 MCP 服务器和插件源，以及控制哪些 hooks 运行。每一行都是一个控制表面，具有驱动它的设置键。

75 75

76| 控制 | 它的作用 | 关键设置 |76| 控制 | 它的作用 | 关键设置 |

77| :---------------------------------------------------------------------------------------- | :------------------------------------------------------ | :---------------------------------------------------------------------------------------------- |77| :---------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------- |

79| [Permission lockdown](/zh-CN/permissions#managed-only-settings) | 仅托管权限规则适用；禁用 `--dangerously-skip-permissions` | `allowManagedPermissionRulesOnly`、`permissions.disableBypassPermissionsMode` |79| [Permission lockdown](/zh-CN/permissions#managed-only-settings) | 仅托管权限规则适用；禁用 `--dangerously-skip-permissions` | `allowManagedPermissionRulesOnly`、`permissions.disableBypassPermissionsMode` |

87| [Model restrictions](/zh-CN/model-config#restrict-model-selection) | 限制用户可以选择的模型，并可选择将允许列表也应用于默认模型选择。请参阅 [surface coverage](/zh-CN/model-config#surface-coverage) 了解此设置如何到达 CLI、web 和 IDE | `availableModels`、`enforceAvailableModels` |

89 90

advisor.md +4 −4

Details

52/advisor opus52/advisor opus

53```53```

54 54

55您的选择被保存到用户设置中的 `advisorModel`，并在会话之间持久化。如果您当前的主模型不支持顾问，选择仍然被保存，并在您使用[`/model`](/zh-CN/model-config#setting-your-model)切换到[兼容的主模型](#choose-an-advisor-model)时激活。55您的选择被保存到用户设置中的 `advisorModel`，并在会话之间持久化。如果您的组织的 [`availableModels`](/zh-CN/model-config#restrict-model-selection) 允许列表排除了保存的顾问模型，则在您使用 `/advisor` 选择允许的模型之前，顾问不会被调用。如果您当前的主模型不支持顾问，选择仍然被保存，并在您使用 [`/model`](/zh-CN/model-config#setting-your-model) 切换到[兼容的主模型](#choose-an-advisor-model)时激活。

56 56

57<h3 id="set-advisormodel-in-settings">57<h3 id="set-advisormodel-in-settings">

58 在设置中设置 `advisorModel`58 在设置中设置 `advisorModel`

76claude --advisor opus76claude --advisor opus

77```77```

78 78

~~79该标志在该会话中优先于 `advisorModel` 设置。与保存非活动选择的 `/advisor` 不同，如果会话的主模型不支持顾问，该标志会以错误退出。~~79该标志在该会话中优先于 `advisorModel` 设置。如果会话的主模型不支持顾问，或者请求的顾问模型被您的组织的 [`availableModels`](/zh-CN/model-config#restrict-model-selection) 允许列表排除，它会以错误退出。

80 80

81<h2 id="choose-an-advisor-model">81<h2 id="choose-an-advisor-model">

82 选择顾问模型82 选择顾问模型

182顾问是结合模型优势的几种方式之一。根据您希望何时涉及第二个模型来选择。182顾问是结合模型优势的几种方式之一。根据您希望何时涉及第二个模型来选择。

183 183

184| 方法 | 更强的模型何时运行 | 如何启动 |184| 方法 | 更强的模型何时运行 | 如何启动 |

185| -------------------------------------------------------- | ----------------------- | ----------------- |185| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------- |

190 190

agent-sdk/claude-code-features.md +3 −3

Details

86`settingSources` 涵盖用户、项目和本地设置。无论其值如何，都会读取一些输入：86`settingSources` 涵盖用户、项目和本地设置。无论其值如何，都会读取一些输入：

87 87

88| 输入 | 行为 | 禁用方式 |88| 输入 | 行为 | 禁用方式 |

89| :------------------------------------------------------------- | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |89| :------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |

93| [claude.ai MCP 连接器](/zh-CN/mcp#use-mcp-servers-from-claude-ai) | 当活跃身份验证方法是 claude.ai 订阅时加载。传递 `mcpServers: {}` 不会抑制它们 | 设置 `strictMcpConfig: true`、[`disableClaudeAiConnectors: true`](/zh-CN/mcp#disable-claude-ai-connectors) 在设置中，或在 `env` 中设置 `ENABLE_CLAUDEAI_MCP_SERVERS=false` |93| [claude.ai MCP 连接器](/zh-CN/mcp#use-mcp-servers-from-claude-ai) | 当活跃身份验证方法是 claude.ai 订阅时加载。传递 `mcpServers: {}` 不会抑制它们 | 设置 `strictMcpConfig: true`、[`disableClaudeAiConnectors: true`](/zh-CN/mcp#disable-claude-ai-connectors) 在设置中，或在 `env` 中设置 `ENABLE_CLAUDEAI_MCP_SERVERS=false` |

94 94

95<Warning>95<Warning>

96 不要依赖默认 `query()` 选项进行多租户隔离。因为上述输入无论 `settingSources` 如何都会被读取，SDK 进程可能会获取主机级配置和按目录内存。对于多租户部署，在自己的文件系统中运行每个租户，并设置 `settingSources: []` 加上 `env` 中的 `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`。请参阅 [安全部署](/zh-CN/agent-sdk/secure-deployment)。96 不要依赖默认 `query()` 选项进行多租户隔离。因为上述输入无论 `settingSources` 如何都会被读取，SDK 进程可能会获取主机级配置和按目录内存。对于多租户部署，在自己的文件系统中运行每个租户，并设置 `settingSources: []` 加上 `env` 中的 `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`。[服务器管理的设置](/zh-CN/server-managed-settings)在进程使用组织凭证进行身份验证时获取；文件系统隔离不会删除它们。请参阅[安全部署](/zh-CN/agent-sdk/secure-deployment)。

97</Warning>97</Warning>

98 98

99<h2 id="project-instructions-claude-md-and-rules">99<h2 id="project-instructions-claude-md-and-rules">

agent-sdk/python.md +3 −3

Details

897```897```

898 898

899| 属性 | 类型 | 默认值 | 描述 |899| 属性 | 类型 | 默认值 | 描述 |

900| :---------------------------- | :--------------------------------------------------------------------------------------- | :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |900| :---------------------------- | :--------------------------------------------------------------------------------------- | :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

901| `tools` | `list[str] \| ToolsPreset \| None` | `None` | 工具配置。使用 `{"type": "preset", "preset": "claude_code"}` 获取 Claude Code 的默认工具 |901| `tools` | `list[str] \| ToolsPreset \| None` | `None` | 工具配置。使用 `{"type": "preset", "preset": "claude_code"}` 获取 Claude Code 的默认工具 |

903| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | 系统提示配置。传递字符串以获取自定义提示，或使用 `{"type": "preset", "preset": "claude_code"}` 获取 Claude Code 的系统提示。添加 `"append"` 以扩展预设 |903| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | 系统提示配置。传递字符串以获取自定义提示，或使用 `{"type": "preset", "preset": "claude_code"}` 获取 Claude Code 的系统提示。添加 `"append"` 以扩展预设 |

936| `setting_sources` | `list[SettingSource] \| None` | `None`（CLI 默认值：所有源） | 控制加载哪些文件系统设置。传递 `[]` 以禁用用户、项目和本地设置。无论如何都会加载托管策略设置。见 [使用 Claude Code 功能](/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) |936| `setting_sources` | `list[SettingSource] \| None` | `None`（CLI 默认值：所有源） | 控制加载哪些文件系统设置。传递 `[]` 以禁用用户、项目和本地设置。无论如何都会加载托管策略设置；当会话使用组织凭证在[符合条件的配置](/zh-CN/server-managed-settings#platform-availability)上进行身份验证时，会获取服务器管理的设置。见 [使用 Claude Code 功能](/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) 了解无论此选项如何都会读取的输入，以及如何禁用它们 |

1022 默认行为1022 默认行为

1023</h4>1023</h4>

1024 1024

1025当 `setting_sources` 被省略或为 `None` 时，`query()` 加载与 Claude Code CLI 相同的文件系统设置：用户、项目和本地。无论如何都会加载托管策略设置。见 [settingSources 不控制什么](/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) 了解无论此选项如何都会读取的输入，以及如何禁用它们。1025当 `setting_sources` 被省略或为 `None` 时，`query()` 加载与 Claude Code CLI 相同的文件系统设置：用户、项目和本地。无论如何都会加载托管策略设置；当会话使用组织凭证在[符合条件的配置](/zh-CN/server-managed-settings#platform-availability)上进行身份验证时，会获取服务器管理的设置。见 [settingSources 不控制什么](/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) 了解无论此选项如何都会读取的输入，以及如何禁用它们。

1026 1026

1027<h4 id="why-use-setting_sources">1027<h4 id="why-use-setting_sources">

1028 为什么使用 setting\_sources1028 为什么使用 setting\_sources

agent-sdk/typescript.md +1 −1

Details

765 默认行为765 默认行为

766</h4>766</h4>

767 767

768当 `settingSources` 被省略或 `undefined` 时，`query()` 加载与 Claude Code CLI 相同的文件系统设置：用户、项目和本地。在所有情况下都会加载托管策略设置。请参阅[settingSources 不控制的内容](/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control)了解无论此选项如何都会读取的输入，以及如何禁用它们。768当 `settingSources` 被省略或 `undefined` 时，`query()` 加载与 Claude Code CLI 相同的文件系统设置：用户、项目和本地。在所有情况下都会加载托管策略设置；当会话使用组织凭证在[符合条件的配置](/zh-CN/server-managed-settings#platform-availability)上进行身份验证时，会获取服务器管理的设置。请参阅[settingSources 不控制的内容](/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control)了解无论此选项如何都会读取的输入，以及如何禁用它们。

769 769

770<h4 id="why-use-settingsources">770<h4 id="why-use-settingsources">

771 为什么使用 settingSources771 为什么使用 settingSources

amazon-bedrock.md +2 −2

Details

477export CLAUDE_CODE_USE_MANTLE=1477export CLAUDE_CODE_USE_MANTLE=1

478```478```

479 479

480要在 `/model` 选择器中显示 Mantle 模型，请在您的[设置文件](/zh-CN/settings)中的 `availableModels` 中列出其 ID。此设置也将选择器限制为列出的条目，因此包括您想保持可用的每个别名：480要在 `/model` 选择器中显示 Mantle 模型，请在您的[设置文件](/zh-CN/settings)中的 `availableModels` 中列出其 ID。此设置也将选择器限制为列出的条目。列出 `anthropic.claude-haiku-4-5` 会从选择器中移除裸 `haiku` 别名，因此也要列出版本前缀或您想保持可选择的版本的完整 ID。请参阅[合并行为](/zh-CN/model-config#merge-behavior)：

481 481

482```json theme={null}482```json theme={null}

483{483{

484 "availableModels": ["opus", "sonnet", "haiku", "anthropic.claude-haiku-4-5"]484 "availableModels": ["opus", "sonnet", "claude-haiku-4-5", "anthropic.claude-haiku-4-5"]

485}485}

486```486```

487 487

claude-code-on-the-web.md +5 −4

Details

63 云会话中可用的内容63 云会话中可用的内容

64</h3>64</h3>

65 65

~~66云会话从你的存储库的新克隆开始。任何提交到存储库的内容都可用。任何你仅在自己的机器上安装或配置的内容都不可用。~~66云会话从你的存储库的新克隆开始。任何提交到存储库的内容都可用。任何你仅在自己的机器上安装或配置的内容都不可用；你的组织的策略通过[服务器管理的设置](/zh-CN/server-managed-settings)单独到达。

67 67

68| | 在云会话中可用 | 原因 |68| | 在云会话中可用 | 原因 |

~~69| :----------------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------- |~~69| :----------------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

70| 你的存储库的 `CLAUDE.md` | 是 | 克隆的一部分 |70| 你的存储库的 `CLAUDE.md` | 是 | 克隆的一部分 |

71| 你的存储库的 `.claude/settings.json` hooks | 是 | 克隆的一部分 |71| 你的存储库的 `.claude/settings.json` hooks | 是 | 克隆的一部分 |

72| 你的存储库的 `.mcp.json` MCP 服务器 | 是 | 克隆的一部分 |72| 你的存储库的 `.mcp.json` MCP 服务器 | 是 | 克隆的一部分 |

73| 你的存储库的 `.claude/rules/` | 是 | 克隆的一部分 |73| 你的存储库的 `.claude/rules/` | 是 | 克隆的一部分 |

74| 你的存储库的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 克隆的一部分 |74| 你的存储库的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 克隆的一部分 |

75| 在 `.claude/settings.json` 中声明的插件 | 是 | 在会话启动时从你声明的[市场](/zh-CN/plugin-marketplaces)安装。需要网络访问才能到达市场源 |75| 在 `.claude/settings.json` 中声明的插件 | 是 | 在会话启动时从你声明的[市场](/zh-CN/plugin-marketplaces)安装。需要网络访问才能到达市场源 |

76| 你的组织的[服务器管理的设置](/zh-CN/server-managed-settings) | 是 | 在会话启动时从 Anthropic 的服务器获取。有关如何在云会话中强制执行 `availableModels` 的信息，请参阅[表面覆盖](/zh-CN/model-config#surface-coverage)。通过 MDM 或托管设置文件部署到你的设备的设置不适用，因为会话在 Anthropic 管理的 VM 上运行 |

76| 你的用户 `~/.claude/CLAUDE.md` | 否 | 存在于你的机器上，不在存储库中 |77| 你的用户 `~/.claude/CLAUDE.md` | 否 | 存在于你的机器上，不在存储库中 |

77| 你的用户 `~/.claude/skills/`、`~/.claude/agents/`、`~/.claude/commands/` | 否 | 存在于你的机器上，不在存储库中。改为将它们提交到存储库的 `.claude/` 目录。你在 claude.ai 上启用的技能会自动加载到云会话中 |78| 你的用户 `~/.claude/skills/`、`~/.claude/agents/`、`~/.claude/commands/` | 否 | 存在于你的机器上，不在存储库中。改为将它们提交到存储库的 `.claude/` 目录。你在 claude.ai 上启用的技能会自动加载到云会话中 |

78| 仅在你的用户设置中启用的插件 | 否 | 用户范围的 `enabledPlugins` 存在于 `~/.claude/settings.json` 中。改为在存储库的 `.claude/settings.json` 中声明它们 |79| 仅在你的用户设置中启用的插件 | 否 | 用户范围的 `enabledPlugins` 存在于 `~/.claude/settings.json` 中。改为在存储库的 `.claude/settings.json` 中声明它们 |

80| 静态 API 令牌和凭证 | 否 | 尚不存在专用的秘密存储。见下文 |81| 静态 API 令牌和凭证 | 否 | 尚不存在专用的秘密存储。见下文 |

81| 交互式身份验证，如 AWS SSO | 否 | 不支持。SSO 需要无法在云会话中运行的基于浏览器的登录 |82| 交互式身份验证，如 AWS SSO | 否 | 不支持。SSO 需要无法在云会话中运行的基于浏览器的登录 |

82 83

83要使配置在云会话中可用，请将其提交到存储库。尚不存在专用的秘密存储。环境变量和设置脚本都存储在环境配置中，对任何可以编辑该环境的人可见。如果你需要云会话中的秘密，请将它们添加为环境变量，并考虑这种可见性。84要使你自己的配置在云会话中可用，请将其提交到存储库；组织策略通过[服务器管理的设置](/zh-CN/server-managed-settings)单独到达。尚不存在专用的秘密存储。环境变量和设置脚本都存储在环境配置中，对任何可以编辑该环境的人可见。如果你需要云会话中的秘密，请将它们添加为环境变量，并考虑这种可见性。

84 85

85<h3 id="installed-tools">86<h3 id="installed-tools">

86 已安装的工具87 已安装的工具

245| 运行 | 在 Claude Code 启动之前，仅在新会话上 | 在 Claude Code 启动之后，在每个会话上，包括已恢复的 |246| 运行 | 在 Claude Code 启动之前，仅在新会话上 | 在 Claude Code 启动之后，在每个会话上，包括已恢复的 |

246| 范围 | 仅云环境 | 本地和云 |247| 范围 | 仅云环境 | 本地和云 |

247 248

248SessionStart hooks 也可以在你的用户级 `~/.claude/settings.json` 中本地定义，但用户级设置不会传送到云会话。在云中，仅提交到存储库的 hooks 运行。249SessionStart hooks 也可以在你的用户级 `~/.claude/settings.json` 中本地定义，但用户级设置不会传送到云会话。在云中，hooks 来自存储库和你的组织的[服务器管理设置](/zh-CN/server-managed-settings)。

249 250

250<h3 id="install-dependencies-with-a-sessionstart-hook">251<h3 id="install-dependencies-with-a-sessionstart-hook">

251 使用 SessionStart hook 安装依赖252 使用 SessionStart hook 安装依赖

commands.md +1 −1

Details

88| `/ide` | 管理 IDE 集成并显示状态 |88| `/ide` | 管理 IDE 集成并显示状态 |

desktop.md +8 −4

Details

691 托管设置691 托管设置

692</h3>692</h3>

693 693

694托管设置覆盖项目和用户设置，并在 Desktop 生成 CLI 会话时应用。你可以在你的组织的[托管设置](/zh-CN/settings#settings-precedence)文件中设置这些键，或通过管理员控制台远程推送它们。694托管设置覆盖项目和用户设置，并应用于 Desktop 中的 Claude Code 会话。你可以在你的组织的[托管设置](/zh-CN/settings#settings-precedence)文件中设置这些键，或通过管理员控制台远程推送它们。

695 695

696| 键 | 描述 |696| 键 | 描述 |

697| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |697| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

699| `disableAutoMode` | 设置为 `"disable"` 以防止用户启用 [Auto](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 模式。从模式选择器中删除 Auto。也在 `permissions` 下接受。 |699| `disableAutoMode` | 设置为 `"disable"` 以防止用户启用 [Auto](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 模式。从模式选择器中删除 Auto。也在 `permissions` 下接受。 |

702| `sshHostAllowlist` | 限制 [SSH 会话](#restrict-which-ssh-hosts-users-can-connect-to)连接到已解析主机名与这些模式之一匹配的主机。空数组禁用 SSH 会话。仅从托管设置中读取。 |702| `sshHostAllowlist` | 限制 [SSH 会话](#restrict-which-ssh-hosts-users-can-connect-to)连接到已解析主机名与这些模式之一匹配的主机。空数组禁用 SSH 会话。仅从托管设置中读取。 |

703| `managedMcpServers` | 将 MCP 服务器配置推送到第三方部署中的所有用户。每个条目指定 `"http"`、`"sse"` 或 `"stdio"` 的传输、连接详细信息，以及可选的 `toolPolicy` 映射，该映射限制该服务器中用户可以调用的工具。仅在第三方 (3P) Desktop 部署中可用。 |703| `managedMcpServers` | 将 MCP 服务器配置推送到第三方部署中的所有用户。每个条目指定 `"http"`、`"sse"` 或 `"stdio"` 的传输、连接详细信息，以及可选的 `toolPolicy` 映射，该映射限制该服务器中用户可以调用的工具。仅在第三方 (3P) Desktop 部署中可用。通过托管设置文件或 MDM 提供此键，因为第三方部署不接收管理员控制台设置。 |

704 704

705部署到每台机器上磁盘的托管设置文件适用于 Desktop 会话。通过管理员控制台远程推送的托管设置目前仅适用于 CLI 和 IDE 会话，因此对于 Desktop 部署，要么通过 MDM 分发文件，要么使用上面的[管理员控制台控制](#admin-console-controls)。705哪些托管设置到达 Desktop 会话取决于该会话运行的位置。模型限制（如 [`availableModels`](/zh-CN/model-config#restrict-model-selection)）在 Desktop 的 Claude Code 会话中的执行方式与在终端 CLI 中相同；请参阅[表面覆盖](/zh-CN/model-config#surface-coverage)。

706

707* **此机器上的本地会话**：部署到磁盘的托管设置文件适用。通过管理员控制台远程推送的托管设置也在会话使用组织登录或直接配置的 API 密钥向 Anthropic 的 API 进行身份验证时到达这些会话，遵循与终端 CLI 相同的[设置优先级](/zh-CN/settings#settings-precedence)。

708* **[云会话](#cloud-sessions)**：在 Anthropic 管理的虚拟机上运行，仅接收[服务器管理的设置](/zh-CN/server-managed-settings)。

709* **[SSH 会话](#ssh-sessions)**：会话从远程主机读取托管设置文件。Desktop 本身在创建连接时从本地机器的托管设置中读取 `sshConfigs` 和 `sshHostAllowlist`。

706 710

707`permissions.disableBypassPermissionsMode` 和 `disableAutoMode` 也在用户和项目设置中工作，但将它们放在托管设置中可防止用户覆盖它们。`autoMode` 从用户设置、`.claude/settings.local.json` 和托管设置中读取，但不从已检入的 `.claude/settings.json` 中读取：克隆的存储库无法注入其自己的分类器规则。有关托管专用设置的完整列表，包括 `allowManagedPermissionRulesOnly` 和 `allowManagedHooksOnly`，请参阅[托管专用设置](/zh-CN/permissions#managed-only-settings)。711`permissions.disableBypassPermissionsMode` 和 `disableAutoMode` 也在用户和项目设置中工作，但将它们放在托管设置中可防止用户覆盖它们。`autoMode` 从用户设置、`.claude/settings.local.json` 和托管设置中读取，但不从已检入的 `.claude/settings.json` 中读取：克隆的存储库无法注入其自己的分类器规则。有关托管专用设置的完整列表，包括 `allowManagedPermissionRulesOnly` 和 `allowManagedHooksOnly`，请参阅[托管专用设置](/zh-CN/permissions#managed-only-settings)。

708 712

discover-plugins.md +4 −0

Details

330 330

331详细视图显示插件贡献的组件：commands、skills、agents、hooks、MCP servers 和 LSP servers。相同的清单也可以从命令行通过 `claude plugin details` 获得。331详细视图显示插件贡献的组件：commands、skills、agents、hooks、MCP servers 和 LSP servers。相同的清单也可以从命令行通过 `claude plugin details` 获得。

332 332

333在 Claude Code v2.1.187 及更高版本中，已安装选项卡添加了一个**最近未使用**组，用于您自己安装的市场插件，但在至少两周内和至少 10 个会话中未调用过，详细视图为每个插件显示一条**最后使用**行。使用这些来查找您不再使用但仍在增加启动和上下文成本的插件，然后禁用或卸载它们。

334

335您的组织管理的插件或您使用 `--plugin-dir` 加载的插件永远不会被列为未使用，贡献 LSP server、主题、输出样式、监视器或工作流的插件也永远不会被列出，因为这些提供的价值无需跟踪调用。当您的组织使用 [`strictKnownMarketplaces`](/zh-CN/settings#strictknownmarketplaces) 限制市场时，该组和**最后使用**行都被隐藏。

336

333当您安装声明依赖项的插件时，安装输出会列出哪些依赖项与其一起自动安装。337当您安装声明依赖项的插件时，安装输出会列出哪些依赖项与其一起自动安装。

334 338

335您也可以使用直接命令管理插件。339您也可以使用直接命令管理插件。

env-vars.md +1 −0

Details

231| `CLAUDE_CODE_MAX_TURNS` | 当未传递显式限制时，限制代理转换的数量。等同于传递 [`--max-turns`](/zh-CN/cli-reference#cli-flags)，当两者都设置时优先。不是正整数的值在启动时被拒绝并显示错误，而不是被视为无限制 |231| `CLAUDE_CODE_MAX_TURNS` | 当未传递显式限制时，限制代理转换的数量。等同于传递 [`--max-turns`](/zh-CN/cli-reference#cli-flags)，当两者都设置时优先。不是正整数的值在启动时被拒绝并显示错误，而不是被视为无限制 |

233| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | 远程 MCP 工具调用的空闲超时（以毫秒为单位）（默认值：300000，或 5 分钟）。当 HTTP、SSE、WebSocket 或 [claude.ai 连接器](/zh-CN/mcp#use-mcp-servers-from-claude-ai) MCP 服务器在这么长时间内没有发送响应和没有进度通知时，工具调用会中止并显示错误，而不是等待墙钟 `MCP_TOOL_TIMEOUT`。设置为 `0` 以禁用空闲检查。低于 1000 的值被提高到一秒，该值上限为有效的 `MCP_TOOL_TIMEOUT`。不适用于 stdio 或 IDE 服务器。需要 Claude Code v2.1.187 或更高版本 |

234| `CLAUDE_CODE_NEW_INIT` | 设置为 `1` 以使 `/init` 运行交互式设置流程。该流程会询问要生成哪些文件，包括 CLAUDE.md、skills 和 hooks，然后再探索代码库并编写它们。没有此变量，`/init` 会自动生成 CLAUDE.md 而不提示。 |235| `CLAUDE_CODE_NEW_INIT` | 设置为 `1` 以使 `/init` 运行交互式设置流程。该流程会询问要生成哪些文件，包括 CLAUDE.md、skills 和 hooks，然后再探索代码库并编写它们。没有此变量，`/init` 会自动生成 CLAUDE.md 而不提示。 |

235| `CLAUDE_CODE_NO_FLICKER` | 设置为 `1` 以启用[全屏渲染](/zh-CN/fullscreen)，这是一个研究预览，可减少闪烁并在长对话中保持内存平坦。等同于 [`tui`](/zh-CN/settings#available-settings) 设置；您也可以使用 `/tui fullscreen` 切换 |236| `CLAUDE_CODE_NO_FLICKER` | 设置为 `1` 以启用[全屏渲染](/zh-CN/fullscreen)，这是一个研究预览，可减少闪烁并在长对话中保持内存平坦。等同于 [`tui`](/zh-CN/settings#available-settings) 设置；您也可以使用 `/tui fullscreen` 切换 |

errors.md +17 −0

Details

55| `Extra inputs are not permitted` | [请求错误](#extra-inputs-are-not-permitted) |55| `Extra inputs are not permitted` | [请求错误](#extra-inputs-are-not-permitted) |

56| `There's an issue with the selected model` | [请求错误](#there%E2%80%99s-an-issue-with-the-selected-model) |56| `There's an issue with the selected model` | [请求错误](#there%E2%80%99s-an-issue-with-the-selected-model) |

57| `Claude Opus is not available with the Claude Pro plan` | [请求错误](#claude-opus-is-not-available-with-the-claude-pro-plan) |57| `Claude Opus is not available with the Claude Pro plan` | [请求错误](#claude-opus-is-not-available-with-the-claude-pro-plan) |

58| `Model ... is restricted by your organization's settings` | [请求错误](#model-is-restricted-by-your-organization%E2%80%99s-settings) |

58| `thinking.type.enabled is not supported for this model` | [请求错误](#thinking-type-enabled-is-not-supported-for-this-model) |59| `thinking.type.enabled is not supported for this model` | [请求错误](#thinking-type-enabled-is-not-supported-for-this-model) |

59| `max_tokens must be greater than thinking.budget_tokens` | [请求错误](#thinking-budget-exceeds-output-limit) |60| `max_tokens must be greater than thinking.budget_tokens` | [请求错误](#thinking-budget-exceeds-output-limit) |

60| `API Error: 400 due to tool use concurrency issues` | [请求错误](#tool-use-or-thinking-block-mismatch) |61| `API Error: 400 due to tool use concurrency issues` | [请求错误](#tool-use-or-thinking-block-mismatch) |

706* 如果您最近升级了计划但仍然看到这个，请运行 `/logout` 然后 `/login`。存储的令牌反映了您登录时的计划，因此在现有会话中升级网络不会生效，直到您重新身份验证。707* 如果您最近升级了计划但仍然看到这个，请运行 `/logout` 然后 `/login`。存储的令牌反映了您登录时的计划，因此在现有会话中升级网络不会生效，直到您重新身份验证。

707* 有关每个计划包括哪些模型，请参阅 [claude.com/pricing](https://claude.com/pricing)708* 有关每个计划包括哪些模型，请参阅 [claude.com/pricing](https://claude.com/pricing)

708 709

710<h3 id="model-is-restricted-by-your-organization’s-settings">

711 Model is restricted by your organization's settings

712</h3>

713

714您的组织管理员已在 Claude 控制台中禁用此模型，或者它被托管设置中的 [`availableModels`](/zh-CN/model-config#restrict-model-selection) 允许列表排除。当使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 设置设置受限制的模型时，Claude Code 会替换为允许的模型并继续。为受限制的模型键入 `/model <name>` 会被拒绝，显示 `Run /model to choose a different model.`，会话保持其当前模型。

715

716```text theme={null}

717Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.

718```

719

720**要做什么：**

721

722* 运行 `/model` 以从您的组织允许的模型中选择。受限制的模型在选择器中被隐藏。

723* 如果受限制的模型是在 `--model`、`ANTHROPIC_MODEL` 或设置文件的 `model` 字段中设置的，请删除或更新该值，以便通知不会在每次启动时重复出现

724* 如果您需要访问受限制的模型，请要求您的组织管理员启用它。请参阅[组织模型限制](/zh-CN/model-config#organization-model-restrictions)。

725

709<h3 id="thinking-type-enabled-is-not-supported-for-this-model">726<h3 id="thinking-type-enabled-is-not-supported-for-this-model">

710 thinking.type.enabled is not supported for this model727 thinking.type.enabled is not supported for this model

711</h3>728</h3>

fast-mode.md +1 −1

Details

115* **团队和企业的管理员启用**：快速模式默认对团队和企业组织禁用。管理员必须明确[启用快速模式](#enable-fast-mode-for-your-organization)，用户才能访问它。115* **团队和企业的管理员启用**：快速模式默认对团队和企业组织禁用。管理员必须明确[启用快速模式](#enable-fast-mode-for-your-organization)，用户才能访问它。

116 116

117<Note>117<Note>

118 如果您的管理员尚未为您的组织启用快速模式，`/fast` 命令将显示"Fast mode has been disabled by your organization."。如果您的组织的 [`availableModels`](/zh-CN/model-config#restrict-model-selection) 允许列表排除了快速模式 Opus 模型，`/fast` 将被拒绝，显示"is not in your organization's allowed models"。118 如果您的管理员尚未为您的组织启用快速模式，`/fast` 命令将显示"Fast mode has been disabled by your organization."。如果您的组织的 [`availableModels`](/zh-CN/model-config#restrict-model-selection) 允许列表排除了快速模式 Opus 模型，`/fast` 将被拒绝，显示"is not in your organization's allowed models"。例外情况是已在支持快速模式的允许 Opus 模型上运行的会话：`/fast` 随后应用于该模型。

119</Note>119</Note>

120 120

121<h3 id="enable-fast-mode-for-your-organization">121<h3 id="enable-fast-mode-for-your-organization">

fullscreen.md +1 −0

Details

56 56

57* **在提示输入框中点击**以在您正在输入的文本中的任何位置放置光标。57* **在提示输入框中点击**以在您正在输入的文本中的任何位置放置光标。

58* **点击 `/` 命令或 `@` 文件列表中的建议**以接受它。悬停会突出显示光标下的行。58* **点击 `/` 命令或 `@` 文件列表中的建议**以接受它。悬停会突出显示光标下的行。

59* **点击选择菜单中的选项**以选择它。这涵盖权限提示、`/model`、`/config` 和其他显示选项列表的对话框。悬停会在光标下的行上显示指针。{/* min-version: 2.1.187 */}需要 Claude Code v2.1.187 或更高版本。

59* **点击折叠的工具结果**以展开它并查看完整输出。再次点击以折叠。工具调用及其结果一起展开。只有有更多内容要显示的消息才可点击。60* **点击折叠的工具结果**以展开它并查看完整输出。再次点击以折叠。工具调用及其结果一起展开。只有有更多内容要显示的消息才可点击。

60* **在 macOS 上按住 `Cmd`，或在 Linux 和 Windows 上按住 `Ctrl`，然后点击 URL 或文件路径**以打开它。工具输出中的文件路径，如 Edit 或 Write 后打印的路径，在您的默认应用程序中打开。纯 `http://` 和 `https://` URL 在您的浏览器中打开。{/* min-version: 2.1.181 */}从 v2.1.181 开始，不按住 `Cmd` 或 `Ctrl` 的纯点击不再打开链接，与原生终端行为相匹配。在 VS Code 集成终端和类似的基于 xterm.js 的终端中，Claude Code 遵从终端自己的链接处理程序，该处理程序使用相同的手势。61* **在 macOS 上按住 `Cmd`，或在 Linux 和 Windows 上按住 `Ctrl`，然后点击 URL 或文件路径**以打开它。工具输出中的文件路径，如 Edit 或 Write 后打印的路径，在您的默认应用程序中打开。纯 `http://` 和 `https://` URL 在您的浏览器中打开。{/* min-version: 2.1.181 */}从 v2.1.181 开始，不按住 `Cmd` 或 `Ctrl` 的纯点击不再打开链接，与原生终端行为相匹配。在 VS Code 集成终端和类似的基于 xterm.js 的终端中，Claude Code 遵从终端自己的链接处理程序，该处理程序使用相同的手势。

61* **点击并拖动**以在对话中的任何位置选择文本。双击选择一个单词，匹配 iTerm2 的单词边界，以便文件路径作为一个单位选择。三击选择该行。62* **点击并拖动**以在对话中的任何位置选择文本。双击选择一个单词，匹配 iTerm2 的单词边界，以便文件路径作为一个单位选择。三击选择该行。

github-actions.md +2 −2

Details

44 快速设置44 快速设置

45</h2>45</h2>

46 46

~~47设置此 action 的最简单方法是通过终端中的 Claude Code。只需打开 claude 并运行 `/install-github-app`。~~47在 Claude Code 终端中运行 `/install-github-app` 以交互方式设置集成。该命令在您的仓库上安装 Claude GitHub App，然后引导您添加 GitHub Actions 工作流和 API 密钥密钥。

48 48

~~49此命令将指导您完成 GitHub 应用和所需密钥的设置。~~49安装 GitHub App 后，该命令会询问是否继续进行 GitHub Actions 设置。在 Claude Code v2.1.187 及更高版本中，您可以选择**暂时跳过**以仅安装 App，然后通过再次运行 `/install-github-app` 返回工作流和密钥步骤。早期版本直接进行工作流选择。

50 50

51<Note>51<Note>

52 * 您必须是仓库管理员才能安装 GitHub 应用并添加密钥52 * 您必须是仓库管理员才能安装 GitHub 应用并添加密钥

glossary.md +2 −2

Details

208 Managed settings208 Managed settings

209</h3>209</h3>

210 210

211由 IT 或 DevOps 在组织范围内强制执行的设置文件，放置在 `~/.claude` 之外的操作系统级路径。用户无法覆盖或排除托管设置。使用此功能可实现安全策略、合规要求或跨一个群体的标准化工具。211由 IT 或 DevOps 在组织范围内强制执行的设置，通过管理员控制台从 Anthropic 的服务器交付，或部署到 `~/.claude` 之外的操作系统级路径。用户无法从较低优先级的范围覆盖托管设置。服务器管理的交付适用于[符合条件的配置](/zh-CN/server-managed-settings#platform-availability)；请参阅[安全考虑](/zh-CN/server-managed-settings#security-considerations)。使用此功能可实现安全策略、合规要求或跨一个群体的标准化工具。

212 212

213了解更多：[服务器管理的设置](/zh-CN/server-managed-settings)213了解更多：[服务器管理的设置](/zh-CN/server-managed-settings) · [设置文件](/zh-CN/settings#settings-files)

214 214

215<h3 id="mcp-model-context-protocol">215<h3 id="mcp-model-context-protocol">

216 MCP (Model Context Protocol)216 MCP (Model Context Protocol)

interactive-mode.md +3 −2

Details

268 * 按 `Ctrl+C` 取消并恢复原始输入268 * 按 `Ctrl+C` 取消并恢复原始输入

269 * 在空搜索上按 `Backspace` 以取消269 * 在空搜索上按 `Backspace` 以取消

270 270

271搜索显示匹配的命令，搜索词突出显示，因此您可以找到并重用以前的输入。271搜索加载所选范围内最近的 100 个唯一提示，重复项折叠到最新出现。匹配的提示显示时搜索词突出显示，因此您可以找到并重用以前的输入。

272 272

273<h2 id="background-bash-commands">273<h2 id="background-bash-commands">

274 后台 bash 命令274 后台 bash 命令

371答案出现后，覆盖层接受这些按键。来自同一会话的较早侧面问题显示为当前答案上方的暗淡列表；它们保持在对话历史之外，但在覆盖层中保持可见，直到您清除它们。371答案出现后，覆盖层接受这些按键。来自同一会话的较早侧面问题显示为当前答案上方的暗淡列表；它们保持在对话历史之外，但在覆盖层中保持可见，直到您清除它们。

372 372

373| 按键 | 操作 |373| 按键 | 操作 |

374| :----------------------- | :---------------------------------------------------------------------------------------------- |374| :----------------------- | :-------------------------------------------------------------------------------------------------------------------- |

377| `Left` / `Right` | {/* min-version: 2.1.187 */}在此答案和您来自会话的较早 `/btw` 答案之间切换。`Left` 移动到较早的答案，`Right` 返回到当前答案。需要 Claude Code v2.1.187 或更高版本 |

377| `c` | 将答案作为原始 Markdown 复制到您的剪贴板。使用此方法而不是鼠标选择，后者会捕获硬换行的终端呈现而不是源文本 |378| `c` | 将答案作为原始 Markdown 复制到您的剪贴板。使用此方法而不是鼠标选择，后者会捕获硬换行的终端呈现而不是源文本 |

378| `f` | 分叉到新会话。分叉继承父对话加上此问题和答案作为真实记录轮次，因此您可以继续使用完整工具访问。原始会话保留在 [`/resume`](/zh-CN/commands) 下。仅在本地会话中可用 |379| `f` | 分叉到新会话。分叉继承父对话加上此问题和答案作为真实记录轮次，因此您可以继续使用完整工具访问。原始会话保留在 [`/resume`](/zh-CN/commands) 下。仅在本地会话中可用 |

379| `x` | 清除当前答案上方显示的较早 `/btw` 交换列表 |380| `x` | 清除当前答案上方显示的较早 `/btw` 交换列表 |

mcp.md +2 −0

Details

218 218

219每个服务器的 `timeout` 是每个工具调用的硬时钟限制，来自服务器的进度通知不会延长它。低于 1000 的值被忽略，并回退到 `MCP_TOOL_TIMEOUT`，或在该变量未设置时回退到其约 28 小时的默认值。{/* min-version: 2.1.162 */}在 v2.1.162 之前，低于 1000 的值被限制为一秒。对于 HTTP 和 SSE 服务器，每个请求的 fetch 首字节预算有 60 秒的最小值。219每个服务器的 `timeout` 是每个工具调用的硬时钟限制，来自服务器的进度通知不会延长它。低于 1000 的值被忽略，并回退到 `MCP_TOOL_TIMEOUT`，或在该变量未设置时回退到其约 28 小时的默认值。{/* min-version: 2.1.162 */}在 v2.1.162 之前，低于 1000 的值被限制为一秒。对于 HTTP 和 SSE 服务器，每个请求的 fetch 首字节预算有 60 秒的最小值。

220 220

221从 v2.1.187 开始，对远程 HTTP、SSE、WebSocket 或 [claude.ai connector](#use-mcp-servers-from-claude-ai) 服务器的工具调用如果在 5 分钟内没有发送响应和进度通知，将以错误中止，而不是等待时钟限制。在毫秒中设置 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/zh-CN/env-vars) 环境变量以更改空闲窗口，或将其设置为 `0` 以禁用检查。Stdio 服务器是本地进程，不受空闲超时的限制。

222

221<h3 id="plugin-provided-mcp-servers">223<h3 id="plugin-provided-mcp-servers">

222 插件提供的 MCP 服务器224 插件提供的 MCP 服务器

223</h3>225</h3>

model-config.md +69 −16

Details

90 90

91`--model` 标志和 `ANTHROPIC_MODEL` 环境变量仅适用于您启动它们的会话。要同时在不同终端中运行不同的模型，请使用各自的 `--model` 标志启动每个终端，而不是使用 `/model` 切换。91`--model` 标志和 `ANTHROPIC_MODEL` 环境变量仅适用于您启动它们的会话。要同时在不同终端中运行不同的模型，请使用各自的 `--model` 标志启动每个终端，而不是使用 `/model` 切换。

92 92

93使用 `claude --resume`、`--continue` 或 `/resume` 选择器启动的恢复会话会保持保存转录时使用的模型，无论当前 `model` 设置如何。如果该模型已被停用，会话会回退到正常的优先级顺序。这可以防止另一个会话的 `/model` 选择在恢复时改变模型。93使用 `claude --resume`、`--continue` 或 `/resume` 选择器启动的恢复会话会保持保存转录时使用的模型，无论当前 `model` 设置如何。如果该模型已被停用或被 [`availableModels`](#restrict-model-selection) 排除，会话会回退到正常的优先级顺序。这可以防止另一个会话的 `/model` 选择在恢复时改变模型。

94 94

95当启动时的活跃模型来自项目或托管设置而不是您自己的选择时，启动标题会显示哪个设置文件设置了它。运行 `/model` 以覆盖；项目或托管设置会在下次启动时重新应用。95当启动时的活跃模型来自项目或托管设置而不是您自己的选择时，启动标题会显示哪个设置文件设置了它。运行 `/model` 以覆盖；项目或托管设置会在下次启动时重新应用。

96 96

121 限制模型选择121 限制模型选择

122</h2>122</h2>

123 123

124企业管理员可以在[托管或策略设置](/zh-CN/settings#settings-files)中使用 `availableModels` 来限制用户可以选择的模型。124企业管理员可以在[托管或策略设置](/zh-CN/settings#settings-files)中使用 `availableModels` 来限制用户可以选择的模型。条目可以匹配模型系列（如 `sonnet`）、版本前缀（如 `claude-sonnet-4-5`）或完整模型 ID（如 `claude-sonnet-4-5-20250929`）。

125 125

126设置 `availableModels` 后，允许列表适用于用户可以指定模型的每个位置：126设置 `availableModels` 后，允许列表适用于用户可以指定模型的每个位置：

127 127

128* **主会话模型**：`/model`、`--model` 标志和 `ANTHROPIC_MODEL` 环境变量128* **主会话模型**：`/model`、`--model` 标志、`ANTHROPIC_MODEL` 环境变量、`model` 设置，以及[恢复会话](#setting-your-model)时恢复的模型

129* **别名解析**：{/* min-version: 2.1.176 */}`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` 和 `ANTHROPIC_DEFAULT_FABLE_MODEL` 环境变量无法将允许的别名重定向到列表外的模型129* **别名解析**：{/* min-version: 2.1.176 */}`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` 和 `ANTHROPIC_DEFAULT_FABLE_MODEL` 环境变量无法将允许的别名重定向到列表外的模型

130* **快速模式**：{/* min-version: 2.1.176 */}`/fast` 在隐式切换到列表外的 Opus 模型时拒绝切换，显示消息"不在您的组织允许的模型中"130* **快速模式**：{/* min-version: 2.1.176 */}`/fast` 在隐式切换到列表外的 Opus 模型时拒绝切换，显示消息"不在您的组织允许的模型中"

131* **子代理模型**：[子代理](/zh-CN/sub-agents#choose-a-model) frontmatter 中的 `model` 字段、Agent 工具的 `model` 参数、`/agents` 中的模型选择器和 `CLAUDE_CODE_SUBAGENT_MODEL`131* **子代理模型**：[子代理](/zh-CN/sub-agents#choose-a-model) frontmatter 中的 `model` 字段、Agent 工具的 `model` 参数、`/agents` 中的模型选择器和 `CLAUDE_CODE_SUBAGENT_MODEL`

132* **顾问模型**：配置的 [`advisorModel`](/zh-CN/advisor) 设置132* **技能和命令模型**：[技能和命令](/zh-CN/skills)中的 `model` frontmatter

133* **回退链**：[回退模型链](#fallback-model-chains)中列表外的元素会被删除133* **顾问模型**：配置的 [`advisorModel`](/zh-CN/advisor) 设置和 `--advisor` 标志

134* **后台代理模型**：[分派选择器](/zh-CN/agent-view)中选择的模型

134 135

135使用 `/model` 切换到被阻止的模型会被拒绝并显示错误，而被阻止的 `--model` 标志或 `ANTHROPIC_MODEL` 值在启动时会被替换为警告，命名请求的和替换的模型，会话会在默认模型上启动。被阻止的子代理或顾问覆盖会回退到继承或默认模型，而不是导致请求失败。136使用 `/model` 切换到被阻止的模型会被拒绝并显示错误，而被阻止的 `--model` 标志、`ANTHROPIC_MODEL` 或 `model` 设置值在启动时会被替换为警告，命名请求的和替换的模型，会话会在默认模型上启动。被阻止的子代理、技能或命令覆盖会回退到继承或默认模型，而不是导致请求失败；被阻止的 `advisorModel` 设置会禁用该会话的顾问，而被阻止的 `--advisor` 标志值会在启动时退出并显示错误。被排除的模型在 `/model` 选择器中被隐藏。

137

138自动模型更改的检查方式相同：[回退模型链](#fallback-model-chains)中列表外的元素会被删除，计划模式升级（如 [`opusplan`](#opusplan-model-setting) 升级到被排除的模型）会被跳过，以便规划继续在会话的模型上进行，[自动模型回退](#automatic-model-fallback)的目标被排除时不会运行，因此标记的请求以拒绝结束。当会话之后运行的模型在允许列表外时，启用[快速模式](/zh-CN/fast-mode)会被拒绝。

136 139

137```json theme={null}140```json theme={null}

138{141{

140}143}

141```144```

142 145

146<h3 id="surface-coverage">

147 表面覆盖

148</h3>

149

150每个表面都强制执行它接收的允许列表。哪个交付机制到达每个表面不同：

151

153| :------------------------------------------------- | :-------- | :----- | :--------- | :-------------- | :--------- |

156

157* 云会话在[网络上的 Claude Code](/zh-CN/claude-code-on-the-web) 或桌面应用中运行在 Anthropic 管理的虚拟机上：部署到您的设备的设置无法到达它们，因此通过服务器管理的设置交付允许列表。云会话中的中途模型切换在请求的模型被允许列表排除时被拒绝。服务器端拒绝在会话创建时适用于[组织模型限制](#organization-model-restrictions)，而不是 `availableModels` 设置键。

158* Cowork 是 Claude 桌面应用中的代理工作选项卡，不是 Claude Code 表面，按设计不接收服务器管理的设置。托管设置文件在会话运行的地方存在时适用于 Cowork 会话；远程 Cowork 会话运行在 Anthropic 管理的虚拟机上，其中不存在设备部署的文件。

159* [第三方提供商](/zh-CN/server-managed-settings#platform-availability)上的会话，如 Bedrock、Vertex AI、Foundry 和 [AWS 上的 Claude Platform](/zh-CN/claude-platform-on-aws)，不接收服务器管理的设置，因此在那里通过 MDM 或托管设置文件交付允许列表。

160* 服务器管理的交付还需要会话使用组织登录或直接配置的 API 密钥进行身份验证。仅通过 [`apiKeyHelper`](/zh-CN/settings#available-settings) 脚本生成密钥的队列应通过 MDM 或托管设置文件交付允许列表。

161* 桌面代码选项卡还托管 [SSH 会话](/zh-CN/desktop#ssh-sessions)，它们从运行的远程主机读取托管设置文件。请参阅[桌面托管设置](/zh-CN/desktop#managed-settings)。

162* claude.ai 和桌面应用中的模型选择器隐藏或灰显您的组织允许列表排除的模型。选择器状态是用户的便利；强制执行发生在会话中。

163

143<h3 id="default-model-behavior">164<h3 id="default-model-behavior">

144 默认模型行为165 默认模型行为

145</h3>166</h3>

146 167

147默认情况下，模型选择器中的"默认"选项不受 `availableModels` 影响。它始终保持可用，并代表系统的运行时默认值[基于用户的订阅层级](#default-model-setting)。168模型选择器中的"默认"选项不受 `availableModels` 影响，除非也设置了 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)。单独使用 `availableModels` 会保持"默认"可用，解析为系统的运行时默认值[基于用户的订阅层级](#default-model-setting)。如果层级默认值是您打算限制的模型，也设置 `enforceAvailableModels`。

148 169

149要将允许列表扩展到"默认"选项，请在托管或策略设置中将 `enforceAvailableModels` 设置为 `true`，同时设置非空的 `availableModels` 列表。当层级默认值不在允许列表中时，"默认"会解析为第一个允许的条目，而不是层级默认值。这需要 Claude Code v2.1.175 或更高版本。170空的 `availableModels` 数组永远不会启用"默认"模型强制执行：使用 `availableModels: []`，命名的模型选择被阻止，但帐户类型的默认模型无论 `enforceAvailableModels` 如何设置都保持可用。

150 171

151空的 `availableModels` 数组永远不会启用强制执行。即使使用 `availableModels: []`，用户仍然可以使用其层级的默认模型来使用 Claude Code，无论 `enforceAvailableModels` 如何设置。172<h3 id="enforce-the-allowlist-for-the-default-model">

173 对默认模型强制执行允许列表

174</h3>

175

176在托管设置中将 `enforceAvailableModels: true` 与非空的 `availableModels` 一起设置，以将允许列表扩展到"默认"选项。这需要 Claude Code v2.1.175 或更高版本。

177

178```json theme={null}

179{

180 "availableModels": ["sonnet", "haiku"],

181 "enforceAvailableModels": true

182}

183```

184

185当用户帐户类型的默认模型不在允许列表中时，"默认"选项改为解析为第一个 `availableModels` 条目，该条目命名允许的、可用的模型，`/model` 选择器的"默认"行显示该模型。这适用于到达默认值的每个地方：会话启动、在 `/model` 中选择"默认"、[回退模型链](#fallback-model-chains)中的 `"default"` 关键字，以及排除的选择被删除时使用的回退。

186

187当 `availableModels` 未设置或为空时，`enforceAvailableModels` 无效：使用 `availableModels: []`，帐户类型的默认模型保持可用，因此该设置无法将用户锁定在每个模型之外。当 `availableModels` 非空但没有条目解析为允许的和可用的模型时，强制执行降级，"默认"回退到帐户类型默认值，警告仅在 `--debug` 下可见。在列表中保持至少一个保证可用的条目以避免这种情况。

188

189在[最高优先级托管源](/zh-CN/settings#settings-precedence)中部署两个键：管理员部署的托管源不合并，因此放在托管设置文件中的一对在管理控制台交付任何设置时被忽略。

152 190

153<h3 id="control-the-model-users-run-on">191<h3 id="control-the-model-users-run-on">

154 控制用户运行的模型192 控制用户运行的模型

155</h3>193</h3>

156 194

157`model` 设置是初始选择，而不是强制执行。它设置会话启动时哪个模型处于活跃状态，但用户仍然可以打开 `/model` 并选择"默认"，这会解析为其层级的系统默认值，无论 `model` 设置为什么。195`model` 设置是初始选择，而不是强制执行。它设置会话启动时哪个模型处于活跃状态，但用户仍然可以打开 `/model` 并选择"默认"，这会解析为其层级的系统默认值，无论 `model` 设置为什么，除非 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 重定向它。

158 196

159要完全控制模型体验，请结合这些设置：197要完全控制模型体验，请结合这些设置：

160 198

182 合并行为220 合并行为

183</h3>221</h3>

184 222

185当 `availableModels` 仅在用户、项目和本地设置中设置时，数组会在这些级别上合并并去重。223当[最高优先级托管设置源](/zh-CN/server-managed-settings#settings-precedence)定义 `availableModels` 时，仅该列表适用：用户、项目或本地设置中的条目无法扩展它，管理员部署的托管源不相互合并，因此在托管设置文件中部署的列表在服务器管理的设置交付任何键时被忽略。否则，来自用户、项目和本地设置的列表像其他数组设置一样[连接和去重](/zh-CN/settings#settings-precedence)。{/* min-version: 2.1.175 */}从 Claude Code v2.1.175 开始，托管列表替换较低优先级条目；早期版本合并它们。

186 224

187当 `availableModels` 在托管或策略设置中设置时，托管或策略值完全替换合并结果：在用户或项目设置中添加的条目无法扩展它。托管和策略设置以相同方式替换 `enforceAvailableModels` 的较低优先级值。从 Claude Code v2.1.175 开始，这是强制执行严格允许列表的唯一方式；早期版本会将托管列表与较低优先级条目合并。225在有效列表中，命名系列中特定模型的条目，无论是版本前缀还是完整模型 ID，都禁用该系列的通配符条目：`["sonnet", "claude-sonnet-4-5"]` 仅允许 Sonnet 4.5 版本，而不是每个 Sonnet 模型。

188 226

189<h3 id="mantle-model-ids">227<h3 id="mantle-model-ids">

190 Mantle 模型 ID228 Mantle 模型 ID

191</h3>229</h3>

192 230

193当启用[Bedrock Mantle 端点](/zh-CN/amazon-bedrock#use-the-mantle-endpoint)时，`availableModels` 中以 `anthropic.` 开头的条目会作为自定义选项添加到 `/model` 选择器，并路由到 Mantle 端点。该设置仍然将选择器限制为列出的条目，因此请在任何 Mantle ID 旁边包含标准别名。231当启用[Bedrock Mantle 端点](/zh-CN/amazon-bedrock#use-the-mantle-endpoint)时，`availableModels` 中以 `anthropic.` 开头的条目会作为自定义选项添加到 `/model` 选择器，并路由到 Mantle 端点。这是对[为第三方部署固定模型](#pin-models-for-third-party-deployments)中描述的别名匹配的例外。该设置仍然将选择器限制为列出的条目，Mantle ID 嵌入系列名称，因此它计为特定条目并禁用该系列的通配符：在任何 Mantle ID 旁边，列出您想保持可选择的版本前缀或完整 ID。请参阅[合并行为](#merge-behavior)。

232

233<h3 id="organization-model-restrictions">

234 组织模型限制

235</h3>

236

237当您的成员通过 Anthropic API 进行身份验证，并且您想要一个组织范围的开关而不部署设置文件时，使用控制台切换而不是 `availableModels`。组织管理员通过在 Claude 控制台中禁用单个模型来限制成员可以运行的模型。当 Claude Code 进行身份验证时，此限制与帐户的权利一起交付，与设置中的任何 `availableModels` 列表分开，服务器在创建会话时独立强制执行相同的限制。需要 Claude Code v2.1.187 或更高版本。

238

239受限制的模型在 `/model` 选择器中被隐藏。使用 `--model`、`ANTHROPIC_MODEL` 环境变量或 `model` 设置按名称选择它会显示通知 `Model "<name>" is restricted by your organization's settings. Using <model> instead.`，会话在允许的模型上启动。为受限制的模型键入 `/model <name>` 会被拒绝，显示 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`，会话保持其当前模型。

240

241这两种机制组合：仅当模型被 `availableModels` 允许且不被组织限制时，它才可选择。组织限制被交付到 Anthropic API 和 [LLM 网关](/zh-CN/llm-gateway)部署上的会话。Bedrock、Vertex AI、Foundry 和 AWS 上的 Claude Platform 上的会话不接收它们，因此在那些提供商上改用 `availableModels`。

194 242

195<h2 id="special-model-behavior">243<h2 id="special-model-behavior">

196 特殊模型行为244 特殊模型行为

209 257

210Enterprise 按使用量付费是指按使用量而非按订阅席位计费的 Enterprise 组织。258Enterprise 按使用量付费是指按使用量而非按订阅席位计费的 Enterprise 组织。

211 259

260当托管设置[对默认模型强制执行允许列表](#enforce-the-allowlist-for-the-default-model)且账户类型默认值不在 `availableModels` 中时，`default` 会解析为强制执行的默认值，而不是上面的账户类型默认值。

261

212Fable 5 不是任何账户类型的默认模型。会话仅在您选择 Fable 5 后才使用它，通过 `/model fable`、`model` 设置或 Fable 5 可用的 `best` 别名。使用 `/model` 选择它会将其保存为用户设置中的选定模型，因此后续会话将从 Fable 5 开始，直到您更改模型。262Fable 5 不是任何账户类型的默认模型。会话仅在您选择 Fable 5 后才使用它，通过 `/model fable`、`model` 设置或 Fable 5 可用的 `best` 别名。使用 `/model` 选择它会将其保存为用户设置中的选定模型，因此后续会话将从 Fable 5 开始，直到您更改模型。

213 263

214<h3 id="opusplan-model-setting">264<h3 id="opusplan-model-setting">

267 317

268会话随后在该 Opus 模型上继续。要返回 Fable 5，请运行 `/model fable`。318会话随后在该 Opus 模型上继续。要返回 Fable 5，请运行 `/model fable`。

269 319

320回退目标会根据 [`availableModels`](#restrict-model-selection) 进行检查。当它被阻止时，不会发生回退。拒绝显示为正常错误，会话的模型保持不变。

321

270<h4 id="check-what-triggered-fallback">322<h4 id="check-what-triggered-fallback">

271 检查触发回退的原因323 检查触发回退的原因

272</h4>324</h4>

286* 如果两个模型都标记相同的请求，您可以编辑提示并重试，或启动新会话。338* 如果两个模型都标记相同的请求，您可以编辑提示并重试，或启动新会话。

287* 在移动 [Claude Code on the web](/zh-CN/claude-code-on-the-web) 会话上，不支持编辑和重试。切换模型，或从桌面浏览器或桌面应用继续会话。339* 在移动 [Claude Code on the web](/zh-CN/claude-code-on-the-web) 会话上，不支持编辑和重试。切换模型，或从桌面浏览器或桌面应用继续会话。

288* 在 [non-interactive mode](/zh-CN/cli-reference#cli-flags) 和无法显示提示的 SDK 集成中，标记的请求以拒绝结束轮次。340* 在 [non-interactive mode](/zh-CN/cli-reference#cli-flags) 和无法显示提示的 SDK 集成中，标记的请求以拒绝结束轮次。

341* 当回退目标被 [`availableModels`](#restrict-model-selection) 阻止时，不会显示提示。标记的请求以拒绝结束，与目标被阻止时的自动回退相同。

289 342

290<h4 id="enable-fallback-on-bedrock-vertex-ai-and-foundry">343<h4 id="enable-fallback-on-bedrock-vertex-ai-and-foundry">

291 在 Bedrock、Vertex AI 和 Foundry 上启用回退344 在 Bedrock、Vertex AI 和 Foundry 上启用回退

452 505

453自定义条目出现在 `/model` 选择器的底部。`ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` 和 `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` 是可选的。如果省略，模型 ID 用作名称，描述默认为 `Custom model (<model-id>)`。506自定义条目出现在 `/model` 选择器的底部。`ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` 和 `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` 是可选的。如果省略，模型 ID 用作名称，描述默认为 `Custom model (<model-id>)`。

454 507

455Claude Code 跳过对 `ANTHROPIC_CUSTOM_MODEL_OPTION` 中设置的模型 ID 的验证，因此您可以使用您的 API 端点接受的任何字符串。508Claude Code 跳过对 `ANTHROPIC_CUSTOM_MODEL_OPTION` 中设置的模型 ID 的验证，因此您可以使用您的 API 端点接受的任何字符串。当设置 [`availableModels`](#restrict-model-selection) 时，也要在允许列表中包含自定义模型 ID：自定义条目会从选择器中被过滤，对其进行 `--model` 选择会被拒绝，就像任何其他被排除的模型一样。嵌入了系列名称的自定义 ID（例如 `my-gateway/claude-opus-4-7`）计为该系列的特定条目并禁用其通配符，因此还要列出您打算保持可选择的版本。请参阅 [合并行为](#merge-behavior)。

456 509

457<h2 id="environment-variables">510<h2 id="environment-variables">

458 环境变量511 环境变量

505* 该后缀按变量读取，而不是按模型读取。在 Bedrock、Vertex 和 Foundry 上，一个变量中没有 `[1m]` 的模型 ID 使用 200K 上下文，即使另一个变量使用相同的模型和后缀。558* 该后缀按变量读取，而不是按模型读取。在 Bedrock、Vertex 和 Foundry 上，一个变量中没有 `[1m]` 的模型 ID 使用 200K 上下文，即使另一个变量使用相同的模型和后缀。

506 559

507<Note>560<Note>

508 使用第三方提供商时，`settings.availableModels` 允许列表仍然适用。过滤与模型别名（如 `opus`）、版本前缀（如 `claude-opus-4-8`）或完整模型 ID 匹配。任何 `[1m]` 后缀在匹配前都会从允许列表条目和请求的模型中删除，因此 `claude-opus-4-8` 条目允许标准和 1M 上下文 Opus 行。提供商特定的前缀（如 `us.anthropic.`）不会被删除：在 `availableModels` 中列出选择器显示的相同形式，或通过 [`modelOverrides`](#override-model-ids-per-version) 映射它。561 使用第三方提供商时，通过 [MDM 或托管设置文件](/zh-CN/settings#settings-files) 提供的 `availableModels` 允许列表仍然适用；[服务器托管设置不会在那里提供](/zh-CN/server-managed-settings#platform-availability)。过滤与模型别名（如 `opus`）、版本前缀（如 `claude-opus-4-8`）或完整提供商形式的模型 ID 匹配。提供商特定的前缀（如 `us.anthropic.`）不会被删除，因此要允许特定模型，请列出选择器显示的相同提供商形式 ID，或通过 [`modelOverrides`](#override-model-ids-per-version) 映射它。任何 `[1m]` 后缀在匹配前都会从允许列表条目和请求的模型中删除。

509</Note>562</Note>

510 563

511<h3 id="customize-pinned-model-display-and-capabilities">564<h3 id="customize-pinned-model-display-and-capabilities">

572 625

573覆盖替换了支持 `/model` 选择器中每个条目的内置模型 ID。在 Bedrock 上，覆盖优先于 Claude Code 在启动时自动发现的任何推理配置文件。您直接通过 `ANTHROPIC_MODEL`、`--model` 或 `ANTHROPIC_DEFAULT_*_MODEL` 环境变量提供的值会按原样传递给提供商，不会被 `modelOverrides` 转换。626覆盖替换了支持 `/model` 选择器中每个条目的内置模型 ID。在 Bedrock 上，覆盖优先于 Claude Code 在启动时自动发现的任何推理配置文件。您直接通过 `ANTHROPIC_MODEL`、`--model` 或 `ANTHROPIC_DEFAULT_*_MODEL` 环境变量提供的值会按原样传递给提供商，不会被 `modelOverrides` 转换。

574 627

575`modelOverrides` 与 `availableModels` 一起工作。允许列表针对 Anthropic 模型 ID 进行评估，而不是覆盖值，因此 `availableModels` 中的条目（如 `"opus"`）即使在 Opus 版本映射到 ARN 时也会继续匹配。628`modelOverrides` 与 `availableModels` 一起工作。允许列表针对 Anthropic 模型 ID 进行评估，而不是覆盖值，因此 `availableModels` 中的条目（如 `"opus"`）即使在 Opus 版本映射到 ARN 时也会继续匹配。当在托管设置中设置 `enforceAvailableModels` 时，强制执行的默认值通过 `modelOverrides` 从[最高优先级托管源](/zh-CN/server-managed-settings#settings-precedence)解析。管理员的映射（如固定到推理配置文件 ARN 的版本）在强制执行的默认值中得到遵守。来自用户或项目设置的覆盖不会影响它。

576 629

577<h3 id="prompt-caching-configuration">630<h3 id="prompt-caching-configuration">

578 Prompt caching 配置631 Prompt caching 配置

monitoring-usage.md +1 −1

Details

1164 1164

1165Claude Code 在内部重试失败的 API 请求，仅在放弃后才发出单个 `claude_code.api_error` 事件，因此事件本身是该请求的终端信号。中间重试尝试不会作为单独的事件记录。1165Claude Code 在内部重试失败的 API 请求，仅在放弃后才发出单个 `claude_code.api_error` 事件，因此事件本身是该请求的终端信号。中间重试尝试不会作为单独的事件记录。

1166 1166

1167事件上的 `attempt` 属性记录进行的总尝试次数。大于 `CLAUDE_CODE_MAX_RETRIES`（默认 `10`，上限为 `15`）的值表示请求在瞬时错误上耗尽了所有重试。较低的值表示不可重试的错误，例如 `400` 响应。1167事件上的 `attempt` 属性记录进行的总尝试次数。`CLAUDE_CODE_MAX_RETRIES` 默认为 10，上限为 15。当请求在瞬时错误上耗尽所有重试时，`attempt` 等于该有效限制加一：默认为 11，永远不超过 16。较低的值表示不可重试的错误，例如 `400` 响应。

1168 1168

1169要区分从一个恢复的会话与停滞的会话，按 `session.id` 分组事件，并检查错误后是否存在更晚的 `api_request` 事件。1169要区分从一个恢复的会话与停滞的会话，按 `session.id` 分组事件，并检查错误后是否存在更晚的 `api_request` 事件。

1170 1170

sandboxing.md +33 −3

Details

202 202

203`allowRead` 中的 `.` 解析为项目根目录，因为此配置位于项目设置中。如果你将相同的配置放在 `~/.claude/settings.json` 中，`.` 将解析为 `~/.claude`，项目文件将保持被 `denyRead` 规则阻止。203`allowRead` 中的 `.` 解析为项目根目录，因为此配置位于项目设置中。如果你将相同的配置放在 `~/.claude/settings.json` 中，`.` 将解析为 `~/.claude`，项目文件将保持被 `denyRead` 规则阻止。

204 204

205<h3 id="protect-credentials">

206 保护凭证

207</h3>

208

209`sandbox.credentials` 设置声明沙箱化命令不能访问的凭证文件和环境变量。列出的文件路径在沙箱内被拒绝读取，与 `filesystem.denyRead` 应用的块相同，列出的环境变量在每个沙箱化命令运行前被取消设置。专用的 `credentials` 块将凭证规则与环境变量取消设置分组，并与常规文件系统规则分开。需要 Claude Code v2.1.187 或更高版本。

210

211下面的示例阻止读取 AWS 凭证文件和 SSH 目录，并从沙箱化命令的环境中删除 `GITHUB_TOKEN` 和 `NPM_TOKEN`：

212

213```json theme={null}

214{

215 "sandbox": {

216 "enabled": true,

217 "credentials": {

218 "files": [

219 { "path": "~/.aws/credentials", "mode": "deny" },

220 { "path": "~/.ssh", "mode": "deny" }

221 ],

222 "envVars": [

223 { "name": "GITHUB_TOKEN", "mode": "deny" },

224 { "name": "NPM_TOKEN", "mode": "deny" }

225 ]

226 }

227 }

228}

229```

230

231每个条目都带有 `"mode": "deny"`，这是唯一支持的值。显式的 `mode` 字段使架构与未来的模式向前兼容。文件路径遵循与 `sandbox.filesystem.*` 设置相同的 [prefix rules](/zh-CN/settings#sandbox-path-prefixes)，来自每个 [settings scope](/zh-CN/settings#settings-precedence) 的条目被合并。因为唯一的模式是 `deny`，任何范围都可以添加限制，但没有任何范围可以删除它们。

232

233没有内置的凭证拒绝列表，因此只有你列出的文件和变量被限制。该设置仅影响沙箱化的 Bash 命令。要从所有子进程中删除 Anthropic 和云提供商凭证，无论是否进行沙箱处理，请设置 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/zh-CN/env-vars)。

234

205<h2 id="how-sandboxing-works">235<h2 id="how-sandboxing-works">

206 沙箱如何工作236 沙箱如何工作

207</h2>237</h2>

213沙箱化 Bash 工具将文件系统访问限制在特定目录：243沙箱化 Bash 工具将文件系统访问限制在特定目录：

214 244

215* **默认写入行为**：对当前工作目录及其子目录的读写访问，加上 `$TMPDIR` 指向的会话临时目录245* **默认写入行为**：对当前工作目录及其子目录的读写访问，加上 `$TMPDIR` 指向的会话临时目录

216* **默认读取行为**：对整个计算机的读取访问，除了某些被拒绝的目录。注意此默认仍允许读取凭证文件，例如 `~/.aws/credentials` 和 `~/.ssh/`。将它们添加到 `denyRead` 以阻止它们。246* **默认读取行为**：对整个计算机的读取访问，除了某些被拒绝的目录。注意此默认仍允许读取凭证文件，例如 `~/.aws/credentials` 和 `~/.ssh/`。使用 [`sandbox.credentials`](#protect-credentials) 阻止读取这些文件并取消设置密钥环境变量，或将路径添加到 `denyRead`。

217* **被阻止的访问**：无法在没有明确权限的情况下修改当前工作目录和会话临时目录外的文件，包括 shell 配置文件（例如 `~/.bashrc`）和 `/bin/` 中的系统二进制文件247* **被阻止的访问**：无法在没有明确权限的情况下修改当前工作目录和会话临时目录外的文件，包括 shell 配置文件（例如 `~/.bashrc`）和 `/bin/` 中的系统二进制文件

218* **Git worktrees**：当工作目录是[链接的 git worktree](/zh-CN/worktrees)时，沙箱还允许写入主存储库的共享 `.git` 目录，以便 `git commit` 等命令可以更新引用和索引。对该目录内的 `hooks/` 和 `config` 的写入仍然被拒绝。248* **Git worktrees**：当工作目录是[链接的 git worktree](/zh-CN/worktrees)时，沙箱还允许写入主存储库的共享 `.git` 目录，以便 `git commit` 等命令可以更新引用和索引。对该目录内的 `hooks/` 和 `config` 的写入仍然被拒绝。

219* **可配置**：通过设置定义自定义允许和拒绝的路径249* **可配置**：通过设置定义自定义允许和拒绝的路径

326* **`failIfUnavailable`**：缺少的依赖项（例如 Linux 上的 bubblewrap）会阻止 Claude Code 启动，而不是显示警告并回退到非沙箱化执行356* **`failIfUnavailable`**：缺少的依赖项（例如 Linux 上的 bubblewrap）会阻止 Claude Code 启动，而不是显示警告并回退到非沙箱化执行

327* **`allowUnsandboxedCommands: false`**：`dangerouslyDisableSandbox` 逃生舱被忽略，因此在沙箱下失败的命令无法在其外重试357* **`allowUnsandboxedCommands: false`**：`dangerouslyDisableSandbox` 逃生舱被忽略，因此在沙箱下失败的命令无法在其外重试

328 358

329值得考虑与它们一起添加两个补充。为任何必须在没有隔离的情况下运行的组织批准的工具添加 `excludedCommands`。为凭证目录（例如 `~/.aws` 和 `~/.ssh`）添加 [`denyRead`](#filesystem-isolation) 条目，默认读取策略仍允许这些。359值得考虑与它们一起添加两个补充。为任何必须在没有隔离的情况下运行的组织批准的工具添加 `excludedCommands`。为凭证目录（例如 `~/.aws` 和 `~/.ssh`）和秘密环境变量添加 [`sandbox.credentials`](#protect-credentials) 条目，因为默认读取策略仍允许这些。

330 360

331沙箱不在原生 Windows 上运行，因此如果你的队伍包括 Windows 主机，请将此配置的范围限制在 macOS 和 Linux，或让这些用户在 WSL2 或容器内运行 Claude Code。361沙箱不在原生 Windows 上运行，因此如果你的队伍包括 Windows 主机，请将此配置的范围限制在 macOS 和 Linux，或让这些用户在 WSL2 或容器内运行 Claude Code。

332 362

417 447

418* **内置文件工具**：Read、Edit 和 Write 直接使用权限系统，而不是通过沙箱运行。请参阅 [permissions](/zh-CN/permissions)。448* **内置文件工具**：Read、Edit 和 Write 直接使用权限系统，而不是通过沙箱运行。请参阅 [permissions](/zh-CN/permissions)。

419* **计算机使用**：当 Claude 打开应用程序并控制你的屏幕时，它在你的实际桌面上运行，而不是在隔离的环境中。每个应用程序的权限提示控制每个应用程序。请参阅 [CLI 中的计算机使用](/zh-CN/computer-use) 或 [Desktop 中的计算机使用](/zh-CN/desktop#let-claude-use-your-computer)。449* **计算机使用**：当 Claude 打开应用程序并控制你的屏幕时，它在你的实际桌面上运行，而不是在隔离的环境中。每个应用程序的权限提示控制每个应用程序。请参阅 [CLI 中的计算机使用](/zh-CN/computer-use) 或 [Desktop 中的计算机使用](/zh-CN/desktop#let-claude-use-your-computer)。

420* **环境变量**：沙箱化 Bash 命令默认继承父进程环境，包括在那里设置的任何凭证。要从子进程中删除 Anthropic 和云提供商凭证，请设置 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/zh-CN/env-vars)。450* **环境变量**：沙箱化 Bash 命令默认继承父进程环境，包括在那里设置的任何凭证。使用 [`sandbox.credentials`](#protect-credentials) 为沙箱化命令取消设置特定变量，或设置 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/zh-CN/env-vars) 以从所有子进程中删除 Anthropic 和云提供商凭证。

421* **子代理**：[subagents](/zh-CN/sub-agents) 在与父会话相同的进程中运行，并使用相同的沙箱配置。当在父会话中启用沙箱时，子代理内的 Bash 命令被沙箱化。451* **子代理**：[subagents](/zh-CN/sub-agents) 在与父会话相同的进程中运行，并使用相同的沙箱配置。当在父会话中启用沙箱时，子代理内的 Bash 命令被沙箱化。

422 452

423<Warning>453<Warning>

server-managed-settings.md +6 −5

Details

6 6

7> 通过 Claude.ai 上基于网络的界面为您的组织集中配置 Claude Code，无需设备管理基础设施。7> 通过 Claude.ai 上基于网络的界面为您的组织集中配置 Claude Code，无需设备管理基础设施。

8 8

9服务器管理的设置允许管理员通过 Claude.ai 上基于网络的界面集中配置 Claude Code。Claude Code 客户端在用户使用其组织凭证进行身份验证时自动接收这些设置。9服务器管理的设置允许管理员通过 Claude.ai 上基于网络的界面集中配置 Claude Code。Claude Code 客户端在用户使用组织 OAuth 登录或直接配置的 API 密钥进行身份验证时自动接收这些设置，在支持服务器管理交付的平台上。请参阅[平台可用性](#platform-availability)。

10 10

11这种方法专为没有设备管理基础设施的组织或需要为非托管设备上的用户管理设置的组织而设计。11这种方法专为没有设备管理基础设施的组织或需要为非托管设备上的用户管理设置的组织而设计。

12 12

37 37

38如果您的设备已在 MDM 或端点管理解决方案中注册，端点管理的设置提供更强的安全保证，因为设置文件可以在操作系统级别受到保护，防止用户修改。38如果您的设备已在 MDM 或端点管理解决方案中注册，端点管理的设置提供更强的安全保证，因为设置文件可以在操作系统级别受到保护，防止用户修改。端点管理的设置不会到达[云会话](/zh-CN/model-config#surface-coverage)，因此在网络上使用 Claude Code 的组织也应该配置服务器管理的设置。

39 39

40<h2 id="configure-server-managed-settings">40<h2 id="configure-server-managed-settings">

41 配置服务器管理的设置41 配置服务器管理的设置

228 平台可用性228 平台可用性

229</h2>229</h2>

230 230

231服务器管理的设置需要直接连接到 `api.anthropic.com`，在使用第三方模型提供商时不可用：231服务器管理的设置需要直接连接到 `api.anthropic.com`，并且交付需要会话使用组织 OAuth 登录或直接配置的 API 密钥进行身份验证：由 [`apiKeyHelper`](/zh-CN/settings#available-settings) 脚本返回的密钥不会触发设置获取。在使用第三方模型提供商时，服务器管理的设置不可用：

232 232

233* Amazon Bedrock233* Amazon Bedrock

234* Google Vertex AI234* Google Vertex AI

235* Microsoft Foundry235* Microsoft Foundry

236* [Claude Platform on AWS](/zh-CN/claude-platform-on-aws)

236* 通过 `ANTHROPIC_BASE_URL` 或 [LLM gateways](/zh-CN/llm-gateway) 的自定义 API 端点237* 通过 `ANTHROPIC_BASE_URL` 或 [LLM gateways](/zh-CN/llm-gateway) 的自定义 API 端点

237 238

238<h2 id="audit-logging">239<h2 id="audit-logging">

250服务器管理的设置提供集中的策略强制执行，但它们作为客户端控制运行。在非托管设备上，具有管理员或 sudo 访问权限的用户可以修改 Claude Code 二进制文件、文件系统或网络配置。251服务器管理的设置提供集中的策略强制执行，但它们作为客户端控制运行。在非托管设备上，具有管理员或 sudo 访问权限的用户可以修改 Claude Code 二进制文件、文件系统或网络配置。

251 252

252| 场景 | 行为 |253| 场景 | 行为 |

253| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |254| :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

254| 用户编辑缓存的设置文件 | 篡改的文件在启动时应用，但正确的设置在下次服务器获取时恢复 |255| 用户编辑缓存的设置文件 | 篡改的文件在启动时应用，但正确的设置在下次服务器获取时恢复 |

255| 用户删除缓存的设置文件 | 首次启动行为发生：设置异步获取，有一个简短的未强制执行的窗口 |256| 用户删除缓存的设置文件 | 首次启动行为发生：设置异步获取，有一个简短的未强制执行的窗口 |

256| API 不可用 | 如果可用，缓存的设置应用，否则托管设置在下次成功获取前不被强制执行。使用 `forceRemoteSettingsRefresh: true` 时，CLI 退出而不是继续，除了 [`claude auth` 子命令](#enforce-fail-closed-startup) |257| API 不可用 | 如果可用，缓存的设置应用，否则托管设置在下次成功获取前不被强制执行。使用 `forceRemoteSettingsRefresh: true` 时，CLI 退出而不是继续，除了 [`claude auth` 子命令](#enforce-fail-closed-startup) |

257| 用户使用不同的组织进行身份验证 | 不为托管组织外的账户传递设置 |258| 用户使用不同的组织进行身份验证 | 不为托管组织外的账户传递设置 |

258| 用户配置[第三方模型提供商](#platform-availability) | 服务器管理的设置被绕过。这包括设置 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_MANTLE`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY` 或非默认的 `ANTHROPIC_BASE_URL` |259| 用户配置[第三方模型提供商](#platform-availability) | 服务器管理的设置被绕过。这包括设置 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_MANTLE`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY`、`CLAUDE_CODE_USE_ANTHROPIC_AWS` 或非默认的 `ANTHROPIC_BASE_URL` |

259 260

260要检测运行时配置更改，请使用 [`ConfigChange` hooks](/zh-CN/hooks#configchange) 来记录修改或在未授权的更改生效前阻止它们。261要检测运行时配置更改，请使用 [`ConfigChange` hooks](/zh-CN/hooks#configchange) 来记录修改或在未授权的更改生效前阻止它们。

261 262

settings.md +15 −8

Details

19</h3>19</h3>

20 20

21| 作用域 | 位置 | 影响范围 | 与团队共享？ |21| 作用域 | 位置 | 影响范围 | 与团队共享？ |

~~22| :---------- | :----------------------------------------------- | :---------- | :------------ |~~22| :---------- | :----------------------------------------------- | :---------------------------------------------------------- | :------------ |

24| **User** | `~/.claude/` 目录 | 您，跨所有项目 | 否 |24| **User** | `~/.claude/` 目录 | 您，跨所有项目 | 否 |

230| `autoMode` | 自定义[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器阻止和允许的内容。包含 `environment`、`allow`、`soft_deny` 和 `hard_deny` 散文规则数组。在数组中包含字面字符串 `"$defaults"` 以在该位置继承内置规则。请参阅[配置自动模式](/zh-CN/auto-mode-config)。不从共享项目设置读取 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |230| `autoMode` | 自定义[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器阻止和允许的内容。包含 `environment`、`allow`、`soft_deny` 和 `hard_deny` 散文规则数组。在数组中包含字面字符串 `"$defaults"` 以在该位置继承内置规则。请参阅[配置自动模式](/zh-CN/auto-mode-config)。不从共享项目设置读取 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

232| `autoUpdatesChannel` | 遵循更新的发布渠道。使用 `"stable"` 获取通常约一周前的版本并跳过有主要回归的版本，或使用 `"latest"`（默认）获取最新版本。要完全禁用自动更新，请在 `env` 中设置 [`DISABLE_AUTOUPDATER`](/zh-CN/setup#disable-auto-updates) | `"stable"` |232| `autoUpdatesChannel` | 遵循更新的发布渠道。使用 `"stable"` 获取通常约一周前的版本并跳过有主要回归的版本，或使用 `"latest"`（默认）获取最新版本。要完全禁用自动更新，请在 `env` 中设置 [`DISABLE_AUTOUPDATER`](/zh-CN/setup#disable-auto-updates) | `"stable"` |

233| `availableModels` | 限制用户可以为主会话、[subagents](/zh-CN/sub-agents) 和 [advisor](/zh-CN/advisor) 选择的模型。请参阅[限制模型选择](/zh-CN/model-config#restrict-model-selection)。另请参阅 `enforceAvailableModels` 以同时限制默认模型 | `["sonnet", "haiku"]` |233| `availableModels` | 限制用户可以为主会话、[subagents](/zh-CN/sub-agents)、[skills](/zh-CN/skills) 和 [advisor](/zh-CN/advisor) 选择的模型。不影响默认选项，除非 `enforceAvailableModels` 也被设置。请参阅[限制模型选择](/zh-CN/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |

258| `effortLevel` | 跨会话持久化[努力级别](/zh-CN/model-config#adjust-effort-level)。接受 `"low"`、`"medium"`、`"high"` 或 `"xhigh"`。当您运行 `/effort` 时自动写入，带有这些值之一。`--effort` 和 [`CLAUDE_CODE_EFFORT_LEVEL`](/zh-CN/env-vars) 覆盖此用于一个会话。请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level)了解支持的模型 | `"xhigh"` |258| `effortLevel` | 跨会话持久化[努力级别](/zh-CN/model-config#adjust-effort-level)。接受 `"low"`、`"medium"`、`"high"` 或 `"xhigh"`。当您运行 `/effort` 时自动写入，带有这些值之一。`--effort` 和 [`CLAUDE_CODE_EFFORT_LEVEL`](/zh-CN/env-vars) 覆盖此用于一个会话。请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level)了解支持的模型 | `"xhigh"` |

261| `enforceAvailableModels` | {/* min-version: 2.1.175 */}当为 `true` 且 `availableModels` 是 managed 或策略设置中的非空列表时，默认模型也被限制在允许列表中。请参阅[限制模型选择](/zh-CN/model-config#restrict-model-selection)了解详情和[合并行为](/zh-CN/model-config#merge-behavior)当 `availableModels` 在多个级别设置时。需要 Claude Code v2.1.175 或更高版本 | `true` |261| `enforceAvailableModels` | {/* min-version: 2.1.175 */}将 `availableModels` 允许列表扩展到默认模型。当在 managed 设置中为 `true` 且 `availableModels` 是非空数组时，默认选项回退到第一个可用的允许列表条目。当 `availableModels` 未设置或为空时无效。请参阅[为默认模型强制执行允许列表](/zh-CN/model-config#enforce-the-allowlist-for-the-default-model)。需要 Claude Code v2.1.175 或更高版本 | `true` |

262| `env` | 应用于每个会话和 Claude Code 从其生成的子进程的环境变量。{/* min-version: 2.1.143 */}从 v2.1.143 开始，此处设置的 `NO_COLOR` 和 `FORCE_COLOR` 被传递到子进程，但不改变 Claude Code 自己的界面颜色。在启动 `claude` 前在您的 shell 中设置这些以改变界面颜色 | `{"FOO": "bar"}` |262| `env` | 应用于每个会话和 Claude Code 从其生成的子进程的环境变量。{/* min-version: 2.1.143 */}从 v2.1.143 开始，此处设置的 `NO_COLOR` 和 `FORCE_COLOR` 被传递到子进程，但不改变 Claude Code 自己的界面颜色。在启动 `claude` 前在您的 shell 中设置这些以改变界面颜色 | `{"FOO": "bar"}` |

263| `fallbackModel` | 当主模型过载或不可用时按顺序尝试的备用模型。Claude Code 为该轮的其余部分切换到链中的下一个可用模型并显示通知。`"default"` 扩展为默认模型。链限制为三个模型；额外条目被忽略。与大多数数组设置不同，此键不跨设置文件合并：定义它的最高优先级文件提供整个链。[`--fallback-model`](/zh-CN/cli-reference#cli-flags) 标志覆盖此用于一个会话。请参阅[备用模型链](/zh-CN/model-config#fallback-model-chains) | `["claude-sonnet-4-6", "claude-haiku-4-5"]` |263| `fallbackModel` | 当主模型过载或不可用时按顺序尝试的备用模型。Claude Code 为该轮的其余部分切换到链中的下一个可用模型并显示通知。`"default"` 扩展为默认模型。链限制为三个模型；额外条目被忽略。与大多数数组设置不同，此键不跨设置文件合并：定义它的最高优先级文件提供整个链。[`--fallback-model`](/zh-CN/cli-reference#cli-flags) 标志覆盖此用于一个会话。请参阅[备用模型链](/zh-CN/model-config#fallback-model-chains) | `["claude-sonnet-4-6", "claude-haiku-4-5"]` |

264| `fastModePerSessionOptIn` | 当为 `true` 时，快速模式不会跨会话持久化。每个会话都以快速模式关闭开始，需要用户使用 `/fast` 启用它。用户的快速模式偏好仍被保存。请参阅[需要每个会话的选择加入](/zh-CN/fast-mode#require-per-session-opt-in) | `true` |264| `fastModePerSessionOptIn` | 当为 `true` 时，快速模式不会跨会话持久化。每个会话都以快速模式关闭开始，需要用户使用 `/fast` 启用它。用户的快速模式偏好仍被保存。请参阅[需要每个会话的选择加入](/zh-CN/fast-mode#require-per-session-opt-in) | `true` |

394配置高级 sandboxing 行为。Sandboxing 将 bash 命令与您的文件系统和网络隔离。请参阅 [Sandboxing](/zh-CN/sandboxing) 了解详情。394配置高级 sandboxing 行为。Sandboxing 将 bash 命令与您的文件系统和网络隔离。请参阅 [Sandboxing](/zh-CN/sandboxing) 了解详情。

395 395

396| 键 | 描述 | 示例 |396| 键 | 描述 | 示例 |

397| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------- |397| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |

399| `failIfUnavailable` | 如果 `sandbox.enabled` 为 true 但 sandbox 无法启动（缺少依赖项或不支持的平台），则在启动时以错误退出。当为 false（默认）时，显示警告，命令无 sandbox 运行。用于需要 sandboxing 作为硬门的 managed 设置部署 | `true` |399| `failIfUnavailable` | 如果 `sandbox.enabled` 为 true 但 sandbox 无法启动（缺少依赖项或不支持的平台），则在启动时以错误退出。当为 false（默认）时，显示警告，命令无 sandbox 运行。用于需要 sandboxing 作为硬门的 managed 设置部署 | `true` |

406| `filesystem.allowRead` | 在 `denyRead` 区域内重新允许读取的路径。优先于 `denyRead`。数组跨所有设置作用域合并。使用此创建仅工作区读取访问模式。 | `["."]` |406| `filesystem.allowRead` | 在 `denyRead` 区域内重新允许读取的路径。优先于 `denyRead`。数组跨所有设置作用域合并。使用此创建仅工作区读取访问模式。 | `["."]` |

408| `credentials.files` | Credential 文件或目录，sandboxed 命令无法读取。应用与 `filesystem.denyRead` 相同的读取块；单独的键将凭证路径与 `credentials.envVars` 分组，与一般文件系统规则分开。每个条目是 `{ "path": "...", "mode": "deny" }`。路径使用与 `filesystem.*` 设置相同的[前缀](#sandbox-path-prefixes)。数组跨所有设置作用域合并。仅支持 `deny`。需要 Claude Code v2.1.187 或更高版本。 | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |

409| `credentials.envVars` | 在运行 sandboxed 命令前要取消设置的环境变量。每个条目是 `{ "name": "...", "mode": "deny" }`。数组跨所有设置作用域合并。仅支持 `deny`。需要 Claude Code v2.1.187 或更高版本。 | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |

408| `network.allowUnixSockets` | （仅 macOS）sandbox 中可访问的 Unix socket 路径。在 Linux 和 WSL2 上被忽略，其中 seccomp 过滤器无法检查 socket 路径；改用 `allowAllUnixSockets`。 | `["~/.ssh/agent-socket"]` |410| `network.allowUnixSockets` | （仅 macOS）sandbox 中可访问的 Unix socket 路径。在 Linux 和 WSL2 上被忽略，其中 seccomp 过滤器无法检查 socket 路径；改用 `allowAllUnixSockets`。 | `["~/.ssh/agent-socket"]` |

409| `network.allowAllUnixSockets` | 允许 sandbox 中的所有 Unix socket 连接。在 Linux 和 WSL2 上这是允许 Unix sockets 的唯一方式，因为它跳过了 seccomp 过滤器，否则会阻止 `socket(AF_UNIX, ...)` 调用。默认：false | `true` |411| `network.allowAllUnixSockets` | 允许 sandbox 中的所有 Unix socket 连接。在 Linux 和 WSL2 上这是允许 Unix sockets 的唯一方式，因为它跳过了 seccomp 过滤器，否则会阻止 `socket(AF_UNIX, ...)` 调用。默认：false | `true` |

424 Sandbox 路径前缀426 Sandbox 路径前缀

425</h4>427</h4>

426 428

427`filesystem.allowWrite`、`filesystem.denyWrite`、`filesystem.denyRead` 和 `filesystem.allowRead` 中的路径支持这些前缀：429`filesystem.allowWrite`、`filesystem.denyWrite`、`filesystem.denyRead`、`filesystem.allowRead` 和 `credentials.files` 中的路径支持这些前缀：

428 430

429| 前缀 | 含义 | 示例 |431| 前缀 | 含义 | 示例 |

430| :-------- | :---------------------------------- | :---------------------------------------------------------------- |432| :-------- | :---------------------------------- | :---------------------------------------------------------------- |

674例如，如果您的用户设置将 `permissions.defaultMode` 设置为 `acceptEdits`，而项目的共享设置将其设置为 `default`，则项目值适用。下面的示例涵盖了数组值设置（如权限规则）如何组合的方式。676例如，如果您的用户设置将 `permissions.defaultMode` 设置为 `acceptEdits`，而项目的共享设置将其设置为 `default`，则项目值适用。下面的示例涵盖了数组值设置（如权限规则）如何组合的方式。

675 677

676<Note>678<Note>

677 **数组设置跨作用域合并。** 当相同的数组值设置（例如 `sandbox.filesystem.allowWrite` 或 `permissions.allow`）出现在多个作用域中时，数组被**连接和去重**，而不是替换。这意味着较低优先级的作用域可以添加条目而不覆盖由较高优先级作用域设置的条目，反之亦然。例如，如果 managed 设置将 `allowWrite` 设置为 `["/opt/company-tools"]`，用户添加 `["~/.kube"]`，则最终配置中包含两个路径。唯一的例外是 [`fallbackModel`](#available-settings)，一个有序链，其中位置具有意义：定义它的最高优先级文件提供整个值，以及 {/* min-version: 2.1.175 */}从 v2.1.175 开始，[`availableModels`](#available-settings)，其中 managed 或策略值完全替换较低优先级条目。请参阅[合并行为](/zh-CN/model-config#merge-behavior)。679 **数组设置跨作用域合并。** 当相同的数组值设置（例如 `sandbox.filesystem.allowWrite` 或 `permissions.allow`）出现在多个作用域中时，数组被**连接和去重**，而不是替换。这意味着较低优先级的作用域可以添加条目而不覆盖由较高优先级作用域设置的条目，反之亦然。例如，如果 managed 设置将 `allowWrite` 设置为 `["/opt/company-tools"]`，用户添加 `["~/.kube"]`，则最终配置中包含两个路径。

680

681 两个数组设置不以这种方式合并：

682

683 * [`fallbackModel`](#available-settings) 是一个有序链，其中位置具有意义：定义它的最高优先级文件提供整个值。

684 * [`availableModels`](#available-settings)：{/* min-version: 2.1.175 */}当[最高优先级 managed 源](/zh-CN/server-managed-settings#settings-precedence)定义它时，该列表按原样应用，用户、项目和本地条目无法扩展它。跨非 managed 作用域，数组照常合并。请参阅[合并行为](/zh-CN/model-config#merge-behavior)。

678</Note>685</Note>

679 686

680<h3 id="verify-active-settings">687<h3 id="verify-active-settings">

696* **Skills**：可以使用 `/skill-name` 调用或由 Claude 自动加载的自定义提示703* **Skills**：可以使用 `/skill-name` 调用或由 Claude 自动加载的自定义提示

697* **MCP servers**：使用额外的工具和集成扩展 Claude Code704* **MCP servers**：使用额外的工具和集成扩展 Claude Code

698* **优先级**：更高级别的配置（Managed）覆盖较低级别的配置（User/Project）705* **优先级**：更高级别的配置（Managed）覆盖较低级别的配置（User/Project）

699* **继承**：设置被合并跨作用域；来自较高优先级作用域的标量值覆盖，数组连接。例外：`fallbackModel`，其中最高优先级作用域提供整个链，以及 `availableModels`，其中 managed 或策略值完全替换较低优先级条目706* **继承**：设置被合并跨作用域；来自较高优先级作用域的标量值覆盖，数组连接，有两个例外，如[数组合并注释](#settings-precedence)中所述

700 707

701<h3 id="system-prompt">708<h3 id="system-prompt">

702 系统提示709 系统提示

skills.md +2 −2

Details

245所有字段都是可选的。建议使用 `description`，以便 Claude 知道何时使用该 skill。245所有字段都是可选的。建议使用 `description`，以便 Claude 知道何时使用该 skill。

246 246

247| 字段 | 必需 | 描述 |247| 字段 | 必需 | 描述 |

248| :------------------------- | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |248| :------------------------- | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

249| `name` | 否 | Skill 列表中显示的显示名称。默认为目录名称。请参阅[Skill 如何获得其命令名称](#how-a-skill-gets-its-command-name)以了解这与你输入的名称在 `/` 后的调用方式有何不同。 |249| `name` | 否 | Skill 列表中显示的显示名称。默认为目录名称。请参阅[Skill 如何获得其命令名称](#how-a-skill-gets-its-command-name)以了解这与你输入的名称在 `/` 后的调用方式有何不同。 |

250| `description` | 推荐 | Skill 的功能以及何时使用它。Claude 使用它来决定何时应用该 skill。如果省略，使用 markdown 内容的第一段。将关键用例放在前面：组合的 `description` 和 `when_to_use` 文本在 skill 列表中被截断为 1,536 个字符以减少上下文使用。 |250| `description` | 推荐 | Skill 的功能以及何时使用它。Claude 使用它来决定何时应用该 skill。如果省略，使用 markdown 内容的第一段。将关键用例放在前面：组合的 `description` 和 `when_to_use` 文本在 skill 列表中被截断为 1,536 个字符以减少上下文使用。 |

251| `when_to_use` | 否 | 关于 Claude 何时应该调用该 skill 的额外上下文，例如触发短语或示例请求。附加到 skill 列表中的 `description`，并计入 1,536 个字符的上限。 |251| `when_to_use` | 否 | 关于 Claude 何时应该调用该 skill 的额外上下文，例如触发短语或示例请求。附加到 skill 列表中的 `description`，并计入 1,536 个字符的上限。 |

255| `user-invocable` | 否 | 设置为 `false` 以从 `/` 菜单中隐藏。用于用户不应直接调用的背景知识。默认值：`true`。 |255| `user-invocable` | 否 | 设置为 `false` 以从 `/` 菜单中隐藏。用于用户不应直接调用的背景知识。默认值：`true`。 |

256| `allowed-tools` | 否 | 当此 skill 处于活动状态时，Claude 可以使用而无需请求权限的工具。接受空格分隔的字符串或 YAML 列表。 |256| `allowed-tools` | 否 | 当此 skill 处于活动状态时，Claude 可以使用而无需请求权限的工具。接受空格分隔的字符串或 YAML 列表。 |

257| `disallowed-tools` | 否 | 当此 skill 处于活动状态时从 Claude 的可用工具池中移除的工具。用于不应该调用某些工具的自主 skills，例如用于后台循环的 `AskUserQuestion`。接受空格分隔的字符串或 YAML 列表。当你发送下一条消息时，限制会清除。 |257| `disallowed-tools` | 否 | 当此 skill 处于活动状态时从 Claude 的可用工具池中移除的工具。用于不应该调用某些工具的自主 skills，例如用于后台循环的 `AskUserQuestion`。接受空格分隔的字符串或 YAML 列表。当你发送下一条消息时，限制会清除。 |

258| `model` | 否 | 当此 skill 处于活动状态时要使用的模型。覆盖适用于当前轮的其余部分，不保存到设置；会话模型在你的下一个提示时恢复。接受与 [`/model`](/zh-CN/model-config) 相同的值，或 `inherit` 以保持活动模型。 |258| `model` | 否 | 当此 skill 处于活动状态时要使用的模型。覆盖适用于当前轮的其余部分，不保存到设置；会话模型在你的下一个提示时恢复。接受与 [`/model`](/zh-CN/model-config) 相同的值，或 `inherit` 以保持活动模型。被你的组织的 [`availableModels`](/zh-CN/model-config#restrict-model-selection) 允许列表排除的值不会被使用，会话保持其当前模型。 |

259| `effort` | 否 | 当此 skill 处于活动状态时的[工作量级别](/zh-CN/model-config#adjust-effort-level)。覆盖会话工作量级别。默认值：继承自会话。选项：`low`、`medium`、`high`、`xhigh`、`max`；可用级别取决于模型。 |259| `effort` | 否 | 当此 skill 处于活动状态时的[工作量级别](/zh-CN/model-config#adjust-effort-level)。覆盖会话工作量级别。默认值：继承自会话。选项：`low`、`medium`、`high`、`xhigh`、`max`；可用级别取决于模型。 |

260| `context` | 否 | 设置为 `fork` 以在分叉的 subagent 上下文中运行。 |260| `context` | 否 | 设置为 `fork` 以在分叉的 subagent 上下文中运行。 |

261| `agent` | 否 | 当设置 `context: fork` 时要使用的 subagent 类型。 |261| `agent` | 否 | 当设置 `context: fork` 时要使用的 subagent 类型。 |

sub-agents.md +4 −0

Details

3173. Subagent 定义的 `model` frontmatter3173. Subagent 定义的 `model` frontmatter

3184. 主对话的模型3184. 主对话的模型

319 319

320环境变量、每次调用的参数和 frontmatter 值会根据您组织的 [`availableModels`](/zh-CN/model-config#restrict-model-selection) 允许列表进行检查。解析为排除模型的值不会被使用，subagent 会改为在继承的模型上运行。

321

320<h3 id="control-subagent-capabilities">322<h3 id="control-subagent-capabilities">

321 控制 subagent 能力323 控制 subagent 能力

322</h3>324</h3>

849 851

850深度计算为主对话下方的 subagent 级别数，无论每个级别是否在 [前台或后台](#run-subagents-in-foreground-or-background) 运行。深度为五的 subagent 不接收 Agent 工具，无法进一步生成。限制是固定的且不可配置。852深度计算为主对话下方的 subagent 级别数，无论每个级别是否在 [前台或后台](#run-subagents-in-foreground-or-background) 运行。深度为五的 subagent 不接收 Agent 工具，无法进一步生成。限制是固定的且不可配置。

851 853

854从 Claude Code v2.1.187 开始，后台 subagent 的深度在首次生成时是固定的，[恢复](#resume-subagents)它稍后不会改变该深度。例如，如果您的主对话生成 subagent A，而 A 在深度二生成后台 subagent B，当您直接从主对话恢复 B 时，B 仍然在深度二。从更浅的上下文恢复 subagent 不会让它生成深度限制已经阻止的额外级别。

855

852要防止特定 subagent 生成其他 subagents，从其 [`tools`](#available-tools) 列表中省略 `Agent` 或将其添加到 `disallowedTools`。856要防止特定 subagent 生成其他 subagents，从其 [`tools`](#available-tools) 列表中省略 `Agent` 或将其添加到 `disallowedTools`。

853 857

854[fork](#fork-the-current-conversation) 仍然无法生成另一个 fork。它可以生成其他 subagent 类型，这些计入深度限制。858[fork](#fork-the-current-conversation) 仍然无法生成另一个 fork。它可以生成其他 subagent 类型，这些计入深度限制。

voice-dictation.md +3 −3

Details

34 34

35```35```

36/voice36/voice

~~37Voice mode enabled (hold). Hold Space to record. Dictation language: en (/config to change).~~37Voice mode enabled (hold). Hold space to record. Dictation language: en (/config to change).

38```38```

39 39

40`/voice` 接受一个可选的模式参数：40`/voice` 接受一个可选的模式参数：

57}57}

58```58```

59 59

60启用语音听写时，当提示词为空时，输入页脚会显示 `hold Space to speak` 提示。提示文本反映你当前的 `voice:pushToTalk` 快捷键绑定，如果你[重新绑定听写键](#rebind-the-dictation-key)，它会更新。提示文本在两种模式中都相同，如果你配置了[自定义状态行](/zh-CN/statusline)，则不会显示。60启用语音听写时，当提示词为空时，输入页脚会显示 `hold space to speak` 提示。提示文本反映你当前的 `voice:pushToTalk` 快捷键绑定，如果你[重新绑定听写键](#rebind-the-dictation-key)，它会更新。提示文本在两种模式中都相同，如果你配置了[自定义状态行](/zh-CN/statusline)，则不会显示。

61 61

62转录在两种模式中都针对编码词汇进行了调整。常见的开发术语如 `regex`、`OAuth`、`JSON` 和 `localhost` 被正确识别，你当前的项目名称和 git 分支名称会自动添加为识别提示。62转录在两种模式中都针对编码词汇进行了调整。常见的开发术语如 `regex`、`OAuth`、`JSON` 和 `localhost` 被正确识别，你当前的项目名称和 git 分支名称会自动添加为识别提示。

63 63

79 79

80```80```

81> refactor the auth middleware to ▮81> refactor the auth middleware to ▮

~~82 # hold Space, speak "use the new token validation helper"~~82 # hold space, speak "use the new token validation helper"

83> refactor the auth middleware to use the new token validation helper▮83> refactor the auth middleware to use the new token validation helper▮

84```84```

85 85

Documentation 2026-06-23 22:00 UTC to 2026-06-24 22:02 UTC