Documentation — Spybara

admin-setup.md +42 −42

Details

83 83

84## 决定要强制执行的内容84## 决定要强制执行的内容

85 85

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

87 87

~~88| 控制 | 它的作用 | 关键设置 |~~88| 控制项 | 作用 | 关键设置 |

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

91| [Permission lockdown](https://code.claude.com/docs/zh-CN/permissions.md#managed-only-settings) | 使托管设置成为[权限规则的唯一设置源](https://code.claude.com/docs/zh-CN/settings-reference.md#allowmanagedpermissionrulesonly)。禁用 `--dangerously-skip-permissions` | `allowManagedPermissionRulesOnly`、`permissions.disableBypassPermissionsMode` |91| [权限锁定](https://code.claude.com/docs/zh-CN/permissions.md#managed-only-settings) | 使托管设置成为[权限规则的唯一设置来源](https://code.claude.com/docs/zh-CN/settings-reference.md#allowmanagedpermissionrulesonly)。禁用 `--dangerously-skip-permissions` | `allowManagedPermissionRulesOnly`、`permissions.disableBypassPermissionsMode` |

92| [Starting permission mode](https://code.claude.com/docs/zh-CN/permission-modes.md#which-mode-a-session-starts-in) | 选择开发人员终端会话启动时的权限模式，而不是内置的启动权限模式，或删除自动模式。[Switch permission modes](https://code.claude.com/docs/zh-CN/permission-modes.md#switch-permission-modes) 列出 VS Code 扩展何时读取您设置的 `defaultMode` | `permissions.defaultMode`、`permissions.disableAutoMode` |92| [起始权限模式](https://code.claude.com/docs/zh-CN/permission-modes.md#which-mode-a-session-starts-in) | 选择开发人员的终端会话启动时所用的权限模式，以替代内置的起始权限模式，或移除自动模式。[切换权限模式](https://code.claude.com/docs/zh-CN/permission-modes.md#switch-permission-modes)列出了 VS Code 扩展何时读取您设置的 `defaultMode` | `permissions.defaultMode`、`permissions.disableAutoMode` |

95| [MCP server control](https://code.claude.com/docs/zh-CN/managed-mcp.md) | 限制用户可以添加或连接的 MCP 服务器、部署固定集合，或为每个用户提供远程服务器以及他们自己的服务器 | `allowedMcpServers`、`deniedMcpServers`、`allowManagedMcpServersOnly`、`managedMcpServers` 或已部署的 `managed-mcp.json` 文件 |95| [MCP 服务器控制](https://code.claude.com/docs/zh-CN/managed-mcp.md) | 限制用户可以添加或连接哪些 MCP 服务器、部署一组固定的服务器，或在用户自有服务器之外为每个用户提供远程服务器 | `allowedMcpServers`、`deniedMcpServers`、`allowManagedMcpServersOnly`、`managedMcpServers`，或已部署的 `managed-mcp.json` 文件 |

96| [Plugin marketplace control](https://code.claude.com/docs/zh-CN/plugins/org.md#restrict-what-users-can-install) | 限制用户可以添加和安装的市场来源，拒绝为单次运行侧加载插件、agents 和 MCP 服务器的 CLI 标志，阻止[`command` 插件源](https://code.claude.com/docs/zh-CN/plugins/marketplace-reference#command-plugin-source)，并允许列出哪些市场的插件可以被建议 | `strictKnownMarketplaces`、`blockedMarketplaces`、`disableSideloadFlags`、`disableCommandPluginSources`、`pluginSuggestionMarketplaces` |96| [插件市场控制](https://code.claude.com/docs/zh-CN/plugins/org.md#restrict-what-users-can-install) | 限制用户可以添加和从中安装的市场来源，并拒绝在单次运行中旁加载插件、Agent 和 MCP 服务器的 CLI 标志。阻止 [`command` 插件来源](https://code.claude.com/docs/zh-CN/plugins/marketplace-reference#command-plugin-source)，并通过允许列表指定哪些市场的插件可以在终端中被推荐 | `strictKnownMarketplaces`、`blockedMarketplaces`、`disableSideloadFlags`、`disableCommandPluginSources`、`pluginSuggestionMarketplaces` |

97| [Customization lockdown](https://code.claude.com/docs/zh-CN/settings-reference.md#strictpluginonlycustomization) | 阻止 skills、agents、hooks 和 MCP 服务器来自用户和项目源，使它们只能来自插件或托管设置。锁定 skills 也会停止[您的开发人员在 claude.ai 上启用的 skills](https://code.claude.com/docs/zh-CN/skills.md#where-synced-skills-load) 的同步 | `strictPluginOnlyCustomization` |97| [自定义锁定](https://code.claude.com/docs/zh-CN/settings-reference.md#strictpluginonlycustomization) | 阻止来自用户和项目来源的 skill、Agent、hook 和 MCP 服务器，使它们只能来自插件或托管设置。锁定 skill 还会停止同步[开发人员在 claude.ai 上启用的 skill](https://code.claude.com/docs/zh-CN/skills.md#where-synced-skills-load) | `strictPluginOnlyCustomization` |

98| [Disable claude.ai sync](https://code.claude.com/docs/zh-CN/settings-reference.md#syncclaudeaiskills) | 停止 Claude Code 加载[您的开发人员在 claude.ai 上启用的 skills](https://code.claude.com/docs/zh-CN/skills.md#how-synced-skills-behave) 和[插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#synced-plugins)。如果您为组织关闭 claude.ai 上的 Skills，Claude Code 会停止同步两者，在 v2.1.273 或更高版本上，它也会删除已同步的那些。要在不关闭 Skills 的情况下停止其中任一个，在托管设置中将其键设置为 `false` | `syncClaudeAiSkills`、`syncClaudeAiPlugins` |98| [禁用 claude.ai 同步](https://code.claude.com/docs/zh-CN/settings-reference.md#syncclaudeaiskills) | 阻止 Claude Code 加载开发人员在 claude.ai 上启用的 [skill](https://code.claude.com/docs/zh-CN/skills.md#how-synced-skills-behave) 和[插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#synced-plugins)。如果您在 claude.ai 上为组织关闭 Skills，Claude Code 会停止同步这两者，并且在 v2.1.273 或更高版本中还会移除已同步的内容。若要在不关闭 Skills 的情况下停止其中任意一项，请在托管设置中将其对应的键设置为 `false` | `syncClaudeAiSkills`、`syncClaudeAiPlugins` |

99| [Hook restrictions](https://code.claude.com/docs/zh-CN/settings-reference.md#allowmanagedhooksonly) | 限制哪些 hooks 运行并限制 HTTP hook URL；请参阅[`allowManagedHooksOnly` 下运行的内容](https://code.claude.com/docs/zh-CN/settings-reference#what-runs-under-allowmanagedhooksonly)了解完整的效果列表 | `allowManagedHooksOnly`、`allowedHttpHookUrls` |99| [Hook 限制](https://code.claude.com/docs/zh-CN/settings-reference.md#allowmanagedhooksonly) | 限制运行哪些 hook 并限制 HTTP hook URL；完整的影响列表请参阅[在 `allowManagedHooksOnly` 下运行的内容](https://code.claude.com/docs/zh-CN/settings-reference#what-runs-under-allowmanagedhooksonly) | `allowManagedHooksOnly`、`allowedHttpHookUrls` |

100| [Login enforcement](https://code.claude.com/docs/zh-CN/settings-reference.md#forceloginmethod) | 限制登录到特定方法或 Anthropic 组织。方法限制适用于 VS Code 扩展、Agent SDK、`claude setup-token` 和 `/install-github-app`，以及终端的交互式登录屏幕（通过 `/login` 或首次运行入门到达），预先选择方法但不强制执行；Claude Code 在终端、VS Code 扩展和 Agent SDK 中验证 claude.ai 账户登录的组织，不检查 Claude Console 登录或[网关](https://code.claude.com/docs/zh-CN/claude-apps-gateway)登录。在 v2.1.212 之前，仅终端登录应用任一密钥。设置后，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 进行身份验证的会话在启动时被阻止；云提供商会话不受影响，除非这些凭证之一或由较早的 Claude Console 登录保存的 API 密钥也存在 | `forceLoginMethod`、`forceLoginOrgUUID` |100| [登录强制](https://code.claude.com/docs/zh-CN/settings-reference.md#forceloginmethod) | 将登录限制为特定方式或特定 Anthropic 组织。方式限制适用于 VS Code 扩展、Agent SDK、`claude setup-token` 和 `/install-github-app`，而终端的交互式登录界面（通过 `/login` 或首次运行引导进入）会预先选中该方式，但不强制执行；Claude Code 会在终端、VS Code 扩展和 Agent SDK 中对 claude.ai 账户登录验证组织，但不会对 Claude Console 登录或[网关](https://code.claude.com/docs/zh-CN/claude-apps-gateway)登录检查组织。在 v2.1.212 之前，这两个键仅对终端登录生效。设置后，通过 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 进行身份验证的会话会在启动时被阻止；云提供商会话不受影响，除非同时存在上述凭据之一，或存在先前 Claude Console 登录时保存的 API 密钥 | `forceLoginMethod`、`forceLoginOrgUUID` |

101| [Provider restrictions](https://code.claude.com/docs/zh-CN/settings-reference.md#allowedproviders) | 限制机器可以使用的 API 提供商。不在列表中的提供商上的会话在启动时、登录时以及下次联系 API 时被拒绝。需要 Claude Code v2.1.285 或更高版本 | `allowedProviders` |101| [提供商限制](https://code.claude.com/docs/zh-CN/settings-reference.md#allowedproviders) | 限制一台机器可以使用哪些 API 提供商。使用未列出提供商的会话会在启动时、登录时以及下次联系 API 时被拒绝。需要 Claude Code v2.1.285 或更高版本 | `allowedProviders` |

102| [Disable agent view](https://code.claude.com/docs/zh-CN/agent-view.md#how-background-sessions-are-hosted) | 关闭 `claude agents`、`--bg`、`/background` 和按需监督程序 | `disableAgentView` |102| [禁用 Agent 视图](https://code.claude.com/docs/zh-CN/agent-view.md#how-background-sessions-are-hosted) | 关闭 `claude agents`、`--bg`、`/background` 和按需启动的监督进程 | `disableAgentView` |

103| [Configure the corporate launcher](https://code.claude.com/docs/zh-CN/corporate-launcher.md) | 使用必需的企业启动器作为[后台代理监督程序](https://code.claude.com/docs/zh-CN/agent-view.md#how-background-sessions-are-hosted)、其工作程序和[其他涵盖的后台进程](https://code.claude.com/docs/zh-CN/corporate-launcher.md#what-the-launcher-covers)的前缀，而不是关闭代理视图 | `processWrapper` |103| [配置企业启动器](https://code.claude.com/docs/zh-CN/corporate-launcher.md) | 为[后台 Agent 监督进程](https://code.claude.com/docs/zh-CN/agent-view.md#how-background-sessions-are-hosted)、其工作进程以及[其他涵盖的后台进程](https://code.claude.com/docs/zh-CN/corporate-launcher.md#what-the-launcher-covers)添加所需的企业启动器前缀，而不是关闭 Agent 视图 | `processWrapper` |

104| [Model restrictions](https://code.claude.com/docs/zh-CN/model-config.md#restrict-model-selection) | `availableModels` 筛选模型选择器中显示的模型。添加 `enforceAvailableModels` 也会限制自动选择的默认模型。请参阅[表面覆盖](https://code.claude.com/docs/zh-CN/model-config.md#surface-coverage)了解此设置如何到达 CLI、web 和 IDE | `availableModels`、`enforceAvailableModels` |104| [模型限制](https://code.claude.com/docs/zh-CN/model-config.md#restrict-model-selection) | `availableModels` 筛选选择器中显示哪些模型。添加 `enforceAvailableModels` 还会约束自动选择的默认模型。有关此设置如何作用于 CLI、Web 和 IDE，请参阅[使用入口覆盖范围](https://code.claude.com/docs/zh-CN/model-config.md#surface-coverage) | `availableModels`、`enforceAvailableModels` |

105| [Effort cap](https://code.claude.com/docs/zh-CN/settings-reference.md#maxeffortlevel) | 为每个模型或每个提供商上的每个模型限制[工作量级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level) | `maxEffortLevel` |105| [Effort 上限](https://code.claude.com/docs/zh-CN/settings-reference.md#maxeffortlevel) | 在所有提供商上为所有模型或按模型限制 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)的上限 | `maxEffortLevel` |

107| [Required version range](https://code.claude.com/docs/zh-CN/settings-reference.md#requiredminimumversion) | 当运行版本超出组织批准的范围时拒绝启动。比 `minimumVersion` 更强大，后者仅阻止降级 | `requiredMinimumVersion`、`requiredMaximumVersion` |107| [必需版本范围](https://code.claude.com/docs/zh-CN/settings-reference.md#requiredminimumversion) | 当运行的版本超出组织批准的范围时完全拒绝启动。比仅阻止降级的 `minimumVersion` 更严格 | `requiredMinimumVersion`、`requiredMaximumVersion` |

108| [Telemetry opt-out](https://code.claude.com/docs/zh-CN/data-usage.md#telemetry-services) | 在每台设备上关闭 Anthropic 绑定的使用指标、错误报告和调查 | `env` 设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 为 `1`；链接的部分列出了按类别的变量 |108| [选择退出遥测](https://code.claude.com/docs/zh-CN/data-usage.md#telemetry-services) | 在每台设备上关闭发送给 Anthropic 的使用指标、错误报告和调查 | 在 `env` 中将 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 设置为 `1`；链接的章节列出了各类别对应的变量 |

~~109~~ 109

110如果您的成员通过 claude.ai 或 Anthropic API 登录，并且您在 Claude Enterprise 计划上，您还可以从组织的管理设置中管理模型，而无需部署任何内容：110如果您的成员通过 claude.ai 或 Anthropic API 登录，并且您使用的是 Claude Enterprise 计划，您还可以在组织的管理设置中管理模型，无需部署任何内容：

~~111~~ 111

112* [Organization model restrictions](https://code.claude.com/docs/zh-CN/model-config.md#organization-model-restrictions)：禁用单个模型。在服务器端强制执行。112* [组织模型限制](https://code.claude.com/docs/zh-CN/model-config.md#organization-model-restrictions)：禁用单个模型。在服务器端强制执行。

113* [Organization default model](https://code.claude.com/docs/zh-CN/model-config.md#organization-default-model)：设置新会话启动时使用的模型。成员仍可切换模型。要在启动时将其恢复为您的默认模型，请启用该部分所述的覆盖设置。要限制成员可选择的模型，请使用[组织模型限制](https://code.claude.com/docs/zh-CN/model-config.md#organization-model-restrictions)。113* [组织默认模型](https://code.claude.com/docs/zh-CN/model-config.md#organization-default-model)：设置新会话启动时使用的模型。成员仍可切换模型。若要在启动时将其恢复为您的默认模型，请打开该章节中描述的覆盖选项。若要限制他们可以选择的模型，请使用[组织模型限制](https://code.claude.com/docs/zh-CN/model-config.md#organization-model-restrictions)。

114* [Organization effort limits](https://code.claude.com/docs/zh-CN/model-config.md#organization-effort-limits)：按角色限制工作量级别。在服务器端强制执行。114* [组织 effort 限制](https://code.claude.com/docs/zh-CN/model-config.md#organization-effort-limits)：按角色限制 effort 级别上限。在服务器端强制执行。

~~115~~ 115

116这些控制都不会到达 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 [Claude Platform on AWS](https://code.claude.com/docs/zh-CN/claude-platform-on-aws.md) 上的会话。在这些提供商上，使用托管设置代替：`availableModels` 用于限制，`model` 用于默认值，[`maxEffortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#maxeffortlevel) 用于工作量限制。116这些控制项均不作用于 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 [Claude Platform on AWS](https://code.claude.com/docs/zh-CN/claude-platform-on-aws.md) 上的会话。在这些提供商上，请改用托管设置：用 `availableModels` 进行限制，用 `model` 设置默认模型，用 [`maxEffortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#maxeffortlevel) 设置 effort 上限。

~~117~~ 117

118[Cloud sessions](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md) 在 claude.ai 上有其自己的管理入口：118[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)在 claude.ai 上有自己的管理入口：

~~119~~ 119

120* **Cloud environments 页面**：所有者创建[组织共享环境](https://code.claude.com/docs/zh-CN/cloud-environments.md#organization-shared-environments)，设置成员云端会话的[网络访问级别](https://code.claude.com/docs/zh-CN/cloud-environments.md#network-access)、环境变量和设置脚本。120* **云环境页面**：所有者创建[组织共享环境](https://code.claude.com/docs/zh-CN/cloud-environments.md#organization-shared-environments)，为成员的云端会话设置[网络访问级别](https://code.claude.com/docs/zh-CN/cloud-environments.md#network-access)、环境变量和设置脚本。

121* **默认环境**：所有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 单独选择组织的默认环境。121* **默认环境**：所有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 单独选择组织的默认环境。

122* **Git providers 页面**：请参阅[已关联的 GitHub 账户](#connected-github-accounts)，了解关联到您组织的 GitHub 账户。122* **Git 提供商页面**：有关关联到您组织的 GitHub 账户，请参阅[已连接的 GitHub 账户](#connected-github-accounts)。

123 123

124权限规则和沙箱覆盖不同的层。拒绝 WebFetch 会阻止 Claude 的 fetch 工具，但如果允许 Bash，`curl` 和 `wget` 仍然可以到达任何 URL。沙箱通过在操作系统级别强制执行的网络域允许列表来弥补这一差距。124权限规则和沙箱隔离覆盖不同的层级。拒绝 WebFetch 会阻止 Claude 的获取工具，但如果允许 Bash，`curl` 和 `wget` 仍然可以访问任何 URL。沙箱隔离通过在操作系统级别强制执行的网络域名允许列表来弥补这一缺口。

125 125

126有关这些控制防御的威胁模型，请参阅[安全性](https://code.claude.com/docs/zh-CN/security.md)。126有关这些控制项所防御的威胁模型，请参阅[安全](https://code.claude.com/docs/zh-CN/security.md)。

127 127

128### 已关联的 GitHub 账户128### 已连接的 GitHub 账户

129 129

130在 Team 和 Enterprise 计划中，[**Organization settings > Git providers**](https://claude.ai/admin-settings/source-control) 的 GitHub 部分列出了通过 [Claude GitHub App](https://github.com/apps/claude) 关联到您的 Claude 组织的 GitHub 组织和个人账户。Claude Code、[Claude Tag](https://claude.com/docs/claude-tag/admins/configure-github) 和 Claude Security 共享此列表。打开该页面需要在您的 Claude 组织中拥有管理员角色。130在 Team 和 Enterprise 计划中，[**Organization settings > Git providers**](https://claude.ai/admin-settings/source-control) 的 GitHub 部分列出了通过 [Claude GitHub App](https://github.com/apps/claude) 关联到您 Claude 组织的 GitHub 组织和个人账户。Claude Code、[Claude Tag](https://claude.com/docs/claude-tag/admins/configure-github) 和 Claude Security 共享该列表。打开此页面需要您在 Claude 组织中拥有管理员角色。

131 131

132管理员或成员都可以关联账户：132管理员或成员都可以关联账户：

133 133

134* **管理员连接**：管理员在该部分点击 **Connect**（或在已连接账户后点击 **Add organization**），并在某个 GitHub 组织上安装 Claude GitHub App。以这种方式关联组织，需要一个既是该 GitHub 组织所有者、又是您 Claude 组织管理员的人来操作。134* **管理员连接**：管理员在该部分点击 **Connect**，或在已连接账户后点击 **Add organization**，然后在 GitHub 组织上安装 Claude GitHub App。以这种方式关联组织，需要一个既是该 GitHub 组织所有者、又是您 Claude 组织管理员的人员。

135* **成员连接**：当成员将其 GitHub 账户连接到 Claude 时（例如在[设置云端会话](https://code.claude.com/docs/zh-CN/web-quickstart.md#connect-github)时），Claude 会关联该成员拥有且已安装 Claude GitHub App 的 GitHub 账户。这可能包括其个人账户以及其拥有的 GitHub 组织。135* **成员连接**：当成员将其 GitHub 账户连接到 Claude 时（例如在[设置云端会话](https://code.claude.com/docs/zh-CN/web-quickstart.md#connect-github)时），Claude 会关联该成员所拥有且已安装 Claude GitHub App 的 GitHub 账户。这可能包括其个人账户以及其拥有的 GitHub 组织。

136 136

137标记为 **Not linked** 的行来自您自己的 GitHub 登录。它是您在 GitHub 上可以看到且已安装 Claude GitHub App 的账户。137标记为 **Not linked** 的行来自您自己的 GitHub 登录。它是您在 GitHub 上可以看到且已安装 Claude GitHub App 的账户。

138 138

139要将某个账户与您的 Claude 组织取消关联，请打开该行的菜单并选择 **Unlink from this workspace**。取消关联后，Claude GitHub App 仍安装在 GitHub 上，下次该账户的某个所有者将 GitHub 连接到 Claude 时，该账户会再次被关联。要防止其再次被关联，请在 GitHub 上从该账户卸载 Claude GitHub App。139若要将某个账户与您的 Claude 组织取消关联，请打开该行的菜单并选择 **Unlink from this workspace**。取消关联后，Claude GitHub App 仍会保留在 GitHub 上，并且下次该账户的任一所有者将 GitHub 连接到 Claude 时，该账户会再次被关联。若要防止其再次被关联，请在 GitHub 上从该账户卸载 Claude GitHub App。

140 140

141在 Enterprise 计划中，用于关联和取消关联的 [Compliance API](https://platform.claude.com/docs/en/api/compliance/activities/list) 活动类型分别为 `github_app_installation_linked` 和 `github_app_installation_unlinked`。141在 Enterprise 计划中，用于关联和取消关联的 [Compliance API](https://platform.claude.com/docs/en/api/compliance/activities/list) 活动类型为 `github_app_installation_linked` 和 `github_app_installation_unlinked`。

142 142

143## 设置使用情况可见性143## 设置使用情况可见性

144 144

agent-sdk/agent-loop.md +2 −2

Details

236| `"dontAsk"` | 从不提示。由 [权限规则](https://code.claude.com/docs/zh-CN/settings-reference.md#permission-settings) 预批准的工具会运行，在 `default` 模式中不需要批准的调用（如您的工作目录内的文件读取）也会运行。所有其他会提示的调用都被拒绝，不过您安装的 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 仍可以批准[其中的部分调用](https://code.claude.com/docs/zh-CN/permissions.md#precedence-among-rules-hooks-and-mods)。`AskUserQuestion`、[您的组织设置为 `ask`](https://code.claude.com/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的连接器工具、标记为 [`requiresUserInteraction`](https://code.claude.com/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具以及 [从网络路径读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths) 即使您已允许它们也会被拒绝 | 您希望为无头 Agent 提供固定、明确的工具范围，并且更倾向于硬拒绝，而不是默默依赖 `canUseTool` 缺失 |236| `"dontAsk"` | 从不提示。由 [权限规则](https://code.claude.com/docs/zh-CN/settings-reference.md#permission-settings) 预批准的工具会运行，在 `default` 模式中不需要批准的调用（如您的工作目录内的文件读取）也会运行。所有其他会提示的调用都被拒绝，不过您安装的 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 仍可以批准[其中的部分调用](https://code.claude.com/docs/zh-CN/permissions.md#precedence-among-rules-hooks-and-mods)。少数调用（如 [从网络路径读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)）即使您已允许也会被拒绝。有关完整列表，请参阅 [Don't ask 模式](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md#don’t-ask-mode-dontask) | 无人批准调用的无头 Agent |

237| `"auto"` | 使用模型分类器来审查诸如 shell 命令和网络请求之类的操作，允许或阻止它审查的每一个。有关可用性和决策顺序，请参阅 [自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode) | 仍然想要工具使用安全防护的自主代理 |237| `"auto"` | 使用模型分类器来审查诸如 shell 命令和网络请求之类的操作，允许或阻止它审查的每一个。有关可用性和决策顺序，请参阅 [自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode) | 仍然想要工具使用安全防护的自主代理 |

238| `"bypassPermissions"` | 运行所有允许的工具而不询问，除了由显式 [`ask` 规则](https://code.claude.com/docs/zh-CN/settings-reference#permission-settings) 匹配的工具、连接器工具 [你的组织设置为 `ask`](https://code.claude.com/docs/zh-CN/mcp#organization-controls-on-connector-tools) 和需要用户交互的工具。[跨会话消息安全防护](https://code.claude.com/docs/zh-CN/permission-modes.md#skip-all-checks-with-bypasspermissions-mode) 仍然适用。有关优先级顺序，请参阅 [权限如何被评估](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md#how-permissions-are-evaluated)。在 TypeScript SDK 中，还需要在 `options` 中设置 `allowDangerouslySkipPermissions: true`。无法在 Unix 上以 root 身份运行。仅在隔离环境中使用，其中代理的操作无法影响你关心的系统 | CI、容器或其他隔离环境 |238| `"bypassPermissions"` | 运行工具调用而不请求批准，包括对您未在 `allowedTools` 中列出的工具的调用。少数调用仍会进入您的 `canUseTool` 回调，这些调用列在 [Bypass permissions 模式](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md#bypass-permissions-mode-bypasspermissions) 下。在 TypeScript SDK 中，还需要在 `options` 中设置 `allowDangerouslySkipPermissions: true`。无法在 Unix 上以 root 身份运行。仅在隔离环境中使用，其中 Agent 的操作无法影响您关心的系统 | CI、容器或其他隔离环境 |

239 239

240对于交互式应用程序，使用 `"default"` 和工具批准回调来显示批准提示。对于开发机器上的自主代理，`"acceptEdits"` 自动批准文件编辑和常见文件系统命令（`mkdir`、`touch`、`mv`、`cp` 等），同时仍然在允许规则后面限制其他 `Bash` 命令。为 CI、容器或其他隔离环境保留 `"bypassPermissions"`。有关完整详情，请参阅 [权限](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md)。240对于交互式应用程序，使用 `"default"` 和工具批准回调来显示批准提示。对于开发机器上的自主代理，`"acceptEdits"` 自动批准文件编辑和常见文件系统命令（`mkdir`、`touch`、`mv`、`cp` 等），同时仍然在允许规则后面限制其他 `Bash` 命令。为 CI、容器或其他隔离环境保留 `"bypassPermissions"`。有关完整详情，请参阅 [权限](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md)。

241 241

agent-sdk/custom-tools.md +29 −1

Details

16| 将参数设为可选 | 在 schema 中将其声明为可选，并在处理程序中应用默认值。请参阅[将参数设为可选](#make-a-parameter-optional)。 |16| 将参数设为可选 | 在 schema 中将其声明为可选，并在处理程序中应用默认值。请参阅[将参数设为可选](#make-a-parameter-optional)。 |

17| 向 Claude 注册工具 | 在 `create_sdk_mcp_server` / `createSdkMcpServer` 中包装并传递给 `query()` 中的 `mcpServers`。请参阅[调用自定义工具](#call-a-custom-tool)。 |17| 向 Claude 注册工具 | 在 `create_sdk_mcp_server` / `createSdkMcpServer` 中包装并传递给 `query()` 中的 `mcpServers`。请参阅[调用自定义工具](#call-a-custom-tool)。 |

18| 预先批准工具 | 添加到您的允许工具列表。请参阅[配置允许的工具](#configure-allowed-tools)。 |18| 预先批准工具 | 添加到您的允许工具列表。请参阅[配置允许的工具](#configure-allowed-tools)。 |

19| 要求调用某个工具前需经批准，或阻止该工具 | 在 TypeScript SDK 中，向 `createSdkMcpServer()` 返回的配置对象添加针对该工具的 `permission_policy`。请参阅[要求特定工具需经批准](#require-approval-for-specific-tools)。 |

19| 从 Claude 的上下文中删除内置工具 | 传递仅列出您想要的内置工具的 `tools` 数组。请参阅[配置允许的工具](#configure-allowed-tools)。 |20| 从 Claude 的上下文中删除内置工具 | 传递仅列出您想要的内置工具的 `tools` 数组。请参阅[配置允许的工具](#configure-allowed-tools)。 |

20| 让 Claude 并行调用工具 | 在没有副作用的工具上设置 `readOnlyHint: true`。请参阅[添加工具注释](#add-tool-annotations)。 |21| 让 Claude 并行调用工具 | 在没有副作用的工具上设置 `readOnlyHint: true`。请参阅[添加工具注释](#add-tool-annotations)。 |

21| 控制 Claude 读取的错误消息 | 返回 `isError: true` 来组合消息，而不是显示原始异常。请参阅[处理错误](#handle-errors)。 |22| 控制 Claude 读取的错误消息 | 返回 `isError: true` 来组合消息，而不是显示原始异常。请参阅[处理错误](#handle-errors)。 |

327| 字段 | 默认值 | 含义 |328| 字段 | 默认值 | 含义 |

328| :- | :- | :- |329| :- | :- | :- |

333 334

383 384

384要完全移除内置工具，请从`tools`中省略它或在`disallowedTools`中列出其裸名称（Python：`disallowed_tools`）；两者都将工具保留在上下文之外，以便Claude永远不会尝试它。作用域`disallowedTools`规则阻止匹配的调用但将工具保留为可见，因此Claude可能会浪费一个回合尝试它。有关完整的评估顺序，请参阅[配置权限](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md)。385要完全移除内置工具，请从`tools`中省略它或在`disallowedTools`中列出其裸名称（Python：`disallowed_tools`）；两者都将工具保留在上下文之外，以便Claude永远不会尝试它。作用域`disallowedTools`规则阻止匹配的调用但将工具保留为可见，因此Claude可能会浪费一个回合尝试它。有关完整的评估顺序，请参阅[配置权限](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md)。

385 386

387### 要求特定工具需经批准

388

389将工具的`permission_policy`设置为`always_ask`后，`allowedTools`将不再批准该工具的调用，因此即使该工具已被列出，其调用也可以到达您的[`canUseTool`](https://code.claude.com/docs/zh-CN/agent-sdk/user-input)回调。如果改为设置`always_deny`，则[对该工具的调用会被拒绝](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md#how-permissions-are-evaluated)，但您加载的插件中的[mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md)[仍然可以批准它](https://code.claude.com/docs/zh-CN/permissions.md#precedence-among-rules-hooks-and-mods)。该字段仅适用于TypeScript，并且需要Agent SDK v0.3.301或更高版本。

390

391请将策略条目放在`createSdkMcpServer()`返回的配置对象的`tools`数组中，而不是放在传入该函数的`tools`选项中。以下示例展开了[天气工具示例](#weather-tool-example)中的`weatherServer`，并添加了一个`tools`数组，为`get_temperature`指定`always_ask`策略：

392

393```typescript TypeScript theme={null}

394options: {

395 mcpServers: {

396 weather: {

397 ...weatherServer,

398 tools: [{ name: "get_temperature", permission_policy: "always_ask" as const }]

399 }

400 },

401 allowedTools: ["mcp__weather__get_temperature"],

402 permissionMode: "default",

403 canUseTool: async (toolName, input) => {

404 console.log(`Approval requested for ${toolName}`);

405 return { behavior: "allow", updatedInput: input };

406 }

407}

408```

409

410要试用该策略，请将[调用自定义工具](#call-a-custom-tool)脚本中的`options`替换为本示例的`options`，然后在终端中运行该脚本。脚本会打印`Approval requested for mcp__weather__get_temperature`，随后输出Claude关于温度的回答。有关完整脚本，请参阅[TypeScript参考](https://code.claude.com/docs/zh-CN/agent-sdk/typescript.md#mcpsdkserverconfigwithinstance)。

411

412如果您使用`auto`或`plan`[权限模式](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md#permission-modes)，请在工具的[注解](#add-tool-annotations)中设置`destructiveHint: true`，以便对该工具的调用仍能到达您的回调。否则，[自动模式分类器](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)可能会在[TypeScript参考中列出的条件](https://code.claude.com/docs/zh-CN/agent-sdk/typescript.md#permission-modes-that-can-approve-an-always_ask-call)下批准某些`always_ask`调用，而被其批准的调用不会到达您的回调。请显式设置该提示，因为对于`always_ask`调用，未设置的`destructiveHint`会被视为`false`，而不是默认为`true`。

413

386## 处理错误414## 处理错误

387 415

388处理程序错误不会停止代理循环。SDK 的进程内 MCP 服务器捕获未捕获的异常并将其作为错误结果返回，因此您报告错误的方式决定了 Claude 读取的内容，而不是查询是否失败：416处理程序错误不会停止代理循环。SDK 的进程内 MCP 服务器捕获未捕获的异常并将其作为错误结果返回，因此您报告错误的方式决定了 Claude 读取的内容，而不是查询是否失败：

agent-sdk/permissions.md +47 −18

Details

10 10

11## 权限如何被评估11## 权限如何被评估

12 12

13> [!NOTE]

14>

15> 如果您加载的插件包含 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md)，请参阅 [mod 的决定在规则和 hook 之间的位置](https://code.claude.com/docs/zh-CN/permissions.md#precedence-among-rules-hooks-and-mods)。

13当 Claude 请求一个工具时，SDK 按以下顺序检查权限：17当 Claude 请求一个工具时，SDK 按以下顺序检查权限：

14 18

15**1. Hooks**19**1. Hooks**

20 24

21**2. 拒绝规则**25**2. 拒绝规则**

22 26

23检查 `deny` 规则（来自 `disallowed_tools` 和 [settings.json](https://code.claude.com/docs/zh-CN/settings-reference.md#permission-settings)）。如果拒绝规则匹配，工具被阻止，即使在 `bypassPermissions` 模式下也是如此。裸名称拒绝规则如 `Bash` 在此评估开始之前将工具从 Claude 的上下文中移除，因此只有作用域规则如 `Bash(rm *)` 在此步骤被检查。27如果来自 `disallowed_tools` 或 [settings.json](https://code.claude.com/docs/zh-CN/settings-reference.md#permission-settings) 的拒绝规则匹配，调用将被拒绝，且不会调用 [`canUseTool`](https://code.claude.com/docs/zh-CN/agent-sdk/user-input)，即使在 [`bypassPermissions`](#bypass-permissions-mode-bypasspermissions) 模式下、即使 hook 返回了 `allow` 也是如此。

29在 TypeScript SDK 中，如果您将某个 [自定义工具](https://code.claude.com/docs/zh-CN/agent-sdk/custom-tools.md#require-approval-for-specific-tools) 的 `permission_policy` 设置为 [`always_deny`](https://code.claude.com/docs/zh-CN/agent-sdk/typescript#mcpservertoolpolicy)，对该工具的调用会在此步骤被拒绝。

24 30

25**3. 询问规则**31**3. 询问规则**

26 32

30 36

31您的组织设置为 `ask` 的 [claude.ai connector](https://code.claude.com/docs/zh-CN/mcp.md#organization-controls-on-connector-tools) 工具也在此步骤离开流程。每个调用都传递到回调，即使在 `bypassPermissions` 模式下，即使当允许规则匹配时也是如此。回调接收原因 `Your organization requires approval for this tool`。在 `dontAsk` 模式下，调用被拒绝，因为该模式从不提示。37您的组织设置为 `ask` 的 [claude.ai connector](https://code.claude.com/docs/zh-CN/mcp.md#organization-controls-on-connector-tools) 工具也在此步骤离开流程。每个调用都传递到回调，即使在 `bypassPermissions` 模式下，即使当允许规则匹配时也是如此。回调接收原因 `Your organization requires approval for this tool`。在 `dontAsk` 模式下，调用被拒绝，因为该模式从不提示。

32 38

39在 TypeScript SDK 中，如果您将自定义工具的 `permission_policy` 设置为 [`always_ask`](https://code.claude.com/docs/zh-CN/agent-sdk/custom-tools#require-approval-for-specific-tools)，任何允许规则都不会批准其调用，即使是 `allowedTools` 条目也不行。在 `dontAsk` 模式下，Claude Code 会拒绝这些调用；在 `auto`、`plan` 或 `bypassPermissions` 模式下，它[可以在您的回调运行之前批准它们](https://code.claude.com/docs/zh-CN/agent-sdk/typescript.md#permission-modes-that-can-approve-an-always_ask-call)。

33**4. 权限模式**41**4. 权限模式**

34 42

35应用活跃的 [权限模式](#permission-modes)：43应用活跃的 [权限模式](#permission-modes)：

36 44

37* 在 `bypassPermissions` 模式下，Claude Code 批准到达此步骤的所有内容，除了被识别出的 [关键路径删除](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)，这些会传递下去。45* 在 `bypassPermissions` 模式下，Claude Code 批准到达此步骤的所有内容，除了被识别出的 [关键路径删除](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths) 以及被标记为 [`Dangerous rm operation not ruled out`](https://code.claude.com/docs/zh-CN/permission-modes#dangerous-rm-operation-not-ruled-out) 的 Bash 命令，这些会传递下去。

38* 在 `acceptEdits` 模式下，Claude Code 批准 [接受编辑模式](#accept-edits-mode-acceptedits) 下列出的文件操作。46* 在 `acceptEdits` 模式下，Claude Code 批准 [接受编辑模式](#accept-edits-mode-acceptedits) 下列出的文件操作。

~~39* 在 `plan` 模式下，Claude Code 将文件编辑和 shell 写入工具发送到您的 `canUseTool` 回调，无论允许规则如何，因此在规划时写入操作无法自动批准。~~47* 在 `plan` 模式下，无论允许规则如何，Claude Code 都会将文件编辑工具发送到您的 `canUseTool` 回调。

40* 在其他模式下，请求传递下去。48* 在其他模式下，请求传递下去。

41 49

42**5. 允许规则**50**5. 允许规则**

43 51

44检查 `allow` 规则（来自 `allowed_tools` 和 settings.json）。如果规则匹配，工具被批准。工具自己批准的调用也在此步骤被解决，无需规则：例如在您的工作目录内的文件读取或 [只读 Bash 命令](https://code.claude.com/docs/zh-CN/permissions.md#read-only-commands)。52检查 `allow` 规则（来自 `allowed_tools` 和 settings.json）。如果规则匹配，工具被批准。工具自己批准的调用也在此步骤被解决，无需规则：例如在您的工作目录内的文件读取或 [只读 Bash 命令](https://code.claude.com/docs/zh-CN/permissions.md#read-only-commands)。

45 53

46被识别出的 [关键路径删除](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths) 不会被允许规则批准。它们是否随后到达您的回调取决于权限模式：例如在 `auto` 模式的 Agent SDK 会话中，Claude Code 默认拒绝它们而不调用它。[关键路径模式表](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-path-removals-in-each-permission-mode) 列出了每种模式对它们的处理方式。54被识别出的 [关键路径删除](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths) 不会被允许规则批准，被标记为 `Dangerous rm operation not ruled out` 的命令也不会被 `Bash` 或 `Bash(*)` 规则批准。它们是否随后到达您的回调取决于权限模式：例如在 `auto` 模式的 Agent SDK 会话中，Claude Code 默认拒绝它们而不调用它。[关键路径模式表](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-path-removals-in-each-permission-mode) 列出了每种模式对它们的处理方式。

47 55

48允许规则不会批准从 [网络路径](https://code.claude.com/docs/zh-CN/permissions.md#network-paths) 进行的读取。56允许规则不会批准从 [网络路径](https://code.claude.com/docs/zh-CN/permissions.md#network-paths) 进行的读取。

49 57

57 65

58如果您在 TypeScript SDK 期望评估顺序在咨询回调之前自动批准调用的配置中传递 `canUseTool` 回调，SDK 在构造查询时会发出一次 Node.js 进程警告。警告的代码是 `CLAUDE_SDK_CAN_USE_TOOL_SHADOWED`。两个配置会触发它：66如果您在 TypeScript SDK 期望评估顺序在咨询回调之前自动批准调用的配置中传递 `canUseTool` 回调，SDK 在构造查询时会发出一次 Node.js 进程警告。警告的代码是 `CLAUDE_SDK_CAN_USE_TOOL_SHADOWED`。两个配置会触发它：

59 67

60* `permissionMode: 'bypassPermissions'`，它自动批准到达权限模式步骤的每个调用，除了 [任何模式都不自动批准的操作](https://code.claude.com/docs/zh-CN/permission-modes.md#actions-no-mode-auto-approves)68* `permissionMode: 'bypassPermissions'`：警告文本以 `canUseTool will not be invoked: permissionMode 'bypassPermissions'` 开头。工具调用在咨询 `canUseTool` 之前就已被批准，因此您的回调只会针对少数调用运行，例如 [绕过权限模式](#bypass-permissions-mode-bypasspermissions) 下列出的调用。若也要检查已批准的调用，请将回调中的检查放入 [`PreToolUse` hook](https://code.claude.com/docs/zh-CN/agent-sdk/hooks)

61* 每个裸 `allowedTools` 条目，如 `"Read"`，它在回调被咨询之前自动批准整个工具，除了 [任何模式都不自动批准的操作](https://code.claude.com/docs/zh-CN/permission-modes.md#actions-no-mode-auto-approves) 和 [从网络路径进行的读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)69* 仅为工具名称的 `allowedTools` 条目，例如 `"Read"`：警告会在 `canUseTool will not be invoked for:` 之后列出每个此类条目。对所列工具的调用在咨询 `canUseTool` 之前就已被批准，[允许规则从不批准的调用](#calls-an-allow-rule-never-approves) 除外。若要让您的回调针对所列工具中需要批准的调用运行，请从 `allowedTools` 中删除该工具的条目

62 70

63带有说明符的条目，如 `Bash(ls *)` 和 `acceptEdits` 模式不会触发它，来自设置文件的允许规则对检查不可见。71带有说明符的条目，如 `Bash(ls *)` 和 `acceptEdits` 模式不会触发它，来自设置文件的允许规则对检查不可见。

64 72

65使用 `process.on('warning', ...)` 监听并匹配代码以记录或抑制它。要对所有工具调用进行门控，无论模式和规则如何，请改用 [`PreToolUse` hook](https://code.claude.com/docs/zh-CN/agent-sdk/hooks)。73该警告不会阻止任何调用，也不会更改任何选项。如果您的回调已经能收到您想检查的每个调用，请保持配置不变。要记录该警告，请使用 `process.on('warning', ...)` 监听并匹配 `CLAUDE_SDK_CAN_USE_TOOL_SHADOWED` 代码。

66 74

67此页面重点关注 **允许和拒绝规则** 和 **权限模式**。对于其他步骤：75此页面重点关注 **允许和拒绝规则** 和 **权限模式**。对于其他步骤：

68 76

90>98>

91> **自动批准的工具永远不会到达 `canUseTool`。** 在任何早期步骤中被批准的工具调用，通过 `acceptEdits` 或 `bypassPermissions`，或通过允许规则，会跳过你的 `canUseTool` 回调，因此你在那里放置的权限检查会被该工具无声地绕过。99> **自动批准的工具永远不会到达 `canUseTool`。** 在任何早期步骤中被批准的工具调用，通过 `acceptEdits` 或 `bypassPermissions`，或通过允许规则，会跳过你的 `canUseTool` 回调，因此你在那里放置的权限检查会被该工具无声地绕过。

92>100>

93> 允许规则永远不会自动批准 `AskUserQuestion`、标记为 [`_meta["anthropic/requiresUserInteraction"]`](https://code.claude.com/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具、[您的组织设置为 `ask`](https://code.claude.com/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的连接器工具，或被识别出的 `rm` 和 `rmdir` [关键路径移除](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)。在 `dontAsk` 模式中，Claude Code 拒绝这些调用而不调用回调。在其他模式中，前三个会到达回调。[关键路径模式表](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-path-removals-in-each-permission-mode)列出了每种模式如何处理关键路径移除。识别这些移除操作的检查[可能会遗漏某些命令](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)。101> 如果对 `allowed_tools` 中某个工具的调用仍然到达您的 `canUseTool` 回调，或在 `dontAsk` 模式中被拒绝，请检查它们是否属于[从网络路径读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)或以下调用之一。任何允许规则都不会批准这些调用。在从不提示的 `dontAsk` 模式中，Claude Code 会拒绝它们而不调用 `canUseTool`；在其他权限模式中，请按照各项说明处理它们：

102>

103> * `AskUserQuestion`、标记为 [`_meta["anthropic/requiresUserInteraction"]`](https://code.claude.com/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，以及[您的组织设置为 `ask`](https://code.claude.com/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的连接器工具：在回调中应答它们。[处理澄清问题](https://code.claude.com/docs/zh-CN/agent-sdk/user-input.md#handle-clarifying-questions)展示了如何应答 `AskUserQuestion`，而连接器调用到达时附带的原因为 `Your organization requires approval for this tool`

104>

105> * 您的应用程序标记为 [`always_ask`](https://code.claude.com/docs/zh-CN/agent-sdk/custom-tools#require-approval-for-specific-tools) 的自定义工具：在回调中对该调用作出决定。要阻止这些调用到达，请[在会话中途更改策略](https://code.claude.com/docs/zh-CN/agent-sdk/typescript.md#mcpsdkserverconfigwithinstance)。在 `auto`、`plan` 和 `bypassPermissions` 模式中，该调用也可能在回调之前被批准，具体情况列于[可以批准 `always_ask` 调用的权限模式](https://code.claude.com/docs/zh-CN/agent-sdk/typescript#permission-modes-that-can-approve-an-always_ask-call)

94>106>

95> 覆盖范围取决于条目的形式：像 `Read` 或 `mcp__github__get_issue` 这样的裸名称会自动批准对该工具的每个调用，上述例外和[从网络路径读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)除外，而像 `Bash(npm test *)` 这样的限定规则仅自动批准匹配的调用，其他需要批准的 `Bash` 调用仍然会进入回调。对于必须在每个工具调用上运行的检查，使用 [`PreToolUse` hook](https://code.claude.com/docs/zh-CN/agent-sdk/hooks)：hook 在每个其他步骤之前运行，hook 拒绝即使在 `bypassPermissions` 模式中也适用。107> * 被识别出的 `rm` 和 `rmdir` [关键路径移除](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)：在 `default`、`acceptEdits` 和 `bypassPermissions` 模式中，在回调中允许或拒绝该移除操作，此时 [`decisionReason`](https://code.claude.com/docs/zh-CN/agent-sdk/typescript#canusetool) 以 `Dangerous rm` 开头。对于 `auto` 和 `plan` 模式，请参阅[各权限模式中的关键路径移除](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-path-removals-in-each-permission-mode)。识别这些移除操作的检查[可能会遗漏某些命令](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)

108>

109> * **裸名称**：像 `Read` 或 `mcp__github__get_issue` 这样的条目会自动批准对该工具的每个调用，[任何模式都不自动批准的操作](https://code.claude.com/docs/zh-CN/permission-modes.md#actions-no-mode-auto-approves)和[从网络路径读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)除外。

110>

111> * **限定规则**：像 `Bash(npm test *)` 这样的条目仅自动批准匹配的调用，其他需要批准的 `Bash` 调用仍然会进入回调。

112>

113> 对于必须在每个工具调用上运行的检查，请使用 [`PreToolUse` hook](https://code.claude.com/docs/zh-CN/agent-sdk/hooks)：hook 在每个其他步骤之前运行，hook 拒绝即使在 `bypassPermissions` 模式中也适用。

96 114

97对于锁定的代理，将 `allowedTools` 与 `permissionMode: "dontAsk"` 配对：115对于锁定的代理，将 `allowedTools` 与 `permissionMode: "dontAsk"` 配对：

98 116

103};121};

104```122```

105 123

106列出的工具被批准，[任何模式都不自动批准的操作](https://code.claude.com/docs/zh-CN/permission-modes.md#actions-no-mode-auto-approves)和[从网络路径读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)除外。每个其他会提示的调用则会被拒绝，不过您安装的 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 仍然可以批准[其中的部分调用](https://code.claude.com/docs/zh-CN/permissions.md#precedence-among-rules-hooks-and-mods)。124列出的 `Read`、`Glob` 和 `Grep` 调用被批准，[任何模式都不自动批准的操作](https://code.claude.com/docs/zh-CN/permission-modes.md#actions-no-mode-auto-approves)和[从网络路径读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)除外。每个其他会提示的调用则会被拒绝，不过您安装的 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 仍然可以批准[其中的部分调用](https://code.claude.com/docs/zh-CN/permissions.md#precedence-among-rules-hooks-and-mods)。

107 125

108在 `default` 模式中不需要批准的调用会运行，无论您是否列出它们。其中包括[只读 Bash 命令](https://code.claude.com/docs/zh-CN/permissions.md#read-only-commands)、不在运行前询问的 `Agent` 等工具，以及工作目录内的文件读取。要将工具从请求中完全移除，请将其裸名称添加到 `disallowedTools`。126在 `default` 模式中不需要批准的调用会运行，无论您是否列出它们。其中包括[只读 Bash 命令](https://code.claude.com/docs/zh-CN/permissions.md#read-only-commands)、不在运行前询问的 `Agent` 等工具，以及工作目录内的文件读取。要对 Claude 完全隐藏某个内置工具而不是拒绝其调用，请将其裸名称添加到 `disallowedTools`。

109 127

110> [!WARNING]128> [!WARNING]

111>129>

129| `dontAsk` | 拒绝而不是提示 | 任何原本会提示的调用都会被拒绝，且不调用 `canUseTool`，不过您安装的 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 仍可批准[其中部分调用](https://code.claude.com/docs/zh-CN/permissions.md#precedence-among-rules-hooks-and-mods)。由 `allowed_tools` 或 `settings.json` 允许规则批准的调用会运行，在 `default` 模式下无需批准的调用也会运行。某些调用，例如[从网络路径读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)，即使 `allowed_tools` 或允许规则与其匹配也会被拒绝。完整列表请参阅[不询问模式](#don’t-ask-mode-dontask) |147| `dontAsk` | 拒绝而不是提示 | 任何原本会提示的调用都会被拒绝，且不调用 `canUseTool`，不过您安装的 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 仍可批准[其中部分调用](https://code.claude.com/docs/zh-CN/permissions.md#precedence-among-rules-hooks-and-mods)。由 `allowed_tools` 或 `settings.json` 允许规则批准的调用会运行，在 `default` 模式下无需批准的调用也会运行。某些调用，例如[从网络路径读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)，即使 `allowed_tools` 或允许规则与其匹配也会被拒绝。完整列表请参阅[不询问模式](#don’t-ask-mode-dontask) |

131| `bypassPermissions` | 绕过权限检查 | 工具无需权限提示即可运行，但[任何模式都不会自动批准的操作](https://code.claude.com/docs/zh-CN/permission-modes.md#actions-no-mode-auto-approves)除外。请谨慎使用 |149| `bypassPermissions` | 绕过权限检查 | 工具无需权限提示即可运行，但[任何模式都不会自动批准的操作](https://code.claude.com/docs/zh-CN/permission-modes.md#actions-no-mode-auto-approves)，以及在[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)之外您的应用程序[标记为 `always_ask`](https://code.claude.com/docs/zh-CN/agent-sdk/custom-tools#require-approval-for-specific-tools) 的自定义工具除外。请谨慎使用 |

133| `auto` | 由模型分类的批准 | 模型分类器会审查 shell 命令和网络请求等操作，对其审查的每个操作予以允许或阻止。有关可用性和决策顺序，请参阅[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode) |151| `auto` | 由模型分类的批准 | 模型分类器会审查 shell 命令和网络请求等操作，对其审查的每个操作予以允许或阻止。有关可用性和决策顺序，请参阅[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode) |

134 152

256* 处理该范围之外的路径274* 处理该范围之外的路径

257* 写入受保护的路径275* 写入受保护的路径

258* 使用 `rm` 或 `rmdir` 删除 Claude Code 识别为[关键路径](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)的路径276* 使用 `rm` 或 `rmdir` 删除 Claude Code 识别为[关键路径](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)的路径

277* 运行带有例如选项、glob 或 `timeout 5`、`LANG=C` 前缀的 [`touch`](https://code.claude.com/docs/zh-CN/permission-modes#auto-approve-file-edits-with-acceptedits-mode)

259 278

260**适用场景：** 您信任 Claude 的编辑并希望加快迭代速度，例如在原型开发期间或在隔离目录中工作时。279**适用场景：** 您信任 Claude 的编辑并希望加快迭代速度，例如在原型开发期间或在隔离目录中工作时。

261 280

263 282

264将任何权限提示转换为拒绝，且不调用 `canUseTool`，不过您安装的 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 仍可批准[其中部分调用](https://code.claude.com/docs/zh-CN/permissions.md#precedence-among-rules-hooks-and-mods)。由 `allowed_tools`、`settings.json` 允许规则或 hook 预先批准的工具会正常运行。在 `default` 模式下无需批准的调用也会运行，例如在工作目录内读取文件以及调用 `Agent`。283将任何权限提示转换为拒绝，且不调用 `canUseTool`，不过您安装的 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 仍可批准[其中部分调用](https://code.claude.com/docs/zh-CN/permissions.md#precedence-among-rules-hooks-and-mods)。由 `allowed_tools`、`settings.json` 允许规则或 hook 预先批准的工具会正常运行。在 `default` 模式下无需批准的调用也会运行，例如在工作目录内读取文件以及调用 `Agent`。

265 284

266[您的组织设置为 `ask`](https://code.claude.com/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的连接器工具、需要用户交互的工具、[从网络路径读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)以及被识别出的[关键路径删除](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)即使匹配允许规则也会被拒绝。`PreToolUse` hook 的允许结果同样无法放行被识别出的关键路径删除或从网络路径读取。识别这些删除操作的检查[可能会漏掉某些命令](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)。285以下调用即使匹配允许规则也会被拒绝：

286

287* [您的组织设置为 `ask`](https://code.claude.com/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的连接器工具

288* 需要用户交互的工具，例如 `AskUserQuestion`，以及其服务器设置了 [`_meta["anthropic/requiresUserInteraction"]`](https://code.claude.com/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具

289* 您的应用程序将其 `permission_policy` 设置为 [`always_ask`](https://code.claude.com/docs/zh-CN/agent-sdk/custom-tools#require-approval-for-specific-tools) 的自定义工具

290* [从网络路径读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)

291* 被识别出的[关键路径删除](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)

292

293如果您的 `PreToolUse` hook 对被识别出的关键路径删除、从网络路径读取或对标记为 `always_ask` 的工具的调用返回 `allow`，该调用仍会被拒绝。识别这些删除操作的检查[可能会漏掉某些命令](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)。

267 294

268**适用场景：** 您希望为无头 Agent 提供一组固定、明确的工具，并且更倾向于硬性拒绝，而不是默默依赖 `canUseTool` 的缺失。295**适用场景：** 您希望为无头 Agent 提供一组固定、明确的工具，并且更倾向于硬性拒绝，而不是默默依赖 `canUseTool` 的缺失。

269 296

270#### 绕过权限模式（`bypassPermissions`）297#### 绕过权限模式（`bypassPermissions`）

271 298

272无需提示即可自动批准工具使用，但下方警告中列出的情况除外。hook 仍会执行，并可在需要时阻止操作。在 Linux 和 macOS 上，如果不在[可识别的沙箱](https://code.claude.com/docs/zh-CN/permission-modes.md#skip-all-checks-with-bypasspermissions-mode)中，无论是以 root 身份还是在 `sudo` 下，Claude Code 都会拒绝以此模式启动，查询会在第一轮之前失败。299无需提示即可自动批准工具使用，但[任何模式都不会自动批准的操作](https://code.claude.com/docs/zh-CN/permission-modes.md#actions-no-mode-auto-approves)除外。hook 仍会执行，并可在需要时阻止操作。在 Linux 和 macOS 上，如果不在[可识别的沙箱](https://code.claude.com/docs/zh-CN/permission-modes.md#skip-all-checks-with-bypasspermissions-mode)中，无论是以 root 身份还是在 `sudo` 下，Claude Code 都会拒绝以此模式启动，查询会在第一轮之前失败。

273 300

274> [!WARNING]301> [!WARNING]

275>302>

278> `allowed_tools` 不会约束此模式。每个工具都会被批准，而不仅仅是您列出的工具。以下控制措施仍然适用：305> `allowed_tools` 不会约束此模式。每个工具都会被批准，而不仅仅是您列出的工具。以下控制措施仍然适用：

279>306>

280> * 拒绝规则、显式 `ask` 规则和 hook 会在模式检查之前进行评估，仍然可以阻止工具。307> * 拒绝规则、显式 `ask` 规则和 hook 会在模式检查之前进行评估，仍然可以阻止工具。

281> * [您的组织设置为 `ask`](https://code.claude.com/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的连接器工具、需要用户交互的工具以及被识别出的[关键路径删除](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)仍会交给您的 `canUseTool` 回调处理。识别这些删除操作的检查[可能会漏掉某些命令](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)。308> * [您的组织设置为 `ask`](https://code.claude.com/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的连接器工具、需要用户交互的工具以及被识别出的[关键路径删除](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)仍会交给您的 `canUseTool` 回调处理。识别这些删除操作的检查[可能会漏掉某些命令](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)。在[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)之外，对您的应用程序[标记为 `always_ask`](https://code.claude.com/docs/zh-CN/agent-sdk/custom-tools#require-approval-for-specific-tools) 的自定义工具的调用也会交给该回调处理。

282> * [跨会话消息传递保护措施](https://code.claude.com/docs/zh-CN/permission-modes.md#skip-all-checks-with-bypasspermissions-mode)仍然适用。309> * [跨会话消息传递保护措施](https://code.claude.com/docs/zh-CN/permission-modes.md#skip-all-checks-with-bypasspermissions-mode)仍然适用。

283 310

284#### 计划模式（`plan`）311#### 计划模式（`plan`）

285 312

286Claude 会探索代码库并制定计划，而不编辑您的源文件。只读工具的运行方式与 `default` 权限模式相同。313Claude 会探索代码库并制定计划，而不编辑您的源文件。在计划模式下，文件编辑永远不会被自动批准，即使某条允许规则与之匹配或 `PreToolUse` hook 返回 `allow` 也是如此。它们会改为通过您的 `canUseTool` 回调进行提示。

287 314

288在计划模式下，文件编辑永远不会被自动批准，即使某条允许规则与之匹配或 `PreToolUse` hook 返回 `allow` 也是如此。它们会改为通过您的 `canUseTool` 回调进行提示。在 Claude Code v2.1.212 或更高版本中，修改文件的 shell 命令（例如 `touch` 和 `rm`）也会以同样的方式交给您的 `canUseTool` 回调。315当会话可以使用自动模式时，Claude 在规划期间运行的命令默认不会交给您的回调，因为[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)使用的分类器模型会[改为审查这些命令](https://code.claude.com/docs/zh-CN/permission-modes.md#analyze-before-you-edit-with-plan-mode)。启用该审查后，分类器还可以批准原本会交给您回调的只读调用，例如没有允许规则的 `WebFetch` 调用。

289 316

290在 TypeScript SDK 中，如果您在设置 `permissionMode: 'plan'` 的同时设置了 `allowDangerouslySkipPermissions: true`，文件编辑和修改文件的 shell 命令仍会交给您的 `canUseTool` 回调。该选项让您之后可以通过 `setPermissionMode()` 切换到 `bypassPermissions`。317> [!NOTE]

318>

319> 在 TypeScript SDK 中，如果您在设置 `permissionMode: 'plan'` 的同时设置了 `allowDangerouslySkipPermissions: true`，文件编辑仍会交给您的 `canUseTool` 回调。要在之后通过 `setPermissionMode()` 将以计划模式启动的会话切换到 `bypassPermissions`，您需要从一开始就设置 `allowDangerouslySkipPermissions`。

291 320

292Claude 可能会在最终确定计划之前使用 `AskUserQuestion` 来澄清需求。有关如何处理这些提示，请参阅[处理批准和用户输入](https://code.claude.com/docs/zh-CN/agent-sdk/user-input.md#handle-clarifying-questions)。321Claude 可能会在最终确定计划之前使用 `AskUserQuestion` 来澄清需求。有关如何处理这些提示，请参阅[处理批准和用户输入](https://code.claude.com/docs/zh-CN/agent-sdk/user-input.md#handle-clarifying-questions)。

293 322

agent-sdk/plugins.md +16 −0

Details

70>70>

71> 路径应指向 plugin 的根目录：`skills/`、`agents/`、`hooks/`、`commands/` 或 `.claude-plugin/` 的父目录。71> 路径应指向 plugin 的根目录：`skills/`、`agents/`、`hooks/`、`commands/` 或 `.claude-plugin/` 的父目录。

72 72

73### 向运行中的会话添加插件

75在 TypeScript SDK 中，对 `query()` 返回的 `Query` 对象调用 [`reloadPlugins()`](https://code.claude.com/docs/zh-CN/agent-sdk/typescript#load-more-plugin-folders-with-addplugins)，并在该调用的 `addPlugins` 选项中列出插件目录。每个 `addPlugins` 条目都是一个带有绝对 `path` 的 `{ type: "local", path }` 对象。需要 TypeScript Agent SDK v0.3.301 或更高版本。

77在此示例中，`q` 是 `query()` 返回的 `Query` 对象。该示例向运行中的会话添加一个插件目录，并在 `reloadPlugins()` 返回后打印会话中每个插件的路径：

79```typescript theme={null}

80const result = await q.reloadPlugins({

81 addPlugins: [{ type: "local", path: "/home/user/plugins/another-plugin" }]

82});

84console.log(result.plugins.map((plugin) => plugin.path));

85```

87如果插件已加载，打印的列表中会包含 `/home/user/plugins/another-plugin`。如果列表中缺少该路径，或者 `reloadPlugins()` 被拒绝（reject），请参阅[当 `reloadPlugins()` 未加载 `addPlugins` 文件夹时](https://code.claude.com/docs/zh-CN/agent-sdk/typescript#when-reloadplugins-doesnt-load-the-addplugins-folders)了解原因。

73## 验证 plugin 安装89## 验证 plugin 安装

74 90

75当 plugins 成功加载时，它们会出现在系统初始化消息中。你可以验证你的 plugins 是否可用：91当 plugins 成功加载时，它们会出现在系统初始化消息中。你可以验证你的 plugins 是否可用：

agent-sdk/typescript.md +169 −6

Details

200| :- | :- | :- | :- |200| :- | :- | :- | :- |

206 206

630 ): Promise<SDKControlReadFileResponse | null>;630 ): Promise<SDKControlReadFileResponse | null>;

631 reloadPlugins(options?: {631 reloadPlugins(options?: {

632 holdOnCacheImpact?: boolean;632 holdOnCacheImpact?: boolean;

633 addPlugins?: SdkPluginConfig[];

633 }): Promise<SDKControlReloadPluginsResponse>;634 }): Promise<SDKControlReloadPluginsResponse>;

634 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;635 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;

635 reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;636 reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;

670| `getContextUsage(opts?)` | 返回一个 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)，按类别、skill 和工具细分会话的上下文窗口使用情况。使用默认的 `detail` 时，它包含 `/context` 在交互式会话中显示的数据，这些数据通过不会出现在消息流中的 token 计数 API 请求计算得出；请参阅[这些请求的处理方式](#sdkcontrolgetcontextusageresponse)。[`detail` 选项](#sdkcontrolgetcontextusageresponse)需要 Agent SDK v0.3.257 或更高版本 |671| `getContextUsage(opts?)` | 返回一个 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)，按类别、skill 和工具细分会话的上下文窗口使用情况。使用默认的 `detail` 时，它包含 `/context` 在交互式会话中显示的数据，这些数据通过不会出现在消息流中的 token 计数 API 请求计算得出；请参阅[这些请求的处理方式](#sdkcontrolgetcontextusageresponse)。[`detail` 选项](#sdkcontrolgetcontextusageresponse)需要 Agent SDK v0.3.257 或更高版本 |

671| `readFile(path, options?)` | 从会话的文件系统中读取文件。Claude Code 会相对于 `cwd` 解析路径；[`readFile()` 可以读取的内容](#what-readfile-can-read)列出了它可提供的文件。传递 `{ maxBytes }` 可更改读取上限（默认 1 MB，最大 10 MB），对于图像等二进制文件传递 `{ encoding: 'base64' }`。以 [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) 完成；在权限被拒绝、文件不存在或传输错误时以 `null` 完成。需要 TypeScript SDK v0.2.121 或更高版本 |672| `readFile(path, options?)` | 从会话的文件系统中读取文件。Claude Code 会相对于 `cwd` 解析路径；[`readFile()` 可以读取的内容](#what-readfile-can-read)列出了它可提供的文件。传递 `{ maxBytes }` 可更改读取上限（默认 1 MB，最大 10 MB），对于图像等二进制文件传递 `{ encoding: 'base64' }`。以 [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) 完成；在权限被拒绝、文件不存在或传输错误时以 `null` 完成。需要 TypeScript SDK v0.2.121 或更高版本 |

672| `reloadPlugins(options?)` | 从磁盘重新加载插件，使您在会话中途安装或编辑的插件作用于正在运行的会话。以 [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) 完成，其中列出会话的命令、子代理、插件和 MCP 服务器状态。需要 Agent SDK v0.2.85 或更高版本。[`holdOnCacheImpact` 选项](#sdkcontrolreloadpluginsresponse)需要 Agent SDK v0.3.268 或更高版本 |673| `reloadPlugins(options?)` | 从磁盘重新加载插件，使您在会话中途安装或编辑的插件能够作用于正在运行的会话。以 [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) 解析，其中列出会话的命令、子代理、插件和 MCP 服务器状态。需要 Agent SDK v0.2.85 或更高版本。[`holdOnCacheImpact` 选项](#sdkcontrolreloadpluginsresponse)需要 Agent SDK v0.3.268 或更高版本。[`addPlugins` 选项](#load-more-plugin-folders-with-addplugins)需要 Agent SDK v0.3.301 或更高版本 |

673| `reloadSkills()` | 从磁盘重新加载 skill，使您在会话中途添加或编辑的 skill 可供正在运行的会话使用。以 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) 完成，其中列出重新加载后可用的 skill。需要 Agent SDK v0.3.163 或更高版本 |674| `reloadSkills()` | 从磁盘重新加载 skill，使您在会话中途添加或编辑的 skill 可供正在运行的会话使用。以 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) 完成，其中列出重新加载后可用的 skill。需要 Agent SDK v0.3.163 或更高版本 |

674| `reloadOutputStyles()` | 从磁盘重新读取[输出样式](https://code.claude.com/docs/zh-CN/output-styles.md)，使您在会话中途添加或编辑的样式文件可供正在运行的会话使用。以 [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) 完成，其中列出重新加载后可用的样式名称。需要 Agent SDK v0.3.261 或更高版本 |675| `reloadOutputStyles()` | 从磁盘重新读取[输出样式](https://code.claude.com/docs/zh-CN/output-styles.md)，使您在会话中途添加或编辑的样式文件可供正在运行的会话使用。以 [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) 完成，其中列出重新加载后可用的样式名称。需要 Agent SDK v0.3.261 或更高版本 |

675| `seedReadState(path, mtime)` | 将文件标记为已读取，使之后的 Edit 不会因 `File has not been read yet` 而失败。请参阅 [`seedReadState()`](#seedreadstate)。需要 TypeScript SDK v0.2.83 或更高版本 |676| `seedReadState(path, mtime)` | 将文件标记为已读取，使之后的 Edit 不会因 `File has not been read yet` 而失败。请参阅 [`seedReadState()`](#seedreadstate)。需要 TypeScript SDK v0.2.83 或更高版本 |

1135 1136

1136`cache_impact` 仅与 `held: true` 一同出现。`mcp_servers_added` 和 `mcp_servers_removed` 以限定的 `plugin:<plugin>:<server>` 名称列出重新加载将注册或移除的插件 MCP 服务器。这些名称由插件作者编写，因此在显示之前请先验证。`lsp_tool_change` 说明应用后是否会添加或移除 LSP 工具，如果两者都不会发生则为 `null`。`may-` 形式表示检查无法完全看到待处理的插件集合。1137`cache_impact` 仅与 `held: true` 一同出现。`mcp_servers_added` 和 `mcp_servers_removed` 以限定的 `plugin:<plugin>:<server>` 名称列出重新加载将注册或移除的插件 MCP 服务器。这些名称由插件作者编写，因此在显示之前请先验证。`lsp_tool_change` 说明应用后是否会添加或移除 LSP 工具，如果两者都不会发生则为 `null`。`may-` 形式表示检查无法完全看到待处理的插件集合。

1137 1138

1139#### 使用 `addPlugins` 加载更多插件文件夹

1140

1141要加载启动时未包含在 [`plugins`](#options) 选项中的插件文件夹，请将它们作为 `addPlugins` 传给 `reloadPlugins()`，这是一个由 [`SdkPluginConfig`](#sdkpluginconfig) 条目组成的列表，其中的 `path` 必须是绝对路径。Claude Code 会在一次处理中加载新文件夹并重新加载会话中已有的插件。每个新增插件的 MCP 服务器也会连接，除非您在该文件夹的条目上设置了 [`skipMcpDiscovery`](#sdkpluginconfig)。需要 Agent SDK v0.3.301 或更高版本以及 Claude Code v2.1.301 或更高版本。

1142

1143以下示例向正在运行的查询 `q` 添加一个文件夹，并在调用返回时打印会话已加载的每个插件的安装路径：

1144

1145```typescript theme={null}

1146const result = await q.reloadPlugins({

1147 addPlugins: [{ type: "local", path: "/opt/my-app/plugins/reports" }]

1148});

1149

1150console.log(result.plugins.map((plugin) => plugin.path));

1151```

1152

1153如果该文件夹已加载，打印的列表中会包含 `/opt/my-app/plugins/reports`，并且该插件的命令和子代理会出现在 `result.commands` 和 `result.agents` 中。

1154

1155新增的文件夹会一直作为会话的一部分。当您再次调用 `reloadPlugins()` 时，Claude Code 会将其与其他插件一起重新加载，您无需再次在 `addPlugins` 中传入它。

1156

1157##### `reloadPlugins()` 未加载 `addPlugins` 文件夹的情况

1158

1159如果 `reloadPlugins()` 被拒绝，`addPlugins` 中的文件夹都不会被添加，因此重试时请再次在 `addPlugins` 中传入它们。当拒绝由以下某个原因导致时，会话会保留其原有的插件：

1160

1161* **相对 `path` 或格式错误的条目**：错误消息为 `add_plugins must be a list of { type: "local", path } entries with absolute paths`。只要有一个错误条目，Claude Code 就会拒绝整个列表，因此请将每个条目都传为 `{ type: "local", path }`，并使用绝对 `path`

1162* **管理员在您的托管设置中启用了 [`disableSideloadFlags`](https://code.claude.com/docs/zh-CN/settings-reference#disablesideloadflags)**：消息为 `reload_plugins add_plugins is disabled by managed settings (disableSideloadFlags)`。要加载该文件夹，请联系该管理员移除此设置

1163* **无法重建[沙箱](https://code.claude.com/docs/zh-CN/sandboxing.md)**：启用[沙箱隔离](#sandboxsettings)时，Claude Code 会重建沙箱配置，使沙箱中的 shell 命令无法写入您添加的文件夹。消息为 `the sandbox could not be rebuilt to keep shell commands out of this folder`。请检查您的[沙箱设置](#sandboxsettings)是否仍构成有效配置

1164

1165如果您传入了 `holdOnCacheImpact`，且调用以 [`held: true`](#sdkcontrolreloadpluginsresponse) 解析，则 `addPlugins` 中的文件夹不会被添加。如需仍然添加，请使用相同的 `addPlugins` 列表、不带 `holdOnCacheImpact` 再次调用 `reloadPlugins()`。

1166

1167如果调用未以 `held: true` 解析，但某个文件夹仍未出现在 `result.plugins` 中，请先排查以下原因：

1168

1169* **文件夹不存在或其插件加载失败**：`result.error_count` 为 `1` 或更高。即便如此，该文件夹仍是会话的一部分。修复文件夹后，再次调用 `reloadPlugins()` 即可加载它，这次无需在 `addPlugins` 中列出它

1170* **Claude Code 可执行文件早于 v2.1.301**：早于 v2.1.301 的可执行文件会忽略 `addPlugins`，只重新加载会话中已有的插件。请检查 [init 消息](#sdksystemmessage)中的 `claude_code_version`，并运行 v2.1.301 或更高版本的可执行文件

1171

1138### `SDKControlReloadSkillsResponse`1172### `SDKControlReloadSkillsResponse`

1139 1173

1140[`reloadSkills()`](#query-object) 的返回类型。1174[`reloadSkills()`](#query-object) 的返回类型。

1430 1464

1431#### `McpSdkServerConfigWithInstance`1465#### `McpSdkServerConfigWithInstance`

1432 1466

1467进程内 MCP 服务器的配置，此类服务器由 [`createSdkMcpServer()`](#createsdkmcpserver) 创建，并在您的应用程序进程内运行。它是 `createSdkMcpServer()` 返回的对象，外加一个由您自行添加的、由 [`McpServerToolPolicy`](#mcpservertoolpolicy) 条目组成的可选 `tools` 列表。要对该服务器某个工具的调用要求批准或予以拒绝，请添加一个指定该工具的条目。

1468

1433```typescript theme={null}1469```typescript theme={null}

1434type McpSdkServerConfigWithInstance = {1470type McpSdkServerConfigWithInstance = {

1435 type: "sdk";1471 type: "sdk";

1436 name: string;1472 name: string;

1437 timeout?: number;1473 timeout?: number;

1474 tools?: McpServerToolPolicy[];

1438 instance: McpServer;1475 instance: McpServer;

1439};1476};

1440```1477```

1441 1478

1479要设置策略，请将 `createSdkMcpServer()` 返回的对象展开到 `mcpServers` 中的一个新对象里，并将 `tools` 列表添加到该新对象上。`createSdkMcpServer()` 自身的 `tools` 选项是另一个列表，用于保存工具定义，不接受策略条目。策略列表需要 Agent SDK v0.3.301 或更高版本，[`McpServerToolPolicy`](#mcpservertoolpolicy) 说明了每个 `permission_policy` 值的作用。

1480

1481以下示例使用 `allowedTools` 通配符预先批准 `records` 服务器上的所有工具，然后将 `delete_record` 标记为 `always_ask`，使对它的调用仍然转到 `canUseTool`。借助 `destructiveHint: true` 注解，即使会话在 `auto` 模式下运行，该调用仍会到达回调；否则自动模式[分类器](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)可能会批准它。

1482

1483```typescript theme={null}

1484import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

1485import { z } from "zod";

1486

1487const deleteRecord = tool(

1488 "delete_record",

1489 "Delete a customer record by ID",

1490 { id: z.string() },

1491 async ({ id }) => ({ content: [{ type: "text", text: `Deleted record ${id}` }] }),

1492 { annotations: { destructiveHint: true } }

1493);

1494

1495const records = createSdkMcpServer({ name: "records", tools: [deleteRecord] });

1496

1497for await (const message of query({

1498 prompt: "Delete customer record 42",

1499 options: {

1500 mcpServers: {

1501 // Spread the returned config and add the policy list beside it

1502 records: {

1503 ...records,

1504 tools: [{ name: "delete_record", permission_policy: "always_ask" as const }]

1505 }

1506 },

1507 allowedTools: ["mcp__records__*"],

1508 canUseTool: async (toolName, input) => {

1509 console.log(`Approval requested for ${toolName}`);

1510 return { behavior: "allow", updatedInput: input };

1511 }

1512 }

1513})) {

1514 if (message.type === "result" && message.subtype === "success") {

1515 console.log(message.result);

1516 }

1517}

1518```

1519

1520当 Claude 调用该工具时，脚本会在 `delete_record` 工具运行之前打印 `Approval requested for mcp__records__delete_record`，尽管 `allowedTools` 条目原本会批准该调用。

1521

1522要在会话运行期间更改或解除某个工具的策略，请将带有新 `tools` 值的服务器配置传给 [`setMcpServers()`](#mcpsetserversresult)。您传入的 `tools` 值从 Claude 下一次调用该服务器的工具时开始生效：

1523

1524* **包含条目的列表**：这些条目替换当前策略

1525* **空列表**：清除该服务器上的所有策略

1526* **没有 `tools` 键**：保留当前策略

1527

1528请在该调用中包含您的其他进程内服务器以及先前 `setMcpServers()` 调用添加的任何服务器，否则该调用会断开它们的连接。

1529

1530#### `McpServerToolPolicy`

1531

1532[`McpSdkServerConfigWithInstance`](#mcpsdkserverconfigwithinstance) 的 `tools` 列表中的一个条目，用于指定服务器的某个工具并设置对该工具调用的权限策略。该列表需要 Agent SDK v0.3.301 或更高版本以及 Claude Code v2.1.301 或更高版本。较旧的 Claude Code 可执行文件（例如您通过 `pathToClaudeCodeExecutable` 指定的可执行文件）会忽略该列表。此时 `always_ask` 和 `always_deny` 不会被强制执行，每个调用都会经过[权限流程](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md#how-permissions-are-evaluated)。

1533

1534```typescript theme={null}

1535type McpServerToolPolicy = {

1536 name: string;

1537 permission_policy?: "always_allow" | "always_ask" | "always_deny";

1538 org_max_permission?: "allow" | "ask" | "blocked";

1539};

1540```

1541

1542| 字段 | 类型 | 描述 |

1543| :- | :- | :- |

1544| `name` | `string` | 传给 [`tool()`](#tool) 的工具裸名称，不带 `mcp__<server>__` 前缀 |

1547

1548##### `permission_policy` 值

1549

1550选择 `always_ask` 以亲自批准每个调用，或选择 `always_deny` 以直接阻止该工具：

1551

1552* **`always_ask`**：对该工具的每个调用都[需要批准](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md#how-permissions-are-evaluated)，即使有 `allowedTools` 条目或 allow 规则覆盖它。该调用会转到您的 `canUseTool` 回调或 [`permissionPromptToolName`](#options) 工具，除非它已先被处理。您加载的插件中的 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) [可以先批准它](https://code.claude.com/docs/zh-CN/permissions.md#precedence-among-rules-hooks-and-mods)。否则，在 `dontAsk` 模式下它会被拒绝，而在 [`auto`、`plan` 和 `bypassPermissions` 模式](#permission-modes-that-can-approve-an-always_ask-call)下，它可能在到达您的回调之前就被批准

1553* **`always_deny`**：在所有权限模式下（包括 `bypassPermissions`），对该工具的调用都[会被拒绝](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md#how-permissions-are-evaluated)，但您加载的插件中的 mod [仍然可以批准它](https://code.claude.com/docs/zh-CN/permissions.md#precedence-among-rules-hooks-and-mods)

1554

1555如果您既未传入 `canUseTool` 也未传入 `permissionPromptToolName`，或将 [`permissionPrompts`](#options) 设为 `'none'`，则未被先行处理的 `always_ask` 调用会被拒绝，除非 [`PermissionRequest` hook](https://code.claude.com/docs/zh-CN/hooks#permissionrequest) 允许它。

1556

1557##### 可以批准 `always_ask` 调用的权限模式

1558

1559在 `auto`、`plan` 和 `bypassPermissions` 模式下，对标记为 [`always_ask`](#permission-policy-values) 的工具的调用可能在到达您的 `canUseTool` 回调之前就被批准。在下面的列表中找到您会话所用的模式，了解该批准何时发生，以及需要设置什么才能让调用仍然到达您的回调：

1560

1561* **`auto`**：自动模式[分类器](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)会审查该调用并可能允许它。要让每个调用在 `auto` 模式下都到达您的回调，请在工具的[注解](#toolannotations)中设置 `destructiveHint: true`

1562* **`plan`**：当会话可使用[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)时，对注解为 `readOnlyHint: true` 的 `always_ask` 工具的调用会转到自动模式分类器，分类器可能允许它们。对其他 `always_ask` 工具的调用会到达您的回调。要让只读工具的调用也到达您的回调，请在该工具的注解中于 `readOnlyHint: true` 之外添加 `destructiveHint: true`。或者，将 [`useAutoModeDuringPlan`](https://code.claude.com/docs/zh-CN/settings-reference#useautomodeduringplan) 设为 `false`，这会在规划期间关闭分类器

1563* **`bypassPermissions`**：当 [`CLAUDE_CODE_REMOTE`](https://code.claude.com/docs/zh-CN/env-vars#variables) 环境变量为 `true` 时（在[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)中即是如此），无论工具的注解如何，该调用都会在不经过您回调的情况下被批准。在其他任何地方，该调用都会到达您的回调。要让它在云端会话中也到达您的回调，请改为在 `default` 或 `acceptEdits` 模式下运行会话

1564

1565在 `auto` 和 `plan` 模式下，请显式地将 `destructiveHint` 设为 `true`。对于 `always_ask` 调用，Claude Code 会将未设置的 `destructiveHint` 视为 `false`，尽管 [`ToolAnnotations`](#toolannotations) 下列出的默认值为 `true`。

1566

1442#### `McpClaudeAIProxyServerConfig`1567#### `McpClaudeAIProxyServerConfig`

1443 1568

1444```typescript theme={null}1569```typescript theme={null}

1464| 字段 | 类型 | 描述 |1589| 字段 | 类型 | 描述 |

1465| :- | :- | :- |1590| :- | :- | :- |

1469 1594

1470**示例：**1595**示例：**

5074};5199};

5075```5200```

5076 5201

5077`source` 表示服务器定义的来源，其取值和信任规则与 [`McpServerProvenance`](#mcpserverprovenance) 的 `source` 相同。该字段需要 Agent SDK v0.3.274 或更高版本，在更早的版本中不存在。5202使用 `source` 决定对服务器的信任程度，并使用每个 `tools` 条目上的 `_meta` 查找服务器附加到该工具的 UI 资源：

5203

5204* **`source`**：服务器定义的来源，取值与 [`McpServerProvenance`](#mcpserverprovenance) 上的 `source` 相同。请基于 `source` 而不是 `name` 做出信任决策，因为只有您自己的进程内服务器才会报告 `sdk`，无论任何其他服务器以什么名称注册。如果您无法识别某个 `source` 值，请像对待任何 `source` 不是 `sdk` 的服务器一样对待该服务器。需要 Agent SDK v0.3.274 或更高版本

5205* **`_meta`**：服务器为该工具声明的 `_meta` 中的 `ui` 对象和 `ui/resourceUri` 字符串。Claude Code 会扣留所有其他 `_meta` 键。`ui/resourceUri` 是 `ui.resourceUri` 的一种较旧的顶层写法。当服务器为该工具附加了 [MCP Apps UI 资源](https://code.claude.com/docs/zh-CN/mcp.md#reference-mcp-resources)时，`ui.resourceUri` 或 `ui/resourceUri` 保存该资源的 `ui://` URI。使用 [`readMcpResource()`](#query-object) 获取该 URI，并在您的应用程序中渲染该资源。需要 Agent SDK v0.3.280 或更高版本

5206

5207仅当 subtype 为 `init` 的 `system` 消息的 [`capabilities`](#sdksystemmessage) 数组列出 `mcp_tool_ui_meta_v1` 时，Claude Code 才会发送 `_meta`。您无需自行启用 `mcp_tool_ui_meta_v1`。

5208

5209#### 当工具的 `_meta.ui` 仅包含 `visibility` 时

5210

5211如果您的服务器为某个工具声明了 `ui.resourceUri`，但您的应用程序收到的 `_meta.ui` 仅包含 `visibility`，则说明服务器发送的 `ui` 对象未通过 Claude Code 的某项检查。Claude Code 会分别检查 `ui` 和 `ui/resourceUri`，因此当一个键未通过检查时，另一个键仍可能到达您的应用程序。请将服务器 `tools/list` 响应中的 `_meta` 与每个键的检查项进行比对：

5212

5213* **`ui`**：如果以下三项检查全部通过，则原样到达您的应用程序，包括 `resourceUri` 和 `visibility` 以外的任何成员：

5214

5215 * `resourceUri` 不存在，或者是以 `ui://` 开头的字符串

5216 * `visibility` 不存在，或者仅列出 `"model"` 和 `"app"`

5217 * 整个对象序列化为 JSON 后最多 4,096 个字符

5218

5219 如果任何一项检查未通过，您的应用程序最多只会收到一个 `ui`，其唯一成员是由服务器所列出的 `"model"` 和 `"app"` 条目组成的 `visibility` 数组。

5220* **`ui/resourceUri`**：如果它是以 `ui://` 开头且最多 4,096 个字符的字符串，则会到达您的应用程序。否则 Claude Code 会将其丢弃

5078 5221

5079`tools` 条目上的 `_meta` 携带该工具 `_meta` 中的 MCP Apps 成员，以便您的应用程序找到要通过 [`readMcpResource()`](#query-object) 渲染的 `ui://` 资源。Claude Code 会透传 `ui` 对象和已弃用的扁平 `ui/resourceUri` 字符串，并扣留所有其他键，不予透传。在 `ui` 内部，当服务器设置了 `resourceUri` 和 `visibility` 时，`resourceUri` 为 `ui://` 字符串，`visibility` 为由 `"model"` 和 `"app"` 组成的数组，其他任何成员原样透传。当值格式错误时，Claude Code 会丢弃相应的键；对于两者都未声明的工具，则省略 `_meta`。仅当 init 消息的 [`capabilities`](#sdksystemmessage) 包含 `mcp_tool_ui_meta_v1` 时，该字段才会出现，并且需要 TypeScript Agent SDK v0.3.280 或更高版本。5222当 Claude Code 既没有可发送的 `ui` 成员，也没有可发送的 `ui/resourceUri` 字符串时，该 `tools` 条目完全不包含 `_meta`。

5080 5223

5081### `McpServerStatusConfig`5224### `McpServerStatusConfig`

5082 5225

5311调用 `setMcpServers()` 时，Claude Code 会应用以下规则：5454调用 `setMcpServers()` 时，Claude Code 会应用以下规则：

5312 5455

5313* **调用未指定的服务器**：在[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)之外，Claude Code 会断开先前 `setMcpServers()` 调用添加的服务器以及进程内 SDK 服务器的连接，并在 `removed` 中列出它们。其他服务器会继续运行，且不会列在 `removed` 中，其中包括来自 [`mcpServers`](#options) 选项的 stdio、HTTP 和 SSE 服务器、来自设置文件的服务器以及插件提供的服务器。5456* **调用未指定的服务器**：在[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)之外，Claude Code 会断开先前 `setMcpServers()` 调用添加的服务器以及进程内 SDK 服务器的连接，并在 `removed` 中列出它们。其他服务器会继续运行，且不会列在 `removed` 中，其中包括来自 [`mcpServers`](#options) 选项的 stdio、HTTP 和 SSE 服务器、来自设置文件的服务器以及插件提供的服务器。

5314* **调用指定的服务器**：对于先前 `setMcpServers()` 调用添加的 stdio、HTTP 或 SSE 服务器，只有当其配置与您传入的配置不同时，Claude Code 才会替换它。已以该名称注册的进程内 SDK 服务器会保持原样，因此要替换它，请在一次调用中将其省略，然后在下一次调用中添加它。5457* **先前 `setMcpServers()` 调用添加的 stdio、HTTP 和 SSE 服务器**：在云端会话之外，如果您以相同的配置再次指定某个服务器，它会保留其连接和工具，既不会出现在 `added` 中，也不会出现在 `removed` 中。如果您传入更改后的配置，Claude Code 会使用该配置重新连接该服务器，并将其列在 `added` 中，而不是 `removed` 中。

5458* **调用指定的、此前没有任何调用添加过的 stdio、HTTP 和 SSE 服务器**：在云端会话之外，Claude Code 会添加该服务器并将其列在 `added` 中；如果拒绝该服务器，则将其列在 `errors` 中。

5459* **调用指定的进程内 SDK 服务器**：已通过 `mcpServers` 或先前调用注册的服务器会保留其正在运行的实例和超时时间。如果您为其传入 [`tools` 策略列表](#mcpsdkserverconfigwithinstance)（即使是空列表），则会替换其策略；否则策略保持不变。要在云端会话之外运行新实例，请在一次调用中省略该服务器，然后在下一次调用中指定它。

5315* **CLI 在启动时启动的内置服务器**：如果调用指定了其中之一，Claude Code 会丢弃该条目并在 `errors` 中报告它。5460* **CLI 在启动时启动的内置服务器**：如果调用指定了其中之一，Claude Code 会丢弃该条目并在 `errors` 中报告它。

5316* **与 MCP 安装作用域（例如 `.mcp.json`）中的服务器同名的 stdio、HTTP 或 SSE 服务器**：在该名称下，会话使用您的服务器的工具，而不是[安装作用域服务器](https://code.claude.com/docs/zh-CN/mcp.md#mcp-installation-scopes)的工具。在 Claude Code v2.1.305 之前，当您的应用[重新加载插件](#query-object)时，Claude Code 可能会断开您的服务器的连接并改为连接安装作用域服务器。5461* **与 MCP 安装作用域（例如 `.mcp.json`）中的服务器同名的 stdio、HTTP 或 SSE 服务器**：在该名称下，会话使用您的服务器的工具，而不是[安装作用域服务器](https://code.claude.com/docs/zh-CN/mcp.md#mcp-installation-scopes)的工具。在 Claude Code v2.1.305 之前，当您的应用[重新加载插件](#query-object)时，Claude Code 可能会断开您的服务器的连接并改为连接安装作用域服务器。

5317 5462

5798 5943

5799在 Claude Code v2.1.203 及更高版本中，SDK 发布的类型定义声明了 `SDKConversationResetMessage`。在 v2.1.203 之前，`SDKMessage` 引用了该类型却未声明它，因此在禁用 `skipLibCheck` 时，基于 `type === "conversation_reset"` 的类型收窄无法通过类型检查。5944在 Claude Code v2.1.203 及更高版本中，SDK 发布的类型定义声明了 `SDKConversationResetMessage`。在 v2.1.203 之前，`SDKMessage` 引用了该类型却未声明它，因此在禁用 `skipLibCheck` 时，基于 `type === "conversation_reset"` 的类型收窄无法通过类型检查。

5800 5945

5946### `BUILTIN_TOOL_NAMES` 和 `LEGACY_TOOL_NAME_ALIASES`

5947

5948使用这两个常量来检查您的应用程序用户输入的工具名称。两者中每个名称的写法都与您在权限规则、hook 匹配器以及 `tools` 和 `disallowedTools` 选项中的写法一致。请从 `@anthropic-ai/claude-agent-sdk` 或 `@anthropic-ai/claude-agent-sdk/core` 导入它们。它们需要 Agent SDK v0.3.301 或更高版本，并且处于 alpha 阶段。

5949

5950SDK 的类型声明为 `BUILTIN_TOOL_NAMES` 提供了只读元组类型，为 `LEGACY_TOOL_NAME_ALIASES` 提供了字符串到字符串的记录类型：

5951

5952```typescript theme={null}

5953const BUILTIN_TOOL_NAMES: readonly ["Agent", /* ...more names... */ "Write"];

5954const LEGACY_TOOL_NAME_ALIASES: Readonly<Record<string, string>>;

5955```

5956

5957* **`BUILTIN_TOOL_NAMES`**：按字母顺序排列的 Claude Code 内置工具名称，例如 `Agent`、`Bash` 和 `Read`。不包括 MCP 工具名称。由于该类型是字符串字面量元组，`(typeof BUILTIN_TOOL_NAMES)[number]` 会为您提供这些名称的联合类型

5958* **`LEGACY_TOOL_NAME_ALIASES`**：权限规则、hook 匹配器以及 `tools` 和 `disallowedTools` 选项仍然接受的早期工具名称。每个键是一个早期名称，其值是当前名称：例如，`Task` 映射到 `Agent`，`KillShell` 和 `KillBash` 映射到 `TaskStop`

5959

5960您可以通过以下两种检测中的任意一种来确认某个名称：`BUILTIN_TOOL_NAMES` 包含它，或者 `Object.hasOwn(LEGACY_TOOL_NAME_ALIASES, name)` 返回 `true`。两种检测都未通过的名称仍可能是有效的，因为 `BUILTIN_TOOL_NAMES` 不包括 MCP 工具和部分内置工具。如果您基于 `BUILTIN_TOOL_NAMES` 构建拒绝列表，Claude 仍然可以使用该常量未包含的工具。要拒绝所有工具，请改为设置 [`disallowedTools: ["*"]`](https://code.claude.com/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules)。

5961

5962在 `BUILTIN_TOOL_NAMES` 中找到某个名称并不代表会话拥有该工具：`TodoWrite` 虽然[默认处于禁用状态](https://code.claude.com/docs/zh-CN/tools-reference.md)，但仍列在其中。要查看会话拥有哪些工具，请读取其 [`SDKSystemMessage`](#sdksystemmessage) 的 `tools` 数组。该数组包含 MCP 工具，并将 Agent 工具列为 `Task`，因此在与 `BUILTIN_TOOL_NAMES` 比较之前，请先通过 `LEGACY_TOOL_NAME_ALIASES` 映射每个名称。

5963

5801### `AbortError`5964### `AbortError`

5802 5965

5803用于中止操作的自定义错误类。5966用于中止操作的自定义错误类。

agent-teams.md +1 −1

Details

188 188

189### 分配和认领任务189### 分配和认领任务

190 190

191共享任务列表用于协调整个团队的工作。负责人创建任务，队友逐一完成。任务有三种状态：待处理、进行中和已完成。任务还可以依赖其他任务：具有未解决依赖的待处理任务，在这些依赖完成之前无法被认领。191共享任务列表用于协调整个团队的工作。负责人创建任务，队友逐一完成。任务有三种状态：待处理、进行中和已完成。任务还可以依赖其他任务，在这些任务完成之前，它会在任务列表中显示为已阻塞。队友不会自行认领已阻塞的任务，但您或负责人仍可以分配它。

192 192

193[没有 Task 工具](https://code.claude.com/docs/zh-CN/tools-reference.md#task-tool-availability)的 Agent 改为通过消息进行协调，而不是通过共享任务列表。193[没有 Task 工具](https://code.claude.com/docs/zh-CN/tools-reference.md#task-tool-availability)的 Agent 改为通过消息进行协调，而不是通过共享任务列表。

194 194

agent-view.md +18 −9

Details

206* 已完成的会话：其结果206* 已完成的会话：其结果

207* 工作中的会话：其完整的状态句子207* 工作中的会话：其完整的状态句子

208 208

209接下来列出与该会话链接的所有拉取请求。对于正在等待您的会话，其下方的一行（例如 `waiting 3m`）显示它已等待多长时间，这也是面板中显示的唯一时间。行右边缘的时长是另一个数字：它从会话启动时开始计算。209接下来列出与该会话链接的所有拉取请求。对于正在等待您或以安全模式运行的会话，其下方还会多出一行：

210

211* 类似 `waiting 3m` 的行：会话已等待您多长时间。行右边缘的时长是另一个数字：它从会话启动时开始计算

212* `safe mode · customizations are off`：此会话在[关闭您的自定义配置](https://code.claude.com/docs/zh-CN/debug-your-config.md#test-against-a-clean-configuration)的情况下运行，因为您是从 shell 用 `claude --bg --safe-mode` 启动它的。您可以保持原样。要在重新启用自定义配置的情况下继续对话，请在 shell 中依次运行 [`claude stop <id>`](#manage-sessions-from-the-shell) 和 [`claude --resume`](https://code.claude.com/docs/zh-CN/sessions#resume-a-session)

210 213

211大多数时候窥视面板就足够了，您无需打开完整的会话记录。214大多数时候窥视面板就足够了，您无需打开完整的会话记录。

212 215

468 471

469#### 后台处理时的继承内容472#### 后台处理时的继承内容

470 473

471后台处理会启动一个从已保存对话恢复的新进程，进行中的后台工作会移到该进程。正在运行的后台 shell 命令、已转入后台的子代理、动态工作流、您使用 [`/loop`](https://code.claude.com/docs/zh-CN/scheduled-tasks) 创建的定时任务，以及 Claude 对 [Artifact 评论的自动回复](https://code.claude.com/docs/zh-CN/artifacts.md#let-claude-reply-to-comments-on-its-own) 都会继承过去并在那里继续运行。子代理会与其启动的所有内容一起移动，因此只有当所有这些工作也都能移动时它才会被继承。474当您将会话转入后台时，每种进行中的后台工作要么继承到后台会话，要么仅在 Claude 于那里重新启动它时才继续，要么停止：

~~472~~

473当 [动态工作流](https://code.claude.com/docs/zh-CN/workflows.md) 仍有子代理在运行时，Claude Code 会在后台处理前通过 `Background this session?` 对话框询问，其中会说明有多少子代理将重新启动。选择 `Stay` 可让它们先完成。如果您确认，Claude Code 会在后台会话中重放该运行：仍在运行的子代理会从头开始，因此它们目前已使用的 token 会再次消耗。请参阅 [暂停后恢复](https://code.claude.com/docs/zh-CN/workflows.md#resume-after-a-pause) 了解哪些已完成的子代理会返回其保存的结果、哪些会再次运行。

474 475

475Claude Code 会停止无法继承的后台工作，例如正在运行的 [monitor](https://code.claude.com/docs/zh-CN/tools-reference.md#monitor-tool)，并一并停止拥有 monitor 的后台子代理。当有任何此类工作正在运行时，Claude Code 会显示 `Background this session?` 对话框，以便您在它停止工作前确认。476* **继承**：正在运行的后台 shell 命令、已转入后台的子代理、您使用 [`/loop`](https://code.claude.com/docs/zh-CN/scheduled-tasks) 创建的定时任务，以及 Claude 对 [Artifact 评论的自动回复](https://code.claude.com/docs/zh-CN/artifacts.md#let-claude-reply-to-comments-on-its-own) 会在后台会话中继续运行。子代理会与其启动的所有内容一起移动，因此只有当所有这些工作也都能移动时它才会被继承。

477* **仅在 Claude 重新启动时继续**：正在运行的 [动态工作流](https://code.claude.com/docs/zh-CN/workflows.md)。如果您查看后台会话时该工作流尚未继续，请 [让 Claude 重新启动它](#dynamic-workflows-when-you-background)。

478* **停止**：无法移到后台会话的工作，例如正在运行的 [monitor](https://code.claude.com/docs/zh-CN/tools-reference.md#monitor-tool)。当有任何此类工作正在运行时，Claude Code 会显示 `Background this session?` 对话框，以便您在它停止工作前确认。拥有 monitor 的已转入后台的子代理会随 monitor 一起停止。

476 479

477进入后台后，会话可以启动新的子代理、monitor 和后台命令，这些在之后的分离和重新附加过程中会持续运行。480进入后台后，会话可以启动新的子代理、monitor 和后台命令，这些在之后的分离和重新附加过程中会持续运行。

478 481

488 491

489您在会话期间使用 [`/add-dir`](https://code.claude.com/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) 添加的目录也会继承。继承 `--allow-dangerously-skip-permissions` 会使 `bypassPermissions` 在后台会话中保持可用，但不会授予任何新权限：该模式仍需要有您 [接受绕过免责声明](https://code.claude.com/docs/zh-CN/permission-modes.md#skip-all-checks-with-bypasspermissions-mode) 的记录。492您在会话期间使用 [`/add-dir`](https://code.claude.com/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) 添加的目录也会继承。继承 `--allow-dangerously-skip-permissions` 会使 `bypassPermissions` 在后台会话中保持可用，但不会授予任何新权限：该模式仍需要有您 [接受绕过免责声明](https://code.claude.com/docs/zh-CN/permission-modes.md#skip-all-checks-with-bypasspermissions-mode) 的记录。

490 493

494##### 后台处理时的动态工作流

495

496如果 [动态工作流](https://code.claude.com/docs/zh-CN/workflows.md) 在您将其会话转入后台后没有继续，请让 Claude [重新启动该工作流](https://code.claude.com/docs/zh-CN/workflows.md#resume-after-you-leave-the-session)。只有当 Claude 在后台会话中重新启动它时，该运行才会继续，并且 Claude Code 可能会先请您批准该重新启动。会话的对话中会显示一条通知，说明该工作流 `could not be resumed`。

497

498当 Claude 重新启动工作流时，在您将会话转入后台时仍在运行的任何子代理都会从头开始，并再次消耗其 token。如果您在仍有子代理运行时按 `←` 或运行 `/background`，`Background this session?` 对话框会说明有多少个。要让它们先完成，请选择 `Stay`。

499

491### 从您的 shell 分派 Agent500### 从您的 shell 分派 Agent

492 501

493传递 `--bg` 或其长形式 `--background` 可启动直接进入后台的会话：502传递 `--bg` 或其长形式 `--background` 可启动直接进入后台的会话：

844* **自动更新后**：监督进程重新启动自身到新版本，并在后台移动空闲会话。工作中、等待您或已连接的会话不会被中断。853* **自动更新后**：监督进程重新启动自身到新版本，并在后台移动空闲会话。工作中、等待您或已连接的会话不会被中断。

845* **监督进程本身停止**，例如因为其进程被 Claude Code 外部结束：在 macOS 和 Linux 上，除非新的监督进程在约一分钟内连接，否则您的会话会停止。要启动新的监督进程，请在 shell 中运行 `claude agents`。超过这一分钟后，请参阅[在监督进程停止后保持会话运行](#keep-sessions-running-after-the-supervisor-stops)。854* **监督进程本身停止**，例如因为其进程被 Claude Code 外部结束：在 macOS 和 Linux 上，除非新的监督进程在约一分钟内连接，否则您的会话会停止。要启动新的监督进程，请在 shell 中运行 `claude agents`。超过这一分钟后，请参阅[在监督进程停止后保持会话运行](#keep-sessions-running-after-the-supervisor-stops)。

846 855

847当会话的进程停止或重新启动时，Claude 在其中启动的后台 shell 命令、动态工作流和后台子代理会转移到其下一个进程；运行中的监视器和子代理启动的 shell 命令会随进程停止。删除会话会停止它转移的所有内容。要改为让所有内容随进程停止而不是转移，请将 [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](https://code.claude.com/docs/zh-CN/env-vars#variables) 设置为 `1`。856当会话的进程停止或重新启动时，Claude 在其中启动的后台 shell 命令和后台子代理会转移到其下一个进程。动态工作流[仅在 Claude 重新启动它时才会继续](#dynamic-workflows-when-you-background)。运行中的监视器和子代理启动的 shell 命令会随进程停止。如果您删除该会话，它转移的所有内容都会停止。要改为让所有内容随进程一起停止，请将 [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](https://code.claude.com/docs/zh-CN/env-vars#variables) 设置为 `1`。

848 857

849监督进程及其会话使用与您的交互式会话相同的存储凭据进行身份验证。关于哪些设置和 shell 变量到达会话（包括 `PATH`），请参阅[设置和提供商](#settings-and-provider)。关于网关端点，请参阅 [LLM 网关](#llm-gateway)。858监督进程及其会话使用与您的交互式会话相同的存储凭据进行身份验证。关于哪些设置和 shell 变量到达会话（包括 `PATH`），请参阅[设置和提供商](#settings-and-provider)。关于网关端点，请参阅 [LLM 网关](#llm-gateway)。

850 859

897 906

898### 后台处理显示 `Background this session?` 对话框907### 后台处理显示 `Background this session?` 对话框

899 908

900如果您按 `←` 来后台处理当前会话，而 Claude Code 显示 `Background this session?` 对话框，说明该会话有正在进行的后台工作，后台处理会停止、重新启动或让其无人值守地运行，Claude Code 在执行这些操作之前会询问：909当您按 `←` 来后台处理某个会话时，如果出现 `Background this session?` 对话框，说明该会话有正在进行的后台工作，这些工作会被停止、被中断或在无人值守的情况下继续运行：

901 910

902* **无法移动的工作**：该会话有无法移动到后台会话的工作，例如正在运行的[监视器](https://code.claude.com/docs/zh-CN/tools-reference.md#monitor-tool)。对话框列出 Claude Code 会停止的后台工作，并另外计算会转移的任务数。911* **无法移动的工作**：该会话有无法移动到后台会话的工作，例如正在运行的[监视器](https://code.claude.com/docs/zh-CN/tools-reference.md#monitor-tool)。对话框列出 Claude Code 会停止的后台工作，并另外计算会转移的任务数。

903* **具有运行子代理的工作流**：[动态工作流](https://code.claude.com/docs/zh-CN/workflows.md)仍然有子代理在运行。工作流本身会转移，但其运行的子代理从头开始重新启动，对话框会说明有多少个。912* **具有运行子代理的工作流**：[动态工作流](https://code.claude.com/docs/zh-CN/workflows.md)仍然有子代理在运行。如果您仍然进行后台处理，这些子代理会停止，对话框会说明有多少个。当 Claude [在后台会话中重新启动该工作流](#dynamic-workflows-when-you-background)时，它们会从头开始。

904* **自动 Artifact 回复**：Claude [自动回复 Artifact 上的评论](https://code.claude.com/docs/zh-CN/artifacts.md#let-claude-reply-to-comments-on-its-own)。这些回复在后台会话中继续，对话框会说明这一点。913* **自动 Artifact 回复**：Claude [自动回复 Artifact 上的评论](https://code.claude.com/docs/zh-CN/artifacts.md#let-claude-reply-to-comments-on-its-own)。这些回复在后台会话中继续，对话框会说明这一点。

905 914

906运行 `/tasks` 来查看正在运行的所有内容，然后确认后台处理或选择 `Stay` 来让工作先完成。请参阅[后台处理时转移的内容](#what-carries-over-when-you-background)，了解哪些类型的工作会转移，哪些 Claude Code 会停止。915运行 `/tasks` 来查看正在运行的所有内容，然后确认后台处理或选择 `Stay` 来让工作先完成。请参阅[后台处理时转移的内容](#what-carries-over-when-you-background)，了解哪些类型的工作会转移，哪些 Claude Code 会停止。

1118| v2.1.200 | 重写 `roster.json` 中会话列表的较旧 Claude Code 版本会保留由较新版本写入的字段，与现有的 `state.json` 保证一致，因此由较新版本启动的会话在监督进程重启后仍能继续接受输入。当您打开已停止响应的会话时，监督进程会重启其进程，会话会从中断处继续被中断的回复。Agent view 会将放在 `agents` 之后的 `--plugin-dir` 标志应用于其自身在调度输入框中的子代理和 skill 自动补全，以及所调度的会话。 |1127| v2.1.200 | 重写 `roster.json` 中会话列表的较旧 Claude Code 版本会保留由较新版本写入的字段，与现有的 `state.json` 保证一致，因此由较新版本启动的会话在监督进程重启后仍能继续接受输入。当您打开已停止响应的会话时，监督进程会重启其进程，会话会从中断处继续被中断的回复。Agent view 会将放在 `agents` 之后的 `--plugin-dir` 标志应用于其自身在调度输入框中的子代理和 skill 自动补全，以及所调度的会话。 |

1119| v2.1.199 | 在低内存主机上，后台会话的进程在完成启动前退出时，其行状态会显示 `possibly low memory — free some up and retry`，而不仅仅是简单的退出原因。使用 `←` 或 `/background` 将会话移到后台时，会将其 `/color` 带到新行。 |1128| v2.1.199 | 在低内存主机上，后台会话的进程在完成启动前退出时，其行状态会显示 `possibly low memory — free some up and retry`，而不仅仅是简单的退出原因。使用 `←` 或 `/background` 将会话移到后台时，会将其 `/color` 带到新行。 |

1120| v2.1.198 | 当后台会话需要输入、完成或失败时，Agent view 会通过 `preferredNotifChannel` 发送通知，并以 `agent_needs_input` 或 `agent_completed` 类型触发 `Notification` hook。在 `claude attach <id>` 中，`←` 和 `/exit` 会返回 agent view，而不是退出到 shell；`Ctrl+Z` 会返回 shell。在 worktree 中隔离其工作的后台会话完成时，会提交、推送其自己的隔离分支（绝不会推送 `main` 或 `master`），并打开一个草稿 Pull Request，而不是先询问。`/login` 可在 agent view 中运行并打开登录对话框。`Background work is running` 退出对话框提供 `Move to background and exit`。退出交接也涵盖后台子代理，它们会在下次唤醒时从其会话记录恢复，而不是被报告为失败。`claude --bg` 与 `-p` 或 `--print` 组合使用时会被拒绝并报错。后台会话主机会在首次访问局域网时请求 macOS 本地网络权限，而不是以 `connect: no route to host` 失败。 |1129| v2.1.198 | 当后台会话需要输入、完成或失败时，Agent view 会通过 `preferredNotifChannel` 发送通知，并以 `agent_needs_input` 或 `agent_completed` 类型触发 `Notification` hook。在 `claude attach <id>` 中，`←` 和 `/exit` 会返回 agent view，而不是退出到 shell；`Ctrl+Z` 会返回 shell。在 worktree 中隔离其工作的后台会话完成时，会提交、推送其自己的隔离分支（绝不会推送 `main` 或 `master`），并打开一个草稿 Pull Request，而不是先询问。`/login` 可在 agent view 中运行并打开登录对话框。`Background work is running` 退出对话框提供 `Move to background and exit`。退出交接也涵盖后台子代理，它们会在下次唤醒时从其会话记录恢复，而不是被报告为失败。`claude --bg` 与 `-p` 或 `--print` 组合使用时会被拒绝并报错。后台会话主机会在首次访问局域网时请求 macOS 本地网络权限，而不是以 `connect: no route to host` 失败。 |

1121| v2.1.196 | 按一次 `←` 即可将前台会话移到后台；早期版本需要按两次，并带有页脚提示和确认。传递给 `claude agents` 的 `--dangerously-skip-permissions` 会显示绕过免责声明，而不是在不提示的情况下被丢弃。您从未命名的交互式会话在会话列表和 `claude agents --json` 中会带有默认名称，例如 `my-app-3f`。后台 shell 命令和动态工作流在会话进程被停止、重启或更新时仍能继续存在，包括在 Windows 上；设置 `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1` 可关闭此交接。在重启时被误读为空的会话记录会被重命名并加上 `.orphaned-` 后缀，而不是被删除。 |1130| v2.1.196 | 按一次 `←` 即可将前台会话移到后台；早期版本需要按两次，并带有页脚提示和确认。传递给 `claude agents` 的 `--dangerously-skip-permissions` 会显示绕过免责声明，而不是在不提示的情况下被丢弃。您从未命名的交互式会话在会话列表和 `claude agents --json` 中会带有默认名称，例如 `my-app-3f`。后台 shell 命令在会话进程被停止、重启或更新时仍能继续存在，包括在 Windows 上；设置 `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1` 可关闭此交接。在重启时被误读为空的会话记录会被重命名并加上 `.orphaned-` 后缀，而不是被删除。 |

1122| v2.1.195 | 在 Windows 上将会话移到后台时，进行中的后台工作也会转移。`Completed` 组会填满剩余的垂直空间，标题在较矮的终端上会压缩显示。较旧的 Claude Code 版本不再丢弃较新会话的 `state.json` 字段，也不再在 `claude agents` 中隐藏这些会话。附加到已停止的会话会立即切换，而不是显示最多五秒的空白屏幕。无法接受连接的监督进程会自行退出并释放其锁。 |1131| v2.1.195 | 在 Windows 上将会话移到后台时，进行中的后台工作也会转移。`Completed` 组会填满剩余的垂直空间，标题在较矮的终端上会压缩显示。较旧的 Claude Code 版本不再丢弃较新会话的 `state.json` 字段，也不再在 `claude agents` 中隐藏这些会话。附加到已停止的会话会立即切换，而不是显示最多五秒的空白屏幕。无法接受连接的监督进程会自行退出并释放其锁。 |

1123| v2.1.191 | 如果 `claude --bg` 使用的 `--agent` 名称与您的任何子代理都不匹配，启动会失败：会话会立即退出并显示 `--agent '<name>' not found` 错误，而不是使用默认 Agent 运行。 |1132| v2.1.191 | 如果 `claude --bg` 使用的 `--agent` 名称与您的任何子代理都不匹配，启动会失败：会话会立即退出并显示 `--agent '<name>' not found` 错误，而不是使用默认 Agent 运行。 |

1124| v2.1.174 | 后台会话不再从监督进程的启动 shell 继承 `ANTHROPIC_BASE_URL` 等网关端点变量；监督进程会向预热的工作进程提供新的凭据快照，修复了虚假的 `Could not resolve authentication method` 错误。 |1133| v2.1.174 | 后台会话不再从监督进程的启动 shell 继承 `ANTHROPIC_BASE_URL` 等网关端点变量；监督进程会向预热的工作进程提供新的凭据快照，修复了虚假的 `Could not resolve authentication method` 错误。 |

claude-apps-gateway-config.md +11 −2

Details

927 927

928切换时，请在重命名块的同一次编辑中删除所有 `serve_to_desktop` 行。在说明中提到 `cli` 块的地方，请使用您的 `code` 块。928切换时，请在重命名块的同一次编辑中删除所有 `serve_to_desktop` 行。在说明中提到 `cli` 块的地方，请使用您的 `code` 块。

929 929

930`serve_to_desktop: true` 是向 Code 标签页提供策略 `cli` 设置的旧方式。当 Claude Desktop 通过 [`bootstrapUrl`](#claude-desktop-overlay) 连接时，它不起作用。当您的策略使用 `cli` 时，提到此键的启动警告意味着这些设置未到达 Code 标签页：

931

932* **要覆盖 Code 标签页**：在用户的计算机满足[在 Code 标签页中应用 `code` 设置](#apply-code-settings-in-the-code-tab)中的条件后，切换到 `code`

933* **要继续使用 `cli`**：在策略中的 `cli` 旁设置 `serve_to_desktop: false` 以消除警告

934

930#### `cli` 中包含什么935#### `cli` 中包含什么

931 936

932每个 `code` 或 `cli` 值都是一个完整的 Claude Code `managed-settings.json` 文档，与您通过 MDM 或 `/etc/claude-code/managed-settings.json` 部署的 schema 相同，只是此处以 YAML 表示。CLI 在托管层级（高于用户和项目设置）应用所交付的文档，以取代服务器托管设置。因此，它会忽略[仅限于操作系统级策略来源](https://code.claude.com/docs/zh-CN/server-managed-settings.md#current-limitations)的设置，例如 `policyHelper` 和 `wslInheritsWindowsSettings`。937每个 `code` 或 `cli` 值都是一个完整的 Claude Code `managed-settings.json` 文档，与您通过 MDM 或 `/etc/claude-code/managed-settings.json` 部署的 schema 相同，只是此处以 YAML 表示。CLI 在托管层级（高于用户和项目设置）应用所交付的文档，以取代服务器托管设置。因此，它会忽略[仅限于操作系统级策略来源](https://code.claude.com/docs/zh-CN/server-managed-settings.md#current-limitations)的设置，例如 `policyHelper` 和 `wslInheritsWindowsSettings`。

974| - | - | - |979| - | - | - |

976| [`deniedModels`](https://code.claude.com/docs/zh-CN/settings-reference#deniedmodels)、[`availableModelsMatch`](https://code.claude.com/docs/zh-CN/settings-reference#availablemodelsmatch) | 网关 + CLI | [阻止特定模型或版本](https://code.claude.com/docs/zh-CN/model-config.md#block-specific-models-or-versions)，即使 `availableModels` 原本会允许它们。被阻止的模型会在 `/v1/messages` 以 `400` 被拒绝，并且不会出现在 `/v1/models` 中。网关自身的检查要求网关服务器上的 Claude Code 为 v2.1.299 或更高版本。CLI 的检查要求客户端为 v2.1.283 或更高版本，更早的客户端会忽略这两个键。 |981| [`deniedModels`](https://code.claude.com/docs/zh-CN/settings-reference#deniedmodels)、[`availableModelsMatch`](https://code.claude.com/docs/zh-CN/settings-reference#availablemodelsmatch) | 网关 + CLI | [阻止特定模型或版本](https://code.claude.com/docs/zh-CN/model-config.md#block-specific-models-or-versions)，即使 `availableModels` 原本会允许它们。被阻止的模型会在 `/v1/messages` 以 `400` 被拒绝，并且不会出现在 `/v1/models` 中。网关自身的检查要求网关服务器上的 Claude Code 为 v2.1.299 或更高版本。CLI 的检查要求客户端为 v2.1.283 或更高版本，更早的客户端会忽略这两个键。 |

977| `permissions.allow` / `.deny` | CLI | 工具和命令规则。请参阅[权限](https://code.claude.com/docs/zh-CN/permissions.md)。 |982| `permissions.allow` / `.deny` | CLI | 工具和命令规则。请参阅[权限](https://code.claude.com/docs/zh-CN/permissions.md)和 [Bash 规则不匹配的情况](https://code.claude.com/docs/zh-CN/permissions.md#bash-rule-limits)。 |

978| `permissions.disableBypassPermissionsMode` | CLI | 设置为 `disable` 可阻止 [`bypassPermissions`](https://code.claude.com/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)（跳过权限提示的模式）以及 `--dangerously-skip-permissions` 标志 |983| `permissions.disableBypassPermissionsMode` | CLI | 设置为 `disable` 可阻止 [`bypassPermissions`](https://code.claude.com/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)（跳过权限提示的模式）以及 `--dangerously-skip-permissions` 标志 |

979| `allowManagedPermissionRulesOnly` | CLI | 为 `true` 时，托管设置成为权限规则的唯一设置来源。[`allowManagedPermissionRulesOnly`](https://code.claude.com/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly) 条目列出了 Claude Code 随后会忽略的每个来源。 |984| `allowManagedPermissionRulesOnly` | CLI | 为 `true` 时，托管设置成为权限规则的唯一设置来源。[`allowManagedPermissionRulesOnly`](https://code.claude.com/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly) 条目列出了 Claude Code 随后会忽略的每个来源。 |

980| `env` | CLI | 合并到 CLI 进程中的环境变量。用于遥测、自动更新和模型名称覆盖。 |985| `env` | CLI | 合并到 CLI 进程中的环境变量。用于遥测、自动更新和模型名称覆盖。 |

1003 1008

1004`cli` 键在早期版本中名为 `settings`，网关仍接受该写法作为别名。对于新部署，请使用 [`code`](#choose-cli-or-code)。1009`cli` 键在早期版本中名为 `settings`，网关仍接受该写法作为别名。对于新部署，请使用 [`code`](#choose-cli-or-code)。

1005 1010

1011#### 在部署前测试策略

1012

1013要测试策略更改，请让网关连接一个临时的 Postgres 数据库启动。网关会先连接 Postgres 并应用其 schema 迁移，然后才检查 `cli`、`code` 和 `desktop` 块的内容。如果无法连接数据库，启动会在 `could not connect to Postgres` 处停止，且不会报告这些块内容的任何信息。

1014

1006#### 终端会话中的上下文窗口1015#### 终端会话中的上下文窗口

1007 1016

1008通过 `/login` 登录的终端会话对 Opus 4.7 及更高版本、Sonnet 5 及更高版本以及 Fable 模型使用 1M 上下文窗口。模型 ID 不需要 `[1m]` 后缀，会话在约 967K token 时压缩。在开发者机器上的 Claude Code v2.1.287 之前，除非模型 ID 以 `[1m]` 结尾，否则 Claude Code 将 Opus 和 Fable 模型视为具有 200K 窗口。1017通过 `/login` 登录的终端会话对 Opus 4.7 及更高版本、Sonnet 5 及更高版本以及 Fable 模型使用 1M 上下文窗口。模型 ID 不需要 `[1m]` 后缀，会话在约 967K token 时压缩。在开发者机器上的 Claude Code v2.1.287 之前，除非模型 ID 以 `[1m]` 结尾，否则 Claude Code 将 Opus 和 Fable 模型视为具有 200K 窗口。

1589 # 承包商策略继承此键。1598 # 承包商策略继承此键。

1590 enforceAvailableModels: true1599 enforceAvailableModels: true

1591 permissions:1600 permissions:

1592 allow: [Read, Grep, Bash, Edit]1601 allow: [Read, Grep, Edit]

1593 deny: ["WebFetch"]1602 deny: ["WebFetch"]

1594 env: { HTTP_PROXY: http://proxy.example.com:8080 }1603 env: { HTTP_PROXY: http://proxy.example.com:8080 }

1595 1604

claude-apps-gateway-deploy.md +1 −0

Details

393| 开发者的 `/login` 显示标准账户选择器而不是 **Cloud gateway** 屏幕 | 该机器的托管设置中未设置 `forceLoginMethod` 或 `forceLoginGatewayUrl` | 将[托管设置文件](https://code.claude.com/docs/zh-CN/claude-apps-gateway#set-the-gateway-url)部署到设备；`/login` 从那里读取网关 URL |393| 开发者的 `/login` 显示标准账户选择器而不是 **Cloud gateway** 屏幕 | 该机器的托管设置中未设置 `forceLoginMethod` 或 `forceLoginGatewayUrl` | 将[托管设置文件](https://code.claude.com/docs/zh-CN/claude-apps-gateway#set-the-gateway-url)部署到设备；`/login` 从那里读取网关 URL |

394| 开发者的请求失败，显示 `Not signed in to the Cloud gateway — run /login.` | 机器的托管设置设置了 `forceLoginMethod: "gateway"` 或 `forceLoginGatewayUrl`，且会话没有网关登录。残留的 claude.ai 登录不满足要求。 | 让开发者运行 `/login` 并完成网关登录。另请参阅[管理员策略需要 Cloud gateway 登录](https://code.claude.com/docs/zh-CN/errors.md#administrator-policy-requires-a-cloud-gateway-sign-in)。 |394| 开发者的请求失败，显示 `Not signed in to the Cloud gateway — run /login.` | 机器的托管设置设置了 `forceLoginMethod: "gateway"` 或 `forceLoginGatewayUrl`，且会话没有网关登录。残留的 claude.ai 登录不满足要求。 | 让开发者运行 `/login` 并完成网关登录。另请参阅[管理员策略需要 Cloud gateway 登录](https://code.claude.com/docs/zh-CN/errors.md#administrator-policy-requires-a-cloud-gateway-sign-in)。 |

395| Claude Desktop 报告其引导配置无法获取 | `/user/bootstrap` 返回 404：与用户匹配的策略不包含 `desktop` 键，或没有策略匹配。网关的审计日志将每次拒绝记录为 `desktop_bootstrap.denied` 并说明原因。 | 将 `desktop` 块添加到与用户匹配的策略，或添加到 `match: {}` 基础层；空的 `desktop: {}` 就足够了。请参阅 [Claude Desktop 覆盖](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config.md#claude-desktop-overlay)。 |395| Claude Desktop 报告其引导配置无法获取 | `/user/bootstrap` 返回 404：与用户匹配的策略不包含 `desktop` 键，或没有策略匹配。网关的审计日志将每次拒绝记录为 `desktop_bootstrap.denied` 并说明原因。 | 将 `desktop` 块添加到与用户匹配的策略，或添加到 `match: {}` 基础层；空的 `desktop: {}` 就足够了。请参阅 [Claude Desktop 覆盖](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config.md#claude-desktop-overlay)。 |

396| 审计日志在 `/v1/logs` 或 `/v1/metrics` 上显示 `auth.denied`，并带有 `reason: invalid_token` | 您在某台机器的托管设置中设置了 [`otelHeadersHelper`](https://code.claude.com/docs/zh-CN/settings-reference#otelheadershelper)。在该机器上的 Claude Desktop 会话中，Claude Code 会将来自该 helper 的 `Authorization` 头发送到网关的遥测中继，以代替会话令牌。如果 Claude Desktop 捆绑的 Claude Code 早于 v2.1.307，而您在这些设置中通过 `OTEL_EXPORTER_OTLP_HEADERS` 或其按信号区分的形式设置了 `Authorization` 头，也会出现同样的拒绝。 | 从这些设置中删除该 helper。如果 Claude Desktop 捆绑的 Claude Code 早于 v2.1.307，请删除该变量。 |

396| 启动显示 `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | 已安装的 Claude Code 版本早于网关支持 | 让开发者更新 Claude Code 到包含 Cloud gateway 支持的版本 |397| 启动显示 `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | 已安装的 Claude Code 版本早于网关支持 | 让开发者更新 Claude Code 到包含 Cloud gateway 支持的版本 |

397| 启动退出，显示 `Administrator policy requires a Cloud gateway sign-in on this machine` | 开发者的环境设置了 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，其设置配置了 [`apiKeyHelper`](https://code.claude.com/docs/zh-CN/settings-reference#apikeyhelper)，或来自早期 Claude Console 登录的 API 密钥仍然保存 | 让开发者清除每个适用的项：取消设置变量、删除 `apiKeyHelper` 条目，或运行 `claude auth logout` 删除保存的密钥。之后，使用 `CLAUDE_CODE_USE_*` 选择云提供商的会话无需登录即可启动；对于其他所有会话，让他们启动 `claude` 并使用 `/login` 登录。另请参阅[管理员策略需要 Cloud gateway 登录](https://code.claude.com/docs/zh-CN/errors.md#administrator-policy-requires-a-cloud-gateway-sign-in)。 |398| 启动退出，显示 `Administrator policy requires a Cloud gateway sign-in on this machine` | 开发者的环境设置了 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，其设置配置了 [`apiKeyHelper`](https://code.claude.com/docs/zh-CN/settings-reference#apikeyhelper)，或来自早期 Claude Console 登录的 API 密钥仍然保存 | 让开发者清除每个适用的项：取消设置变量、删除 `apiKeyHelper` 条目，或运行 `claude auth logout` 删除保存的密钥。之后，使用 `CLAUDE_CODE_USE_*` 选择云提供商的会话无需登录即可启动；对于其他所有会话，让他们启动 `claude` 并使用 `/login` 登录。另请参阅[管理员策略需要 Cloud gateway 登录](https://code.claude.com/docs/zh-CN/errors.md#administrator-policy-requires-a-cloud-gateway-sign-in)。 |

398| 启动或 `/login` 在托管设置加载时返回 403 后报告 `Claude Code may not be enabled for your organization` | 网关或其前面的某个组件用 403 响应了 `/managed/settings` 请求。网关自身的设置路由从不返回 403。状态来自 [`access_control`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#http-tuning) IP 检查或网关前面的代理或 WAF。审计日志将 IP 检查拒绝记录为 `access.denied` 并说明原因。开发者保持登录状态。 | 检查审计日志中失败时的 `access.denied`，修复 `access_control` 列表或前端，然后让开发者再次启动 `claude` |399| 启动或 `/login` 在托管设置加载时返回 403 后报告 `Claude Code may not be enabled for your organization` | 网关或其前面的某个组件用 403 响应了 `/managed/settings` 请求。网关自身的设置路由从不返回 403。状态来自 [`access_control`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#http-tuning) IP 检查或网关前面的代理或 WAF。审计日志将 IP 检查拒绝记录为 `access.denied` 并说明原因。开发者保持登录状态。 | 检查审计日志中失败时的 `access.denied`，修复 `access_control` 列表或前端，然后让开发者再次启动 `claude` |

claude-code-on-the-web.md +22 −0

Details

288 288

289[Agent teams](https://code.claude.com/docs/zh-CN/agent-teams.md) 默认关闭，但可以通过将 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 添加到你的[环境变量](https://code.claude.com/docs/zh-CN/cloud-environments.md#set-environment-variables)来启用。289[Agent teams](https://code.claude.com/docs/zh-CN/agent-teams.md) 默认关闭，但可以通过将 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 添加到你的[环境变量](https://code.claude.com/docs/zh-CN/cloud-environments.md#set-environment-variables)来启用。

290 290

291### 对话中的插件建议

292

293如果对话中出现一张列出一个或多个[插件](https://code.claude.com/docs/zh-CN/plugins/overview.md)并带有 **Add** 按钮的卡片，则表示 Claude 正在为您的任务建议插件。Claude 可能会在您未提出请求的情况下给出这些建议。您无需回应，无论如何 Claude 都会继续执行任务。

294

295#### 添加或移除建议的插件

296

297在插件上选择 **Add**，即可为您的 claude.ai 账户启用该插件，会话结束后该插件仍保持启用。要撤销，请从卡片中打开已添加的插件，选择 **Manage** 进入该插件在 claude.ai 上的页面，然后从该页面移除插件。

298

299#### 关闭插件建议

300

301要阻止 Claude 建议插件，请使用[权限规则](https://code.claude.com/docs/zh-CN/permissions.md#manage-permissions)拒绝 `SearchPlugins` 和 `SuggestPluginInstall` 工具。在[项目](https://code.claude.com/docs/zh-CN/claude-projects.md)之外且仅包含一个仓库的会话中，请将这些规则提交到该仓库的 `.claude/settings.json`，并在 `permissions.deny` 下列出这两个工具名称：

302

303```json theme={null}

304{

305 "permissions": {

306 "deny": ["SearchPlugins", "SuggestPluginInstall"]

307 }

308}

309```

310

311当适用于该会话的[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)设置了 [`allowManagedPermissionRulesOnly`](https://code.claude.com/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly) 时，Claude Code 会忽略仓库 `.claude/settings.json` 中的权限规则，包括这些拒绝规则。在这种情况下，请改为将规则放入这些托管设置中。对于其他配置，例如包含多个仓库的会话或项目中的云端线程，请参阅哪些[设置会作用于云端会话](https://code.claude.com/docs/zh-CN/settings.md#settings-in-cloud-sessions)。

312

291### 取回已排队的消息313### 取回已排队的消息

292 314

293如果您在 Claude 工作时发送消息，该消息会排队，直到 Claude 读取它。要取回已排队的消息，请点击消息上的 ✕。文本会返回到消息框，以便您编辑或发送其他内容。315如果您在 Claude 工作时发送消息，该消息会排队，直到 Claude 读取它。要取回已排队的消息，请点击消息上的 ✕。文本会返回到消息框，以便您编辑或发送其他内容。

claude-directory.md +9 −2

Details

103 103

104除了您创作的配置外，`~/.claude` 还保存 Claude Code 在会话期间写入的数据。这些文件是纯文本。通过工具传递的任何内容都会在磁盘上的记录中：文件内容、命令输出、粘贴的文本。104除了您创作的配置外，`~/.claude` 还保存 Claude Code 在会话期间写入的数据。这些文件是纯文本。通过工具传递的任何内容都会在磁盘上的记录中：文件内容、命令输出、粘贴的文本。

105 105

106会话记录还可能包含 Claude Code 随您的消息一起发送给模型的内容：

107

108* 系统提示词

109* 工具定义

110* 请求参数

111* 它加载的指令文件，例如 CLAUDE.md

112

106### 自动清理113### 自动清理

107 114

108Claude Code 删除下面路径中的文件，一旦它们的年龄超过 [`cleanupPeriodDays`](https://code.claude.com/docs/zh-CN/settings-reference#cleanupperioddays)，只要它能安全地确定保留期。默认值为 30 天，最小值为 1；设置 `0` 会导致验证错误。相同的年龄截止值也适用于 [孤立 worktrees](https://code.claude.com/docs/zh-CN/worktrees.md#clean-up-subagent-and-background-session-worktrees) 的自动删除。115Claude Code 删除下面路径中的文件，一旦它们的年龄超过 [`cleanupPeriodDays`](https://code.claude.com/docs/zh-CN/settings-reference#cleanupperioddays)，只要它能安全地确定保留期。默认值为 30 天，最小值为 1；设置 `0` 会导致验证错误。相同的年龄截止值也适用于 [孤立 worktrees](https://code.claude.com/docs/zh-CN/worktrees.md#clean-up-subagent-and-background-session-worktrees) 的自动删除。

109 116

110| `~/.claude/` 下的路径 | 内容 |117| `~/.claude/` 下的路径 | 内容 |

111| - | - |118| - | - |

113| `projects/<project>/<session>.orphaned-<timestamp>-<suffix>.jsonl`、`projects/<project>/<session>.jsonl.superseded-<timestamp>` | 会话的先前记录，Claude Code 将其搁置而不是覆盖或删除它。它不会出现在会话选择器中 |120| `projects/<project>/<session>.orphaned-<timestamp>-<suffix>.jsonl`、`projects/<project>/<session>.jsonl.superseded-<timestamp>` | 会话的先前记录，Claude Code 将其搁置而不是覆盖或删除它。它不会出现在会话选择器中 |

114| `projects/<project>/<session>/subagents/` | [Subagent](https://code.claude.com/docs/zh-CN/sub-agents.md) 对话记录，当父会话记录过期时被删除 |121| `projects/<project>/<session>/subagents/` | [子代理](https://code.claude.com/docs/zh-CN/sub-agents.md)的会话记录，格式与会话的会话记录相同，当父会话记录过期时随之删除 |

115| `projects/<project>/<session>/tool-results/` | 大型工具输出溢出到单独的文件，以及 [MCP 工具返回的图像](https://code.claude.com/docs/zh-CN/mcp.md#images-in-tool-results) 的完整大小副本 |122| `projects/<project>/<session>/tool-results/` | 大型工具输出溢出到单独的文件，以及 [MCP 工具返回的图像](https://code.claude.com/docs/zh-CN/mcp.md#images-in-tool-results) 的完整大小副本 |

116| `projects/<project>/<session>/mcp-tasks/` | 恢复的会话重新跟踪其正在运行的 [MCP 任务](https://code.claude.com/docs/zh-CN/mcp.md#mcp-tasks-that-run-on-the-server)所需的内容，以及 Claude 尚未读取的已完成任务的结果 |123| `projects/<project>/<session>/mcp-tasks/` | 恢复的会话重新跟踪其正在运行的 [MCP 任务](https://code.claude.com/docs/zh-CN/mcp.md#mcp-tasks-that-run-on-the-server)所需的内容，以及 Claude 尚未读取的已完成任务的结果 |

117| `file-history/<session>/` | Claude 更改的文件的编辑前快照，用于 [checkpoint 恢复](https://code.claude.com/docs/zh-CN/checkpointing.md)。保存最近 100 个 checkpoint 的快照；没有保留 checkpoint 引用的快照文件被删除，除了每个文件的第一个快照 |124| `file-history/<session>/` | Claude 更改的文件的编辑前快照，用于 [checkpoint 恢复](https://code.claude.com/docs/zh-CN/checkpointing.md)。保存最近 100 个 checkpoint 的快照；没有保留 checkpoint 引用的快照文件被删除，除了每个文件的第一个快照 |

claude-security.md +20 −2

Details

6 6

7> 安装 Claude Security plugin 以在 Claude Code 会话中扫描代码库中的漏洞，并将发现的问题转化为您可以审查和应用的补丁。7> 安装 Claude Security plugin 以在 Claude Code 会话中扫描代码库中的漏洞，并将发现的问题转化为您可以审查和应用的补丁。

8 8

9Claude Security plugin 在 Claude Code 会话中对您的代码库运行多代理漏洞扫描。一个 Claude 代理团队映射您的架构、构建威胁模型、搜寻漏洞，并在编写报告前独立审查每个发现。使用该插件扫描整个存储库或[仅扫描一组更改](#scan-only-your-changes)，例如分支的差异、拉取请求的差异或单个提交，然后将您选择的发现转化为您自己审查和应用的补丁。9Claude Security plugin 在 Claude Code 会话中对您的代码库运行多 Agent 漏洞扫描。[默认情况下](#choose-a-scan-effort)，当您扫描整个仓库时，Claude Agent 会映射您的架构、构建威胁模型、搜寻漏洞，并在编写报告前独立审查每个发现。

11使用该插件扫描整个仓库或[仅扫描一组更改](#scan-only-your-changes)，例如分支的 diff、Pull Request 的 diff 或单个提交，然后将您选择的发现转化为您自己审查和应用的补丁。

10 12

11该插件在您的会话中本地运行，使用[您在 Claude Code 中可以访问的任何模型](#models-and-providers)，每次扫描都计入您的[使用量](https://code.claude.com/docs/zh-CN/costs.md)。如果您想要一个监控您的仓库的托管服务，或想要在 [Claude Mythos](https://platform.claude.com/docs/en/about-claude/models/introducing-claude-fable-5-and-claude-mythos-5) 上运行扫描，请参阅 [Claude Security](https://claude.com/product/claude-security) 产品，该产品在企业计划中提供。13该插件在您的会话中本地运行，使用[您在 Claude Code 中可以访问的任何模型](#models-and-providers)，每次扫描都计入您的[使用量](https://code.claude.com/docs/zh-CN/costs.md)。如果您想要一个监控您的仓库的托管服务，或想要在 [Claude Mythos](https://platform.claude.com/docs/en/about-claude/models/introducing-claude-fable-5-and-claude-mythos-5) 上运行扫描，请参阅 [Claude Security](https://claude.com/product/claude-security) 产品，该产品在企业计划中提供。

12 14

51 53

52一旦插件处于活跃状态，您已准备好[扫描和修复您的代码库](#scan-and-fix-your-codebase)。54一旦插件处于活跃状态，您已准备好[扫描和修复您的代码库](#scan-and-fix-your-codebase)。

53 55

56### 更新插件

58要自行更新插件，请参阅[立即更新插件](https://code.claude.com/docs/zh-CN/plugins/install.md#update-plugins-now)。除非关闭了自动更新，否则 Claude Code 还会[自动更新插件](https://code.claude.com/docs/zh-CN/plugins/install.md#keep-plugins-updated)。

54### 卸载插件60### 卸载插件

55 61

56要删除该插件，从 `/plugin` 菜单卸载它，或在您的终端中运行 `claude plugin uninstall claude-security`。62要删除该插件，从 `/plugin` 菜单卸载它，或在您的终端中运行 `claude plugin uninstall claude-security`。

95 101

96在大型存储库上，一次扫描一个区域而不是整个树。选择插件提供的聚焦范围之一，例如您的 API 层或您的身份验证代码，运行会根据您选择的内容调整大小。报告的覆盖部分说明了什么被检查了，什么没有。随时在不同区域运行另一次扫描。102在大型存储库上，一次扫描一个区域而不是整个树。选择插件提供的聚焦范围之一，例如您的 API 层或您的身份验证代码，运行会根据您选择的内容调整大小。报告的覆盖部分说明了什么被检查了，什么没有。随时在不同区域运行另一次扫描。

97 103

104### 选择扫描工作量

105

106扫描工作量决定扫描的深度。在 `low`、`medium` 和 `high` 下，您的发现都会经过相同的独立验证。

107

108* **`low`**：快速初步检查。扫描代码库时，它会跳过架构图和威胁模型。

109* **`medium`**：默认值。

110* **`high`**：执行 `medium` 的所有工作，并在同一代码中进一步搜寻漏洞。

111

112在 Claude Code 输入框中的请求里指明扫描工作量，例如 `/claude-security scan my public API code at high` 或 `/claude-security scan my branch at high`。

113

114如果对大型仓库的扫描发现的问题少于预期，请选择 `high` 扫描工作量、再扫描一次，或两者都做。每种方式都可能报告出一次 `medium` 扫描未发现的问题。

115

98### 阅读扫描结果116### 阅读扫描结果

99 117

100每次扫描都会将其结果写入您的存储库中的时间戳 `CLAUDE-SECURITY-<timestamp>/` 目录：118每次扫描都会将其结果写入您的存储库中的时间戳 `CLAUDE-SECURITY-<timestamp>/` 目录：

102* **`CLAUDE-SECURITY-RESULTS.md`**：报告，包含每个发现的 ID，例如 `F1`，加上其影响、利用场景、严重性、置信度和建议120* **`CLAUDE-SECURITY-RESULTS.md`**：报告，包含每个发现的 ID，例如 `F1`，加上其影响、利用场景、严重性、置信度和建议

103* **`CLAUDE-SECURITY-RESULTS.jsonl`**：相同的发现以机器可读的形式，每行一个 JSON 对象121* **`CLAUDE-SECURITY-RESULTS.jsonl`**：相同的发现以机器可读的形式，每行一个 JSON 对象

104* **`CLAUDE-SECURITY-RESULTS.sarif`**：相同的发现作为 [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) 日志，用于 GitHub 代码扫描和任何其他读取该标准的工具。扫描将发现分类在其 [CWE](https://cwe.mitre.org/) 弱点类别下122* **`CLAUDE-SECURITY-RESULTS.sarif`**：相同的发现作为 [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) 日志，用于 GitHub 代码扫描和任何其他读取该标准的工具。扫描将发现分类在其 [CWE](https://cwe.mitre.org/) 弱点类别下

105* **`CLAUDE-SECURITY-REVISION-<commit>.json`**：修订戳，记录扫描了哪个提交、以什么工作量、未提交的更改是否是扫描树的一部分，以及运行的验证程度如何，因此报告始终与它描述的代码相关联。版本控制外的扫描在提交位置戳上 `UNVERSIONED`123* **`CLAUDE-SECURITY-REVISION-<commit>.json`**：修订戳，记录扫描了哪个提交、以什么[扫描工作量](#choose-a-scan-effort)、未提交的更改是否是扫描树的一部分，以及运行的验证程度如何，因此报告始终与它描述的代码相关联。版本控制外的扫描在提交位置戳上 `UNVERSIONED`

106 124

107该目录是扫描对您的检出所做的唯一更改，它有自己的 `.gitignore`，因此随意的 `git add` 永远不会将报告扫入提交。要在历史中保留报告以供审计跟踪，删除那一个 `.gitignore` 文件并像任何其他文件一样提交目录。125该目录是扫描对您的检出所做的唯一更改，它有自己的 `.gitignore`，因此随意的 `git add` 永远不会将报告扫入提交。要在历史中保留报告以供审计跟踪，删除那一个 `.gitignore` 文件并像任何其他文件一样提交目录。

108 126

desktop.md +64 −0

Details

994* **Shell**：远程计算机上为您的账户设置的 shell 必须能运行通过 SSH 发送的命令，Bash、Zsh 和 `sh` 均可994* **Shell**：远程计算机上为您的账户设置的 shell 必须能运行通过 SSH 发送的命令，Bash、Zsh 和 `sh` 均可

995* **网络**：Claude Code 在远程计算机上运行，并从那里发出网络请求，因此该计算机需要具备 [Claude Code 所需的网络访问](https://code.claude.com/docs/zh-CN/network-config.md#network-access-requirements)。如果该计算机无法下载 Claude Code，Desktop 会在您的计算机上下载并上传它。Claude Code 的其他请求仍从远程计算机发出。在 Linux 远程计算机上，如果这些请求需要代理，请[为 SSH 会话设置代理](#set-a-proxy-or-a-ca-certificate-for-ssh-sessions)。995* **网络**：Claude Code 在远程计算机上运行，并从那里发出网络请求，因此该计算机需要具备 [Claude Code 所需的网络访问](https://code.claude.com/docs/zh-CN/network-config.md#network-access-requirements)。如果该计算机无法下载 Claude Code，Desktop 会在您的计算机上下载并上传它。Claude Code 的其他请求仍从远程计算机发出。在 Linux 远程计算机上，如果这些请求需要代理，请[为 SSH 会话设置代理](#set-a-proxy-or-a-ca-certificate-for-ssh-sessions)。

996 996

997#### 检查远程机器的主机密钥

998

999主机密钥是远程机器出示的、用于证明自身身份的密钥，而指纹是该密钥的简短形式。当您信任某个密钥时，您的计算机会保存它，之后连接到出示该密钥的任何机器时都不会再询问。请在信任密钥之前先检查它，因为可能有其他方在拦截连接。

1000

1001首先，根据您看到指纹的位置，确定该密钥属于哪台机器：

1002

1003* **Desktop 询问 `Connect to <host> for the first time?`，或者您选择了 Review new key**：Desktop 指明的机器，即 `<host>`

1004* **Desktop 询问 `Connect through <jump host> for the first time?`**：跳板机，即您的连接所经过的机器，而不是您想要访问的机器

1005* **`ssh` 在终端中询问或发出警告**：其消息中指明的机器，这可能不是您输入的那台

1006

1007从该机器本身获取其指纹，而不是通过您正在检查的连接获取：

1008

1009* **该机器由他人管理**：向对方索取其主机密钥指纹

1010* **由您管理，且运行 Linux 或 macOS**：在该机器的控制台上，或通过您已信任的连接，在该机器上运行 `ssh-keygen -lf /etc/ssh/ssh_host_<type>_key.pub`。对于 `<type>`，请使用 Desktop 或 `ssh` 在指纹旁显示的密钥类型的小写形式：`ED25519` 或 `ssh-ed25519` 对应 `ed25519`。

1011

1012然后将该机器本身的指纹与您看到的指纹进行比较：

1013

1014* **两者一致**：信任该密钥。在 Desktop 中选择 **Trust and connect** 或 **Trust new key**，或在终端中回答 `yes`。

1015* **两者不一致，或者您无法检查**：不要连接。在 Desktop 中选择 **Cancel**，或在终端中回答 `no`。如果该机器由他人管理，请告知对方您看到的指纹。

1016

1017如果您是从某个故障排除步骤跳转到此处的，无论结果如何，请返回该步骤。

1018

997#### 为 SSH 会话设置代理或 CA 证书1019#### 为 SSH 会话设置代理或 CA 证书

998 1020

999如果 Linux 远程计算机通过代理访问互联网或需要 CA 证书，请在该计算机上的 `~/.claude/settings.json` 中的 `env` 下添加[代理和 CA 变量](https://code.claude.com/docs/zh-CN/network-config.md)。即使您已在该计算机上的 `~/.profile`、`~/.bash_profile`、`~/.zprofile` 或 `~/.zshrc` 中导出它们，也要添加。1021如果 Linux 远程计算机通过代理访问互联网或需要 CA 证书，请在该计算机上的 `~/.claude/settings.json` 中的 `env` 下添加[代理和 CA 变量](https://code.claude.com/docs/zh-CN/network-config.md)。即使您已在该计算机上的 `~/.profile`、`~/.bash_profile`、`~/.zprofile` 或 `~/.zshrc` 中导出它们，也要添加。

2135 2157

2136如果 MCP server 切换不响应或服务器在 Windows 上连接失败，检查服务器在你的设置中是否正确配置，重启应用，验证服务器进程在任务管理器中运行，并查看服务器日志以获取连接错误。2158如果 MCP server 切换不响应或服务器在 Windows 上连接失败，检查服务器在你的设置中是否正确配置，重启应用，验证服务器进程在任务管理器中运行，并查看服务器日志以获取连接错误。

2137 2159

2160### SSH host key verification failed

2161

2162以下每条消息都表示 Desktop 拒绝了某个[主机密钥](#check-a-remote-machines-host-key)：

2163

2164* 在 `Couldn't connect to <host>` 卡片的 **View details** 下出现 `SSH host key verification failed` 或 `Host denied (verification failed)`

2165* 在输入框旁边或执行 **Test connection** 后出现 `Connection failed: Host key changed or not trusted`

2166* 在已断开的会话上出现 `<host>'s host key is not trusted` 或 `<host>'s host key has changed`

2167

2168Desktop 拒绝密钥，通常是因为它与您计算机上保存的密钥不同，或者没有为该机器保存任何密钥。重建或重新安装过的机器通常会提供新的密钥，拦截连接的程序也会如此。再次连接之前，请先检查密钥，并从 Desktop 随消息显示的内容入手：

2169

2170* **您使用的是 Windows，且 Desktop 显示 `Connection failed: Host key changed or not trusted`**：首先排除[缺少 OpenSSH 客户端](#ssh-host-key-refused-on-windows-without-an-openssh-client)的情况

2171* **Desktop 提示您设置 `UserKnownHostsFile`**：在 `~/.ssh/config` 中将其设置为 `~/.ssh/known_hosts`，然后[从终端检查密钥](#check-the-host-key-from-a-terminal)

2172* **您看到 Review new key 按钮**：选择该按钮，并将 Desktop 显示的指纹与该机器自身的指纹进行[比较](#check-a-remote-machines-host-key)。如果两者匹配，请选择 **Trust new key** 以替换已保存的密钥。否则请选择 **Cancel**。

2173* **您没有看到 Review new key 按钮、Desktop 显示 `Couldn't show the new key`，或者在 Trust new key 之后 Desktop 再次拒绝密钥**：[从终端检查密钥](#check-the-host-key-from-a-terminal)

2174

2175#### 从终端检查主机密钥

2176

2177在您的计算机上运行 `ssh <SSH host>`，使用 Desktop 中您的 [SSH 连接](#ssh-sessions)的 **SSH host** 值。如果该连接有 **SSH port** 值，请添加 `-p <SSH port>`。在 Windows 上，请使用 PowerShell，因为 Desktop 不会使用 Git Bash 或 WSL 中的 `ssh` 进行连接。如果 PowerShell 找不到 `ssh`，请[安装 Microsoft 的 OpenSSH 客户端](#ssh-host-key-refused-on-windows-without-an-openssh-client)。

2178

2179留意 `ssh` 在其消息中提到的是哪台机器，它可能是跳板主机而不是 `<SSH host>`，然后按照适用的情况操作：

2180

2181* **`ssh` 询问是否继续连接**：将其显示的指纹与该机器自身的指纹进行[比较](#check-a-remote-machines-host-key)。仅当两者匹配时才回答 `yes`。

2182* **`ssh` 警告主机密钥已更改**：将警告中的指纹与该机器自身的指纹进行[比较](#check-a-remote-machines-host-key)。仅当两者匹配时，才删除 `Offending <type> key in <file>:<line>` 所指出的那一行，然后重新运行 `ssh`。如果 `ssh` 再次就另一行发出警告，请按照同样的方式比较、删除并重新运行。

2183* **`ssh` 未经询问就拒绝了它不认识的密钥**：从该机器的管理人员处获取该机器的 `known_hosts` 行，不要通过您正在检查的连接获取。将该行添加到您的 `known_hosts` 文件中，并使用 `ssh` 消息中的名称作为其主机名，然后重新运行 `ssh`。

2184* **`ssh` 没有询问主机密钥就继续登录**：先不要输入密码。[检查 `ssh` 已信任的密钥](#check-the-keys-that-ssh-already-trusts)。

2185

2186一旦 `ssh` 接受了您检查过或添加的密钥，请在 Desktop 中重试。如果 Desktop 再次拒绝该密钥，请参阅[获取 SSH 问题的 Desktop 日志](#get-desktops-logs-for-an-ssh-problem)。

2187

2188##### 检查 `ssh` 已信任的密钥

2189

2190添加 `-v -S none` 后重新运行相同的 `ssh` 命令。在其输出中，`Server host key:` 行会显示一个指纹，紧随其后的 `Host '<name>' is known` 行会指出该指纹所属的机器。将您找到的每个指纹与对应机器自身的指纹进行[比较](#check-a-remote-machines-host-key)。

2191

2192* **跳板主机没有 `Server host key:` 行**：同时运行 `ssh -v -S none <jump host>`，并以同样的方式比较该指纹。

2193* **某个指纹不匹配，或者您无法检查它**：不要再次连接。删除已保存的密钥：在 `Host '<name>' is known` 下方，`Found key in <file>:<line>` 行指出了保存该密钥的文件。运行 `ssh-keygen -R "<name>" -f <file>`。如果您将主机密钥保存在多个文件中，请从每个文件中删除该密钥。如果您无法修改某个文件，请告知您计算机的管理人员。

2194* **所有指纹都匹配**：在 Desktop 中重试。如果 Desktop 再次拒绝该密钥，请参阅[获取 SSH 问题的 Desktop 日志](#get-desktops-logs-for-an-ssh-problem)。

2195

2196### 在没有 OpenSSH 客户端的 Windows 上 SSH 主机密钥被拒绝

2197

2198在没有 OpenSSH 客户端的 Windows 上，Desktop 即使面对正确的主机密钥也会拒绝，并显示 `Connection failed: Host key changed or not trusted`。它需要该客户端来查找已保存的密钥。要确认您是否已安装该客户端，请在 PowerShell 中运行 `ssh`。如果 PowerShell 无法识别 `ssh`，请安装 [Microsoft 的 OpenSSH 客户端](https://learn.microsoft.com/windows-server/administration/openssh/openssh_install_firstuse)并重启 Desktop。

2199

2200然后再次连接。如果 Desktop 询问是否首次连接，请在信任之前先[检查该机器的主机密钥](#check-a-remote-machines-host-key)。如果 Desktop 仍然拒绝该密钥，请按照 [SSH host key verification failed](#ssh-host-key-verification-failed) 下的其他情况操作。

2201

2138### 登录后 SSH 连接失败2202### 登录后 SSH 连接失败

2139 2203

2140在下表中找到卡片的标题或错误消息末尾的代码，然后按照最后一列的说明操作。要查看消息，请在失败卡片上选择 **View details**。2204在下表中找到卡片的标题或错误消息末尾的代码，然后按照最后一列的说明操作。要查看消息，请在失败卡片上选择 **View details**。

env-vars.md +2 −2

Details

236| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 设置为 `1` 可从 Bash、PowerShell 和子代理工具中移除 `run_in_background` 参数，并关闭 Ctrl+B 快捷键以及 [fork 的 skill](https://code.claude.com/docs/zh-CN/skills.md#run-skills-in-a-subagent) 的后台运行。此后 Claude Code 也不再自动将子代理、长 MCP 工具调用和超时的 shell 命令移至后台。[MCP 任务](https://code.claude.com/docs/zh-CN/mcp.md#make-claude-wait-for-the-result-of-an-mcp-task)和 [Monitor 工具](https://code.claude.com/docs/zh-CN/tools-reference.md#monitor-tool)仍在后台运行 |236| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 设置为 `1` 可从 Bash、PowerShell 和子代理工具中移除 `run_in_background` 参数，并关闭 Ctrl+B 快捷键以及 [fork 的 skill](https://code.claude.com/docs/zh-CN/skills.md#run-skills-in-a-subagent) 的后台运行。此后 Claude Code 也不再自动将子代理、长 MCP 工具调用和超时的 shell 命令移至后台。[MCP 任务](https://code.claude.com/docs/zh-CN/mcp.md#make-claude-wait-for-the-result-of-an-mcp-task)和 [Monitor 工具](https://code.claude.com/docs/zh-CN/tools-reference.md#monitor-tool)仍在后台运行 |

237| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | 设置为 `1` 可阻止 Claude Code 将缺少 `Content-Type` 标头或该标头为空的 [Amazon Bedrock](https://code.claude.com/docs/zh-CN/amazon-bedrock.md) 流式响应视为 Amazon Bedrock 的二进制事件流。默认情况下，Claude Code 假定网关从一个未经其他修改的响应中丢弃了该标头，因此会解码响应体，流式传输得以继续工作。仅当网关还会将流重新作为服务器发送事件输出时才设置此变量；Claude Code 随后会将没有该标头的响应体作为服务器发送事件读取。需要 Claude Code v2.1.239 或更高版本 |237| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | 设置为 `1` 可阻止 Claude Code 将缺少 `Content-Type` 标头或该标头为空的 [Amazon Bedrock](https://code.claude.com/docs/zh-CN/amazon-bedrock.md) 流式响应视为 Amazon Bedrock 的二进制事件流。默认情况下，Claude Code 假定网关从一个未经其他修改的响应中丢弃了该标头，因此会解码响应体，流式传输得以继续工作。仅当网关还会将流重新作为服务器发送事件输出时才设置此变量；Claude Code 随后会将没有该标头的响应体作为服务器发送事件读取。需要 Claude Code v2.1.239 或更高版本 |

238| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 设置为 `1` 可跳过对 [Amazon Bedrock](https://code.claude.com/docs/zh-CN/amazon-bedrock.md) 流式响应是否带有 `application/vnd.amazon.eventstream` content-type 的检查。未设置此变量时，如果响应带有不同的 content-type，Claude Code 会使请求失败，并显示指明该类型的错误，这表示[网关或代理正在转换响应](https://code.claude.com/docs/zh-CN/amazon-bedrock.md#streaming-errors-behind-a-gateway-or-proxy)。请配置网关以原样转发 `Content-Type` 标头和响应体，而不是设置此变量。需要 Claude Code v2.1.208 或更高版本 |238| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 设置为 `1` 可跳过对 [Amazon Bedrock](https://code.claude.com/docs/zh-CN/amazon-bedrock.md) 流式响应是否带有 `application/vnd.amazon.eventstream` content-type 的检查。未设置此变量时，如果响应带有不同的 content-type，Claude Code 会使请求失败，并显示指明该类型的错误，这表示[网关或代理正在转换响应](https://code.claude.com/docs/zh-CN/amazon-bedrock.md#streaming-errors-behind-a-gateway-or-proxy)。请配置网关以原样转发 `Content-Type` 标头和响应体，而不是设置此变量。需要 Claude Code v2.1.208 或更高版本 |

239| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 设置为 `1` 可在[监督进程](https://code.claude.com/docs/zh-CN/agent-view.md#the-supervisor-process)停止、重启或更新[后台会话](https://code.claude.com/docs/zh-CN/agent-view.md)的进程时停止该会话正在进行的工作，而不是将其移交给该会话的下一个进程。这些工作包括会话中正在运行的后台 shell 命令和动态工作流，从 v2.1.198 起还包括后台子代理。仅影响该移交：使用 `←` 或 [`/background`](https://code.claude.com/docs/zh-CN/agent-view#from-inside-a-session) 将会话转入后台时，仍会转移正在进行的后台工作。需要 Claude Code v2.1.196 或更高版本 |239| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 设置为 `1` 可在[监督进程](https://code.claude.com/docs/zh-CN/agent-view.md#the-supervisor-process)停止、重启或更新某个[后台会话](https://code.claude.com/docs/zh-CN/agent-view.md)的进程时，停止该会话正在进行的工作，而不是将其移交给该会话的下一个进程。这些工作是该会话正在运行的后台 shell 命令，自 v2.1.198 起还包括后台子代理。仅影响该移交：使用 `←` 或 [`/background`](https://code.claude.com/docs/zh-CN/agent-view#from-inside-a-session) 将会话转入后台时，仍会将正在进行的后台工作延续过去。需要 Claude Code v2.1.196 或更高版本 |

240| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 设置为 `1` 可阻止 Claude Code 在内存压力下终止[后台 shell 命令](https://code.claude.com/docs/zh-CN/interactive-mode.md#background-bash-commands)。默认情况下，在 macOS 和 Linux 上，当操作系统报告严重内存压力，且会话已空闲 30 分钟、没有轮次或子代理在运行时，Claude Code 会终止后台 shell。Windows 没有内存压力信号，因此此变量在 Windows 上不起作用。需要 Claude Code v2.1.193 或更高版本 |240| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 设置为 `1` 可阻止 Claude Code 在内存压力下终止[后台 shell 命令](https://code.claude.com/docs/zh-CN/interactive-mode.md#background-bash-commands)。默认情况下，在 macOS 和 Linux 上，当操作系统报告严重内存压力，且会话已空闲 30 分钟、没有轮次或子代理在运行时，Claude Code 会终止后台 shell。Windows 没有内存压力信号，因此此变量在 Windows 上不起作用。需要 Claude Code v2.1.193 或更高版本 |

241| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 设置为 `1` 可禁用 Claude Code 随附的 [skill](https://code.claude.com/docs/zh-CN/skills.md) 和工作流：随附 skill 和工作流会被完全移除，而 `/init` 等内置命令仍可输入，但会对模型隐藏。`/doctor` 与内置命令一样仍可输入；请改用 `DISABLE_DOCTOR_COMMAND` 将其隐藏。来自插件、`.claude/skills/` 和 `.claude/commands/` 的 skill 不受影响。等同于 [`disableBundledSkills`](https://code.claude.com/docs/zh-CN/settings-reference#disablebundledskills) 设置 |241| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 设置为 `1` 可禁用 Claude Code 随附的 [skill](https://code.claude.com/docs/zh-CN/skills.md) 和工作流：随附 skill 和工作流会被完全移除，而 `/init` 等内置命令仍可输入，但会对模型隐藏。`/doctor` 与内置命令一样仍可输入；请改用 `DISABLE_DOCTOR_COMMAND` 将其隐藏。来自插件、`.claude/skills/` 和 `.claude/commands/` 的 skill 不受影响。等同于 [`disableBundledSkills`](https://code.claude.com/docs/zh-CN/settings-reference#disablebundledskills) 设置 |

242| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 设置为 `1` 可保留 [Claude in Chrome](https://code.claude.com/docs/zh-CN/chrome.md) 浏览器工具可用，同时省略系统提示词中的 Chrome 部分以及 `/claude-in-chrome` [随附 skill](https://code.claude.com/docs/zh-CN/skills.md#bundled-skills)。适用于嵌入 Claude Code 并提供自己的浏览器指导的宿主。需要 Claude Code v2.1.257 或更高版本 |242| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 设置为 `1` 可保留 [Claude in Chrome](https://code.claude.com/docs/zh-CN/chrome.md) 浏览器工具可用，同时省略系统提示词中的 Chrome 部分以及 `/claude-in-chrome` [随附 skill](https://code.claude.com/docs/zh-CN/skills.md#bundled-skills)。适用于嵌入 Claude Code 并提供自己的浏览器指导的宿主。需要 Claude Code v2.1.257 或更高版本 |

244| `CLAUDE_CODE_DISABLE_CRON` | 设置为 `1` 可禁用[会话范围的定时任务](https://code.claude.com/docs/zh-CN/scheduled-tasks.md)。`/loop` skill 和 cron 工具将不可用，所有已安排的任务都会停止触发，包括会话中途已在运行的任务 |244| `CLAUDE_CODE_DISABLE_CRON` | 设置为 `1` 可禁用[会话范围的定时任务](https://code.claude.com/docs/zh-CN/scheduled-tasks.md)。`/loop` skill 和 cron 工具将不可用，所有已安排的任务都会停止触发，包括会话中途已在运行的任务 |

245| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | 设置为 `1` 可关闭[关键路径删除](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)提示的时间限制。随后在 `auto` 模式下，Claude Code 会改为将这些删除操作发送给分类器；在 `bypassPermissions` 模式下，提示会等待您的回答。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置 `env` 块传递的副本。需要 Claude Code v2.1.281 或更高版本 |245| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | 设为 `1` 可关闭 `auto` 和 `bypassPermissions` 模式下针对关键路径删除操作的[时间限制和拒绝](https://code.claude.com/docs/zh-CN/permission-modes.md#time-limits-and-denials-in-auto-and-bypasspermissions-modes)。这些删除操作随后在 `auto` 模式下交由分类器处理，在 `bypassPermissions` 模式下，只要 Claude Code 能够显示提示，就会显示不限时的提示。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置 `env` 块传递的副本。需要 Claude Code v2.1.281 或更高版本 |

246| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 设置为 `1` 可从 API 请求中移除预发布的 `anthropic-beta` 请求标头、与其配对的请求体字段，以及 `defer_loading` 和 `eager_input_streaming` 等 beta 工具架构字段。当代理网关因 `anthropic-beta` 标头返回 `Unexpected value(s)` 错误或返回 `Extra inputs are not permitted` 错误而拒绝请求时使用。[禁用预发布功能](https://code.claude.com/docs/zh-CN/llm-gateway-protocol.md#disable-pre-release-capabilities)列出了该变量移除的内容（包括 [MCP 工具搜索](https://code.claude.com/docs/zh-CN/mcp.md#scale-with-mcp-tool-search)）以及 Claude Code 仍会发送的内容 |246| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 设置为 `1` 可从 API 请求中移除预发布的 `anthropic-beta` 请求标头、与其配对的请求体字段，以及 `defer_loading` 和 `eager_input_streaming` 等 beta 工具架构字段。当代理网关因 `anthropic-beta` 标头返回 `Unexpected value(s)` 错误或返回 `Extra inputs are not permitted` 错误而拒绝请求时使用。[禁用预发布功能](https://code.claude.com/docs/zh-CN/llm-gateway-protocol.md#disable-pre-release-capabilities)列出了该变量移除的内容（包括 [MCP 工具搜索](https://code.claude.com/docs/zh-CN/mcp.md#scale-with-mcp-tool-search)）以及 Claude Code 仍会发送的内容 |

247| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 设置为 `1` 可禁用内置的 [Explore 和 Plan 子代理](https://code.claude.com/docs/zh-CN/sub-agents.md#built-in-subagents)。Claude 会改用其搜索工具或 general-purpose 子代理进行探索，[计划模式](https://code.claude.com/docs/zh-CN/permission-modes.md#analyze-before-you-edit-with-plan-mode)会直接读取文件，而不是启动 Explore 和 Plan Agent。名为 `Explore` 或 `Plan` 的自定义子代理不受影响。若要在 Agent SDK 或非交互模式下移除所有内置子代理类型，请改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更高版本 |247| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 设置为 `1` 可禁用内置的 [Explore 和 Plan 子代理](https://code.claude.com/docs/zh-CN/sub-agents.md#built-in-subagents)。Claude 会改用其搜索工具或 general-purpose 子代理进行探索，[计划模式](https://code.claude.com/docs/zh-CN/permission-modes.md#analyze-before-you-edit-with-plan-mode)会直接读取文件，而不是启动 Explore 和 Plan Agent。名为 `Explore` 或 `Plan` 的自定义子代理不受影响。若要在 Agent SDK 或非交互模式下移除所有内置子代理类型，请改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更高版本 |

errors.md +37 −5

Details

245| `MCP server "<name>" may not have been saved` / `may not have been removed` | [命令行错误](#mcp-server-may-not-have-been-saved-or-removed) |245| `MCP server "<name>" may not have been saved` / `may not have been removed` | [命令行错误](#mcp-server-may-not-have-been-saved-or-removed) |

246| `Server rejected the Authorization header minted by the configured headersHelper` | [命令行错误](#server-rejected-the-authorization-header-minted-by-the-configured-headershelper) |246| `Server rejected the Authorization header minted by the configured headersHelper` | [命令行错误](#server-rejected-the-authorization-header-minted-by-the-configured-headershelper) |

247| `This server (Java MCP SDK 0.17.0 or older) rejected Claude Code's elicitation capability` | [命令行错误](#mcp-server-rejected-the-elicitation-capability) |

247| `Error: MCP tool <name> (passed via --permission-prompt-tool) not found` | [命令行错误](#mcp-permission-prompt-tool-not-found) |248| `Error: MCP tool <name> (passed via --permission-prompt-tool) not found` | [命令行错误](#mcp-permission-prompt-tool-not-found) |

248| `OAuth callback port <port> is already in use — another process may be holding it` | [命令行错误](#oauth-callback-port-is-already-in-use) |249| `OAuth callback port <port> is already in use — another process may be holding it` | [命令行错误](#oauth-callback-port-is-already-in-use) |

3280* **`Error: Workspace not trusted. <folder> is your home directory`**：由于主目录的信任从不保存，先在那里运行 `claude` 也无济于事。请改为在项目目录中运行 `claude ultrareview`（先在那里运行一次 `claude` 以接受信任对话框），或追加 `--trust-workspace`。3281* **`Error: Workspace not trusted. <folder> is your home directory`**：由于主目录的信任从不保存，先在那里运行 `claude` 也无济于事。请改为在项目目录中运行 `claude ultrareview`（先在那里运行一次 `claude` 以接受信任对话框），或追加 `--trust-workspace`。

3281* **`No answer in time.` 后跟 `Error: Workspace not trusted`**：`Trust <folder>? [y/N]` 问题在 5 分钟内未得到回答。再次运行 `claude ultrareview` 并回答该问题。3282* **`No answer in time.` 后跟 `Error: Workspace not trusted`**：`Trust <folder>? [y/N]` 问题在 5 分钟内未得到回答。再次运行 `claude ultrareview` 并回答该问题。

3282* **`Ultrareview did not start: <folder> is not trusted`**：您在 `Trust <folder>? [y/N]` 问题处拒绝了，例如回答 `n` 或按 Enter。若要开始审查，请再次运行 `claude ultrareview` 并回答 `y`。3283* **`Ultrareview did not start: <folder> is not trusted`**：您在 `Trust <folder>? [y/N]` 问题处拒绝了，例如回答 `n` 或按 Enter。若要开始审查，请再次运行 `claude ultrareview` 并回答 `y`。

3283* **``Ultrareview did not start: `--trust-workspace` takes no value``**：`--trust-workspace` 后面跟着的不是标志，例如 PR 编号或 `false`。如果您不信任该文件夹，请省略该标志。若要在此次运行中信任它，请将 PR 编号或基础分支放在标志之前：`claude ultrareview 1234 --trust-workspace`。3284* **``Ultrareview did not start: `--trust-workspace` takes no value``**：`--trust-workspace` 后面跟了非标志的内容，例如 PR 编号或 `false`。如果您不信任该文件夹，请省略此标志。若要在本次运行中信任它，请将 PR 编号或基础分支放在标志之前：`claude ultrareview 1234 --trust-workspace`。

3284 3285

3285在 v2.1.309 之前，`claude ultrareview` 不接受 `--trust-workspace`。3286在 v2.1.309 之前，`claude ultrareview` 不接受 `--trust-workspace`。

3286 3287

3473 3474

3474在 v2.1.248 之前，对于由辅助程序提供 `Authorization` 标头的服务器，Claude Code 会运行 OAuth 发现。该发现过程可能以 `Incompatible auth server: does not support dynamic client registration` 失败，而不是报告被拒绝的凭据。3475在 v2.1.248 之前，对于由辅助程序提供 `Authorization` 标头的服务器，Claude Code 会运行 OAuth 发现。该发现过程可能以 `Incompatible auth server: does not support dynamic client registration` 失败，而不是报告被拒绝的凭据。

3475 3476

3477### MCP server rejected the elicitation capability

3478

3479基于 Java MCP SDK 0.11.0 至 0.17.0 构建的 MCP 服务器拒绝了连接。这些 SDK 版本无法解析 Claude Code 在握手中声明的 `form` 和 `url` [elicitation 模式](https://code.claude.com/docs/zh-CN/mcp.md#elicitation-modes-claude-code-declares)。`claude mcp list` 会将该服务器显示为失败，并以此消息代替服务器自身的错误：

3480

3481```text theme={null}

3482This server (Java MCP SDK 0.17.0 or older) rejected Claude Code's elicitation capability. Set "bareElicitationCapability": true for it, or upgrade to Java MCP SDK 0.17.1+ (Spring AI 1.0.7+ or 1.1.6+).

3483```

3484

3485**解决方法：**

3486

3487* 将服务器升级到 Java MCP SDK 0.17.1 或更高版本，或升级到消息中列出的 Spring AI 版本之一

3488* 或者在 MCP 配置中为该服务器的条目添加 `"bareElicitationCapability": true`，然后重启 Claude Code。该字段可用于 stdio、`sse`、`http` 和 `ws` 条目，需要 Claude Code v2.1.281 或更高版本

3489

3490以下 `.mcp.json` 条目为一个 HTTP 服务器设置了该字段：

3491

3492```json theme={null}

3493{

3494 "mcpServers": {

3495 "inventory": {

3496 "type": "http",

3497 "url": "https://mcp.example.com/mcp",

3498 "bareElicitationCapability": true

3499 }

3500 }

3501}

3502```

3503

3504重启后，`/mcp` 会将该服务器显示为已连接。Claude Code 仅向该服务器声明 form 模式，因此在升级服务器后请移除此字段。

3505

3506服务器也可能以其自身的错误文本失败，例如包含 `Unrecognized field "form"` 的错误。解决方法相同。

3507

3476### 未找到 MCP 权限提示工具3508### 未找到 MCP 权限提示工具

3477 3509

3478当运行首次需要权限决策时，您传给 [`--permission-prompt-tool`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 的工具不在已连接的 MCP 工具之中，原因可能是其服务器从未连接，或者没有任何已连接的服务器公开该名称的工具。Claude Code 仍会发送您的提示词：[非交互](https://code.claude.com/docs/zh-CN/headless.md)运行会在第一次工具调用时以此错误和退出码 1 退出，因此即使请求已经发出，也不会产生回答。在第一个提示词之前，Claude Code 会等待该服务器连接，最长等待由 [`MCP_TIMEOUT`](https://code.claude.com/docs/zh-CN/env-vars) 设置的每服务器连接超时时间 30 秒。在 v2.1.206 之前，启动时不会等待服务器完成连接，因此启动较慢但运行正常的服务器也会产生此错误。3510当运行首次需要权限决策时，您传给 [`--permission-prompt-tool`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 的工具不在已连接的 MCP 工具之中，原因可能是其服务器从未连接，或者没有任何已连接的服务器公开该名称的工具。Claude Code 仍会发送您的提示词：[非交互](https://code.claude.com/docs/zh-CN/headless.md)运行会在第一次工具调用时以此错误和退出码 1 退出，因此即使请求已经发出，也不会产生回答。在第一个提示词之前，Claude Code 会等待该服务器连接，最长等待由 [`MCP_TIMEOUT`](https://code.claude.com/docs/zh-CN/env-vars) 设置的每服务器连接超时时间 30 秒。在 v2.1.206 之前，启动时不会等待服务器完成连接，因此启动较慢但运行正常的服务器也会产生此错误。

3541 3573

3542以下相关消息会在命令运行之前就出现：3574以下相关消息会在命令运行之前就出现：

3543 3575

3544* `Shell command permission check failed for pattern "..."`：该命令的权限检查不允许它运行。[对注入命令的权限检查](https://code.claude.com/docs/zh-CN/skills.md#permission-checks-on-injected-commands)介绍了在各权限模式下哪些结果会导致中止，以及如何使用 `allowed-tools` 预先批准命令3576* `Shell command permission check failed for pattern "..."`：该命令的权限检查未允许其运行。[注入命令的权限检查](https://code.claude.com/docs/zh-CN/skills.md#permission-checks-on-injected-commands)介绍了在每种权限模式下哪些结果会导致中止，以及如何使用 `allowed-tools` 预先批准命令

3545* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``：该 skill 的 frontmatter 要求使用 bash，但机器上没有 bash。请安装 Git for Windows，或将 frontmatter 更改为 `shell: powershell`。请参阅[注入命令的运行方式](https://code.claude.com/docs/zh-CN/skills.md#how-injected-commands-run)3577* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``：该 skill 的 frontmatter 要求在没有 bash 的机器上使用 bash。请安装 Git for Windows，或将 frontmatter 改为 `shell: powershell`。请参阅[注入命令的运行方式](https://code.claude.com/docs/zh-CN/skills.md#how-injected-commands-run)

3546* `No shell command in <name> was run`：文件中某个 `!` 命令包含除制表符或换行符之外的原始控制字符，因此所有命令都不会运行。请参阅[如何查找并移除该字符](#no-shell-command-was-run)3578* `No shell command in <name> was run`：该文件的某个 `!` 命令包含制表符或换行符以外的原始控制字符，因此所有命令都不会运行。请参阅[如何查找并删除该字符](#no-shell-command-was-run)

3547 3579

3548**解决方法：**3580**解决方法：**

3549 3581

3693 3725

3694* **您没有传入基础分支**：Claude Code 与仓库的默认分支进行了比较，并建议您显式传入基础分支，如上例所示3726* **您没有传入基础分支**：Claude Code 与仓库的默认分支进行了比较，并建议您显式传入基础分支，如上例所示

3695* **您传入的基础分支已存在于您的克隆中**：提示为 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``3727* **您传入的基础分支已存在于您的克隆中**：提示为 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``

3696* **您传入的基础分支不在您的克隆中**：Claude Code 在比较之前从 origin 获取了该分支。提示为 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``；当 Claude Code 无法判断您的克隆是否为浅克隆时，它会改为建议 `git fetch --unshallow origin`。在 v2.1.221 之前，对于每个获取的基础分支，提示都会建议 `git fetch --unshallow origin`，而在完整克隆上该命令会失败并报错 `fatal: --unshallow on a complete repository does not make sense`。3728* **您传入的基础分支不在您的克隆中**：Claude Code 在比较之前从 origin 获取了该分支。提示内容为 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``；当 Claude Code 无法判断您的克隆是否为浅克隆时，它会改为建议 `git fetch --unshallow origin`。在 v2.1.221 之前，对于每个获取的基础分支，提示都会建议 `git fetch --unshallow origin`，而在完整克隆上，该命令会失败并报错 `fatal: --unshallow on a complete repository does not make sense`。

3697 3729

3698**解决方法：**3730**解决方法：**

3699 3731

features-overview.md +1 −1

Details

303* CLAUDE.md 和 git 状态。内置的 Explore 和 Plan Agent [启动时两者都不包含](https://code.claude.com/docs/zh-CN/sub-agents.md#what-loads-at-startup)，而定义中设置了 [`omitClaudeMd`](https://code.claude.com/docs/zh-CN/sub-agents#supported-frontmatter-fields) 的 Agent 启动时不包含用户、项目和本地 CLAUDE.md 文件。303* CLAUDE.md 和 git 状态。内置的 Explore 和 Plan Agent [启动时两者都不包含](https://code.claude.com/docs/zh-CN/sub-agents.md#what-loads-at-startup)，而定义中设置了 [`omitClaudeMd`](https://code.claude.com/docs/zh-CN/sub-agents#supported-frontmatter-fields) 的 Agent 启动时不包含用户、项目和本地 CLAUDE.md 文件。

304* 主 Agent 在提示词中传递的任何上下文304* 主 Agent 在提示词中传递的任何上下文

305 305

306对于 [fork](https://code.claude.com/docs/zh-CN/sub-agents.md#fork-the-current-conversation)，Claude Code 加载父对话到目前为止、系统提示和工具。306对于 [fork](https://code.claude.com/docs/zh-CN/sub-agents.md#fork-the-current-conversation)，Claude Code 改为加载父对话到目前为止的内容、系统提示和工具。

307 307

308**上下文成本：** 与主会话隔离。308**上下文成本：** 与主会话隔离。

309 309

hooks.md +1 −1

Details

1957 1957

1958| 字段 | 说明 |1958| 字段 | 说明 |

1959| :- | :- |1959| :- | :- |

1960| `permissionDecision` | `"allow"` 会跳过权限提示，但[任何模式都不会自动批准的操作](https://code.claude.com/docs/zh-CN/permission-modes.md#actions-no-mode-auto-approves)和[从网络路径读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)除外。`AskUserQuestion` 和 `ExitPlanMode` 需要[与 `"allow"` 配对的 `updatedInput`](#allow-with-updatedinput)。关于计划模式，请参阅[计划模式中的 hook 批准](https://code.claude.com/docs/zh-CN/permissions.md#hook-approvals-in-plan-mode)。`"deny"` 会阻止工具调用。`"ask"` 会提示用户确认。`"defer"` 会结束当前轮次，以便稍后恢复该工具，并且需要使用 `-p` 标志的[非交互模式](#defer-a-tool-call-for-later)。无论 hook 返回什么，[拒绝和询问规则](https://code.claude.com/docs/zh-CN/permissions.md#manage-permissions)仍会被评估 |1960| `permissionDecision` | `"allow"` 会跳过权限提示，但[任何模式都不会自动批准的操作](https://code.claude.com/docs/zh-CN/permission-modes.md#actions-no-mode-auto-approves)和[从网络路径读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)除外。对于[Agent SDK 应用标记为 `always_ask` 的工具](https://code.claude.com/docs/zh-CN/agent-sdk/custom-tools#require-approval-for-specific-tools)的调用，它同样不会跳过批准，除非[权限模式批准该调用](https://code.claude.com/docs/zh-CN/agent-sdk/typescript.md#permission-modes-that-can-approve-an-always_ask-call)。`AskUserQuestion` 和 `ExitPlanMode` 需要[将 `updatedInput` 与 `"allow"` 搭配使用](#allow-with-updatedinput)。有关计划模式，请参阅[计划模式中的 hook 批准](https://code.claude.com/docs/zh-CN/permissions.md#hook-approvals-in-plan-mode)。`"deny"` 会阻止工具调用。`"ask"` 会提示用户确认。`"defer"` 会结束当前轮次，以便稍后恢复该工具，并且需要在使用 `-p` 标志的[非交互模式](#defer-a-tool-call-for-later)下运行。无论 hook 返回什么，[拒绝和询问规则](https://code.claude.com/docs/zh-CN/permissions.md#manage-permissions)仍会被评估 |

1961| `permissionDecisionReason` | 对于 `"ask"`，在权限提示中显示给用户。当 Claude Code 在无人能回应该提示的 `-p` 运行中[拒绝该调用](https://code.claude.com/docs/zh-CN/headless.md#turn-off-permission-prompts-in-unattended-runs)时，Claude 会在工具结果中读取该原因。对于 `"deny"`，显示给 Claude。对于 `"allow"` 和 `"defer"`，仅写入[调试日志](#debug-hooks) |1961| `permissionDecisionReason` | 对于 `"ask"`，在权限提示中显示给用户。当 Claude Code 在无人能回应该提示的 `-p` 运行中[拒绝该调用](https://code.claude.com/docs/zh-CN/headless.md#turn-off-permission-prompts-in-unattended-runs)时，Claude 会在工具结果中读取该原因。对于 `"deny"`，显示给 Claude。对于 `"allow"` 和 `"defer"`，仅写入[调试日志](#debug-hooks) |

1962| `updatedInput` | 在执行前修改工具的输入参数。会替换整个输入对象，因此请将未更改的字段与修改后的字段一起包含。Claude Code 会针对您的 hook 返回的输入（而非 Claude 发送的输入）评估权限规则以及 Bash 命令的[自动转入后台资格](https://code.claude.com/docs/zh-CN/tools-reference.md#foreground-commands-that-move-to-the-background)。与 `"allow"` 结合可自动批准，与 `"ask"` 结合可向用户显示修改后的输入。对于 `"defer"`，会被忽略 |1962| `updatedInput` | 在执行前修改工具的输入参数。会替换整个输入对象，因此请将未更改的字段与修改后的字段一起包含。Claude Code 会针对您的 hook 返回的输入（而非 Claude 发送的输入）评估权限规则以及 Bash 命令的[自动转入后台资格](https://code.claude.com/docs/zh-CN/tools-reference.md#foreground-commands-that-move-to-the-background)。与 `"allow"` 结合可自动批准，与 `"ask"` 结合可向用户显示修改后的输入。对于 `"defer"`，会被忽略 |

1963| `additionalContext` | 与工具结果一起添加到 Claude 上下文中的字符串。当 `permissionDecision` 为 `"defer"` 时会被忽略。请参阅[为 Claude 添加上下文](#add-context-for-claude) |1963| `additionalContext` | 与工具结果一起添加到 Claude 上下文中的字符串。当 `permissionDecision` 为 `"defer"` 时会被忽略。请参阅[为 Claude 添加上下文](#add-context-for-claude) |

hooks-guide.md +2 −0

Details

629 629

630* 从 [网络路径](https://code.claude.com/docs/zh-CN/permissions.md#network-paths) 读取630* 从 [网络路径](https://code.claude.com/docs/zh-CN/permissions.md#network-paths) 读取

631* 标记为 [`requiresUserInteraction`](https://code.claude.com/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具631* 标记为 [`requiresUserInteraction`](https://code.claude.com/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具

632* 对 [Agent SDK 应用标记为 `always_ask` 的工具](https://code.claude.com/docs/zh-CN/agent-sdk/custom-tools#require-approval-for-specific-tools) 的调用，除非 [权限模式批准该调用](https://code.claude.com/docs/zh-CN/agent-sdk/typescript.md#permission-modes-that-can-approve-an-always_ask-call)

632* 在该设置到达 Claude Code 的会话中，[您的组织设置为 `ask`](https://code.claude.com/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的连接器工具633* 在该设置到达 Claude Code 的会话中，[您的组织设置为 `ask`](https://code.claude.com/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的连接器工具

633 634

634 有关 `"allow"` 在计划模式下的作用，请参阅 [计划模式下的 hook 批准](https://code.claude.com/docs/zh-CN/permissions.md#hook-approvals-in-plan-mode)。635 有关 `"allow"` 在计划模式下的作用，请参阅 [计划模式下的 hook 批准](https://code.claude.com/docs/zh-CN/permissions.md#hook-approvals-in-plan-mode)。

963* **对 `"allow"` 仍然有效的限制**：返回 `"allow"` 的 hook 不会绕过设置中的拒绝规则，并且在以下情况下也无法抑制提示：964* **对 `"allow"` 仍然有效的限制**：返回 `"allow"` 的 hook 不会绕过设置中的拒绝规则，并且在以下情况下也无法抑制提示：

964 * 从[网络路径](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)读取965 * 从[网络路径](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)读取

965 * 标记为 [`requiresUserInteraction`](https://code.claude.com/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具966 * 标记为 [`requiresUserInteraction`](https://code.claude.com/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具

967 * 调用 [Agent SDK 应用标记为 `always_ask` 的工具](https://code.claude.com/docs/zh-CN/agent-sdk/custom-tools#require-approval-for-specific-tools)，除非[权限模式批准该调用](https://code.claude.com/docs/zh-CN/agent-sdk/typescript.md#permission-modes-that-can-approve-an-always_ask-call)

966 * 在该设置会传达到 Claude Code 的会话中，[您的组织设置为 `ask`](https://code.claude.com/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的连接器工具968 * 在该设置会传达到 Claude Code 的会话中，[您的组织设置为 `ask`](https://code.claude.com/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的连接器工具

967 969

968在[计划模式](https://code.claude.com/docs/zh-CN/permissions.md#hook-approvals-in-plan-mode)中，如果您的 `PreToolUse` hook 对文件编辑返回 `"allow"`，您得到的提示、阻止或批准与没有 hook 时该编辑所得到的相同。要解除对 hook 批准的这一限制，请[批准计划](https://code.claude.com/docs/zh-CN/permission-modes.md#review-and-approve-a-plan)或切换到其他权限模式。970在[计划模式](https://code.claude.com/docs/zh-CN/permissions.md#hook-approvals-in-plan-mode)中，如果您的 `PreToolUse` hook 对文件编辑返回 `"allow"`，您得到的提示、阻止或批准与没有 hook 时该编辑所得到的相同。要解除对 hook 批准的这一限制，请[批准计划](https://code.claude.com/docs/zh-CN/permission-modes.md#review-and-approve-a-plan)或切换到其他权限模式。

managed-settings.md +1 −1

Details

407| [`managedMcpServers`](https://code.claude.com/docs/zh-CN/settings-reference#managedmcpservers) | 提供给每个用户的远程 MCP 服务器，与他们自己的一起。它提供服务器而不是锁定任何东西。请参阅[通过托管设置提供服务器](https://code.claude.com/docs/zh-CN/managed-mcp.md#provide-servers-through-managed-settings)。需要 Claude Code v2.1.259 或更高版本 |407| [`managedMcpServers`](https://code.claude.com/docs/zh-CN/settings-reference#managedmcpservers) | 提供给每个用户的远程 MCP 服务器，与他们自己的一起。它提供服务器而不是锁定任何东西。请参阅[通过托管设置提供服务器](https://code.claude.com/docs/zh-CN/managed-mcp.md#provide-servers-through-managed-settings)。需要 Claude Code v2.1.259 或更高版本 |

408| [`managedSourcesBehavior`](https://code.claude.com/docs/zh-CN/settings-reference#managedsourcesbehavior) | Claude Code 是仅应用最高优先级托管源还是[组合它们中的每一个](#compose-every-managed-source) |408| [`managedSourcesBehavior`](https://code.claude.com/docs/zh-CN/settings-reference#managedsourcesbehavior) | Claude Code 是仅应用最高优先级托管源还是[组合它们中的每一个](#compose-every-managed-source) |

409| [`parentSettingsBehavior`](https://code.claude.com/docs/zh-CN/settings-reference#parentsettingsbehavior) | 主机提供的父设置是否在托管策略下合并 |409| [`parentSettingsBehavior`](https://code.claude.com/docs/zh-CN/settings-reference#parentsettingsbehavior) | 主机提供的父设置是否在托管策略下合并 |

410| [`pluginSuggestionMarketplaces`](https://code.claude.com/docs/zh-CN/settings-reference#pluginsuggestionmarketplaces) | Claude Code 可能向用户建议其插件的市场 |410| [`pluginSuggestionMarketplaces`](https://code.claude.com/docs/zh-CN/settings-reference#pluginsuggestionmarketplaces) | Claude Code 可以在终端中向用户建议其插件的市场 |

411| [`pluginTrustMessage`](https://code.claude.com/docs/zh-CN/settings-reference#plugintrustmessage) | 附加到安装前显示的插件信任警告的自定义消息 |411| [`pluginTrustMessage`](https://code.claude.com/docs/zh-CN/settings-reference#plugintrustmessage) | 附加到安装前显示的插件信任警告的自定义消息 |

412| [`policyHelper`](https://code.claude.com/docs/zh-CN/settings-reference#policyhelper) | 在启动时计算托管设置的可执行文件；请参阅[使用策略助手计算托管设置](https://code.claude.com/docs/zh-CN/settings-reference.md#policyhelper) |412| [`policyHelper`](https://code.claude.com/docs/zh-CN/settings-reference#policyhelper) | 在启动时计算托管设置的可执行文件；请参阅[使用策略助手计算托管设置](https://code.claude.com/docs/zh-CN/settings-reference.md#policyhelper) |

413| [`sandbox.filesystem.allowManagedReadPathsOnly`](https://code.claude.com/docs/zh-CN/settings-reference#sandbox-filesystem-allowmanagedreadpathsonly) | 当 `true` 时，仅尊重来自托管设置的 `filesystem.allowRead` 路径。`denyRead` 仍然从所有源合并 |413| [`sandbox.filesystem.allowManagedReadPathsOnly`](https://code.claude.com/docs/zh-CN/settings-reference#sandbox-filesystem-allowmanagedreadpathsonly) | 当 `true` 时，仅尊重来自托管设置的 `filesystem.allowRead` 路径。`denyRead` 仍然从所有源合并 |

mcp.md +10 −1

Details

1624 1624

1625如果你正在构建使用引出功能的 MCP 服务器，请参阅 [MCP 引出规范](https://modelcontextprotocol.io/docs/learn/client-concepts#elicitation) 了解协议详情和架构示例。1625如果你正在构建使用引出功能的 MCP 服务器，请参阅 [MCP 引出规范](https://modelcontextprotocol.io/docs/learn/client-concepts#elicitation) 了解协议详情和架构示例。

1626 1626

1627在使用 [protocol revision 2026-07-28](#mcp-client-runtimes) 的连接上，Claude Code 在其客户端功能中声明 `elicitation: {form: {}, url: {}}`，因此该处的服务器可以通过协议的标准引出请求来请求任一模式。1627### Claude Code 声明的引出模式

1628

1629如果您构建 MCP 服务器，Claude Code 在连接时发送的客户端功能会告知您的服务器可以请求哪些引出模式。Claude Code 在以下连接上声明 `elicitation: {form: {}, url: {}}`，因此其中任何连接上的服务器都可以请求这两种模式：

1630

1631* 使用 [protocol revision 2026-07-28](#mcp-client-runtimes) 的连接

1632* 在较早的协议修订版（2025-11-25 及更早版本）上，与用户 Claude Code MCP 配置中的 stdio、`sse`、`http` 和 `ws` 服务器建立的连接。需要 Claude Code v2.1.287 或更高版本

1633

1634在较早修订版上的其他连接中，例如与 [claude.ai 连接器](#use-mcp-servers-from-claude-ai)的连接，Claude Code 声明的是不带内容的 `elicitation: {}`，这仅允许表单模式的引出请求。

1635

1636基于 Java MCP SDK 0.17.0 或更早版本构建的服务器可能会拒绝包含 `form` 和 `url` 的声明。请参阅 [MCP server rejected the elicitation capability](https://code.claude.com/docs/zh-CN/errors.md#mcp-server-rejected-the-elicitation-capability)。

1628 1637

1629## 使用 MCP 资源1638## 使用 MCP 资源

1630 1639

permission-modes.md +48 −6

Details

36* 与显式 [询问规则](https://code.claude.com/docs/zh-CN/permissions.md#manage-permissions) 匹配的工具36* 与显式 [询问规则](https://code.claude.com/docs/zh-CN/permissions.md#manage-permissions) 匹配的工具

37* 您的组织 [设置为 `ask`](https://code.claude.com/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的连接器工具，在该设置到达 Claude Code 的会话中37* 您的组织 [设置为 `ask`](https://code.claude.com/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的连接器工具，在该设置到达 Claude Code 的会话中

38* 需要用户交互的工具：内置 `AskUserQuestion` 工具和标记为 [`requiresUserInteraction`](https://code.claude.com/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具38* 需要用户交互的工具：内置 `AskUserQuestion` 工具和标记为 [`requiresUserInteraction`](https://code.claude.com/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具

~~39* 可识别的 `rm` 和 `rmdir` [关键路径删除](#critical-paths)，任何允许规则或 `PreToolUse` hook `"allow"` 都无法批准~~39* 可识别的 `rm` 和 `rmdir` [关键路径删除](#critical-paths)，任何允许规则或 `PreToolUse` hook `"allow"` 都无法批准；以及被标记为 [`Dangerous rm operation not ruled out`](#dangerous-rm-operation-not-ruled-out) 的 Bash 命令

40* [跨会话消息传递保护措施](#skip-all-checks-with-bypasspermissions-mode)40* [跨会话消息传递保护措施](#skip-all-checks-with-bypasspermissions-mode)

41* 在 [`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/zh-CN/settings-reference#permissions-blockreadsoutsideworkingdirectories) 打开时在工作目录外读取：识别的文件读取 Bash 命令和任何需要批准才能在沙箱外运行的 [未沙箱化重试](https://code.claude.com/docs/zh-CN/sandboxing.md#the-unsandboxed-retry-escape-hatch)，即使在 auto 模式和 `bypassPermissions` 模式下也会提示。需要 Claude Code v2.1.257 或更高版本。41* 在 [`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/zh-CN/settings-reference#permissions-blockreadsoutsideworkingdirectories) 打开时在工作目录外读取：识别的文件读取 Bash 命令和任何需要批准才能在沙箱外运行的 [未沙箱化重试](https://code.claude.com/docs/zh-CN/sandboxing.md#the-unsandboxed-retry-escape-hatch)，即使在 auto 模式和 `bypassPermissions` 模式下也会提示。需要 Claude Code v2.1.257 或更高版本。

42 42

265 265

266`acceptEdits` 模式让 Claude 在您的工作目录中创建和编辑文件而无需提示。当此模式处于活动状态时，状态栏显示 `⏵⏵ accept edits on`。266`acceptEdits` 模式让 Claude 在您的工作目录中创建和编辑文件而无需提示。当此模式处于活动状态时，状态栏显示 `⏵⏵ accept edits on`。

267 267

268除了文件编辑外，`acceptEdits` 模式还自动批准常见的文件系统 Bash 命令：`mkdir`、`touch`、`rm`、`rmdir`、`mv`、`cp` 和 `sed`。当这些命令带有安全环境变量（如 `LANG=C` 或 `NO_COLOR=1`）或进程包装器（如 `timeout`、`nice` 或 `nohup`）作为前缀时，也会自动批准。与文件编辑一样，自动批准仅适用于工作目录或 `additionalDirectories` 内的路径。268除了文件编辑外，`acceptEdits` 模式还自动批准常见的文件系统 Bash 命令：`mkdir`、`touch`、`rm`、`rmdir`、`mv`、`cp` 和 `sed`。除 `touch` 外，当这些命令带有安全环境变量（如 `LANG=C` 或 `NO_COLOR=1`）或进程包装器（如 `timeout`、`nice` 或 `nohup`）作为前缀时，也会自动批准。与文件编辑一样，自动批准仅适用于工作目录或 `additionalDirectories` 内的路径。

269 269

270以下情况仍然会提示：270以下情况仍然会提示：

271 271

272* 超出该范围的路径272* 超出该范围的路径

273* 对[受保护路径](#protected-paths)的写入273* 对[受保护路径](#protected-paths)的写入

274* 可识别的 `rm` 和 `rmdir` [关键路径移除](#critical-paths)操作274* 可识别的 `rm` 和 `rmdir` [关键路径移除](#critical-paths)操作

275* `touch` 带有纯文件路径以外的任何内容，例如选项、glob，或 `timeout 5`、`LANG=C` 之类的前缀

275* 除[内置只读集合](https://code.claude.com/docs/zh-CN/permissions.md#read-only-commands)之外的所有其他 Bash 命令276* 除[内置只读集合](https://code.claude.com/docs/zh-CN/permissions.md#read-only-commands)之外的所有其他 Bash 命令

276 277

277每个路径也会经过[符号链接检查](https://code.claude.com/docs/zh-CN/permissions.md#symlinks)，因此解析到该范围之外的写入也不会自动批准。278每个路径也会经过[符号链接检查](https://code.claude.com/docs/zh-CN/permissions.md#symlinks)，因此解析到该范围之外的写入也不会自动批准。

369* **直接连接到 Anthropic API**：在交互式终端会话以及 `-p`、Agent SDK、[VS Code 扩展](https://code.claude.com/docs/zh-CN/vs-code.md)和[桌面应用](https://code.claude.com/docs/zh-CN/desktop.md)会话中，无论您的计划或账户类型如何，随 Anthropic 逐步推出而生效。在交互式终端会话中，Pro、Max 和 Team 计划需要 Claude Code v2.1.271 或更高版本，Enterprise 计划和 Claude API 账户需要 v2.1.278 或更高版本。在 `-p`、Agent SDK、VS Code 扩展和桌面应用会话中，需要 Claude Code v2.1.281 或更高版本。从 v2.1.282 起，[不获取功能标志](https://code.claude.com/docs/zh-CN/env-vars.md#features-that-need-feature-flag-fetching)的会话（例如因为您关闭了遥测）在任何类型的会话中都会默认请求服务器审查。370* **直接连接到 Anthropic API**：在交互式终端会话以及 `-p`、Agent SDK、[VS Code 扩展](https://code.claude.com/docs/zh-CN/vs-code.md)和[桌面应用](https://code.claude.com/docs/zh-CN/desktop.md)会话中，无论您的计划或账户类型如何，随 Anthropic 逐步推出而生效。在交互式终端会话中，Pro、Max 和 Team 计划需要 Claude Code v2.1.271 或更高版本，Enterprise 计划和 Claude API 账户需要 v2.1.278 或更高版本。在 `-p`、Agent SDK、VS Code 扩展和桌面应用会话中，需要 Claude Code v2.1.281 或更高版本。从 v2.1.282 起，[不获取功能标志](https://code.claude.com/docs/zh-CN/env-vars.md#features-that-need-feature-flag-fetching)的会话（例如因为您关闭了遥测）在任何类型的会话中都会默认请求服务器审查。

370* **云提供商，或 LLM 网关或代理**：在 [Claude Platform on AWS](https://code.claude.com/docs/zh-CN/claude-platform-on-aws.md)、Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，以及每当您将 `ANTHROPIC_BASE_URL` 指向 [LLM 网关或代理](https://code.claude.com/docs/zh-CN/llm-gateway)时，无论您的计划如何。默认请求服务器审查需要 Claude Code v2.1.278 或更高版本。371* **云提供商，或 LLM 网关或代理**：在 [Claude Platform on AWS](https://code.claude.com/docs/zh-CN/claude-platform-on-aws.md)、Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，以及每当您将 `ANTHROPIC_BASE_URL` 指向 [LLM 网关或代理](https://code.claude.com/docs/zh-CN/llm-gateway)时，无论您的计划如何。默认请求服务器审查需要 Claude Code v2.1.278 或更高版本。

371* **已登录的 [Claude apps gateway](https://code.claude.com/docs/zh-CN/claude-apps-gateway) 会话**：需要 Claude Code v2.1.280 或更高版本372* **已登录的 [Claude apps gateway](https://code.claude.com/docs/zh-CN/claude-apps-gateway) 会话**：需要 Claude Code v2.1.280 或更高版本

373* **Anthropic 托管环境中的[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)**：无论您的计划如何，当您在选择了 **Cloud** 的情况下从网页、移动应用或桌面应用启动该会话时。由[云端定时任务](https://code.claude.com/docs/zh-CN/routines.md)启动的会话会随 Anthropic 逐步推出而请求服务器审查。

372 374

373当服务器审查这些操作时，由服务器的裁决决定结果。此外还有另外两种可能的结果：375当服务器审查这些操作时，由服务器的裁决决定结果。此外还有另外两种可能的结果：

374 376

647 649

648`bypassPermissions` 模式禁用权限提示和安全检查，以便工具调用立即执行，包括对[受保护路径](#protected-paths)的写入。650`bypassPermissions` 模式禁用权限提示和安全检查，以便工具调用立即执行，包括对[受保护路径](#protected-paths)的写入。

649 651

650[任何模式都不会自动批准的操作](#actions-no-mode-auto-approves)在此模式下仍会提示。读取[其他组织的公开 Artifact](https://code.claude.com/docs/zh-CN/artifacts.md#read-an-artifact-shared-with-you) 需要您的批准，而此模式不会请求批准，因此 Claude 无法读取此类 Artifact。[PowerShell 中的 Remove-Item](#remove-item-in-powershell) 拒绝也适用于此模式。652即使在 `bypassPermissions` 模式下，每项[任何模式都不会自动批准的操作](#actions-no-mode-auto-approves)也会触发提示或被拒绝，而不会自行运行。读取[其他组织的公开 Artifact](https://code.claude.com/docs/zh-CN/artifacts.md#read-an-artifact-shared-with-you) 需要您的批准，而此模式不会请求批准，因此 Claude 无法读取此类 Artifact。[PowerShell 中的 Remove-Item](#remove-item-in-powershell) 拒绝也适用于此模式。

651 653

652两个[跨会话消息传递](https://code.claude.com/docs/zh-CN/cross-session-messaging.md)保护措施在此模式下仍然适用，在可使用绕过权限的交互式终端计划模式会话中同样适用：654两个[跨会话消息传递](https://code.claude.com/docs/zh-CN/cross-session-messaging.md)保护措施在此模式下仍然适用，在可使用绕过权限的交互式终端计划模式会话中同样适用：

653 655

769* `.devcontainer.json`771* `.devcontainer.json`

770* `.ripgreprc`、`pyrightconfig.json`772* `.ripgreprc`、`pyrightconfig.json`

771* `.mcp.json`、`.claude.json`773* `.mcp.json`、`.claude.json`

774* 您在启动会话时传递给 [`--settings`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags)、`--mcp-config` 或 `--agents` 的文件

772* 当您的用户、项目或本地[设置文件](https://code.claude.com/docs/zh-CN/settings.md#settings-files-and-who-they-affect)本身是符号链接（例如指向 dotfiles 仓库）时，该设置文件所指向的文件。在将受保护路径写入路由到分类器的模式中，对此文件的写入会改为提示您，即使有允许规则匹配也是如此。如果该文件自身的路径同时也是某个设置文件的路径，例如另一个文件夹中的 `.claude/settings.json`，则该写入会像其他受保护路径写入一样交由分类器处理775* 当您的用户、项目或本地[设置文件](https://code.claude.com/docs/zh-CN/settings.md#settings-files-and-who-they-affect)本身是符号链接（例如指向 dotfiles 仓库）时，该设置文件所指向的文件。在将受保护路径写入路由到分类器的模式中，对此文件的写入会改为提示您，即使有允许规则匹配也是如此。如果该文件自身的路径同时也是某个设置文件的路径，例如另一个文件夹中的 `.claude/settings.json`，则该写入会像其他受保护路径写入一样交由分类器处理

773 776

774## 关键路径777## 关键路径

844 847

845对于变量下的 glob 或尾部斜杠，提示命名被标记的 `rm` 并说明如何重写它以便检查通过。848对于变量下的 glob 或尾部斜杠，提示命名被标记的 `rm` 并说明如何重写它以便检查通过。

846 849

850### `Dangerous rm operation not ruled out` 提示

851

852完整原因如下：

853

854```text theme={null}

855Dangerous rm operation not ruled out — the shell may read this command differently than it was parsed

856```

857

858此原因表示 shell 对该命令的解读可能与 Claude Code 不同，因此即使命令中没有 `rm`，移除操作也可能位于未经检查的部分中。在 `auto` 或 `bypassPermissions` 模式下，包含以下语句的拒绝也来自同一检查：

859

860```text theme={null}

861This command could not be checked for dangerous rm operations: the shell may read it differently than it was parsed.

862```

863

864您会收到关键路径移除[在您的权限模式下](#critical-path-removals-in-each-permission-mode)会收到的提示或拒绝，`bypassPermissions` 也不例外。您无法通过 `Bash` 或 `Bash(*)` 允许规则、沙箱[自动允许模式](https://code.claude.com/docs/zh-CN/sandboxing.md#auto-allow-mode)或返回 `"allow"` 的 `PreToolUse` hook 批准该命令。请阅读该命令，然后批准提示，或者在被拒绝后在您的 shell 中运行它。

865

847### 挂载驱动器提示866### 挂载驱动器提示

848 867

849在 macOS、Linux 和 WSL 上，当递归 `rm` 的目标是所列的[挂载驱动器路径](#paths-that-get-the-mounted-drive-prompt)（如 `/mnt/c` 或 `/Volumes/USB/build`）时，会出现挂载驱动器提示。其原因显示为 `Dangerous rm operation on mounted drive path: <path>`。`/*` 目标即使没有递归标志也会出现该提示，因为 Claude Code 将 `rm /Volumes/USB/build/*` 视为对 `/Volumes/USB/build` 的移除。868在 macOS、Linux 和 WSL 上，当递归 `rm` 的目标是所列的[挂载驱动器路径](#paths-that-get-the-mounted-drive-prompt)（如 `/mnt/c` 或 `/Volumes/USB/build`）时，会出现挂载驱动器提示。其原因显示为 `Dangerous rm operation on mounted drive path: <path>`。`/*` 目标即使没有递归标志也会出现该提示，因为 Claude Code 将 `rm /Volumes/USB/build/*` 视为对 `/Volumes/USB/build` 的移除。

902| `dontAsk` | 拒绝它 |921| `dontAsk` | 拒绝它 |

904 923

905如果显式[询问规则](https://code.claude.com/docs/zh-CN/permissions.md#manage-permissions)与命令匹配，Claude Code 即使在 `auto` 模式下也会询问您，且没有时间限制。在询问的模式中，[`PermissionRequest` hook](https://code.claude.com/docs/zh-CN/hooks#permissionrequest) 可以回答提示。924如果显式[询问规则](https://code.claude.com/docs/zh-CN/permissions.md#manage-permissions)与命令匹配，Claude Code 即使在 `auto` 模式下也会询问您，且没有时间限制。在询问的模式中，[`PermissionRequest` hook](https://code.claude.com/docs/zh-CN/hooks#permissionrequest) 可以回答提示。

906 925

912* 在提示打开时按任何键停止倒计时并保持提示等待您的回答。931* 在提示打开时按任何键停止倒计时并保持提示等待您的回答。

913* 在一个会话中这样的提示运行完三次后无人回答，Claude Code 停止显示它们并立即拒绝进一步的关键路径移除。发送新消息会重新开始计数。932* 在一个会话中这样的提示运行完三次后无人回答，Claude Code 停止显示它们并立即拒绝进一步的关键路径移除。发送新消息会重新开始计数。

914 933

915在 `auto` 模式下，无论 Claude Code 无法向您显示终端提示的地方，它都立即拒绝命令，例如在[非交互式运行](https://code.claude.com/docs/zh-CN/headless.md)中使用 `-p`、在 [Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md) 会话中，以及在 VS Code 扩展的聊天面板和桌面应用中。拒绝告诉 Claude 报告它想删除的内容并将移除留给您。934时间限制适用于 Claude Code v2.1.281 及更高版本，终端之外的 `auto` 模式拒绝同样如此。

935

936在终端之外，您不会收到该提示：

916 937

917`auto` 和 `bypassPermissions` 处理需要 Claude Code v2.1.281 或更高版本。要关闭它，请在启动 Claude Code 的环境中设置 [`CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT=1`](https://code.claude.com/docs/zh-CN/env-vars#variables)。在 `auto` 模式下，关键路径移除随后转到分类器，在 `bypassPermissions` 模式下提示没有时间限制。938| 位置 | `auto` | `bypassPermissions` |

939| :- | :- | :- |

940| [VS Code 扩展](https://code.claude.com/docs/zh-CN/vs-code.md)的聊天面板 | 拒绝它 | 拒绝它，除非 [`PermissionRequest` hook](https://code.claude.com/docs/zh-CN/hooks#permissionrequest) 允许它 |

941| [桌面应用](https://code.claude.com/docs/zh-CN/desktop.md) | 拒绝它 | 拒绝它，除非 `PermissionRequest` hook 允许它 |

942| [`-p` 运行](https://code.claude.com/docs/zh-CN/headless)或 [Agent SDK 会话](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md) | 拒绝它 | 由您的 [`--permission-prompt-tool`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 或 [`canUseTool` 回调](https://code.claude.com/docs/zh-CN/agent-sdk/user-input#handle-tool-approval-requests)决定。如果两者都没有，或者在 [`--permission-prompts none`](https://code.claude.com/docs/zh-CN/headless#turn-off-permission-prompts-in-unattended-runs) 下，则拒绝它，除非 `PermissionRequest` hook 允许它 |

943

944无论在何处拒绝了该移除，您都可以阅读完整命令并在您的 shell 中运行它。

945

946要更改每种模式下的处理方式，请将 [`CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT`](https://code.claude.com/docs/zh-CN/env-vars#variables) 设置为 `1`：

947

948* **`bypassPermissions`**：终端提示没有时间限制，VS Code 聊天面板会询问您

949* **`auto`**：由[分类器](#eliminate-prompts-with-auto-mode)决定，适用于终端、VS Code 聊天面板、`-p` 运行和 Agent SDK 会话

950

951请在启动 Claude Code 的环境中设置它，例如您的 shell 或 SDK 的 `env` 选项，而不是在 Claude Code 设置文件中设置。对于聊天面板，请将其添加到 VS Code 自身用户 `settings.json` 中的 [`claudeCode.environmentVariables`](https://code.claude.com/docs/zh-CN/vs-code#extension-settings)，然后开始新的对话：

952

953```json theme={null}

954{

955 "claudeCode.environmentVariables": [

956 { "name": "CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT", "value": "1" }

957 ]

958}

959```

918 960

919### PowerShell 中的 Remove-Item961### PowerShell 中的 Remove-Item

920 962

plugins/anthropic-marketplaces.md +1 −1

Details

41 41

42如果教程或较旧的说明告诉你运行 `/plugin marketplace add anthropics/claude-code`，这会添加演示市场，名为 `claude-code-plugins`。它不是官方市场。42如果教程或较旧的说明告诉你运行 `/plugin marketplace add anthropics/claude-code`，这会添加演示市场，名为 `claude-code-plugins`。它不是官方市场。

43 43

44演示市场的大多数插件也在官方市场中以相同的名称存在。例如，`code-review`、`feature-dev`、`commit-commands` 和 `security-guidance` 都在两者中。从 `claude-plugins-official` 安装这些，这样你就不会安装两个副本。44演示市场的大多数插件也在官方市场中以相同的名称存在。例如，`code-review`、`feature-dev` 和 `commit-commands` 都在两者中。请从 `claude-plugins-official` 安装这些插件，以免安装两个副本。

45 45

46## 在官方市场中查找插件46## 在官方市场中查找插件

47 47

plugins/host-marketplace.md +1 −1

Details

403 403

404对于版本范围、它们解析的 `<plugin>--v<version>` git 标签约定和跨 marketplace 信任，请参阅 [插件依赖](https://code.claude.com/docs/zh-CN/plugins/dependencies.md)。404对于版本范围、它们解析的 `<plugin>--v<version>` git 标签约定和跨 marketplace 信任，请参阅 [插件依赖](https://code.claude.com/docs/zh-CN/plugins/dependencies.md)。

405 405

406要在项目匹配时让 Claude Code 建议插件，向条目添加 `relevance` 块，其中包含识别项目的信号。用户仅在管理员在 `pluginSuggestionMarketplaces` 中列出你的 marketplace 时才看到来自你的 marketplace 的建议。对于信号和启用步骤，请参阅 [插件相关性](https://code.claude.com/docs/zh-CN/plugins/relevance.md)。406要在项目匹配时让 Claude Code 建议某个插件，请向条目添加 `relevance` 块，其中包含用于识别该项目的信号。仅当管理员在 `pluginSuggestionMarketplaces` 中列出您的市场时，用户才会看到这些建议。有关信号和启用步骤，请参阅[插件相关性](https://code.claude.com/docs/zh-CN/plugins/relevance.md)。

407 407

408## 解决 marketplace 无法做的事情408## 解决 marketplace 无法做的事情

409 409

plugins/mods/admin.md +38 −1

Details

95 95

96这些控制中的任何一个都不会沙箱化 mod。您允许的 mod 以用户身份运行，具有用户对文件、进程和网络的访问权限。96这些控制中的任何一个都不会沙箱化 mod。您允许的 mod 以用户身份运行，具有用户对文件、进程和网络的访问权限。

97 97

98### 了解用户 mod 的哪些 hook 不会运行

100在[内置守卫](#know-what-happens-by-default)加载的地方，用户的 mod 在以下事件上注册的 hook 永远不会运行，`/plugin` 会通过一条说明告知该用户。在 [`session.append`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#session) 各行中，`door` 是该 hook 所筛选的存储行的类型。

101

102| hook 所在事件 | 事件是什么 |

103| :- | :- |

104| [`classic.<Event>`](https://code.claude.com/docs/zh-CN/plugins/mods/events#hook-the-settings-hook-events)，例如 `classic.Stop` | 一个[设置 hook 事件](https://code.claude.com/docs/zh-CN/hooks.md#hook-events) |

105| [`prompt.compose`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#prompts-and-what-claude-reads) | 系统提示词的章节列表 |

106| `prompt.section` | 系统提示词的一个章节 |

107| `prompt.context` | 随对话第一条消息一起发送的上下文 |

108| `prompt.attachment` | Claude Code 为 Claude 添加的消息，例如提醒 |

109| `skill.prompt` | 为 Claude 展开时的 skill 文本 |

110| `attribution.text` | 提交或 Pull Request 的署名文本 |

111| [`session.compact`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#session) | 对话的一次压缩 |

112| `settings.read` | 一次设置读取，例如 mod 的 `$.settings.read` 调用 |

113| `session.append{door=attachment}` | Claude Code 为 Claude 添加的消息的存储行 |

114| `session.append{door=hook-context}` | 来自设置 hook 的上下文的存储行 |

115| `session.append{door=compaction}` | 压缩摘要和边界的存储行 |

116

117在其他一些情况下，守卫也会跳过用户的 hook，例如 [`tool.describe`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#tools) 上您组织的工具描述，以及 skill 文本的存储行。对于这些情况，`/plugin` 不会显示说明。如果其他事件上的 hook 没有任何作用，请参阅[查明 mod 为何没有任何作用](https://code.claude.com/docs/zh-CN/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing)。

118

119该说明显示在插件的详细信息中以及 `/plugin` 的 **Errors** 选项卡中。它需要 Claude Code v2.1.299 或更高版本。它会按照 mod 注册时的写法列出表中的每个 hook，如以下示例所示：

120

121```text theme={null}

122Its hooks on classic.Stop, prompt.section do not run here: where an organization manages Claude Code, these events pass over the plugins you install

123Only a plugin that counts as your organization's own runs hooks on these events. An administrator sets that up in managed settings

124```

125

126要让这些 hook 运行，请通过以下两种方式之一更改托管设置：

127

128* **将该 mod 作为您组织的 mod 运行**：[安装该 mod，使其算作您组织自己的 mod](#install-your-organizations-mods)。这样它在这些事件上的 hook 就会运行，而守卫对其他所有 mod 仍保持加载。该 mod 会为接收这些设置的每个人开启，并且必须位于您放置在每台机器上的目录中。如果您将其列在 `prependPlugins` 中，请在列表中保留 `sec-default@builtin`。

129* **移除守卫**：在 `prependPlugins` 中省略 `sec-default@builtin`。一个空列表 `"prependPlugins": []` 就足够了。您失去的是整个守卫，而不仅仅是这些事件。这样用户的 mod 就可以做[守卫原本会阻止它做的事情](#know-what-happens-by-default)，并且[守卫的选项](#set-options-on-the-built-in-guard)也不再适用。

130

131如果您通过[服务器托管设置](https://code.claude.com/docs/zh-CN/server-managed-settings.md#fetch-and-caching-behavior)下发不含守卫的列表，守卫会保持加载，直到服务器为该会话确认这些设置。要在运行 v2.1.299 或更高版本的机器上确认任一更改，请在该机器上的会话中打开 `/plugin`，并检查该说明是否已消失。

132

133没有 `door` 筛选条件的 `session.append` hook 仍会运行且不会收到说明，但表中的存储行不会传递给它。

134

98## 决定是否保持 mods 开启135## 决定是否保持 mods 开启

99 136

100Mod 可以做的比插件的其他部分更多，因为它在 Claude Code 内运行。它看到每个提示和工具调用，可以更改它们，并可以在权限提示出现之前允许或拒绝工具调用。137Mod 可以做的比插件的其他部分更多，因为它在 Claude Code 内运行。它看到每个提示和工具调用，可以更改它们，并可以在权限提示出现之前允许或拒绝工具调用。

144 181

145在 `hooks:` 行中，[`tool.call`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#tools) 和 [`prompt.submit`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#prompts-and-what-claude-reads) 意味着 mod 看到每个工具调用和每个提示，并可以更改它们。[`session.append`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#session) 意味着 mod 可以在存储之前重写对话的每一行。[`ui.render{component=AskUserQuestion}`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#change-what-claude-code-already-draws) 意味着 mod 可以重新绘制 Claude 用来询问用户问题的对话框。`tool.check` 意味着 mod 可以在权限提示出现之前批准或拒绝工具调用。[了解默认情况下会发生什么](#know-what-happens-by-default)列出了您的哪些规则和 hooks 优先于其答案。182在 `hooks:` 行中，[`tool.call`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#tools) 和 [`prompt.submit`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#prompts-and-what-claude-reads) 意味着 mod 看到每个工具调用和每个提示词，并可以更改它们。[`session.append`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#session) 意味着 mod 可以在存储之前重写对话的每一行，但[防护机制跳过的行](#hooks-the-guard-passes-over)除外。[`ui.render{component=AskUserQuestion}`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#change-what-claude-code-already-draws) 意味着 mod 可以重新绘制 Claude 用来询问用户问题的对话框。`tool.check` 意味着 mod 可以在权限提示出现之前批准或拒绝工具调用。[了解默认情况下会发生什么](#know-what-happens-by-default)列出了您的哪些规则和 hook 优先于其答案。

146 183

147## 选择允许的程度184## 选择允许的程度

148 185

plugins/mods/events.md +2 −2

Details

377 377

378### 处理设置 hook 事件378### 处理设置 hook 事件

379 379

380设置 hook 是您在设置文件中配置的命令、HTTP、提示词和 Agent hook。每个[设置 hook 事件](https://code.claude.com/docs/zh-CN/hooks.md#hook-events)（例如 `Stop`、`SessionEnd` 或 `PostToolUse`）同时也是一个名为 `classic.` 后跟该设置 hook 事件名称的事件，例如 `classic.Stop`。`e` 是设置 hook 在 stdin 上接收的 JSON，包括 `transcript_path`。380设置 hook 是您在设置文件中配置的命令、HTTP、提示词和 Agent hook。每个[设置 hook 事件](https://code.claude.com/docs/zh-CN/hooks.md#hook-events)（例如 `Stop`、`SessionEnd` 或 `PostToolUse`）同时也是一个名为 `classic.` 后跟该设置 hook 事件名称的事件，例如 `classic.Stop`。`e` 是设置 hook 在 stdin 上接收的 JSON，包括 `transcript_path`。在加载了[内置守卫](https://code.claude.com/docs/zh-CN/plugins/mods/admin.md#know-what-happens-by-default)的环境中，[您安装的 mod 中针对这些事件的 hook 不会运行](https://code.claude.com/docs/zh-CN/plugins/mods/admin.md#hooks-the-guard-passes-over)。

381 381

382以下 hook 使用 `Stop`（在 Claude 完成回复时触发）来记录会话的会话记录保存位置：382以下 hook 使用 `Stop`（在 Claude 完成回复时触发）来记录会话的会话记录保存位置：

383 383

425* **它在调用 `next` 之前失败**：Claude Code 跳过它，下一个处理程序代替运行425* **它在调用 `next` 之前失败**：Claude Code 跳过它，下一个处理程序代替运行

426* **它在 `next` 解析后失败**：该结果成立，没有任何东西运行第二次426* **它在 `next` 解析后失败**：该结果成立，没有任何东西运行第二次

427 427

428一行内容会指明 mod、事件和原因，例如 `my-mod: tool.call hook skipped: threw Error: boom`。您读取它的位置取决于会话，如[找出 mod 为什么不做任何事](https://code.claude.com/docs/zh-CN/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing)所列。其绘图未通过验证的 `ui.render` hook 的报告方式不同，如[从元素构建树](https://code.claude.com/docs/zh-CN/plugins/mods/interface.md#build-a-tree-from-elements)所述。428一行内容会指明 mod、事件和原因，例如 `my-mod: tool.call hook skipped: threw Error: boom`。您读取它的位置取决于会话，如[找出 mod 为什么不做任何事](https://code.claude.com/docs/zh-CN/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing)所列。[树未通过验证](https://code.claude.com/docs/zh-CN/plugins/mods/interface.md#build-a-tree-from-elements)的 `ui.render` hook 视为返回了错误形状结果的 hook。

429 429

430要使阻止调用的 hook 失败关闭，请添加一个 `.catch` 错误处理程序来代替回答。这里，`guard` 是您的 hook 函数，处理程序检查 [`next.called`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#the-hook-function) 来判断 `guard` 在失败时是否已经调用了 `next`：430要使阻止调用的 hook 失败关闭，请添加一个 `.catch` 错误处理程序来代替回答。这里，`guard` 是您的 hook 函数，处理程序检查 [`next.called`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#the-hook-function) 来判断 `guard` 在失败时是否已经调用了 `next`：

431 431

plugins/mods/gallery.md +21 −1

Details

246 246

247### `Input`247### `Input`

248 248

249`Input` 是单行文本输入框，用户按 Enter 时会运行 `onSubmit`：249`Input` 是文本输入框，用户按 Enter 时会运行 `onSubmit`。除非为其指定 `rows`，否则它只容纳一行：

250 250

251```javascript theme={null}251```javascript theme={null}

252Input({252Input({

271 271

272![同一个输入框，其中包含已键入的字母 Rel，后跟回车符号和单词 save。](https://mintcdn.com/claude-code/EXkwf0kKMewZsyod/images/mods-el-input-typed-light.png?fit=max\&auto=format\&n=EXkwf0kKMewZsyod\&q=85\&s=4eb6d4443763a21415dad4e426bc747a)272![同一个输入框，其中包含已键入的字母 Rel，后跟回车符号和单词 save。](https://mintcdn.com/claude-code/EXkwf0kKMewZsyod/images/mods-el-input-typed-light.png?fit=max\&auto=format\&n=EXkwf0kKMewZsyod\&q=85\&s=4eb6d4443763a21415dad4e426bc747a)

273 273

274如需容纳多行内容的输入框（例如备注或提交信息），请添加 `rows`：

275

276```javascript theme={null}

277Input({

278 key: 'note',

279 label: 'Note',

280 placeholder: 'Write a note',

281 rows: 4,

282 onSubmit: noop,

283})

284```

285

286无论输入框中有什么内容，它都占据该数量的行，最多不超过其所在窗格或区域的高度。更长的文本会在输入框内滚动。

287

288* Enter 仍然用于提交。在终端中，用户可以先键入反斜杠再按 Enter 来换行，或者在[终端模拟器支持的情况下](https://code.claude.com/docs/zh-CN/terminal-config.md#enter-multiline-prompts)按 Shift+Enter。这些按键与输入框中的按键相同。

289* 上方向键和下方向键用于在输入框的各行之间移动。在第一行和最后一行时，它们会移动到前一个或后一个控件。

290* `onSubmit` 和 `onInput` 接收完整文本，其各行以 `\n` 连接。

291

292终端和桌面应用会绘制多行。在 VS Code 扩展中，输入框只容纳一行。

293

274### `Select`294### `Select`

275 295

276`Select` 让用户从多个选项中选择一个，并以该选项的 `value` 运行 `onSelect`：296`Select` 让用户从多个选项中选择一个，并以该选项的 `value` 运行 `onSelect`：

plugins/mods/interface.md +7 −3

Details

421Note: Type a note and press Enter421Note: Type a note and press Enter

422```422```

423 423

424添加 `rows` 可让该字段容纳多行。Enter 仍会提交，在 Enter 前输入反斜杠会开始新行，在[终端支持的情况下](https://code.claude.com/docs/zh-CN/terminal-config.md#enter-multiline-prompts)按 Shift+Enter 也可以。图库展示了[带有 `rows` 的字段](https://code.claude.com/docs/zh-CN/plugins/mods/gallery#input)。

425

424[界面图库](https://code.claude.com/docs/zh-CN/plugins/mods/gallery.md)提供了大多数元素的示例和屏幕截图。此表列出了每个元素：426[界面图库](https://code.claude.com/docs/zh-CN/plugins/mods/gallery.md)提供了大多数元素的示例和屏幕截图。此表列出了每个元素：

425 427

426| 元素 | 它绘制什么 | 位置 |428| 元素 | 它绘制什么 | 位置 |

436 438

437如果您的模块是 `.tsx` 或 `.jsx` 文件，您可以将树写成 JSX。首先从 `$.ui.resolve(e)` 解构元素。439如果您的模块是 `.tsx` 或 `.jsx` 文件，您可以将树写成 JSX。首先从 `$.ui.resolve(e)` 解构元素。

438 440

439如果树使用应用没有的元素、元素不接受的属性或在不应有子项的位置放置子项，Claude Code 会绘制其自己的站点版本。441如果您的绘制没有显示，请检查其树中是否有元素不接受的 prop，或是否在不应有子项的位置放置了子项。返回此类树的 hook 会[失败](https://code.claude.com/docs/zh-CN/plugins/mods/events.md#handle-a-hook-that-fails)，并且会出现一行 [`hook skipped` 行](https://code.claude.com/docs/zh-CN/plugins/mods/troubleshoot#a-pane-or-band-is-empty)，指出您的 mod 以及该树违反的规则。对于窗格中带有名为 `bogusProp` 的 prop 的 `Text`，该行内容为：

440 442

441在使用 `--plugin-dir` 启动的会话中，会话记录中会有一行说明这一点，例如 `ui.render (Pane) refused: Text prop "bogusProp" is not allowed; the engine drew its own`。[调试日志](https://code.claude.com/docs/zh-CN/plugins/mods/troubleshoot.md#read-the-debug-log) 将其记录为 `ui.render (Pane): a hook returned a tree that does not validate` 并带有相同的原因。会话中没有其他内容出现，所以当绘制不显示时，请检查该行或日志。443```text theme={null}

444my-mod: ui.render hook skipped: returned the wrong shape (a tree Pane refuses: Text prop "bogusProp" is not allowed)

445```

442 446

443### 桌面应用和 VS Code 中的 `Link`447### 桌面应用和 VS Code 中的 `Link`

444 448

542| 键 | 它做什么 |546| 键 | 它做什么 |

543| :- | :- |547| :- | :- |

544| Tab | 移动到下一个控件 |548| Tab | 移动到下一个控件 |

545| 上和下 | 在绘制内容能完整显示时在控件之间移动。当窗格或条带的行数超过它可以显示的行数时，它们会滚动它。 |549| 上和下 | 在绘制内容能完整显示时在控件之间移动。当窗格或条带的行数超过它可以显示的行数时，它们会滚动它。在 `Input` 中，它们会先[在字段的各行之间移动](https://code.claude.com/docs/zh-CN/plugins/mods/gallery.md#input)。 |

548| Page Up、Page Down、Home 和 End | 当您的窗格或条带的行数超过它可以显示的行数时，滚动它 |552| Page Up、Page Down、Home 和 End | 当您的窗格或条带的行数超过它可以显示的行数时，滚动它 |

plugins/mods/reference.md +11 −7

Details

275| [`Link`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#link-in-the-desktop-app) | `href`、`label`。请参阅[限制](#limits)。 | ✓ | ✓ | ✓ |275| [`Link`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#link-in-the-desktop-app) | `href`、`label`。请参阅[限制](#limits)。 | ✓ | ✓ | ✓ |

276| [`Code`](https://code.claude.com/docs/zh-CN/plugins/mods/gallery#show-code-and-changes) | `source`、`language`、`path`、`startLine`、`format`、`wrap` | ✓ | ✓ | ✓ |276| [`Code`](https://code.claude.com/docs/zh-CN/plugins/mods/gallery#show-code-and-changes) | `source`、`language`、`path`、`startLine`、`format`、`wrap` | ✓ | ✓ | ✓ |

277| `Markdown` | `text`、`key`、`dimColor`、`onLinkPress`、`pressableLinks` | ✓ | ✓ | ✓ |277| `Markdown` | `text`、`key`、`dimColor`、`onLinkPress`、`pressableLinks` | ✓ | ✓ | ✓ |

278| [`Input`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#take-typed-input-and-draw-a-row-for-each-item) | `key`、`label`、`placeholder`、`value`、`submitLabel`、`onSubmit`、`onInput`、`autoFocus` | ✓ | ✓ | ✓ |278| [`Input`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#take-typed-input-and-draw-a-row-for-each-item) | `key`、`label`、`placeholder`、`value`、`submitLabel`、[`rows`](https://code.claude.com/docs/zh-CN/plugins/mods/gallery#input)、`onSubmit`、`onInput`、`autoFocus` | ✓ | ✓ | ✓ |

279| `Select` | `key`、`label`、`options`、`value`、`onSelect`、`autoFocus` | ✓ | ✓ | ✓ |279| `Select` | `key`、`label`、`options`、`value`、`onSelect`、`autoFocus` | ✓ | ✓ | ✓ |

280| `Svg` | 最多 131,072 个字符的 SVG 标记 `source`、`alt` 文本、`width`、`height` 以及 `isInteractive` | | ✓ | ✓ |280| `Svg` | 最多 131,072 个字符的 SVG 标记 `source`、`alt` 文本、`width`、`height` 以及 `isInteractive` | | ✓ | ✓ |

281| [`Client`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements) | `module`、`key`、`props`、`width`、`height`、`flexGrow` | ✓ | ✓ | |281| [`Client`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements) | `module`、`key`、`props`、`width`、`height`、`flexGrow` | ✓ | ✓ | |

333 333

334如果将 `gap`、`padding` 或 `margin` 设置为某个步长，该步长会同时应用于横向和纵向。例如，在终端和 VS Code 扩展中，`padding: 'md'` 表示左右两侧各两个单元格，上下各一行。334如果将 `gap`、`padding` 或 `margin` 设置为某个步长，该步长会同时应用于横向和纵向。例如，在终端和 VS Code 扩展中，`padding: 'md'` 表示左右两侧各两个单元格，上下各一行。

335 335

336步长名称需要 Claude Code v2.1.299 或更高版本。在更早的版本中，对于使用了步长名称的树，Claude Code 会[绘制它自己版本的该位置内容](https://code.claude.com/docs/zh-CN/plugins/mods/interface.md#build-a-tree-from-elements)来代替。336步长名称需要 Claude Code v2.1.299 或更高版本。在更早的版本中，使用了步长名称的树不会绘制。

337 337

338### `Text` 排版 prop338### `Text` 排版 prop

339 339

348 348

349这四个 prop 需要 Claude Code v2.1.299 或更高版本。在更早的版本中，对于设置了 `size`、`weight`、`mono` 或 `tabular` 的树，Claude Code 会[绘制它自己版本的该位置内容](https://code.claude.com/docs/zh-CN/plugins/mods/interface.md#build-a-tree-from-elements)来代替。349这四个 prop 需要 Claude Code v2.1.299 或更高版本。在更早的版本中，设置了 `size`、`weight`、`mono` 或 `tabular` 的树不会绘制。

350 350

351#### 用 `weight` 替换 `bold`351#### 用 `weight` 替换 `bold`

352 352

353`Text` 上的 `bold` 已弃用，建议改用 `weight`，但它仍然可用。要在未设置 `weight` 的 `Text` 上替换它，请将 `bold: true` 改为 `weight: 'semibold'`，在 Claude Code v2.1.299 或更高版本上效果相同。353`Text` 上的 `bold` 已弃用，建议改用 `weight`，但它仍然可用。要在未设置 `weight` 的 `Text` 上替换它，请将 `bold: true` 改为 `weight: 'semibold'`，在 Claude Code v2.1.299 或更高版本上效果相同。

354 354

355在早于 v2.1.299 的版本中，设置了 `weight` 的树不会绘制，Claude Code 会改为[绘制它自己版本的该位置内容](https://code.claude.com/docs/zh-CN/plugins/mods/interface.md#build-a-tree-from-elements)。如果您在 `Text` 上同时设置了 `bold` 和 `weight`，则 `bold` 不起作用。355在早于 v2.1.299 的版本中，设置了 `weight` 的树不会绘制。如果您在 `Text` 上同时设置了 `bold` 和 `weight`，则 `bold` 不起作用。

356 356

357## 限制357## 限制

358 358

359hook 和 mods API 调用受时间和大小限制。Claude Code 会跳过超出时间限制的 hook。359hook 和 mods API 调用受时间和大小限制。Claude Code 会跳过超出时间限制的 hook。超出嵌套、元素、`Raster` 单元格或 `Image` 字节限制的树[不会被绘制](https://code.claude.com/docs/zh-CN/plugins/mods/troubleshoot.md#a-pane-or-band-is-empty)。

360 360

361| 限制 | 值 |361| 限制 | 值 |

362| :- | :- |362| :- | :- |

372| 单次 `$.http.fetch` 调用跟随的重定向次数 | 5 |372| 单次 `$.http.fetch` 调用跟随的重定向次数 | 5 |

373| hook 的 `drop` 原因或 `config.set` 的 `deny` 原因 | 4,096 个字符。更长的原因会被截去末尾部分，drop 或 deny 仍然生效。截断需要 Claude Code v2.1.292 或更高版本；在更早的版本中，该 hook 会改为[失败](https://code.claude.com/docs/zh-CN/plugins/mods/events.md#handle-a-hook-that-fails)。 |373| hook 的 `drop` 原因或 `config.set` 的 `deny` 原因 | 4,096 个字符。更长的原因会被截去末尾部分，drop 或 deny 仍然生效。截断需要 Claude Code v2.1.292 或更高版本；在更早的版本中，该 hook 会改为[失败](https://code.claude.com/docs/zh-CN/plugins/mods/events.md#handle-a-hook-that-fails)。 |

374| 单个树中的文本 | 仅绘制前 100,000 个字符 |374| 单个树中的文本 | 仅绘制前 100,000 个字符 |

375| `Code` 的 `language` 或 `path`、`Select` 选项的 `value`，或 `Client` 的 `module` | 10,000 个字符。如果其中任何一项超出此长度，Claude Code 会[在该位置绘制其自身的版本](https://code.claude.com/docs/zh-CN/plugins/mods/interface.md#build-a-tree-from-elements)。 |375| `Code` 的 `language` 或 `path`、`Select` 选项的 `value`，或 `Client` 的 `module` | 10,000 个字符。如果其中任何一项超出此长度，返回它的 `ui.render` hook 会[失败](https://code.claude.com/docs/zh-CN/plugins/mods/events.md#handle-a-hook-that-fails)。 |

377| 单个树的嵌套深度 | 根元素以下 32 层 |

378| 单个树中的元素和文本子项 | 20,000 |

379| 单个树中的 `Raster` 单元格，即每个 `Raster` 的 `columns` 乘以其 `rows` | 262,144 |

380| 单个树中所有 `Image` 的 PNG 或 RGBA 字节数 | 2 MiB |

plugins/mods/test.md +2 −2

Details

312| 方法 | 它做什么 |312| 方法 | 它做什么 |

313| :- | :- |313| :- | :- |

314| `press({ key: 'more' })` | 按下具有该 key 的 `Button` |314| `press({ key: 'more' })` | 按下具有该 key 的 `Button` |

315| `input({ key: 'new-note', text: 'buy milk' })` | 将文本输入到具有该 key 的 `Input` 中并按 Enter。添加 `kind: 'change'` 以输入而不提交。 |315| `input({ key: 'new-note', text: 'buy milk' })` | 将文本输入到具有该 key 的 `Input` 中并按 Enter。添加 `kind: 'change'` 以输入而不提交。对于带有 `rows` 的字段，文本中可以包含 `\n`。 |

316| `select({ key: 'size', value: 'large' })` | 在具有该 key 的 `Select` 中选择具有该值的选项 |316| `select({ key: 'size', value: 'large' })` | 在具有该 key 的 `Select` 中选择具有该值的选项 |

317| `find({ key: 'more' })` 或 `find({ type: 'Text', text: 'Count: 2' })` | 返回第一个匹配的元素作为 `{ type, props, children }`，或 `undefined`。`text` 可以是字符串或正则表达式。 |317| `find({ key: 'more' })` 或 `find({ type: 'Text', text: 'Count: 2' })` | 返回第一个匹配的元素作为 `{ type, props, children }`，或 `undefined`。`text` 可以是字符串或正则表达式。 |

319 319

320每个方法在您的处理程序完成后解析，因此您可以在下一行检查结果。将 `props` 设置为 Claude Code 为该站点传递的内容。[render sites table](https://code.claude.com/docs/zh-CN/plugins/mods/reference.md#render-sites) 列出每个站点的 props，[您的构建的类型](https://code.claude.com/docs/zh-CN/plugins/mods/create.md#get-the-types-for-your-build) 有它们的类型。320每个方法在您的处理程序完成后解析，因此您可以在下一行检查结果。将 `props` 设置为 Claude Code 为该站点传递的内容。[render sites table](https://code.claude.com/docs/zh-CN/plugins/mods/reference.md#render-sites) 列出每个站点的 props，[您的构建的类型](https://code.claude.com/docs/zh-CN/plugins/mods/create.md#get-the-types-for-your-build) 有它们的类型。

321 321

322绘图测试检查您的 hook 返回的树以及它对该应用是否有效。它不检查应用如何绘制它，因此也在真实会话中查看新布局。322要捕获对您在 `surface` 中指定的应用无效的[元素树](https://code.claude.com/docs/zh-CN/plugins/mods/interface.md#build-a-tree-from-elements)，请使用 `find` 检查您的 hook 添加的某个元素。测试不检查应用如何绘制树，因此也请在真实会话中查看新布局。

323 323

324### 在 `/clear` 后测试绘图324### 在 `/clear` 后测试绘图

325 325

plugins/mods/troubleshoot.md +22 −4

Details

226 226

227要找到该 mod，请[写入调试日志](#read-the-debug-log)并在其中搜索 `answered ui.render without next()`。诸如 `other-mod (user) answered ui.render without next()` 的行会指明一个返回了树但未调用 `next(e)` 的 mod。该行不会指明[渲染位置](https://code.claude.com/docs/zh-CN/plugins/mods/reference.md#render-sites)，因此仅绘制窗格的 mod 也可能出现在其中。调用了 `next(e)` 但丢弃其结果的 mod 不会产生该行，因此也请检查在您的 mod 之前运行的 hook。227要找到该 mod，请[写入调试日志](#read-the-debug-log)并在其中搜索 `answered ui.render without next()`。诸如 `other-mod (user) answered ui.render without next()` 的行会指明一个返回了树但未调用 `next(e)` 的 mod。该行不会指明[渲染位置](https://code.claude.com/docs/zh-CN/plugins/mods/reference.md#render-sites)，因此仅绘制窗格的 mod 也可能出现在其中。调用了 `next(e)` 但丢弃其结果的 mod 不会产生该行，因此也请检查在您的 mod 之前运行的 hook。

228 228

229进行更改后，如果任一 mod 返回的树未通过验证，带中将不显示任何内容。要了解原因，请在 `--plugin-dir` 会话的会话记录中查找 `ui.render (AbovePrompt) refused:` 行，或在调试日志中搜索 `does not validate`。当带中有多个 mod 时，这两行都不会指明具体的 mod，因此请检查每个 mod 的树。229当某个 mod 自身的 hook 返回的树未通过验证时，该 mod 的带也会缺失，而其他 mod 的带仍会保留。要了解是哪个 mod 以及原因，请[写入调试日志](#read-the-debug-log)并在其中搜索 [`ui.render hook skipped`](#a-pane-or-band-is-empty)。

230 230

231### 窗格或带为空或显示 Claude Code 的常规内容231### 窗格或带为空或显示 Claude Code 的常规内容

232 232

233您的 hook 返回的 [树](https://code.claude.com/docs/zh-CN/plugins/mods/interface.md#build-a-tree-from-elements) 未通过验证。使用 `--plugin-dir` 时，会话记录会显示 `ui.render (Pane) refused:` 及原因，如 `first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own`。调试日志中有 `a hook returned a tree that does not validate` 及相同的原因。233您的 hook 返回的[树](https://code.claude.com/docs/zh-CN/plugins/mods/interface.md#build-a-tree-from-elements)未通过验证。[会话记录或调试日志中](#find-out-why-a-mod-does-nothing)的 [`hook skipped`](#hook-skipped) 行会指明您的 mod 及原因，例如以下针对窗格中某个 `Box` 的行：

234 234

235读取该行上的原因。常见原因是元素不接受的 prop 和应用没有的元素。235```text theme={null}

236first-mod: ui.render hook skipped: returned the wrong shape (a tree Pane refuses: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse)

237```

238

239请修复原因中指出的问题。如果原因被截断，请[写入调试日志](#read-the-debug-log)并在其中搜索 `a hook returned a tree that does not validate` 以查看其余内容。

240

241如果该行在位置名称之后紧接着显示 `refused:`，如 `ui.render (Pane) refused:`，请参阅[`ui.render` 行显示 `refused`](#ui-render-refused)。

242

243### `ui.render` 行显示 `refused`

244

245`ui.render (<site>) refused:`，或[调试日志](#read-the-debug-log)中的 `ui.render (<site>): the chain settled on a tree that does not validate`，表示该位置的[树](https://code.claude.com/docs/zh-CN/plugins/mods/interface.md#build-a-tree-from-elements)超出了[大小限制](https://code.claude.com/docs/zh-CN/plugins/mods/reference.md#limits)。这两行都会先指明[渲染位置](https://code.claude.com/docs/zh-CN/plugins/mods/reference.md#render-sites)，然后给出原因，原因中会指明该限制。

246

247请修改在该位置绘制的 mod，使其 [`ui.render`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#interface) hook 返回更小的树，或请其作者修改。如果会话记录行以 `hooks` 开头，则表示有多个已加载的 mod 为该位置设置了 `ui.render` hook，因此请检查每个这些 mod 的树。当多个 mod 在输入框上方的带嵌套成深度超过 32 层的树时，该行显示为：

248

249```text theme={null}

250hooks: ui.render (AbovePrompt) refused: deeper than 32; nothing was drawn

251```

252

253在 v2.1.307 之前，任何位置的 `refused:` 行都会报告任何未通过验证的树，并且对于 `Pane` 和 `AbovePrompt`，该行以 `; the engine drew its own` 结尾。在这些版本中，请修复原因中指出的问题。

236 254

237### `needs a key`、`is drawn twice` 或 `key each once`255### `needs a key`、`is drawn twice` 或 `key each once`

238 256

383hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render401hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render

384```402```

385 403

386未验证的绘图计为被拒绝的结果，也会获得一行。要在日志中写入您自己的行，请调用 [`$.ui.log`](https://code.claude.com/docs/zh-CN/plugins/mods/api#show-something-without-starting-a-turn)，带有第二个参数，如 `$.ui.log('message', { to: 'debug' })`。没有第二个参数，`$.ui.log` 会在会话记录中添加一条暗行。404要在日志中写入您自己的行，请调用 [`$.ui.log`](https://code.claude.com/docs/zh-CN/plugins/mods/api#show-something-without-starting-a-turn)，带有第二个参数，如 `$.ui.log('message', { to: 'debug' })`。没有第二个参数，`$.ui.log` 会在会话记录中添加一条暗行。

387 405

388当您编辑使用 `--plugin-dir` 加载的 mod 时，会话记录为每次重新加载显示一行，命名 mod 并列出其 hook。如果保存破坏了模块，该行会显示 `reload failed, the previous version stays loaded:` 及原因，最后一个可用版本会继续运行，直到 Claude Code 下次重新加载插件，例如当您运行 `/reload-plugins` 时。406当您编辑使用 `--plugin-dir` 加载的 mod 时，会话记录为每次重新加载显示一行，命名 mod 并列出其 hook。如果保存破坏了模块，该行会显示 `reload failed, the previous version stays loaded:` 及原因，最后一个可用版本会继续运行，直到 Claude Code 下次重新加载插件，例如当您运行 `/reload-plugins` 时。

389 407

plugins/org.md +6 −2

Details

183| `syncClaudeAiPlugins` | 设置 `false` 以停止 Claude Code 下载和加载为每个用户账户[从 claude.ai 同步](https://code.claude.com/docs/zh-CN/plugins/loading.md#synced-plugins)的插件。需要 Claude Code v2.1.273 或更高版本 | 不关闭一个同步插件。为此，在[`enabledPlugins`](https://code.claude.com/docs/zh-CN/settings-reference#enabledplugins)中设置 `"<name>@synced": false` |183| `syncClaudeAiPlugins` | 设置 `false` 以停止 Claude Code 下载和加载为每个用户账户[从 claude.ai 同步](https://code.claude.com/docs/zh-CN/plugins/loading.md#synced-plugins)的插件。需要 Claude Code v2.1.273 或更高版本 | 不关闭一个同步插件。为此，在[`enabledPlugins`](https://code.claude.com/docs/zh-CN/settings-reference#enabledplugins)中设置 `"<name>@synced": false` |

185| `disableSideloadFlags` | 拒绝 `--plugin-dir`、`--plugin-url`、`--agents`、Agent SDK `plugins` 选项和非 SDK `--mcp-config` 在启动时，并以相同方式拒绝[`CLAUDE_CODE_PLUGIN_DIRS`](https://code.claude.com/docs/zh-CN/env-vars#variables)变量中命名的文件夹 | 不限制 `.mcp.json`、`claude mcp add` 或 SDK 提供的服务器。将其与[`allowedMcpServers`](https://code.claude.com/docs/zh-CN/managed-mcp)配对 |185| `disableSideloadFlags` | 在启动时拒绝 `--plugin-dir`、`--plugin-url`、`--agents`、Agent SDK `plugins` 选项以及 [`CLAUDE_CODE_PLUGIN_DIRS`](https://code.claude.com/docs/zh-CN/env-vars#variables) 变量中命名的文件夹，并且也拒绝 `--mcp-config`，除非其中的每个服务器都是进程内 `type: "sdk"` 条目。拒绝 Agent SDK 应用程序在会话中途通过 [`addPlugins`](https://code.claude.com/docs/zh-CN/agent-sdk/typescript#load-more-plugin-folders-with-addplugins) 添加的插件文件夹 | 不限制 `.mcp.json`、`claude mcp add` 或 SDK 提供的服务器。将其与[`allowedMcpServers`](https://code.claude.com/docs/zh-CN/managed-mcp)配对 |

187| `allowManagedHooksOnly` | 限制哪些 hooks 运行。请参阅[`allowManagedHooksOnly`](https://code.claude.com/docs/zh-CN/settings-reference#allowmanagedhooksonly) | 不信任用户自己启用的插件中的 hooks |187| `allowManagedHooksOnly` | 限制哪些 hooks 运行。请参阅[`allowManagedHooksOnly`](https://code.claude.com/docs/zh-CN/settings-reference#allowmanagedhooksonly) | 不信任用户自己启用的插件中的 hooks |

188| `strictPluginOnlyCustomization` | 阻止不来自插件、托管设置或 Claude Code 内置的 skill、Agent、hook 和 MCP 服务器。它还会阻止 [skill 目录插件](#keep-skills-directory-plugins-loading)加载。设置 `true` 以覆盖所有四种类型，或 `skills`、`agents`、`hooks` 和 `mcp` 值的数组（例如 `["skills", "hooks"]`）以覆盖某些 | 不限制用户安装哪些插件。将其与 `strictKnownMarketplaces` 配对 |188| `strictPluginOnlyCustomization` | 阻止不来自插件、托管设置或 Claude Code 内置的 skill、Agent、hook 和 MCP 服务器。它还会阻止 [skill 目录插件](#keep-skills-directory-plugins-loading)加载。设置 `true` 以覆盖所有四种类型，或 `skills`、`agents`、`hooks` 和 `mcp` 值的数组（例如 `["skills", "hooks"]`）以覆盖某些 | 不限制用户安装哪些插件。将其与 `strictKnownMarketplaces` 配对 |

191| `allowedChannelPlugins` | 替换允许推送频道消息的默认插件列表。需要 `channelsEnabled: true` | 请参阅[限制哪些频道插件可以运行](https://code.claude.com/docs/zh-CN/channels.md#restrict-which-channel-plugins-can-run) |191| `allowedChannelPlugins` | 替换允许推送频道消息的默认插件列表。需要 `channelsEnabled: true` | 请参阅[限制哪些频道插件可以运行](https://code.claude.com/docs/zh-CN/channels.md#restrict-which-channel-plugins-can-run) |

192| [`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1`](https://code.claude.com/docs/zh-CN/env-vars) | 停止交互式终端会话自动注册官方市场 | 不删除已注册的市场。允许列表和阻止列表在没有它的情况下门控相同的自动注册。在设置它的情况下启动一次的机器在您取消设置它后不会恢复自动注册 |192| [`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1`](https://code.claude.com/docs/zh-CN/env-vars) | 停止交互式终端会话自动注册官方市场 | 不删除已注册的市场。允许列表和阻止列表在没有它的情况下门控相同的自动注册。在设置它的情况下启动一次的机器在您取消设置它后不会恢复自动注册 |

361 361

362来自市场的建议仅在其在用户的机器上注册、您在托管设置中的 `pluginSuggestionMarketplaces` 中列出其名称，并且您在相同策略中声明其源时出现。声明源作为市场的 `extraKnownMarketplaces` 条目或允许列表条目。官方市场仅需要名称。请参阅[在托管设置中启用建议](https://code.claude.com/docs/zh-CN/plugins/relevance.md#enable-suggestions-in-managed-settings)。362来自市场的建议仅在其在用户的机器上注册、您在托管设置中的 `pluginSuggestionMarketplaces` 中列出其名称，并且您在相同策略中声明其源时出现。声明源作为市场的 `extraKnownMarketplaces` 条目或允许列表条目。官方市场仅需要名称。请参阅[在托管设置中启用建议](https://code.claude.com/docs/zh-CN/plugins/relevance.md#enable-suggestions-in-managed-settings)。

363 363

364> [!NOTE]

365>

366> 在云端会话的对话中，无论您是否设置了 `pluginSuggestionMarketplaces`，Claude 都可以建议插件。要关闭这些建议，请参阅[关闭插件建议](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md#turn-off-plugin-suggestions)。

367

364## 审计和审查368## 审计和审查

365 369

366OpenTelemetry 事件和 Analytics API 告诉您您的车队安装和运行什么。370OpenTelemetry 事件和 Analytics API 告诉您您的车队安装和运行什么。

plugins/relevance.md +3 −3

Details

8 8

9Claude Code 可以在用户的会话与您为该插件定义的信号匹配时，建议从您组织的 marketplace 安装插件。信号包括工作目录、Claude 已读取的文件以及 Claude 已运行的命令。您可以通过向 `marketplace.json` 中的插件条目添加 `relevance` 块来定义这些信号。9Claude Code 可以在用户的会话与您为该插件定义的信号匹配时，建议从您组织的 marketplace 安装插件。信号包括工作目录、Claude 已读取的文件以及 Claude 已运行的命令。您可以通过向 `marketplace.json` 中的插件条目添加 `relevance` 块来定义这些信号。

10 10

11marketplace 运营商编写 `relevance` 条目。然后管理员在托管设置中将 marketplace 列入允许列表。在 marketplace 被列入允许列表之前，用户看不到来自该 marketplace 的任何建议。11市场运营商编写 `relevance` 条目。然后管理员在托管设置中将市场列入允许列表。在终端中，市场被列入允许列表之前，用户看不到来自该市场的任何建议。

12 12

13> [!NOTE]13> [!NOTE]

14>14>

15> 这些情况在其他页面上有介绍：15> 这些情况在其他页面上有介绍：

16>16>

17> * **您想安装插件**：请参阅[安装和管理插件](https://code.claude.com/docs/zh-CN/plugins/install.md)17> * **您想安装插件**：请参阅[安装和管理插件](https://code.claude.com/docs/zh-CN/plugins/install.md)

~~18> * **您想关闭建议**：请参阅[了解插件相关性的工作原理](#understand-how-plugin-relevance-works)~~18> * **您想关闭建议**：请参阅[了解插件相关性的工作原理](#understand-how-plugin-relevance-works)；对于 Claude 在云端会话的对话中提出的建议，请参阅[关闭插件建议](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md#turn-off-plugin-suggestions)

19 19

20从适合您角色的部分开始：20从适合您角色的部分开始：

21 21

158 158

159## 在托管设置中启用建议159## 在托管设置中启用建议

160 160

161用户看不到来自 marketplace 的任何建议，直到管理员在 [托管设置](https://code.claude.com/docs/zh-CN/plugins/org.md) 中将其加入允许列表，即使其 `marketplace.json` 声明了 `relevance`。161在终端中，即使市场的 `marketplace.json` 声明了 `relevance`，在管理员于[托管设置](https://code.claude.com/docs/zh-CN/plugins/org.md)中将其加入允许列表之前，用户也看不到来自该市场的任何建议。

162 162

163要将 marketplace 加入允许列表，请按如下方式编辑您的托管设置：163要将 marketplace 加入允许列表，请按如下方式编辑您的托管设置：

164 164

self-hosted-environments-deploy.md +1 −1

Details

810 不可写的基础目录会在启动时停止运行器，而不是使会话失败。请参阅此列表中的 **运行器在启动时退出，显示 `cannot create or write to base directory`** 条目。810 不可写的基础目录会在启动时停止运行器，而不是使会话失败。请参阅此列表中的 **运行器在启动时退出，显示 `cannot create or write to base directory`** 条目。

811* **会话已被拾取，但 Claude 从未回答其第一条消息**：如果您的运行器通过代理访问 `api.anthropic.com`，请将代理配置为在会话的 `/worker/events/stream` 响应到达时立即将其传递出去。提高运行器的超时时间没有帮助。要在运行器的日志中确认原因，请参阅 [会话已被拾取，但 Claude 从未回答其第一条消息](#when-a-sessions-first-message-is-never-answered)。811* **会话已被拾取，但 Claude 从未回答其第一条消息**：如果您的运行器通过代理访问 `api.anthropic.com`，请将代理配置为在会话的 `/worker/events/stream` 响应到达时立即将其传递出去。提高运行器的超时时间没有帮助。要在运行器的日志中确认原因，请参阅 [会话已被拾取，但 Claude 从未回答其第一条消息](#when-a-sessions-first-message-is-never-answered)。

812* **在设置了 `--use-anthropic-git-proxy` 的运行器上会话无法启动**：在运行器的日志中查找 `access denied by the git proxy`，或查找指明包含 `/git_proxy/` 的 `api.anthropic.com` 地址的 git 错误。要判断 Anthropic 是否提供了该会话并修复原因，请参阅 [当会话在使用 git 代理的运行器上无法启动时](#when-anthropic-doesnt-serve-a-session)。812* **在设置了 `--use-anthropic-git-proxy` 的运行器上会话无法启动**：在运行器的日志中查找 `access denied by the git proxy`，或查找指明包含 `/git_proxy/` 的 `api.anthropic.com` 地址的 git 错误。要判断 Anthropic 是否提供了该会话并修复原因，请参阅 [当会话在使用 git 代理的运行器上无法启动时](#when-anthropic-doesnt-serve-a-session)。

813* **会话无法通过身份验证出口代理到达网络**：当您使用 [`--proxy-authorization-command` 或 `--proxy-authorization-file`](#authenticate-to-an-egress-proxy) 设置的源失败、在 30 秒后超时或产生空值时，运行器以 `502 Bad Gateway` 应答该连接并记录原因。运行器在该日志中编辑命令的 stderr，并且永远不会记录标头值。使用 `--proxy-authorization-command` 时，在主机上自己运行该命令以确认它在 stdout 上打印整个标头值。如果运行器改为在启动时退出，显示 `could not start the proxy-authorization listener`，则它无法打开其环回监听器。813* **会话无法通过身份验证出口代理到达网络**：当您使用 [`--proxy-authorization-command` 或 `--proxy-authorization-file`](#authenticate-to-an-egress-proxy) 设置的源失败、在 30 秒后超时或产生空值时，运行器以 `502 Bad Gateway` 应答该连接并记录原因。运行器在该日志中对命令的 stderr 进行脱敏，并且永远不会记录标头值。使用 `--proxy-authorization-command` 时，在主机上自己运行该命令以确认它在 stdout 上打印整个标头值。如果运行器改为在启动时退出，显示 `could not start the proxy-authorization listener`，则它无法打开其环回监听器。

814* **运行器记录包含 `rejecting the malformed poll response` 的 `Poll failed` 行**：运行器收到的工作轮询响应的正文不是队列的预期 JSON。原因之一是拦截代理或强制门户用自己的页面进行了应答。如果运行器通过代理连接，请配置代理以将来自 `api.anthropic.com` 的响应原封不动地传递。814* **运行器记录包含 `rejecting the malformed poll response` 的 `Poll failed` 行**：运行器收到的工作轮询响应的正文不是队列的预期 JSON。原因之一是拦截代理或强制门户用自己的页面进行了应答。如果运行器通过代理连接，请配置代理以将来自 `api.anthropic.com` 的响应原封不动地传递。

815 815

816 运行器拒绝该格式错误的响应，在 `claude_code_self_hosted_runner_poll_errors_total` [指标](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference.md#prometheus-metrics) 的 `transport` 类型下计数，并按 [会话生命周期](https://code.claude.com/docs/zh-CN/self-hosted-environments#session-lifecycle) 中描述的失败轮询计划重试。运行器继续为其实时会话提供服务。在 v2.1.246 之前，运行器将这样的响应读取为空工作队列，这可能会结束其实时会话或使其退出。816 运行器拒绝该格式错误的响应，在 `claude_code_self_hosted_runner_poll_errors_total` [指标](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference.md#prometheus-metrics) 的 `transport` 类型下计数，并按 [会话生命周期](https://code.claude.com/docs/zh-CN/self-hosted-environments#session-lifecycle) 中描述的失败轮询计划重试。运行器继续为其实时会话提供服务。在 v2.1.246 之前，运行器将这样的响应读取为空工作队列，这可能会结束其实时会话或使其退出。

self-hosted-environments-reference.md +1 −1

Details

46| `--post-session-hook-timeout-sec <n>` | `SELF_HOSTED_RUNNER_POST_SESSION_HOOK_TIMEOUT_MS` | `60` | 每次会话结束时（包括 runner 关闭时）[`post-session` hook](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#post-session) 的时间预算 |46| `--post-session-hook-timeout-sec <n>` | `SELF_HOSTED_RUNNER_POST_SESSION_HOOK_TIMEOUT_MS` | `60` | 每次会话结束时（包括 runner 关闭时）[`post-session` hook](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#post-session) 的时间预算 |

47| `--proxy-authorization-command <command>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_COMMAND` | 未设置 | runner 在每次连接您的出口代理时运行的 shell 命令，其去除首尾空白后的 stdout 用作 `Proxy-Authorization` 标头值。需要 `HTTPS_PROXY` 或 `HTTP_PROXY`，且不能与 `--proxy-authorization-file` 同时使用。请参阅[向出口代理进行身份验证](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#authenticate-to-an-egress-proxy)。需要 Claude Code v2.1.238 或更高版本。 |47| `--proxy-authorization-command <command>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_COMMAND` | 未设置 | runner 在每次连接您的出口代理时运行的 shell 命令，其去除首尾空白后的 stdout 用作 `Proxy-Authorization` 标头值。需要 `HTTPS_PROXY` 或 `HTTP_PROXY`，且不能与 `--proxy-authorization-file` 同时使用。请参阅[向出口代理进行身份验证](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#authenticate-to-an-egress-proxy)。需要 Claude Code v2.1.238 或更高版本。 |

48| `--proxy-authorization-file <path>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_FILE` | 未设置 | runner 在每次连接您的出口代理时读取的文件，其去除首尾空白后的内容用作 `Proxy-Authorization` 标头值。对于由其他进程原地轮换的令牌，请使用此标志。要求与 `--proxy-authorization-command` 相同，且不能与其同时使用。请参阅[向出口代理进行身份验证](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#authenticate-to-an-egress-proxy)。需要 Claude Code v2.1.238 或更高版本。 |48| `--proxy-authorization-file <path>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_FILE` | 未设置 | runner 在每次连接您的出口代理时读取的文件，其去除首尾空白后的内容用作 `Proxy-Authorization` 标头值。对于由其他进程原地轮换的令牌，请使用此标志。要求与 `--proxy-authorization-command` 相同，且不能与其同时使用。请参阅[向出口代理进行身份验证](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#authenticate-to-an-egress-proxy)。需要 Claude Code v2.1.238 或更高版本。 |

49| `--push-outcome-on-release` | `SELF_HOSTED_RUNNER_PUSH_OUTCOME_ON_RELEASE` | 关闭 | 在由 runner 发起的会话结束（例如排空或空闲释放）时，在删除工作区之前将跟踪的结果分支推送到 `origin`，以便进行中的提交在重启后得以保留。尽力而为；会为关闭预算增加 30 秒，且需要 git 2.29 或更高版本才能从推送的分支恢复。启用前请将推送权限限制为 `claude/*` 引用；请参阅[恢复的会话会丢失未推送的工作](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#additional-limitations)。通过 `checkout` 生命周期 hook 检出的仓库不会被推送；请改为在 [`post-session` hook](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#post-session) 中为其创建快照。 |49| `--push-outcome-on-release` | `SELF_HOSTED_RUNNER_PUSH_OUTCOME_ON_RELEASE` | 关闭 | 在由 runner 发起的会话结束（例如排空或空闲释放）时，在删除工作区之前将跟踪的结果分支推送到 `origin`，以便进行中的提交在重启后得以保留。尽力而为；会为关闭预算增加 30 秒，且需要 git 2.29 或更高版本才能从推送的分支恢复。启用前请限制谁可以推送到 `claude/*` 引用；请参阅[恢复的会话会丢失未推送的工作](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#additional-limitations)。通过 `checkout` 生命周期 hook 检出的仓库不会被推送；请改为在 [`post-session` hook](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#post-session) 中为其创建快照。 |

50| `--release-idle-session-min <n>` | `SELF_HOSTED_RUNNER_SESSION_IDLE_MS` | `0` | 在轮次结束或会话等待用户操作后，若不活动达 N 分钟，则释放会话槽位。仍处于轮次中的会话（包括持有永不结束的后台任务的会话，或在正在运行的工具调用内部请求了批准的会话）不计为空闲；请搭配 `--kill-session-after-min` 作为硬性兜底。会话的后台任务完成后，runner 会将该会话视为忙碌，直到读取结果的后续轮次开始为止，最长不超过 [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings) 窗口。在 runner 收到关闭信号或到达其退役时间之前，如果一次释放使 runner 不再有活动会话，则会启动与正常排空相同的退出流程，由 `--drain-grace-sec` 控制。如果您使用 [`--defer-shutdown-max-min`](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal) 推迟了第一个信号，则一旦某次释放使 runner 不再持有任何会话，runner 就会立即退出。`0` 表示禁用。 |50| `--release-idle-session-min <n>` | `SELF_HOSTED_RUNNER_SESSION_IDLE_MS` | `0` | 在轮次结束或会话等待用户操作后，若不活动达 N 分钟，则释放会话槽位。仍处于轮次中的会话（包括持有永不结束的后台任务的会话，或在正在运行的工具调用内部请求了批准的会话）不计为空闲；请搭配 `--kill-session-after-min` 作为硬性兜底。会话的后台任务完成后，runner 会将该会话视为忙碌，直到读取结果的后续轮次开始为止，最长不超过 [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings) 窗口。在 runner 收到关闭信号或到达其退役时间之前，如果一次释放使 runner 不再有活动会话，则会启动与正常排空相同的退出流程，由 `--drain-grace-sec` 控制。如果您使用 [`--defer-shutdown-max-min`](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal) 推迟了第一个信号，则一旦某次释放使 runner 不再持有任何会话，runner 就会立即退出。`0` 表示禁用。 |

51| `--remove-session-state [bool]` | `SELF_HOSTED_RUNNER_REMOVE_SESSION_STATE` | 关闭 | 当会话在此 runner 上结束时，无论结果如何，都删除该会话在 `<base-dir>/_sessions/` 下的每会话目录。[复用预热的检出](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#reuse-a-pre-warmed-checkout)介绍了这些目录保存的内容，以及它们保留时谁可以读取。删除是尽力而为的：如果 runner 在清理运行之前被终止或到达其排空截止时间，每会话目录将保留原位。启用该标志后，失败或中断的会话的调试日志不会保留在磁盘上。需要 Claude Code v2.1.268 或更高版本。 |51| `--remove-session-state [bool]` | `SELF_HOSTED_RUNNER_REMOVE_SESSION_STATE` | 关闭 | 当会话在此 runner 上结束时，无论结果如何，都删除该会话在 `<base-dir>/_sessions/` 下的每会话目录。[复用预热的检出](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#reuse-a-pre-warmed-checkout)介绍了这些目录保存的内容，以及它们保留时谁可以读取。删除是尽力而为的：如果 runner 在清理运行之前被终止或到达其排空截止时间，每会话目录将保留原位。启用该标志后，失败或中断的会话的调试日志不会保留在磁盘上。需要 Claude Code v2.1.268 或更高版本。 |

52| `--retire-at <epoch-seconds>` | `SELF_HOSTED_RUNNER_RETIRE_AT` | 未设置 | 在以秒为单位的绝对 Unix 时间戳处让 runner 退役，适用于会在已知时间终止 runner 的基础设施；[Runner 生命周期](https://code.claude.com/docs/zh-CN/self-hosted-environments#runner-lifecycle)介绍了释放顺序以及如何确定余量。早于 2001 年或晚于 5138 年的值会被该标志拒绝，并被该环境变量忽略。 |52| `--retire-at <epoch-seconds>` | `SELF_HOSTED_RUNNER_RETIRE_AT` | 未设置 | 在以秒为单位的绝对 Unix 时间戳处让 runner 退役，适用于会在已知时间终止 runner 的基础设施；[Runner 生命周期](https://code.claude.com/docs/zh-CN/self-hosted-environments#runner-lifecycle)介绍了释放顺序以及如何确定余量。早于 2001 年或晚于 5138 年的值会被该标志拒绝，并被该环境变量忽略。 |

server-managed-settings.md +3 −1

Details

170 170

171**后续启动且有缓存的设置：**171**后续启动且有缓存的设置：**

172 172

173* 缓存的设置在启动时立即应用，除了缓存的 `modelPricing` 和 `managedMcpServers` 值以及 Claude Code 在服务器确认有效负载之前暂扣的环境变量173* 缓存的设置在启动时立即应用，但以下情况除外：缓存的 `modelPricing` 和 `managedMcpServers` 值；Claude Code 在服务器确认负载之前暂扣的环境变量；缓存的插件列表对[内置守卫](https://code.claude.com/docs/zh-CN/plugins/mods/admin.md#know-what-happens-by-default)的移除、重新定位或禁用；以及在端点管理的源自行列出或启用插件的机器上，仅由缓存列表启用的插件的[组织归属](https://code.claude.com/docs/zh-CN/plugins/mods/admin.md#install-your-organizations-mods)

174* 缓存的 [`modelPricing`](https://code.claude.com/docs/zh-CN/settings-reference#modelpricing) 在会话的获取确认有效负载前不适用。在那之前，开发者在 `/usage` 中看到的成本数字和状态行处于列表价格174* 缓存的 [`modelPricing`](https://code.claude.com/docs/zh-CN/settings-reference#modelpricing) 在会话的获取确认有效负载前不适用。在那之前，开发者在 `/usage` 中看到的成本数字和状态行处于列表价格

175* 缓存的 [`managedMcpServers`](https://code.claude.com/docs/zh-CN/settings-reference#managedmcpservers) 块在会话的获取确认有效负载前不适用。Claude Code 在连接 MCP 服务器前最多等待 30 秒以获取。如果获取失败或超时，会话启动时不使用组织的服务器，`/status` 会说明这一点，它们在后续获取确认它们后连接。有关完整行为（包括首次启动），请参阅[何时提供的服务器连接](https://code.claude.com/docs/zh-CN/managed-mcp.md#when-provided-servers-connect)。需要 Claude Code v2.1.259 或更高版本175* 缓存的 [`managedMcpServers`](https://code.claude.com/docs/zh-CN/settings-reference#managedmcpservers) 块在会话的获取确认有效负载前不适用。Claude Code 在连接 MCP 服务器前最多等待 30 秒以获取。如果获取失败或超时，会话启动时不使用组织的服务器，`/status` 会说明这一点，它们在后续获取确认它们后连接。有关完整行为（包括首次启动），请参阅[何时提供的服务器连接](https://code.claude.com/docs/zh-CN/managed-mcp.md#when-provided-servers-connect)。需要 Claude Code v2.1.259 或更高版本

176* 缓存的 [`prependPlugins`](https://code.claude.com/docs/zh-CN/settings-reference#prependplugins)、[`appendPlugins`](https://code.claude.com/docs/zh-CN/settings-reference#appendplugins) 或 [`enabledPlugins`](https://code.claude.com/docs/zh-CN/settings-reference#enabledplugins) 值在会话的获取确认负载之前，无法移除内置守卫、更改其位置或将其关闭

177* 在[端点管理的源](https://code.claude.com/docs/zh-CN/managed-settings.md#choose-a-delivery-mechanism)自行列出或启用插件的机器上，仅由缓存列表启用的插件在获取确认负载之前被视为[用户的](https://code.claude.com/docs/zh-CN/plugins/mods/admin.md#install-your-organizations-mods)插件，而非您组织的插件

176* Claude Code 在后台获取新鲜设置178* Claude Code 在后台获取新鲜设置

177* 缓存的设置通过网络故障持久化。如果启动获取失败，Claude Code 在交互式会话中警告缓存的策略有效179* 缓存的设置通过网络故障持久化。如果启动获取失败，Claude Code 在交互式会话中警告缓存的策略有效

178* 在某次获取成功之前，启动时被暂扣的值保持暂扣状态180* 在某次获取成功之前，启动时被暂扣的值保持暂扣状态

sessions.md +1 −1

Details

249 249

250默认情况下，Claude Code 将文本记录存储为 JSONL，位置为 `~/.claude/projects/<project>/<session-id>.jsonl`，其中 `<project>` 是您的工作目录路径，非字母数字字符被替换为 `-`。对于转换后的名称超过 200 个字符的工作目录，Claude Code 将名称截断为 200 个字符，并附加完整路径的哈希值，以便目录名称保持在文件系统限制范围内。250默认情况下，Claude Code 将文本记录存储为 JSONL，位置为 `~/.claude/projects/<project>/<session-id>.jsonl`，其中 `<project>` 是您的工作目录路径，非字母数字字符被替换为 `-`。对于转换后的名称超过 200 个字符的工作目录，Claude Code 将名称截断为 200 个字符，并附加完整路径的哈希值，以便目录名称保持在文件系统限制范围内。

251 251

252每行是消息、工具使用或元数据条目的 JSON 对象。条目格式是 Claude Code 的内部格式，在版本之间会发生变化，因此直接解析这些文件的脚本可能在任何版本上中断。要基于会话数据构建，请改用 `/export` 或 [脚本接口](#access-conversations-from-scripts)。252每行是一个 JSON 对象：消息、工具使用或结果、Claude Code 向模型发送的请求的记录，或元数据条目。条目格式是 Claude Code 的内部格式，在版本之间会发生变化，因此直接解析这些文件的脚本可能在任何版本上中断。要基于会话数据构建，请改用 `/export` 或 [脚本接口](#access-conversations-from-scripts)。

253 253

254位置、保留期和写入行为是可配置的：254位置、保留期和写入行为是可配置的：

255 255

settings-reference.md +8 −5

Details

2037* **类型**：字符串数组，每项是一个服务名称；单个末尾 `*` 匹配前缀，单独的 `"*"` 匹配所有服务2037* **类型**：字符串数组，每项是一个服务名称；单个末尾 `*` 匹配前缀，单独的 `"*"` 匹配所有服务

2038* **默认值**：未设置2038* **默认值**：未设置

2039 2039

2040以下配置允许 `com.apple.coresimulator.` 前缀下的所有服务：2040以下配置允许 `com.apple.CoreSimulator.` 前缀下的所有服务：

2041 2041

2042```json settings.json theme={null}2042```json settings.json theme={null}

2043{2043{

2044 "sandbox": {2044 "sandbox": {

2045 "network": {2045 "network": {

2046 "allowMachLookup": ["com.apple.coresimulator.*"]2046 "allowMachLookup": ["com.apple.CoreSimulator.*"]

2047 }2047 }

2048 }2048 }

2049}2049}

4729* **类型**：字符串数组，相对于仓库根目录的目录路径4729* **类型**：字符串数组，相对于仓库根目录的目录路径

4730* **默认值**：未设置，因此每个 worktree 检出整个树4730* **默认值**：未设置，因此每个 worktree 检出整个树

4731 4731

4732以下示例在每个 worktree 中仅检出 `packages/my-app` 和 `shared/utils` 以及根级文件：4732请在列表中包含 `.claude`，以便每个 worktree 中也包含仓库的 `.claude/settings.json` 和 `.claude/rules/`。以下示例在每个 worktree 中仅检出 `.claude`、`packages/my-app` 和 `shared/utils` 以及根级文件：

4733 4733

4734```json settings.json theme={null}4734```json settings.json theme={null}

4735{4735{

4736 "worktree": {4736 "worktree": {

4737 "sparsePaths": ["packages/my-app", "shared/utils"]4737 "sparsePaths": [".claude", "packages/my-app", "shared/utils"]

4738 }4738 }

4739}4739}

4740```4740```

5525 5525

5526如果 `--mcp-config` 中的服务器全部是进程内 `type: "sdk"` 条目，Claude Code 仍会接受它，因此 Agent SDK 和 VS Code 扩展可以继续正常工作。用户仍然可以通过 `claude mcp add` 或 `.mcp.json` 文件添加服务器；如需按服务器进行控制，请同时设置 [`allowedMcpServers`](https://code.claude.com/docs/zh-CN/managed-mcp)。需要 Claude Code v2.1.193 或更高版本。5526如果 `--mcp-config` 中的服务器全部是进程内 `type: "sdk"` 条目，Claude Code 仍会接受它，因此 Agent SDK 和 VS Code 扩展可以继续正常工作。用户仍然可以通过 `claude mcp add` 或 `.mcp.json` 文件添加服务器；如需按服务器进行控制，请同时设置 [`allowedMcpServers`](https://code.claude.com/docs/zh-CN/managed-mcp)。需要 Claude Code v2.1.193 或更高版本。

5527 5527

5528同样的检查也适用于 [`CLAUDE_CODE_PLUGIN_DIRS`](https://code.claude.com/docs/zh-CN/env-vars#variables) 环境变量中指定的插件文件夹，这需要 Claude Code v2.1.280 或更高版本。当该变量指定了文件夹时，Claude Code 会以相同的错误退出，并且错误信息会提示取消设置该变量。5528`disableSideloadFlags` 还会拒绝来自以下来源的插件文件夹：

5529

5530* **[`CLAUDE_CODE_PLUGIN_DIRS`](https://code.claude.com/docs/zh-CN/env-vars#variables) 环境变量**：当该变量指定了插件文件夹时，Claude Code 会在启动时退出，并显示一条指出该变量并提示取消设置它的错误。需要 Claude Code v2.1.280 或更高版本

5531* **Agent SDK [`addPlugins`](https://code.claude.com/docs/zh-CN/agent-sdk/typescript#load-more-plugin-folders-with-addplugins) 选项**：当应用程序在 `addPlugins` 中将插件文件夹传递给 `reloadPlugins()` 时，该调用会失败并报错。会话将继续运行，并保留其已有的插件。需要 Claude Code v2.1.301 或更高版本

5529 5532

5530在云端会话中，Claude Code 还会忽略服务器在会话中途下发的 MCP 更新，云端会话配置以及到达这些会话的 SDK `setMcpServers()` 调用都是通过这一路径生效的。在这里，进程内 `type: "sdk"` 条目和 Claude Tag 会话的 Slack 工具同样不受影响。在 v2.1.268 之前，这种丢弃和启动时的丢弃也会移除 Claude Tag 会话的 Slack 工具。在 v2.1.239 之前，服务器下发的 `--mcp-config` 会导致云端会话无法启动。5533在云端会话中，Claude Code 还会忽略服务器在会话中途下发的 MCP 更新，云端会话配置以及到达这些会话的 SDK `setMcpServers()` 调用都是通过这一路径生效的。在这里，进程内 `type: "sdk"` 条目和 Claude Tag 会话的 Slack 工具同样不受影响。在 v2.1.268 之前，这种丢弃和启动时的丢弃也会移除 Claude Tag 会话的 Slack 工具。在 v2.1.239 之前，服务器下发的 `--mcp-config` 会导致云端会话无法启动。

5531 5534

vs-code.md +36 −17

Details

203What's in @src/components/ (include a trailing slash for folders)203What's in @src/components/ (include a trailing slash for folders)

204```204```

205 205

206对于大型 PDF，您可以让 Claude 读取特定页面而不是整个文件。可以请求单个页面、诸如第 1-10 页的范围，或诸如第 3 页起的开放范围。读取特定页面需要在运行 Claude Code 的计算机上安装 [poppler-utils](https://code.claude.com/docs/zh-CN/tools-reference.md#read-tool-behavior)。206### 读取 PDF 的特定页面

~~207~~

208当您在编辑器中选择文本时，Claude 会自动看到您高亮显示的代码。输入框底部会显示已选择的行数。按 `Option+K`（Mac）/ `Alt+K`（Windows/Linux）可插入包含文件路径和行号的 @ 提及，例如 `@app.ts#5-10`。点击选择指示器上的 **X** 可将其移除，这样 Claude 就不会收到所选内容。当您选择其他文本时，指示器会重新出现。

209 207

210扩展不会发送某些文件中的所选文本：208对于大型 PDF，您可以让 Claude 读取特定页面而不是整个文件。可以请求单个页面、诸如第 1-10 页的范围，或诸如第 3 页起的开放范围。读取特定页面需要在运行 Claude Code 的计算机上安装 [poppler-utils](https://code.claude.com/docs/zh-CN/tools-reference.md#read-tool-behavior)。

~~211~~

212* 当文件位于您的工作区内且匹配您的 `files.exclude` 或 `search.exclude` 设置时，Claude 最多只会收到文件路径，而不会收到您所选的文本。

213* 这同样适用于被 git 忽略的文件，前提是 VS Code 的 `search.useIgnoreFiles` 设置和扩展的 [`respectGitIgnore` 设置](#extension-settings)都已打开（默认如此）。

214 209

215此筛选仅适用于聊天面板。当 Claude Code 在集成终端中运行时，无论是什么文件，CLI 都会发送您所选的文本。要在终端中阻止 Claude 获取文件内容，请添加 [`Read` 拒绝规则](#the-built-in-ide-mcp-server)。210### 在提示词中包含终端输出

216 211

217即使没有选择任何内容，Claude 也能看到您在编辑器中打开的是哪个文件，输入框会显示其名称。如果只想添加您所选的文本，请关闭 [Attach Open File 设置](vscode://settings/claudeCode.attachOpenFile)。该设置需要 Claude Code v2.1.271 或更高版本。212在提示词中使用 `@terminal:name` 引用终端输出，其中 `name` 是终端的标题。这样 Claude 无需复制粘贴即可看到命令输出、错误消息或日志。

218 213

219您还可以将图片和文件附加到消息中：214### 附加图片和文件

220 215

221* 要附加图片，请将其从剪贴板粘贴到输入框中。216* 要附加图片，请将其从剪贴板粘贴到输入框中。

222* 要附加文件，请按住 `Shift` 将其拖入输入框。217* 要附加文件，请按住 `Shift` 将其拖入输入框。

223* 要从上下文中移除附件，请点击附件上的 X。218* 要从上下文中移除附件，请点击附件上的 X。

224 219

225### 在提示词中包含终端输出

~~226~~

227在提示词中使用 `@terminal:name` 引用终端输出，其中 `name` 是终端的标题。这样 Claude 无需复制粘贴即可看到命令输出、错误消息或日志。

~~228~~

229### 粘贴文本220### 粘贴文本

230 221

231您粘贴的文本会在输入框中保持可见，而不会像[在终端中](https://code.claude.com/docs/zh-CN/terminal-config.md#paste-large-content)那样折叠为占位符。在 Claude Code [标记粘贴文本](https://code.claude.com/docs/zh-CN/terminal-config.md#how-claude-treats-pasted-text)的会话中，Claude 仍会将大段粘贴内容视为您粘贴而非输入的文本。222您粘贴的文本会在输入框中保持可见，而不会像[在终端中](https://code.claude.com/docs/zh-CN/terminal-config.md#paste-large-content)那样折叠为占位符。在 Claude Code [标记粘贴文本](https://code.claude.com/docs/zh-CN/terminal-config.md#how-claude-treats-pasted-text)的会话中，Claude 仍会将大段粘贴内容视为您粘贴而非输入的文本。

235* 如果粘贴时出现 `Removed 3 invisible characters from the pasted text` 之类的通知，则表示文本已去除这些字符后放入输入框。226* 如果粘贴时出现 `Removed 3 invisible characters from the pasted text` 之类的通知，则表示文本已去除这些字符后放入输入框。

236* 如果发送时出现有关已移除字符的通知，则表示没有发送任何内容。清理后的文本会回到输入框中。再次发送即可按显示的内容发送文本。227* 如果发送时出现有关已移除字符的通知，则表示没有发送任何内容。清理后的文本会回到输入框中。再次发送即可按显示的内容发送文本。

237 228

229### 根据所选内容和打开的文件自动提供上下文

230

231当您在编辑器中选择文本时，Claude 会自动看到您高亮显示的代码。输入框底部会显示已选择的行数。即使没有选择任何内容，Claude 也能看到您在编辑器中打开的是哪个文件，输入框会显示其名称。

232

233按 `Option+K`（Mac）/ `Alt+K`（Windows/Linux）可插入包含文件路径和行号的 @ 提及，例如 `@app.ts#5-10`。

234

235#### 不让所选内容和打开的文件进入您的消息

236

237要阻止所选文本或打开的文件进入您的消息，请在 VS Code 的设置中关闭相应的设置项：

238

239* **所选文本**：关闭 [Attach Selection 设置](vscode://settings/claudeCode.attachSelection)。需要 Claude Code v2.1.300 或更高版本。要移除某一次选择，请点击行数旁边的 **X**。当您选择其他文本时，行数会重新出现。

240* **打开的文件**：关闭 [Attach Open File 设置](vscode://settings/claudeCode.attachOpenFile)。需要 Claude Code v2.1.271 或更高版本。除非您的消息包含您在该文件中所选的文本，否则该文件不会被包含在内。

241

242在关闭 Attach Selection 的情况下，要将文本作为 @ 提及添加，请选择该文本，然后在 Mac 上按 `Option+K`，在 Windows 和 Linux 上按 `Alt+K`。

243

244在 VS Code 的集成终端中运行 `claude` 时，这两个设置同样适用。

245

246#### 来自排除或忽略文件的所选文本

247

248在聊天面板中，扩展不会发送某些文件中的所选文本：

249

250* 当文件位于您的工作区内且匹配您的 `files.exclude` 或 `search.exclude` 设置时，Claude 最多只会收到文件路径，而不会收到您所选的文本。

251* 这同样适用于被 git 忽略的文件，前提是 VS Code 的 `search.useIgnoreFiles` 设置和扩展的 [`respectGitIgnore` 设置](#extension-settings)都已打开（默认如此）。

252

253此筛选仅适用于聊天面板。当 Claude Code 在集成终端中运行时，Claude 可以收到您在这些文件中所选的文本。要在终端中阻止 Claude 获取文件内容，请添加 [`Read` 拒绝规则](https://code.claude.com/docs/zh-CN/permissions#read-and-edit)。

254

238### 回复中的 LaTeX 数学公式255### 回复中的 LaTeX 数学公式

239 256

240聊天面板会将 Claude 回复中的 LaTeX 数学公式显示为排版后的公式。数学公式渲染需要 Claude Code v2.1.301 或更高版本。在[终端模式](#switch-to-terminal-mode)下，数学公式不会被排版。面板会同时排版独立公式和行内公式：257聊天面板会将 Claude 回复中的 LaTeX 数学公式显示为排版后的公式。数学公式渲染需要 Claude Code v2.1.301 或更高版本。在[终端模式](#switch-to-terminal-mode)下，数学公式不会被排版。面板会同时排版独立公式和行内公式：

695| `lockEditorGroups` | `true` | [锁定 Claude 为其标签页启动的编辑器组](#choose-where-claude-lives)，这样在 Claude 标签页获得焦点时打开的文件会进入另一个编辑器组。关闭时，扩展永远不会锁定编辑器组。需要 Claude Code v2.1.274 或更高版本 |712| `lockEditorGroups` | `true` | [锁定 Claude 为其标签页启动的编辑器组](#choose-where-claude-lives)，这样在 Claude 标签页获得焦点时打开的文件会进入另一个编辑器组。关闭时，扩展永远不会锁定编辑器组。需要 Claude Code v2.1.274 或更高版本 |

715| `attachSelection` | `true` | 将您在编辑器中选中的文本添加到您的消息中，并在输入框中显示。关闭时，您仍然可以[将选区作为 @-mention 添加](#automatic-context-from-your-selection-and-open-file)。需要 Claude Code v2.1.300 或更高版本 |

707| `focusView` | `false` | 将工具调用、工具结果和思考内容隐藏在可展开的行中，仅保留您的提示词和 Claude 的回复。Claude 最新的待办事项列表保持可见；这需要 Claude Code v2.1.225 或更高版本。您也可以从命令菜单中切换 Focus view。需要 Claude Code v2.1.221 或更高版本 |725| `focusView` | `false` | 将工具调用、工具结果和思考内容隐藏在可展开的行中，仅保留您的提示词和 Claude 的回复。Claude 最新的待办事项列表保持可见；这需要 Claude Code v2.1.225 或更高版本。您也可以从命令菜单中切换 Focus view。需要 Claude Code v2.1.221 或更高版本 |

710| `environmentVariables` | `[]` | 为 Claude 进程设置环境变量。如需共享配置，请改用 Claude Code 设置。[`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-CN/env-vars) 条目仅在其值为绝对路径时生效；扩展不会展开 `~`，并会忽略相对路径值。 |728| `environmentVariables` | `[]` | 为 Claude 进程设置环境变量。如需共享配置，请改用 Claude Code 设置。[`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-CN/env-vars) 条目仅在其值为绝对路径时生效；扩展不会展开 `~`，并会忽略相对路径值。 |

835 853

836**选中内容和已打开文件上下文。** 连接期间，CLI 会在您发送的每条提示词中附带当前编辑器的选中内容以及活动文件的路径作为上下文。发生这种情况时，会话记录中会显示一行 `⧉ Selected N lines from <file>`。以下情况会改变该上下文：854**选中内容和已打开文件上下文。** 连接期间，CLI 会在您发送的每条提示词中附带当前编辑器的选中内容以及活动文件的路径作为上下文。发生这种情况时，会话记录中会显示一行 `⧉ Selected N lines from <file>`。以下情况会改变该上下文：

837 855

856* **关闭 [Attach Selection 设置](#keep-your-selection-and-open-file-out-of-your-messages)**：CLI 不会将您的选中内容作为上下文附带。

857* **关闭 Attach Open File 设置**：只有在同时附带选中内容时，CLI 才会附带活动文件的路径。

838* **排队的消息**：如果您[在 Claude 工作时将消息加入队列](https://code.claude.com/docs/zh-CN/interactive-mode.md#queue-messages-while-claude-works)，该消息会保留您按下 `Enter` 时的选中内容，无论您之后选中了什么。858* **排队的消息**：如果您[在 Claude 工作时将消息加入队列](https://code.claude.com/docs/zh-CN/interactive-mode.md#queue-messages-while-claude-works)，该消息会保留您按下 `Enter` 时的选中内容，无论您之后选中了什么。

839* **敏感文件**：要排除 `.env` 等敏感文件，请为其路径添加 [`Read` 拒绝规则](https://code.claude.com/docs/zh-CN/permissions#read-and-edit)。匹配的拒绝规则会阻止该文件的选中文本和已打开文件通知发送给 Claude。859* **敏感文件**：要排除 `.env` 等敏感文件，请为其路径添加 [`Read` 拒绝规则](https://code.claude.com/docs/zh-CN/permissions#read-and-edit)。匹配的拒绝规则会阻止该文件的选中文本和已打开文件通知发送给 Claude。

840* **关闭 Attach Open File**：如果您关闭了 [Attach Open File 设置](#extension-settings)，则只有在活动文件中有选中文本时，CLI 才会收到该文件的路径。

841 860

842**传输和身份验证。** 该服务器绑定到 `127.0.0.1` 上 10000–65535 范围内的随机端口，端口不可配置。传输方式和身份验证令牌的工作方式如下：861**传输和身份验证。** 该服务器绑定到 `127.0.0.1` 上 10000–65535 范围内的随机端口，端口不可配置。传输方式和身份验证令牌的工作方式如下：

843 862

workflows.md +67 −66

Details

333 333

334工作流运行时在隔离的环境中执行脚本，与您的对话分离。中间结果保留在脚本变量中，而不是进入 Claude 的上下文。334工作流运行时在隔离的环境中执行脚本，与您的对话分离。中间结果保留在脚本变量中，而不是进入 Claude 的上下文。

335 335

336每次运行都会将其脚本写入您会话目录下 `~/.claude/projects/` 中的文件。Claude 在运行开始时接收路径，因此您可以要求它提供路径。您可以打开该文件来读取 Claude 编写的编排，将其与之前运行的脚本进行对比，或编辑它并要求 Claude 从编辑后的版本重新启动。336除非 Claude 从脚本文件的路径启动运行，否则 Claude Code 会将该次运行的脚本写入您会话目录下 `~/.claude/projects/` 中的文件。Claude 在运行开始时接收脚本的路径，因此您可以要求它提供该路径。您可以打开该文件来读取 Claude 编写的编排，将其与之前运行的脚本进行对比，或编辑它并要求 Claude 从编辑后的版本重新启动。

337 337

338Claude 只能从会话已允许读取的脚本文件启动工作流。要运行保存在工作目录外的脚本，请先使用 [`/add-dir`](https://code.claude.com/docs/zh-CN/permissions#working-directories) 或 [Read allow rule](https://code.claude.com/docs/zh-CN/permissions.md#read-and-edit) 添加其目录。338Claude 只能从会话已允许读取的脚本文件启动工作流。要运行保存在工作目录外的脚本，请先使用 [`/add-dir`](https://code.claude.com/docs/zh-CN/permissions#working-directories) 或 [Read allow rule](https://code.claude.com/docs/zh-CN/permissions.md#read-and-edit) 添加其目录。

339 339

363 363

364## 管理运行364## 管理运行

365 365

366运行启动后，您可以从 `/workflows` 视图管理它，或通过展开输入框下方任务面板中的其进度行来管理。366运行开始后，您可以在 `/workflows` 视图中管理它，也可以展开输入框下方任务面板中该运行的进度行进行管理。

367 367

368当您停止运行时，它会保留在任务面板中，直到其任何代理的进程仍在运行。如果您再次停止它，Claude Code 会重新向这些进程发送信号。368停止运行后，只要其任何 Agent 的进程仍在运行，该运行就会一直保留在任务面板中。如果您再次停止它，Claude Code 会重新向这些进程发送信号。

369 369

370### 暂停后恢复370### 暂停后恢复

371 371

372从 `/workflows` 恢复暂停的运行，选择它并按 `p`。对于您停止的运行，要求 Claude 使用相同脚本重新启动工作流。如果来自已停止运行的代理尚未退出，Claude Code 会拒绝重新启动，直到它们退出，这样这些代理的第二个副本就不会与它们并行运行。372要恢复已暂停的运行，请在 `/workflows` 中选中它并按 `p`。对于您已停止的运行，请让 Claude 使用同一脚本重新启动该工作流。如果已停止运行中的 Agent 尚未退出，Claude Code 会拒绝重新启动，直到它们退出为止，以免这些 Agent 的第二个副本与它们同时运行。

373 373

374#### 哪些 Agent 会再次运行374#### 哪些 Agent 会再次运行

375 375

376Claude Code 按 Agent 启动的顺序重放运行，每个 Agent 要么返回其保存的结果，要么再次运行：376Claude Code 按 Agent 的启动顺序重放运行，每个 Agent 要么返回其保存的结果，要么再次运行：

377 377

378* **已完成**：返回其保存的结果。第一个提示与之前运行不同的代理（因为您编辑了脚本或较早的代理返回了不同的内容）会再次运行，之后的每个代理也会再次运行，即使是已完成的代理。378* **已完成**：返回其保存的结果。第一个提示词与上一次运行不同的 Agent（因为您编辑了脚本，或者前面的某个 Agent 返回了不同的内容）会再次运行，其后的每个 Agent 也会再次运行，即使它们已经完成。

379 379

380 在 v2.1.305 之前，当您重新启动一个未经编辑的脚本，且其 `pipeline()` 项或 `parallel()` 任务各自运行了多个 Agent 时，已完成的 Agent 也可能再次运行。要让新的运行不再出现这类重新运行，请更新 Claude Code。380 在 v2.1.305 之前，如果您重新启动一个未经编辑的脚本，而该脚本的 `pipeline()` 项或 `parallel()` 任务各自运行了多个 Agent，已完成的 Agent 也可能再次运行。要让新的运行不再出现这类重复运行，请更新 Claude Code。

381* **停止时仍在运行**：重新开始。停止整个运行不会将任何代理计为失败。381* **停止时仍在运行**：从头开始。停止整个运行不会将任何 Agent 计为失败。

382* **失败**：再次运行，脚本在其之后启动的每个 Agent 也会再次运行，即使是已完成的 Agent。通过在 [`/workflows`](#watch-the-run) 中选择单个 Agent 并按 `x` 来停止它，会将其计为失败。382* **失败**：再次运行，脚本在其之后启动的每个 Agent 也会再次运行，即使它们已经完成。单独停止某一个 Agent（在 [`/workflows`](#watch-the-run) 中选中它并按 `x`）会被计为失败。

383 383

384最后一种情况意味着在扇出中间的失败会重新运行已经完成的工作。如果脚本按该顺序启动 A、B、C 和 D，并且 B 失败，重新启动会从缓存返回 A 并再次运行 B、C 和 D。384最后一种情况意味着，扇出过程中途的失败会导致已完成的工作重新运行。如果一个脚本按顺序启动 A、B、C 和 D，而 B 失败了，重新启动时会从缓存返回 A，并再次运行 B、C 和 D。

385 385

386如果您将一个按 A、B、C、D 顺序启动的脚本编辑为按 A、C、B、D 顺序启动，那么第二个启动的 Agent 现在是 C，而之前的运行在这个位置启动的是 B。重新启动会从缓存返回 A，并再次运行 C、B 和 D。386如果您编辑一个原本启动 A、B、C 和 D 的脚本，使其改为启动 A、C、B 和 D，那么第二个启动的 Agent 现在是 C，而上一次运行中是 B。重新启动时会从缓存返回 A，并再次运行 C、B 和 D。

387 387

388#### 离开会话后恢复388#### 离开会话后恢复

389 389

390您可以在同一 Claude Code 会话中恢复运行。当您离开会话时，运行中的工作流会发生什么取决于您如何离开：390如果您在工作流运行进行期间将会话转入后台或退出 Claude Code，该运行不会自行继续。只有当 Claude 通过 `Workflow` 调用重新启动它时，运行才会继续，这会[根据保存的结果重放运行](#which-agents-run-again)。

391 391

392* 如果您[后台运行会话](https://code.claude.com/docs/zh-CN/agent-view.md#what-carries-over-when-you-background)，Claude Code 会在后台会话中以相同方式重放运行并继续它。392* **您将会话转入了后台，或选择了 [`Move to background and exit`](https://code.claude.com/docs/zh-CN/agent-view#from-inside-a-session)**：如果您查看[后台会话](https://code.claude.com/docs/zh-CN/agent-view.md#what-carries-over-when-you-background)时运行尚未继续，请在该会话中让 Claude 重新启动工作流。根据您的[权限模式](#approve-the-plan-before-it-runs)，Claude Code 会先请您批准此次重新启动。如果该会话在 agent view 中显示在 `Needs input` 下，请[连接到该会话](https://code.claude.com/docs/zh-CN/agent-view.md#attach-to-a-session)以回应批准提示。

393* 如果您在工作流运行时退出 Claude Code 并且[代理视图已打开](https://code.claude.com/docs/zh-CN/agent-view.md#from-inside-a-session)，退出对话框会提供 `Move to background and exit`，它以相同方式转移运行。如果您选择 `Exit and stop tasks` 或未提供该选项，运行会随会话停止。Claude Code 会将运行的保存结果保存在 `~/.claude/projects/` 中该会话的目录下，所以您使用 `claude --resume` 恢复的会话可以在您要求 Claude 重新启动工作流时重放它们。在您全新启动的会话中，Claude 没有较早的运行可以重新启动，会将工作流作为新运行启动。393* **在后台会话中重新启动失败并显示 `nothing to resume`**：请让 Claude 将工作流作为新运行从头开始。如果 Claude 是从 `~/.claude/projects/` 之外的脚本文件路径（例如工作目录中的脚本）启动该运行的，Claude 无法在后台会话中重新启动它。

394* **您选择了 `Exit and stop tasks`，或者没有出现 `Move to background and exit` 选项**：运行已随会话一起停止，Claude Code 会将该运行保存的结果保留在 `~/.claude/projects/` 中该会话的目录下。请在 shell 中使用 `claude --resume` 恢复该会话，然后让 Claude 重新启动工作流。在全新的会话中，Claude 没有可以重新启动的先前运行，会从头开始工作流。

394 395

395在[云会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)中，Claude Code 也会将运行的结果与会话的对话历史一起保存，当会话的 VM 被回收时，这些历史会保留。当您[重新打开这样的会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md#environment-expired)并要求 Claude 重新启动工作流时，已完成的代理仍会返回其保存的结果。396在[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)中，Claude Code 还会将运行的结果与会话的对话历史一起保存，即使会话的 VM 被回收，这些结果也会保留。当您[重新打开此类会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md#environment-expired)并让 Claude 重新启动工作流时，已完成的 Agent 仍会返回其保存的结果。

396 397

397在本地和云会话中，当 Claude 重新启动较早的运行并且 Claude Code 根本找不到该运行的保存结果时，重新启动会失败并显示 `nothing to resume` 错误，而不是自动启动运行。要求 Claude 将工作流作为新运行启动。398无论是本地会话还是云端会话，当 Claude 重新启动先前的运行而 Claude Code 完全找不到该运行保存的结果时，重新启动会失败并显示 `nothing to resume` 错误，而不会自行从头开始运行。请让 Claude 将工作流作为新运行从头开始。

398 399

399### 当运行达到您的使用限制时400### 运行达到用量限制时

400 401

401当代理达到您的 claude.ai [使用限制](https://code.claude.com/docs/zh-CN/interactive-mode.md#wait-for-a-usage-limit-to-reset)时，运行会暂停而不是该代理失败：达到限制的代理会等待重置，并且不会启动新代理。限制重置后不久，等待的代理会再次运行，运行会自动继续。需要 Claude Code v2.1.271 或更高版本；在较早的版本上，受影响的代理会失败。402当某个 Agent 达到您的 claude.ai [用量限制](https://code.claude.com/docs/zh-CN/interactive-mode.md#wait-for-a-usage-limit-to-reset)时，运行会暂停，而不是让该 Agent 失败：达到限制的 Agent 会等待重置，并且不会启动新的 Agent。限制重置后不久，等待中的 Agent 会再次运行，运行会自行继续。需要 Claude Code v2.1.271 或更高版本；在更早的版本中，受影响的 Agent 会失败。

402 403

403当运行等待时，其在任务面板中的进度行和 [`/workflows`](#watch-the-run) 标题显示限制何时重置。404运行等待期间，任务面板中的进度行和 [`/workflows`](#watch-the-run) 标题会显示限制的重置时间。

404 405

405运行仅在以下所有条件都成立时暂停；当其中一个不成立时，受影响的代理会失败：406只有当以下所有条件都满足时，运行才会暂停；任一条件不满足时，受影响的 Agent 会失败：

406 407

407* 会话是交互式的并使用 claude.ai 订阅登录。运行不会在[非交互模式](https://code.claude.com/docs/zh-CN/headless.md)中使用 `claude -p` 或 [Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/overview.md) 暂停，在[后台会话](https://code.claude.com/docs/zh-CN/agent-view.md)中，或在 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 或[代理团队](https://code.claude.com/docs/zh-CN/agent-teams.md)队友会话中。408* 会话是交互式的，并且已使用 claude.ai 订阅登录。在使用 `claude -p` 的[非交互模式](https://code.claude.com/docs/zh-CN/headless.md)或 [Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/overview.md) 中、在[后台会话](https://code.claude.com/docs/zh-CN/agent-view.md)中，或在 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 或 [agent team](https://code.claude.com/docs/zh-CN/agent-teams.md) 队友会话中，运行不会暂停。

408* [`autoContinueAtUsageLimit`](https://code.claude.com/docs/zh-CN/settings-reference#autocontinueatusagelimit) 已打开，这是让会话本身[等待使用限制重置](https://code.claude.com/docs/zh-CN/interactive-mode.md#wait-for-a-usage-limit-to-reset)的相同设置。如果您在等待期间关闭它，等待会结束，等待的代理会失败。409* [`autoContinueAtUsageLimit`](https://code.claude.com/docs/zh-CN/settings-reference#autocontinueatusagelimit) 已开启，这也是让会话本身能够[等待用量限制重置](https://code.claude.com/docs/zh-CN/interactive-mode.md#wait-for-a-usage-limit-to-reset)的同一设置。如果您在等待期间将其关闭，等待会结束，等待中的 Agent 会失败。

409* 限制在 24 小时内重置。每周限制可能重置得更远。410* 限制在 24 小时内重置。每周限制的重置时间可能更远。

410* 运行还没有等待过两次。当它第三次达到限制时，代理会失败。411* 运行尚未等待过两次。当第三次达到限制时，该 Agent 会失败。

411 412

412### 当 Agent 停滞并重启时413### Agent 停滞并重新启动时

413 414

414如果某个 Agent 的输出停止到达足够长的时间，它会使用相同的提示词重新开始。在 [`/workflows`](#watch-the-run) 中，其名称会添加 `(retry 1)` 后缀，其详细信息会显示 `attempt 2 (stalled)`。重启是自动的，因此您无需执行任何操作。415如果某个 Agent 的输出停止到达的时间足够长，它会使用相同的提示词从头开始。在 [`/workflows`](#watch-the-run) 中，其名称会加上 `(retry 1)` 后缀，详情中显示 `attempt 2 (stalled)`。重新启动是自动的，您无需进行任何操作。

415 416

416新的尝试在开始时不带有停滞尝试的会话记录。停滞尝试已更改的文件保持更改状态，其消耗的 token 仍计入运行的总量。停滞窗口是 Claude Code 在结束尝试之前等待 Agent 输出的时长。Agent 等待其自身工具调用或等待[用量限制重置](#when-a-run-hits-your-usage-limit)所花费的时间不计入停滞窗口。417新的尝试启动时不带有停滞尝试的会话记录。停滞尝试已经更改的文件会保持更改状态，其消耗的 token 也会计入运行的总量。停滞窗口是 Claude Code 在结束尝试之前等待 Agent 输出的时长。Agent 等待自身工具调用或[用量限制重置](#when-a-run-hits-your-usage-limit)所花的时间不计入停滞窗口。

417 418

418一个 Agent 最多重启五次，包括您使用 `r` 请求的任何重启。如果第六次尝试也停滞，`agent()` 调用会失败，错误的开头会说明原因：419一个 Agent 最多重新启动五次，包括您通过 `r` 要求的任何重新启动。如果第六次尝试也停滞，`agent()` 调用会失败，错误开头会说明原因：

419 420

420* `agent stalled on all 6 attempts`：每次尝试在整个窗口内都没有输出。如果 Agent 的工作使其保持静默这么长时间，请延长窗口421* `agent stalled on all 6 attempts`：每次尝试在整个窗口内都没有输出。如果 Agent 的工作会让它保持沉默这么长时间，请延长窗口

421* `agent lost its reply on all 6 attempts`：每次尝试的响应流都变为静默，Claude Code 放弃了等待。延长停滞窗口没有帮助，因为[流式空闲看门狗](https://code.claude.com/docs/zh-CN/network-config.md#streaming-idle-watchdogs)先结束了响应，而 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 设置该看门狗的超时时间422* `agent lost its reply on all 6 attempts`：每次尝试的响应流都变得沉默，Claude Code 放弃了等待。延长停滞窗口没有帮助，因为[流式空闲看门狗](https://code.claude.com/docs/zh-CN/network-config.md#streaming-idle-watchdogs)先结束了响应，而 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 用于设置该看门狗的超时时间

422* `agent abandoned after 6 attempts`：各次尝试以不同方式结束，错误会按顺序列出这些方式423* `agent abandoned after 6 attempts`：各次尝试以不同方式结束，错误会按顺序列出这些方式

423 424

424要在窗口结束前给 Agent 更多时间来产生输出：425要在窗口结束前给 Agent 更多时间产生输出：

425 426

426* **单个 Agent**：在其 `agent()` 调用中以毫秒为单位传入 `stallMs`，例如 `agent(prompt, { stallMs: 1800000 })` 表示 30 分钟427* **单个 Agent**：在其 `agent()` 调用中以毫秒为单位传入 `stallMs`，例如 `agent(prompt, { stallMs: 1800000 })` 表示 30 分钟

427* **所有 Agent**：设置 [`CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`](https://code.claude.com/docs/zh-CN/env-vars#variables)，它也适用于工作流之外的子代理428* **所有 Agent**：设置 [`CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`](https://code.claude.com/docs/zh-CN/env-vars#variables)，它也适用于工作流之外的子代理

428 429

429失败后运行是否继续取决于您的脚本如何调用该 Agent：430失败后运行是否继续，取决于您的脚本如何调用该 Agent：

430 431

431* **在 [`parallel()` 或 `pipeline()`](#what-the-saved-script-looks-like) 内部**：运行继续，用 `null` 代替该 Agent 的结果432* **在 [`parallel()` 或 `pipeline()`](#what-the-saved-script-looks-like) 内部**：运行会继续，以 `null` 代替该 Agent 的结果

432* **直接 await**：运行以该错误结束433* **直接 await**：运行会随错误结束

433 434

434要重试，请要求 Claude 重新启动工作流。[暂停后恢复](#resume-after-a-pause)介绍了哪些内容会再次运行。435要重试，请让 Claude 重新启动工作流。[暂停后恢复](#resume-after-a-pause)介绍了哪些内容会再次运行。

435 436

436### 成本437### 成本

437 438

438工作流生成许多代理，所以单次运行可以使用比在对话中处理相同任务更多的令牌。运行计入您的计划使用和速率限制。439工作流会生成许多 Agent，因此单次运行使用的 token 可能明显多于在对话中完成同一任务。运行会计入您套餐的用量和速率限制。

439 440

440要在提交大型任务前评估支出，请先在小范围上运行工作流：一个目录而不是整个仓库，或一个狭窄的问题而不是一个宽泛的问题。`/workflows` 视图显示每个代理的令牌使用情况，随着运行进行，您可以随时在那里停止运行，通常不会丢失已完成的工作。[暂停后恢复](#resume-after-a-pause)涵盖了停止的运行保留的内容。运行时的[代理上限](#behavior-and-limits)限制单次运行可以生成多少个代理，这限制了失控脚本的成本。要保持运行的代理数量较少，选择 `small` [大小指南](#set-a-size-guideline)。441要在投入大型任务之前估算开销，请先在一小部分内容上运行工作流：一个目录而不是整个仓库，或者一个具体的问题而不是宽泛的问题。`/workflows` 视图会在运行过程中显示每个 Agent 的 token 用量，您可以随时在那里停止运行，通常不会丢失已完成的工作。[暂停后恢复](#resume-after-a-pause)介绍了已停止的运行会保留哪些内容。运行时的 [Agent 上限](#behavior-and-limits)限制了单次运行可以生成的 Agent 数量，从而限定了失控脚本的成本。要让运行使用更少的 Agent，请选择 `small` [规模指导](#set-a-size-guideline)。

441 442

442Claude Code 还会标记增长异常大的运行。当工作流调度超过 25 个代理，或其预计令牌总数超过 150 万时，输入框下方任务面板中的其进度行显示 `Large workflow` 警告。警告指向您可以停止运行的 [`/workflows`](#watch-the-run)。443Claude Code 还会标记规模异常大的运行。当工作流安排的 Agent 超过 25 个，或其预计的 token 总量超过 150 万时，输入框下方任务面板中的进度行会显示 `Large workflow` 警告。该警告会引导您前往 [`/workflows`](#watch-the-run)，您可以在那里停止运行。

443 444

444警告是建议性的：它不会暂停或限制运行。当您看到它时，两个设置会改变：445该警告仅作提示：它不会暂停或限制运行。有两项设置会改变您看到它的时机：

445 446

446* 如果您自己选择[大小指南](#set-a-size-guideline)，其代理计数替换 25 个代理的阈值。内置默认指南将阈值保留在 25。447* 如果您自行选择了[规模指导](#set-a-size-guideline)，其 Agent 数量会取代 25 个 Agent 的阈值。内置的默认指导会将阈值保持为 25。

447* 启用[ultracode](#let-claude-decide-with-ultracode)的会话不显示警告，因为打开 ultracode 已经让您选择加入大型运行。448* 开启了 [ultracode](#let-claude-decide-with-ultracode) 的会话不会显示该警告，因为开启 ultracode 就已表示您选择接受大型运行。

448 449

449Claude Code 按照它用于子代理的相同[顺序选择每个工作流代理的模型](https://code.claude.com/docs/zh-CN/sub-agents.md#choose-a-model)。脚本为阶段命名的模型在该顺序中计为每次调用的模型。当没有其他东西分配一个时，代理在您的会话模型上运行。450Claude Code 为每个工作流 Agent 选择模型的顺序与[为子代理选择模型的顺序](https://code.claude.com/docs/zh-CN/sub-agents.md#choose-a-model)相同。脚本为某个阶段指定的模型在该顺序中算作按调用指定的模型。当没有其他来源指定模型时，Agent 会使用您会话的模型运行。

450 451

451要控制模型成本：452要控制模型成本：

452 453

453* 在大型运行前检查 `/model`，如果您通常为日常工作切换到较小的模型454* 如果您通常会为日常工作切换到较小的模型，请在大型运行之前检查 `/model`

454* 当您描述任务时，要求 Claude 为不需要最强模型的阶段使用较小的模型455* 在描述任务时，让 Claude 为不需要最强模型的阶段使用较小的模型

455 456

456当您组织的 [`availableModels` 允许列表](https://code.claude.com/docs/zh-CN/model-config#restrict-model-selection)阻止脚本为某个 Agent 请求的模型时，该 Agent 会改为在替代模型上运行，遵循与[子代理相同的替代规则](https://code.claude.com/docs/zh-CN/sub-agents.md#choose-a-model)。457当您组织的 [`availableModels` 允许列表](https://code.claude.com/docs/zh-CN/model-config#restrict-model-selection)阻止了脚本为某个 Agent 请求的模型时，该 Agent 会改用替代模型运行，遵循与[子代理相同的替代规则](https://code.claude.com/docs/zh-CN/sub-agents.md#choose-a-model)。

457 458

458### 设置大小指南459### 设置规模指导

459 460

460大小指南告诉 Claude 在编写动态工作流时应以多少个 Agent 为目标。Claude Code 将指南作为建议而不是上限发送给 Claude，所以要求不同规模的提示词仍然会覆盖它。461规模指导告诉 Claude 在编写动态工作流时以多少个 Agent 为目标。Claude Code 将该指导作为建议而不是上限发送给 Claude，因此要求不同规模的提示词仍会覆盖它。

461 462

462每个值映射到一个代理计数：463每个值对应一个 Agent 数量：

463 464

464| 值 | Claude 针对的代理计数 |465| 值 | Claude 的目标 Agent 数量 |

465| :- | :- |466| :- | :- |

470 471

471默认值是 `medium`，或当您在使用 Claude Code v2.1.271 或更高版本的 Pro 计划上登录时为 `small`。在您选择值之前，`/config` 行将值标记为默认值，工作流的 `Running in background` 行命名生效的大小。需要 Claude Code v2.1.219 或更高版本；较早的版本默认为 `unrestricted`。472默认值为 `medium`，如果您使用 Pro 套餐登录且 Claude Code 为 v2.1.271 或更高版本，则默认值为 `small`。在您选择某个值之前，`/config` 中的该行会将该值标记为默认值，工作流的 `Running in background` 行会显示当前生效的规模。需要 Claude Code v2.1.219 或更高版本；更早的版本默认为 `unrestricted`。

472 473

473要更改指南，在 `/config` 中为 Dynamic workflow size 设置选择一个值，或运行 `/config workflowSizeGuideline=small`。在 v2.1.219 及更高版本上，您也可以在任何设置文件中设置 [`workflowSizeGuideline` 键](https://code.claude.com/docs/zh-CN/settings-reference#workflowsizeguideline)；该值优先于 `/config`，当设置文件提供一个时，Claude Code 会隐藏 `/config` 行。474要更改指导，请在 `/config` 中为 Dynamic workflow size 设置选择一个值，或运行 `/config workflowSizeGuideline=small`。在 v2.1.219 及更高版本中，您还可以在任意设置文件中设置 [`workflowSizeGuideline` 键](https://code.claude.com/docs/zh-CN/settings-reference#workflowsizeguideline)；该值优先于 `/config`，并且当设置文件提供了该值时，Claude Code 会隐藏 `/config` 中的该行。

474 475

475更改在下一个提示时生效。[运行时代理上限](#behavior-and-limits)仍然适用，无论设置如何。476更改会在下一个提示词时生效。无论该设置如何，[运行时 Agent 上限](#behavior-and-limits)仍然适用。

476 477

477### 关闭工作流478### 关闭工作流

478 479

479工作流在 CLI、桌面应用、IDE 扩展、[非交互模式](https://code.claude.com/docs/zh-CN/headless.md)与 `claude -p` 和 [Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/overview.md) 中可用。相同的禁用设置在每个表面上应用。480工作流可在 CLI、Desktop 应用、IDE 扩展、使用 `claude -p` 的[非交互模式](https://code.claude.com/docs/zh-CN/headless.md)以及 [Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/overview.md) 中使用。相同的禁用设置适用于每个使用入口。

480 481

481要为自己关闭工作流：482要为您自己关闭工作流：

482 483

483* 在 `/config` 中切换 Dynamic workflows 关闭。在会话中持续。484* 在 `/config` 中关闭 Dynamic workflows。在会话之间保持有效。

484* 在 `~/.claude/settings.json` 中设置 `"disableWorkflows": true`。在会话中持续。485* 在 `~/.claude/settings.json` 中设置 `"disableWorkflows": true`。在会话之间保持有效。

485* 设置 `CLAUDE_CODE_DISABLE_WORKFLOWS=1`。在启动时读取，所以它在您设置它的任何地方应用。486* 设置 `CLAUDE_CODE_DISABLE_WORKFLOWS=1`。在启动时读取，因此在您设置它的任何位置都适用。

486 487

487要为整个组织关闭工作流，在[托管设置](https://code.claude.com/docs/zh-CN/server-managed-settings.md)中设置 `"disableWorkflows": true`，或使用[Claude Code 管理员设置](https://claude.ai/admin-settings/claude-code)页面上的切换。488要为整个组织关闭工作流，请在[托管设置](https://code.claude.com/docs/zh-CN/server-managed-settings.md)中设置 `"disableWorkflows": true`，或使用 [Claude Code 管理设置](https://claude.ai/admin-settings/claude-code)页面上的开关。

488 489

489当工作流被禁用时：490工作流被禁用时：

490 491

491* `/workflows`、工作流命令和 `/workflow-authoring` skill 不可用492* `/workflows`、工作流命令以及 `/workflow-authoring` skill 不可用

492* `ultracode` 关键字不再触发运行，**Ultracode** 开关会从 `/effort` 中移除493* `ultracode` 关键字不再触发运行，并且 **Ultracode** 开关会从 `/effort` 中移除

493 494

494已在进行中的运行会继续进行。495已在进行中的运行会继续进行。

495 496

496关闭工作流也会使[ultracode](#let-claude-decide-with-ultracode)不可用。没有托管设置单独排除 ultracode：无论它在哪里[可用](https://code.claude.com/docs/zh-CN/model-config.md#when-ultracode-is-available)，用户可以使用 `/effort ultracode` 打开它。[努力上限](https://code.claude.com/docs/zh-CN/model-config.md#organization-effort-limits)降低了启用 ultracode 的会话运行的努力级别，但不会关闭 ultracode。497关闭工作流也会使 [ultracode](#let-claude-decide-with-ultracode) 不可用。没有任何托管设置可以单独禁止 ultracode：在 ultracode [可用](https://code.claude.com/docs/zh-CN/model-config.md#when-ultracode-is-available)的任何地方，用户都可以使用 `/effort ultracode` 开启它。[effort 上限](https://code.claude.com/docs/zh-CN/model-config.md#organization-effort-limits)会降低开启了 ultracode 的会话运行时所用的 effort 级别，但不会关闭 ultracode。

497 498

498## 相关资源499## 相关资源

499 500

Documentation 2026-10-25 23:58 UTC to 2026-10-26 22:57 UTC