Documentation — Spybara

claude-apps-gateway-deploy.md +28 −26

Details

6 6

7> 向身份提供商注册网关，构建容器，在 Kubernetes 或 Cloud Run 上部署，并运维它：健康检查、密钥轮换、升级和安全。7> 向身份提供商注册网关，构建容器，在 Kubernetes 或 Cloud Run 上部署，并运维它：健康检查、密钥轮换、升级和安全。

8 8

9本页面涵盖运行 [Claude 应用网关](/zh-CN/claude-apps-gateway) 的运维方面：在身份提供商 (IdP) 中注册 OAuth 客户端、将网关部署为容器，以及日常运行。关于网关在启动时读取的 `gateway.yaml` 文件中的每个选项，请参阅 [配置参考](/zh-CN/claude-apps-gateway-config)。9本页面涵盖运行 [Claude 应用网关](/docs/zh-CN/claude-apps-gateway) 的运维方面：在身份提供商 (IdP) 中注册 OAuth 客户端、将网关部署为容器，以及日常运行。关于网关在启动时读取的 `gateway.yaml` 文件中的每个选项，请参阅 [配置参考](/docs/zh-CN/claude-apps-gateway-config)。

10 10

11生产部署按顺序遵循四个步骤，下面的部分与之相对应。前两个是您做出选择的地方；后两个是在运行后参考的材料。11生产部署按顺序遵循四个步骤，下面的部分与之相对应。前两个是您做出选择的地方；后两个是在运行后参考的材料。

12 12

31 31

32任何符合 OIDC 的 IdP 都可以工作：Okta、Microsoft Entra ID、Google Workspace、Keycloak、Dex、PingFederate 等。IdP 必须满足三个要求：32任何符合 OIDC 的 IdP 都可以工作：Okta、Microsoft Entra ID、Google Workspace、Keycloak、Dex、PingFederate 等。IdP 必须满足三个要求：

33 33

34* 在生产环境中通过 HTTPS 提供 `/.well-known/openid-configuration`；网关接受 [`http://` 发行者](/zh-CN/claude-apps-gateway-config#oidc)，本地环回发行者另外需要 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`34* 在生产环境中通过 HTTPS 提供 `/.well-known/openid-configuration`；网关接受 [`http://` 发行者](/docs/zh-CN/claude-apps-gateway-config#oidc)，本地环回发行者另外需要 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`

35* 支持授权代码流。PKCE（代码交换证明密钥）默认启用；对于不支持它的 IdP，使用 `oidc.use_pkce: false` 禁用它35* 支持授权代码流。PKCE（代码交换证明密钥）默认启用；对于不支持它的 IdP，使用 `oidc.use_pkce: false` 禁用它

36* 在 id\_token 中返回 `email` 和可选的 `groups`，或使用 `oidc.userinfo_fallback: true` 从 userinfo 端点提供它们36* 在 id\_token 中返回 `email` 和可选的 `groups`，或使用 `oidc.userinfo_fallback: true` 从 userinfo 端点提供它们

37 37

41 41

42* **Okta**：位于 `https://example.okta.com` 的组织授权服务器返回一个省略 `email` 和 `groups` 的简化 id\_token，因此当您将其用作 `issuer` 时设置 `oidc.userinfo_fallback: true`。包含 id\_token 中 `email` 和可选 `groups` 的自定义授权服务器（如 `https://example.okta.com/oauth2/default`）直接发出它们，不需要回退。Okta 仅在 `oidc.scopes` 中请求 `groups` 作用域且应用的组声明过滤器允许时才发出 `groups`；`userinfo_fallback` 无法填充 IdP 未被要求的声明。42* **Okta**：位于 `https://example.okta.com` 的组织授权服务器返回一个省略 `email` 和 `groups` 的简化 id\_token，因此当您将其用作 `issuer` 时设置 `oidc.userinfo_fallback: true`。包含 id\_token 中 `email` 和可选 `groups` 的自定义授权服务器（如 `https://example.okta.com/oauth2/default`）直接发出它们，不需要回退。Okta 仅在 `oidc.scopes` 中请求 `groups` 作用域且应用的组声明过滤器允许时才发出 `groups`；`userinfo_fallback` 无法填充 IdP 未被要求的声明。

43* **Microsoft Entra ID**：`issuer` = `https://login.microsoftonline.com/<tenant-id>/v2.0`。Entra 发出组对象 ID 而不是名称，因此在 `managed.policies.match.groups` 中使用 GUID，或使用应用角色获得人类可读的名称。如果您的租户在 `roles` 而不是 `groups` 下发出角色，设置 `oidc.groups_claim: roles`。43* **Microsoft Entra ID**：`issuer` = `https://login.microsoftonline.com/<tenant-id>/v2.0`。Entra 发出组对象 ID 而不是名称，因此在 `managed.policies.match.groups` 中使用 GUID，或使用应用角色获得人类可读的名称。如果您的租户在 `roles` 而不是 `groups` 下发出角色，设置 `oidc.groups_claim: roles`。

44* **Google Workspace**：`issuer` = `https://accounts.google.com`。Google 的 id\_token 不包含组。要在 Google 作为 IdP 时使用基于组的 `allowed_groups` 或 `managed.policies`，配置 [`oidc.google_groups`](/zh-CN/claude-apps-gateway-config#oidc)，它使用具有域范围委派的服务账户通过 Admin SDK Directory API 查找每个用户的组。没有它，使用 `oidc.allowed_email_domains` 进行成员资格门控，使用 `managed.policies.match.email_domain` 进行策略分配。Google 也忽略标准 `offline_access` 作用域。对于刷新令牌，设置 `oidc.scopes: [openid, profile, email]` 和 `oidc.extra_auth_params: { access_type: offline, prompt: consent }`。44* **Google Workspace**：`issuer` = `https://accounts.google.com`。Google 的 id\_token 不包含组。要在 Google 作为 IdP 时使用基于组的 `allowed_groups` 或 `managed.policies`，配置 [`oidc.google_groups`](/docs/zh-CN/claude-apps-gateway-config#oidc)，它使用具有域范围委派的服务账户通过 Admin SDK Directory API 查找每个用户的组。没有它，使用 `oidc.allowed_email_domains` 进行成员资格门控，使用 `managed.policies.match.email_domain` 进行策略分配。Google 也忽略标准 `offline_access` 作用域。对于刷新令牌，设置 `oidc.scopes: [openid, profile, email]` 和 `oidc.extra_auth_params: { access_type: offline, prompt: consent }`。

45 45

46有关不在上述范围内的身份提供商的支持，请参阅[故障排除](#troubleshooting)。46有关不在上述范围内的身份提供商的支持，请参阅[故障排除](#troubleshooting)。

47 47

48<Warning>48<Warning>

49 刷新令牌让网关可以在不将开发者发送回浏览器的情况下无声地续订开发者的会话。它们也驱动取消配置，因为当 IdP 禁用用户时，下一次刷新失败，会话在 `ttl_hours` 内结束。网关默认请求 `offline_access` 以获取刷新令牌。如果您的 IdP 需要明确同意离线访问，配置 OAuth 客户端以允许它。49 刷新令牌让网关可以在不将开发者发送回浏览器的情况下无声地续订开发者的会话。它们也驱动取消配置，因为当 IdP 禁用用户时，下一次刷新失败，会话在 `ttl_hours` 内结束。网关默认请求 `offline_access` 以获取刷新令牌。如果您的 IdP 需要明确同意离线访问，配置 OAuth 客户端以允许它。

50 50

51 如果您的 IdP 根本无法发出刷新令牌，网关仍然可以工作，但没有无声续订，因此开发者在会话过期时重新运行浏览器登录。为了防止每小时都发生这种情况，将 [`session.ttl_hours`](/zh-CN/claude-apps-gateway-config#session) 提高到 `8` 或 `12`。权衡是取消配置延迟，因为没有刷新令牌，禁用的用户在更长的 TTL 过期之前保持访问权限。51 如果您的 IdP 根本无法发出刷新令牌，网关仍然可以工作，但没有无声续订，因此开发者在会话过期时重新运行浏览器登录。为了防止每小时都发生这种情况，将 [`session.ttl_hours`](/docs/zh-CN/claude-apps-gateway-config#session) 提高到 `8` 或 `12`。权衡是取消配置延迟，因为没有刷新令牌，禁用的用户在更长的 TTL 过期之前保持访问权限。

52</Warning>52</Warning>

53 53

54<h2 id="deployment">54<h2 id="deployment">

62除了运行位置外，还有一些决策塑造部署：62除了运行位置外，还有一些决策塑造部署：

63 63

64* **成本**：网关没有单独的许可证或按座位费用；它是 `claude` 二进制文件的一部分。您通过现有的云或 Anthropic 承诺为推理付费，加上容器的计算和您的遥测收集器。64* **成本**：网关没有单独的许可证或按座位费用；它是 `claude` 二进制文件的一部分。您通过现有的云或 Anthropic 承诺为推理付费，加上容器的计算和您的遥测收集器。

65* **绕过**：网关不强制执行通过它的唯一模型路由。具有自己凭证的开发者仍然可以直接调用提供商，因此关闭该路径是网络策略决策，例如阻止到 `api.anthropic.com` 的出口，除了来自网关的。阻止该出口也会破坏 [WebFetch 域安全检查](/zh-CN/data-usage#webfetch-domain-safety-check)，它从每个开发者的机器调用 `api.anthropic.com`；在托管策略中设置 `skipWebFetchPreflight: true` 以禁用它。65* **绕过**：网关不强制执行通过它的唯一模型路由。具有自己凭证的开发者仍然可以直接调用提供商，因此关闭该路径是网络策略决策，例如阻止到 `api.anthropic.com` 的出口，除了来自网关的。阻止该出口也会破坏 [WebFetch 域安全检查](/docs/zh-CN/data-usage#webfetch-domain-safety-check)，它从每个开发者的机器调用 `api.anthropic.com`；在托管策略中设置 `skipWebFetchPreflight: true` 以禁用它。

66* **多个网关**：每个网关是一个单独的部署，有自己的配置。CLI 按网关主机名存储其信任指纹和凭证，因此不同的团队可以连接到不同的网关而不会冲突。要提供多个 OIDC 发行者，运行单独的实例。66* **多个网关**：每个网关是一个单独的部署，有自己的配置。CLI 按网关主机名存储其信任指纹和凭证，因此不同的团队可以连接到不同的网关而不会冲突。要提供多个 OIDC 发行者，运行单独的实例。

67* **无服务器**：Cloud Run 可以工作；设置 `min-instances: 1` 以避免冷 OIDC 发现。Lambda 和 Cloud Functions 不行，因为网关是一个长时间运行的 HTTP 服务器。67* **无服务器**：Cloud Run 可以工作；设置 `min-instances: 1` 以避免冷 OIDC 发现。Lambda 和 Cloud Functions 不行，因为网关是一个长时间运行的 HTTP 服务器。

68 68

69这里的每个生产拓扑都在普通 HTTP 副本前面放置一个 L7 代理，如 Ingress、Cloud Run 的前端或 ALB。设置 [`listen.trusted_proxies`](/zh-CN/claude-apps-gateway-config#listen) 为代理的源范围，以便网关从 `X-Forwarded-For` 读取客户端 IP。网关仅在 TCP 对等体受信任时才遵守该标头；[Google Cloud 工作示例](/zh-CN/claude-apps-gateway-on-gcp) 为每个拓扑提供具体值。没有受信任的代理，每个请求似乎都来自代理的 IP，这会将按 IP 速率限制折叠为一个共享桶，并在审计事件中记录代理的 IP。69这里的每个生产拓扑都在普通 HTTP 副本前面放置一个 L7 代理，如 Ingress、Cloud Run 的前端或 ALB。设置 [`listen.trusted_proxies`](/docs/zh-CN/claude-apps-gateway-config#listen) 为代理的源范围，以便网关从 `X-Forwarded-For` 读取客户端 IP。网关仅在 TCP 对等体受信任时才遵守该标头；[Google Cloud 工作示例](/docs/zh-CN/claude-apps-gateway-on-gcp) 为每个拓扑提供具体值。没有受信任的代理，每个请求似乎都来自代理的 IP，这会将按 IP 速率限制折叠为一个共享桶，并在审计事件中记录代理的 IP。

70 70

71<h3 id="container-image">71<h3 id="container-image">

72 容器镜像72 容器镜像

74 74

75围绕标准 Claude Code 版本中的本机 `claude` 二进制文件构建您自己的镜像：75围绕标准 Claude Code 版本中的本机 `claude` 二进制文件构建您自己的镜像：

76 76

~~771. 从固定版本下载您的镜像架构的 Linux 构建；请参阅 [安装特定版本](/zh-CN/setup#install-a-specific-version) 了解下载 URL。~~771. 从固定版本下载您的镜像架构的 Linux 构建；请参阅 [安装特定版本](/docs/zh-CN/setup#install-a-specific-version) 了解下载 URL。

~~782. 根据版本的 GPG 签名 `manifest.json` 验证它，如 [二进制完整性和代码签名](/zh-CN/setup#binary-integrity-and-code-signing) 中所述。~~782. 根据版本的 GPG 签名 `manifest.json` 验证它，如 [二进制完整性和代码签名](/docs/zh-CN/setup#binary-integrity-and-code-signing) 中所述。

793. 将其复制到构建上下文中。793. 将其复制到构建上下文中。

80 80

81如果您的构建无法到达版本主机，请将版本镜像到您的内部注册表中，并固定您的舰队运行的版本。81如果您的构建无法到达版本主机，请将版本镜像到您的内部注册表中，并固定您的舰队运行的版本。

82 82

83除了二进制文件外，镜像还需要：83除了二进制文件外，镜像还需要：

84 84

85* **基于 glibc 的镜像**：glibc 构建的唯一动态依赖项是 glibc 库。基于 Musl 的镜像需要 `linux-x64-musl` 或 `linux-arm64-musl` 构建加上额外的包；请参阅 [Alpine Linux 设置](/zh-CN/setup#alpine-linux-and-musl-based-distributions)。85* **基于 glibc 的镜像**：glibc 构建的唯一动态依赖项是 glibc 库。基于 Musl 的镜像需要 `linux-x64-musl` 或 `linux-arm64-musl` 构建加上额外的包；请参阅 [Alpine Linux 设置](/docs/zh-CN/setup#alpine-linux-and-musl-based-distributions)。

86* **可写状态目录**：网关以任何用户身份运行，但最小镜像没有可写的主目录。将 `CLAUDE_CONFIG_DIR` 设置为可写路径，如 `/tmp/.claude`。86* **可写状态目录**：网关以任何用户身份运行，但最小镜像没有可写的主目录。将 `CLAUDE_CONFIG_DIR` 设置为可写路径，如 `/tmp/.claude`。

87* **容器命令**：`claude gateway --config /etc/claude/gateway.yaml`，配置文件以只读方式挂载，密钥作为环境变量提供；网关在 `listen.port` 上监听，默认为 `8080`。87* **容器命令**：`claude gateway --config /etc/claude/gateway.yaml`，配置文件以只读方式挂载，密钥作为环境变量提供；网关在 `listen.port` 上监听，默认为 `8080`。

88 88

99<Note>99<Note>

100 **工作负载身份**100 **工作负载身份**

101 101

102 优先使用平台的工作负载身份而不是静态密钥：EKS 上的 IRSA 用于 Bedrock 和 AWS 上的 Claude Platform，GKE 上的工作负载身份用于 Agent Platform，AKS 上的工作负载身份用于 Foundry。在上游块中设置 `auth: {}`，或对 Foundry 设置 `use_azure_ad: true`，网关通过该提供商的默认凭证链获取 pod 的身份。对于跨云配对，如 GKE 上的 Bedrock 上游，在上游的 `auth` 块中设置显式凭证。[`upstreams` 参考](/zh-CN/claude-apps-gateway-config#upstreams) 有每个平台的设置详情。102 优先使用平台的工作负载身份而不是静态密钥：EKS 上的 IRSA 用于 Bedrock 和 AWS 上的 Claude Platform，GKE 上的工作负载身份用于 Agent Platform，AKS 上的工作负载身份用于 Foundry。在上游块中设置 `auth: {}`，或对 Foundry 设置 `use_azure_ad: true`，网关通过该提供商的默认凭证链获取 pod 的身份。对于跨云配对，如 GKE 上的 Bedrock 上游，在上游的 `auth` 块中设置显式凭证。[`upstreams` 参考](/docs/zh-CN/claude-apps-gateway-config#upstreams) 有每个平台的设置详情。

103</Note>103</Note>

104 104

105<h3 id="cloud-run">105<h3 id="cloud-run">

109按如下方式配置服务：109按如下方式配置服务：

110 110

111* 将 `listen.port` 保留在其默认值 `8080`，这与 Cloud Run 的默认 `PORT` 匹配，或设置 `port: ${PORT}`111* 将 `listen.port` 保留在其默认值 `8080`，这与 Cloud Run 的默认 `PORT` 匹配，或设置 `port: ${PORT}`

112* 将 `public_url` 设置为外部可达的源。对于生产，这通常是内部负载均衡器的主机名，因为 `/login` [拒绝公共地址](/zh-CN/claude-apps-gateway#prerequisites)，而 `*.run.app` URL 解析为一个，所以单独的 Cloud Run URL 仅适用于 `curl` 或浏览器烟雾测试。例外是一个网络，其中 `*.run.app` 通过 Private Service Connect 和 Cloud DNS 私有区域私下解析；在该拓扑中，Cloud Run URL 是有效的 `public_url`。[Google Cloud 工作示例](/zh-CN/claude-apps-gateway-on-gcp#deploy-the-gateway) 涵盖两者。112* 将 `public_url` 设置为外部可达的源。对于生产，这通常是内部负载均衡器的主机名，因为 `/login` [拒绝公共地址](/docs/zh-CN/claude-apps-gateway#prerequisites)，而 `*.run.app` URL 解析为一个，所以单独的 Cloud Run URL 仅适用于 `curl` 或浏览器烟雾测试。例外是一个网络，其中 `*.run.app` 通过 Private Service Connect 和 Cloud DNS 私有区域私下解析；在该拓扑中，Cloud Run URL 是有效的 `public_url`。[Google Cloud 工作示例](/docs/zh-CN/claude-apps-gateway-on-gcp#deploy-the-gateway) 涵盖两者。

113* 将配置作为密钥卷挂载113* 将配置作为密钥卷挂载

114* 设置 `min-instances: 1` 以避免首次请求时的冷 OIDC 发现114* 设置 `min-instances: 1` 以避免首次请求时的冷 OIDC 发现

115 115

116<Note>116<Note>

117 有关 Google Cloud 上的完整工作示例，涵盖 Cloud Run 或 GKE、Cloud SQL 和 Secret Manager，请参阅 [在 Google Cloud 上部署](/zh-CN/claude-apps-gateway-on-gcp)。117 有关 Google Cloud 上的完整工作示例，涵盖 Cloud Run 或 GKE、Cloud SQL 和 Secret Manager，请参阅 [在 Google Cloud 上部署](/docs/zh-CN/claude-apps-gateway-on-gcp)。

118</Note>118</Note>

119 119

120<h3 id="push-the-gateway-url-to-developer-machines">120<h3 id="push-the-gateway-url-to-developer-machines">

121 将网关 URL 推送到开发者机器121 将网关 URL 推送到开发者机器

122</h3>122</h3>

123 123

124一旦网关开始提供服务，通过托管设置、MDM 或直接写入每个操作系统的 `managed-settings.json` 将 `forceLoginMethod` 和 `forceLoginGatewayUrl` 推送到每个开发者的机器。没有这个，`/login` 显示标准账户选择器，没有网关选项。请参阅 [客户端托管设置](/zh-CN/claude-apps-gateway-config#client-side-managed-settings) 了解文件路径。124一旦网关开始提供服务，通过托管设置、MDM 或直接写入每个操作系统的 `managed-settings.json` 将 `forceLoginMethod` 和 `forceLoginGatewayUrl` 推送到每个开发者的机器。没有这个，`/login` 显示标准账户选择器，没有网关选项。请参阅 [客户端托管设置](/docs/zh-CN/claude-apps-gateway-config#client-side-managed-settings) 了解文件路径。

125 125

126<h2 id="operations">126<h2 id="operations">

127 运维127 运维

160 160

161* **现有会话**：持有者令牌使用 JWT 密钥在本地验证，会话刷新不接触存储，网关进程仍然可以提供推理161* **现有会话**：持有者令牌使用 JWT 密钥在本地验证，会话刷新不接触存储，网关进程仍然可以提供推理

162* **新登录**：失败直到 Postgres 恢复，因为设备流及其速率限制计数器存在于 Postgres 中162* **新登录**：失败直到 Postgres 恢复，因为设备流及其速率限制计数器存在于 Postgres 中

163* **[支出限制执行](/zh-CN/claude-apps-gateway-spend-limits#postgres-availability)**：在中断期间默认失败开放，因此推理仍然流动；如果您宁愿阻止而不是无计量运行，将其翻转为失败关闭163* **[支出限制执行](/docs/zh-CN/claude-apps-gateway-spend-limits#postgres-availability)**：在中断期间默认失败开放，因此推理仍然流动；如果您宁愿阻止而不是无计量运行，将其翻转为失败关闭

164* **就绪**：`/readyz` 在中断期间报告未就绪，因此在就绪上门控流量的编排器一次从轮换中移除每个副本。在该拓扑中，所有流量，包括网关仍然可以提供的推理，在负载均衡器处失败，直到 Postgres 恢复。`/healthz` 上的活跃探针继续通过，因此副本不会重新启动。如果您宁愿已登录的开发者在存储中断期间继续工作，将就绪探针指向 `/healthz`；成本是新登录失败，反对仍然报告就绪的副本。164* **就绪**：`/readyz` 在中断期间报告未就绪，因此在就绪上门控流量的编排器一次从轮换中移除每个副本。在该拓扑中，所有流量，包括网关仍然可以提供的推理，在负载均衡器处失败，直到 Postgres 恢复。`/healthz` 上的活跃探针继续通过，因此副本不会重新启动。如果您宁愿已登录的开发者在存储中断期间继续工作，将就绪探针指向 `/healthz`；成本是新登录失败，反对仍然报告就绪的副本。

165 165

166如果您的 IdP 宕机，现有会话工作直到 `ttl_hours`，新登录和刷新失败。如果您的 IdP 有频繁的维护窗口，设置更长的 `ttl_hours`。166如果您的 IdP 宕机，现有会话工作直到 `ttl_hours`，新登录和刷新失败。如果您的 IdP 有频繁的维护窗口，设置更长的 `ttl_hours`。

193 193

194一个 30 秒的循环过期 `kv` 行超过其 TTL，一个每小时的扫描在支出表上强制保留窗口，因此没有什么无限增长。没有 [支出限制](/zh-CN/claude-apps-gateway-spend-limits) 配置，只有 `kv` 被写入。如果您的安全策略禁止应用角色的 DDL，预先创建这些表和 `_migrations`，使用管理员角色，并授予应用角色 `SELECT, INSERT, UPDATE, DELETE` 在每个上。194一个 30 秒的循环过期 `kv` 行超过其 TTL，一个每小时的扫描在支出表上强制保留窗口，因此没有什么无限增长。没有 [支出限制](/docs/zh-CN/claude-apps-gateway-spend-limits) 配置，只有 `kv` 被写入。如果您的安全策略禁止应用角色的 DDL，预先创建这些表和 `_migrations`，使用管理员角色，并授予应用角色 `SELECT, INSERT, UPDATE, DELETE` 在每个上。

195 195

196使用支出限制，丢失的数据库意味着丢失支出跟踪和上限，不仅仅是开发者重新登录，因此运行定期备份。要立即删除一个离职的开发者而不是等待保留，直接运行 `DELETE FROM principal_emails WHERE principal = '<sub>'`；这移除了唯一持有其电子邮件、名称和组的表。`spend` 和 `admin_audit` 行仅引用伪匿名 OIDC `sub`。196使用支出限制，丢失的数据库意味着丢失支出跟踪和上限，不仅仅是开发者重新登录，因此运行定期备份。要立即删除一个离职的开发者而不是等待保留，直接运行 `DELETE FROM principal_emails WHERE principal = '<sub>'`；这移除了唯一持有其电子邮件、名称和组的表。`spend` 和 `admin_audit` 行仅引用伪匿名 OIDC `sub`。

197 197

218| 数据 | 路径 | 由网关发送给 Anthropic |218| 数据 | 路径 | 由网关发送给 Anthropic |

219| ----------------------------------------------------------------------- | -------------------------------------- | ------------------------ |219| ----------------------------------------------------------------------- | -------------------------------------- | ------------------------ |

221| 遥测（OTLP 指标，加上 [选择加入日志和跟踪](/zh-CN/claude-apps-gateway-config#telemetry)） | CLI → 网关 → 您的收集器 | 从不 |221| 遥测（OTLP 指标，加上 [选择加入日志和跟踪](/docs/zh-CN/claude-apps-gateway-config#telemetry)） | CLI → 网关 → 您的收集器 | 从不 |

222| 身份（电子邮件、组、sub） | IdP → 网关 → JWT → CLI；CLI 在 OTLP 导出上标记它 | 从不 |222| 身份（电子邮件、组、sub） | IdP → 网关 → JWT → CLI；CLI 在 OTLP 导出上标记它 | 从不 |

223| 托管设置 | 您的网关 YAML → CLI | 从不 |223| 托管设置 | 您的网关 YAML → CLI | 从不 |

224| 审计日志 | 网关 stderr → 您的聚合器 | 从不 |224| 审计日志 | 网关 stderr → 您的聚合器 | 从不 |

237 237

238两个威胁超出范围，因为它们是您的基础设施来保护：238两个威胁超出范围，因为它们是您的基础设施来保护：

239 239

240* **受损的网关主机**：主机既持有上游凭证，又向每个连接的开发者分发 [托管设置](/zh-CN/claude-apps-gateway-config#managed)，因此对网关配置的控制与对您的 MDM 的控制相当。CLI 的一次性批准对话框用于 shell 能力设置限制无声更改，但不替代主机安全。240* **受损的网关主机**：主机既持有上游凭证，又向每个连接的开发者分发 [托管设置](/docs/zh-CN/claude-apps-gateway-config#managed)，因此对网关配置的控制与对您的 MDM 的控制相当。CLI 的一次性批准对话框用于 shell 能力设置限制无声更改，但不替代主机安全。

241* **恶意 OIDC 提供商**：提供商签署网关信任的 id\_tokens，因此它可以声称任何身份。审查和保护您的 IdP 是您的责任。241* **恶意 OIDC 提供商**：提供商签署网关信任的 id\_tokens，因此它可以声称任何身份。审查和保护您的 IdP 是您的责任。

242 242

243<h3 id="user-code-brute-force-resistance">243<h3 id="user-code-brute-force-resistance">

246 246

247开发者在 `/device` 验证页面中输入的 `user_code` 是从 20 字符字母表中抽取的 8 个字符，产生 20⁸ 或约 2.56×10¹⁰ 个组合，在 10 分钟后过期。247开发者在 `/device` 验证页面中输入的 `user_code` 是从 20 字符字母表中抽取的 8 个字符，产生 20⁸ 或约 2.56×10¹⁰ 个组合，在 10 分钟后过期。

248 248

249网关在设备授权端点上应用按 IP 速率限制，可通过 [`rate_limits`](/zh-CN/claude-apps-gateway-config#http-tuning) 配置。如果许多开发者从单个共享公司 NAT 地址登录，提高限制。限制仅适用于登录流，不适用于推理。249网关在设备授权端点上应用按 IP 速率限制，可通过 [`rate_limits`](/docs/zh-CN/claude-apps-gateway-config#http-tuning) 配置。如果许多开发者从单个共享公司 NAT 地址登录，提高限制。限制仅适用于登录流，不适用于推理。

250 250

251<h3 id="compliance-posture">251<h3 id="compliance-posture">

252 合规性态势252 合规性态势

255* **数据驻留**：网关自己的数据平面除非 Anthropic API 是配置的上游，否则不向 Anthropic 发送任何内容；当它是时，您现有的数据处理协议适用于推理路径。遥测、审计、身份和设置仅去往您配置的目的地。255* **数据驻留**：网关自己的数据平面除非 Anthropic API 是配置的上游，否则不向 Anthropic 发送任何内容；当它是时，您现有的数据处理协议适用于推理路径。遥测、审计、身份和设置仅去往您配置的目的地。

256* **主机进程流量**：主机进程是 Claude Code CLI，它可以向 Anthropic 发送启动分析和更新检查。对于严格出口部署，在网关的容器环境中设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`。256* **主机进程流量**：主机进程是 Claude Code CLI，它可以向 Anthropic 发送启动分析和更新检查。对于严格出口部署，在网关的容器环境中设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`。

257* **客户端分析**：CLI 在登录到网关时禁用自己的使用分析，错误报告在第三方 API 表面上默认关闭。257* **客户端分析**：CLI 在登录到网关时禁用自己的使用分析，错误报告在第三方 API 表面上默认关闭。

258* **客户端机器**：开发者的 CLI 仍然向 Anthropic 发送 WebFetch 主机名检查和版本检查，除非设置了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` 和 `skipWebFetchPreflight: true`。请参阅 [数据使用](/zh-CN/data-usage)。258* **客户端机器**：开发者的 CLI 仍然向 Anthropic 发送 WebFetch 主机名检查和版本检查，除非设置了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` 和 `skipWebFetchPreflight: true`。请参阅 [数据使用](/docs/zh-CN/data-usage)。

259* **调查评分**：网关凭证禁用 Anthropic 绑定的评分接收器，因此评分不发送给 Anthropic。259* **调查评分**：网关凭证禁用 Anthropic 绑定的评分接收器，因此评分不发送给 Anthropic。

260* **成绩单共享**：在调查的成绩单共享提示上选择"是"会在 `~/.claude/feedback-bundles/` 下写入本地文件，而不是上传到 Anthropic。260* **成绩单共享**：在调查的成绩单共享提示上选择"是"会在 `~/.claude/feedback-bundles/` 下写入本地文件，而不是上传到 Anthropic。

261* **客户端更新**：更新检查与网关流量分开。通过您自己的分发固定版本，如果笔记本电脑不得获取版本，设置 `DISABLE_UPDATES`。`DISABLE_AUTOUPDATER` 仅停止后台更新，而 `claude update` 仍然有效。261* **客户端更新**：更新检查与网关流量分开。通过您自己的分发固定版本，如果笔记本电脑不得获取版本，设置 `DISABLE_UPDATES`。`DISABLE_AUTOUPDATER` 仅停止后台更新，而 `claude update` 仍然有效。

262* **TLS**：在生产中通过 HTTPS 提供 `public_url`，要么从网关自己的监听器通过 `listen.tls`，要么从 TLS 终止入口在普通 HTTP 副本前面，设置 `listen.public_url`。网关不拒绝普通 HTTP。IdP 必须在生产中提供 HTTPS，Postgres 支持 `?sslmode=require`。在您的入口处设置 `Strict-Transport-Security`。262* **TLS**：在生产中通过 HTTPS 提供 `public_url`，要么从网关自己的监听器通过 `listen.tls`，要么从 TLS 终止入口在普通 HTTP 副本前面，设置 `listen.public_url`。网关不拒绝普通 HTTP。IdP 必须在生产中提供 HTTPS，Postgres 支持 `?sslmode=require`。在您的入口处设置 `Strict-Transport-Security`。

263* **漏洞披露**：遵循 [报告安全问题](/zh-CN/security#reporting-security-issues)263* **漏洞披露**：遵循 [报告安全问题](/docs/zh-CN/security#reporting-security-issues)

264 264

265<h2 id="troubleshooting">265<h2 id="troubleshooting">

266 故障排除266 故障排除

272* **登录问题**：开发者运行 `claude --debug-file ./claude-debug.txt`，重现，并发送该文件加上相同窗口的网关审计日志272* **登录问题**：开发者运行 `claude --debug-file ./claude-debug.txt`，重现，并发送该文件加上相同窗口的网关审计日志

273* **推理问题**：请求的模型、配置的上游和请求的网关审计日志，记录哪个上游提供了它和响应状态273* **推理问题**：请求的模型、配置的上游和请求的网关审计日志，记录哪个上游提供了它和响应状态

274 274

275网关的 stderr 包含审计事件流，审计日志记录开发者身份，调试文件记录来自开发者机器的 hook 和 MCP 服务器输出。在发布到公开问题前，请审查并隐去这些信息。

276

275| 症状 | 原因 | 修复 |277| 症状 | 原因 | 修复 |

276| ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |278| ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

279| CLI `/login`：`Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | 网关主机名解析为至少一个公共 IP 地址。Claude Code 检查每个解析的地址，需要每一个都是私有的。常见原因是一个双栈名称，其中一个族解析为公共地址，包括 AWS 内部双栈负载均衡器，它们返回公共范围 AAAA 地址。Anthropic 运营的公共网关端点免于检查，`/login` 通过 `https://` 接受它们。在 v2.1.206 之前，`/login` 拒绝它们，就像任何其他公共地址一样 | 让网关名称在开发者机器上仅解析为私有地址。对于双栈名称，删除公共范围记录或提供单独的仅内部 DNS 名称。请参阅 [私有网络先决条件](/zh-CN/claude-apps-gateway#prerequisites)。 |281| CLI `/login`：`Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | 网关主机名解析为至少一个公共 IP 地址。Claude Code 检查每个解析的地址，需要每一个都是私有的。常见原因是一个双栈名称，其中一个族解析为公共地址，包括 AWS 内部双栈负载均衡器，它们返回公共范围 AAAA 地址。Anthropic 运营的公共网关端点免于检查，`/login` 通过 `https://` 接受它们。在 v2.1.206 之前，`/login` 拒绝它们，就像任何其他公共地址一样 | 让网关名称在开发者机器上仅解析为私有地址。对于双栈名称，删除公共范围记录或提供单独的仅内部 DNS 名称。请参阅 [私有网络先决条件](/docs/zh-CN/claude-apps-gateway#prerequisites)。 |

280| CLI `/login`：`Gateway login requires a direct connection and does not support connecting through an HTTP proxy` | `HTTPS_PROXY` 或 `HTTP_PROXY` 适用于网关主机，代理的主机名解析为公共地址。代理的主机解析为仅私有地址是允许的，不会触发此错误 | 在开发者的机器上将网关主机添加到 `NO_PROXY`，以便连接是直接的，或使用主机名解析为私有地址的代理 |282| CLI `/login`：`Gateway login requires a direct connection and does not support connecting through an HTTP proxy` | `HTTPS_PROXY` 或 `HTTP_PROXY` 适用于网关主机，代理的主机名解析为公共地址。代理的主机解析为仅私有地址是允许的，不会触发此错误 | 在开发者的机器上将网关主机添加到 `NO_PROXY`，以便连接是直接的，或使用主机名解析为私有地址的代理 |

282| 启动退出，配置验证错误命名 `store.postgres_url` | 未配置 Postgres；网关需要 Postgres | 设置 `store.postgres_url`。对于本地开发，使用一次性容器：`docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |284| 启动退出，配置验证错误命名 `store.postgres_url` | 未配置 Postgres；网关需要 Postgres | 设置 `store.postgres_url`。对于本地开发，使用一次性容器：`docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |

286| `/oauth/callback` 显示"Sign-in could not be completed" | 电子邮件域被拒绝，id\_token 验证失败，或 `email_verified` 明确为 `false`，网关总是拒绝，没有覆盖 | 检查 `allowed_email_domains` 和 IdP 返回验证的 `email` 声明。对于 `email_verified: false`，修复 IdP 端验证。如果您的 IdP 在不同的声明名称下发出电子邮件，设置 `oidc.email_claim`。 |288| `/oauth/callback` 显示"Sign-in could not be completed" | 电子邮件域被拒绝，id\_token 验证失败，或 `email_verified` 明确为 `false`，网关总是拒绝，没有覆盖 | 检查 `allowed_email_domains` 和 IdP 返回验证的 `email` 声明。对于 `email_verified: false`，修复 IdP 端验证。如果您的 IdP 在不同的声明名称下发出电子邮件，设置 `oidc.email_claim`。 |

293| 登录在 IdP 处完成，但回调失败，Chrome 中出现 CSP 错误或 Safari 中出现"this sign-in link has expired" | IdP 通过 `response_mode=form_post` 返回代码，它通过 POST 自动提交到 `/oauth/callback`。Chrome 在严格 CSP 下阻止它；Safari 允许提交，但回调仅读取查询字符串。 | 确保您的 IdP 遵守 `response_mode=query`，网关明确请求它，以便回调是普通重定向 |295| 登录在 IdP 处完成，但回调失败，Chrome 中出现 CSP 错误或 Safari 中出现"this sign-in link has expired" | IdP 通过 `response_mode=form_post` 返回代码，它通过 POST 自动提交到 `/oauth/callback`。Chrome 在严格 CSP 下阻止它；Safari 允许提交，但回调仅读取查询字符串。 | 确保您的 IdP 遵守 `response_mode=query`，网关明确请求它，以便回调是普通重定向 |

296| CLI `/login`：`"Could not verify the gateway's TLS certificate"` 或 `SELF_SIGNED_CERT_IN_CHAIN` | 网关的 TLS 链由 CLI 主机的信任存储中不存在的私有 CA 签署 | Claude Code 默认在本机二进制文件上读取 OS 信任存储，在 Node 22.15 或更高版本上；[`CLAUDE_CODE_CERT_STORE`](/zh-CN/network-config#ca-certificate-store) 控制此行为。如果 CA 安装在 OS 信任存储中，确保开发者在当前运行时上。否则在启动前将 `NODE_EXTRA_CA_CERTS` 设置为 CA 证书 PEM。首次连接指纹提示仍然适用。 |298| CLI `/login`：`"Could not verify the gateway's TLS certificate"` 或 `SELF_SIGNED_CERT_IN_CHAIN` | 网关的 TLS 链由 CLI 主机的信任存储中不存在的私有 CA 签署 | Claude Code 默认在本机二进制文件上读取 OS 信任存储，在 Node 22.15 或更高版本上；[`CLAUDE_CODE_CERT_STORE`](/docs/zh-CN/network-config#ca-certificate-store) 控制此行为。如果 CA 安装在 OS 信任存储中，确保开发者在当前运行时上。否则在启动前将 `NODE_EXTRA_CA_CERTS` 设置为 CA 证书 PEM。首次连接指纹提示仍然适用。 |

297 299

298<h2 id="related">300<h2 id="related">

299 相关301 相关

300</h2>302</h2>

301 303

302* [Claude 应用网关概述](/zh-CN/claude-apps-gateway)：快速入门和开发者连接304* [Claude 应用网关概述](/docs/zh-CN/claude-apps-gateway)：快速入门和开发者连接

303* [配置参考](/zh-CN/claude-apps-gateway-config)：每个 `gateway.yaml` 选项305* [配置参考](/docs/zh-CN/claude-apps-gateway-config)：每个 `gateway.yaml` 选项

commands.md +78 −78

Details

10 10

11输入 `/` 可以查看所有可用命令，或输入 `/` 后跟字母来筛选。11输入 `/` 可以查看所有可用命令，或输入 `/` 后跟字母来筛选。

12 12

13命令只在您的消息开头被识别。命令名称后面的文本作为参数传递给它。{/* min-version: 2.1.199 */}从 v2.1.199 开始，[skills](/zh-CN/skills#pass-arguments-to-skills) 是例外：skill 调用后跟更多 skills，例如 `/skill-a /skill-b do XYZ`，会加载开头命名的每个 skill，并将尾部文本作为参数传递给每个 skill。最多可以链接六个 skills。13命令只在您的消息开头被识别。命令名称后面的文本作为参数传递给它。{/* min-version: 2.1.199 */}从 v2.1.199 开始，[skills](/docs/zh-CN/skills#pass-arguments-to-skills) 是例外：skill 调用后跟更多 skills，例如 `/skill-a /skill-b do XYZ`，会加载开头命名的每个 skill，并将尾部文本作为参数传递给每个 skill。最多可以链接六个 skills。

14 14

15如果您在 Claude 正在响应时发送命令，它会排队并在当前轮次完成后运行。某些命令，例如 `/status`、`/tasks` 和 `/usage`，会立即运行而不中断响应。15如果您在 Claude 正在响应时发送命令，它会排队并在当前轮次完成后运行。某些命令，例如 `/status`、`/tasks` 和 `/usage`，会立即运行而不中断响应。

16 16

20 20

21大多数命令在会话的特定点很有用，从设置项目到发布更改。21大多数命令在会话的特定点很有用，从设置项目到发布更改。

22 22

23**首次在存储库中的会话。** 运行 `/init` 以生成启动器 `CLAUDE.md`，然后运行 `/memory` 以完善它。使用 `/mcp` 来设置项目需要的任何服务器，要求 Claude 创建您想要的任何 [subagents](/zh-CN/sub-agents)，并运行 `/permissions` 来设置您的批准规则。23**首次在存储库中的会话。** 运行 `/init` 以生成启动器 `CLAUDE.md`，然后运行 `/memory` 以完善它。使用 `/mcp` 来设置项目需要的任何服务器，要求 Claude 创建您想要的任何 [subagents](/docs/zh-CN/sub-agents)，并运行 `/permissions` 来设置您的批准规则。

24 24

25**在任务期间。** `/plan` 在大型更改前切换到 Plan Mode。`/model` 和 `/effort` 调整您使用的模型以及它应用的推理量。当对话变长时，`/context` 显示窗口中填充的内容，`/compact` 将其总结以释放空间。使用 `/btw` 进行快速附加说明，不应该添加到对话历史记录中。25**在任务期间。** `/plan` 在大型更改前切换到 Plan Mode。`/model` 和 `/effort` 调整您使用的模型以及它应用的推理量。当对话变长时，`/context` 显示窗口中填充的内容，`/compact` 将其总结以释放空间。使用 `/btw` 进行快速附加说明，不应该添加到对话历史记录中。

26 26

27**并行运行工作。** Claude 将侧面任务委派给 [subagents](/zh-CN/sub-agents)，`/tasks` 列出当前会话的后台工作，包括已完成的 subagents。`/background` 分离整个会话以继续作为 [background agent](/zh-CN/agent-view) 运行，并释放您的终端。对于跨越代码库的大型更改，`/batch` 将其分解为独立单元，并在其自己的 [worktree](/zh-CN/worktrees) 中运行每个单元。请参阅 [Run agents in parallel](/zh-CN/agents) 以了解这些方法如何相关联。27**并行运行工作。** Claude 将侧面任务委派给 [subagents](/docs/zh-CN/sub-agents)，`/tasks` 列出当前会话的后台工作，包括已完成的 subagents。`/background` 分离整个会话以继续作为 [background agent](/docs/zh-CN/agent-view) 运行，并释放您的终端。对于跨越代码库的大型更改，`/batch` 将其分解为独立单元，并在其自己的 [worktree](/docs/zh-CN/worktrees) 中运行每个单元。请参阅 [Run agents in parallel](/docs/zh-CN/agents) 以了解这些方法如何相关联。

28 28

29**在您发布之前。** `/diff` 显示更改的内容，`/code-review` 检查差异以查找正确性错误和清理，并可以使用 `--fix` 应用这些发现，`/review` 对 GitHub pull request 运行快速单遍只读审查，`/code-review <level> <pr#>` 对其运行多代理审查，`/security-review` 检查差异以查找安全漏洞。`/code-review ultra` 在云中运行多代理审查。29**在您发布之前。** `/diff` 显示更改的内容，`/code-review` 检查差异以查找正确性错误和清理，并可以使用 `--fix` 应用这些发现，`/review` 对 GitHub pull request 运行快速单遍只读审查，`/code-review <level> <pr#>` 对其运行多代理审查，`/security-review` 检查差异以查找安全漏洞。`/code-review ultra` 在云中运行多代理审查。

30 30

38 38

39下表列出了 Claude Code 中包含的所有命令。大多数是内置命令，其行为被编码到 CLI 中。两种条目被标记：39下表列出了 Claude Code 中包含的所有命令。大多数是内置命令，其行为被编码到 CLI 中。两种条目被标记：

40 40

41* **[Skill](/zh-CN/skills#bundled-skills)**：一个捆绑的 skill。它的工作方式与您自己编写的 skills 相同：一个提示交给 Claude，Claude 也可以在相关时自动调用。41* **[Skill](/docs/zh-CN/skills#bundled-skills)**：一个捆绑的 skill。它的工作方式与您自己编写的 skills 相同：一个提示交给 Claude，Claude 也可以在相关时自动调用。

~~42* **[Workflow](/zh-CN/workflows#bundled-workflows)**：一个捆绑的[动态工作流](/zh-CN/workflows)，可以跨许多子代理展开工作并在后台运行。~~42* **[Workflow](/docs/zh-CN/workflows#bundled-workflows)**：一个捆绑的[动态工作流](/docs/zh-CN/workflows)，可以跨许多子代理展开工作并在后台运行。

43 43

~~44要添加您自己的命令，请参阅 [skills](/zh-CN/skills)。~~44要添加您自己的命令，请参阅 [skills](/docs/zh-CN/skills)。

45 45

46在下表中，`<arg>` 表示必需的参数，`[arg]` 表示可选参数。46在下表中，`<arg>` 表示必需的参数，`[arg]` 表示可选参数。

47 47

51 51

52| 命令 | 用途 |52| 命令 | 用途 |

53| :--------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |53| :--------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

54| `/add-dir <path>` | 为当前会话期间的文件访问添加工作目录。输入部分路径会显示匹配的目录建议；按 `Tab` 接受一个。大多数 `.claude/` 配置[不会从添加的目录中发现](/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍后使用 `--continue` 或 `--resume` 从添加的目录恢复会话 |54| `/add-dir <path>` | 为当前会话期间的文件访问添加工作目录。输入部分路径会显示匹配的目录建议；按 `Tab` 接受一个。大多数 `.claude/` 配置[不会从添加的目录中发现](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍后使用 `--continue` 或 `--resume` 从添加的目录恢复会话 |

55| `/advisor [model\|off]` | 启用或禁用[顾问工具](/zh-CN/advisor)，它在任务期间的关键时刻咨询第二个模型以获取指导。接受 `opus`、`sonnet`、`fable`（{/* min-version: 2.1.170 */}v2.1.170+）或完整模型 ID。不带参数时，打开选择器 |55| `/advisor [model\|off]` | 启用或禁用[顾问工具](/docs/zh-CN/advisor)，它在任务期间的关键时刻咨询第二个模型以获取指导。接受 `opus`、`sonnet`、`fable`（{/* min-version: 2.1.170 */}v2.1.170+）或完整模型 ID。不带参数时，打开选择器 |

56| `/agents` | {/* min-version: 2.1.198 */}从 v2.1.198 开始，运行 `/agents` 会打印一个提醒，要求您询问 Claude 创建或管理 [subagents](/zh-CN/sub-agents)，或直接编辑 `.claude/agents/` 或 `~/.claude/agents/`。{/* max-version: 2.1.197 */}在 v2.1.197 及更早版本中，打开用于创建和管理 subagent 配置的交互式界面 |56| `/agents` | {/* min-version: 2.1.198 */}从 v2.1.198 开始，运行 `/agents` 会打印一个提醒，要求您询问 Claude 创建或管理 [subagents](/docs/zh-CN/sub-agents)，或直接编辑 `.claude/agents/` 或 `~/.claude/agents/`。{/* max-version: 2.1.197 */}在 v2.1.197 及更早版本中，打开用于创建和管理 subagent 配置的交互式界面 |

57| `/autofix-pr [prompt]` | 生成一个[网络版 Claude Code](/zh-CN/claude-code-on-the-web#auto-fix-pull-requests) 会话，监视当前分支的 PR，并在 CI 失败或审阅者留下评论时推送修复。使用 `gh pr view` 检测已检出分支的开放 PR；要监视不同的 PR，请先检出其分支。默认情况下，远程会话被告知修复每个 CI 失败和审阅评论；传递一个提示以给它不同的说明，例如 `/autofix-pr only fix lint and type errors`。需要 `gh` CLI 和访问[网络版 Claude Code](/zh-CN/claude-code-on-the-web) |57| `/autofix-pr [prompt]` | 生成一个[网络版 Claude Code](/docs/zh-CN/claude-code-on-the-web#auto-fix-pull-requests) 会话，监视当前分支的 PR，并在 CI 失败或审阅者留下评论时推送修复。使用 `gh pr view` 检测已检出分支的开放 PR；要监视不同的 PR，请先检出其分支。默认情况下，远程会话被告知修复每个 CI 失败和审阅评论；传递一个提示以给它不同的说明，例如 `/autofix-pr only fix lint and type errors`。需要 `gh` CLI 和访问[网络版 Claude Code](/docs/zh-CN/claude-code-on-the-web) |

58| `/background [prompt]` | 将当前会话分离以作为[后台 agent](/zh-CN/agent-view) 运行并释放此终端。传递一个提示以在分离前发送一条更多指令。使用 `claude agents` 监视会话。别名：`/bg` |58| `/background [prompt]` | 将当前会话分离以作为[后台 agent](/docs/zh-CN/agent-view) 运行并释放此终端。传递一个提示以在分离前发送一条更多指令。使用 `claude agents` 监视会话。别名：`/bg` |

59| `/batch <instruction>` | **[Skill](/zh-CN/skills#bundled-skills).** 在整个代码库中并行编排大规模更改。研究代码库，将工作分解为 5 到 30 个独立单元，并呈现一个计划。获得批准后，在隔离的 [git worktree](/zh-CN/worktrees) 中为每个单元生成一个[后台 subagent](/zh-CN/sub-agents#run-subagents-in-foreground-or-background)。每个 subagent 实现其单元、运行测试并打开一个 pull request。需要一个 git 存储库。示例：`/batch migrate src/ from Solid to React` |59| `/batch <instruction>` | **[Skill](/docs/zh-CN/skills#bundled-skills).** 在整个代码库中并行编排大规模更改。研究代码库，将工作分解为 5 到 30 个独立单元，并呈现一个计划。获得批准后，在隔离的 [git worktree](/docs/zh-CN/worktrees) 中为每个单元生成一个[后台 subagent](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)。每个 subagent 实现其单元、运行测试并打开一个 pull request。需要一个 git 存储库。示例：`/batch migrate src/ from Solid to React` |

60| `/branch [name]` | 在此点创建当前对话的分支，以便您可以尝试不同的方向而不会丢失当前的对话。切换到分支并保留原始分支，您可以使用 `/resume` 返回。要将附加任务交给后台 subagent 而不是自己切换到副本，请使用 `/fork` |60| `/branch [name]` | 在此点创建当前对话的分支，以便您可以尝试不同的方向而不会丢失当前的对话。切换到分支并保留原始分支，您可以使用 `/resume` 返回。要将附加任务交给后台 subagent 而不是自己切换到副本，请使用 `/fork` |

62| `/cd <path>` | {/* min-version: 2.1.169 */}将此会话移动到新的工作目录。对话的提示缓存被保留：新目录的 [`CLAUDE.md`](/zh-CN/memory) 作为消息附加，而不是重建系统提示。会话被重新定位到新目录的项目存储，因此 `--resume` 和 `--continue` 从那里找到它。如果您之前未在该目录中工作过，会提示您信任该目录。{/* min-version: 2.1.206 */}输入部分路径会显示匹配的目录建议；按 `Tab` 接受一个。建议需要 Claude Code v2.1.206 或更高版本。要授予对额外目录的访问权限而不移动会话，请使用 `/add-dir`。使用 [`Cd` 权限规则](/zh-CN/permissions#cd) 限制或禁用 `/cd` 目标。需要 Claude Code v2.1.169 或更高版本；早期版本报告 `Unknown command: /cd` |62| `/cd <path>` | {/* min-version: 2.1.169 */}将此会话移动到新的工作目录。对话的提示缓存被保留：新目录的 [`CLAUDE.md`](/docs/zh-CN/memory) 作为消息附加，而不是重建系统提示。会话被重新定位到新目录的项目存储，因此 `--resume` 和 `--continue` 从那里找到它。如果您之前未在该目录中工作过，会提示您信任该目录。{/* min-version: 2.1.206 */}输入部分路径会显示匹配的目录建议；按 `Tab` 接受一个。建议需要 Claude Code v2.1.206 或更高版本。要授予对额外目录的访问权限而不移动会话，请使用 `/add-dir`。使用 [`Cd` 权限规则](/docs/zh-CN/permissions#cd) 限制或禁用 `/cd` 目标。需要 Claude Code v2.1.169 或更高版本；早期版本报告 `Unknown command: /cd` |

64| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/zh-CN/skills#bundled-skills).** 为您的项目语言（Python、TypeScript、Java、Go、Ruby、C#、PHP 或 cURL）和 Managed Agents 参考加载 Claude API 参考资料。涵盖工具使用、流式传输、批处理、结构化输出和常见陷阱。当您的代码导入 `anthropic` 或 `@anthropic-ai/sdk` 时也会自动激活。运行 `/claude-api migrate` 以将现有 Claude API 代码升级到更新的模型：Claude 询问要扫描哪些文件以及要针对哪个模型，然后更新在版本之间更改的模型 ID、thinking 配置和其他参数。运行 `/claude-api managed-agents-onboard` 以获得交互式演练，从头开始创建新的 Managed Agent |64| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/docs/zh-CN/skills#bundled-skills).** 为您的项目语言（Python、TypeScript、Java、Go、Ruby、C#、PHP 或 cURL）和 Managed Agents 参考加载 Claude API 参考资料。涵盖工具使用、流式传输、批处理、结构化输出和常见陷阱。当您的代码导入 `anthropic` 或 `@anthropic-ai/sdk` 时也会自动激活。运行 `/claude-api migrate` 以将现有 Claude API 代码升级到更新的模型：Claude 询问要扫描哪些文件以及要针对哪个模型，然后更新在版本之间更改的模型 ID、thinking 配置和其他参数。运行 `/claude-api managed-agents-onboard` 以获得交互式演练，从头开始创建新的 Managed Agent |

65| `/clear [name]` | 使用空上下文启动新对话。传递一个名称以在 `/resume` 选择器中标记之前的对话。要在继续同一对话的同时释放上下文，请改用 `/compact`。使用 `/resume` 恢复之前的对话，或在同一 Claude Code 进程中，{/* min-version: 2.1.191 */}从[倒回菜单的上一个会话条目](/zh-CN/checkpointing#rewind-past-a-cleared-conversation)恢复它。别名：`/reset`、`/new` |65| `/clear [name]` | 使用空上下文启动新对话。传递一个名称以在 `/resume` 选择器中标记之前的对话。要在继续同一对话的同时释放上下文，请改用 `/compact`。使用 `/resume` 恢复之前的对话，或在同一 Claude Code 进程中，{/* min-version: 2.1.191 */}从[倒回菜单的上一个会话条目](/docs/zh-CN/checkpointing#rewind-past-a-cleared-conversation)恢复它。别名：`/reset`、`/new` |

66| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [target]` | **[Skill](/zh-CN/skills#bundled-skills).** 审阅当前差异以查找正确性错误以及重用、简化和效率清理。传递 `--fix` 以将发现应用到您的工作树，传递 `--comment` 以将其作为内联 GitHub PR 评论发布，或传递 `ultra` 以运行深度[云审阅](/zh-CN/ultrareview)。{/* min-version: 2.1.154 */}从 v2.1.154 开始，`/simplify` 运行单独的仅清理审阅，应用修复而不寻找错误。有关工作量级别和目标，请参阅[本地审阅差异](/zh-CN/code-review#review-a-diff-locally) |66| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [target]` | **[Skill](/docs/zh-CN/skills#bundled-skills).** 审阅当前差异以查找正确性错误以及重用、简化和效率清理。传递 `--fix` 以将发现应用到您的工作树，传递 `--comment` 以将其作为内联 GitHub PR 评论发布，或传递 `ultra` 以运行深度[云审阅](/docs/zh-CN/ultrareview)。{/* min-version: 2.1.154 */}从 v2.1.154 开始，`/simplify` 运行单独的仅清理审阅，应用修复而不寻找错误。有关工作量级别和目标，请参阅[本地审阅差异](/docs/zh-CN/code-review#review-a-diff-locally) |

67| `/color [color\|default]` | 为当前会话设置提示栏颜色。可用颜色：`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、`cyan`。使用 `default` 重置，或不带参数运行以选择随机颜色。当 [Remote Control](/zh-CN/remote-control) 连接时，颜色同步到 claude.ai/code。{/* min-version: 2.1.205 */}也可在非交互模式（`-p`）中使用；需要 Claude Code v2.1.205 或更高版本 |67| `/color [color\|default]` | 为当前会话设置提示栏颜色。可用颜色：`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、`cyan`。使用 `default` 重置，或不带参数运行以选择随机颜色。当 [Remote Control](/docs/zh-CN/remote-control) 连接时，颜色同步到 claude.ai/code。{/* min-version: 2.1.205 */}也可在非交互模式（`-p`）中使用；需要 Claude Code v2.1.205 或更高版本 |

68| `/compact [instructions]` | 通过总结到目前为止的对话来释放上下文。可选择性地传递焦点说明以进行总结。请参阅[压缩如何处理规则、skills 和内存文件](/zh-CN/context-window#what-survives-compaction) |68| `/compact [instructions]` | 通过总结到目前为止的对话来释放上下文。可选择性地传递焦点说明以进行总结。请参阅[压缩如何处理规则、skills 和内存文件](/docs/zh-CN/context-window#what-survives-compaction) |

69| `/config [key=value ...]` | 打开[设置](/zh-CN/settings)界面以调整主题、模型、[输出样式](/zh-CN/output-styles)和其他偏好设置。{/* min-version: 2.1.181 */}从 v2.1.181 开始，传递一个或多个 `key=value` 对以直接设置设置而无需打开界面，例如 `/config thinking=false`。{/* min-version: 2.1.182 */}从 v2.1.182 开始，也接受命名的简写键，例如 `/config theme=dark` 或 `/config model=sonnet`。`key=value` 形式也适用于非交互模式（`-p`）和[远程控制](/zh-CN/remote-control)。运行 `/config --help` 以列出每个可设置的键及其选项。别名：`/settings` |69| `/config [key=value ...]` | 打开[设置](/docs/zh-CN/settings)界面以调整主题、模型、[输出样式](/docs/zh-CN/output-styles)和其他偏好设置。{/* min-version: 2.1.181 */}从 v2.1.181 开始，传递一个或多个 `key=value` 对以直接设置设置而无需打开界面，例如 `/config thinking=false`。{/* min-version: 2.1.182 */}从 v2.1.182 开始，也接受命名的简写键，例如 `/config theme=dark` 或 `/config model=sonnet`。`key=value` 形式也适用于非交互模式（`-p`）和[远程控制](/docs/zh-CN/remote-control)。运行 `/config --help` 以列出每个可设置的键及其选项。别名：`/settings` |

71| `/copy [N]` | 将最后一个助手响应复制到剪贴板。传递数字 `N` 以复制第 N 个最新响应：`/copy 2` 复制倒数第二个。当存在代码块时，显示交互式选择器以选择单个块或完整响应。在选择器中按 `w` 将选择内容写入文件而不是剪贴板，这在 SSH 上很有用 |71| `/copy [N]` | 将最后一个助手响应复制到剪贴板。传递数字 `N` 以复制第 N 个最新响应：`/copy 2` 复制倒数第二个。当存在代码块时，显示交互式选择器以选择单个块或完整响应。在选择器中按 `w` 将选择内容写入文件而不是剪贴板，这在 SSH 上很有用 |

73| `/dataviz [request]` | **[Skill](/zh-CN/skills#bundled-skills).** 为图表、图形和仪表板提供设计指导。Claude 为数据选择图表形式，按角色分配颜色，使用捆绑脚本验证调色板的色盲安全性和对比度，并应用标记、交互和可访问性规则。使用品牌中立的占位符调色板，您可以用自己的调色板替换。{/* min-version: 2.1.198 */}需要 Claude Code v2.1.198 或更高版本 |73| `/dataviz [request]` | **[Skill](/docs/zh-CN/skills#bundled-skills).** 为图表、图形和仪表板提供设计指导。Claude 为数据选择图表形式，按角色分配颜色，使用捆绑脚本验证调色板的色盲安全性和对比度，并应用标记、交互和可访问性规则。使用品牌中立的占位符调色板，您可以用自己的调色板替换。{/* min-version: 2.1.198 */}需要 Claude Code v2.1.198 或更高版本 |

74| `/debug [description]` | **[Skill](/zh-CN/skills#bundled-skills).** 为当前会话启用调试日志记录并通过读取会话调试日志来排查问题。调试日志默认关闭，除非您使用 `claude --debug` 启动，因此在会话中途运行 `/debug` 会从该点开始捕获日志。可选择性地描述问题以集中分析 |74| `/debug [description]` | **[Skill](/docs/zh-CN/skills#bundled-skills).** 为当前会话启用调试日志记录并通过读取会话调试日志来排查问题。调试日志默认关闭，除非您使用 `claude --debug` 启动，因此在会话中途运行 `/debug` 会从该点开始捕获日志。可选择性地描述问题以集中分析 |

77| `/design-sync [hint]` | **[Skill](/zh-CN/skills#bundled-skills).** 转换您的存储库的 React 设计系统并将其上传到 [Claude Design](https://claude.ai/design)，以便它生成的设计使用您的真实组件。可选择性地命名设计系统，例如 `/design-sync Acme DS`。首次同步验证每个组件，在大型存储库上可能需要几个小时。在 Anthropic API 上可用；在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Claude Platform on AWS 上，底层工具无法访问 claude.ai，因此该命令不可用 |77| `/design-sync [hint]` | **[Skill](/docs/zh-CN/skills#bundled-skills).** 转换您的存储库的 React 设计系统并将其上传到 [Claude Design](https://claude.ai/design)，以便它生成的设计使用您的真实组件。可选择性地命名设计系统，例如 `/design-sync Acme DS`。首次同步验证每个组件，在大型存储库上可能需要几个小时。在 Anthropic API 上可用；在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Claude Platform on AWS 上，底层工具无法访问 claude.ai，因此该命令不可用 |

79| `/diff` | 打开交互式差异查看器，显示未提交的更改和每轮差异。使用左/右箭头在当前 git 差异和单个 Claude 轮次之间切换，使用上/下浏览文件。按 Enter 打开所选文件的差异，使用上/下或 PageUp/PageDown 滚动，按 Esc 返回文件列表。{/* min-version: 2.1.198 */}从 v2.1.198 开始，打开的查看器也会在存储库的 git 状态在会话外发生变化时自动刷新，例如在另一个终端中进行分支切换或提交 |79| `/diff` | 打开交互式差异查看器，显示未提交的更改和每轮差异。使用左/右箭头在当前 git 差异和单个 Claude 轮次之间切换，使用上/下浏览文件。按 Enter 打开所选文件的差异，使用上/下或 PageUp/PageDown 滚动，按 Esc 返回文件列表。{/* min-version: 2.1.198 */}从 v2.1.198 开始，打开的查看器也会在存储库的 git 状态在会话外发生变化时自动刷新，例如在另一个终端中进行分支切换或提交 |

80| `/doctor` | **[Skill](/zh-CN/skills#bundled-skills).** 运行设置检查以诊断问题并可以修复它们。检查安装健康状况，包括重复或遗留安装、`PATH` 问题和无法解析的设置文件。查找未使用的 skills、MCP servers 和 plugins 与其上下文成本，标记缓慢的 [hooks](/zh-CN/hooks)，并检查是否有更新版本。针对已检入的文件去重本地 `CLAUDE.md` 文件，通过删除 Claude 可以从代码库派生的内容来修剪已检入的 [`CLAUDE.md`](/zh-CN/memory) 文件，并将保留的始终加载的指导迁移到 [skills](/zh-CN/skills) 和按需加载的嵌套 `CLAUDE.md` 文件。修剪会删除目录布局、依赖列表和架构概览等部分，并保留陷阱、基本原理和与工具默认值不同的约定。还提供将 [auto mode](/zh-CN/permissions#permission-modes) 设置为默认值的选项，以及[预先批准](/zh-CN/permissions)经常被拒绝的只读命令。首先报告发现并在更改任何内容之前要求确认。从终端，`claude doctor` 打印只读安装诊断而不启动会话。别名：`/checkup`。{/* min-version: 2.1.206 */}CLAUDE.md 修剪检查需要 Claude Code v2.1.206 或更高版本。在 v2.1.206 之前，版本检查将 Homebrew 安装与 `autoUpdatesChannel` 设置进行比较，而不是[已安装 cask 的频道](/zh-CN/setup#configure-release-channel)。{/* min-version: 2.1.205 */}在 v2.1.205 之前，`/doctor` 打开只读诊断屏幕，按 `f` 将报告发送给 Claude |80| `/doctor` | **[Skill](/docs/zh-CN/skills#bundled-skills).** 运行设置检查以诊断问题并可以修复它们。检查安装健康状况，包括重复或遗留安装、`PATH` 问题和无法解析的设置文件。查找未使用的 skills、MCP servers 和 plugins 与其上下文成本，标记缓慢的 [hooks](/docs/zh-CN/hooks)，并检查是否有更新版本。针对已检入的文件去重本地 `CLAUDE.md` 文件，通过删除 Claude 可以从代码库派生的内容来修剪已检入的 [`CLAUDE.md`](/docs/zh-CN/memory) 文件，并将保留的始终加载的指导迁移到 [skills](/docs/zh-CN/skills) 和按需加载的嵌套 `CLAUDE.md` 文件。修剪会删除目录布局、依赖列表和架构概览等部分，并保留陷阱、基本原理和与工具默认值不同的约定。还提供将 [auto mode](/docs/zh-CN/permissions#permission-modes) 设置为默认值的选项，以及[预先批准](/docs/zh-CN/permissions)经常被拒绝的只读命令。首先报告发现并在更改任何内容之前要求确认。从终端，`claude doctor` 打印只读安装诊断而不启动会话。别名：`/checkup`。{/* min-version: 2.1.206 */}CLAUDE.md 修剪检查需要 Claude Code v2.1.206 或更高版本。在 v2.1.206 之前，版本检查将 Homebrew 安装与 `autoUpdatesChannel` 设置进行比较，而不是[已安装 cask 的频道](/docs/zh-CN/setup#configure-release-channel)。{/* min-version: 2.1.205 */}在 v2.1.205 之前，`/doctor` 打开只读诊断屏幕，按 `f` 将报告发送给 Claude |

81| `/effort [level\|auto]` | 设置模型[工作量级别](/zh-CN/model-config#adjust-effort-level)。接受 `low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`；可用级别取决于模型，`max` 和 `ultracode` 仅限会话。`ultracode` 是一个 Claude Code 设置，它结合了 `xhigh` 推理和自动[工作流](/zh-CN/workflows#let-claude-decide-with-ultracode)编排。`auto` 重置为模型默认值。不带参数时，打开交互式滑块；使用左右箭头选择级别，按 `Enter` 应用。立即生效，无需等待当前响应完成。{/* min-version: 2.1.205 */}也可在非交互模式（`-p`）中使用级别参数，其中它仅适用于当前会话且不保存为您的默认值；需要 Claude Code v2.1.205 或更高版本。在 Fable 5、Opus 4.8 和 Opus 4.7 上，当[模型默认工作量级别保持](/zh-CN/model-config#adjust-effort-level)生效时，非交互 `/effort` 报告 `Not applied`，因此改为在启动时传递 `--effort` |81| `/effort [level\|auto]` | 设置模型[工作量级别](/docs/zh-CN/model-config#adjust-effort-level)。接受 `low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`；可用级别取决于模型，`max` 和 `ultracode` 仅限会话。`ultracode` 是一个 Claude Code 设置，它结合了 `xhigh` 推理和自动[工作流](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)编排。`auto` 重置为模型默认值。不带参数时，打开交互式滑块；使用左右箭头选择级别，按 `Enter` 应用。立即生效，无需等待当前响应完成。{/* min-version: 2.1.205 */}也可在非交互模式（`-p`）中使用级别参数，其中它仅适用于当前会话且不保存为您的默认值；需要 Claude Code v2.1.205 或更高版本。在 Fable 5、Opus 4.8 和 Opus 4.7 上，当[模型默认工作量级别保持](/docs/zh-CN/model-config#adjust-effort-level)生效时，非交互 `/effort` 报告 `Not applied`，因此改为在启动时传递 `--effort` |

84| `/fast [on\|off]` | 切换[快速模式](/zh-CN/fast-mode)开启或关闭。{/* min-version: 2.1.205 */}在非交互模式（`-p`）中，`/fast` 仅在使用快速模式在其 [`--settings`](/zh-CN/cli-reference#cli-flags) 值中启动的会话中工作，例如 `claude -p --settings '{"fastMode": true}'`；切换然后仅适用于当前会话且不保存为您的默认值，在任何其他非交互会话中，该命令报告快速模式不可用。需要 Claude Code v2.1.205 或更高版本 |84| `/fast [on\|off]` | 切换[快速模式](/docs/zh-CN/fast-mode)开启或关闭。{/* min-version: 2.1.205 */}在非交互模式（`-p`）中，`/fast` 仅在使用快速模式在其 [`--settings`](/docs/zh-CN/cli-reference#cli-flags) 值中启动的会话中工作，例如 `claude -p --settings '{"fastMode": true}'`；切换然后仅适用于当前会话且不保存为您的默认值，在任何其他非交互会话中，该命令报告快速模式不可用。需要 Claude Code v2.1.205 或更高版本 |

86| `/fewer-permission-prompts` | **[Skill](/zh-CN/skills#bundled-skills).** 扫描您的记录以查找常见的只读 Bash 和 MCP 工具调用，然后向项目 `.claude/settings.json` 添加优先级允许列表以减少权限提示 |86| `/fewer-permission-prompts` | **[Skill](/docs/zh-CN/skills#bundled-skills).** 扫描您的记录以查找常见的只读 Bash 和 MCP 工具调用，然后向项目 `.claude/settings.json` 添加优先级允许列表以减少权限提示 |

87| `/focus` | 切换焦点视图，仅显示您的最后一个提示、带有编辑 diffstats 的单行工具调用摘要和最终响应。{/* min-version: 2.1.198 */}从 v2.1.198 开始，工具调用摘要也计算在轮次中启动的 subagents 数量，并将已完成的后台任务通知折叠为单个计数。选择在会话间保持；设置 [`viewMode`](/zh-CN/settings#available-settings) 在设置中以覆盖它。仅在[全屏渲染](/zh-CN/fullscreen)中可用 |87| `/focus` | 切换焦点视图，仅显示您的最后一个提示、带有编辑 diffstats 的单行工具调用摘要和最终响应。{/* min-version: 2.1.198 */}从 v2.1.198 开始，工具调用摘要也计算在轮次中启动的 subagents 数量，并将已完成的后台任务通知折叠为单个计数。选择在会话间保持；设置 [`viewMode`](/docs/zh-CN/settings#available-settings) 在设置中以覆盖它。仅在[全屏渲染](/docs/zh-CN/fullscreen)中可用 |

88| `/fork <directive>` | {/* min-version: 2.1.161 */}生成一个[分叉的 subagent](/zh-CN/sub-agents#fork-the-current-conversation)：一个继承完整对话的后台 subagent，在您继续进行时处理该指令。其结果在完成时返回到您的对话。要自己切换到对话的副本，请使用 `/branch`。在 v2.1.161 之前，`/fork` 是 `/branch` 的别名 |88| `/fork <directive>` | {/* min-version: 2.1.161 */}生成一个[分叉的 subagent](/docs/zh-CN/sub-agents#fork-the-current-conversation)：一个继承完整对话的后台 subagent，在您继续进行时处理该指令。其结果在完成时返回到您的对话。要自己切换到对话的副本，请使用 `/branch`。在 v2.1.161 之前，`/fork` 是 `/branch` 的别名 |

90| `/heapdump` | 将 JavaScript 堆快照和内存分解写入 `~/Desktop`，或在 Linux 上没有 Desktop 文件夹的情况下写入您的主目录，以诊断高内存使用情况。请参阅[故障排除](/zh-CN/troubleshooting#high-cpu-or-memory-usage) |90| `/heapdump` | 将 JavaScript 堆快照和内存分解写入 `~/Desktop`，或在 Linux 上没有 Desktop 文件夹的情况下写入您的主目录，以诊断高内存使用情况。`.heapsnapshot` 文件包含您的完整对话和凭证，所以不要分享它。请参阅[故障排除](/docs/zh-CN/troubleshooting#high-cpu-or-memory-usage) |

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

101| `/loop [interval] [prompt]` | **[Skill](/zh-CN/skills#bundled-skills).** 在会话保持打开状态时重复运行提示。省略间隔，Claude 会在迭代之间自动调整步速。省略提示，[在可用的地方](/zh-CN/scheduled-tasks#run-the-built-in-maintenance-prompt)Claude 运行自主维护检查或运行 `.claude/loop.md` 中的提示。示例：`/loop 5m check if the deploy finished`。请参阅[按计划运行提示](/zh-CN/scheduled-tasks)。别名：`/proactive` |101| `/loop [interval] [prompt]` | **[Skill](/docs/zh-CN/skills#bundled-skills).** 在会话保持打开状态时重复运行提示。省略间隔，Claude 会在迭代之间自动调整步速。省略提示，[在可用的地方](/docs/zh-CN/scheduled-tasks#run-the-built-in-maintenance-prompt)Claude 运行自主维护检查或运行 `.claude/loop.md` 中的提示。示例：`/loop 5m check if the deploy finished`。请参阅[按计划运行提示](/docs/zh-CN/scheduled-tasks)。别名：`/proactive` |

102| `/mcp [reconnect <server>\|enable\|disable [<server>\|all]]` | 管理 MCP server 连接和 OAuth 身份验证。不带参数运行以打开交互式列表，传递 `reconnect <server>` 以重新连接一个断开连接的 server，或传递 `enable`/`disable` 与 server 名称或 `all` 以更改连接状态而不打开对话框。{/* min-version: 2.1.205 */}也可在非交互模式（`-p`）中使用，其中不带参数运行它会打印 server 状态的文本摘要而不是打开列表；需要 Claude Code v2.1.205 或更高版本 |102| `/mcp [reconnect <server>\|enable\|disable [<server>\|all]]` | 管理 MCP server 连接和 OAuth 身份验证。不带参数运行以打开交互式列表，传递 `reconnect <server>` 以重新连接一个断开连接的 server，或传递 `enable`/`disable` 与 server 名称或 `all` 以更改连接状态而不打开对话框。{/* min-version: 2.1.205 */}也可在非交互模式（`-p`）中使用，其中不带参数运行它会打印 server 状态的文本摘要而不是打开列表；需要 Claude Code v2.1.205 或更高版本 |

105| `/model [model]` | 切换 AI 模型并将其保存为新会话的默认值。对于支持的模型，使用左/右箭头[调整工作量级别](/zh-CN/model-config#adjust-effort-level)。不带参数时，打开选择器；在一行上按 `s` 以仅为当前会话切换。当对话有先前输出时，选择器要求确认，因为下一个响应会重新读取完整历史记录而不使用缓存的上下文。确认后，更改立即生效，无需等待当前响应完成。{/* min-version: 2.1.205 */}也可在非交互模式（`-p`）中使用模型参数而不是选择器，其中它仅适用于当前会话且不保存为您的默认值；需要 Claude Code v2.1.205 或更高版本 |105| `/model [model]` | 切换 AI 模型并将其保存为新会话的默认值。对于支持的模型，使用左/右箭头[调整工作量级别](/docs/zh-CN/model-config#adjust-effort-level)。不带参数时，打开选择器；在一行上按 `s` 以仅为当前会话切换。当对话有先前输出时，选择器要求确认，因为下一个响应会重新读取完整历史记录而不使用缓存的上下文。确认后，更改立即生效，无需等待当前响应完成。{/* min-version: 2.1.205 */}也可在非交互模式（`-p`）中使用模型参数而不是选择器，其中它仅适用于当前会话且不保存为您的默认值；需要 Claude Code v2.1.205 或更高版本 |

107| `/permissions` | 管理工具权限的允许、询问和拒绝规则。打开交互式对话框，您可以按范围查看规则、添加或删除规则、管理工作目录，以及查看[最近的自动模式拒绝](/zh-CN/auto-mode-config#review-denials)。别名：`/allowed-tools` |107| `/permissions` | 管理工具权限的允许、询问和拒绝规则。打开交互式对话框，您可以按范围查看规则、添加或删除规则、管理工作目录，以及查看[最近的自动模式拒绝](/docs/zh-CN/auto-mode-config#review-denials)。别名：`/allowed-tools` |

109| `/plugin [subcommand]` | 管理 Claude Code [plugins](/zh-CN/plugins)。不带参数运行以打开 plugin 菜单，或传递子命令如 `list`、`install`、`enable` 或 `disable` 以直接执行 |109| `/plugin [subcommand]` | 管理 Claude Code [plugins](/docs/zh-CN/plugins)。不带参数运行以打开 plugin 菜单，或传递子命令如 `list`、`install`、`enable` 或 `disable` 以直接执行 |

111| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}在 v2.1.91 中移除。改为直接询问 Claude 以查看 pull request 评论。在早期版本中，从 GitHub pull request 获取并显示评论；自动检测当前分支的 PR，或传递 PR URL 或编号。需要 `gh` CLI |111| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}在 v2.1.91 中移除。改为直接询问 Claude 以查看 pull request 评论。在早期版本中，从 GitHub pull request 获取并显示评论；自动检测当前分支的 PR，或传递 PR URL 或编号。需要 `gh` CLI |

113| `/radio` | 在浏览器中打开 Claude FM lo-fi 电台。当浏览器不可用时打印流 URL。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 上不可用 |113| `/radio` | 在浏览器中打开 Claude FM lo-fi 电台。当浏览器不可用时打印流 URL。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 上不可用 |

115| `/release-notes` | 在交互式版本选择器中查看更改日志。选择特定版本以查看其发布说明，或选择显示所有版本。{/* min-version: 2.1.208 */}这些说明出现在您的记录中，而不进入 Claude 看到的对话。在 v2.1.208 之前，查看的说明进入对话，包括显示所有版本时的整个更改日志 |115| `/release-notes` | 在交互式版本选择器中查看更改日志。选择特定版本以查看其发布说明，或选择显示所有版本。{/* min-version: 2.1.208 */}这些说明出现在您的记录中，而不进入 Claude 看到的对话。在 v2.1.208 之前，查看的说明进入对话，包括显示所有版本时的整个更改日志 |

116| `/reload-plugins [--force]` | 重新加载所有活跃 [plugins](/zh-CN/plugins) 以应用待处理的更改而无需重启。报告每个已重新加载组件的计数并标记任何加载错误。当重新加载会改变加载哪些 MCP 工具并使提示缓存失效时，该命令会警告并跳过，除非您传递 `--force` |116| `/reload-plugins [--force]` | 重新加载所有活跃 [plugins](/docs/zh-CN/plugins) 以应用待处理的更改而无需重启。报告每个已重新加载组件的计数并标记任何加载错误。当重新加载会改变加载哪些 MCP 工具并使提示缓存失效时，该命令会警告并跳过，除非您传递 `--force` |

117| `/reload-skills` | {/* min-version: 2.1.152 */}重新扫描 [skill](/zh-CN/skills) 和命令目录，以便在会话期间添加或更改的 skills 在磁盘上变得可用，无需重启。报告有多少 skills 可用以及添加或删除了多少 |117| `/reload-skills` | {/* min-version: 2.1.152 */}重新扫描 [skill](/docs/zh-CN/skills) 和命令目录，以便在会话期间添加或更改的 skills 在磁盘上变得可用，无需重启。报告有多少 skills 可用以及添加或删除了多少 |

118| `/remote-control` | 使此会话可从 claude.ai 进行[远程控制](/zh-CN/remote-control)。{/* min-version: 2.1.206 */}在未登录时运行它会打印远程控制需要 claude.ai 订阅并告诉您如何登录；在 v2.1.206 之前它报告 `Unknown command: /remote-control`。别名：`/rc` |118| `/remote-control` | 使此会话可从 claude.ai 进行[远程控制](/docs/zh-CN/remote-control)。{/* min-version: 2.1.206 */}在未登录时运行它会打印远程控制需要 claude.ai 订阅并告诉您如何登录；在 v2.1.206 之前它报告 `Unknown command: /remote-control`。别名：`/rc` |

120| `/rename [name]` | 重命名当前会话并在提示栏上显示名称。不使用名称时，从对话历史记录自动生成一个。{/* min-version: 2.1.205 */}也可在非交互模式（`-p`）中使用；需要 Claude Code v2.1.205 或更高版本 |120| `/rename [name]` | 重命名当前会话并在提示栏上显示名称。不使用名称时，从对话历史记录自动生成一个。{/* min-version: 2.1.205 */}也可在非交互模式（`-p`）中使用；需要 Claude Code v2.1.205 或更高版本 |

121| `/resume [session]` | 按 ID 或名称恢复对话，或打开会话选择器。从 v2.1.144 起，[后台会话](/zh-CN/agent-view)在选择器中显示，标记为 `bg`；仍在运行的会话无法在此处恢复，因此从 `claude agents` 附加到它或先在那里停止它。别名：`/continue` |121| `/resume [session]` | 按 ID 或名称恢复对话，或打开会话选择器。从 v2.1.144 起，[后台会话](/docs/zh-CN/agent-view)在选择器中显示，标记为 `bg`；仍在运行的会话无法在此处恢复，因此从 `claude agents` 附加到它或先在那里停止它。别名：`/continue` |

122| `/review [PR]` | {/* min-version: 2.1.202 */}按编号运行 GitHub pull request 的快速单遍、只读审阅。不带参数时，列出要选择的开放 PR；PR 编号后的文本成为额外的审阅说明。从 v2.1.186 到 v2.1.201，`/review` 改为运行与 `/code-review medium` 相同的多 agent 引擎。对于选定工作量级别的多 agent 审阅，使用 [`/code-review <level> <pr#>`](/zh-CN/code-review#review-a-diff-locally)；对于基于云的审阅，请参阅 [`/code-review ultra`](/zh-CN/ultrareview) |122| `/review [PR]` | {/* min-version: 2.1.202 */}按编号运行 GitHub pull request 的快速单遍、只读审阅。不带参数时，列出要选择的开放 PR；PR 编号后的文本成为额外的审阅说明。从 v2.1.186 到 v2.1.201，`/review` 改为运行与 `/code-review medium` 相同的多 agent 引擎。对于选定工作量级别的多 agent 审阅，使用 [`/code-review <level> <pr#>`](/docs/zh-CN/code-review#review-a-diff-locally)；对于基于云的审阅，请参阅 [`/code-review ultra`](/docs/zh-CN/ultrareview) |

124| `/run` | **[Skill](/zh-CN/skills#bundled-skills).** 启动并驱动您的项目应用以在运行的应用中看到更改工作，而不仅仅是在测试中。请参阅[运行和验证您的应用](/zh-CN/skills#run-and-verify-your-app)。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更高版本 |124| `/run` | **[Skill](/docs/zh-CN/skills#bundled-skills).** 启动并驱动您的项目应用以在运行的应用中看到更改工作，而不仅仅是在测试中。请参阅[运行和验证您的应用](/docs/zh-CN/skills#run-and-verify-your-app)。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更高版本 |

125| `/run-skill-generator` | **[Skill](/zh-CN/skills#bundled-skills).** 通过从干净环境编写每个项目的 [skill](/zh-CN/skills#run-and-verify-your-app)，教 `/run` 和 `/verify` 如何构建、启动和驱动您的项目应用。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更高版本 |125| `/run-skill-generator` | **[Skill](/docs/zh-CN/skills#bundled-skills).** 通过从干净环境编写每个项目的 [skill](/docs/zh-CN/skills#run-and-verify-your-app)，教 `/run` 和 `/verify` 如何构建、启动和驱动您的项目应用。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更高版本 |

127| `/schedule [description]` | 创建、更新、列出或运行 [routines](/zh-CN/routines)，这些 routines 在 Anthropic 管理的云基础设施上执行。Claude 会以对话方式引导您完成设置。别名：`/routines` |127| `/schedule [description]` | 创建、更新、列出或运行 [routines](/docs/zh-CN/routines)，这些 routines 在 Anthropic 管理的云基础设施上执行。Claude 会以对话方式引导您完成设置。别名：`/routines` |

128| `/scroll-speed` | 交互式调整鼠标滚轮[滚动速度](/zh-CN/fullscreen#mouse-wheel-scrolling)，使用标尺，您可以在对话框打开时滚动以预览更改。仅在[全屏渲染](/zh-CN/fullscreen)中可用，在 JetBrains IDE 终端中不可用 |128| `/scroll-speed` | 交互式调整鼠标滚轮[滚动速度](/docs/zh-CN/fullscreen#mouse-wheel-scrolling)，使用标尺，您可以在对话框打开时滚动以预览更改。仅在[全屏渲染](/docs/zh-CN/fullscreen)中可用，在 JetBrains IDE 终端中不可用 |

130| `/setup-bedrock` | 通过交互式向导配置 [Amazon Bedrock](/zh-CN/amazon-bedrock) 身份验证、区域和模型固定。仅在设置 `CLAUDE_CODE_USE_BEDROCK=1` 时可见。首次 Amazon Bedrock 用户也可以从登录屏幕访问此向导 |130| `/setup-bedrock` | 通过交互式向导配置 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 身份验证、区域和模型固定。仅在设置 `CLAUDE_CODE_USE_BEDROCK=1` 时可见。首次 Amazon Bedrock 用户也可以从登录屏幕访问此向导 |

131| `/setup-vertex` | 通过交互式向导配置 [Google Cloud 的 Agent Platform](/zh-CN/google-vertex-ai) 身份验证、项目、区域和模型固定。仅在设置 `CLAUDE_CODE_USE_VERTEX=1` 时可见。首次 Google Cloud 的 Agent Platform 用户也可以从登录屏幕访问此向导 |131| `/setup-vertex` | 通过交互式向导配置 [Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 身份验证、项目、区域和模型固定。仅在设置 `CLAUDE_CODE_USE_VERTEX=1` 时可见。首次 Google Cloud 的 Agent Platform 用户也可以从登录屏幕访问此向导 |

132| `/simplify [target]` | {/* min-version: 2.1.154 */}**[Skill](/zh-CN/skills#bundled-skills).** 审阅更改的代码以查找清理机会并应用修复。四个审阅 [agents](/zh-CN/sub-agents) 并行运行，涵盖现有帮助程序的重用、简化、效率和更改是否处于正确的抽象级别。从 v2.1.154 开始，审阅不寻找正确性错误。使用 `/code-review` 查找错误。在早期版本中，`/simplify` 等同于 `/code-review --fix`。传递路径或 PR 参考以审阅特定目标 |132| `/simplify [target]` | {/* min-version: 2.1.154 */}**[Skill](/docs/zh-CN/skills#bundled-skills).** 审阅更改的代码以查找清理机会并应用修复。四个审阅 [agents](/docs/zh-CN/sub-agents) 并行运行，涵盖现有帮助程序的重用、简化、效率和更改是否处于正确的抽象级别。从 v2.1.154 开始，审阅不寻找正确性错误。使用 `/code-review` 查找错误。在早期版本中，`/simplify` 等同于 `/code-review --fix`。传递路径或 PR 参考以审阅特定目标 |

133| `/skills` | 列出可用的 [skills](/zh-CN/skills)。{/* min-version: 2.1.121 */}从 v2.1.121 开始，输入以按名称过滤列表。按 `t` 按令牌计数排序。按 `Space` 以[从 Claude 或 `/` 菜单中隐藏 skill](/zh-CN/skills#override-skill-visibility-from-settings)，然后按 `Enter` 保存 |133| `/skills` | 列出可用的 [skills](/docs/zh-CN/skills)。{/* min-version: 2.1.121 */}从 v2.1.121 开始，输入以按名称过滤列表。按 `t` 按令牌计数排序。按 `Space` 以[从 Claude 或 `/` 菜单中隐藏 skill](/docs/zh-CN/skills#override-skill-visibility-from-settings)，然后按 `Enter` 保存 |

140| `/team-onboarding` | 从您的 Claude Code 使用历史记录生成团队入职指南。Claude 分析您过去 30 天的会话、命令和 MCP server 使用情况，并生成一个 markdown 指南，团队成员可以粘贴为第一条消息以快速设置。对于 Pro、Max、Team 和 Enterprise 计划上的 claude.ai 订阅者，还返回一个共享链接，团队成员可以直接在 Claude Code 中打开 |140| `/team-onboarding` | 从您的 Claude Code 使用历史记录生成团队入职指南。Claude 分析您过去 30 天的会话、命令和 MCP server 使用情况，并生成一个 markdown 指南，团队成员可以粘贴为第一条消息以快速设置。对于 Pro、Max、Team 和 Enterprise 计划上的 claude.ai 订阅者，还返回一个共享链接，团队成员可以直接在 Claude Code 中打开 |

141| `/teleport` | 将[网络版 Claude Code](/zh-CN/claude-code-on-the-web#from-web-to-terminal) 会话拉入此终端：打开选择器，然后获取分支和对话。也可用作 `/tp`。需要 claude.ai 订阅 |141| `/teleport` | 将[网络版 Claude Code](/docs/zh-CN/claude-code-on-the-web#from-web-to-terminal) 会话拉入此终端：打开选择器，然后获取分支和对话。也可用作 `/tp`。需要 claude.ai 订阅 |

143| `/theme` | 更改颜色主题。包括跟随您终端深色或浅色背景的 `auto` 选项、浅色和深色变体、色盲友好（道尔顿化）主题、使用您终端颜色调色板的 ANSI 主题，以及来自 `~/.claude/themes/` 或 plugins 的任何[自定义主题](/zh-CN/terminal-config#create-a-custom-theme)。选择\*\*新建自定义主题…\*\*以创建一个 |143| `/theme` | 更改颜色主题。包括跟随您终端深色或浅色背景的 `auto` 选项、浅色和深色变体、色盲友好（道尔顿化）主题、使用您终端颜色调色板的 ANSI 主题，以及来自 `~/.claude/themes/` 或 plugins 的任何[自定义主题](/docs/zh-CN/terminal-config#create-a-custom-theme)。选择\*\*新建自定义主题…\*\*以创建一个 |

146| `/ultrareview [PR]` | 在云沙箱中运行深度、多 agent 代码审阅，使用 [ultrareview](/zh-CN/ultrareview)。首选调用现在是 `/code-review ultra`，`/ultrareview` 仍然作为别名保留。Pro 和 Max 包括 3 次免费运行，然后需要[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |146| `/ultrareview [PR]` | 在云沙箱中运行深度、多 agent 代码审阅，使用 [ultrareview](/docs/zh-CN/ultrareview)。首选调用现在是 `/code-review ultra`，`/ultrareview` 仍然作为别名保留。Pro 和 Max 包括 3 次免费运行，然后需要[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

148| `/usage` | 显示会话成本、计划使用限制和活动统计。在 Pro、Max、Team 或 Enterprise 计划上，包括按 skill、subagent、plugin 和 MCP server 的使用情况分解。有关详细信息，请参阅[成本跟踪指南](/zh-CN/costs#using-the-%2Fusage-command)。`/cost` 和 `/stats` 是别名 |148| `/usage` | 显示会话成本、计划使用限制和活动统计。在 Pro、Max、Team 或 Enterprise 计划上，包括按 skill、subagent、plugin 和 MCP server 的使用情况分解。有关详细信息，请参阅[成本跟踪指南](/docs/zh-CN/costs#using-the-%2Fusage-command)。`/cost` 和 `/stats` 是别名 |

149| `/usage-credits` | 配置使用额度以在达到限制时继续工作。在 Pro 和 Max 计划上，打开[CLI 内对话框](/zh-CN/costs#set-a-spend-limit-on-pro-and-max)以购买使用额度、设置每月支出限制和配置自动重新加载；在 Claude Code v2.1.207 之前的版本和其他计划上，打开使用额度计费页面在您的浏览器中，除了 Team 和 Enterprise 成员没有计费访问权限的情况下，改为从 CLI 向其管理员发送使用额度请求。{/* min-version: 2.1.205 */}当没有浏览器可以打开计费页面时，例如通过 SSH，该命令改为打印要访问的 URL；这需要 Claude Code v2.1.205 或更高版本，早期版本在这种情况下没有显示任何内容。之前为 `/extra-usage` |149| `/usage-credits` | 配置使用额度以在达到限制时继续工作。在 Pro 和 Max 计划上，打开[CLI 内对话框](/docs/zh-CN/costs#set-a-spend-limit-on-pro-and-max)以购买使用额度、设置每月支出限制和配置自动重新加载；在 Claude Code v2.1.207 之前的版本和其他计划上，打开使用额度计费页面在您的浏览器中，除了 Team 和 Enterprise 成员没有计费访问权限的情况下，改为从 CLI 向其管理员发送使用额度请求。{/* min-version: 2.1.205 */}当没有浏览器可以打开计费页面时，例如通过 SSH，该命令改为打印要访问的 URL；这需要 Claude Code v2.1.205 或更高版本，早期版本在这种情况下没有显示任何内容。之前为 `/extra-usage` |

150| `/verify` | **[Skill](/zh-CN/skills#bundled-skills).** 通过构建您的项目应用、运行它并观察结果来确认代码更改是否按预期工作，而不是依赖测试或类型检查。请参阅[运行和验证您的应用](/zh-CN/skills#run-and-verify-your-app)。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更高版本 |150| `/verify` | **[Skill](/docs/zh-CN/skills#bundled-skills).** 通过构建您的项目应用、运行它并观察结果来确认代码更改是否按预期工作，而不是依赖测试或类型检查。请参阅[运行和验证您的应用](/docs/zh-CN/skills#run-and-verify-your-app)。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更高版本 |

151| `/vim` | {/* max-version: 2.1.91 */}在 v2.1.92 中移除。要在 Vim 和普通编辑模式之间切换，请使用 `/config` → 编辑器模式 |151| `/vim` | {/* max-version: 2.1.91 */}在 v2.1.92 中移除。要在 Vim 和普通编辑模式之间切换，请使用 `/config` → 编辑器模式 |

152| `/voice [hold\|tap\|off]` | 切换[语音听写](/zh-CN/voice-dictation)，或在特定模式下启用它。需要 Claude.ai 账户 |152| `/voice [hold\|tap\|off]` | 切换[语音听写](/docs/zh-CN/voice-dictation)，或在特定模式下启用它。需要 Claude.ai 账户 |

153| `/web-setup` | 使用您的本地 `gh` CLI 凭证将您的 GitHub 账户连接到[网络版 Claude Code](/zh-CN/web-quickstart#connect-from-your-terminal)。如果 GitHub 未连接，`/schedule` 会自动提示此操作 |153| `/web-setup` | 使用您的本地 `gh` CLI 凭证将您的 GitHub 账户连接到[网络版 Claude Code](/docs/zh-CN/web-quickstart#connect-from-your-terminal)。如果 GitHub 未连接，`/schedule` 会自动提示此操作 |

155 155

156<h2 id="mcp-prompts">156<h2 id="mcp-prompts">

157 MCP prompts157 MCP prompts

158</h2>158</h2>

159 159

160MCP servers 可以公开显示为命令的 prompts。这些使用格式 `/mcp__<server>__<prompt>`，并从连接的服务器动态发现。有关详细信息，请参阅 [MCP prompts](/zh-CN/mcp#use-mcp-prompts-as-commands)。160MCP servers 可以公开显示为命令的 prompts。这些使用格式 `/mcp__<server>__<prompt>`，并从连接的服务器动态发现。有关详细信息，请参阅 [MCP prompts](/docs/zh-CN/mcp#use-mcp-prompts-as-commands)。

161 161

162<h2 id="see-also">162<h2 id="see-also">

163 另请参阅163 另请参阅

164</h2>164</h2>

165 165

166* [Skills](/zh-CN/skills)：创建您自己的命令166* [Skills](/docs/zh-CN/skills)：创建您自己的命令

167* [Interactive mode](/zh-CN/interactive-mode)：快捷键、Vim 模式和命令历史记录167* [Interactive mode](/docs/zh-CN/interactive-mode)：快捷键、Vim 模式和命令历史记录

168* [CLI reference](/zh-CN/cli-reference)：启动时标志168* [CLI reference](/docs/zh-CN/cli-reference)：启动时标志

hooks.md +63 −63

Details

7> Claude Code hook 事件、配置架构、JSON 输入/输出格式、退出代码、异步 hooks、HTTP hooks、提示 hooks 和 MCP 工具 hooks 的参考。7> Claude Code hook 事件、配置架构、JSON 输入/输出格式、退出代码、异步 hooks、HTTP hooks、提示 hooks 和 MCP 工具 hooks 的参考。

8 8

9<Tip>9<Tip>

~~10 有关包含示例的快速入门指南，请参阅[使用 hooks 自动化工作流](/zh-CN/hooks-guide)。~~10 有关包含示例的快速入门指南，请参阅[使用 hooks 自动化工作流](/docs/zh-CN/hooks-guide)。

11</Tip>11</Tip>

12 12

13Hooks 是用户定义的 shell 命令、HTTP 端点或 LLM 提示，在 Claude Code 生命周期中的特定点自动执行。使用此参考查找事件架构、配置选项、JSON 输入/输出格式以及异步 hooks、HTTP hooks 和 MCP 工具 hooks 等高级功能。如果您是第一次设置 hooks，请改为从[指南](/zh-CN/hooks-guide)开始。13Hooks 是用户定义的 shell 命令、HTTP 端点或 LLM 提示，在 Claude Code 生命周期中的特定点自动执行。使用此参考查找事件架构、配置选项、JSON 输入/输出格式以及异步 hooks、HTTP hooks 和 MCP 工具 hooks 等高级功能。如果您是第一次设置 hooks，请改为从[指南](/docs/zh-CN/hooks-guide)开始。

14 14

15<h2 id="hook-lifecycle">15<h2 id="hook-lifecycle">

16 Hook 生命周期16 Hook 生命周期

52| `TaskCompleted` | When a task is being marked as completed |52| `TaskCompleted` | When a task is being marked as completed |

53| `Stop` | When Claude finishes responding |53| `Stop` | When Claude finishes responding |

54| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |54| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |

56| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |56| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

57| `ConfigChange` | When a configuration file changes during a session |57| `ConfigChange` | When a configuration file changes during a session |

58| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |58| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

59| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |59| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |

~~60| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |~~60| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |

62| `PreCompact` | Before context compaction |62| `PreCompact` | Before context compaction |

63| `PostCompact` | After context compaction completes |63| `PostCompact` | After context compaction completes |

64| `Elicitation` | When an MCP server requests user input during a tool call |64| `Elicitation` | When an MCP server requests user input during a tool call |

147 }147 }

148 ```148 ```

149 149

150 如果命令是更安全的 `rm` 变体，如 `rm file.txt`，脚本会改为执行 `exit 0`。退出代码 0 且无输出意味着 hook 没有决定要报告，因此工具调用继续通过正常的[权限流程](/zh-CN/permissions)。hook 可以拒绝调用，但保持沉默不会批准它。150 如果命令是更安全的 `rm` 变体，如 `rm file.txt`，脚本会改为执行 `exit 0`。退出代码 0 且无输出意味着 hook 没有决定要报告，因此工具调用继续通过正常的[权限流程](/docs/zh-CN/permissions)。hook 可以拒绝调用，但保持沉默不会批准它。

151 </Step>151 </Step>

152 152

153 <Step title="Claude Code 对结果采取行动">153 <Step title="Claude Code 对结果采取行动">

190 190

191有关设置文件解析的详细信息，请参阅[设置](/zh-CN/settings)。企业管理员可以使用 `allowManagedHooksOnly` 来阻止用户、项目和插件 hooks。在托管设置 `enabledPlugins` 中强制启用的插件中的 Hooks 是豁免的，因此管理员可以通过组织市场分发经过审查的 hooks。请参阅[Hook 配置](/zh-CN/settings#hook-configuration)。191有关设置文件解析的详细信息，请参阅[设置](/docs/zh-CN/settings)。企业管理员可以使用 `allowManagedHooksOnly` 来阻止用户、项目和插件 hooks。在托管设置 `enabledPlugins` 中强制启用的插件中的 Hooks 是豁免的，因此管理员可以通过组织市场分发经过审查的 hooks。请参阅[Hook 配置](/docs/zh-CN/settings#hook-configuration)。

192 192

193<h3 id="matcher-patterns">193<h3 id="matcher-patterns">

194 匹配器模式194 匹配器模式

258 258

259`UserPromptSubmit`、`PostToolBatch`、`Stop`、`TeammateIdle`、`TaskCreated`、`TaskCompleted`、`WorktreeCreate`、`WorktreeRemove`、`MessageDisplay` 和 `CwdChanged` 不支持匹配器，总是在每次出现时触发。如果您向这些事件添加 `matcher` 字段，它会被静默忽略。259`UserPromptSubmit`、`PostToolBatch`、`Stop`、`TeammateIdle`、`TaskCreated`、`TaskCompleted`、`WorktreeCreate`、`WorktreeRemove`、`MessageDisplay` 和 `CwdChanged` 不支持匹配器，总是在每次出现时触发。如果您向这些事件添加 `matcher` 字段，它会被静默忽略。

260 260

261对于工具事件，您可以通过在单个 hook 处理程序上设置[`if` 字段](#common-fields)来更狭隘地过滤。`if` 使用[权限规则语法](/zh-CN/permissions)来匹配工具名称和参数，因此 `"Bash(git *)"` 仅在任何 Bash 输入的子命令与 `git *` 匹配时运行，`"Edit(*.ts)"` 仅对 TypeScript 文件运行。261对于工具事件，您可以通过在单个 hook 处理程序上设置[`if` 字段](#common-fields)来更狭隘地过滤。`if` 使用[权限规则语法](/docs/zh-CN/permissions)来匹配工具名称和参数，因此 `"Bash(git *)"` 仅在任何 Bash 输入的子命令与 `git *` 匹配时运行，`"Edit(*.ts)"` 仅对 TypeScript 文件运行。

262 262

263<h4 id="match-mcp-tools">263<h4 id="match-mcp-tools">

264 匹配 MCP 工具264 匹配 MCP 工具

265</h4>265</h4>

266 266

267[MCP](/zh-CN/mcp) 服务器工具在工具事件中显示为常规工具（`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`、`PermissionDenied`），因此您可以像匹配任何其他工具名称一样匹配它们。267[MCP](/docs/zh-CN/mcp) 服务器工具在工具事件中显示为常规工具（`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`、`PermissionDenied`），因此您可以像匹配任何其他工具名称一样匹配它们。

268 268

269MCP 工具遵循命名模式 `mcp__<server>__<tool>`，例如：269MCP 工具遵循命名模式 `mcp__<server>__<tool>`，例如：

270 270

280 280

281精确匹配集中的连字符需要 Claude Code v2.1.195 或更高版本。在早期版本中，像 `mcp__brave-search` 这样的裸连字符前缀被评估为未锚定的正则表达式，并匹配来自该服务器的每个工具。`mcp__brave-search__.*` 形式在每个版本上都有效。281精确匹配集中的连字符需要 Claude Code v2.1.195 或更高版本。在早期版本中，像 `mcp__brave-search` 这样的裸连字符前缀被评估为未锚定的正则表达式，并匹配来自该服务器的每个工具。`mcp__brave-search__.*` 形式在每个版本上都有效。

282 282

283来自[插件捆绑的 MCP 服务器](/zh-CN/mcp#plugin-provided-mcp-servers)的工具使用包含插件名称的作用域服务器段：`mcp__plugin_<plugin-name>_<server-name>__<tool>`。针对裸服务器密钥编写的匹配器永远不会对这些工具触发。对于在密钥 `db` 下捆绑服务器的名为 `my-plugin` 的插件，`query` 工具显示为 `mcp__plugin_my-plugin_db__query`，因此来自该服务器的每个工具的匹配器是 `mcp__plugin_my-plugin_db__.*`。在处理程序的[`if` 字段](#common-fields)中使用相同的作用域工具名称。有关如何构建作用域名称的信息，请参阅[插件提供的 MCP 服务器](/zh-CN/mcp#plugin-provided-mcp-servers)。283来自[插件捆绑的 MCP 服务器](/docs/zh-CN/mcp#plugin-provided-mcp-servers)的工具使用包含插件名称的作用域服务器段：`mcp__plugin_<plugin-name>_<server-name>__<tool>`。针对裸服务器密钥编写的匹配器永远不会对这些工具触发。对于在密钥 `db` 下捆绑服务器的名为 `my-plugin` 的插件，`query` 工具显示为 `mcp__plugin_my-plugin_db__query`，因此来自该服务器的每个工具的匹配器是 `mcp__plugin_my-plugin_db__.*`。在处理程序的[`if` 字段](#common-fields)中使用相同的作用域工具名称。有关如何构建作用域名称的信息，请参阅[插件提供的 MCP 服务器](/docs/zh-CN/mcp#plugin-provided-mcp-servers)。

284 284

285此示例记录所有内存服务器操作并验证来自任何 MCP 服务器的写入操作：285此示例记录所有内存服务器操作并验证来自任何 MCP 服务器的写入操作：

286 286

319 319

320* **[命令 hooks](#command-hook-fields)**（`type: "command"`）：运行 shell 命令。您的脚本在 stdin 上接收事件的[JSON 输入](#hook-input-and-output)，并通过退出代码和 stdout 传回结果。320* **[命令 hooks](#command-hook-fields)**（`type: "command"`）：运行 shell 命令。您的脚本在 stdin 上接收事件的[JSON 输入](#hook-input-and-output)，并通过退出代码和 stdout 传回结果。

321* **[HTTP hooks](#http-hook-fields)**（`type: "http"`）：将事件的 JSON 输入作为 HTTP POST 请求发送到 URL。端点通过使用与命令 hooks 相同的[JSON 输出格式](#json-output)的响应体传回结果。321* **[HTTP hooks](#http-hook-fields)**（`type: "http"`）：将事件的 JSON 输入作为 HTTP POST 请求发送到 URL。端点通过使用与命令 hooks 相同的[JSON 输出格式](#json-output)的响应体传回结果。

322* **[MCP 工具 hooks](#mcp-tool-hook-fields)**（`type: "mcp_tool"`）：在已连接的[MCP 服务器](/zh-CN/mcp)上调用工具。工具的文本输出被视为命令 hook stdout。322* **[MCP 工具 hooks](#mcp-tool-hook-fields)**（`type: "mcp_tool"`）：在已连接的[MCP 服务器](/docs/zh-CN/mcp)上调用工具。工具的文本输出被视为命令 hook stdout。

323* **[提示 hooks](#prompt-and-agent-hook-fields)**（`type: "prompt"`）：向 Claude 模型发送提示以进行单轮评估。模型返回 yes/no 决定作为 JSON。请参阅[基于提示的 hooks](#prompt-based-hooks)。323* **[提示 hooks](#prompt-and-agent-hook-fields)**（`type: "prompt"`）：向 Claude 模型发送提示以进行单轮评估。模型返回 yes/no 决定作为 JSON。请参阅[基于提示的 hooks](#prompt-based-hooks)。

324* **[代理 hooks](#prompt-and-agent-hook-fields)**（`type: "agent"`）：生成一个可以使用 Read、Grep 和 Glob 等工具来验证条件的 subagent，然后返回决定。代理 hooks 是实验性的，可能会改变。请参阅[基于代理的 hooks](#agent-based-hooks)。324* **[代理 hooks](#prompt-and-agent-hook-fields)**（`type: "agent"`）：生成一个可以使用 Read、Grep 和 Glob 等工具来验证条件的 subagent，然后返回决定。代理 hooks 是实验性的，可能会改变。请参阅[基于代理的 hooks](#agent-based-hooks)。

325 325

326所有匹配的 hooks 并行运行，相同的处理程序会自动去重。命令 hooks 按命令字符串和 `args` 去重，HTTP hooks 按 URL 去重。326所有匹配的 hooks 并行运行，相同的处理程序会自动去重。命令 hooks 按命令字符串和 `args` 去重，HTTP hooks 按 URL 去重。

327 327

328处理程序在当前目录中运行，使用 Claude Code 的环境。在远程 web 环境中，`$CLAUDE_CODE_REMOTE` 环境变量设置为 `"true"`，在本地 CLI 中未设置。{/* min-version: 2.1.199 */}从 v2.1.199 开始，[`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/zh-CN/env-vars)设置为[远程控制](/zh-CN/remote-control)会话 ID，而本地会话具有活跃的远程控制连接。328处理程序在当前目录中运行，使用 Claude Code 的环境。在远程 web 环境中，`$CLAUDE_CODE_REMOTE` 环境变量设置为 `"true"`，在本地 CLI 中未设置。{/* min-version: 2.1.199 */}从 v2.1.199 开始，[`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/docs/zh-CN/env-vars)设置为[远程控制](/docs/zh-CN/remote-control)会话 ID，而本地会话具有活跃的远程控制连接。

329 329

330<h4 id="common-fields">330<h4 id="common-fields">

331 通用字段331 通用字段

336| 字段 | 必需 | 描述 |336| 字段 | 必需 | 描述 |

337| :-------------- | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |337| :-------------- | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

338| `type` | 是 | `"command"`、`"http"`、`"mcp_tool"`、`"prompt"` 或 `"agent"` |338| `type` | 是 | `"command"`、`"http"`、`"mcp_tool"`、`"prompt"` 或 `"agent"` |

339| `if` | 否 | 权限规则语法以过滤此 hook 何时运行，例如 `"Bash(git *)"` 或 `"Edit(*.ts)"`。hook 命令仅在工具调用与模式匹配时运行。请参阅下面的[Bash 匹配表](#bash-if-matching)了解 Bash 模式如何针对子命令、`$()`和反引号进行评估。仅在工具事件上评估：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 和 `PermissionDenied`。在其他事件上，设置了 `if` 的 hook 永远不会运行。使用与[权限规则](/zh-CN/permissions)相同的语法 |339| `if` | 否 | 权限规则语法以过滤此 hook 何时运行，例如 `"Bash(git *)"` 或 `"Edit(*.ts)"`。hook 命令仅在工具调用与模式匹配时运行。请参阅下面的[Bash 匹配表](#bash-if-matching)了解 Bash 模式如何针对子命令、`$()`和反引号进行评估。仅在工具事件上评估：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 和 `PermissionDenied`。在其他事件上，设置了 `if` 的 hook 永远不会运行。使用与[权限规则](/docs/zh-CN/permissions)相同的语法 |

340| `timeout` | 否 | 取消前的秒数。默认值：`command`、`http` 和 `mcp_tool` 为 600；`prompt` 为 30；`agent` 为 60。[`UserPromptSubmit`](#userpromptsubmit) 将 `command`、`http` 和 `mcp_tool` 的默认值降低到 30，[`MessageDisplay`](#messagedisplay) 将其降低到 10 |340| `timeout` | 否 | 取消前的秒数。默认值：`command`、`http` 和 `mcp_tool` 为 600；`prompt` 为 30；`agent` 为 60。[`UserPromptSubmit`](#userpromptsubmit) 将 `command`、`http` 和 `mcp_tool` 的默认值降低到 30，[`MessageDisplay`](#messagedisplay) 将其降低到 10 |

341| `statusMessage` | 否 | hook 运行时显示的自定义加载程序消息 |341| `statusMessage` | 否 | hook 运行时显示的自定义加载程序消息 |

342| `once` | 否 | 如果为 `true`，每个会话仅运行一次，然后被移除。仅在[skill frontmatter](#hooks-in-skills-and-agents)中声明的 hooks 中受尊重；在设置文件和代理 frontmatter 中被忽略 |342| `once` | 否 | 如果为 `true`，每个会话仅运行一次，然后被移除。仅在[skill frontmatter](#hooks-in-skills-and-agents)中声明的 hooks 中受尊重；在设置文件和代理 frontmatter 中被忽略 |

355 355

356过滤器也会失败开放，当 Bash 命令无法解析时无论如何运行您的 hook。因为 `if` 过滤器是尽力而为的，使用[权限系统](/zh-CN/permissions)而不是 hook 来强制执行硬允许或拒绝。356过滤器也会失败开放，当 Bash 命令无法解析时无论如何运行您的 hook。因为 `if` 过滤器是尽力而为的，使用[权限系统](/docs/zh-CN/permissions)而不是 hook 来强制执行硬允许或拒绝。

357 357

358<h4 id="command-hook-fields">358<h4 id="command-hook-fields">

359 命令 hook 字段359 命令 hook 字段

406 406

407两种形式都支持相同的[路径占位符](#reference-scripts-by-path)，并且都将它们作为环境变量 `CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT` 和 `CLAUDE_PLUGIN_DATA` 导出到生成的进程上，因此脚本可以读取 `process.env.CLAUDE_PLUGIN_ROOT`，无论它是如何启动的。407两种形式都支持相同的[路径占位符](#reference-scripts-by-path)，并且都将它们作为环境变量 `CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT` 和 `CLAUDE_PLUGIN_DATA` 导出到生成的进程上，因此脚本可以读取 `process.env.CLAUDE_PLUGIN_ROOT`，无论它是如何启动的。

408 408

409插件 hooks 另外替换 [`${user_config.*}`](/zh-CN/plugins-reference#user-configuration) 值，仅在 exec 形式中：该值被替换为 `command` 和每个 `args` 元素中的纯字符串，因此没有 shell 重新解析它。409插件 hooks 另外替换 [`${user_config.*}`](/docs/zh-CN/plugins-reference#user-configuration) 值，仅在 exec 形式中：该值被替换为 `command` 和每个 `args` 元素中的纯字符串，因此没有 shell 重新解析它。

410 410

411一个 shell 形式的插件 hook，其 `command` 引用 `${user_config.*}` 会失败并出现[错误](/zh-CN/errors#plugin-command-references-user-config)，而不是运行。要从 shell 形式的 hook 使用选项值，请读取 `$CLAUDE_PLUGIN_OPTION_<KEY>` 环境变量，例如 `webhook_url` 选项的 `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL`，或设置 `args` 以将 hook 切换到 exec 形式。在 v2.1.207 之前，shell 形式的插件 hook 命令也替换了 `${user_config.*}`。411一个 shell 形式的插件 hook，其 `command` 引用 `${user_config.*}` 会失败并出现[错误](/docs/zh-CN/errors#plugin-command-references-user-config)，而不是运行。要从 shell 形式的 hook 使用选项值，请读取 `$CLAUDE_PLUGIN_OPTION_<KEY>` 环境变量，例如 `webhook_url` 选项的 `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL`，或设置 `args` 以将 hook 切换到 exec 形式。在 v2.1.207 之前，shell 形式的插件 hook 命令也替换了 `${user_config.*}`。

412 412

413<Note>413<Note>

414 在 exec 形式中，`command` 仅是可执行文件名或路径。如果 `command` 是没有路径分隔符的裸名称，并且与 `args` 一起包含空格，Claude Code 会记录警告，因为生成会失败：没有名为 `node script.js` 的可执行文件。将额外的令牌移到 `args` 中。包含空格的绝对路径，如 `C:\Program Files\nodejs\node.exe`，是单个有效的可执行文件，不会触发警告。414 在 exec 形式中，`command` 仅是可执行文件名或路径。如果 `command` 是没有路径分隔符的裸名称，并且与 `args` 一起包含空格，Claude Code 会记录警告，因为生成会失败：没有名为 `node script.js` 的可执行文件。将额外的令牌移到 `args` 中。包含空格的绝对路径，如 `C:\Program Files\nodejs\node.exe`，是单个有效的可执行文件，不会触发警告。

463 463

464| 字段 | 必需 | 描述 |464| 字段 | 必需 | 描述 |

465| :------- | :- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |465| :------- | :- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

466| `server` | 是 | 已配置的 MCP 服务器的名称。对于[插件捆绑的服务器](/zh-CN/mcp#plugin-provided-mcp-servers)，这是作用域名称 `plugin:<plugin-name>:<server-name>`，例如 `plugin:my-plugin:db`，而不是裸服务器密钥。服务器必须已连接；hook 永远不会触发 OAuth 或连接流 |466| `server` | 是 | 已配置的 MCP 服务器的名称。对于[插件捆绑的服务器](/docs/zh-CN/mcp#plugin-provided-mcp-servers)，这是作用域名称 `plugin:<plugin-name>:<server-name>`，例如 `plugin:my-plugin:db`，而不是裸服务器密钥。服务器必须已连接；hook 永远不会触发 OAuth 或连接流 |

467| `tool` | 是 | 该服务器上要调用的工具的名称 |467| `tool` | 是 | 该服务器上要调用的工具的名称 |

468| `input` | 否 | 传递给工具的参数。字符串值支持从 hook 的[JSON 输入](#hook-input-and-output)进行 `${path}` 替换，例如 `"${tool_input.file_path}"` |468| `input` | 否 | 传递给工具的参数。字符串值支持从 hook 的[JSON 输入](#hook-input-and-output)进行 `${path}` 替换，例如 `"${tool_input.file_path}"` |

469 469

510 510

511使用这些占位符按项目或插件根目录引用 hook 脚本，无论 hook 运行时的工作目录如何：511使用这些占位符按项目或插件根目录引用 hook 脚本，无论 hook 运行时的工作目录如何：

512 512

513* `${CLAUDE_PROJECT_DIR}`：项目根目录。Claude Code 也在[stdio MCP 服务器](/zh-CN/mcp#option-3-add-a-local-stdio-server)和插件 LSP 服务器的环境中设置此变量。513* `${CLAUDE_PROJECT_DIR}`：项目根目录。Claude Code 也在[stdio MCP 服务器](/docs/zh-CN/mcp#option-3-add-a-local-stdio-server)和插件 LSP 服务器的环境中设置此变量。

514* `${CLAUDE_PLUGIN_ROOT}`：插件的安装目录，用于与[插件](/zh-CN/plugins)捆绑的脚本。在每次插件更新时更改。514* `${CLAUDE_PLUGIN_ROOT}`：插件的安装目录，用于与[插件](/docs/zh-CN/plugins)捆绑的脚本。在每次插件更新时更改。

515* `${CLAUDE_PLUGIN_DATA}`：插件的[持久数据目录](/zh-CN/plugins-reference#persistent-data-directory)，用于应该在插件更新后保留的依赖项和状态。515* `${CLAUDE_PLUGIN_DATA}`：插件的[持久数据目录](/docs/zh-CN/plugins-reference#persistent-data-directory)，用于应该在插件更新后保留的依赖项和状态。

516 516

517对于任何引用路径占位符的 hook，优先使用[exec 形式](#exec-form-and-shell-form)。Exec 形式将每个 `args` 元素作为一个参数传递，不带 shell 标记化，因此包含空格或特殊字符的路径不需要引号。在 shell 形式中，用双引号包装每个占位符。517对于任何引用路径占位符的 hook，优先使用[exec 形式](#exec-form-and-shell-form)。Exec 形式将每个 `args` 元素作为一个参数传递，不带 shell 标记化，因此包含空格或特殊字符的路径不需要引号。在 shell 形式中，用双引号包装每个占位符。

518 518

566 }566 }

567 ```567 ```

568 568

569 有关创建插件 hooks 的详细信息，请参阅[插件组件参考](/zh-CN/plugins-reference#hooks)。569 有关创建插件 hooks 的详细信息，请参阅[插件组件参考](/docs/zh-CN/plugins-reference#hooks)。

570 </Tab>570 </Tab>

571</Tabs>571</Tabs>

572 572

574 Skills 和代理中的 Hooks574 Skills 和代理中的 Hooks

575</h3>575</h3>

576 576

577除了设置文件和插件外，hooks 还可以使用 frontmatter 直接在[skills](/zh-CN/skills)和[subagents](/zh-CN/sub-agents)中定义。这些 hooks 的范围限于组件的生命周期，仅在该组件活跃时运行。577除了设置文件和插件外，hooks 还可以使用 frontmatter 直接在[skills](/docs/zh-CN/skills)和[subagents](/docs/zh-CN/sub-agents)中定义。这些 hooks 的范围限于组件的生命周期，仅在该组件活跃时运行。

578 578

579支持所有 hook 事件。对于 subagents，`Stop` hooks 会自动转换为 `SubagentStop`，因为这是 subagent 完成时触发的事件。579支持所有 hook 事件。对于 subagents，`Stop` hooks 会自动转换为 `SubagentStop`，因为这是 subagent 完成时触发的事件。

580 580

643| 字段 | 描述 |643| 字段 | 描述 |

644| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |644| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

646| `prompt_id` | UUID 标识当前正在处理的用户提示。与 OpenTelemetry 事件上的[`prompt.id` 属性](/zh-CN/monitoring-usage#event-correlation-attributes)匹配，因此您可以将 hook 输出与单个提示的遥测关联起来。在第一个用户输入之前不存在。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更高版本 |646| `prompt_id` | UUID 标识当前正在处理的用户提示。与 OpenTelemetry 事件上的[`prompt.id` 属性](/docs/zh-CN/monitoring-usage#event-correlation-attributes)匹配，因此您可以将 hook 输出与单个提示的遥测关联起来。在第一个用户输入之前不存在。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更高版本 |

647| `transcript_path` | 对话 JSON 的路径。成绩单文件异步写入，可能滞后于内存中的对话，因此当 hook 触发时，它可能还不包括当前轮次的最新消息。需要当前轮次最后助手文本的 hooks 应该在[Stop](#stop) 和 [SubagentStop](#subagentstop) 上使用 `last_assistant_message`，而不是读取成绩单 |647| `transcript_path` | 对话 JSON 的路径。成绩单文件异步写入，可能滞后于内存中的对话，因此当 hook 触发时，它可能还不包括当前轮次的最新消息。需要当前轮次最后助手文本的 hooks 应该在[Stop](#stop) 和 [SubagentStop](#subagentstop) 上使用 `last_assistant_message`，而不是读取成绩单 |

648| `cwd` | 调用 hook 时的当前工作目录 |648| `cwd` | 调用 hook 时的当前工作目录 |

649| `permission_mode` | 当前[权限模式](/zh-CN/permissions#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。标记为**手动**的模式作为 `"default"` 到达，永远不会作为 `"manual"` 到达，因此匹配 `"default"` 的脚本继续工作。并非所有事件都接收此字段。检查每个[hook 事件](#hook-events)部分中的 JSON 示例 |649| `permission_mode` | 当前[权限模式](/docs/zh-CN/permissions#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。标记为**手动**的模式作为 `"default"` 到达，永远不会作为 `"manual"` 到达，因此匹配 `"default"` 的脚本继续工作。并非所有事件都接收此字段。检查每个[hook 事件](#hook-events)部分中的 JSON 示例 |

650| `effort` | 对象，其中 `level` 字段保存该轮次的活跃[努力级别](/zh-CN/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。如果请求的模型努力级别超过当前模型支持的级别，这是模型实际使用的降级级别。Ultracode 不是一个不同的级别，报告为 `"xhigh"`。该对象与[状态行](/zh-CN/statusline#available-data) `effort` 字段匹配。存在于在工具使用上下文中触发的事件中，例如 `PreToolUse`、`PostToolUse`、`Stop` 和 `SubagentStop`，当当前模型支持努力参数时。该级别也可作为 `$CLAUDE_EFFORT` 环境变量提供给 hook 命令和 Bash 工具。 |650| `effort` | 对象，其中 `level` 字段保存该轮次的活跃[努力级别](/docs/zh-CN/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。如果请求的模型努力级别超过当前模型支持的级别，这是模型实际使用的降级级别。Ultracode 不是一个不同的级别，报告为 `"xhigh"`。该对象与[状态行](/docs/zh-CN/statusline#available-data) `effort` 字段匹配。存在于在工具使用上下文中触发的事件中，例如 `PreToolUse`、`PostToolUse`、`Stop` 和 `SubagentStop`，当当前模型支持努力参数时。该级别也可作为 `$CLAUDE_EFFORT` 环境变量提供给 hook 命令和 Bash 工具。 |

652 652

653使用 `--agent` 运行或在 subagent 内部时，包括两个额外字段：653使用 `--agent` 运行或在 subagent 内部时，包括两个额外字段：

655| 字段 | 描述 |655| 字段 | 描述 |

656| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |656| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

658| `agent_type` | 代理名称（例如，`"Explore"` 或 `"security-reviewer"`）。当会话使用 `--agent` 或 hook 在 subagent 内触发时存在。对于 subagents，subagent 的类型优先于会话的 `--agent` 值。对于[自定义 subagents](/zh-CN/sub-agents)，这是代理 frontmatter 中的 `name` 字段，而不是文件名。对于由[插件](/zh-CN/plugins)提供的 subagents，这是插件范围的标识符，例如 `my-plugin:reviewer`，而不是裸 frontmatter 名称。请参阅[SubagentStart](#subagentstart)了解如何针对插件范围的名称编写匹配器。 |658| `agent_type` | 代理名称（例如，`"Explore"` 或 `"security-reviewer"`）。当会话使用 `--agent` 或 hook 在 subagent 内触发时存在。对于 subagents，subagent 的类型优先于会话的 `--agent` 值。对于[自定义 subagents](/docs/zh-CN/sub-agents)，这是代理 frontmatter 中的 `name` 字段，而不是文件名。对于由[插件](/docs/zh-CN/plugins)提供的 subagents，这是插件范围的标识符，例如 `my-plugin:reviewer`，而不是裸 frontmatter 名称。请参阅[SubagentStart](#subagentstart)了解如何针对插件范围的名称编写匹配器。 |

659 659

660仅[`SessionStart`](#sessionstart) hooks 可以接收 `model` 字段，且不保证存在。没有 `$CLAUDE_MODEL` 环境变量。Hook 进程继承父环境，因此如果您在 shell 中设置了 `$ANTHROPIC_MODEL`，它可以读取该值，但当您在会话期间使用 `/model` 切换模型时，该值不会改变。一组变量不被继承：Claude Code [从它生成的每个子进程中删除 `OTEL_*` 导出器变量](/zh-CN/monitoring-usage#administrator-configuration)，包括 hooks。660仅[`SessionStart`](#sessionstart) hooks 可以接收 `model` 字段，且不保证存在。没有 `$CLAUDE_MODEL` 环境变量。Hook 进程继承父环境，因此如果您在 shell 中设置了 `$ANTHROPIC_MODEL`，它可以读取该值，但当您在会话期间使用 `/model` 切换模型时，该值不会改变。一组变量不被继承：Claude Code [从它生成的每个子进程中删除 `OTEL_*` 导出器变量](/docs/zh-CN/monitoring-usage#administrator-configuration)，包括 hooks。

661 661

662例如，Bash 命令的 `PreToolUse` hook 在 stdin 上接收：662例如，Bash 命令的 `PreToolUse` hook 在 stdin 上接收：

663 663

776 您必须为每个 hook 选择一种方法，而不是两种：要么单独使用退出代码进行信号传递，要么退出 0 并打印 JSON 以进行结构化控制。Claude Code 仅在退出 0 时处理 JSON。如果您退出 2，任何 JSON 都会被忽略。776 您必须为每个 hook 选择一种方法，而不是两种：要么单独使用退出代码进行信号传递，要么退出 0 并打印 JSON 以进行结构化控制。Claude Code 仅在退出 0 时处理 JSON。如果您退出 2，任何 JSON 都会被忽略。

777</Note>777</Note>

778 778

779您的 hook 的 stdout 必须仅包含 JSON 对象。如果您的 shell 配置文件在启动时打印文本，它可能会干扰 JSON 解析。请参阅故障排除指南中的[JSON 验证失败](/zh-CN/hooks-guide#json-validation-failed)。779您的 hook 的 stdout 必须仅包含 JSON 对象。如果您的 shell 配置文件在启动时打印文本，它可能会干扰 JSON 解析。请参阅故障排除指南中的[JSON 验证失败](/docs/zh-CN/hooks-guide#json-validation-failed)。

780 780

781Hook 输出字符串，包括 `additionalContext`、`systemMessage` 和纯 stdout，上限为 10,000 个字符。超过此限制的输出被保存到文件并替换为预览和文件路径，与大型工具结果的处理方式相同。781Hook 输出字符串，包括 `additionalContext`、`systemMessage` 和纯 stdout，上限为 10,000 个字符。超过此限制的输出被保存到文件并替换为预览和文件路径，与大型工具结果的处理方式相同。

782 782

868* **条件项目规则**：哪个测试命令适用于刚刚编辑的文件，哪些目录在此 worktree 中是只读的868* **条件项目规则**：哪个测试命令适用于刚刚编辑的文件，哪些目录在此 worktree 中是只读的

869* **外部数据**：分配给您的开放问题、最近的 CI 结果、从内部服务获取的内容869* **外部数据**：分配给您的开放问题、最近的 CI 结果、从内部服务获取的内容

870 870

871对于永不改变的说明，更倾向于[CLAUDE.md](/zh-CN/memory)。它加载时无需运行脚本，是静态项目约定的标准位置。871对于永不改变的说明，更倾向于[CLAUDE.md](/docs/zh-CN/memory)。它加载时无需运行脚本，是静态项目约定的标准位置。

872 872

873将文本写成事实陈述而不是命令式系统指令。措辞如"部署目标是生产"或"此 repo 使用 `bun test`"读作项目信息。框架为带外系统命令的文本可能会触发 Claude 的提示注入防御，这会导致 Claude 将文本呈现给您，而不是将其视为上下文。873将文本写成事实陈述而不是命令式系统指令。措辞如"部署目标是生产"或"此 repo 使用 `bun test`"读作项目信息。框架为带外系统命令的文本可能会触发 Claude 的提示注入防御，这会导致 Claude 将文本呈现给您，而不是将其视为上下文。

874 874

950 </Tab>950 </Tab>

951</Tabs>951</Tabs>

952 952

953有关扩展示例，包括 Bash 命令验证、提示过滤和自动批准脚本，请参阅指南中的[您可以自动化的内容](/zh-CN/hooks-guide#what-you-can-automate)以及[Bash 命令验证器参考实现](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py)。953有关扩展示例，包括 Bash 命令验证、提示过滤和自动批准脚本，请参阅指南中的[您可以自动化的内容](/docs/zh-CN/hooks-guide#what-you-can-automate)以及[Bash 命令验证器参考实现](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py)。

954 954

955<h2 id="hook-events">955<h2 id="hook-events">

956 Hook 事件956 Hook 事件

962 SessionStart962 SessionStart

963</h3>963</h3>

964 964

965在 Claude Code 启动新会话或恢复现有会话时运行。用于加载开发上下文，如现有问题或代码库的最近更改，或设置环境变量。对于不需要脚本的静态上下文，请改用[CLAUDE.md](/zh-CN/memory)。965在 Claude Code 启动新会话或恢复现有会话时运行。用于加载开发上下文，如现有问题或代码库的最近更改，或设置环境变量。对于不需要脚本的静态上下文，请改用[CLAUDE.md](/docs/zh-CN/memory)。

966 966

967SessionStart 在每个会话上运行，因此保持这些 hooks 快速。仅支持 `type: "command"` 和 `type: "mcp_tool"` hooks。967SessionStart 在每个会话上运行，因此保持这些 hooks 快速。仅支持 `type: "command"` 和 `type: "mcp_tool"` hooks。

968 968

1008| 字段 | 描述 |1008| 字段 | 描述 |

1009| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |1009| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |

1010| `additionalContext` | 添加到 Claude 上下文开始处的字符串，在第一个提示之前。请参阅[为 Claude 添加上下文](#add-context-for-claude)了解文本如何传递、放入什么内容以及恢复的会话如何处理过去的值 |1010| `additionalContext` | 添加到 Claude 上下文开始处的字符串，在第一个提示之前。请参阅[为 Claude 添加上下文](#add-context-for-claude)了解文本如何传递、放入什么内容以及恢复的会话如何处理过去的值 |

1011| `initialUserMessage` | 用作会话第一个用户消息的字符串。适用于[非交互模式](/zh-CN/headless)（`-p`），其中即使未提供提示，它也成为第一个轮次。如果提供了提示，它作为下一个轮次跟随。与 `additionalContext` 不同，后者附加到现有轮次，这创建轮次 |1011| `initialUserMessage` | 用作会话第一个用户消息的字符串。适用于[非交互模式](/docs/zh-CN/headless)（`-p`），其中即使未提供提示，它也成为第一个轮次。如果提供了提示，它作为下一个轮次跟随。与 `additionalContext` 不同，后者附加到现有轮次，这创建轮次 |

1012| `sessionTitle` | 设置会话标题，与 `/rename` 的效果相同。使用此根据启动文件夹、git 分支或 worktree 名称自动命名会话。仅在 `source` 为 `"startup"` 或 `"resume"` 时适用；在 `"clear"` 和 `"compact"` 上被忽略 |1012| `sessionTitle` | 设置会话标题，与 `/rename` 的效果相同。使用此根据启动文件夹、git 分支或 worktree 名称自动命名会话。仅在 `source` 为 `"startup"` 或 `"resume"` 时适用；在 `"clear"` 和 `"compact"` 上被忽略 |

1014| `reloadSkills` | 布尔值。当为 `true` 时，Claude Code 在 SessionStart hooks 完成后重新扫描[skill](/zh-CN/skills)和命令目录，因此 hook 安装的 skills 在同一会话中可用，从第一个提示开始 |1014| `reloadSkills` | 布尔值。当为 `true` 时，Claude Code 在 SessionStart hooks 完成后重新扫描[skill](/docs/zh-CN/skills)和命令目录，因此 hook 安装的 skills 在同一会话中可用，从第一个提示开始 |

1015 1015

1016```json theme={null}1016```json theme={null}

1017{1017{

1085 Setup1085 Setup

1086</h3>1086</h3>

1087 1087

1088仅当您使用 `--init-only` 启动 Claude Code，或在[非交互模式](/zh-CN/headless)中使用 `-p` 标志与 `--init` 或 `--maintenance` 结合时触发。它不在正常启动时触发。使用它进行一次性依赖安装或您从 CI 或脚本显式触发的计划清理，与正常会话启动分开。对于每个会话的初始化，请改用[SessionStart](#sessionstart)。1088仅当您使用 `--init-only` 启动 Claude Code，或在[非交互模式](/docs/zh-CN/headless)中使用 `-p` 标志与 `--init` 或 `--maintenance` 结合时触发。它不在正常启动时触发。使用它进行一次性依赖安装或您从 CI 或脚本显式触发的计划清理，与正常会话启动分开。对于每个会话的初始化，请改用[SessionStart](#sessionstart)。

1089 1089

1090匹配器值对应于触发 hook 的 CLI 标志：1090匹配器值对应于触发 hook 的 CLI 标志：

1091 1091

1096 1096

1097`--init-only` 运行 Setup hooks 和 SessionStart hooks（带 `startup` 匹配器），然后退出而不启动对话。`--init` 和 `--maintenance` 仅在与 `-p` 结合时触发 Setup hooks；在交互式会话中，这两个标志目前不触发 Setup hooks。1097`--init-only` 运行 Setup hooks 和 SessionStart hooks（带 `startup` 匹配器），然后退出而不启动对话。`--init` 和 `--maintenance` 仅在与 `-p` 结合时触发 Setup hooks；在交互式会话中，这两个标志目前不触发 Setup hooks。

1098 1098

1099因为 Setup 不在每次启动时触发，需要安装依赖的插件不能仅依赖 Setup。实际的模式是在首次使用时检查依赖，如果缺失则安装，例如测试 `${CLAUDE_PLUGIN_DATA}/node_modules` 的 hook 或 skill，如果不存在则运行 `npm install`。请参阅[持久数据目录](/zh-CN/plugins-reference#persistent-data-directory)了解在何处存储已安装的依赖。1099因为 Setup 不在每次启动时触发，需要安装依赖的插件不能仅依赖 Setup。实际的模式是在首次使用时检查依赖，如果缺失则安装，例如测试 `${CLAUDE_PLUGIN_DATA}/node_modules` 的 hook 或 skill，如果不存在则运行 `npm install`。请参阅[持久数据目录](/docs/zh-CN/plugins-reference#persistent-data-directory)了解在何处存储已安装的依赖。

1100 1100

1101<h4 id="setup-input">1101<h4 id="setup-input">

1102 Setup 输入1102 Setup 输入

1118 Setup 决定控制1118 Setup 决定控制

1119</h4>1119</h4>

1120 1120

1121Setup hooks 无法阻止。任何非零退出代码（包括 2）都会向用户显示 stderr 作为 `<hook name> hook error` 通知，执行继续。在[非交互模式](/zh-CN/headless)中，hook 输出仅在您使用 `--verbose` 启动时出现。1121Setup hooks 无法阻止。任何非零退出代码（包括 2）都会向用户显示 stderr 作为 `<hook name> hook error` 通知，执行继续。在[非交互模式](/docs/zh-CN/headless)中，hook 输出仅在您使用 `--verbose` 启动时出现。

1122 1122

1123要将信息传入 Claude 的上下文，在 JSON 输出中返回 `additionalContext`；纯 stdout 仅写入调试日志。除了所有 hooks 可用的[JSON 输出字段](#json-output)外，您还可以返回这些事件特定字段：1123要将信息传入 Claude 的上下文，在 JSON 输出中返回 `additionalContext`；纯 stdout 仅写入调试日志。除了所有 hooks 可用的[JSON 输出字段](#json-output)外，您还可以返回这些事件特定字段：

1124 1124

1188 1188

1189达到超时的 `UserPromptSubmit` hook 被取消，其输出（包括任何 `additionalContext`）被丢弃。提示仍然到达 Claude，但没有该上下文。从 v2.1.196 开始，成绩单显示一个通知，命名 hook、触发的超时以及输出被丢弃。早期版本取消 hook 而不显示通知。1189达到超时的 `UserPromptSubmit` hook 被取消，其输出（包括任何 `additionalContext`）被丢弃。提示仍然到达 Claude，但没有该上下文。从 v2.1.196 开始，成绩单显示一个通知，命名 hook、触发的超时以及输出被丢弃。早期版本取消 hook 而不显示通知。

1190 1190

1191在 `UserPromptSubmit` 上达到超时的[Agent SDK 回调 hook](/zh-CN/agent-sdk/hooks)会用命名 hook 和超时的消息阻止提示，因为那里的回调可能充当必须不失败打开的策略门。会话继续。在 v2.1.208 之前，该事件上的回调超时以执行错误结束轮次。1191在 `UserPromptSubmit` 上达到超时的[Agent SDK 回调 hook](/docs/zh-CN/agent-sdk/hooks)会用命名 hook 和超时的消息阻止提示，因为那里的回调可能充当必须不失败打开的策略门。会话继续。在 v2.1.208 之前，该事件上的回调超时以执行错误结束轮次。

1192 1192

1193<h4 id="userpromptsubmit-input">1193<h4 id="userpromptsubmit-input">

1194 UserPromptSubmit 输入1194 UserPromptSubmit 输入

1443在 Claude 创建工具参数后和处理工具调用之前运行。在工具名称上匹配：`Bash`、`Edit`、`Write`、`Read`、`Glob`、`Grep`、`Agent`、`WebFetch`、`WebSearch`、`AskUserQuestion`、`ExitPlanMode` 和任何[MCP 工具名称](#match-mcp-tools)。1443在 Claude 创建工具参数后和处理工具调用之前运行。在工具名称上匹配：`Bash`、`Edit`、`Write`、`Read`、`Glob`、`Grep`、`Agent`、`WebFetch`、`WebSearch`、`AskUserQuestion`、`ExitPlanMode` 和任何[MCP 工具名称](#match-mcp-tools)。

1444 1444

1445<Warning>1445<Warning>

1446 PreToolUse 仅在 Claude 调用工具时运行。您[在提示中使用 `@` 引用的文件](/zh-CN/common-workflows#reference-files-and-directories)被添加而不进行任何工具调用：Claude Code 在构建提示时插入其内容，因此没有 PreToolUse hook 对它们触发，包括匹配 `Read` 的 hooks。要阻止特定路径的 `@` 引用，请改用[`Read` 拒绝规则](/zh-CN/permissions#read-and-edit)。1446 PreToolUse 仅在 Claude 调用工具时运行。您[在提示中使用 `@` 引用的文件](/docs/zh-CN/common-workflows#reference-files-and-directories)被添加而不进行任何工具调用：Claude Code 在构建提示时插入其内容，因此没有 PreToolUse hook 对它们触发，包括匹配 `Read` 的 hooks。要阻止特定路径的 `@` 引用，请改用[`Read` 拒绝规则](/docs/zh-CN/permissions#read-and-edit)。

1447</Warning>1447</Warning>

1448 1448

1449使用[PreToolUse 决定控制](#pretooluse-decision-control)来允许、拒绝、询问或延迟工具调用。1449使用[PreToolUse 决定控制](#pretooluse-decision-control)来允许、拒绝、询问或延迟工具调用。

1464| :------------------ | :------ | :----------------- | :------------------------------------------------------------------------- |1464| :------------------ | :------ | :----------------- | :------------------------------------------------------------------------- |

1469 1469

1470<h5 id="write">1470<h5 id="write">

1556 Agent1556 Agent

1557</h5>1557</h5>

1558 1558

1559生成一个[subagent](/zh-CN/sub-agents)。1559生成一个[subagent](/docs/zh-CN/sub-agents)。

1560 1560

1561| 字段 | 类型 | 示例 | 描述 |1561| 字段 | 类型 | 示例 | 描述 |

1562| :-------------- | :----- | :------------------------- | :------------ |1562| :-------------- | :----- | :------------------------- | :------------ |

1599 ExitPlanMode1599 ExitPlanMode

1600</h5>1600</h5>

1601 1601

1602呈现一个计划并要求用户在 Claude 离开[Plan Mode](/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)之前批准它。Claude 在调用工具之前将计划写入磁盘上的文件，因此来自模型的字面 `tool_input` 通常为空。Claude Code 在将输入传递给 hooks 之前注入计划内容和文件路径。1602呈现一个计划并要求用户在 Claude 离开[Plan Mode](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)之前批准它。Claude 在调用工具之前将计划写入磁盘上的文件，因此来自模型的字面 `tool_input` 通常为空。Claude Code 在将输入传递给 hooks 之前注入计划内容和文件路径。

1603 1603

1604| 字段 | 类型 | 示例 | 描述 |1604| 字段 | 类型 | 示例 | 描述 |

1605| :--------------- | :----- | :------------------------------------------ | :-------------------------------------------------------------------------------------------- |1605| :--------------- | :----- | :------------------------------------------ | :-------------------------------------------------------------------------------------------- |

1617 1617

1618| 字段 | 描述 |1618| 字段 | 描述 |

1619| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1619| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1620| `permissionDecision` | `"allow"` 绕过权限提示，除了[需要用户交互的工具](#pretooluse-decision-control)和连接器工具[您的组织设置为 `ask`](/zh-CN/mcp#organization-controls-on-connector-tools)。`"deny"` 防止工具调用。`"ask"` 提示用户确认。`"defer"` 优雅地退出，以便工具稍后可以恢复。[拒绝和询问规则](/zh-CN/permissions#manage-permissions)在 hook 返回什么时仍然被评估 |1620| `permissionDecision` | `"allow"` 绕过权限提示，除了[需要用户交互的工具](#pretooluse-decision-control)和连接器工具[您的组织设置为 `ask`](/docs/zh-CN/mcp#organization-controls-on-connector-tools)。`"deny"` 防止工具调用。`"ask"` 提示用户确认。`"defer"` 优雅地退出，以便工具稍后可以恢复。[拒绝和询问规则](/docs/zh-CN/permissions#manage-permissions)在 hook 返回什么时仍然被评估 |

1622| `updatedInput` | 在执行前修改工具的输入参数。替换整个输入对象，因此包括未修改的字段以及修改后的字段。与 `"allow"` 结合以自动批准，或与 `"ask"` 结合以向用户显示修改后的输入。对于 `"defer"`，被忽略 |1622| `updatedInput` | 在执行前修改工具的输入参数。替换整个输入对象，因此包括未修改的字段以及修改后的字段。与 `"allow"` 结合以自动批准，或与 `"ask"` 结合以向用户显示修改后的输入。对于 `"defer"`，被忽略 |

1640}1640}

1641```1641```

1642 1642

1643`AskUserQuestion` 和 `ExitPlanMode` 需要用户交互，通常在[非交互模式](/zh-CN/headless)中使用 `-p` 标志时阻止。返回 `permissionDecision: "allow"` 以及 `updatedInput` 满足该要求：hook 从 stdin 读取工具的输入，通过您自己的 UI 收集答案，并在 `updatedInput` 中返回它，以便工具运行而不提示。仅返回 `"allow"` 对这些工具不足够。对于 `AskUserQuestion`，回显原始 `questions` 数组并添加一个[`answers`](#askuserquestion)对象，将每个问题的文本映射到选定的答案。1643`AskUserQuestion` 和 `ExitPlanMode` 需要用户交互，通常在[非交互模式](/docs/zh-CN/headless)中使用 `-p` 标志时阻止。返回 `permissionDecision: "allow"` 以及 `updatedInput` 满足该要求：hook 从 stdin 读取工具的输入，通过您自己的 UI 收集答案，并在 `updatedInput` 中返回它，以便工具运行而不提示。仅返回 `"allow"` 对这些工具不足够。对于 `AskUserQuestion`，回显原始 `questions` 数组并添加一个[`answers`](#askuserquestion)对象，将每个问题的文本映射到选定的答案。

1644 1644

1645连接器工具[您的组织设置为 `ask`](/zh-CN/mcp#organization-controls-on-connector-tools)即使 hook 返回 `"allow"` 也会提示。1645连接器工具[您的组织设置为 `ask`](/docs/zh-CN/mcp#organization-controls-on-connector-tools)即使 hook 返回 `"allow"` 也会提示。

1646 1646

1647从 v2.1.199 开始，一个 MCP 工具，其服务器用 [`_meta["anthropic/requiresUserInteraction"]`](/zh-CN/mcp#require-approval-for-a-specific-tool) 标记它，更严格：hook 不能用 `"allow"` 跳过其批准提示，无论是否有 `updatedInput`，因为 Claude Code 无法确认 hook 收集了工具需要的交互。1647从 v2.1.199 开始，一个 MCP 工具，其服务器用 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 标记它，更严格：hook 不能用 `"allow"` 跳过其批准提示，无论是否有 `updatedInput`，因为 Claude Code 无法确认 hook 收集了工具需要的交互。

1648 1648

1649<Note>1649<Note>

1650 PreToolUse 之前使用顶级 `decision` 和 `reason` 字段，但这些对此事件已弃用。改用 `hookSpecificOutput.permissionDecision` 和 `hookSpecificOutput.permissionDecisionReason`。已弃用的值 `"approve"` 和 `"block"` 映射到 `"allow"` 和 `"deny"`。PostToolUse 和 Stop 等其他事件继续使用顶级 `decision` 和 `reason` 作为其当前格式。1650 PreToolUse 之前使用顶级 `decision` 和 `reason` 字段，但这些对此事件已弃用。改用 `hookSpecificOutput.permissionDecision` 和 `hookSpecificOutput.permissionDecisionReason`。已弃用的值 `"approve"` 和 `"block"` 映射到 `"allow"` 和 `"deny"`。PostToolUse 和 Stop 等其他事件继续使用顶级 `decision` 和 `reason` 作为其当前格式。

1654 延迟工具调用以供稍后使用1654 延迟工具调用以供稍后使用

1655</h4>1655</h4>

1656 1656

1657`"defer"` 用于运行 `claude -p` 作为子进程并读取其 JSON 输出的集成，例如 Agent SDK 应用或构建在 Claude Code 之上的自定义 UI。它让该调用进程在工具调用处暂停 Claude，通过其自己的界面收集输入，并从中断处恢复。Claude Code 仅在[非交互模式](/zh-CN/headless)中使用 `-p` 标志时遵守此值。在交互式会话中，它记录警告并忽略 hook 结果。1657`"defer"` 用于运行 `claude -p` 作为子进程并读取其 JSON 输出的集成，例如 Agent SDK 应用或构建在 Claude Code 之上的自定义 UI。它让该调用进程在工具调用处暂停 Claude，通过其自己的界面收集输入，并从中断处恢复。Claude Code 仅在[非交互模式](/docs/zh-CN/headless)中使用 `-p` 标志时遵守此值。在交互式会话中，它记录警告并忽略 hook 结果。

1658 1658

1659`AskUserQuestion` 工具是典型情况：Claude 想要询问用户一些事情，但没有终端来回答。往返工作如下：1659`AskUserQuestion` 工具是典型情况：Claude 想要询问用户一些事情，但没有终端来回答。往返工作如下：

1660 1660

1680}1680}

1681```1681```

1682 1682

1683没有超时或重试限制。会话保留在磁盘上，直到您恢复它，受到 [`cleanupPeriodDays`](/zh-CN/settings#available-settings) 保留扫描的约束，该扫描默认在 30 天后删除会话文件。如果恢复时答案还没有准备好，hook 可以再次返回 `"defer"`，进程以相同的方式退出。调用进程控制何时通过最终返回 `"allow"` 或 `"deny"` 从 hook 中断循环。1683没有超时或重试限制。会话保留在磁盘上，直到您恢复它，受到 [`cleanupPeriodDays`](/docs/zh-CN/settings#available-settings) 保留扫描的约束，该扫描默认在 30 天后删除会话文件。如果恢复时答案还没有准备好，hook 可以再次返回 `"defer"`，进程以相同的方式退出。调用进程控制何时通过最终返回 `"allow"` 或 `"deny"` 从 hook 中断循环。

1684 1684

1685`"defer"` 仅在 Claude 在轮次中进行单个工具调用时有效。如果 Claude 一次进行多个工具调用，`"defer"` 被忽略并显示警告，工具通过正常权限流程进行。约束存在是因为恢复只能重新运行一个工具：没有办法延迟一个调用而不留下其他调用未解决。1685`"defer"` 仅在 Claude 在轮次中进行单个工具调用时有效。如果 Claude 一次进行多个工具调用，`"defer"` 被忽略并显示警告，工具通过正常权限流程进行。约束存在是因为恢复只能重新运行一个工具：没有办法延迟一个调用而不留下其他调用未解决。

1686 1686

1735 1735

1736| 字段 | 描述 |1736| 字段 | 描述 |

1737| :------------------- | :------------------------------------------------------------------------------------------------------------------ |1737| :------------------- | :------------------------------------------------------------------------------------------------------------------ |

1738| `behavior` | `"allow"` 授予权限，`"deny"` 拒绝它。[拒绝和询问规则](/zh-CN/permissions#manage-permissions)仍然被评估，所以返回 `"allow"` 的 hook 不会覆盖匹配的拒绝规则 |1738| `behavior` | `"allow"` 授予权限，`"deny"` 拒绝它。[拒绝和询问规则](/docs/zh-CN/permissions#manage-permissions)仍然被评估，所以返回 `"allow"` 的 hook 不会覆盖匹配的拒绝规则 |

1772 1772

1773<Note>1773<Note>

1774 `setMode` 与 `bypassPermissions` 仅在会话已启动时生效，绕过模式已可用：`--dangerously-skip-permissions`、`--permission-mode bypassPermissions`、`--allow-dangerously-skip-permissions` 或设置中的 `permissions.defaultMode: "bypassPermissions"`，且模式未被 [`permissions.disableBypassPermissionsMode`](/zh-CN/permissions#managed-settings) 禁用。否则更新是无操作。`bypassPermissions` 无论 `destination` 如何都永远不会作为 `defaultMode` 持久化。1774 `setMode` 与 `bypassPermissions` 仅在会话已启动时生效，绕过模式已可用：`--dangerously-skip-permissions`、`--permission-mode bypassPermissions`、`--allow-dangerously-skip-permissions` 或设置中的 `permissions.defaultMode: "bypassPermissions"`，且模式未被 [`permissions.disableBypassPermissionsMode`](/docs/zh-CN/permissions#managed-settings) 禁用。否则更新是无操作。`bypassPermissions` 无论 `destination` 如何都永远不会作为 `defaultMode` 持久化。

1775</Note>1775</Note>

1776 1776

1777每个条目上的 `destination` 字段确定更改是保留在内存中还是持久化到设置文件。1777每个条目上的 `destination` 字段确定更改是保留在内存中还是持久化到设置文件。

1990 PermissionDenied1990 PermissionDenied

1991</h3>1991</h3>

1992 1992

1993当[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器拒绝工具调用时运行。此 hook 仅在自动模式中触发：当您手动拒绝权限对话框、`PreToolUse` hook 阻止调用或 `deny` 规则匹配时，它不运行。使用它来记录分类器拒绝、调整配置或告诉模型它可能重试工具调用。1993当[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器拒绝工具调用时运行。此 hook 仅在自动模式中触发：当您手动拒绝权限对话框、`PreToolUse` hook 阻止调用或 `deny` 规则匹配时，它不运行。使用它来记录分类器拒绝、调整配置或告诉模型它可能重试工具调用。

1994 1994

1995在工具名称上匹配，与 PreToolUse 相同的值。1995在工具名称上匹配，与 PreToolUse 相同的值。

1996 1996

2057 2057

2058`agent_needs_input` 和 `agent_completed` 类型需要 Claude Code v2.1.198 或更高版本。2058`agent_needs_input` 和 `agent_completed` 类型需要 Claude Code v2.1.198 或更高版本。

2059 2059

2110 SubagentStart2110 SubagentStart

2111</h3>2111</h3>

2112 2112

2113当通过 Agent 工具生成 Claude Code subagent 时运行。支持匹配器以按代理类型名称过滤。对于内置代理，这是代理名称，如 `general-purpose`、`Explore` 或 `Plan`。对于[自定义 subagents](/zh-CN/sub-agents)，这是代理 frontmatter 中的 `name` 字段，而不是文件名。2113当通过 Agent 工具生成 Claude Code subagent 时运行。支持匹配器以按代理类型名称过滤。对于内置代理，这是代理名称，如 `general-purpose`、`Explore` 或 `Plan`。对于[自定义 subagents](/docs/zh-CN/sub-agents)，这是代理 frontmatter 中的 `name` 字段，而不是文件名。

2114 2114

2115对于由[插件](/zh-CN/plugins)提供的 subagents，代理类型是插件范围的标识符，例如 `my-plugin:reviewer`，而不是裸 frontmatter 名称。冒号将插件范围的名称放在正则表达式路径上，因此使用 `^` 和 `$` 锚定匹配器以进行精确匹配：`^my-plugin:reviewer$`。2115对于由[插件](/docs/zh-CN/plugins)提供的 subagents，代理类型是插件范围的标识符，例如 `my-plugin:reviewer`，而不是裸 frontmatter 名称。冒号将插件范围的名称放在正则表达式路径上，因此使用 `^` 和 `$` 锚定匹配器以进行精确匹配：`^my-plugin:reviewer$`。

2116 2116

2117<h4 id="subagentstart-input">2117<h4 id="subagentstart-input">

2118 SubagentStart 输入2118 SubagentStart 输入

2244 TaskCompleted2244 TaskCompleted

2245</h3>2245</h3>

2246 2246

2247当任务被标记为已完成时运行。这在两种情况下触发：当任何代理通过 TaskUpdate 工具显式标记任务为已完成时，或当[代理团队](/zh-CN/agent-teams)队友完成其轮次且有进行中的任务时。使用此来强制执行完成标准，如通过测试或 lint 检查，然后任务才能关闭。2247当任务被标记为已完成时运行。这在两种情况下触发：当任何代理通过 TaskUpdate 工具显式标记任务为已完成时，或当[代理团队](/docs/zh-CN/agent-teams)队友完成其轮次且有进行中的任务时。使用此来强制执行完成标准，如通过测试或 lint 检查，然后任务才能关闭。

2248 2248

2249当 `TaskCompleted` hook 以代码 2 退出时，任务不被标记为已完成，stderr 消息作为反馈反馈给模型。要完全停止队友而不是重新运行它，返回 JSON `{"continue": false, "stopReason": "..."}` 。TaskCompleted hooks 不支持匹配器，在每次出现时触发。2249当 `TaskCompleted` hook 以代码 2 退出时，任务不被标记为已完成，stderr 消息作为反馈反馈给模型。要完全停止队友而不是重新运行它，返回 JSON `{"continue": false, "stopReason": "..."}` 。TaskCompleted hooks 不支持匹配器，在每次出现时触发。

2250 2250

2309在主 Claude Code 代理完成响应时运行。如果停止是由于用户中断，则不运行。API 错误触发[StopFailure](#stopfailure)。2309在主 Claude Code 代理完成响应时运行。如果停止是由于用户中断，则不运行。API 错误触发[StopFailure](#stopfailure)。

2310 2310

2311<Tip>2311<Tip>

2312 [`/goal`](/zh-CN/goal)命令是会话范围的基于提示的 Stop hook 的内置快捷方式。当您想要 Claude 继续工作直到条件成立而不编写 hook 配置时使用它。2312 [`/goal`](/docs/zh-CN/goal)命令是会话范围的基于提示的 Stop hook 的内置快捷方式。当您想要 Claude 继续工作直到条件成立而不编写 hook 配置时使用它。

2313</Tip>2313</Tip>

2314 2314

2315<h4 id="stop-input">2315<h4 id="stop-input">

2442 TeammateIdle2442 TeammateIdle

2443</h3>2443</h3>

2444 2444

2445当[代理团队](/zh-CN/agent-teams)队友在完成其轮次后即将空闲时运行。使用此来强制执行质量门，如要求通过 lint 检查或验证输出文件存在。2445当[代理团队](/docs/zh-CN/agent-teams)队友在完成其轮次后即将空闲时运行。使用此来强制执行质量门，如要求通过 lint 检查或验证输出文件存在。

2446 2446

2447当 `TeammateIdle` hook 以代码 2 退出时，队友接收 stderr 消息作为反馈并继续工作而不是空闲。要完全停止队友而不是重新运行它，返回 JSON `{"continue": false, "stopReason": "..."}` 。TeammateIdle hooks 不支持匹配器，在每次出现时触发。2447当 `TeammateIdle` hook 以代码 2 退出时，队友接收 stderr 消息作为反馈并继续工作而不是空闲。要完全停止队友而不是重新运行它，返回 JSON `{"continue": false, "stopReason": "..."}` 。TeammateIdle hooks 不支持匹配器，在每次出现时触发。

2448 2448

2656 WorktreeCreate2656 WorktreeCreate

2657</h3>2657</h3>

2658 2658

2659当您运行 `claude --worktree` 或[subagent 使用 `isolation: "worktree"`](/zh-CN/sub-agents#choose-the-subagent-scope)时运行。默认情况下，Claude Code 使用 `git worktree` 创建隔离的工作副本。配置 WorktreeCreate hook 替换该默认 git 行为，让您使用不同的版本控制系统，如 SVN、Perforce 或 Mercurial。2659当您运行 `claude --worktree` 或[subagent 使用 `isolation: "worktree"`](/docs/zh-CN/sub-agents#choose-the-subagent-scope)时运行。默认情况下，Claude Code 使用 `git worktree` 创建隔离的工作副本。配置 WorktreeCreate hook 替换该默认 git 行为，让您使用不同的版本控制系统，如 SVN、Perforce 或 Mercurial。

2660 2660

2661因为 hook 完全替换默认行为，[`.worktreeinclude`](/zh-CN/worktrees#copy-gitignored-files-into-worktrees)不被处理。如果您需要将本地配置文件（如 `.env`）复制到新 worktree，请在您的 hook 脚本内执行。2661因为 hook 完全替换默认行为，[`.worktreeinclude`](/docs/zh-CN/worktrees#copy-gitignored-files-into-worktrees)不被处理。如果您需要将本地配置文件（如 `.env`）复制到新 worktree，请在您的 hook 脚本内执行。

2662 2662

2663Hook 必须返回创建的 worktree 目录的绝对路径。Claude Code 使用此路径作为隔离会话的工作目录。请参阅[WorktreeCreate 输出](#worktreecreate-output)了解每个 hook 类型如何返回路径。2663Hook 必须返回创建的 worktree 目录的绝对路径。Claude Code 使用此路径作为隔离会话的工作目录。请参阅[WorktreeCreate 输出](#worktreecreate-output)了解每个 hook 类型如何返回路径。

2664 2664

3111 检查多个条件后再停止3111 检查多个条件后再停止

3112</h3>3112</h3>

3113 3113

3114此 `Stop` hook 使用详细提示检查三个条件，然后允许 Claude 停止。`SubagentStop` hooks 使用相同的格式来评估[子代理](/zh-CN/sub-agents)是否应该停止。如果 `"ok"` 为 `false`，Claude 继续工作，提供的原因作为其下一条指令：3114此 `Stop` hook 使用详细提示检查三个条件，然后允许 Claude 停止。`SubagentStop` hooks 使用相同的格式来评估[子代理](/docs/zh-CN/sub-agents)是否应该停止。如果 `"ok"` 为 `false`，Claude 继续工作，提供的原因作为其下一条指令：

3115 3115

3116```json theme={null}3116```json theme={null}

3117{3117{

3384 3384

3385对于更细粒度的 hook 匹配详细信息，设置 `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` 以查看额外的日志行，例如 hook 匹配器计数和查询匹配。3385对于更细粒度的 hook 匹配详细信息，设置 `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` 以查看额外的日志行，例如 hook 匹配器计数和查询匹配。

3386 3386

3387有关故障排除常见问题，如 hooks 不触发、Stop hooks 持续阻止或配置错误，请参阅指南中的[限制和故障排除](/zh-CN/hooks-guide#limitations-and-troubleshooting)。有关涵盖 `/context`、`/doctor` 和设置优先级的更广泛的诊断演练，请参阅[调试你的配置](/zh-CN/debug-your-config)。3387有关故障排除常见问题，如 hooks 不触发、Stop hooks 持续阻止或配置错误，请参阅指南中的[限制和故障排除](/docs/zh-CN/hooks-guide#limitations-and-troubleshooting)。有关涵盖 `/context`、`/doctor` 和设置优先级的更广泛的诊断演练，请参阅[调试你的配置](/docs/zh-CN/debug-your-config)。

hooks-guide.md +50 −50

Details

10 10

11对于需要判断而不是确定性规则的决策，你也可以使用 [基于提示的 hooks](#prompt-based-hooks) 或 [基于代理的 hooks](#agent-based-hooks)，它们使用 Claude 模型来评估条件。11对于需要判断而不是确定性规则的决策，你也可以使用 [基于提示的 hooks](#prompt-based-hooks) 或 [基于代理的 hooks](#agent-based-hooks)，它们使用 Claude 模型来评估条件。

12 12

13有关扩展 Claude Code 的其他方式，请参阅 [skills](/zh-CN/skills) 用于为 Claude 提供额外的指令和可执行命令，[subagents](/zh-CN/sub-agents) 用于在隔离的上下文中运行任务，以及 [plugins](/zh-CN/plugins) 用于打包要在项目间共享的扩展。13有关扩展 Claude Code 的其他方式，请参阅 [skills](/docs/zh-CN/skills) 用于为 Claude 提供额外的指令和可执行命令，[subagents](/docs/zh-CN/sub-agents) 用于在隔离的上下文中运行任务，以及 [plugins](/docs/zh-CN/plugins) 用于打包要在项目间共享的扩展。

14 14

15<Tip>15<Tip>

16 本指南涵盖常见用例和入门方法。有关完整的事件架构、JSON 输入/输出格式和异步 hooks 和 MCP 工具 hooks 等高级功能，请参阅 [Hooks 参考](/zh-CN/hooks)。16 本指南涵盖常见用例和入门方法。有关完整的事件架构、JSON 输入/输出格式和异步 hooks 和 MCP 工具 hooks 等高级功能，请参阅 [Hooks 参考](/docs/zh-CN/hooks)。

17</Tip>17</Tip>

18 18

19<h2 id="set-up-your-first-hook">19<h2 id="set-up-your-first-hook">

85 你可以自动化什么85 你可以自动化什么

86</h2>86</h2>

87 87

88Hooks 让你在 Claude Code 生命周期中的关键点运行代码：编辑后格式化文件、在执行前阻止命令、在 Claude 需要输入时发送通知、在会话开始时注入上下文等。有关完整的 hook 事件列表，请参阅 [Hooks 参考](/zh-CN/hooks#hook-lifecycle)。88Hooks 让你在 Claude Code 生命周期中的关键点运行代码：编辑后格式化文件、在执行前阻止命令、在 Claude 需要输入时发送通知、在会话开始时注入上下文等。有关完整的 hook 事件列表，请参阅 [Hooks 参考](/docs/zh-CN/hooks#hook-lifecycle)。

89 89

90每个示例都包含一个现成的配置块，你可以将其添加到 [设置文件](#configure-hook-location)。90每个示例都包含一个现成的配置块，你可以将其添加到 [设置文件](#configure-hook-location)。

91 91

92有关运行单独模型审查并将发现反馈回会话的 hooks 的生产示例，请参阅 [`security-guidance` 插件如何与 Claude Code 集成](/zh-CN/security-guidance#how-the-plugin-integrates-with-claude-code)。92有关运行单独模型审查并将发现反馈回会话的 hooks 的生产示例，请参阅 [`security-guidance` 插件如何与 Claude Code 集成](/docs/zh-CN/security-guidance#how-the-plugin-integrates-with-claude-code)。

93 93

94<h3 id="get-notified-when-claude-needs-input">94<h3 id="get-notified-when-claude-needs-input">

95 在 Claude 需要输入时获得通知95 在 Claude 需要输入时获得通知

186 186

187`agent_needs_input` 和 `agent_completed` 匹配器需要 Claude Code v2.1.198 或更高版本。187`agent_needs_input` 和 `agent_completed` 匹配器需要 Claude Code v2.1.198 或更高版本。

188 188

189输入 `/hooks` 并选择 `Notification` 以确认 hook 已注册。有关完整的事件架构，请参阅 [Notification 参考](/zh-CN/hooks#notification)。189输入 `/hooks` 并选择 `Notification` 以确认 hook 已注册。有关完整的事件架构，请参阅 [Notification 参考](/docs/zh-CN/hooks#notification)。

190 190

191<h3 id="auto-format-code-after-edits">191<h3 id="auto-format-code-after-edits">

192 编辑后自动格式化代码192 编辑后自动格式化代码

309}309}

310```310```

311 311

312你可以用任何产生动态输出的命令替换 `echo`，如 `git log --oneline -5` 来显示最近的提交。有关在每个会话开始时注入上下文，请考虑改用 [CLAUDE.md](/zh-CN/memory)。有关环境变量，请参阅参考中的 [`CLAUDE_ENV_FILE`](/zh-CN/hooks#persist-environment-variables)。312你可以用任何产生动态输出的命令替换 `echo`，如 `git log --oneline -5` 来显示最近的提交。有关在每个会话开始时注入上下文，请考虑改用 [CLAUDE.md](/docs/zh-CN/memory)。有关环境变量，请参阅参考中的 [`CLAUDE_ENV_FILE`](/docs/zh-CN/hooks#persist-environment-variables)。

313 313

314<h3 id="audit-configuration-changes">314<h3 id="audit-configuration-changes">

315 审计配置更改315 审计配置更改

337}337}

338```338```

339 339

340匹配器按配置类型过滤：`user_settings`、`project_settings`、`local_settings`、`policy_settings` 或 `skills`。要阻止更改生效，以代码 2 退出或返回 `{"decision": "block"}`。有关完整的输入架构，请参阅 [ConfigChange 参考](/zh-CN/hooks#configchange)。340匹配器按配置类型过滤：`user_settings`、`project_settings`、`local_settings`、`policy_settings` 或 `skills`。要阻止更改生效，以代码 2 退出或返回 `{"decision": "block"}`。有关完整的输入架构，请参阅 [ConfigChange 参考](/docs/zh-CN/hooks#configchange)。

341 341

342<h3 id="reload-environment-when-directory-or-files-change">342<h3 id="reload-environment-when-directory-or-files-change">

343 当目录或文件更改时重新加载环境343 当目录或文件更改时重新加载环境

376 376

377在每个包含 `.envrc` 的目录中运行一次 `direnv allow`，以便 direnv 被允许加载它。如果你使用 devbox 或 nix 而不是 direnv，相同的模式适用于 `devbox shellenv` 或 `devbox global shellenv` 代替 `direnv export bash`。377在每个包含 `.envrc` 的目录中运行一次 `direnv allow`，以便 direnv 被允许加载它。如果你使用 devbox 或 nix 而不是 direnv，相同的模式适用于 `devbox shellenv` 或 `devbox global shellenv` 代替 `direnv export bash`。

378 378

379要对特定文件而不是每个目录更改做出反应，请使用 `FileChanged` 和 `matcher` 列出要监视的文件名，用 `|` 分隔。要构建监视列表，Claude Code 将此值分割为文字文件名而不是作为正则表达式进行评估。有关当文件更改时相同值如何也过滤哪些 hook 组运行，请参阅 [FileChanged](/zh-CN/hooks#filechanged)。此示例监视工作目录中 `.envrc` 和 `.env` 的更改：379要对特定文件而不是每个目录更改做出反应，请使用 `FileChanged` 和 `matcher` 列出要监视的文件名，用 `|` 分隔。要构建监视列表，Claude Code 将此值分割为文字文件名而不是作为正则表达式进行评估。有关当文件更改时相同值如何也过滤哪些 hook 组运行，请参阅 [FileChanged](/docs/zh-CN/hooks#filechanged)。此示例监视工作目录中 `.envrc` 和 `.env` 的更改：

380 380

381```json theme={null}381```json theme={null}

382{382{

396}396}

397```397```

398 398

399有关输入架构、`watchPaths` 输出和 `CLAUDE_ENV_FILE` 详情，请参阅 [CwdChanged](/zh-CN/hooks#cwdchanged) 和 [FileChanged](/zh-CN/hooks#filechanged) 参考条目。399有关输入架构、`watchPaths` 输出和 `CLAUDE_ENV_FILE` 详情，请参阅 [CwdChanged](/docs/zh-CN/hooks#cwdchanged) 和 [FileChanged](/docs/zh-CN/hooks#filechanged) 参考条目。

400 400

401<h3 id="auto-approve-specific-permission-prompts">401<h3 id="auto-approve-specific-permission-prompts">

402 自动批准特定权限提示402 自动批准特定权限提示

431要改为设置特定的权限模式，你的 hook 的输出可以包含一个 `updatedPermissions` 数组，其中包含 `setMode` 条目。`mode` 值是任何权限模式，如 `default`、`acceptEdits` 或 `bypassPermissions`，`destination: "session"` 仅将其应用于当前会话。431要改为设置特定的权限模式，你的 hook 的输出可以包含一个 `updatedPermissions` 数组，其中包含 `setMode` 条目。`mode` 值是任何权限模式，如 `default`、`acceptEdits` 或 `bypassPermissions`，`destination: "session"` 仅将其应用于当前会话。

432 432

433<Note>433<Note>

434 `bypassPermissions` 仅在会话已启动时应用，具有绕过模式可用：`--dangerously-skip-permissions`、`--permission-mode bypassPermissions`、`--allow-dangerously-skip-permissions` 或 `permissions.defaultMode: "bypassPermissions"` 在设置中，且未被 [`permissions.disableBypassPermissionsMode`](/zh-CN/permissions#managed-settings) 禁用。它永远不会作为 `defaultMode` 持久化。434 `bypassPermissions` 仅在会话已启动时应用，具有绕过模式可用：`--dangerously-skip-permissions`、`--permission-mode bypassPermissions`、`--allow-dangerously-skip-permissions` 或 `permissions.defaultMode: "bypassPermissions"` 在设置中，且未被 [`permissions.disableBypassPermissionsMode`](/docs/zh-CN/permissions#managed-settings) 禁用。它永远不会作为 `defaultMode` 持久化。

435</Note>435</Note>

436 436

437要将会话切换到 `acceptEdits`，你的 hook 将此 JSON 写入 stdout：437要将会话切换到 `acceptEdits`，你的 hook 将此 JSON 写入 stdout：

450}450}

451```451```

452 452

453保持匹配器尽可能狭窄。匹配 `.*` 或留下匹配器为空会自动批准每个权限提示，包括文件写入和 shell 命令。有关完整的决策字段集，请参阅 [PermissionRequest 参考](/zh-CN/hooks#permissionrequest-decision-control)。453保持匹配器尽可能狭窄。匹配 `.*` 或留下匹配器为空会自动批准每个权限提示，包括文件写入和 shell 命令。有关完整的决策字段集，请参阅 [PermissionRequest 参考](/docs/zh-CN/hooks#permissionrequest-decision-control)。

454 454

455<h2 id="how-hooks-work">455<h2 id="how-hooks-work">

456 Hooks 如何工作456 Hooks 如何工作

482| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |482| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

484| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |484| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

486| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |486| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |

494每个 hook 都有一个 `type` 来确定它如何运行。大多数 hooks 使用 `"type": "command"`，它运行 shell 命令。还有四种其他类型可用：494每个 hook 都有一个 `type` 来确定它如何运行。大多数 hooks 使用 `"type": "command"`，它运行 shell 命令。还有四种其他类型可用：

495 495

496* `"type": "http"`：将事件数据 POST 到 URL。请参阅 [HTTP hooks](#http-hooks)。496* `"type": "http"`：将事件数据 POST 到 URL。请参阅 [HTTP hooks](#http-hooks)。

497* `"type": "mcp_tool"`：在已连接的 MCP 服务器上调用工具。请参阅 [MCP tool hooks](/zh-CN/hooks#mcp-tool-hook-fields)。497* `"type": "mcp_tool"`：在已连接的 MCP 服务器上调用工具。请参阅 [MCP tool hooks](/docs/zh-CN/hooks#mcp-tool-hook-fields)。

498* `"type": "prompt"`：单轮 LLM 评估。请参阅 [Prompt-based hooks](#prompt-based-hooks)。498* `"type": "prompt"`：单轮 LLM 评估。请参阅 [Prompt-based hooks](#prompt-based-hooks)。

499* `"type": "agent"`：具有工具访问权限的多轮验证。Agent hooks 是实验性的，可能会改变。请参阅 [Agent-based hooks](#agent-based-hooks)。499* `"type": "agent"`：具有工具访问权限的多轮验证。Agent hooks 是实验性的，可能会改变。请参阅 [Agent-based hooks](#agent-based-hooks)。

500 500

556}556}

557```557```

558 558

559你的脚本可以解析该 JSON 并对任何这些字段进行操作。`UserPromptSubmit` hooks 获取 `prompt` 文本，`SessionStart` hooks 获取 `source`（启动、恢复、清除、压缩），等等。有关共享字段，请参阅参考中的 [常见输入字段](/zh-CN/hooks#common-input-fields)，以及每个事件的部分了解事件特定的架构。559你的脚本可以解析该 JSON 并对任何这些字段进行操作。`UserPromptSubmit` hooks 获取 `prompt` 文本，`SessionStart` hooks 获取 `source`（启动、恢复、清除、压缩），等等。有关共享字段，请参阅参考中的 [常见输入字段](/docs/zh-CN/hooks#common-input-fields)，以及每个事件的部分了解事件特定的架构。

560 560

561<h4 id="hook-output">561<h4 id="hook-output">

562 Hook 输出562 Hook 输出

579 579

580退出代码确定接下来会发生什么：580退出代码确定接下来会发生什么：

581 581

582* **退出 0**：hook 报告没有异议，操作正常进行。对于 `PreToolUse` hook，这不会批准工具调用：正常的 [权限流程](/zh-CN/permissions) 仍然适用。对于 `UserPromptSubmit`、`UserPromptExpansion` 和 `SessionStart` hooks，你写入 stdout 的任何内容都会添加到 Claude 的上下文中。582* **退出 0**：hook 报告没有异议，操作正常进行。对于 `PreToolUse` hook，这不会批准工具调用：正常的 [权限流程](/docs/zh-CN/permissions) 仍然适用。对于 `UserPromptSubmit`、`UserPromptExpansion` 和 `SessionStart` hooks，你写入 stdout 的任何内容都会添加到 Claude 的上下文中。

583* **退出 2**：操作被阻止。写入原因到 stderr，Claude 会收到它作为反馈，以便它可以调整。某些事件无法被阻止：对于 `SessionStart`、`Setup`、`Notification` 和其他事件，退出 2 向用户显示 stderr，执行继续。有关每个事件的退出代码 2 行为的完整列表，请参阅 [每个事件的退出代码 2 行为](/zh-CN/hooks#exit-code-2-behavior-per-event)。583* **退出 2**：操作被阻止。写入原因到 stderr，Claude 会收到它作为反馈，以便它可以调整。某些事件无法被阻止：对于 `SessionStart`、`Setup`、`Notification` 和其他事件，退出 2 向用户显示 stderr，执行继续。有关每个事件的退出代码 2 行为的完整列表，请参阅 [每个事件的退出代码 2 行为](/docs/zh-CN/hooks#exit-code-2-behavior-per-event)。

584* **任何其他退出代码**：操作继续。成绩单显示 `<hook name> hook error` 通知，后跟 stderr 的第一行；完整的 stderr 进入 [调试日志](/zh-CN/hooks#debug-hooks)。584* **任何其他退出代码**：操作继续。成绩单显示 `<hook name> hook error` 通知，后跟 stderr 的第一行；完整的 stderr 进入 [调试日志](/docs/zh-CN/hooks#debug-hooks)。

585 585

586<h4 id="structured-json-output">586<h4 id="structured-json-output">

587 结构化 JSON 输出587 结构化 JSON 输出

607 607

608使用 `"deny"`，Claude Code 取消工具调用并将 `permissionDecisionReason` 反馈给 Claude。这些 `permissionDecision` 值特定于 `PreToolUse`：608使用 `"deny"`，Claude Code 取消工具调用并将 `permissionDecisionReason` 反馈给 Claude。这些 `permissionDecision` 值特定于 `PreToolUse`：

609 609

610* `"allow"`：跳过交互式权限提示。拒绝和询问规则，包括企业托管拒绝列表，仍然适用，以及你的组织设置为 `ask` 的 [连接器工具](/zh-CN/mcp#organization-controls-on-connector-tools) 和标记为 [`requiresUserInteraction`](/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具610* `"allow"`：跳过交互式权限提示。拒绝和询问规则，包括企业托管拒绝列表，仍然适用，以及你的组织设置为 `ask` 的 [连接器工具](/docs/zh-CN/mcp#organization-controls-on-connector-tools) 和标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具

611* `"deny"`：取消工具调用并将原因发送给 Claude611* `"deny"`：取消工具调用并将原因发送给 Claude

612* `"ask"`：照常向用户显示权限提示612* `"ask"`：照常向用户显示权限提示

613 613

614第四个值 `"defer"` 在 [非交互模式](/zh-CN/headless) 中使用 `-p` 标志时可用。它以保留的工具调用退出进程，以便 Agent SDK 包装器可以收集输入并恢复。请参阅参考中的 [延迟工具调用以供稍后使用](/zh-CN/hooks#defer-a-tool-call-for-later)。614第四个值 `"defer"` 在 [非交互模式](/docs/zh-CN/headless) 中使用 `-p` 标志时可用。它以保留的工具调用退出进程，以便 Agent SDK 包装器可以收集输入并恢复。请参阅参考中的 [延迟工具调用以供稍后使用](/docs/zh-CN/hooks#defer-a-tool-call-for-later)。

615 615

616返回 `"allow"` 跳过交互式提示但不覆盖 [权限规则](/zh-CN/permissions#manage-permissions)。如果拒绝规则与工具调用匹配，即使你的 hook 返回 `"allow"`，调用也会被阻止。如果询问规则匹配，用户仍然会被提示，以及你的组织设置为 `ask` 的 [连接器工具](/zh-CN/mcp#organization-controls-on-connector-tools) 和标记为 [`requiresUserInteraction`](/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具。这意味着来自任何设置范围的拒绝规则，包括 [托管设置](/zh-CN/settings#settings-files)，总是优先于 hook 批准。616返回 `"allow"` 跳过交互式提示但不覆盖 [权限规则](/docs/zh-CN/permissions#manage-permissions)。如果拒绝规则与工具调用匹配，即使你的 hook 返回 `"allow"`，调用也会被阻止。如果询问规则匹配，用户仍然会被提示，以及你的组织设置为 `ask` 的 [连接器工具](/docs/zh-CN/mcp#organization-controls-on-connector-tools) 和标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具。这意味着来自任何设置范围的拒绝规则，包括 [托管设置](/docs/zh-CN/settings#settings-files)，总是优先于 hook 批准。

617 617

618其他事件使用不同的决策模式。例如，`PostToolUse` 和 `Stop` hooks 使用顶级 `decision: "block"` 字段，而 `PermissionRequest` 使用 `hookSpecificOutput.decision.behavior`。有关按事件的完整分解，请参阅参考中的 [摘要表](/zh-CN/hooks#decision-control)。618其他事件使用不同的决策模式。例如，`PostToolUse` 和 `Stop` hooks 使用顶级 `decision: "block"` 字段，而 `PermissionRequest` 使用 `hookSpecificOutput.decision.behavior`。有关按事件的完整分解，请参阅参考中的 [摘要表](/docs/zh-CN/hooks#decision-control)。

619 619

620对于 `UserPromptSubmit` hooks，改用 `hookSpecificOutput.additionalContext` 将文本注入到 Claude 的上下文中。将 `additionalContext` 嵌套在 `hookSpecificOutput` 内；如果你将其放在 JSON 的顶级，Claude Code 会默默忽略它。例如，此输出将当前分支状态添加到每个提示：620对于 `UserPromptSubmit` hooks，改用 `hookSpecificOutput.additionalContext` 将文本注入到 Claude 的上下文中。将 `additionalContext` 嵌套在 `hookSpecificOutput` 内；如果你将其放在 JSON 的顶级，Claude Code 会默默忽略它。例如，此输出将当前分支状态添加到每个提示：

621 621

628}628}

629```629```

630 630

631有关完整的输出形状，包括阻止提示和设置会话标题，请参阅 [UserPromptSubmit 决策控制](/zh-CN/hooks#userpromptsubmit-decision-control)。631有关完整的输出形状，包括阻止提示和设置会话标题，请参阅 [UserPromptSubmit 决策控制](/docs/zh-CN/hooks#userpromptsubmit-decision-control)。

632 632

633基于 prompt 的 hooks（`type: "prompt"`）处理输出的方式不同：请参阅 [Prompt-based hooks](#prompt-based-hooks)。633基于 prompt 的 hooks（`type: "prompt"`）处理输出的方式不同：请参阅 [Prompt-based hooks](#prompt-based-hooks)。

634 634

653}653}

654```654```

655 655

656`"Edit|Write"` 匹配器仅在 Claude 使用 `Edit` 或 `Write` 工具时触发，而不是在它使用 `Bash`、`Read` 或任何其他工具时触发。{/* min-version: 2.1.191 */}在 Claude Code v2.1.191 或更高版本上，逗号以相同的方式分隔替代项，所以 `"Edit, Write"` 是等效的。请参阅 [匹配器模式](/zh-CN/hooks#matcher-patterns) 了解纯名称和正则表达式如何被评估。656`"Edit|Write"` 匹配器仅在 Claude 使用 `Edit` 或 `Write` 工具时触发，而不是在它使用 `Bash`、`Read` 或任何其他工具时触发。{/* min-version: 2.1.191 */}在 Claude Code v2.1.191 或更高版本上，逗号以相同的方式分隔替代项，所以 `"Edit, Write"` 是等效的。请参阅 [匹配器模式](/docs/zh-CN/hooks#matcher-patterns) 了解纯名称和正则表达式如何被评估。

657 657

658<Note>658<Note>

659 Claude 也可以通过 `Bash` 工具运行 shell 命令来创建或修改文件。如果你的 hook 必须看到每个文件更改，例如用于合规性扫描或审计日志，添加一个 [`Stop`](/zh-CN/hooks#stop) hook，它每轮扫描一次工作树。为了获得每次调用的覆盖，也匹配 `Bash` 并让你的脚本使用 `git status --porcelain` 列出修改和未跟踪的文件。659 Claude 也可以通过 `Bash` 工具运行 shell 命令来创建或修改文件。如果你的 hook 必须看到每个文件更改，例如用于合规性扫描或审计日志，添加一个 [`Stop`](/docs/zh-CN/hooks#stop) hook，它每轮扫描一次工作树。为了获得每次调用的覆盖，也匹配 `Bash` 并让你的脚本使用 `git status --porcelain` 列出修改和未跟踪的文件。

660</Note>660</Note>

661 661

662每个事件类型在特定字段上匹配：662每个事件类型在特定字段上匹配：

681| `UserPromptSubmit`、`PostToolBatch`、`Stop`、`TeammateIdle`、`TaskCreated`、`TaskCompleted`、`WorktreeCreate`、`WorktreeRemove`、`CwdChanged`、`MessageDisplay` | 不支持匹配器 | 始终在每次出现时触发 |681| `UserPromptSubmit`、`PostToolBatch`、`Stop`、`TeammateIdle`、`TaskCreated`、`TaskCompleted`、`WorktreeCreate`、`WorktreeRemove`、`CwdChanged`、`MessageDisplay` | 不支持匹配器 | 始终在每次出现时触发 |

682 682

706 </Tab>706 </Tab>

707 707

708 <Tab title="匹配 MCP 工具">708 <Tab title="匹配 MCP 工具">

709 MCP 工具使用与内置工具不同的命名约定：`mcp__<server>__<tool>`，其中 `<server>` 是 MCP 服务器名称，`<tool>` 是它提供的工具。例如，`mcp__github__search_repositories` 或 `mcp__filesystem__read_file`。使用正则表达式匹配器来针对来自特定服务器的所有工具，或使用 `mcp__.*__write.*` 之类的模式跨服务器匹配。有关完整的示例列表，请参阅参考中的 [匹配 MCP 工具](/zh-CN/hooks#match-mcp-tools)。709 MCP 工具使用与内置工具不同的命名约定：`mcp__<server>__<tool>`，其中 `<server>` 是 MCP 服务器名称，`<tool>` 是它提供的工具。例如，`mcp__github__search_repositories` 或 `mcp__filesystem__read_file`。使用正则表达式匹配器来针对来自特定服务器的所有工具，或使用 `mcp__.*__write.*` 之类的模式跨服务器匹配。有关完整的示例列表，请参阅参考中的 [匹配 MCP 工具](/docs/zh-CN/hooks#match-mcp-tools)。

710 710

711 下面的命令使用 `jq` 从 hook 的 JSON 输入中提取工具名称，并将其写入 stderr。将其写入 stderr 保持 stdout 清洁以用于 JSON 输出，并将消息发送到 [调试日志](/zh-CN/hooks#debug-hooks)：711 下面的命令使用 `jq` 从 hook 的 JSON 输入中提取工具名称，并将其写入 stderr。将其写入 stderr 保持 stdout 清洁以用于 JSON 输出，并将消息发送到 [调试日志](/docs/zh-CN/hooks#debug-hooks)：

712 712

713 ```json theme={null}713 ```json theme={null}

714 {714 {

752 </Tab>752 </Tab>

753</Tabs>753</Tabs>

754 754

755有关完整的匹配器语法，请参阅 [Hooks 参考](/zh-CN/hooks#configuration)。755有关完整的匹配器语法，请参阅 [Hooks 参考](/docs/zh-CN/hooks#configuration)。

756 756

757<h4 id="filter-by-tool-name-and-arguments-with-the-if-field">757<h4 id="filter-by-tool-name-and-arguments-with-the-if-field">

758 使用 `if` 字段按工具名称和参数过滤758 使用 `if` 字段按工具名称和参数过滤

759</h4>759</h4>

760 760

761`if` 字段使用 [权限规则语法](/zh-CN/permissions) 按工具名称和参数一起过滤 hooks，因此 hook 进程仅在工具调用匹配时生成。这超越了 `matcher`，它仅在工具名称级别按组过滤。761`if` 字段使用 [权限规则语法](/docs/zh-CN/permissions) 按工具名称和参数一起过滤 hooks，因此 hook 进程仅在工具调用匹配时生成。这超越了 `matcher`，它仅在工具名称级别按组过滤。

762 762

763例如，这个配置仅在 Claude 使用 `git` 命令而不是所有 Bash 命令时运行 hook：763例如，这个配置仅在 Claude 使用 `git` 命令而不是所有 Bash 命令时运行 hook：

764 764

793 793

794当 Bash 命令无法解析时，过滤器也会失败开放，无论如何都会运行你的 hook。因为过滤器是尽力而为的，使用 [权限系统](/zh-CN/permissions) 而不是 hook 来强制执行硬允许或拒绝。794当 Bash 命令无法解析时，过滤器也会失败开放，无论如何都会运行你的 hook。因为过滤器是尽力而为的，使用 [权限系统](/docs/zh-CN/permissions) 而不是 hook 来强制执行硬允许或拒绝。

795 795

796`if` 字段接受与权限规则相同的模式：`"Bash(git *)"`、`"Edit(*.ts)"` 等。要匹配多个工具名称，使用单独的处理程序，每个都有自己的 `if` 值，或在 `matcher` 级别匹配，其中支持管道交替。796`if` 字段接受与权限规则相同的模式：`"Bash(git *)"`、`"Edit(*.ts)"` 等。要匹配多个工具名称，使用单独的处理程序，每个都有自己的 `if` 值，或在 `matcher` 级别匹配，其中支持管道交替。

797 797

814 814

815在 Claude Code 中运行 [`/hooks`](/zh-CN/hooks#the-%2Fhooks-menu) 以浏览所有按事件分组的配置 hooks。815在 Claude Code 中运行 [`/hooks`](/docs/zh-CN/hooks#the-%2Fhooks-menu) 以浏览所有按事件分组的配置 hooks。

816 816

817要禁用 hooks，在设置文件中设置 `"disableAllHooks": true`。托管设置中配置的 Hooks 仍然运行，除非 `disableAllHooks` 也在那里设置。817要禁用 hooks，在设置文件中设置 `"disableAllHooks": true`。托管设置中配置的 Hooks 仍然运行，除非 `disableAllHooks` 也在那里设置。

818 818

851}851}

852```852```

853 853

854有关完整的配置选项，请参阅参考中的 [基于提示的 hooks](/zh-CN/hooks#prompt-based-hooks)。854有关完整的配置选项，请参阅参考中的 [基于提示的 hooks](/docs/zh-CN/hooks#prompt-based-hooks)。

855 855

856<h2 id="agent-based-hooks">856<h2 id="agent-based-hooks">

857 基于代理的 hooks857 基于代理的 hooks

858</h2>858</h2>

859 859

860<Warning>860<Warning>

861 代理 hooks 是实验性的。行为和配置可能在未来版本中改变。对于生产工作流，更倾向于 [命令 hooks](/zh-CN/hooks#command-hook-fields)。861 代理 hooks 是实验性的。行为和配置可能在未来版本中改变。对于生产工作流，更倾向于 [命令 hooks](/docs/zh-CN/hooks#command-hook-fields)。

862</Warning>862</Warning>

863 863

864当验证需要检查文件或运行命令时，使用 `type: "agent"` hooks。与只进行单个 LLM 调用的提示 hooks 不同，代理 hooks 生成一个 subagent，它可以读取文件、搜索代码和使用其他工具来验证条件，然后返回决策。864当验证需要检查文件或运行命令时，使用 `type: "agent"` hooks。与只进行单个 LLM 调用的提示 hooks 不同，代理 hooks 生成一个 subagent，它可以读取文件、搜索代码和使用其他工具来验证条件，然后返回决策。

887 887

888当 hook 输入数据本身足以做出决策时使用提示 hooks。当你需要根据代码库的实际状态验证某些内容时使用代理 hooks。888当 hook 输入数据本身足以做出决策时使用提示 hooks。当你需要根据代码库的实际状态验证某些内容时使用代理 hooks。

889 889

890有关完整的配置选项，请参阅参考中的 [基于代理的 hooks](/zh-CN/hooks#agent-based-hooks)。890有关完整的配置选项，请参阅参考中的 [基于代理的 hooks](/docs/zh-CN/hooks#agent-based-hooks)。

891 891

892<h2 id="http-hooks">892<h2 id="http-hooks">

893 HTTP hooks893 HTTP hooks

920}920}

921```921```

922 922

923端点应使用与命令 hooks 相同的 [输出格式](/zh-CN/hooks#json-output) 返回 JSON 响应体。要阻止工具调用，返回 2xx 响应，包含适当的 `hookSpecificOutput` 字段。HTTP 状态代码本身无法阻止操作。923端点应使用与命令 hooks 相同的 [输出格式](/docs/zh-CN/hooks#json-output) 返回 JSON 响应体。要阻止工具调用，返回 2xx 响应，包含适当的 `hookSpecificOutput` 字段。HTTP 状态代码本身无法阻止操作。

924 924

925标头值支持使用 `$VAR_NAME` 或 `${VAR_NAME}` 语法的环境变量插值。仅解析 `allowedEnvVars` 数组中列出的变量；所有其他 `$VAR` 引用保持为空。925标头值支持使用 `$VAR_NAME` 或 `${VAR_NAME}` 语法的环境变量插值。仅解析 `allowedEnvVars` 数组中列出的变量；所有其他 `$VAR` 引用保持为空。

926 926

927有关完整的配置选项和响应处理，请参阅参考中的 [HTTP hooks](/zh-CN/hooks#http-hook-fields)。927有关完整的配置选项和响应处理，请参阅参考中的 [HTTP hooks](/docs/zh-CN/hooks#http-hook-fields)。

928 928

929<h2 id="limitations-and-troubleshooting">929<h2 id="limitations-and-troubleshooting">

930 限制和故障排除930 限制和故障排除

942 * `prompt`：30 秒。942 * `prompt`：30 秒。

943 * `agent`：60 秒。943 * `agent`：60 秒。

944* `PostToolUse` hooks 无法撤销操作，因为工具已经执行。944* `PostToolUse` hooks 无法撤销操作，因为工具已经执行。

945* `PermissionRequest` hooks 不在 [非交互模式](/zh-CN/headless)（带 `-p` 标志）中触发。对于自动化权限决策，使用 `PreToolUse` hooks。945* `PermissionRequest` hooks 不在 [非交互模式](/docs/zh-CN/headless)（带 `-p` 标志）中触发。对于自动化权限决策，使用 `PreToolUse` hooks。

946* `Stop` hooks 在 Claude 完成响应时触发，而不仅仅在任务完成时。它们不在用户中断时触发。API 错误触发 [StopFailure](/zh-CN/hooks#stopfailure) 代替。946* `Stop` hooks 在 Claude 完成响应时触发，而不仅仅在任务完成时。它们不在用户中断时触发。API 错误触发 [StopFailure](/docs/zh-CN/hooks#stopfailure) 代替。

947* 当多个 `PreToolUse` hooks 返回 [`updatedInput`](/zh-CN/hooks#pretooluse) 来重写工具的参数时，最后完成的获胜。由于 hooks 并行运行，顺序是非确定性的。避免有多个 hook 修改同一工具的输入。947* 当多个 `PreToolUse` hooks 返回 [`updatedInput`](/docs/zh-CN/hooks#pretooluse) 来重写工具的参数时，最后完成的获胜。由于 hooks 并行运行，顺序是非确定性的。避免有多个 hook 修改同一工具的输入。

948 948

949<h3 id="hooks-and-permission-modes">949<h3 id="hooks-and-permission-modes">

950 Hooks 和权限模式950 Hooks 和权限模式

952 952

953`PreToolUse` hooks 在任何权限模式检查之前触发。返回 `permissionDecision: "deny"` 的 hook 会阻止工具，即使在 `bypassPermissions` 模式或使用 `--dangerously-skip-permissions` 时也是如此。这让你强制执行用户无法通过更改其权限模式来绕过的策略。953`PreToolUse` hooks 在任何权限模式检查之前触发。返回 `permissionDecision: "deny"` 的 hook 会阻止工具，即使在 `bypassPermissions` 模式或使用 `--dangerously-skip-permissions` 时也是如此。这让你强制执行用户无法通过更改其权限模式来绕过的策略。

954 954

955反面不成立：返回 `"allow"` 的 hook 不会绕过来自设置的拒绝规则，它也无法抑制你的组织设置为 `ask` 的连接器工具的提示 [](/zh-CN/mcp#organization-controls-on-connector-tools) 或标记为 [`requiresUserInteraction`](/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具。Hooks 可以收紧限制，但不能放松它们超过权限规则允许的范围。955反面不成立：返回 `"allow"` 的 hook 不会绕过来自设置的拒绝规则，它也无法抑制你的组织设置为 `ask` 的连接器工具的提示 [](/docs/zh-CN/mcp#organization-controls-on-connector-tools) 或标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具。Hooks 可以收紧限制，但不能放松它们超过权限规则允许的范围。

956 956

957<h3 id="hook-not-firing">957<h3 id="hook-not-firing">

958 Hook 未触发958 Hook 未触发

976 echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh976 echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh

977 echo $? # 检查退出代码977 echo $? # 检查退出代码

978 ```978 ```

979* 如果你看到"command not found"，使用绝对路径或 `${CLAUDE_PROJECT_DIR}` 来引用脚本。为了完全避免 shell 引用，添加 `"args": []` 来切换到 [exec 形式](/zh-CN/hooks#exec-form-and-shell-form)，它直接生成脚本而不使用 shell979* 如果你看到"command not found"，使用绝对路径或 `${CLAUDE_PROJECT_DIR}` 来引用脚本。为了完全避免 shell 引用，添加 `"args": []` 来切换到 [exec 形式](/docs/zh-CN/hooks#exec-form-and-shell-form)，它直接生成脚本而不使用 shell

980* 如果你看到"jq: command not found"，安装 `jq` 或使用 Python/Node.js 进行 JSON 解析980* 如果你看到"jq: command not found"，安装 `jq` 或使用 Python/Node.js 进行 JSON 解析

981* 如果脚本根本没有运行，使其可执行：`chmod +x ./my-hook.sh`981* 如果脚本根本没有运行，使其可执行：`chmod +x ./my-hook.sh`

982 982

1007# ... 你的 hook 逻辑的其余部分1007# ... 你的 hook 逻辑的其余部分

1008```1008```

1009 1009

1010如果你的 hook 合理地需要超过八次迭代才能收敛，使用 [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/zh-CN/env-vars) 提高上限。1010如果你的 hook 合理地需要超过八次迭代才能收敛，使用 [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/zh-CN/env-vars) 提高上限。

1011 1011

1012<h3 id="json-validation-failed">1012<h3 id="json-validation-failed">

1013 JSON 验证失败1013 JSON 验证失败

1045 了解更多1045 了解更多

1046</h2>1046</h2>

1047 1047

1048* [Hooks 参考](/zh-CN/hooks)：完整的事件架构、JSON 输出格式、异步 hooks 和 MCP 工具 hooks1048* [Hooks 参考](/docs/zh-CN/hooks)：完整的事件架构、JSON 输出格式、异步 hooks 和 MCP 工具 hooks

1049* [安全考虑](/zh-CN/hooks#security-considerations)：在共享或生产环境中部署 hooks 之前查看1049* [安全考虑](/docs/zh-CN/hooks#security-considerations)：在共享或生产环境中部署 hooks 之前查看

1050* [Bash 命令验证器示例](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py)：完整的参考实现1050* [Bash 命令验证器示例](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py)：完整的参考实现

plugins-reference.md +45 −45

Details

7> Claude Code 插件系统的完整技术参考，包括架构、CLI 命令和组件规范。7> Claude Code 插件系统的完整技术参考，包括架构、CLI 命令和组件规范。

8 8

9<Tip>9<Tip>

10 想要安装插件？请参阅[发现和安装插件](/zh-CN/discover-plugins)。如需创建插件，请参阅[Plugins](/zh-CN/plugins)。如需分发插件，请参阅[Plugin marketplaces](/zh-CN/plugin-marketplaces)。10 想要安装插件？请参阅[发现和安装插件](/docs/zh-CN/discover-plugins)。如需创建插件，请参阅[Plugins](/docs/zh-CN/plugins)。如需分发插件，请参阅[Plugin marketplaces](/docs/zh-CN/plugin-marketplaces)。

11</Tip>11</Tip>

12 12

13本参考提供了 Claude Code 插件系统的完整技术规范，包括组件架构、CLI 命令和开发工具。13本参考提供了 Claude Code 插件系统的完整技术规范，包括组件架构、CLI 命令和开发工具。

48 48

49如果插件没有 `skills/` 目录且没有 `skills` manifest 字段，则插件根目录中的 `SKILL.md` 会作为单个 skill 加载。设置 frontmatter `name` 字段以控制 skill 的调用名称。如果没有设置，Claude Code 会回退到安装目录名称，对于从市场安装的插件，这是一个在每次更新时都会改变的版本字符串。对于提供多个 skill 的插件，请使用上面所示的 `skills/` 目录布局。49如果插件没有 `skills/` 目录且没有 `skills` manifest 字段，则插件根目录中的 `SKILL.md` 会作为单个 skill 加载。设置 frontmatter `name` 字段以控制 skill 的调用名称。如果没有设置，Claude Code 会回退到安装目录名称，对于从市场安装的插件，这是一个在每次更新时都会改变的版本字符串。对于提供多个 skill 的插件，请使用上面所示的 `skills/` 目录布局。

50 50

~~51有关完整详情，请参阅 [Skills](/zh-CN/skills)。~~51有关完整详情，请参阅 [Skills](/docs/zh-CN/skills)。

52 52

53<h3 id="agents">53<h3 id="agents">

54 Agents54 Agents

79 79

80**集成点**：80**集成点**：

81 81

~~82* Agents 在 [@-mention 类型提前](/zh-CN/sub-agents#invoke-subagents-explicitly) 中显示，使用其作用域名称，例如 `my-plugin:code-reviewer`，一旦启用插件~~82* Agents 在 [@-mention 类型提前](/docs/zh-CN/sub-agents#invoke-subagents-explicitly) 中显示，使用其作用域名称，例如 `my-plugin:code-reviewer`，一旦启用插件

83* Claude 可以根据任务上下文自动调用 agents83* Claude 可以根据任务上下文自动调用 agents

84* Agents 可以由用户手动调用84* Agents 可以由用户手动调用

85* Plugin agents 与内置 Claude agents 一起工作85* Plugin agents 与内置 Claude agents 一起工作

86 86

~~87有关完整详情，请参阅 [Subagents](/zh-CN/sub-agents)。~~87有关完整详情，请参阅 [Subagents](/docs/zh-CN/sub-agents)。

88 88

89<h3 id="hooks">89<h3 id="hooks">

90 Hooks90 Hooks

116}116}

117```117```

118 118

119Plugin hooks 响应与 [用户定义的 hooks](/zh-CN/hooks) 相同的生命周期事件：119Plugin hooks 响应与 [用户定义的 hooks](/docs/zh-CN/hooks) 相同的生命周期事件：

120 120

121| Event | When it fires |121| Event | When it fires |

122| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |122| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

142| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |142| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

144| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |144| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

146| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |146| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |

155 155

156* `command`：执行 shell 命令或脚本156* `command`：执行 shell 命令或脚本

157* `http`：将事件 JSON 作为 POST 请求发送到 URL157* `http`：将事件 JSON 作为 POST 请求发送到 URL

158* `mcp_tool`：在配置的 [MCP server](/zh-CN/mcp) 上调用工具158* `mcp_tool`：在配置的 [MCP server](/docs/zh-CN/mcp) 上调用工具

159* `prompt`：使用 LLM 评估提示（使用 `$ARGUMENTS` 占位符表示上下文）159* `prompt`：使用 LLM 评估提示（使用 `$ARGUMENTS` 占位符表示上下文）

160* `agent`：运行具有工具的 agentic 验证器以完成复杂验证任务160* `agent`：运行具有工具的 agentic 验证器以完成复杂验证任务

161 161

162针对插件自己的 [捆绑 MCP server](#mcp-servers) 的 Hooks 必须使用其作用域名称。工具匹配器和 `if` 字段采用作用域工具名称 `mcp__plugin_<plugin-name>_<server-name>__<tool>`，而 `mcp_tool` hook 的 `server` 字段采用 `plugin:<plugin-name>:<server-name>`。针对裸服务器密钥编写的匹配器永远不会触发。请参阅 [匹配 MCP 工具](/zh-CN/hooks#match-mcp-tools) 和 [Plugin 提供的 MCP servers](/zh-CN/mcp#plugin-provided-mcp-servers)。162针对插件自己的 [捆绑 MCP server](#mcp-servers) 的 Hooks 必须使用其作用域名称。工具匹配器和 `if` 字段采用作用域工具名称 `mcp__plugin_<plugin-name>_<server-name>__<tool>`，而 `mcp_tool` hook 的 `server` 字段采用 `plugin:<plugin-name>:<server-name>`。针对裸服务器密钥编写的匹配器永远不会触发。请参阅 [匹配 MCP 工具](/docs/zh-CN/hooks#match-mcp-tools) 和 [Plugin 提供的 MCP servers](/docs/zh-CN/mcp#plugin-provided-mcp-servers)。

163 163

164<h3 id="mcp-servers">164<h3 id="mcp-servers">

165 MCP servers165 MCP servers

300 300

301Plugins 可以声明后台 monitors，Claude Code 在 plugin 激活时自动启动。每个 monitor 为会话的生命周期运行一个 shell 命令，并将每个 stdout 行作为通知传递给 Claude，以便 Claude 可以对日志条目、状态更改或轮询事件做出反应，而无需被要求启动监视本身。301Plugins 可以声明后台 monitors，Claude Code 在 plugin 激活时自动启动。每个 monitor 为会话的生命周期运行一个 shell 命令，并将每个 stdout 行作为通知传递给 Claude，以便 Claude 可以对日志条目、状态更改或轮询事件做出反应，而无需被要求启动监视本身。

302 302

303Plugin monitors 使用与 [Monitor tool](/zh-CN/tools-reference#monitor-tool) 相同的机制，并共享其可用性约束。它们仅在交互式 CLI 会话中运行，在与 [hooks](#hooks) 相同的信任级别上无沙箱运行，并在 Monitor tool 不可用的主机上跳过。303Plugin monitors 使用与 [Monitor tool](/docs/zh-CN/tools-reference#monitor-tool) 相同的机制，并共享其可用性约束。它们仅在交互式 CLI 会话中运行，在与 [hooks](#hooks) 相同的信任级别上无沙箱运行，并在 Monitor tool 不可用的主机上跳过。

304 304

305**位置**：插件根目录中的 `monitors/monitors.json`，或在 plugin.json 中内联305**位置**：插件根目录中的 `monitors/monitors.json`，或在 plugin.json 中内联

306 306

342 342

343`command` 值支持 [路径替换](#environment-variables) `${CLAUDE_PLUGIN_ROOT}`、`${CLAUDE_PLUGIN_DATA}` 和 `${CLAUDE_PROJECT_DIR}`，加上环境中的任何 `${ENV_VAR}`。如果脚本需要从插件自己的目录运行，请在命令前加上 `cd "${CLAUDE_PLUGIN_ROOT}" && `。343`command` 值支持 [路径替换](#environment-variables) `${CLAUDE_PLUGIN_ROOT}`、`${CLAUDE_PLUGIN_DATA}` 和 `${CLAUDE_PROJECT_DIR}`，加上环境中的任何 `${ENV_VAR}`。如果脚本需要从插件自己的目录运行，请在命令前加上 `cd "${CLAUDE_PLUGIN_ROOT}" && `。

344 344

345monitor `command` 不能引用 [`${user_config.*}`](#user-configuration) 值。该命令通过 shell 运行，因此 Claude Code 会拒绝该 monitor 并显示 [错误](/zh-CN/errors#plugin-command-references-user-config)，而不是替换该值。Monitor 进程不会接收 `CLAUDE_PLUGIN_OPTION_<KEY>` 环境变量，因此让 monitor 脚本从它拥有的配置文件中读取该值。在 v2.1.207 之前，monitor 命令替换了 `${user_config.*}` 值。345monitor `command` 不能引用 [`${user_config.*}`](#user-configuration) 值。该命令通过 shell 运行，因此 Claude Code 会拒绝该 monitor 并显示 [错误](/docs/zh-CN/errors#plugin-command-references-user-config)，而不是替换该值。Monitor 进程不会接收 `CLAUDE_PLUGIN_OPTION_<KEY>` 环境变量，因此让 monitor 脚本从它拥有的配置文件中读取该值。在 v2.1.207 之前，monitor 命令替换了 `${user_config.*}` 值。

346 346

347在会话中途禁用插件不会停止已在运行的 monitors。它们在会话结束时停止。347在会话中途禁用插件不会停止已在运行的 monitors。它们在会话结束时停止。

348 348

383 383

384Plugins 使用与其他 Claude Code 配置相同的范围系统。有关安装说明和范围标志，请参阅[安装 plugins](/zh-CN/discover-plugins#install-plugins)。有关范围的完整说明，请参阅[Configuration scopes](/zh-CN/settings#configuration-scopes)。384Plugins 使用与其他 Claude Code 配置相同的范围系统。有关安装说明和范围标志，请参阅[安装 plugins](/docs/zh-CN/discover-plugins#install-plugins)。有关范围的完整说明，请参阅[Configuration scopes](/docs/zh-CN/settings#configuration-scopes)。

385 385

386***386***

387 387

395 395

396| 您拥有的 | 它是什么 |396| 您拥有的 | 它是什么 |

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

401 401

406| Skills 目录 | 范围 | 加载 |406| Skills 目录 | 范围 | 加载 |

407| :---------------------- | :- | :---------------------------------------------- |407| :---------------------- | :- | :---------------------------------------------- |

408| `~/.claude/skills/` | 个人 | 在每个项目中，因为位置仅属于您 |408| `~/.claude/skills/` | 个人 | 在每个项目中，因为位置仅属于您 |

409| `<cwd>/.claude/skills/` | 项目 | 仅在您接受该文件夹的工作区 [trust dialog](/zh-CN/settings) 后 |409| `<cwd>/.claude/skills/` | 项目 | 仅在您接受该文件夹的工作区 [trust dialog](/docs/zh-CN/settings) 后 |

410 410

411项目范围的 plugin 被检入存储库，并到达克隆它的每个协作者。因为该内容来自存储库而不是来自您，它仅在与 `.claude/settings.json` 相同的信任门后加载，并且运行代码的组件受到进一步限制：411项目范围的 plugin 被检入存储库，并到达克隆它的每个协作者。因为该内容来自存储库而不是来自您，它仅在与 `.claude/settings.json` 相同的信任门后加载，并且运行代码的组件受到进一步限制：

412 412

413* 它声明的 MCP servers 通过与项目 `.mcp.json` 相同的 [per-server approval](/zh-CN/mcp)413* 它声明的 MCP servers 通过与项目 `.mcp.json` 相同的 [per-server approval](/docs/zh-CN/mcp)

414* LSP servers 仅在您信任工作区后启动414* LSP servers 仅在您信任工作区后启动

415* [Background monitors](#monitors) 不加载415* [Background monitors](#monitors) 不加载

416 416

417个人范围的 plugins 没有这些限制。417个人范围的 plugins 没有这些限制。

418 418

419<Warning>419<Warning>

420 项目范围的 `@skills-dir` plugins 仅从启动 Claude Code 的目录的 `.claude/skills/` 加载。它们不会 [walk up to the repository root](/zh-CN/skills#automatic-discovery-from-parent-and-nested-directories) 的方式与普通 skills 和 commands 相同，因此从子目录启动会错过位于存储库根目录的 plugin。从存储库根目录启动，或在更改目录后运行 `/reload-plugins`。420 项目范围的 `@skills-dir` plugins 仅从启动 Claude Code 的目录的 `.claude/skills/` 加载。它们不会 [walk up to the repository root](/docs/zh-CN/skills#automatic-discovery-from-parent-and-nested-directories) 的方式与普通 skills 和 commands 相同，因此从子目录启动会错过位于存储库根目录的 plugin。从存储库根目录启动，或在更改目录后运行 `/reload-plugins`。

421</Warning>421</Warning>

422 422

423<h3 id="edit-reload-and-disable-a-skills-directory-plugin">423<h3 id="edit-reload-and-disable-a-skills-directory-plugin">

424 编辑、重新加载和禁用 skills 目录 plugin424 编辑、重新加载和禁用 skills 目录 plugin

425</h3>425</h3>

426 426

427您对 skill 的 `SKILL.md` 所做的更改在当前会话中立即生效。对 plugin 的其他组件（如 `hooks/`、`.mcp.json`、`agents/` 和 `output-styles/`）的更改则不会。运行 `/reload-plugins` 或重启 Claude Code 以获取这些更改。请参阅 [Live change detection](/zh-CN/skills#live-change-detection)。427您对 skill 的 `SKILL.md` 所做的更改在当前会话中立即生效。对 plugin 的其他组件（如 `hooks/`、`.mcp.json`、`agents/` 和 `output-styles/`）的更改则不会。运行 `/reload-plugins` 或重启 Claude Code 以获取这些更改。请参阅 [Live change detection](/docs/zh-CN/skills#live-change-detection)。

428 428

429要停止加载 skills 目录 plugin，请删除其文件夹或按名称禁用它。没有 `uninstall` 步骤，因为没有从市场安装任何东西。429要停止加载 skills 目录 plugin，请删除其文件夹或按名称禁用它。没有 `uninstall` 步骤，因为没有从市场安装任何东西。

430 430

487 487

488| 字段 | 类型 | 描述 | 示例 |488| 字段 | 类型 | 描述 | 示例 |

489| :----- | :----- | :------------------------------------------------------------------------------------------------------------------------------------ | :------------------- |489| :----- | :----- | :------------------------------------------------------------------------------------------------------------------------------------ | :------------------- |

491 491

492此名称用于命名空间组件。例如，在 UI 中，名为 `plugin-dev` 的 plugin 的 agent `agent-creator` 将显示为 `plugin-dev:agent-creator`。492此名称用于命名空间组件。例如，在 UI 中，名为 `plugin-dev` 的 plugin 的 agent `agent-creator` 将显示为 `plugin-dev:agent-creator`。

493 493

533`defaultEnabled` 是当没有其他东西决定 plugin 状态时的后备。两件事优先于它：533`defaultEnabled` 是当没有其他东西决定 plugin 状态时的后备。两件事优先于它：

534 534

535* **用户的设置**：任何设置范围中 `enabledPlugins` 中的 plugin 条目。一旦写入，它在 plugin 更新和重新安装中持续，因此在后续版本中更改 `defaultEnabled` 不会翻转现有用户。535* **用户的设置**：任何设置范围中 `enabledPlugins` 中的 plugin 条目。一旦写入，它在 plugin 更新和重新安装中持续，因此在后续版本中更改 `defaultEnabled` 不会翻转现有用户。

536* **依赖项要求**：当 plugin 被另一个活跃的 plugin 需要时，Claude Code 在安装或启用时为其写入 `true`。这给了它一个显式设置，所以它自己的默认值不再适用。请参阅[启用或禁用具有依赖项的 plugin](/zh-CN/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)。536* **依赖项要求**：当 plugin 被另一个活跃的 plugin 需要时，Claude Code 在安装或启用时为其写入 `true`。这给了它一个显式设置，所以它自己的默认值不再适用。请参阅[启用或禁用具有依赖项的 plugin](/docs/zh-CN/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)。

537 537

538相同的字段可以出现在 plugin 的市场条目中，其中它优先于 `plugin.json` 中的值。请参阅[可选 plugin 字段](/zh-CN/plugin-marketplaces#optional-plugin-fields)。538相同的字段可以出现在 plugin 的市场条目中，其中它优先于 `plugin.json` 中的值。请参阅[可选 plugin 字段](/docs/zh-CN/plugin-marketplaces#optional-plugin-fields)。

539 539

540<h3 id="component-path-fields">540<h3 id="component-path-fields">

541 组件路径字段541 组件路径字段

557| `dependencies` | array | 此 plugin 需要的其他 plugins，可选择带有 semver 版本约束。请参阅[约束 plugin 依赖版本](/zh-CN/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |557| `dependencies` | array | 此 plugin 需要的其他 plugins，可选择带有 semver 版本约束。请参阅[约束 plugin 依赖版本](/docs/zh-CN/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |

558 558

559<h3 id="experimental-components">559<h3 id="experimental-components">

560 实验性组件560 实验性组件

601 601

602每个值都可用于在 MCP 和 LSP server 配置和 hook 命令中作为 `${user_config.KEY}` 进行替换。非敏感值也可以在 skill 和 agent 内容中替换。所有值都作为 `CLAUDE_PLUGIN_OPTION_<KEY>` 环境变量导出到 hook 进程和 MCP 及 LSP server 子进程，其中 `<KEY>` 是选项键的大写形式。602每个值都可用于在 MCP 和 LSP server 配置和 hook 命令中作为 `${user_config.KEY}` 进行替换。非敏感值也可以在 skill 和 agent 内容中替换。所有值都作为 `CLAUDE_PLUGIN_OPTION_<KEY>` 环境变量导出到 hook 进程和 MCP 及 LSP server 子进程，其中 `<KEY>` 是选项键的大写形式。

603 603

604在 shell 中运行的字段拒绝 `${user_config.*}`：将配置的值替换到 shell 命令中会让 shell 运行该值包含的任何内容，因此组件会失败并出现[错误](/zh-CN/errors#plugin-command-references-user-config)。每个被拒绝的字段都有一种替代方式来传递值：604在 shell 中运行的字段拒绝 `${user_config.*}`：将配置的值替换到 shell 命令中会让 shell 运行该值包含的任何内容，因此组件会失败并出现[错误](/docs/zh-CN/errors#plugin-command-references-user-config)。每个被拒绝的字段都有一种替代方式来传递值：

605 605

606| 被拒绝的字段 | 如何传递值 |606| 被拒绝的字段 | 如何传递值 |

607| :------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------- |607| :------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------- |

608| Shell 形式的 hook 命令 | 使用[执行形式](/zh-CN/hooks#exec-form-and-shell-form)与 `args`，或从 hook 的环境中读取 `CLAUDE_PLUGIN_OPTION_<KEY>` |608| Shell 形式的 hook 命令 | 使用[执行形式](/docs/zh-CN/hooks#exec-form-and-shell-form)与 `args`，或从 hook 的环境中读取 `CLAUDE_PLUGIN_OPTION_<KEY>` |

609| [Monitor](#monitors) 命令 | 从脚本中的配置文件读取值 |609| [Monitor](#monitors) 命令 | 从脚本中的配置文件读取值 |

611 611

612在 v2.1.207 之前，这些字段替换了 `${user_config.KEY}` 值；更新依赖此功能的 plugins。612在 v2.1.207 之前，这些字段替换了 `${user_config.KEY}` 值；更新依赖此功能的 plugins。

613 613

614非敏感值存储在 `settings.json` 中的 [`pluginConfigs`](/zh-CN/settings#pluginconfigs) 键下，作为 `pluginConfigs[<plugin-id>].options`。{/* min-version: 2.1.207 */}Claude Code 将键写入用户设置并从用户设置、`--settings` 标志和托管设置中读取它；项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的条目被忽略。在 v2.1.207 之前，Claude Code 也读取项目和本地设置。614非敏感值存储在 `settings.json` 中的 [`pluginConfigs`](/docs/zh-CN/settings#pluginconfigs) 键下，作为 `pluginConfigs[<plugin-id>].options`。{/* min-version: 2.1.207 */}Claude Code 将键写入用户设置并从用户设置、`--settings` 标志和托管设置中读取它；项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的条目被忽略。在 v2.1.207 之前，Claude Code 也读取项目和本地设置。

615 615

616敏感值进入 macOS Keychain，或在没有支持的钥匙链的平台上进入 `~/.claude/.credentials.json`。钥匙链存储与 OAuth 令牌共享，总限制约为 2 KB，因此请保持敏感值较小。616敏感值进入 macOS Keychain，或在没有支持的钥匙链的平台上进入 `~/.claude/.credentials.json`。钥匙链存储与 OAuth 令牌共享，总限制约为 2 KB，因此请保持敏感值较小。

617 617

653自定义路径是否替换或扩展 plugin 的默认目录取决于该字段：653自定义路径是否替换或扩展 plugin 的默认目录取决于该字段：

654 654

655* **替换默认值**：`commands`、`agents`、`outputStyles`、`experimental.themes`、`experimental.monitors`。例如，当清单指定 `commands` 时，不会扫描默认 `commands/` 目录。要保留默认值并添加更多，请明确列出它：`"commands": ["./commands/", "./extras/"]`655* **替换默认值**：`commands`、`agents`、`outputStyles`、`experimental.themes`、`experimental.monitors`。例如，当清单指定 `commands` 时，不会扫描默认 `commands/` 目录。要保留默认值并添加更多，请明确列出它：`"commands": ["./commands/", "./extras/"]`

656* **添加到默认值**：`skills`。默认 `skills/` 目录始终被扫描，`skills` 中列出的目录与其一起加载。异常：对于[其 `source` 解析为市场根的市场条目](/zh-CN/plugin-marketplaces#advanced-plugin-entries)，声明特定子目录会替换默认 `skills/` 扫描656* **添加到默认值**：`skills`。默认 `skills/` 目录始终被扫描，`skills` 中列出的目录与其一起加载。异常：对于[其 `source` 解析为市场根的市场条目](/docs/zh-CN/plugin-marketplaces#advanced-plugin-entries)，声明特定子目录会替换默认 `skills/` 扫描

657* **自己的合并规则**：[hooks](#hooks)、[MCP servers](#mcp-servers) 和 [LSP servers](#lsp-servers)。请参阅每个部分了解多个源如何组合657* **自己的合并规则**：[hooks](#hooks)、[MCP servers](#mcp-servers) 和 [LSP servers](#lsp-servers)。请参阅每个部分了解多个源如何组合

658 658

659当 plugin 同时具有默认文件夹和匹配的清单键时，Claude Code v2.1.140 及更高版本在 `claude plugin list` 和 `/plugin` 详细视图中标记被忽略的文件夹。plugin 仍然使用清单路径加载。当清单键指向默认文件夹时不显示警告，例如 `"commands": ["./commands/deploy.md"]`，因为在这种情况下文件夹被明确寻址。659当 plugin 同时具有默认文件夹和匹配的清单键时，Claude Code v2.1.140 及更高版本在 `claude plugin list` 和 `/plugin` 详细视图中标记被忽略的文件夹。plugin 仍然使用清单路径加载。当清单键指向默认文件夹时不显示警告，例如 `"commands": ["./commands/deploy.md"]`，因为在这种情况下文件夹被明确寻址。

706 706

707在 hook 命令中，使用[执行形式](/zh-CN/hooks#exec-form-and-shell-form)与 `args` 以便每个路径作为一个参数传递，无需引用。在 shell 形式的 hooks 和 monitor 命令中，用双引号包装变量，如 `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`。此 shell 形式的 hook 运行与 plugin 捆绑的脚本：707在 hook 命令中，使用[执行形式](/docs/zh-CN/hooks#exec-form-and-shell-form)与 `args` 以便每个路径作为一个参数传递，无需引用。在 shell 形式的 hooks 和 monitor 命令中，用双引号包装变量，如 `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`。此 shell 形式的 hook 运行与 plugin 捆绑的脚本：

708 708

709```json theme={null}709```json theme={null}

710{710{

727 727

728当 plugin 在会话中期更新时，hook 命令、monitors、MCP servers 和 LSP servers 继续使用前一个版本的路径。运行 `/reload-plugins` 以将 hooks、MCP servers 和 LSP servers 切换到新路径；monitors 需要会话重启。728当 plugin 在会话中期更新时，hook 命令、monitors、MCP servers 和 LSP servers 继续使用前一个版本的路径。运行 `/reload-plugins` 以将 hooks、MCP servers 和 LSP servers 切换到新路径；monitors 需要会话重启。

729 729

730MCP servers 也可以调用 `roots/list` 请求来在运行时读取会话的工作目录。请参阅[`roots/list` 返回的内容以及 Claude Code 何时通知服务器更改](/zh-CN/mcp#option-3-add-a-local-stdio-server)。730MCP servers 也可以调用 `roots/list` 请求来在运行时读取会话的工作目录。请参阅[`roots/list` 返回的内容以及 Claude Code 何时通知服务器更改](/docs/zh-CN/mcp#option-3-add-a-local-stdio-server)。

731 731

732<h4 id="persistent-data-directory">732<h4 id="persistent-data-directory">

733 持久数据目录733 持久数据目录

895| **Executables** | `bin/` | 添加到 Bash tool 的 `PATH` 的可执行文件。此处的文件在 plugin 启用时可作为任何 Bash tool 调用中的裸命令调用 |895| **Executables** | `bin/` | 添加到 Bash tool 的 `PATH` 的可执行文件。此处的文件在 plugin 启用时可作为任何 Bash tool 调用中的裸命令调用 |

897 897

898***898***

899 899

942| `mcp` | 一个 `.mcp.json` 带有 HTTP 和 stdio server 示例 |942| `mcp` | 一个 `.mcp.json` 带有 HTTP 和 stdio server 示例 |

943| `lsp` | 一个 `.lsp.json` 语言服务器示例 |943| `lsp` | 一个 `.lsp.json` 语言服务器示例 |

946 946

947搭建的 plugin 使用 `@skills-dir` 源而不是市场。管理员可以使用 `strictKnownMarketplaces` 或通过在 [managed settings](/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) 中添加 `{"source": "skills-dir"}` 到 `blockedMarketplaces` 来阻止此源。当被阻止时，`plugin init` 在写入前失败。947搭建的 plugin 使用 `@skills-dir` 源而不是市场。管理员可以使用 `strictKnownMarketplaces` 或通过在 [managed settings](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) 中添加 `{"source": "skills-dir"}` 到 `blockedMarketplaces` 来阻止此源。当被阻止时，`plugin init` 在写入前失败。

948 948

949**示例：**949**示例：**

950 950

1027 plugin prune1027 plugin prune

1028</h3>1028</h3>

1029 1029

1030删除不再被任何已安装 plugin 需要的自动安装 plugin 依赖项。Claude Code 为满足另一个 plugin 的 [`dependencies`](/zh-CN/plugin-dependencies) 字段而引入的依赖项将被删除；您直接安装的 plugin 永远不会被触及。1030删除不再被任何已安装 plugin 需要的自动安装 plugin 依赖项。Claude Code 为满足另一个 plugin 的 [`dependencies`](/docs/zh-CN/plugin-dependencies) 字段而引入的依赖项将被删除；您直接安装的 plugin 永远不会被触及。

1031 1031

1032```bash theme={null}1032```bash theme={null}

1033claude plugin prune [options]1033claude plugin prune [options]

1054 plugin enable1054 plugin enable

1055</h3>1055</h3>

1056 1056

1057启用已禁用的 plugin。如果 plugin 声明了[依赖项](/zh-CN/plugin-dependencies)，Claude Code 会在同一范围内以传递方式启用它们，当依赖项未安装时命令会失败。1057启用已禁用的 plugin。如果 plugin 声明了[依赖项](/docs/zh-CN/plugin-dependencies)，Claude Code 会在同一范围内以传递方式启用它们，当依赖项未安装时命令会失败。

1058 1058

1059```bash theme={null}1059```bash theme={null}

1060claude plugin enable <plugin> [options]1060claude plugin enable <plugin> [options]

1075 plugin disable1075 plugin disable

1076</h3>1076</h3>

1077 1077

1078禁用 plugin 而不卸载它。当另一个已启用的 plugin [依赖于](/zh-CN/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)目标时失败。错误消息包括一个链式命令，首先禁用每个依赖项。1078禁用 plugin 而不卸载它。当另一个已启用的 plugin [依赖于](/docs/zh-CN/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)目标时失败。错误消息包括一个链式命令，首先禁用每个依赖项。

1079 1079

1080```bash theme={null}1080```bash theme={null}

1081claude plugin disable <plugin> [options]1081claude plugin disable <plugin> [options]

1192 plugin tag1192 plugin tag

1193</h3>1193</h3>

1194 1194

1195为当前目录中的 plugin 创建发布 git 标签。从 plugin 的文件夹内运行。请参阅[标记 plugin 发布](/zh-CN/plugin-dependencies#tag-plugin-releases-for-version-resolution)。1195为当前目录中的 plugin 创建发布 git 标签。从 plugin 的文件夹内运行。请参阅[标记 plugin 发布](/docs/zh-CN/plugin-dependencies#tag-plugin-releases-for-version-resolution)。

1196 1196

1197```bash theme={null}1197```bash theme={null}

1198claude plugin tag [options]1198claude plugin tag [options]

1352 另请参阅1352 另请参阅

1353</h2>1353</h2>

1354 1354

1355* [Plugins](/zh-CN/plugins) - 教程和实际用法1355* [Plugins](/docs/zh-CN/plugins) - 教程和实际用法

1356* [Plugin marketplaces](/zh-CN/plugin-marketplaces) - 创建和管理市场1356* [Plugin marketplaces](/docs/zh-CN/plugin-marketplaces) - 创建和管理市场

1357* [Skills](/zh-CN/skills) - Skill 开发详情1357* [Skills](/docs/zh-CN/skills) - Skill 开发详情

1358* [Subagents](/zh-CN/sub-agents) - Agent 配置和功能1358* [Subagents](/docs/zh-CN/sub-agents) - Agent 配置和功能

1359* [Hooks](/zh-CN/hooks) - 事件处理和自动化1359* [Hooks](/docs/zh-CN/hooks) - 事件处理和自动化

1360* [MCP](/zh-CN/mcp) - 外部工具集成1360* [MCP](/docs/zh-CN/mcp) - 外部工具集成

1361* [Settings](/zh-CN/settings) - Plugins 的配置选项1361* [Settings](/docs/zh-CN/settings) - Plugins 的配置选项

troubleshooting.md +18 −14

Details

10 10

11| 症状 | 转到 |11| 症状 | 转到 |

12| :------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------ |12| :------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------ |

14| 更新或安装下载失败，显示 `The connection dropped while downloading the update` 或 `aborted` | [错误参考](/zh-CN/errors#the-connection-dropped-while-downloading-the-update) |14| 更新或安装下载失败，显示 `The connection dropped while downloading the update` 或 `aborted` | [错误参考](/docs/zh-CN/errors#the-connection-dropped-while-downloading-the-update) |

15| 登录循环、OAuth 错误、`403 Forbidden`、"organization disabled"、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 凭据 | [故障排除安装和登录](/zh-CN/troubleshoot-install#login-and-authentication) |15| 登录循环、OAuth 错误、`403 Forbidden`、"organization disabled"、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 凭据 | [故障排除安装和登录](/docs/zh-CN/troubleshoot-install#login-and-authentication) |

16| 设置未应用、hooks 未触发、MCP 服务器未加载 | [调试您的配置](/zh-CN/debug-your-config) |16| 设置未应用、hooks 未触发、MCP 服务器未加载 | [调试您的配置](/docs/zh-CN/debug-your-config) |

19| VS Code 扩展未连接或未检测到 Claude | [VS Code 集成](/zh-CN/vs-code#fix-common-issues) |19| VS Code 扩展未连接或未检测到 Claude | [VS Code 集成](/docs/zh-CN/vs-code#fix-common-issues) |

20| JetBrains 插件或 IDE 未检测到 | [JetBrains 集成](/zh-CN/jetbrains#troubleshooting) |20| JetBrains 插件或 IDE 未检测到 | [JetBrains 集成](/docs/zh-CN/jetbrains#troubleshooting) |

21| 高 CPU 或内存、响应缓慢、挂起、搜索找不到文件 | [性能和稳定性](#performance-and-stability)下方 |21| 高 CPU 或内存、响应缓慢、挂起、搜索找不到文件 | [性能和稳定性](#performance-and-stability)下方 |

22 22

23如果您不确定哪个适用，请在 Claude Code 内运行 `/doctor` 以自动检查您的安装、设置、扩展和上下文使用情况；它会提议可以在您确认后应用的修复。如果 `claude` 根本无法启动，请从您的 shell 运行 `claude doctor`。运行 `/mcp` 以检查 MCP 服务器状态。23如果您不确定哪个适用，请在 Claude Code 内运行 `/doctor` 以自动检查您的安装、设置、扩展和上下文使用情况；它会提议可以在您确认后应用的修复。如果 `claude` 根本无法启动，请从您的 shell 运行 `claude doctor`。运行 `/mcp` 以检查 MCP 服务器状态。

371. 定期使用 `/compact` 以减少上下文大小371. 定期使用 `/compact` 以减少上下文大小

382. 在主要任务之间关闭并重启 Claude Code382. 在主要任务之间关闭并重启 Claude Code

393. 考虑将大型构建目录添加到您的 `.gitignore` 文件393. 考虑将大型构建目录添加到您的 `.gitignore` 文件

404. 使用 [`claude --safe-mode`](/zh-CN/cli-reference#cli-flags) 重启以检查插件、MCP 服务器或 hook 是否是源头。它禁用会话的所有自定义；如果使用量下降，请参阅[调试您的配置](/zh-CN/debug-your-config#test-against-a-clean-configuration)以找出是哪一个404. 使用 [`claude --safe-mode`](/docs/zh-CN/cli-reference#cli-flags) 重启以检查插件、MCP 服务器或 hook 是否是源头。它禁用会话的所有自定义；如果使用量下降，请参阅[调试您的配置](/docs/zh-CN/debug-your-config#test-against-a-clean-configuration)以找出是哪一个

41 41

42如果内存使用在这些步骤后仍然很高，请运行 `/heapdump` 以将 JavaScript 堆快照和内存分解写入 `~/Desktop`。在 Linux 上没有 Desktop 文件夹的情况下，文件被写入您的主目录。42如果内存使用在这些步骤后仍然很高，请运行 `/heapdump` 以将 JavaScript 堆快照和内存分解写入 `~/Desktop`。在 Linux 上没有 Desktop 文件夹的情况下，文件被写入您的主目录。

43 43

44分解显示驻留集大小、JS 堆、数组缓冲区和未计算的本机内存，这有助于识别增长是在 JavaScript 对象还是本机代码中。要检查保留者，请在 Chrome DevTools 中的 Memory → Load 下打开 `.heapsnapshot` 文件。在 [GitHub](https://github.com/anthropics/claude-code/issues) 上报告内存问题时附加两个文件。44分解显示驻留集大小、JS 堆、数组缓冲区和未计算的本机内存，这有助于识别增长是在 JavaScript 对象中还是在本机代码中。要检查保留者，请在 Chrome DevTools 中的 Memory → Load 下打开 `.heapsnapshot` 文件；分解是以 `-diagnostics.json` 结尾的文件。

46<Warning>

47 `.heapsnapshot` 文件包含进程中的每个字符串。不要将其附加到公开问题或共享。在 [GitHub](https://github.com/anthropics/claude-code/issues) 上报告内存问题时，仅附加 `-diagnostics.json` 文件。该文件包含内存统计信息，不包含任何对话内容或凭证。

48</Warning>

45 49

46<h3 id="large-tables-are-cut-off-in-the-terminal">50<h3 id="large-tables-are-cut-off-in-the-terminal">

47 大型表格在终端中被截断51 大型表格在终端中被截断

48</h3>52</h3>

49 53

50超过 200 行的 Markdown 表格呈现其前 200 行，后跟 `… N more rows not shown` 行。仅显示被限制：完整表格保留在对话中，[`/copy`](/zh-CN/commands) 复制每一行。对于在终端中太大而无法读取的表格，请要求 Claude 将其写入文件。在 v2.1.208 之前，Claude Code 呈现每一行，因此恢复包含非常大表格的会话可能会在重新呈现时停滞。54超过 200 行的 Markdown 表格呈现其前 200 行，后跟 `… N more rows not shown` 行。仅显示被限制：完整表格保留在对话中，[`/copy`](/docs/zh-CN/commands) 复制每一行。对于在终端中太大而无法读取的表格，请要求 Claude 将其写入文件。在 v2.1.208 之前，Claude Code 呈现每一行，因此恢复包含非常大表格的会话可能会在重新呈现时停滞。

51 55

52<h3 id="auto-compaction-stops-with-a-thrashing-error">56<h3 id="auto-compaction-stops-with-a-thrashing-error">

53 自动压缩停止并出现抖动错误57 自动压缩停止并出现抖动错误

59 63

601. 要求 Claude 以较小的块读取超大文件，例如特定行范围或函数，而不是整个文件641. 要求 Claude 以较小的块读取超大文件，例如特定行范围或函数，而不是整个文件

612. 运行 `/compact`，重点是删除大输出，例如 `/compact keep only the plan and the diff`652. 运行 `/compact`，重点是删除大输出，例如 `/compact keep only the plan and the diff`

~~623. 将大文件工作移到 [subagent](/zh-CN/sub-agents)，以便它在单独的上下文窗口中运行~~663. 将大文件工作移到 [subagent](/docs/zh-CN/sub-agents)，以便它在单独的上下文窗口中运行

634. 如果早期对话不再需要，运行 `/clear`674. 如果早期对话不再需要，运行 `/clear`

64 68

65<h3 id="command-hangs-or-freezes">69<h3 id="command-hangs-or-freezes">

77 编辑器集成终端中的文本乱码或损坏81 编辑器集成终端中的文本乱码或损坏

78</h3>82</h3>

79 83

80如果在 VS Code、Cursor 或 Devin Desktop 集成终端中运行 Claude Code 时字符呈现为方框、涂抹或错误的字形，终端的 GPU 渲染器可能是原因。在 Claude Code 中运行 `/terminal-setup` 以将 `terminal.integrated.gpuAcceleration` 设置为 `"off"`，或在编辑器设置中手动设置并重新加载窗口。有关 `/terminal-setup` 写入的其他设置，请参阅[终端配置](/zh-CN/terminal-config)。84如果在 VS Code、Cursor 或 Devin Desktop 集成终端中运行 Claude Code 时字符呈现为方框、涂抹或错误的字形，终端的 GPU 渲染器可能是原因。在 Claude Code 中运行 `/terminal-setup` 以将 `terminal.integrated.gpuAcceleration` 设置为 `"off"`，或在编辑器设置中手动设置并重新加载窗口。有关 `/terminal-setup` 写入的其他设置，请参阅[终端配置](/docs/zh-CN/terminal-config)。

81 85

82<h3 id="search-and-discovery-issues">86<h3 id="search-and-discovery-issues">

83 搜索和发现问题87 搜索和发现问题

117 </Tab>121 </Tab>

118</Tabs>122</Tabs>

119 123

120然后在您的[环境](/zh-CN/env-vars)中设置 `USE_BUILTIN_RIPGREP=0`。124然后在您的[环境](/docs/zh-CN/env-vars)中设置 `USE_BUILTIN_RIPGREP=0`。

121 125

122<h3 id="slow-or-incomplete-search-results-on-wsl">126<h3 id="slow-or-incomplete-search-results-on-wsl">

123 WSL 上的搜索速度缓慢或结果不完整127 WSL 上的搜索速度缓慢或结果不完整

Documentation 2026-07-20 23:01 UTC to 2026-07-21 23:00 UTC