SpyBara
Go Premium

Documentation 2026-09-29 23:58 UTC to 2026-09-30 05:01 UTC

35 files changed +337 −117. View all changes and history on the product overview
2026
Wed 30 06:58 Tue 29 23:58 Mon 28 22:59 Fri 25 23:58 Thu 24 22:57 Wed 23 23:57 Tue 22 23:59 Mon 21 22:59 Sun 20 23:59 Sat 19 23:57 Fri 18 23:58 Tue 15 23:58 Mon 14 22:58 Sun 13 21:00 Sat 12 03:02 Thu 10 23:00 Wed 9 22:58 Tue 8 20:00 Tue 1 21:02

artifacts.md +11 −11

Details

100你可以与谁分享取决于你的计划:100你可以与谁分享取决于你的计划:

101 101 

102* **在你的组织内**:在Team和Enterprise计划上,向组织中的特定人员或所有人授予访问权限。查看者以组织成员身份登录claude.ai以查看该页面。102* **在你的组织内**:在Team和Enterprise计划上,向组织中的特定人员或所有人授予访问权限。查看者以组织成员身份登录claude.ai以查看该页面。

103* **公开**:分享一个链接,互联网上的任何人都可以打开,无需claude.ai登录。在Pro和Max计划上,公开链接是分享artifact的唯一方式。在Team和Enterprise计划上,公开分享处于关闭状态,直到所有者[为组织启用它](#control-public-sharing)。103* **公开**:分享一个链接,互联网上的任何人都可以打开,无需claude.ai登录。在Team和Enterprise计划上,公开分享处于关闭状态,直到所有者[为组织启用它](#control-public-sharing)。

104 104 

105<h3 id="let-someone-edit-with-you">105<h3 id="let-someone-edit-with-you">

106 让某人与你一起编辑106 让某人与你一起编辑


122 收集工件上的评论122 收集工件上的评论

123</h2>123</h2>

124 124 

125当您在组织内共享工件时,与您共享的人可以在页面上留下评论,您可以让 Claude 读取这些评论并回复。您需要 Claude Code v2.1.221 或更高版本以及 Team 或 Enterprise 计划,因为只有您[在组织内共享](#share-an-artifact)的工件才会接收评论。Claude 在两种情况下读取评论:125当您在组织内共享工件时,与您共享的人可以在页面上留下评论,您可以让 Claude 读取这些评论并回复。您需要 Claude Code v2.1.221 或更高版本。Claude 在两种情况下读取评论:

126 126 

127* **您要求 Claude 读取评论**:向 Claude 提供工件的 URL 并要求查看评论。Claude 列出每个线程,并标记可以编辑工件的人发送给它的评论。127* **您要求 Claude 读取评论**:向 Claude 提供工件的 URL 并要求查看评论。Claude 列出每个线程,并标记可以编辑工件的人发送给它的评论。

128* **可以编辑工件的人向 Claude 发送评论**:在页面上的线程中,他们使用**发送给 Claude**发送评论,或在其中提及 `@claude`。无论哪种方式,他们都会激活该线程。128* **可以编辑工件的人向 Claude 发送评论**:在页面上的线程中,他们使用**发送给 Claude**发送评论,或在其中提及 `@claude`。无论哪种方式,他们都会激活该线程。

129 129 

130Claude 只能回复或解决已激活的线程。其他线程保持打开状态,直到某人在页面上解决它们。查看者会看到每条回复都归属于 Claude,通过您。130Claude 只能回复或解决已激活的线程。其他线程保持打开状态,直到某人在页面上解决它们。查看者会看到每条回复都归属于 Claude,通过您。

131 131 

132如果您公开共享工件,查看者无法对其进行评论:页面显示`此工件公开共享时评论不可用。`要将已有评论线程的工件切换到公开链接,请先删除这些线程。132如果您公开共享工件,只有其公开链接访问权限的人看不到其评论,也无法添加任何评论。现有评论线程保留在工件上,您和其编辑者仍然可以读取和回复它们。

133 133 

134要自己要求查看评论,请向 Claude 提供 URL:134要自己要求查看评论,请向 Claude 提供 URL:

135 135 


195 195 

196当您计划共享一个由连接器支持的页面时,请要求 Claude 在每个实时部分中包含一条后备消息,该消息命名它需要的连接器。缺少连接的查看者随后会看到要连接的内容,而不是空部分。196当您计划共享一个由连接器支持的页面时,请要求 Claude 在每个实时部分中包含一条后备消息,该消息命名它需要的连接器。缺少连接的查看者随后会看到要连接的内容,而不是空部分。

197 197 

198调用连接器的 artifact 无法在任何计划上共享到公开链接。在 Team 和 Enterprise 计划上,您可以将其保持为私有或[在您的组织内共享](#share-an-artifact)。在 Pro 和 Max 计划上,其中公开链接是唯一的共享方式,由连接器支持的 artifact 对您保持私有。198您可以在您的组织内或公开[共享一个由连接器支持的页面](#share-an-artifact),如您的计划和组织设置所允许的那样。连接器调用不会为未登录 claude.ai 的查看者或来自您组织外部的查看者运行。该查看者看到的页面没有其实时部分。

199 199 

200<h3 id="the-page-shows-no-live-data-for-a-viewer">200<h3 id="the-page-shows-no-live-data-for-a-viewer">

201 页面对查看者显示没有实时数据201 页面对查看者显示没有实时数据

202</h3>202</h3>

203 203 

204当由连接器支持的页面呈现但其实时部分对您共享的某人保持为空时,请解决这些原因:204当由连接器支持的页面呈现但其实时部分对您组织中的查看者保持为空时,请解决这些原因:

205 205 

206* **查看者未连接连接器**:连接器是按账户的,因此每个查看者都需要自己连接到页面调用的每个连接器。他们可以在 claude.ai 上的**设置 > 连接器**下添加一个,然后重新加载页面。206* **查看者未连接连接器**:连接器是按账户的,因此每个查看者都需要自己连接到页面调用的每个连接器。他们可以在 claude.ai 上的**设置 > 连接器**下添加一个,然后重新加载页面。

207* **查看者拒绝了权限请求**:拒绝在该页面加载的其余部分持续。重新加载页面会再次显示权限请求。207* **查看者拒绝了权限请求**:拒绝在该页面加载的其余部分持续。重新加载页面会再次显示权限请求。


375 375 

376| 要求 | 可用时间 |376| 要求 | 可用时间 |

377| :- | :- |377| :- | :- |

378| 计划 | Pro、Max、Team 或 Enterprise。在 Pro 和 Max 计划上,artifacts 仅对您私有,不适用任何管理员管理。在 Team 计划上,artifacts 默认启用。在 Enterprise 计划上,Owner 在 claude.ai 管理设置中 [启用它们](#manage-artifacts-for-your-organization)。 |378| 计划 | Pro、Max、Team 或 Enterprise。在 Pro 和 Max 计划上,artifacts 仅对您私有,直到您共享它们,不适用任何管理员管理。在 Team 和 Enterprise 计划上,artifacts 默认启用,Owner 可以在 claude.ai 管理设置中 [关闭它们](#manage-artifacts-for-your-organization)。 |

379| 身份验证 | 会话由 claude.ai 账户支持:在 CLI 或桌面应用中使用 `/login` 登录。Claude Tag 会话通过代理的身份登录,因此不需要任何步骤。使用 API 密钥、[网关令牌](/docs/zh-CN/llm-gateway) 或云提供商凭证的会话无法发布。 |379| 身份验证 | 会话由 claude.ai 账户支持:在 CLI 或桌面应用中使用 `/login` 登录。Claude Tag 会话通过代理的身份登录,因此不需要任何步骤。使用 API 密钥、[网关令牌](/docs/zh-CN/llm-gateway) 或云提供商凭证的会话无法发布。 |

380| 模型提供商 | Anthropic API。在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上不可用。 |380| 模型提供商 | Anthropic API。在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上不可用。 |

381| 组织策略 | 客户管理的加密密钥 (CMEK)、HIPAA 和 [零数据保留](/docs/zh-CN/zero-data-retention) 未为组织启用。 |381| 组织策略 | 客户管理的加密密钥 (CMEK)、HIPAA 和 [零数据保留](/docs/zh-CN/zero-data-retention) 未为组织启用。 |


408 为您的组织管理 artifacts408 为您的组织管理 artifacts

409</h2>409</h2>

410 410 

411Team 和 Enterprise 计划上的管理员从 [claude.ai 管理设置](https://claude.ai/admin-settings/claude-code) 控制 artifacts。Artifact 内容存储在 Anthropic 运营的基础设施上,仅对发布组织的经过身份验证的成员可见,除非该 artifact 是[公开共享](#control-public-sharing)的。411Team 和 Enterprise 计划上的所有者从 [claude.ai 管理设置](https://claude.ai/admin-settings/artifacts) 控制 artifacts。Artifact 内容存储在 Anthropic 运营的基础设施上,仅对发布组织的经过身份验证的成员可见,除非该 artifact 是[公开共享](#control-public-sharing)的。

412 412 

413<h3 id="enable-or-disable-artifacts">413<h3 id="enable-or-disable-artifacts">

414 启用或禁用 artifacts414 启用或禁用 artifacts

415</h3>415</h3>

416 416 

417要为整个组织启用或禁用 artifacts,请转到 [**Settings > Claude Code > Capabilities**](https://claude.ai/admin-settings/claude-code) 并使用 **Artifacts** 切换。在具有基于角色的访问控制的 Enterprise 计划上,您还可以将 artifacts 限制到特定角色:转到 [**Settings > Roles**](https://claude.ai/admin-settings/roles),编辑角色,并在 **Claude Code** 组下设置 **Artifacts** 权限。417要为整个组织启用或禁用 artifacts,请转到 [**Organization settings > Artifacts**](https://claude.ai/admin-settings/artifacts) 并使用 **Artifacts** 切换。在具有基于角色的访问控制的 Enterprise 计划上,您还可以将 artifacts 限制到特定角色:转到 [**Organization settings > Roles**](https://claude.ai/admin-settings/roles),编辑角色,并设置 **Artifacts** 权限。

418 418 

419<h3 id="control-connector-calls-from-artifacts">419<h3 id="control-connector-calls-from-artifacts">

420 控制来自 artifacts 的连接器调用420 控制来自 artifacts 的连接器调用

421</h3>421</h3>

422 422 

423[来自 artifacts 的连接器调用](#pull-live-data-with-mcp-connectors)有自己的切换,与打开或关闭 artifacts 的 **Artifacts** 切换分开。转到 [**Settings > Capabilities**](https://claude.ai/admin-settings/capabilities) 并使用 **Enable artifact connectors** 切换。同一切换控制在 claude.ai 对话中创建的 artifacts 的连接器调用,这就是为什么它位于 **Settings > Capabilities** 而不是 **Settings > Claude Code** 下。423[来自 artifacts 的连接器调用](#pull-live-data-with-mcp-connectors)有自己的切换,与打开或关闭 artifacts 的 **Artifacts** 切换分开。转到 [**Organization settings > Capabilities**](https://claude.ai/admin-settings/capabilities) 并使用 **Enable artifact connectors** 切换。同一切换控制在 claude.ai 对话中创建的 artifacts 的连接器调用。

424 424 

425<h3 id="control-public-sharing">425<h3 id="control-public-sharing">

426 控制公开共享426 控制公开共享

427</h3>427</h3>

428 428 

429在 Team 和 Enterprise 计划上,公开共享默认处于关闭状态,因此成员只能在组织内共享 artifacts,直到管理员将其打开。要让成员将 artifacts 发布到任何人都可以查看而无需登录的公开链接,请转到 **Settings > Claude Code > Capabilities** 并在 **Artifacts** 切换下打开 **External sharing**。将其关闭会阻止通过现有公开链接的访问,而不会更改每个 artifact 的受众;如果您重新启用它,访问将恢复。429在 Team 和 Enterprise 计划上,公开共享默认处于关闭状态。要让成员将 artifacts 发布到任何人都可以查看而无需登录的公开链接,请转到 [**Organization settings > Artifacts**](https://claude.ai/admin-settings/artifacts) 并在 **Artifacts** 切换下打开 **External sharing**。将其关闭会阻止通过现有公开链接的访问,而不会更改每个 artifact 的受众;如果您重新启用它,访问将恢复。

430 430 

431<h3 id="set-a-retention-policy">431<h3 id="set-a-retention-policy">

432 设置保留策略432 设置保留策略

433</h3>433</h3>

434 434 

435要设置在自动删除之前保留 artifacts 的时间长度,请转到 [**Settings > Data & privacy controls**](https://claude.ai/admin-settings/data-privacy-controls)。您可以为仍然对其作者私有的 artifacts 和已共享的 artifacts 设置单独的保留期。435要设置在自动删除之前保留 artifacts 的时间长度,请转到 [**Organization settings > Data and privacy**](https://claude.ai/admin-settings/data-privacy-controls)。您可以为仍然对其作者私有的 artifacts 和已共享的 artifacts 设置单独的保留期。

436 436 

437<h3 id="review-the-audit-log">437<h3 id="review-the-audit-log">

438 查看审计日志438 查看审计日志

Details

163 有效负载作为 `<channel>` 标签到达 Claude 的上下文中:163 有效负载作为 `<channel>` 标签到达 Claude 的上下文中:

164 164 

165 ```text theme={null}165 ```text theme={null}

166 <channel source="webhook" path="/" method="POST">build failed on main: https://ci.example.com/run/1234</channel>166 <channel source="webhook" path="/" method="POST">

167 build failed on main: https://ci.example.com/run/1234

168 </channel>

167 ```169 ```

168 170 

169 您的终端将事件呈现为单行摘要 `← webhook: build failed on main: https://ci.example.com/run/1234`,而不是原始标签。然后您会看到 Claude 开始响应:读取文件、运行命令或消息要求的任何操作。这是一个单向频道,因此 Claude 在您的会话中行动,但不会通过 webhook 发送任何内容回复。要添加回复,请参阅[公开回复工具](#expose-a-reply-tool)。171 您的终端将事件呈现为单行摘要 `← webhook: build failed on main: https://ci.example.com/run/1234`,而不是原始标签。然后您会看到 Claude 开始响应:读取文件、运行命令或消息要求的任何操作。这是一个单向频道,因此 Claude 在您的会话中行动,但不会通过 webhook 发送任何内容回复。要添加回复,请参阅[公开回复工具](#expose-a-reply-tool)。

chrome.md +5 −2

Details

98* **暂不**:继续执行任务而不使用浏览器工具。Claude Code 可以在稍后的会话中再次询问。98* **暂不**:继续执行任务而不使用浏览器工具。Claude Code 可以在稍后的会话中再次询问。

99* **不再询问**:在未来的会话中停止该提示。您仍然可以随时使用 `/chrome` 设置集成。99* **不再询问**:在未来的会话中停止该提示。您仍然可以随时使用 `/chrome` 设置集成。

100 100 

101如果您的组织使用 [`deniedMcpServers` 托管设置](/docs/zh-CN/managed-mcp#policy-based-control-with-allowlists-and-denylists)阻止 `claude-in-chrome` MCP 服务器,Claude Code 不会显示安装提示。101两个托管 MCP 策略会关闭该提示:

102 

103* 如果您的组织使用 [`deniedMcpServers` 托管设置](/docs/zh-CN/managed-mcp#policy-based-control-with-allowlists-and-denylists)阻止 `claude-in-chrome` MCP 服务器,Claude Code 不会显示安装提示。

104* 如果您的组织部署了 [`managed-mcp.json`](/docs/zh-CN/managed-mcp#exclusive-control-with-managed-mcp-json) 文件,但未[在托管集合中允许 Claude in Chrome](/docs/zh-CN/managed-mcp#allow-claude-in-chrome-alongside-the-managed-set),Claude Code 不会显示安装提示。

102 105 

103<h3 id="enable-chrome-by-default">106<h3 id="enable-chrome-by-default">

104 默认启用 Chrome107 默认启用 Chrome


118 管理网站权限121 管理网站权限

119</h3>122</h3>

120 123 

121网站级权限从 Chrome 扩展程序继承。在 Chrome 扩展程序设置中管理权限,以控制 Claude 可以浏览、点击和输入的网站。124网站级权限从 Chrome 扩展程序继承。在 Chrome 扩展程序设置中管理权限,以控制 Claude 可以浏览、点击和输入的网站。在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中,当自动模式分类器本身批准对网站的浏览器调用时,扩展程序会跳过该调用的自己的按网站检查,除非您的权限规则拒绝任何网站对 Claude in Chrome 的访问。

122 125 

123<h3 id="browser-tools-in-plan-mode">126<h3 id="browser-tools-in-plan-mode">

124 Plan Mode 中的浏览器工具127 Plan Mode 中的浏览器工具

Details

356 356 

357仅运行 Claude Desktop 的机器需要它。Claude Desktop 将模型列表和禁用工具列表应用于嵌入式会话本身,但出口允许列表仅作为父设置到达它们,形式为 `WebFetch` 域规则和沙箱网络规则。没有选择加入,这些会话运行时没有出口限制,没有任何警告。网关仍然拒绝策略未授予的模型的推理请求。357仅运行 Claude Desktop 的机器需要它。Claude Desktop 将模型列表和禁用工具列表应用于嵌入式会话本身,但出口允许列表仅作为父设置到达它们,形式为 `WebFetch` 域规则和沙箱网络规则。没有选择加入,这些会话运行时没有出口限制,没有任何警告。网关仍然拒绝策略未授予的模型的推理请求。

358 358 

359插件市场允许列表也仅作为父设置到达嵌入式会话。当您在 Claude Desktop 的托管配置中关闭用户添加的插件市场时,Claude Desktop 2.16120.0 或更高版本隐藏您的组织未配置的市场,并拒绝从它们安装。要停止嵌入式会话加载已从这些市场安装的插件,它将 `strictKnownMarketplaces` 列表作为父设置发送给它们。没有选择加入,Claude Code 忽略该列表,这些插件继续加载。

360 

359开发人员通过 `/login` 登录的机器不需要它;每个 Claude Code 会话从网关获取其策略。361开发人员通过 `/login` 登录的机器不需要它;每个 Claude Code 会话从网关获取其策略。

360 362 

361其[`policyHelper`](/docs/zh-CN/settings-reference#policyhelper)提供托管设置的舰队无法使用它:Claude Code 从不在这些舰队上合并父设置,因为它仅从助手的输出读取托管设置。363其[`policyHelper`](/docs/zh-CN/settings-reference#policyhelper)提供托管设置的舰队无法使用它:Claude Code 从不在这些舰队上合并父设置,因为它仅从助手的输出读取托管设置。


451* **`forceLoginOrgUUID`**:当最高优先级管理员源未设置组织 UUID 时,Claude Code 尊重父提供的值。网关登录不检查此密钥。最高优先级管理员源中的组织 UUID 阻止父的值,是 Claude Code 强制执行的值。453* **`forceLoginOrgUUID`**:当最高优先级管理员源未设置组织 UUID 时,Claude Code 尊重父提供的值。网关登录不检查此密钥。最高优先级管理员源中的组织 UUID 阻止父的值,是 Claude Code 强制执行的值。

452* **`allowedMcpServers`**:当最高优先级管理员源未设置允许列表时,Claude Code 尊重父提供的允许列表,`allowManagedMcpServersOnly` 不阻止它,因为锁强制执行任何赢家列表作为托管值,包括当最高优先级管理员源未设置时的父提供列表。最高优先级管理员源中的列表阻止父的并是 Claude Code 强制执行的列表,因此在那里设置 `allowedMcpServers`,在锁旁边。在 v2.1.223 之前,任何管理员源中任一密钥的值都阻止父的。454* **`allowedMcpServers`**:当最高优先级管理员源未设置允许列表时,Claude Code 尊重父提供的允许列表,`allowManagedMcpServersOnly` 不阻止它,因为锁强制执行任何赢家列表作为托管值,包括当最高优先级管理员源未设置时的父提供列表。最高优先级管理员源中的列表阻止父的并是 Claude Code 强制执行的列表,因此在那里设置 `allowedMcpServers`,在锁旁边。在 v2.1.223 之前,任何管理员源中任一密钥的值都阻止父的。

453* **`availableModels`**:当赢家托管源未设置模型列表时,Claude Code 尊重父提供的模型列表。如果您的舰队限制模型,在赢家源中设置 `availableModels`。455* **`availableModels`**:当赢家托管源未设置模型列表时,Claude Code 尊重父提供的模型列表。如果您的舰队限制模型,在赢家源中设置 `availableModels`。

454* **`strictKnownMarketplaces`**:当赢家托管源未设置一个时,Claude Code 尊重父提供的插件市场允许列表。如果您的舰队限制市场,在赢家源中设置 `strictKnownMarketplaces`。需要 Claude Code v2.1.282 或更高版本。456* **`strictKnownMarketplaces`**:当赢家托管源未设置一个时,Claude Code 尊重父提供的插件市场允许列表。Claude Desktop 2.16120.0 或更高版本在其托管配置关闭用户添加的插件市场时发送一个。如果您的舰队限制市场,在赢家源中设置 `strictKnownMarketplaces`。需要 Claude Code v2.1.282 或更高版本。

455* **`blockedMarketplaces`**:父提供的市场阻止列表通过并添加到任何托管源设置的阻止列表,因为阻止列表只能进一步限制。需要 Claude Code v2.1.282 或更高版本。457* **`blockedMarketplaces`**:父提供的市场阻止列表通过并添加到任何托管源设置的阻止列表,因为阻止列表只能进一步限制。需要 Claude Code v2.1.282 或更高版本。

456* **`strictPluginOnlyCustomization`**:此密钥无论任何锁都通过过滤器,它使 Claude Code 忽略开发人员的自己定制,包括保护性 hooks。没有锁阻止它。458* **`strictPluginOnlyCustomization`**:此密钥无论任何锁都通过过滤器,它使 Claude Code 忽略开发人员的自己定制,包括保护性 hooks。没有锁阻止它。

457 459 

Details

566 * platform.claude.com566 * platform.claude.com

567 * code.claude.com567 * code.claude.com

568 * claude.ai568 * claude.ai

569 * claude.com

570 * support.claude.com

571 * anthropic.com

572 * [www.anthropic.com](http://www.anthropic.com)

569 </Accordion>573 </Accordion>

570 574 

571 <Accordion title="版本控制">575 <Accordion title="版本控制">


596 * hub.docker.com600 * hub.docker.com

597 * [www.docker.com](http://www.docker.com)601 * [www.docker.com](http://www.docker.com)

598 * production.cloudflare.docker.com602 * production.cloudflare.docker.com

603 * production.cloudfront.docker.com

599 * download.docker.com604 * download.docker.com

600 * gcr.io605 * gcr.io

601 * \*.gcr.io606 * \*.gcr.io

commands.md +1 −1

Details

91| `/fast [on\|off]` | 切换[快速模式](/docs/zh-CN/fast-mode)打开或关闭。在 Claude 响应时运行它,Claude Code 切换快速模式而不等待轮次结束,尽管运行的轮次以其原始速度完成。在 v2.1.242 之前,Claude Code 从它从 Anthropic 获取的功能标志决定是在轮中期运行命令还是将其排队直到轮次完成,并始终在不[获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话中排队它。非交互模式中的可用性受限于 `-p`;请参阅[切换快速模式](/docs/zh-CN/fast-mode#toggle-fast-mode)。需要 Claude Code v2.1.205 或更高版本 |91| `/fast [on\|off]` | 切换[快速模式](/docs/zh-CN/fast-mode)打开或关闭。在 Claude 响应时运行它,Claude Code 切换快速模式而不等待轮次结束,尽管运行的轮次以其原始速度完成。在 v2.1.242 之前,Claude Code 从它从 Anthropic 获取的功能标志决定是在轮中期运行命令还是将其排队直到轮次完成,并始终在不[获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话中排队它。非交互模式中的可用性受限于 `-p`;请参阅[切换快速模式](/docs/zh-CN/fast-mode#toggle-fast-mode)。需要 Claude Code v2.1.205 或更高版本 |

92| `/feedback [report]` | 发送关于 Claude Code 的产品反馈。打开与 [`/bug`](#all-commands) 相同的对话框,具有相同的同意步骤、发送规则和轮中期行为。在具有 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)的会话中,不带参数的 `/feedback` 打开草稿队列,你可以在其中审查、编辑、发送或丢弃 Claude 排队的草稿;队列包括一个选项来在对话框中写入新报告。使用参数,对于 `/bug` 总是,对话框直接打开 |92| `/feedback [report]` | 发送关于 Claude Code 的产品反馈。打开与 [`/bug`](#all-commands) 相同的对话框,具有相同的同意步骤、发送规则和轮中期行为。在具有 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)的会话中,不带参数的 `/feedback` 打开草稿队列,你可以在其中审查、编辑、发送或丢弃 Claude 排队的草稿;队列包括一个选项来在对话框中写入新报告。使用参数,对于 `/bug` 总是,对话框直接打开 |

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

94| `/focus` | 切换焦点视图,仅显示你的最后一个提示、一行工具调用摘要和最终响应。工具调用摘要也计算在轮中启动的子代理数量,并将完成的后台任务通知折叠为单个计数。选择在会话中持久化;在设置中设置 [`viewMode`](/docs/zh-CN/settings-reference#viewmode) 以覆盖它。仅在[全屏渲染](/docs/zh-CN/fullscreen)中可用。[VS Code 扩展](/docs/zh-CN/vs-code#use-the-prompt-box)提供其自己的焦点视图作为命令菜单切换,存储为扩展设置,独立于 `viewMode` |94| `/focus` | 切换焦点视图,仅显示你的最后一个提示、一行工具调用摘要和最终响应。工具调用摘要也计算在轮中启动的子代理数量,并将完成的后台任务通知折叠为单个计数。选择在会话中持久化;在设置中设置 [`viewMode`](/docs/zh-CN/settings-reference#viewmode) 以覆盖它。仅在[全屏渲染](/docs/zh-CN/fullscreen)中可用。从 [Remote Control](/docs/zh-CN/remote-control) 客户端,运行 `/focus [on\|off]` 以仅为当前会话打开或关闭焦点视图,而不更改你的保存选择;这需要 Claude Code v2.1.281 或更高版本。[VS Code 扩展](/docs/zh-CN/vs-code#use-the-prompt-box)提供其自己的焦点视图作为命令菜单切换,存储为扩展设置,独立于 `viewMode` |

95| `/fork [prompt]` | [将当前对话复制](/docs/zh-CN/agent-view#copy-the-session-with-%2Ffork)到新的后台会话并继续在这里工作。传递一个提示词,副本立即开始处理它;没有它,它在代理视图中等待其第一个提示词。除非副本[就地编辑](/docs/zh-CN/agent-view#how-file-edits-are-isolated),Claude Code 指示它在进行代码更改之前创建自己的 worktree;隔离指令需要 Claude Code v2.1.221 或更高版本。要将侧面任务交给一个子代理,其结果返回到这个对话,请使用 `/subtask`;要自己切换到副本,请使用 `/branch`。需要 Claude Code v2.1.212 或更高版本;在 v2.1.161 到 v2.1.211,以及每当[代理视图关闭](/docs/zh-CN/agent-view#turn-off-agent-view)时,`/fork` 启动一个[分叉子代理](/docs/zh-CN/sub-agents#fork-the-current-conversation) |95| `/fork [prompt]` | [将当前对话复制](/docs/zh-CN/agent-view#copy-the-session-with-%2Ffork)到新的后台会话并继续在这里工作。传递一个提示词,副本立即开始处理它;没有它,它在代理视图中等待其第一个提示词。除非副本[就地编辑](/docs/zh-CN/agent-view#how-file-edits-are-isolated),Claude Code 指示它在进行代码更改之前创建自己的 worktree;隔离指令需要 Claude Code v2.1.221 或更高版本。要将侧面任务交给一个子代理,其结果返回到这个对话,请使用 `/subtask`;要自己切换到副本,请使用 `/branch`。需要 Claude Code v2.1.212 或更高版本;在 v2.1.161 到 v2.1.211,以及每当[代理视图关闭](/docs/zh-CN/agent-view#turn-off-agent-view)时,`/fork` 启动一个[分叉子代理](/docs/zh-CN/sub-agents#fork-the-current-conversation) |

96| `/goal [condition\|clear]` | 设置一个[目标](/docs/zh-CN/goal):Claude 跨轮继续工作直到条件满足或目标[因另一个原因清除](/docs/zh-CN/goal#how-evaluation-works)。没有参数时,显示当前或最近实现的目标。`clear`、`stop`、`off`、`reset`、`none` 或 `cancel` 提前移除活跃目标 |96| `/goal [condition\|clear]` | 设置一个[目标](/docs/zh-CN/goal):Claude 跨轮继续工作直到条件满足或目标[因另一个原因清除](/docs/zh-CN/goal#how-evaluation-works)。没有参数时,显示当前或最近实现的目标。`clear`、`stop`、`off`、`reset`、`none` 或 `cancel` 提前移除活跃目标 |

97| `/heapdump` | 写入 JavaScript 堆快照和内存细目到 `~/Desktop`,或 Linux 上没有 Desktop 文件夹的主目录,用于诊断高内存使用。报告内存问题时仅附加 `-diagnostics.json` 文件;`.heapsnapshot` 包含你的完整对话和凭证,所以不要共享它。[从命令菜单隐藏](#how-the-command-menu-matches-what-you-type);完整输入它。请参阅[如何处理输出](/docs/zh-CN/troubleshooting#high-cpu-or-memory-usage) |97| `/heapdump` | 写入 JavaScript 堆快照和内存细目到 `~/Desktop`,或 Linux 上没有 Desktop 文件夹的主目录,用于诊断高内存使用。报告内存问题时仅附加 `-diagnostics.json` 文件;`.heapsnapshot` 包含你的完整对话和凭证,所以不要共享它。[从命令菜单隐藏](#how-the-command-menu-matches-what-you-type);完整输入它。请参阅[如何处理输出](/docs/zh-CN/troubleshooting#high-cpu-or-memory-usage) |

costs.md +2 −0

Details

96 96 

97运行 [`/insights`](/docs/zh-CN/commands#all-commands) 以获取关于您如何工作而不是您使用了多少令牌的报告。它分析此机器上的最近会话,并编写一份 HTML 报告,涵盖您处理的内容、摩擦点(例如误解的请求或有缺陷的代码)以及有关更有效地使用 Claude Code 的建议。单次运行分析最多 200 个它之前未见过的会话,并跳过非常短的会话。当会话被遗漏时,报告标题显示分析的计数,括号中显示总数,例如 `200 sessions (412 total)`。97运行 [`/insights`](/docs/zh-CN/commands#all-commands) 以获取关于您如何工作而不是您使用了多少令牌的报告。它分析此机器上的最近会话,并编写一份 HTML 报告,涵盖您处理的内容、摩擦点(例如误解的请求或有缺陷的代码)以及有关更有效地使用 Claude Code 的建议。单次运行分析最多 200 个它之前未见过的会话,并跳过非常短的会话。当会话被遗漏时,报告标题显示分析的计数,括号中显示总数,例如 `200 sessions (412 total)`。

98 98 

99当[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)对会话可用且您最近的会话大多在没有它的情况下运行时,报告还可以包括自动模式在这些会话中可以处理多少权限提示的估计。

100 

99Claude Code 将最新报告写入 `~/.claude/usage-data/report.html`,并在同一目录中保存每次运行的时间戳副本,因此早期报告不会被覆盖。Claude Code 按与其余会话数据相同的计划删除报告:在启动时,它删除早于 [`cleanupPeriodDays`](/docs/zh-CN/claude-directory#cleaned-up-automatically) 的文件,默认为 30 天。101Claude Code 将最新报告写入 `~/.claude/usage-data/report.html`,并在同一目录中保存每次运行的时间戳副本,因此早期报告不会被覆盖。Claude Code 按与其余会话数据相同的计划删除报告:在启动时,它删除早于 [`cleanupPeriodDays`](/docs/zh-CN/claude-directory#cleaned-up-automatically) 的文件,默认为 30 天。

100 102 

101您可以在任何计划和任何提供商上运行 `/insights`。分析通过与您的常规会话相同的提供商和账户运行,令牌计入您的计划或 API 使用情况。不包括来自其他设备和 claude.ai 的会话。103您可以在任何计划和任何提供商上运行 `/insights`。分析通过与您的常规会话相同的提供商和账户运行,令牌计入您的计划或 API 使用情况。不包括来自其他设备和 claude.ai 的会话。

desktop.md +6 −0

Details

834* **Remote Control**:为你的组织启用或禁用[远程控制](/docs/zh-CN/remote-control)834* **Remote Control**:为你的组织启用或禁用[远程控制](/docs/zh-CN/remote-control)

835* **禁用绕过权限模式**:防止你的组织中的用户启用绕过权限模式835* **禁用绕过权限模式**:防止你的组织中的用户启用绕过权限模式

836 836 

837<Note>

838 Cowork 下的 OpenTelemetry 表单位于管理员控制台的[数据和隐私设置](https://claude.ai/admin-settings/data-privacy-controls)中的**监控**下,仅适用于 Cowork 会话。在此机器上的 Cowork 会话中,桌面应用将该收集器作为 `OTEL_*` 环境变量传递给 Claude Code,因此该表单生效,尽管该会话中的 Claude Code [从不获取管理员控制台设置](#managed-settings)。

839 

840 要从 Code 选项卡会话导出遥测,请在 Claude Code 托管设置的 `env` 块中设置 `CLAUDE_CODE_ENABLE_TELEMETRY` 和 `OTEL_*` 变量,如[监控的管理员配置](/docs/zh-CN/monitoring-usage#administrator-configuration)中所示。本地、云和 SSH 会话各自从不同来源读取[托管设置](#managed-settings)。有关云会话可以到达的主机,请参阅[网络访问](/docs/zh-CN/cloud-environments#network-access)。有关 Code 选项卡会话报告的 `service.name`,请参阅[服务信息](/docs/zh-CN/monitoring-usage#service-information)。

841</Note>

842 

837<h3 id="managed-settings">843<h3 id="managed-settings">

838 托管设置844 托管设置

839</h3>845</h3>

env-vars.md +1 −1

Details

110 110 

111某些行为同时具有环境变量和专用设置键,Claude Code 读取哪一个的顺序因键而异。对于 `ANTHROPIC_MODEL` 和 `CLAUDE_CODE_AUTO_CONNECT_IDE`,Claude Code 首先读取变量,仅当变量未设置时才使用 `model` 或 `autoConnectIde` 设置。对于您正在设置的对,请检查下面变量的行和 [设置参考](/docs/zh-CN/settings-reference) 上的键条目。111某些行为同时具有环境变量和专用设置键,Claude Code 读取哪一个的顺序因键而异。对于 `ANTHROPIC_MODEL` 和 `CLAUDE_CODE_AUTO_CONNECT_IDE`,Claude Code 首先读取变量,仅当变量未设置时才使用 `model` 或 `autoConnectIde` 设置。对于您正在设置的对,请检查下面变量的行和 [设置参考](/docs/zh-CN/settings-reference) 上的键条目。

112 112 

113当同一变量在您的 shell 和设置文件 `env` 块中都设置时,设置文件值适用。Claude Code 将每个 `env` 条目写入进程环境,替换从 shell 继承的值。[`env` 设置](/docs/zh-CN/settings-reference#when-claude-code-applies-env-values) 说明何时应用它们。少数变量是特殊情况;[`env` 设置](/docs/zh-CN/settings-reference#env) 列出了例外。113当同一变量在您的 shell 和设置文件 `env` 块中都设置时,在大多数会话中设置文件值适用。Claude Code 将每个 `env` 条目写入进程环境,替换从 shell 继承的值。[`env` 值如何与您的 shell 交互](/docs/zh-CN/settings-reference#how-env-values-interact-with-your-shell) 涵盖保留继承值的会话,以及 [`env` 设置](/docs/zh-CN/settings-reference#when-claude-code-applies-env-values) 说明何时应用它们。少数变量是特殊情况;[`env` 设置](/docs/zh-CN/settings-reference#env) 列出了例外。

114 114 

115在设置文件中,您可以设置变量,但不能删除变量。要覆盖无法取消设置的变量,例如由您无法控制的 shell 配置文件导出的过时 `CLAUDE_CODE_USE_VERTEX`,请在 `env` 块中将其设置为空字符串:`"CLAUDE_CODE_USE_VERTEX": ""`。Claude Code 将空值视为未设置以进行提供程序选择。子进程仍然继承空值。115在设置文件中,您可以设置变量,但不能删除变量。要覆盖无法取消设置的变量,例如由您无法控制的 shell 配置文件导出的过时 `CLAUDE_CODE_USE_VERTEX`,请在 `env` 块中将其设置为空字符串:`"CLAUDE_CODE_USE_VERTEX": ""`。Claude Code 将空值视为未设置以进行提供程序选择。子进程仍然继承空值。

116 116 

errors.md +40 −9

Details

152| `There's an issue with the selected model` | [请求错误](#theres-an-issue-with-the-selected-model) |152| `There's an issue with the selected model` | [请求错误](#theres-an-issue-with-the-selected-model) |

153| `Model ... is not a recognized model id` | [请求错误](#model-is-not-a-recognized-model-id) |153| `Model ... is not a recognized model id` | [请求错误](#model-is-not-a-recognized-model-id) |

154| `Model ... not found` | [请求错误](#model-not-found) |154| `Model ... not found` | [请求错误](#model-not-found) |

155| `Couldn't confirm model ... with the API` | [请求错误](#couldnt-confirm-model-with-the-api) |

155| `API error: ... · model not changed` | [请求错误](#api-error-model-not-changed) |156| `API error: ... · model not changed` | [请求错误](#api-error-model-not-changed) |

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

157| `Claude Code ... does not support this model; version ... or newer is required` | [请求错误](#claude-code-does-not-support-this-model) |158| `Claude Code ... does not support this model; version ... or newer is required` | [请求错误](#claude-code-does-not-support-this-model) |


2346 模型不是公认的模型 ID2347 模型不是公认的模型 ID

2347</h3>2348</h3>

2348 2349 

2349您传递给模型切换的模型字符串不是模型别名、此 Claude Code 版本知道的模型 ID,也不是以 `claude-` 开头的 ID。常见原因是 ID 中的拼写错误、显示名称(如 `Sonnet 5`,其中需要 ID `claude-sonnet-5`)或仅较新 Claude Code 版本识别的别名。Claude Code 立即拒绝切换。在 v2.1.200 之前,Claude Code 保存字符串并在下一个请求时失败,显示[所选模型存在问题](#theres-an-issue-with-the-selected-model)。2350您传递给模型切换的字符串不是 Claude Code 可以用作模型的字符串,因此它拒绝了切换而不发送请求,会话保持其当前模型。您可以在通过 [Agent SDK](/docs/zh-CN/agent-sdk/typescript) `setModel()` 方法设置模型时获得此错误,通过运行 Claude Code CLI 的应用程序(如 [Desktop app](/docs/zh-CN/desktop)),或当您从通过 [Remote Control](/docs/zh-CN/remote-control) 连接的设备选择模型时。在 v2.1.200 之前,Claude Code 保存字符串并在下一个请求时失败,显示[所选模型存在问题](#theres-an-issue-with-the-selected-model)。

2350 2351 

2351```text theme={null}2352```text theme={null}

2352Model "claud-sonnet-5" is not a recognized model id. Did you mean 'claude-sonnet-5'?2353Model "Sonnet5" is not a recognized model id. Did you mean 'claude-sonnet-5'?

2353```2354```

2354 2355 

2355尾部提示命名最接近的匹配别名或模型 ID。当没有足够接近的内容时,它读取 `Run /model to see available models.`。在 [Desktop app](/docs/zh-CN/desktop) 启动的会话中,无匹配提示读取 `Switch to a different model.`2356在此示例中,应用程序发送了显示名称 `Sonnet 5`,消息重复时不带其空格。尾部提示命名最接近的匹配别名或模型 ID。当没有足够接近的内容时,它读取 `Run /model to see available models.`。在 [Desktop app](/docs/zh-CN/desktop) 启动的会话中,无匹配提示读取 `Switch to a different model.`

2356 2357 

2357Claude Code 在请求切换时在本地生成此错误,在发送任何 API 请求之前。它适用于通过 [Agent SDK](/docs/zh-CN/agent-sdk/typescript) `setModel()` 方法设置模型的情况,通过运行 Claude Code CLI 的应用程序(如 [Desktop app](/docs/zh-CN/desktop)),或当您从通过 [Remote Control](/docs/zh-CN/remote-control) 连接的设备选择模型时。在 v2.1.260 之前,检查不涵盖 Remote Control 选择,因此 Claude Code 应用了选择,下一个请求失败,显示[所选模型存在问题](#theres-an-issue-with-the-selected-model)。2358当您通过 Agent SDK 或在 Anthropic API 上的应用程序切换时,只有无法成为模型 ID 的字符串(如显示名称或空字符串)会获得此错误。

2359 

2360当您从 Remote Control 设备选择模型时,Claude Code 在本地检查字符串。任何不是模型别名、Claude Code 列出或您配置的模型,或以 `claude-` 开头的 ID 的字符串都会获得此错误,包括拼写错误的 ID(如 `claud-sonnet-5`)。在 v2.1.260 之前,此检查不涵盖 Remote Control 选择,因此无法识别的字符串被应用,下一个请求失败。

2358 2361 

2359**要做什么:**2362**要做什么:**

2360 2363 

2361* 运行 `/model` 不带参数以打开选择器并从您帐户可用的模型中选择,然后传递那里显示的别名或 ID2364* 运行 `/model` 不带参数以打开选择器并从您帐户可用的模型中选择,然后传递那里显示的别名或 ID

2362* 如果您使用了较新 Claude Code 版本支持的别名,运行 `claude update`。以 `claude-` 开头的完整 ID 通过此本地检查,即使模型比您的 Claude Code 版本更新。服务器仍然可能需要该模型的最低版本;请参阅 [Claude Code 不支持此模型](#claude-code-does-not-support-this-model)。2365* 如果您使用了较新 Claude Code 版本支持的别名,运行 `claude update`,或传递模型的完整 ID。服务器仍然可能需要该模型的最低 Claude Code 版本;请参阅 [Claude Code 不支持此模型](#claude-code-does-not-support-this-model)。

2363* v2.1.200 之前保存的模型不会被此检查修复。如果过时的值不断返回,请从[设置您的模型](/docs/zh-CN/model-config#setting-your-model)下列出的位置删除它。2366* v2.1.200 之前保存的模型不会被此检查修复。如果过时的值不断返回,请从[设置您的模型](/docs/zh-CN/model-config#setting-your-model)下列出的位置删除它。

2364* 检查仅在 Anthropic API 上运行。在任何其他提供商或网关上,包括自定义 `ANTHROPIC_BASE_URL`,提供商定义模型名称,因此 Claude Code 接受任何字符串并将其传递。Claude Code 仍然可以在请求时写入[无法识别的模型诊断行](#unrecognized-model-id-on-a-request),在每个提供商上。2367* 在 Anthropic API 以外的任何提供商上,或在网关或自定义 `ANTHROPIC_BASE_URL` 后面,只有空字符串会获得此错误。Claude Code 仍然可以在请求时写入[无法识别的模型诊断行](#unrecognized-model-id-on-a-request),在每个提供商上。

2365 2368 

2366<h3 id="model-not-found">2369<h3 id="model-not-found">

2367 模型未找到2370 模型未找到

2368</h3>2371</h3>

2369 2372 

2370您使用 `/model <name>` 选择了模型,Claude Code 无法确认存在具有该名称的模型。当名称不是 [model alias](/docs/zh-CN/model-config#model-aliases) 或 Claude Code 在本地接受的另一种拼写时,`/model` 使用最小 API 请求验证它,此错误通常是您的 API 端点的答案。无法成为模型 ID 的名称(如包含空格的名称)会获得相同的消息。2373您使用名称切换到模型,Claude Code 无法确认存在具有该名称的模型。当名称不是 [model alias](/docs/zh-CN/model-config#model-aliases) 或 Claude Code 在本地接受的另一种拼写时,Claude Code 使用最小 API 请求验证它,此错误通常是您的 API 端点的答案。使用 `/model <name>` 时,无法成为模型 ID 的名称(如包含空格的名称)会获得相同的消息。

2371 2374 

2372```text theme={null}2375```text theme={null}

2373Model 'claude-opus-9' not found2376Model 'claude-opus-9' not found


2379 2382 

2380* 运行 `/model` 不带参数并从您帐户可用的模型中选择,或使用 [model alias](/docs/zh-CN/model-config#model-aliases)(如 `sonnet`),它解析为维护的默认值2383* 运行 `/model` 不带参数并从您帐户可用的模型中选择,或使用 [model alias](/docs/zh-CN/model-config#model-aliases)(如 `sonnet`),它解析为维护的默认值

2381* 如果您输入了完整 ID,请根据您提供商的模型目录检查它。新推出的模型可能在 Anthropic API 上可用,但您的提供商或地区尚未提供。2384* 如果您输入了完整 ID,请根据您提供商的模型目录检查它。新推出的模型可能在 Anthropic API 上可用,但您的提供商或地区尚未提供。

2385* 在 Agent SDK 中,`setModel()` 失败,显示此消息,会话继续在其前一个模型上运行。在 TypeScript SDK 中,调用 [`supportedModels()`](/docs/zh-CN/agent-sdk/typescript#query-object) 以列出您可以切换到的模型。

2382* 在 v2.1.265 之前,`/model` 也以此错误拒绝了 `opusplan[1m]` 别名拼写。在这些版本上,更新 Claude Code,或在[设置](/docs/zh-CN/model-config#setting-your-model)中或使用 `--model` 设置模型。2386* 在 v2.1.265 之前,`/model` 也以此错误拒绝了 `opusplan[1m]` 别名拼写。在这些版本上,更新 Claude Code,或在[设置](/docs/zh-CN/model-config#setting-your-model)中或使用 `--model` 设置模型。

2383 2387 

2388<h3 id="couldnt-confirm-model-with-the-api">

2389 无法通过 API 确认模型

2390</h3>

2391 

2392您通过 [Agent SDK](/docs/zh-CN/agent-sdk/typescript) `setModel()` 方法或运行 Claude Code CLI 的应用程序(如 [Desktop app](/docs/zh-CN/desktop))切换了模型,确认模型 ID 与您的 API 端点的请求在五秒内没有得到答复。会话保持其当前模型。

2393 

2394```text theme={null}

2395Couldn't confirm model "claude-sonnet-5" with the API. Try again, or run /model to see available models.

2396```

2397 

2398在 [Desktop app](/docs/zh-CN/desktop) 启动的会话中,消息在 `Try again.` 处结束。

2399 

2400**要做什么:**

2401 

2402* 再次切换到模型

2403* 如果切换继续失败,检查 Claude Code 是否可以到达您的 API 端点;请参阅[网络和连接错误](#network-and-connection-errors)

2404 

2384<h3 id="api-error-model-not-changed">2405<h3 id="api-error-model-not-changed">

2385 检查选择的模型时出现 API 错误2406 检查选择的模型时出现 API 错误

2386</h3>2407</h3>


2432API Error: 400 Claude Code 2.1.240 is older than the minimum version required by your organization's policy. Run 'claude update', or update the Claude desktop app, to continue.2453API Error: 400 Claude Code 2.1.240 is older than the minimum version required by your organization's policy. Run 'claude update', or update the Claude desktop app, to continue.

2433```2454```

2434 2455 

2456发出请求的 Claude Code 二进制文件报告的版本是 API 检查的版本。

2457 

2435**要做什么:**2458**要做什么:**

2436 2459 

2437* 运行 `claude update`,或更新 Claude 桌面应用,然后启动新会话2460更新该二进制文件,然后启动新会话。二进制文件的来源决定了如何,除了在[自托管环境](/docs/zh-CN/self-hosted-environments-deploy#pin-the-version)中:

2438* 对于按模型措辞,您可以通过使用 `/model` 切换到另一个模型来继续在当前会话中工作2461 

2462| 发出请求的二进制文件 | 如何更新它 |

2463| :- | :- |

2464| 您安装的 Claude Code | 运行 `claude update` |

2465| Claude desktop app | 更新应用 |

2466| [VS Code extension](/docs/zh-CN/vs-code) 捆绑的二进制文件 | 更新扩展 |

2467| Agent SDK 包捆绑的二进制文件 | [升级 SDK 包](/docs/zh-CN/agent-sdk/hosting#runtime-dependencies),然后重启您的应用程序。在[编译的单文件可执行文件](/docs/zh-CN/agent-sdk/typescript#compile-to-a-single-executable)中,重建它 |

2468 

2469* 对于按模型措辞,您可以通过切换到另一个模型来继续在当前会话中工作:在 CLI 中运行 `/model`,在流式输入模式下的 TypeScript SDK 的 `Query` 对象上调用 [`setModel()`](/docs/zh-CN/agent-sdk/typescript#query-object),或在 Python SDK 的 `ClaudeSDKClient` 上调用 [`set_model()`](/docs/zh-CN/agent-sdk/python#claudesdkclient)

2439* 对于组织政策措辞,在继续之前更新2470* 对于组织政策措辞,在继续之前更新

2440 2471 

2441<h3 id="model-is-restricted-by-your-organizations-settings">2472<h3 id="model-is-restricted-by-your-organizations-settings">

fast-mode.md +2 −0

Details

72 72 

73在会话中输入 `/fast on` 以打开快速模式。它仅对该会话保持打开,不会保存为您的默认值。[要求](#requirements)也适用于云会话。73在会话中输入 `/fast on` 以打开快速模式。它仅对该会话保持打开,不会保存为您的默认值。[要求](#requirements)也适用于云会话。

74 74 

75在浏览器中访问 [claude.ai/code](https://claude.ai/code),您也可以从消息框上的模型菜单打开和关闭快速模式。当您的计划包含快速模式且所选模型支持它时,菜单会显示该开关。

76 

75<h2 id="understand-the-cost-tradeoff">77<h2 id="understand-the-cost-tradeoff">

76 了解成本权衡78 了解成本权衡

77</h2>79</h2>

Details

312| [Computer use](/docs/zh-CN/computer-use) | ✓ | ✓ | ✗ | ✗ |312| [Computer use](/docs/zh-CN/computer-use) | ✓ | ✓ | ✗ | ✗ |

313| Dispatch ([Desktop](/docs/zh-CN/desktop#sessions-from-dispatch)) | ✓ | ✓ | ✗ | ✗ |313| Dispatch ([Desktop](/docs/zh-CN/desktop#sessions-from-dispatch)) | ✓ | ✓ | ✗ | ✗ |

314| [Code Review](/docs/zh-CN/code-review) | ✗ | ✗ | ✓ | ✓ |314| [Code Review](/docs/zh-CN/code-review) | ✗ | ✗ | ✓ | ✓ |

315| [Artifacts](/docs/zh-CN/artifacts) | ✓ | ✓ | ✓ | Admin-enabled |315| [Artifacts](/docs/zh-CN/artifacts) | ✓ | ✓ | ✓ | ✓ |

316| [分析仪表板和贡献指标](/docs/zh-CN/analytics) | ✗ | ✗ | ✓ | ✓ |316| [分析仪表板和贡献指标](/docs/zh-CN/analytics) | ✗ | ✗ | ✓ | ✓ |

317| [Enterprise Analytics API](/docs/zh-CN/analytics#access-data-programmatically) | ✗ | ✗ | ✗ | ✓ |317| [Enterprise Analytics API](/docs/zh-CN/analytics#access-data-programmatically) | ✗ | ✗ | ✗ | ✓ |

318| [Server-managed settings](/docs/zh-CN/server-managed-settings) | ✗ | ✗ | ✓ | ✓ |318| [Server-managed settings](/docs/zh-CN/server-managed-settings) | ✗ | ✗ | ✓ | ✓ |

Details

43 43 

44Claude Code 然后推送一个包含您选择的工作流文件的分支,已设置为使用该密钥,并在您的浏览器中打开 GitHub,准备创建拉取请求。创建并合并该拉取请求,`@claude` 就可以在仓库中工作。44Claude Code 然后推送一个包含您选择的工作流文件的分支,已设置为使用该密钥,并在您的浏览器中打开 GitHub,准备创建拉取请求。创建并合并该拉取请求,`@claude` 就可以在仓库中工作。

45 45 

46要停止设置过程中途,请按 Esc。已在进行的步骤会完成,之后的步骤不会开始。关闭消息列出了仓库中已发生的事情,例如推送的分支或保存的密钥。

47 

46如果您选择审查工作流,Claude 会在拉取请求本身上发布每个审查,作为它发现的每个问题的内联评论或在它没有发现任何问题时作为一个摘要评论。Claude 会跳过一些拉取请求,例如草稿。[审查工作流示例](#run-a-skill)使用相同的 skill 并列出它们。在 v2.1.229 之前,Claude 仅将其审查写入工作流运行日志。48如果您选择审查工作流,Claude 会在拉取请求本身上发布每个审查,作为它发现的每个问题的内联评论或在它没有发现任何问题时作为一个摘要评论。Claude 会跳过一些拉取请求,例如草稿。[审查工作流示例](#run-a-skill)使用相同的 skill 并列出它们。在 v2.1.229 之前,Claude 仅将其审查写入工作流运行日志。

47 49 

48要更新早期版本生成的审查工作流,请执行以下操作之一:50要更新早期版本生成的审查工作流,请执行以下操作之一:

glossary.md +1 −1

Details

56 Artifact56 Artifact

57</h3>57</h3>

58 58 

59Claude Code 从您的会话发布到 claude.ai 上私有 URL 的实时交互式网页,因此您可以直观地查看输出或共享它,而不是阅读终端文本。当会话重新发布时,页面会就地更新。您从 Claude Code 创建的 Artifacts 出现在与 claude.ai 对话中创建的 artifacts 相同的库中。共享取决于您的计划:在 Pro 和 Max 上,任何人都可以打开的公开链接;在 Team 和 Enterprise 上,在您的组织内共享,以及一旦所有者启用它们就可以公开链接。59Claude Code 从您的会话发布到 claude.ai 上私有 URL 的实时交互式网页,因此您可以直观地查看输出或共享它,而不是阅读终端文本。当会话重新发布时,页面会就地更新。您从 Claude Code 创建的 Artifacts 出现在与 claude.ai 对话中创建的 artifacts 相同的库中。共享选项取决于您的计划:请参阅[共享 artifact](/docs/zh-CN/artifacts#share-an-artifact)。

60 60 

61了解更多:[将会话输出共享为 artifacts](/docs/zh-CN/artifacts)61了解更多:[将会话输出共享为 artifacts](/docs/zh-CN/artifacts)

62 62 

hooks.md +3 −3

Details

274 274 

275来自设置文件、托管策略设置和插件的 Hooks 也在 [subagents](/docs/zh-CN/sub-agents) 内运行。当子代理调用工具时,工具事件(如 `PreToolUse` 和 `PostToolUse`)触发与主对话中相同的配置 hooks,输入包含标识子代理的 `agent_id` 和 `agent_type` [通用输入字段](#common-input-fields)。275来自设置文件、托管策略设置和插件的 Hooks 也在 [subagents](/docs/zh-CN/sub-agents) 内运行。当子代理调用工具时,工具事件(如 `PreToolUse` 和 `PostToolUse`)触发与主对话中相同的配置 hooks,输入包含标识子代理的 `agent_id` 和 `agent_type` [通用输入字段](#common-input-fields)。

276 276 

277企业管理员可以使用 `allowManagedHooksOnly` 来限制哪些 hooks 运行:277管理员可以使用 [`allowManagedHooksOnly`](/docs/zh-CN/settings-reference#allowmanagedhooksonly) 在 [托管设置](/docs/zh-CN/managed-settings) 中限制哪些 hooks 运行:

278 278 

279* 用户、项目、本地和插件 hooks 被阻止。托管设置 `enabledPlugins` 中强制启用的插件中的 Hooks 除外279* 用户、项目、本地和插件 hooks 被阻止。托管设置 `enabledPlugins` 中强制启用的插件中的 Hooks 除外

280* Claude Code 还将 [`statusLine`](/docs/zh-CN/statusline)、[`fileSuggestion`](/docs/zh-CN/settings-reference#filesuggestion) 和 [`subagentStatusLine`](/docs/zh-CN/statusline#subagent-status-lines) 设置限制为托管设置280* Claude Code 还将 [`statusLine`](/docs/zh-CN/statusline)、[`fileSuggestion`](/docs/zh-CN/settings-reference#filesuggestion) 和 [`subagentStatusLine`](/docs/zh-CN/statusline#subagent-status-lines) 设置限制为托管设置


1187| `resume` | `--resume`、`--continue` 或 `/resume` |1187| `resume` | `--resume`、`--continue` 或 `/resume` |

1188| `clear` | `/clear` |1188| `clear` | `/clear` |

1189| `compact` | 自动或手动压缩 |1189| `compact` | 自动或手动压缩 |

1190| `fork` | 从现有会话分叉的新会话:`--fork-session` 与 `--resume` 或 `--continue`、`/fork` 后台副本或 `/branch` |1190| `fork` | 从现有会话分叉的新会话:`--fork-session` 与 `--resume` 或 `--continue`、`/fork` 后台副本、`/branch` 或您 [移到后台](/docs/zh-CN/agent-view#from-inside-a-session) 的对话 |

1191 1191 

1192在 v2.1.214 之前,分叉的会话报告源为 `"resume"`。1192在 v2.1.214 之前,分叉的会话报告源为 `"resume"`。

1193 1193 


2431| `elicitation_url_dialog` | MCP 服务器要求您打开浏览器 URL,您约六秒没有输入 |2431| `elicitation_url_dialog` | MCP 服务器要求您打开浏览器 URL,您约六秒没有输入 |

2432| `elicitation_complete` | MCP 服务器报告 [URL 模式引出](#elicitation-input) 完成 |2432| `elicitation_complete` | MCP 服务器报告 [URL 模式引出](#elicitation-input) 完成 |

2433| `elicitation_response` | MCP 引出响应被发送回服务器 |2433| `elicitation_response` | MCP 引出响应被发送回服务器 |

2434| `agent_needs_input` | 后台会话在 [agent view](/docs/zh-CN/agent-view) 在终端中打开时开始等待您的输入,或当前会话要求您一个 [agent team 队友的终端设置问题](/docs/zh-CN/agent-teams#choose-a-display-mode),您约六秒没有输入 |2434| `agent_needs_input` | 后台会话在 [agent view](/docs/zh-CN/agent-view) 在终端中打开时开始等待您的输入,或当前会话要求您一个 [agent team 队友的终端设置问题](/docs/zh-CN/agent-teams#choose-a-display-mode) 或自动模式的 [分类器请求费用](/docs/zh-CN/auto-mode-classifier-billing) 通知,您约六秒没有输入 |

2435| `agent_completed` | 后台会话完成或失败。仅在 [agent view](/docs/zh-CN/agent-view) 在终端中打开时触发 |2435| `agent_completed` | 后台会话完成或失败。仅在 [agent view](/docs/zh-CN/agent-view) 在终端中打开时触发 |

2436| `quota_auto_resume_fired` | Claude Code 在 claude.ai 使用限制暂停它后继续您的任务:在重置时,或更早当您在 Claude Code 中做的某事(如添加使用信用、升级您的计划或切换模型)在等待期间使使用可用时,带有 [模型设置异常](/docs/zh-CN/interactive-mode#wait-for-a-usage-limit-to-reset) |2436| `quota_auto_resume_fired` | Claude Code 在 claude.ai 使用限制暂停它后继续您的任务:在重置时,或更早当您在 Claude Code 中做的某事(如添加使用信用、升级您的计划或切换模型)在等待期间使使用可用时,带有 [模型设置异常](/docs/zh-CN/interactive-mode#wait-for-a-usage-limit-to-reset) |

2437| `quota_auto_resume_stale` | claude.ai 使用限制在您的计算机睡眠超过约 30 分钟时重置。Claude Code 等待您按 `Enter` 而不是继续。在更短的睡眠后它继续并改为触发 `quota_auto_resume_fired` |2437| `quota_auto_resume_stale` | claude.ai 使用限制在您的计算机睡眠超过约 30 分钟时重置。Claude Code 等待您按 `Enter` 而不是继续。在更短的睡眠后它继续并改为触发 `quota_auto_resume_fired` |

hooks-guide.md +1 −1

Details

196| `elicitation_url_dialog` | MCP 服务器要求你打开浏览器 URL,且你约六秒内没有输入 |196| `elicitation_url_dialog` | MCP 服务器要求你打开浏览器 URL,且你约六秒内没有输入 |

197| `elicitation_complete` | MCP 服务器报告[URL 模式引导](/docs/zh-CN/hooks#elicitation-input)已完成 |197| `elicitation_complete` | MCP 服务器报告[URL 模式引导](/docs/zh-CN/hooks#elicitation-input)已完成 |

198| `elicitation_response` | MCP 引导响应被发送回服务器 |198| `elicitation_response` | MCP 引导响应被发送回服务器 |

199| `agent_needs_input` | 后台会话开始等待你的输入,同时 [agent view](/docs/zh-CN/agent-view) 打开,或当前会话询问你一个[代理团队队友的终端设置问题](/docs/zh-CN/agent-teams#choose-a-display-mode),且你约六秒内没有输入 |199| `agent_needs_input` | 后台会话开始等待你的输入,同时 [agent view](/docs/zh-CN/agent-view) 打开。也在终端会话显示你一个[代理团队队友的终端设置问题](/docs/zh-CN/agent-teams#choose-a-display-mode)或自动模式的[分类器请求费用](/docs/zh-CN/auto-mode-classifier-billing)通知时触发,且你约六秒内没有输入 |

200| `agent_completed` | 后台会话完成或失败。仅在 [agent view](/docs/zh-CN/agent-view) 打开时触发 |200| `agent_completed` | 后台会话完成或失败。仅在 [agent view](/docs/zh-CN/agent-view) 打开时触发 |

201| `quota_auto_resume_fired` | Claude Code 在 claude.ai 使用限制暂停后继续你的任务:在重置时,或更早当你在等待期间在 Claude Code 中做的某些事情(如添加使用额度、升级你的计划或切换模型)使使用量再次可用时,但有[模型设置例外](/docs/zh-CN/interactive-mode#wait-for-a-usage-limit-to-reset) |201| `quota_auto_resume_fired` | Claude Code 在 claude.ai 使用限制暂停后继续你的任务:在重置时,或更早当你在等待期间在 Claude Code 中做的某些事情(如添加使用额度、升级你的计划或切换模型)使使用量再次可用时,但有[模型设置例外](/docs/zh-CN/interactive-mode#wait-for-a-usage-limit-to-reset) |

202| `quota_auto_resume_stale` | claude.ai 使用限制在你的计算机睡眠超过约 30 分钟时重置。Claude Code 等待你按 `Enter` 而不是继续。在较短的睡眠后它继续并改为触发 `quota_auto_resume_fired` |202| `quota_auto_resume_stale` | claude.ai 使用限制在你的计算机睡眠超过约 30 分钟时重置。Claude Code 等待你按 `Enter` 而不是继续。在较短的睡眠后它继续并改为触发 `quota_auto_resume_fired` |

managed-mcp.md +40 −23

Details

31 31 

32| 模式 | 功能 | 配置 |32| 模式 | 功能 | 配置 |

33| :- | :- | :- |33| :- | :- | :- |

34| **禁用 MCP** | 不加载任何服务器,除了[启动会话的应用程序注册的进程内服务器](#exclusive-control-with-managed-mcp-json)和任何你[通过 `managedMcpServers` 提供的服务器](#provide-servers-through-managed-settings) | 使用空服务器映射的 `managed-mcp.json` |34| **禁用 MCP** | 不加载任何服务器,除了[在独占控制下加载](#exclusive-control-with-managed-mcp-json)的少数几个 | 使用空服务器映射的 `managed-mcp.json` |

35| **固定部署** | 每个用户获得相同的服务器,无法添加其他服务器 | 包含你想要的服务器的 `managed-mcp.json` |35| **固定部署** | 每个用户获得相同的服务器,无法添加其他服务器 | 包含你想要的服务器的 `managed-mcp.json` |

36| **提供的服务器** | 每个用户获得你列出的远程服务器,并保留他们自己的服务器 | 托管设置中的 `managedMcpServers` |36| **提供的服务器** | 每个用户获得你列出的远程服务器,并保留他们自己的服务器 | 托管设置中的 `managedMcpServers` |

37| **批准的目录** | 发布批准的服务器列表;用户添加他们想要的服务器,其他任何内容都被阻止 | `allowedMcpServers` + `allowManagedMcpServersOnly: true` |37| **批准的目录** | 发布批准的服务器列表;用户添加他们想要的服务器,其他任何内容都被阻止 | `allowedMcpServers` + `allowManagedMcpServersOnly: true` |


48 使用 managed-mcp.json 进行独占控制48 使用 managed-mcp.json 进行独占控制

49</h2>49</h2>

50 50 

51当你部署 `managed-mcp.json` 文件时,Claude Code 仅加载以下 MCP 服务器:51当你部署 `managed-mcp.json` 文件时,Claude Code 仅加载这些 MCP 服务器:

52 52 

53* 该文件定义的服务器53* 该文件定义的服务器

54* 你[通过 `managedMcpServers` 提供的服务器](#provide-servers-through-managed-settings)54* 你[通过 `managedMcpServers` 提供的服务器](#provide-servers-through-managed-settings)

55* 启动会话的应用注册的进程内服务器,例如 VS Code 扩展自己的服务器或[桌面应用提供的连接器](/docs/zh-CN/mcp#how-connectors-reach-claude-code)55* 启动会话的应用程序注册的进程内服务器,例如 VS Code 扩展自己的服务器或[桌面应用程序提供的连接器](/docs/zh-CN/mcp#how-connectors-reach-claude-code)

56* 内置的[Chrome 中的 Claude](/docs/zh-CN/chrome) 服务器,如果你[允许它与托管集合一起使用](#allow-claude-in-chrome-alongside-the-managed-set)

56 57 

57用户无法添加、修改或使用任何其他 MCP 服务器,包括插件提供的服务器和通过 [`--mcp-config` CLI 标志](/docs/zh-CN/cli-reference#cli-flags)传递的服务器。该文件还会抑制 Claude Code 自身获取的 claude.ai 连接器,除非你[允许它们与托管集合一起使用](#allow-claude-ai-connectors-alongside-the-managed-set)。58用户无法添加、修改或使用任何其他 MCP 服务器,包括插件提供的服务器和通过 [`--mcp-config` CLI 标志](/docs/zh-CN/cli-reference#cli-flags)传递的服务器。该文件还会禁止 Claude Code 自身获取的 claude.ai 连接器,除非你[允许它们与托管集合一起使用](#allow-claude-ai-connectors-alongside-the-managed-set)。

58 59 

59<h3 id="deploy-managed-mcp-json">60<h3 id="deploy-managed-mcp-json">

60 部署 managed-mcp.json61 部署 managed-mcp.json


62 63 

63`managed-mcp.json` 是一个独立文件,因此无法通过[服务器管理的设置](/docs/zh-CN/server-managed-settings)交付。要通过托管设置交付服务器而不进行独占控制,请使用 [`managedMcpServers`](#provide-servers-through-managed-settings)。64`managed-mcp.json` 是一个独立文件,因此无法通过[服务器管理的设置](/docs/zh-CN/server-managed-settings)交付。要通过托管设置交付服务器而不进行独占控制,请使用 [`managedMcpServers`](#provide-servers-through-managed-settings)。

64 65 

65任何可以以管理员权限写入系统路径的进程都可以部署该文件。在整个机队中,这通常通过设备管理工具进行,例如 macOS 上的 Jamf 或配置文件、Windows 上的组策略或 Intune,或 Linux 上你选择的机队管理工具。Claude Code 在以下路径之一查找该文件:66任何可以以管理员权限写入系统路径的进程都可以部署该文件。在整个机队中,这通常通过设备管理工具完成,例如 macOS 上的 Jamf 或配置文件、Windows 上的组策略或 Intune,或 Linux 上你选择的机队管理工具。Claude Code 在以下路径之一查找该文件:

66 67 

67| 平台 | 路径 |68| 平台 | 路径 |

68| :- | :- |69| :- | :- |


99 使用按用户凭证进行身份验证100 使用按用户凭证进行身份验证

100</h3>101</h3>

101 102 

102机器上的任何用户都可以读取此文件,因此不要在 `env` 块中存储 API 密钥或其他凭证。改用以下方式之一传递按用户凭证:103机器上的任何用户都可以读取此文件,因此不要在 `env` 块中存储 API 密钥或其他凭证。改为使用以下方式之一传递按用户凭证:

103 104 

104* [使用 `${VAR}` 扩展](/docs/zh-CN/mcp#environment-variable-expansion-in-mcp-json)从每个用户的环境中读取机密。105* [`${VAR}` 扩展](/docs/zh-CN/mcp#environment-variable-expansion-in-mcp-json)从每个用户的环境中读取机密。

105* [OAuth 或按用户标头](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers),以便每个用户以自己的身份进行身份验证。106* [OAuth 或按用户标头](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers)使每个用户以自己的身份进行身份验证。

106* [`headersHelper`](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication)在连接时生成凭证。107* [`headersHelper`](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication)在连接时生成凭证。

107 108 

108<h3 id="servers-passed-with-mcp-config-or-strict-mcp-config">109<h3 id="servers-passed-with-mcp-config-or-strict-mcp-config">

109 通过 `--mcp-config` 或 `--strict-mcp-config` 传递的服务器110 通过 `--mcp-config` 或 `--strict-mcp-config` 传递的服务器

110</h3>111</h3>

111 112 

112当会话在部署 `managed-mcp.json` 时通过 `--mcp-config` 接收服务器时,用户看到的内容在工作站和云会话之间有所不同:113当会话通过 `--mcp-config` 接收服务器,同时部署了 Claude Code 可以读取和解析的 `managed-mcp.json` 时,用户看到的内容在工作站和云会话之间有所不同:

113 114 

114* 在工作站上,Claude Code 在启动时退出,显示 `You cannot dynamically configure MCP servers when an enterprise MCP config is present`。115* 在工作站上,Claude Code 在启动时退出,显示 `You cannot dynamically configure MCP servers when an enterprise MCP config is present`。

115* 在部署了该文件的主机上的[云会话](/docs/zh-CN/claude-code-on-the-web)中,例如[自托管运行器](/docs/zh-CN/self-hosted-environments-configuration#mcp-servers),Claude Code 仅使用托管服务器启动,并跳过 claude.ai 连接器和云主机通过 `--mcp-config` 交付的其他服务器。会话中没有任何内容告诉用户哪些服务器被遗漏了。Claude Code 在其 stderr 上的警告中命名它们,自托管运行器在 `debug` 日志级别记录这些警告。116* 在[云会话](/docs/zh-CN/claude-code-on-the-web)中,在部署了该文件的主机上,例如[自托管运行器](/docs/zh-CN/self-hosted-environments-configuration#mcp-servers),Claude Code 仅使用托管服务器启动,并跳过 claude.ai 连接器和云主机通过 `--mcp-config` 交付的其他服务器。会话中没有任何内容告诉用户哪些服务器被遗漏了。Claude Code 在其 stderr 上以警告的形式命名它们,自托管运行器在 `debug` 日志级别记录这些警告。

116 117 

117`--strict-mcp-config` 标志要求替换托管集合。如果用户在部署了这样的文件时传递它,Claude Code 在工作站和云会话中都会在启动时退出。118`--strict-mcp-config` 标志要求替换托管集合。如果用户在部署了这样的文件时传递它,Claude Code 在工作站和云会话中都会在启动时退出。

118 119 


125* `deniedMcpServers` 也适用于托管服务器,因此与条目匹配的托管服务器将不会加载。126* `deniedMcpServers` 也适用于托管服务器,因此与条目匹配的托管服务器将不会加载。

126* 用户自己的 `deniedMcpServers` 从他们的设置中合并,因此用户可以为自己阻止托管服务器。127* 用户自己的 `deniedMcpServers` 从他们的设置中合并,因此用户可以为自己阻止托管服务器。

127 128 

128`allowedMcpServers` 不适用于 `managed-mcp.json` 中的服务器,有一个例外:Claude Code 仍然会检查其定义使用 [`${VAR}` 扩展](/docs/zh-CN/mcp#environment-variable-expansion-in-mcp-json)的服务器是否符合允许列表,因为该服务器的有效配置来自每个用户的环境而不是仅来自文件。在 v2.1.259 之前,每个托管服务器在设置了允许列表时都必须通过允许列表。有关哪些字段触发 `${VAR}` 检查和完整检查顺序,请参阅[如何评估服务器](#how-a-server-is-evaluated)。129`allowedMcpServers` 不适用于 `managed-mcp.json` 中的服务器,有一个例外:Claude Code 仍然会针对允许列表检查其定义使用 [`${VAR}` 扩展](/docs/zh-CN/mcp#environment-variable-expansion-in-mcp-json)的服务器,因为该服务器的有效配置来自每个用户的环境而不仅仅来自文件。在 v2.1.259 之前,每个托管服务器在设置了允许列表时都必须通过允许列表。有关哪些字段触发 `${VAR}` 检查和完整检查顺序,请参阅[如何评估服务器](#how-a-server-is-evaluated)。

129 130 

130如果你使用 `allowedMcpServers` 来防止你自己的某些 `managed-mcp.json` 服务器加载,那些服务器将在每个用户首次启动 v2.1.259 或更高版本时开始加载,除非它们使用 `${VAR}` 扩展,没有提示或通知:只有 `deniedMcpServers` 仍然从这些服务器中减去。在用户升级之前,为它们添加拒绝列表条目,或为每个组部署单独的 `managed-mcp.json`。131如果你使用 `allowedMcpServers` 来防止你自己的某些 `managed-mcp.json` 服务器加载,那些服务器将在每个用户首次启动 v2.1.259 或更高版本时开始加载,除非它们使用 `${VAR}` 扩展,没有提示或通知:只有 `deniedMcpServers` 仍然从这些服务器中减去。在用户升级之前,为它们添加拒绝列表条目,或为每个组部署单独的 `managed-mcp.json`。

131 132 


135 136 

136要确认文件生效,请在托管机器上运行两项检查:137要确认文件生效,请在托管机器上运行两项检查:

137 138 

1381. `claude mcp list` 仅显示 `managed-mcp.json` 中的服务器,加上你通过 `managedMcpServers` 提供的任何服务器。两个其他结果意味着出现了问题:1391. `claude mcp list` 仅显示 `managed-mcp.json` 中的服务器,加上你通过 `managedMcpServers` 提供的任何服务器。另外两个结果意味着出现了问题:

139 * 如果用户自己的服务器仍然出现,Claude Code 未读取该文件,因此请检查其路径和父目录的权限。140 * 如果用户自己的服务器仍然出现,Claude Code 没有读取该文件,因此请检查其路径和父目录的权限。

140 * 如果文件的服务器未出现,且 `MCP config diagnostics` 部分将企业配置标记为无法解析,Claude Code 无法读取或解析该文件。修复该部分命名的错误,然后让用户重新启动 Claude Code。141 * 如果文件的服务器没有出现,且 `MCP config diagnostics` 部分将企业配置标记为解析失败,Claude Code 无法读取或解析该文件。修复该部分命名的错误,然后让用户重新启动 Claude Code。

1412. `claude mcp add --transport http test https://example.com/mcp` 失败,显示 `Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers`。URL 不需要是真实服务器,因为策略检查在联系任何内容之前拒绝该命令。1422. `claude mcp add --transport http test https://example.com/mcp` 失败,显示 `Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers`。URL 不需要是真实服务器,因为策略检查在联系任何内容之前拒绝该命令。

142 143 

143<h3 id="disable-mcp-entirely">144<h3 id="disable-mcp-entirely">

144 完全禁用 MCP145 完全禁用 MCP

145</h3>146</h3>

146 147 

147部署包含空服务器映射的 `managed-mcp.json` 以阻止除[启动会话的应用注册的进程内服务器](#exclusive-control-with-managed-mcp-json)之外的每个 MCP 服务器:148部署包含空服务器映射的 `managed-mcp.json` 以阻止除[在独占控制下加载](#exclusive-control-with-managed-mcp-json)的服务器之外的每个 MCP 服务器:

148 149 

149```json theme={null}150```json theme={null}

150{151{


152}153}

153```154```

154 155 

155`claude mcp add` 失败,显示上面的企业策略错误。用户之前配置的服务器在下次启动会话时停止加载,没有警告说明策略是原因。你通过 `managedMcpServers` 提供的服务器仍在空映射下加载,因此也保持该密钥未设置以完全禁用 MCP。156`claude mcp add` 失败,显示上述企业策略错误。用户之前配置的服务器在下次启动会话时停止加载,没有警告说明策略是原因。你通过 `managedMcpServers` 提供的服务器以及你允许与托管集合一起使用的任何其他内容仍然在空映射下加载,因此保持这些键未设置以完全关闭 MCP。

156 157 

157<h3 id="allow-claude-ai-connectors-alongside-the-managed-set">158<h3 id="allow-claude-ai-connectors-alongside-the-managed-set">

158 允许 claude.ai 连接器与托管集合一起使用159 允许 claude.ai 连接器与托管集合一起使用

159</h3>160</h3>

160 161 

161默认情况下,部署 `managed-mcp.json` 会抑制 Claude Code 自身获取的 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai),包括管理员在 claude.ai 管理控制台中为组织配置的连接器。要将这些连接器与 `managed-mcp.json` 中的服务器一起加载,请在[托管设置源](/docs/zh-CN/admin-setup#decide-how-settings-reach-devices)中设置 `"allowAllClaudeAiMcps": true`。162默认情况下,部署 `managed-mcp.json` 会禁止 Claude Code 自身获取的 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai),包括管理员在 claude.ai 管理控制台中为组织配置的连接器。要将这些连接器与 `managed-mcp.json` 中的服务器一起加载,请在[托管设置源](/docs/zh-CN/admin-setup#decide-how-settings-reach-devices)中设置 `"allowAllClaudeAiMcps": true`。

162 163 

163启用该设置后,Claude Code 加载与未部署 `managed-mcp.json` 时相同的 claude.ai 连接器。[允许列表和拒绝列表](#policy-based-control-with-allowlists-and-denylists)仍然适用于这些连接器,因此你可以使用 `deniedMcpServers` 阻止特定连接器。该设置仅影响 Claude Code 自身获取的 claude.ai 连接器;插件提供的服务器保持被抑制。164启用该设置后,Claude Code 加载与未部署 `managed-mcp.json` 时相同的 claude.ai 连接器。[允许列表和拒绝列表](#policy-based-control-with-allowlists-and-denylists)仍然适用于这些连接器,因此你可以使用 `deniedMcpServers` 阻止特定的连接器。该设置仅影响 Claude Code 自身获取的 claude.ai 连接器;插件提供的服务器保持禁止。

164 165 

165云会话和桌面应用的本地和 SSH 会话以另一种方式接收连接器,如[连接器如何到达 Claude Code](/docs/zh-CN/mcp#how-connectors-reach-claude-code) 中所述。运行云会话的主机上的 `managed-mcp.json`,例如[自托管运行器主机](/docs/zh-CN/self-hosted-environments-configuration#mcp-servers),无论你是否设置 `allowAllClaudeAiMcps`,都会抑制该会话的连接器。没有 `managed-mcp.json` 到达桌面应用交付给其本地和 SSH 会话的连接器。166云会话和桌面应用程序的本地和 SSH 会话以另一种方式接收连接器,如[连接器如何到达 Claude Code](/docs/zh-CN/mcp#how-connectors-reach-claude-code) 中所述。运行云会话的主机上的 `managed-mcp.json`,例如[自托管运行器主机](/docs/zh-CN/self-hosted-environments-configuration#mcp-servers),无论你是否设置 `allowAllClaudeAiMcps`,都会禁止该会话的连接器。没有 `managed-mcp.json` 到达桌面应用程序交付给其本地和 SSH 会话的连接器。

166 167 

167Claude Code 仅从管理员控制的策略层读取 `allowAllClaudeAiMcps`:服务器管理的设置、MDM 部署的 plist 或 HKLM 注册表密钥,或系统 `managed-settings.json` 文件。将其放在用户或项目设置中无效,因此用户无法重新启用独占控制抑制的连接器。168Claude Code 仅从管理员控制的策略层读取 `allowAllClaudeAiMcps`:服务器管理的设置、MDM 部署的 plist 或 HKLM 注册表项,或系统 `managed-settings.json` 文件。将其放在用户或项目设置中无效,因此用户无法重新启用独占控制禁止的连接器。

169 

170<h3 id="allow-claude-in-chrome-alongside-the-managed-set">

171 允许 Chrome 中的 Claude 与托管集合一起使用

172</h3>

173 

174默认情况下,当你部署 `managed-mcp.json` 时,Claude Code 在终端会话中阻止内置的[Chrome 中的 Claude](/docs/zh-CN/chrome) 服务器。用户不会获得[扩展安装提示](/docs/zh-CN/chrome#install-the-extension-when-claude-asks),以及用户[默认启用 Chrome](/docs/zh-CN/chrome#enable-chrome-by-default) 的会话启动时不使用 Chrome 且不打印警告。当可以运行 Chrome 中的 Claude 的用户使用 `claude --chrome` 或 `CLAUDE_CODE_ENABLE_CFC=1` 启动它时,Claude Code 在启动时退出,显示命名 `allowClaudeInChromeWithManagedMcp` 设置的错误。

175 

176要让用户在 `managed-mcp.json` 中的服务器旁边运行 Chrome 中的 Claude,请在设备自己的托管设置中设置 `"allowClaudeInChromeWithManagedMcp": true`。将其放在 MDM 部署的 plist 或 HKLM 注册表项中,或系统 `managed-settings.json` 文件中,无论 Claude Code 在该设备上[选择](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)哪个。需要 Claude Code v2.1.282 或更高版本。在 v2.1.282 之前,Claude Code 忽略该设置,启动错误读取 `You cannot dynamically configure MCP servers when an enterprise MCP config is present`。

177 

178Claude Code 从这些设备源读取该设置,即使[服务器管理的设置](/docs/zh-CN/server-managed-settings)交付你的其余策略。它忽略服务器管理的设置本身、用户可写的 HKCU 注册表和用户或项目设置中的该设置。[`deniedMcpServers`](#policy-based-control-with-allowlists-and-denylists) 条目中的 `claude-in-chrome` 仍然会阻止该服务器,即使该设置已启用。

168 179 

169<h2 id="provide-servers-through-managed-settings">180<h2 id="provide-servers-through-managed-settings">

170 通过托管设置提供服务器181 通过托管设置提供服务器


303 314 

304| 设置 | 未设置(默认) | 空数组 `[]` | 已填充 |315| 设置 | 未设置(默认) | 空数组 `[]` | 已填充 |

305| :- | :- | :- | :- |316| :- | :- | :- | :- |

306| `allowedMcpServers` | 允许所有服务器 | 不允许任何服务器,除了[组织自己的](#how-a-server-is-evaluated) | 仅允许匹配的服务器,除了[组织自己的](#how-a-server-is-evaluated) |317| `allowedMcpServers` | 允许所有服务器 | 不允许任何服务器,除了[那些跳过允许列表检查的](#how-a-server-is-evaluated) | 仅允许匹配的服务器,除了[那些跳过允许列表检查的](#how-a-server-is-evaluated) |

307| `deniedMcpServers` | 不阻止任何服务器 | 不阻止任何服务器 | 阻止匹配的服务器 |318| `deniedMcpServers` | 不阻止任何服务器 | 不阻止任何服务器 | 阻止匹配的服务器 |

308 319 

309有关条目未通过架构验证时会发生什么,请参阅[托管设置中的无效条目](/docs/zh-CN/managed-settings#invalid-entries-in-managed-settings)。320有关条目未通过架构验证时会发生什么,请参阅[托管设置中的无效条目](/docs/zh-CN/managed-settings#invalid-entries-in-managed-settings)。


3292. **检查拒绝列表。** 与任何拒绝列表条目匹配的服务器(按 URL、命令或名称)被阻止。没有任何东西可以覆盖拒绝列表匹配。3402. **检查拒绝列表。** 与任何拒绝列表条目匹配的服务器(按 URL、命令或名称)被阻止。没有任何东西可以覆盖拒绝列表匹配。

3303. **检查允许列表。** 如果 `allowedMcpServers` 未在任何地方设置,每个通过拒绝列表的服务器都会加载。如果已设置,服务器必须匹配的内容取决于其类型,如下表所示。3413. **检查允许列表。** 如果 `allowedMcpServers` 未在任何地方设置,每个通过拒绝列表的服务器都会加载。如果已设置,服务器必须匹配的内容取决于其类型,如下表所示。

331 342 

332 组织自己的服务器跳过此检查:每个 `managedMcpServers` 条目,以及任何 `managed-mcp.json` 条目,其值不使用 `${VAR}` 展开。内置服务器也跳过它,例如 Chrome 中的 Claude、Claude Code 在运行的 VS Code 或 JetBrains IDE 中连接的 `ide` 服务器,以及 CLI 本身配置的服务器。343 三组服务器跳过此检查:

344 

345 * 组织自己的服务器:每个 `managedMcpServers` 条目,以及任何 `managed-mcp.json` 条目,其值不使用 `${VAR}` 展开。

346 * 内置服务器,例如 Chrome 中的 Claude、Claude Code 在运行的 VS Code 或 JetBrains IDE 中连接的 `ide` 服务器,以及 CLI 本身配置的服务器。

347 * [Claude Tag](/docs/zh-CN/claude-tag) 会话的 Slack 工具:它用来读取线程和发布回复的服务器无需允许列表条目即可加载。

333 348 

334 使用 `${VAR}` 展开的 `managed-mcp.json` 服务器在其命令、参数、`env`、URL 或标头中仍会被检查,用户、插件、`--mcp-config` 或 claude.ai 添加的每个服务器也是如此。349 使用 `${VAR}` 展开的 `managed-mcp.json` 服务器在其命令、参数、`env`、URL 或标头中仍会被检查。用户、插件或 claude.ai 添加的每个服务器也是如此,以及用户通过 `--mcp-config` 传递的每个服务器。

335 350 

336| 服务器类型 | 匹配时允许 |351| 服务器类型 | 匹配时允许 |

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


514| 限制 | 用户看到的内容 |529| 限制 | 用户看到的内容 |

515| :- | :- |530| :- | :- |

516| `managed-mcp.json` 存在且用户运行 `claude mcp add` | `Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers` |531| `managed-mcp.json` 存在且用户运行 `claude mcp add` | `Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers` |

532| `managed-mcp.json` 存在且可以在 Chrome 中运行 Claude 的用户运行 `claude --chrome` | Claude Code 在启动时退出,显示 `Claude in Chrome is blocked by your organization's managed MCP configuration (managed-mcp.json). An administrator can allow it with allowClaudeInChromeWithManagedMcp in device policy.` |

517| 服务器在拒绝列表上且用户运行 `claude mcp add` | `Cannot add MCP server "<name>": server is explicitly blocked by enterprise policy` |533| 服务器在拒绝列表上且用户运行 `claude mcp add` | `Cannot add MCP server "<name>": server is explicitly blocked by enterprise policy` |

518| 服务器不在允许列表上且用户运行 `claude mcp add` | `Cannot add MCP server "<name>": not allowed by enterprise policy` |534| 服务器不在允许列表上且用户运行 `claude mcp add` | `Cannot add MCP server "<name>": not allowed by enterprise policy` |

519| 用户在来自 `managedMcpServers` 的服务器上运行 `claude mcp remove` | `MCP server "<name>" is provided by your organization (managed settings) and cannot be removed locally.` |535| 用户在来自 `managedMcpServers` 的服务器上运行 `claude mcp remove` | `MCP server "<name>" is provided by your organization (managed settings) and cannot be removed locally.` |


541| `allowedMcpServers` | 允许的服务器允许列表 | 任何[设置范围](/docs/zh-CN/settings#where-settings-live);[服务器如何被评估](#how-a-server-is-evaluated)说明来自多个范围和托管源的列表如何组合 | 为了强制执行,一个[托管设置源](/docs/zh-CN/admin-setup#decide-how-settings-reach-devices):服务器管理的设置、`managed-settings.json`、MDM 配置文件或注册表 |557| `allowedMcpServers` | 允许的服务器允许列表 | 任何[设置范围](/docs/zh-CN/settings#where-settings-live);[服务器如何被评估](#how-a-server-is-evaluated)说明来自多个范围和托管源的列表如何组合 | 为了强制执行,一个[托管设置源](/docs/zh-CN/admin-setup#decide-how-settings-reach-devices):服务器管理的设置、`managed-settings.json`、MDM 配置文件或注册表 |

542| `deniedMcpServers` | 被阻止的服务器拒绝列表 | 任何设置范围;[服务器如何被评估](#how-a-server-is-evaluated)说明来自多个范围和托管源的列表如何组合 | 与 `allowedMcpServers` 相同 |558| `deniedMcpServers` | 被阻止的服务器拒绝列表 | 任何设置范围;[服务器如何被评估](#how-a-server-is-evaluated)说明来自多个范围和托管源的列表如何组合 | 与 `allowedMcpServers` 相同 |

543| `allowManagedMcpServersOnly` | 将允许列表锁定为仅托管源 | 仅托管设置源;[从每个管理源读取的密钥](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)说明哪些托管源可以打开它。该设置在其他范围中无效 | 与 `allowedMcpServers` 相同 |559| `allowManagedMcpServersOnly` | 将允许列表锁定为仅托管源 | 仅托管设置源;[从每个管理源读取的密钥](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)说明哪些托管源可以打开它。该设置在其他范围中无效 | 与 `allowedMcpServers` 相同 |

560| `allowClaudeInChromeWithManagedMcp` | 让内置的 Chrome 中的 Claude 服务器与 `managed-mcp.json` 一起运行 | 设备上的托管设置:MDM 配置文件、HKLM 注册表或 `managed-settings.json`。服务器管理的设置和用户可写源无效 | MDM、GPO、舰队管理或任何具有管理员权限的进程 |

544| `allowAllClaudeAiMcps` | 加载 claude.ai 连接器,Claude Code 自身与 `managed-mcp.json` 一起获取。[在运行云会话的主机上的 `managed-mcp.json` 仍然会抑制该会话的连接器](#allow-claude-ai-connectors-alongside-the-managed-set) | 仅托管设置源;该设置在其他地方无效 | 与 `allowedMcpServers` 相同 |561| `allowAllClaudeAiMcps` | 加载 claude.ai 连接器,Claude Code 自身与 `managed-mcp.json` 一起获取。[在运行云会话的主机上的 `managed-mcp.json` 仍然会抑制该会话的连接器](#allow-claude-ai-connectors-alongside-the-managed-set) | 仅托管设置源;该设置在其他地方无效 | 与 `allowedMcpServers` 相同 |

545 562 

546<h2 id="related-resources">563<h2 id="related-resources">

Details

449| [`blockedMarketplaces`](/docs/zh-CN/settings-reference#blockedmarketplaces) | 市场源的阻止列表。被阻止的源在下载前被检查,因此它们永远不会接触文件系统。请参阅[托管市场限制](/docs/zh-CN/plugins/org#restrict-what-users-can-install) |449| [`blockedMarketplaces`](/docs/zh-CN/settings-reference#blockedmarketplaces) | 市场源的阻止列表。被阻止的源在下载前被检查,因此它们永远不会接触文件系统。请参阅[托管市场限制](/docs/zh-CN/plugins/org#restrict-what-users-can-install) |

450| [`channelsEnabled`](/docs/zh-CN/settings-reference#channelsenabled) | 允许组织的[通道](/docs/zh-CN/channels)。请参阅[企业控制](/docs/zh-CN/channels#enterprise-controls)以获取每个计划上的默认值 |450| [`channelsEnabled`](/docs/zh-CN/settings-reference#channelsenabled) | 允许组织的[通道](/docs/zh-CN/channels)。请参阅[企业控制](/docs/zh-CN/channels#enterprise-controls)以获取每个计划上的默认值 |

451| [`disableCommandPluginSources`](/docs/zh-CN/settings-reference#disablecommandpluginsources) | 当 `true` 时,完全阻止[`command` 插件源](/docs/zh-CN/plugins/marketplace-reference#command-plugin-source),因此市场声明的命令永远不会运行。也阻止市场[`headersHelper` 命令](/docs/zh-CN/plugins/host-marketplace#authenticate-archive-downloads),除了托管设置本身声明的市场。未设置时,遵循 `allowManagedHooksOnly`。需要 Claude Code v2.1.229 或更高版本,`headersHelper` 块需要 v2.1.238 或更高版本 |451| [`disableCommandPluginSources`](/docs/zh-CN/settings-reference#disablecommandpluginsources) | 当 `true` 时,完全阻止[`command` 插件源](/docs/zh-CN/plugins/marketplace-reference#command-plugin-source),因此市场声明的命令永远不会运行。也阻止市场[`headersHelper` 命令](/docs/zh-CN/plugins/host-marketplace#authenticate-archive-downloads),除了托管设置本身声明的市场。未设置时,遵循 `allowManagedHooksOnly`。需要 Claude Code v2.1.229 或更高版本,`headersHelper` 块需要 v2.1.238 或更高版本 |

452| [`disableSideloadFlags`](/docs/zh-CN/settings-reference#disablesideloadflags) | 在启动时拒绝 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` 标志。在云会话中,Claude Code 删除服务器通过 `--mcp-config` 交付的 MCP 服务器,除了进程内 `type: "sdk"` 条目,并启动会话。需要 Claude Code v2.1.193 或更高版本 |452| [`disableSideloadFlags`](/docs/zh-CN/settings-reference#disablesideloadflags) | 在启动时拒绝 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` 标志。在云会话中,Claude Code 删除服务器通过 `--mcp-config` 交付的 MCP 服务器,除了其[参考条目](/docs/zh-CN/settings-reference#disablesideloadflags)列出的异常,并启动会话。需要 Claude Code v2.1.193 或更高版本 |

453| [`forceRemoteSettingsRefresh`](/docs/zh-CN/settings-reference#forceremotesettingsrefresh) | 当 `true` 时,阻止 CLI 启动,直到远程托管设置被新鲜获取,如果获取失败则退出。请参阅[失败关闭强制执行](/docs/zh-CN/server-managed-settings#enforce-fail-closed-startup) |453| [`forceRemoteSettingsRefresh`](/docs/zh-CN/settings-reference#forceremotesettingsrefresh) | 当 `true` 时,阻止 CLI 启动,直到远程托管设置被新鲜获取,如果获取失败则退出。请参阅[失败关闭强制执行](/docs/zh-CN/server-managed-settings#enforce-fail-closed-startup) |

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

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

memory.md +6 −0

Details

115 115 

116允许相对路径和绝对路径。相对路径相对于包含导入的文件解析,而不是工作目录。导入的文件可以递归导入其他文件,最大深度为四跳。116允许相对路径和绝对路径。相对路径相对于包含导入的文件解析,而不是工作目录。导入的文件可以递归导入其他文件,最大深度为四跳。

117 117 

118要导入其路径包含空格的文件,请在每个空格前放置反斜杠。没有反斜杠,路径在第一个空格处结束,即使导入在其自己的行上。用引号包装的路径根本不导入,无论是否有反斜杠。此导入从名为 `Design Docs` 的文件夹加载文件:

119 

120```text theme={null}

121- API conventions @Design\ Docs/api-conventions.md

122```

123 

118导入解析跳过 Markdown 代码跨度和围栏代码块。要在您的 CLAUDE.md 中提及路径而不导入它,请将其包装在反引号中:编写 `` `@README` `` 保持文本字面,而 `@README` 在反引号外导入文件。124导入解析跳过 Markdown 代码跨度和围栏代码块。要在您的 CLAUDE.md 中提及路径而不导入它,请将其包装在反引号中:编写 `` `@README` `` 保持文本字面,而 `@README` 在反引号外导入文件。

119 125 

120要引入 README、package.json 和工作流指南,请在 CLAUDE.md 中的任何地方使用 `@` 语法引用它们:126要引入 README、package.json 和工作流指南,请在 CLAUDE.md 中的任何地方使用 `@` 语法引用它们:

model-config.md +7 −9

Details

65别名指向你的提供商的推荐版本,并随时间更新。要固定到特定版本,请使用完整模型名称,例如 `claude-opus-5-5`,或设置相应的环境变量,如 `ANTHROPIC_DEFAULT_OPUS_MODEL`。65别名指向你的提供商的推荐版本,并随时间更新。要固定到特定版本,请使用完整模型名称,例如 `claude-opus-5-5`,或设置相应的环境变量,如 `ANTHROPIC_DEFAULT_OPUS_MODEL`。

66 66 

67<Note>67<Note>

68 Sonnet 5.5 需要 Claude Code v2.1.284 或更高版本,Opus 5.5 需要 v2.1.280 或更高版本。运行 `claude update` 进行升级。68 Sonnet 5.5 需要 Claude Code v2.1.284 或更高版本,Opus 5.5 需要 v2.1.280 或更高版本。如果来自较旧版本的请求失败,请参阅 [Claude Code does not support this model](/docs/zh-CN/errors#claude-code-does-not-support-this-model)。运行 `claude update` 进行升级。

69</Note>69</Note>

70 70 

71<h3 id="work-with-fable">71<h3 id="work-with-fable">


164 164 

165当 Claude Code 无法判断你的组织的[托管插件](/docs/zh-CN/settings-reference#enabledplugins)提供哪些 PreModelSwitch hooks 时,例如因为托管插件加载失败,它拒绝切换而不是应用它,并在每次新尝试时再次检查。参阅 [Model switch was blocked by a PreModelSwitch hook](/docs/zh-CN/errors#model-switch-was-blocked-by-a-premodelswitch-hook) 了解消息和恢复。165当 Claude Code 无法判断你的组织的[托管插件](/docs/zh-CN/settings-reference#enabledplugins)提供哪些 PreModelSwitch hooks 时,例如因为托管插件加载失败,它拒绝切换而不是应用它,并在每次新尝试时再次检查。参阅 [Model switch was blocked by a PreModelSwitch hook](/docs/zh-CN/errors#model-switch-was-blocked-by-a-premodelswitch-hook) 了解消息和恢复。

166 166 

167当你通过 [Agent SDK](/docs/zh-CN/agent-sdk/overview) `setModel()` 方法或从通过 [Remote Control](/docs/zh-CN/remote-control) 连接的设备切换模型,或运行 Claude Code CLI 的应用(如 [Desktop app](/docs/zh-CN/desktop))为你切换时,Claude Code 会检查该字符串是否是它识别的。此检查需要 Claude Code v2.1.200 或更高版本。检查 Remote Control 选择需要你的机器上的 Claude Code v2.1.260 或更高版本。在 Anthropic API 上,Claude Code 识别:167当你通过 [Agent SDK](/docs/zh-CN/agent-sdk/overview) `setModel()` 方法、通过 [Remote Control](/docs/zh-CN/remote-control) 连接的设备或运行 Claude Code CLI 的应用(如 [Desktop app](/docs/zh-CN/desktop))切换模型时,Claude Code 会检查该值在切换时:

168 168 

169* 一个模型别名169* **Agent SDK 或应用**:使用 Claude Code v2.1.268 或更高版本,除非 Claude Code 在本地接受模型 ID(如它对你的[自定义模型选项](#add-a-custom-model-option)所做的那样),它在会话首次切换到它时与你的提供商确认该 ID。确认在每个提供商上运行,你的提供商不提供的 ID 在切换时被拒绝,而不是在你的下一个请求时失败。

170* `/model` 选择器中的一个条目170* **Remote Control**:在 Anthropic API 上,Claude Code 在本地检查该值并不发送请求。

171* 任何以 `claude-` 开头的名称

172* 你自己配置的值,作为[自定义模型选项](#add-a-custom-model-option)或在 [`modelOverrides`](#override-model-ids-per-version) 中

173 171 

174Claude Code 拒绝无法识别的字符串,显示 `Model "<name>" is not a recognized model id.`,会话保持其当前模型,而不是保存字符串并在下一个请求时失败。参阅[错误参考](/docs/zh-CN/errors#model-is-not-a-recognized-model-id)了解恢复步骤。172参阅 [Model is not a recognized model id](/docs/zh-CN/errors#model-is-not-a-recognized-model-id) 和 [Model not found](/docs/zh-CN/errors#model-not-found) 了解消息。

175 173 

176检查仅在 Anthropic API 上运行。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和 [LLM 网关](/docs/zh-CN/llm-gateway) 后面或自定义 `ANTHROPIC_BASE_URL`,你的提供商或网关定义模型名称,所以 Claude Code 不检查地通过任何字符串。检查也不涵盖 `--model` 标志、`ANTHROPIC_MODEL` 环境变量或 `model` 设置;那里的拼写错误值会在第一个请求时产生 [There's an issue with the selected model](/docs/zh-CN/errors#theres-an-issue-with-the-selected-model)。Claude Code 仍然可以在请求时在每个提供商上写入[无法识别的模型诊断行](/docs/zh-CN/errors#unrecognized-model-id-on-a-request)。174如果你使用 `--model` 标志、`ANTHROPIC_MODEL` 环境变量或 `model` 设置设置模型,Claude Code 不会提前检查它,拼写错误的值会在第一个请求时产生 [There's an issue with the selected model](/docs/zh-CN/errors#theres-an-issue-with-the-selected-model)。

177 175 

178当请求的模型有计划的停用日期或自动重新映射到较新版本时,Claude Code 显示一个警告,命名请求的模型。交互式会话将其显示为启动通知。从 v2.1.182 开始,在使用默认文本输出格式的[非交互模式](/docs/zh-CN/headless)中,相同的警告被写入 stderr。检查也涵盖在[子代理前言](/docs/zh-CN/sub-agents)中设置的 `model`。对于 `--output-format json` 和 `stream-json`,stderr 警告被抑制;从[结果消息](/docs/zh-CN/headless#get-structured-output)的 `modelUsage` 字段读取实际模型。176当请求的模型有计划的停用日期或自动重新映射到较新版本时,Claude Code 显示一个警告,命名请求的模型。交互式会话将其显示为启动通知。从 v2.1.182 开始,在使用默认文本输出格式的[非交互模式](/docs/zh-CN/headless)中,相同的警告被写入 stderr。检查也涵盖在[子代理前言](/docs/zh-CN/sub-agents)中设置的 `model`。对于 `--output-format json` 和 `stream-json`,stderr 警告被抑制;从[结果消息](/docs/zh-CN/headless#get-structured-output)的 `modelUsage` 字段读取实际模型。

179 177 


751| 设置全局默认值 | 运行 `/config` 并切换思考模式。保存为 `~/.claude/settings.json` 中的 `alwaysThinkingEnabled` |749| 设置全局默认值 | 运行 `/config` 并切换思考模式。保存为 `~/.claude/settings.json` 中的 `alwaysThinkingEnabled` |

752| 通过环境变量禁用 | 设置 [`MAX_THINKING_TOKENS=0`](/docs/zh-CN/env-vars),这在 Anthropic API 上关闭思考,除了 Opus 5.5、Sonnet 5.5 和 Fable 模型。在[第三方提供商](/docs/zh-CN/third-party-integrations)上,Claude Code 改为省略 `thinking` 参数,自适应推理模型可能仍然思考。其他值仅适用于[固定思考预算](#adaptive-reasoning-and-fixed-thinking-budgets) |750| 通过环境变量禁用 | 设置 [`MAX_THINKING_TOKENS=0`](/docs/zh-CN/env-vars),这在 Anthropic API 上关闭思考,除了 Opus 5.5、Sonnet 5.5 和 Fable 模型。在[第三方提供商](/docs/zh-CN/third-party-integrations)上,Claude Code 改为省略 `thinking` 参数,自适应推理模型可能仍然思考。其他值仅适用于[固定思考预算](#adaptive-reasoning-and-fixed-thinking-budgets) |

753 751 

754您不能在 Opus 5.5、Sonnet 5.5 或 Fable 模型上关闭思考。会话切换、`alwaysThinkingEnabled` 和 `MAX_THINKING_TOKENS=0` 在那里没有效果,模型根据努力级别按步骤决定思考多少。752您不能在 Opus 5.5、Sonnet 5.5 或 Fable 模型上关闭思考。会话切换和 `/config` 行显示 `Thinking can't be turned off` 对于这些模型,而不是提供切换,保存的 `alwaysThinkingEnabled: false` 或 `MAX_THINKING_TOKENS=0` 在那里没有效果。在这些模型上,模型根据努力级别按步骤决定思考多少。保存的设置在您切换到接受它的模型时再次应用。

755 753 

756Claude Code 默认折叠思考输出。按 `Ctrl+O` 切换详细模式并将推理视为灰色斜体文本。Anthropic API 上的交互式会话默认接收编辑的思考块,因此如果您想要完整摘要在展开时可用,在[设置](/docs/zh-CN/settings)中设置 `showThinkingSummaries: true`。您需要为所有生成的思考令牌付费,即使折叠或编辑。754Claude Code 默认折叠思考输出。按 `Ctrl+O` 切换详细模式并将推理视为灰色斜体文本。Anthropic API 上的交互式会话默认接收编辑的思考块,因此如果您想要完整摘要在展开时可用,在[设置](/docs/zh-CN/settings)中设置 `showThinkingSummaries: true`。您需要为所有生成的思考令牌付费,即使折叠或编辑。

757 755 

Details

64}64}

65```65```

66 66 

67在 Claude Desktop 应用中,Code 标签页会话从 [到达每种 Desktop 会话的源](/docs/zh-CN/desktop#managed-settings) 读取这些托管设置。Cowork 在管理员控制台的 [数据和隐私设置](https://claude.ai/admin-settings/data-privacy-controls) 中的 **监控** 下的 OpenTelemetry 表单仅适用于 Cowork 会话,因此终端 CLI 和 Code 标签页都不会导出到您在那里设置的收集器。

68 

67Claude Code 忽略存储库的 `.claude/settings.json` 和 `.claude/settings.local.json` 中的 [OpenTelemetry 导出器变量](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env),因此存储库无法使用它们来打开遥测、选择其去向或捕获内容。在托管设置中设置它们,或让每个开发者在其 shell 或 `~/.claude/settings.json` 中设置它们。存储库仍然可以通过将其导出器选择器(如 `OTEL_LOGS_EXPORTER`)设置为 `none` 来关闭信号,除非托管设置、`--settings` 文件或启动 Claude Code 的环境设置了该变量。69Claude Code 忽略存储库的 `.claude/settings.json` 和 `.claude/settings.local.json` 中的 [OpenTelemetry 导出器变量](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env),因此存储库无法使用它们来打开遥测、选择其去向或捕获内容。在托管设置中设置它们,或让每个开发者在其 shell 或 `~/.claude/settings.json` 中设置它们。存储库仍然可以通过将其导出器选择器(如 `OTEL_LOGS_EXPORTER`)设置为 `none` 来关闭信号,除非托管设置、`--settings` 文件或启动 Claude Code 的环境设置了该变量。

68 70 

69Claude Code 不会将 `OTEL_*` 环境变量传递给它生成的子进程,包括 Bash 工具、hooks、MCP 服务器和语言服务器。通过 Bash 工具运行的已进行 OpenTelemetry 检测的应用程序不会继承 Claude Code 的导出器端点或标头,因此如果该应用程序需要导出自己的遥测,请直接在命令中设置这些变量。71Claude Code 不会将 `OTEL_*` 环境变量传递给它生成的子进程,包括 Bash 工具、hooks、MCP 服务器和语言服务器。通过 Bash 工具运行的已进行 OpenTelemetry 检测的应用程序不会继承 Claude Code 的导出器端点或标头,因此如果该应用程序需要导出自己的遥测,请直接在命令中设置这些变量。

Details

526 * 在具有[服务器端分类器审查](#server-side-classifier-review)的会话中,只读和[沙箱](/docs/zh-CN/sandboxing#sandbox-modes) shell 命令等待该审查并在其标记时被阻止526 * 在具有[服务器端分类器审查](#server-side-classifier-review)的会话中,只读和[沙箱](/docs/zh-CN/sandboxing#sandbox-modes) shell 命令等待该审查并在其标记时被阻止

527 * 工作目录内的写入,[符号链接检查](/docs/zh-CN/permissions#symlinks)解决为其外的位置,提示您527 * 工作目录内的写入,[符号链接检查](/docs/zh-CN/permissions#symlinks)解决为其外的位置,提示您

528 3. 其他所有内容都进入分类器,除了[关键路径删除](#critical-paths)在其默认处理下。在步骤 1 中直接提示您的连接器工具和`requiresUserInteraction` MCP 工具永远不会到达分类器,因此既不是组织要求的批准也不是同意步骤被自动批准528 3. 其他所有内容都进入分类器,除了[关键路径删除](#critical-paths)在其默认处理下。在步骤 1 中直接提示您的连接器工具和`requiresUserInteraction` MCP 工具永远不会到达分类器,因此既不是组织要求的批准也不是同意步骤被自动批准

529 4. 如果分类器阻止,Claude 收到原因并尝试替代方案。在大多数会话中,原因命名分类器匹配的规则,例如 `[Data Exfiltration]`,而不是给出书面解释;请参阅[审查拒绝](/docs/zh-CN/auto-mode-config#review-denials)529 4. 如果分类器阻止,Claude 收到原因。在大多数会话中,原因命名分类器匹配的规则,例如 `[Data Exfiltration]`,而不是给出书面解释;请参阅[审查拒绝](/docs/zh-CN/auto-mode-config#review-denials)

530 530 

531 进入自动模式时,授予任意代码执行的广泛允许规则被丢弃:531 进入自动模式时,授予任意代码执行的广泛允许规则被丢弃:

532 532 

Details

121 121 

122在您的终端中,插件仅在您使用 claude.ai 账户登录的会话中同步。122在您的终端中,插件仅在您使用 claude.ai 账户登录的会话中同步。

123 123 

124Claude Code 在这些终端会话中既不下载也不加载同步插件,即使您使用 `/login` 登录后也是如此:

125 

126* 一个会话,其中 `ANTHROPIC_AUTH_TOKEN`、`CLAUDE_CODE_OAUTH_TOKEN` 或 `apiKeyHelper` 脚本提供凭证来代替该登录

127* 一个不[从 Anthropic 获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话,例如您设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 的会话

128* 一个处于[裸模式](/docs/zh-CN/headless#start-faster-with-bare-mode)的会话或您使用 `--safe-mode` 启动的会话

129* 一个您使用[`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags)列表启动的会话,该列表遗漏了 `user`

130 

124如果您在早期版本的 Claude Code 上登录,该登录不会覆盖插件,直到 Claude Code 在后台续期。要更快获得访问权限,请再次运行 `/login`。插件同步然后在下次启动 Claude Code 时开始。131如果您在早期版本的 Claude Code 上登录,该登录不会覆盖插件,直到 Claude Code 在后台续期。要更快获得访问权限,请再次运行 `/login`。插件同步然后在下次启动 Claude Code 时开始。

125 132 

126<h4 id="control-which-synced-plugins-load">133<h4 id="control-which-synced-plugins-load">

remote-control.md +35 −35

Details

48 claude remote-control48 claude remote-control

49 ```49 ```

50 50 

51 在您接受远程控制的一次性确认之前,`claude remote-control` 会解释它的作用并在启动服务器之前询问 `Enable Remote Control? (y/n)`。回答 `y` 以接受并启动服务器。如果您拒绝,Claude Code 将退出而不启动服务器,并在您下次运行该命令时再次询问。51 在您接受远程控制的一次性确认之前,`claude remote-control` 会解释它的作用,并在启动服务器之前询问 `Enable Remote Control? (y/n)`。回答 `y` 以接受并启动服务器。如果您拒绝,Claude Code 将退出而不启动服务器,并在您下次运行该命令时再次询问。

52 52 

53 该进程在您的终端中以服务器模式保持运行,等待远程连接。它显示一个会话 URL,您可以使用该 URL 从[另一台设备连接](#connect-from-another-device),您可以按空格键显示 QR 码以从您的手机快速访问。当远程会话处于活动状态时,终端显示连接状态和工具活动。53 该进程在您的终端中以服务器模式保持运行,等待远程连接。它显示一个会话 URL,您可以使用该 URL 从[另一台设备连接](#connect-from-another-device),您可以按空格键显示 QR 码以便从手机快速访问。当远程会话处于活动状态时,终端显示连接状态和工具活动。

54 54 

55 可用标志:55 可用标志:

56 56 

57 | 标志 | 描述 |57 | 标志 | 描述 |

58 | - | - |58 | - | - |

59 | `--name "My Project"` | 设置自定义会话标题,在 claude.ai/code 的会话列表中可见。 |59 | `--name "My Project"` | 设置自定义会话标题,在 claude.ai/code 的会话列表中可见。 |

60 | `--remote-control-session-name-prefix <prefix>` | 当未设置显式名称时,自动生成的会话名称的前缀。默认为您的机器主机名,生成类似 `myhost-graceful-unicorn` 的名称。设置 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以获得相同效果。 |60 | `--remote-control-session-name-prefix <prefix>` | 当未设置显式名称时,自动生成的会话名称的前缀。默认为您机器的主机名,生成类似 `myhost-graceful-unicorn` 的名称。设置 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 可获得相同效果。 |

61 | `-c`, `--continue` | 恢复此目录中最后一个服务器启动的会话,而不是创建新会话。请参阅[停止服务器后恢复会话](#resume-sessions-after-stopping-the-server)。不能与 `--session-id`、`--spawn`、`--capacity` 或 `--create-session-in-dir` 结合使用。需要 Claude Code v2.1.200 或更高版本。 |61 | `-c`, `--continue` | 恢复此目录中最后一个服务器启动的会话,而不是创建新会话。请参阅[停止服务器后恢复会话](#resume-sessions-after-stopping-the-server)。不能与 `--session-id`、`--spawn`、`--capacity` 或 `--create-session-in-dir` 结合使用。需要 Claude Code v2.1.200 或更高版本。 |

62 | `--session-id <id>` | 按其 ID 恢复一个会话。请参阅[停止服务器后恢复会话](#resume-sessions-after-stopping-the-server)。不能与 `--continue`、`--spawn`、`--capacity` 或 `--create-session-in-dir` 结合使用。需要 Claude Code v2.1.200 或更高版本。 |62 | `--session-id <id>` | 按其 ID 恢复一个会话。请参阅[停止服务器后恢复会话](#resume-sessions-after-stopping-the-server)。不能与 `--continue`、`--spawn`、`--capacity` 或 `--create-session-in-dir` 结合使用。需要 Claude Code v2.1.200 或更高版本。 |

63 | `--spawn <mode>` | 服务器如何创建会话。<br />• `same-dir`(默认):所有会话共享当前工作目录,因此如果编辑相同文件可能会冲突。<br />• `worktree`:每个按需会话获得自己的 [git worktree](/docs/zh-CN/worktrees)。需要 git 存储库。<br />• `session`:单会话模式。恰好服务一个会话并拒绝其他连接。仅在启动时设置。<br />在运行时按 `w` 在 `same-dir` 和 `worktree` 之间切换。 |63 | `--spawn <mode>` | 服务器创建会话的方式。<br />• `same-dir`(默认):所有会话共享当前工作目录,因此如果编辑相同文件可能会冲突。<br />• `worktree`:每个按需会话获得自己的 [git worktree](/docs/zh-CN/worktrees)。需要 git 存储库。<br />• `session`:单会话模式。恰好服务一个会话并拒绝其他连接。仅在启动时设置。<br />在运行时按 `w` 在 `same-dir` 和 `worktree` 之间切换。 |

64 | `--capacity <N>` | 最大并发会话数。默认为 32。不能与 `--spawn=session` 一起使用。 |64 | `--capacity <N>` | 最大并发会话数。默认为 32。不能与 `--spawn=session` 一起使用。 |

65 | `--[no-]create-session-in-dir` | 在服务器启动时在当前目录中预创建一个会话,以便您有地方立即输入。在 `worktree` 模式下,此会话保留在当前目录中,而按需会话获得隔离的 worktree。默认启用。如果您传递 `--no-create-session-in-dir` 以不启动任何会话,Claude Code 会在您停止服务器时存档服务器的会话,因此没有任何内容可[恢复](#resume-sessions-after-stopping-the-server)。 |65 | `--[no-]create-session-in-dir` | 服务器启动时在当前目录中预创建一个会话,以便您有地方立即输入。在 `worktree` 模式下,此会话保留在当前目录中,而按需会话获得隔离的 worktree。默认启用。如果您传递 `--no-create-session-in-dir` 以不创建任何会话启动,Claude Code 会在您停止服务器时存档服务器的会话,因此没有任何内容可[恢复](#resume-sessions-after-stopping-the-server)。 |

66 | `--permission-mode <mode>` | 为服务器的会话设置起始[权限模式](/docs/zh-CN/permission-modes),例如 `acceptEdits`。接受 `manual` 作为 `default` 的别名;无法识别的模式会在启动时停止服务器并列出有效模式。 |66 | `--permission-mode <mode>` | 为服务器的会话设置起始[权限模式](/docs/zh-CN/permission-modes),例如 `acceptEdits`。接受 `manual` 作为 `default` 的别名;无法识别的模式会在启动时停止服务器并列出有效模式。 |

67 | `--chrome` / `--no-chrome` | 在服务器创建的会话中打开或关闭 [Chrome 集成](/docs/zh-CN/chrome),以便 Claude 可以在您从另一台设备工作时在您的机器上使用 Chrome。没有任何标志,服务器预创建的会话和您从 claude.ai/code 或 Claude 应用启动的任何会话都以 Chrome 关闭开始,即使您[默认启用了 Chrome](/docs/zh-CN/chrome#enable-chrome-by-default)。服务器为您的[项目](/docs/zh-CN/claude-projects)线程之一启动的会话改为遵循该设置,除非在 `bypassPermissions` 模式下。需要 Claude Code v2.1.273 或更高版本。 |67 | `--chrome` / `--no-chrome` | 在服务器创建的会话中打开或关闭 [Chrome 集成](/docs/zh-CN/chrome),以便 Claude 可以在您从另一台设备工作时在您的机器上使用 Chrome。如果没有任一标志,服务器预创建的会话和您从 claude.ai/code 或 Claude 应用自己启动的任何会话都以 Chrome 关闭开始,即使您[默认启用了 Chrome](/docs/zh-CN/chrome#enable-chrome-by-default)。服务器为您的[项目](/docs/zh-CN/claude-projects)线程之一启动的会话改为遵循该设置,除非在 `bypassPermissions` 模式下。需要 Claude Code v2.1.273 或更高版本。 |

68 | `-d`, `--debug[=<filter>]` | 为服务器打开调试日志记录,可选择按类别过滤。仅以 `=` 形式传递过滤器,例如 `--debug=api,hooks`。需要 Claude Code v2.1.282 或更高版本。 |68 | `-d`, `--debug[=<filter>]` | 为服务器打开调试日志记录,可选择按类别过滤。仅以 `=` 形式传递过滤器,例如 `--debug=api,hooks`。需要 Claude Code v2.1.282 或更高版本。 |

69 | `--debug-file <path>` | 将调试日志写入给定文件。 |69 | `--debug-file <path>` | 将调试日志写入给定文件。 |

70 | `--verbose` | 显示详细的连接和会话日志。 |70 | `--verbose` | 显示详细的连接和会话日志。 |


72 72 

73 在 `remote-control` 之后给出这些标志。73 在 `remote-control` 之后给出这些标志。

74 74 

75 如果您在 `remote-control` 之前传递全局 `claude` 标志,或者包装脚本添加了一个,Claude Code 不会将该标志转移到服务器创建的会话。Claude Code 仅在已知删除该标志不会改变这些会话可以执行的操作时才允许该标志通过,例如 `--verbose` 或 `--model`。对于任何其他标志,例如 `--settings`,Claude Code [拒绝启动](/docs/zh-CN/errors#not-carried-over-to-the-sessions-remote-control-starts)并命名要删除的标志。75 如果您在 `remote-control` 之前传递全局 `claude` 标志,或包装脚本添加了一个,Claude Code 不会将该标志转移到服务器创建的会话。Claude Code 仅在已知删除该标志不会改变这些会话可以执行的操作时才允许该标志通过,例如 `--verbose` 或 `--model`。对于任何其他标志,例如 `--settings`,Claude Code [拒绝启动](/docs/zh-CN/errors#not-carried-over-to-the-sessions-remote-control-starts)并命名要删除的标志。

76 76 

77 Claude Code 在打印帮助之前检查远程控制资格,因此当您未使用符合条件的帐户登录时,`claude remote-control --help` 返回错误而不是此标志列表。77 Claude Code 在打印帮助之前检查远程控制资格,因此当您未使用符合条件的帐户登录时,`claude remote-control --help` 返回错误而不是此标志列表。

78 </Tab>78 </Tab>


84 claude --remote-control84 claude --remote-control

85 ```85 ```

86 86 

87 可选择为会话传递一个名称:87 可选择为会话传递名称:

88 88 

89 ```bash theme={null}89 ```bash theme={null}

90 claude --remote-control "My Project"90 claude --remote-control "My Project"

91 ```91 ```

92 92 

93 这为您提供了一个完整的交互式会话在您的终端中,您也可以从 claude.ai 或 Claude 应用远程控制。与 `claude remote-control`(服务器模式)不同,您可以在本地输入消息,同时会话也可以远程使用。93 这为您提供了一个完整的交互式会话在您的终端中,您也可以从 claude.ai 或 Claude 应用远程控制。与 `claude remote-control`(服务器模式)不同,您可以在会话也可远程使用时在本地输入消息。

94 </Tab>94 </Tab>

95 95 

96 <Tab title="从现有会话">96 <Tab title="从现有会话">


100 /remote-control100 /remote-control

101 ```101 ```

102 102 

103 传递一个名称作为参数以设置自定义会话标题:103 传递名称作为参数以设置自定义会话标题:

104 104 

105 ```text theme={null}105 ```text theme={null}

106 /remote-control My Project106 /remote-control My Project

107 ```107 ```

108 108 

109 这启动一个远程控制会话,该会话继承您当前的对话历史。109 这启动一个远程控制会话,该会话延续您当前的对话历史。

110 110 

111 在您接受远程控制的一次性确认之前,在 `/remote-control` 连接之前会出现一个对话框。选择**启用远程控制**以接受并连接。如果您选择**算了**或按 Esc,Claude Code 不会连接,并在您下次运行 `/remote-control` 时再次询问。111 在您接受远程控制的一次性确认之前,在 `/remote-control` 连接之前会出现一个对话框。选择**启用远程控制**以接受并连接。如果您选择**算了**或按 Esc,Claude Code 不会连接,并在您下次运行 `/remote-control` 时再次询问。

112 112 

113 此命令不支持 `--verbose`、`--sandbox` 和 `--no-sandbox` 标志。113 `--verbose`、`--sandbox` 和 `--no-sandbox` 标志不适用于此命令。

114 </Tab>114 </Tab>

115 115 

116 <Tab title="VS Code">116 <Tab title="VS Code">


120 /remote-control120 /remote-control

121 ```121 ```

122 122 

123 当远程控制打开时,Claude Code 在提示框页脚中显示**远程控制**指示器。会话连接后,单击指示器直接转到会话,或在 [claude.ai/code](https://claude.ai/code) 的会话列表中找到它。Claude Code 也会在对话中发布会话 URL。要断开连接,再次运行 `/remote-control`。123 当远程控制打开时,Claude Code 在提示框页脚中显示**远程控制**指示器。会话连接后,单击指示器直接转到会话,或在 [claude.ai/code](https://claude.ai/code) 的会话列表中找到它。Claude Code 还在对话中发布会话 URL。要断开连接,再次运行 `/remote-control`。

124 124 

125 与 CLI 不同,VS Code 命令不接受名称参数或显示 QR 码。会话标题从您的对话历史或第一个提示派生。125 与 CLI 不同,VS Code 命令不接受名称参数或显示 QR 码。会话标题从您的对话历史或第一个提示派生。

126 </Tab>126 </Tab>


142 检查连接状态142 检查连接状态

143</h3>143</h3>

144 144 

145在交互式会话中,当远程控制已连接时,终端显示一个 `/rc active` 指示器,该指示器链接到 claude.ai 上的会话。当终端太窄无法容纳它时,指示器被隐藏。要查看会话 URL 和 QR 码以[从另一台设备连接](#connect-from-another-device),再次运行 `/remote-control` 以打开状态面板。该面板还允许您断开远程控制,同时您的本地会话继续运行。145在交互式会话中,当远程控制已连接时,终端显示一个 `/rc active` 指示器,该指示器链接到 claude.ai 上的会话。当终端太窄无法容纳它时,指示器被隐藏。要查看会话 URL 和用于[从另一台设备连接](#connect-from-another-device)的 QR 码,再次运行 `/remote-control` 以打开状态面板。该面板还允许您断开远程控制,同时您的本地会话继续运行。

146 146 

147<span id="session-ended-elsewhere" />如果连接在交互式会话中失败,指示器会更改以显示失败,Claude Code 会在通知中显示原因并将其添加到对话中。运行 `/remote-control` 以重新连接,除非原因说会话在其他地方更改:147<span id="session-ended-elsewhere" />如果连接在交互式会话中失败,指示器会更改以显示失败,Claude Code 会在通知中显示原因并将其添加到对话中。运行 `/remote-control` 以重新连接,除非原因说会话在其他地方更改:

148 148 


157一旦远程控制会话处于活动状态,您有几种方式从另一台设备连接:157一旦远程控制会话处于活动状态,您有几种方式从另一台设备连接:

158 158 

159* **打开会话 URL** 在任何浏览器中直接转到 [claude.ai/code](https://claude.ai/code) 上的会话。159* **打开会话 URL** 在任何浏览器中直接转到 [claude.ai/code](https://claude.ai/code) 上的会话。

160* **扫描 QR 码** 显示在会话 URL 旁边,以在 Claude 应用中直接打开它。使用 `claude remote-control`,按空格键切换 QR 码显示。160* **扫描 QR 码** 显示在会话 URL 旁边,在 Claude 应用中直接打开它。使用 `claude remote-control`,按空格键切换 QR 码显示。

161* **打开 [claude.ai/code](https://claude.ai/code) 或 Claude 应用** 并在会话列表中按名称找到会话。在 Claude 移动应用中,点击导航中的**代码**以到达会话列表。远程控制会话在在线时显示带有绿色状态点的计算机图标。161* **打开 [claude.ai/code](https://claude.ai/code) 或 Claude 应用** 并在会话列表中按名称找到会话。在 Claude 移动应用中,点击导航中的**代码**以到达会话列表。远程控制会话在联机时显示带有绿色状态点的计算机图标。

162 162 

163当您连接时,设备显示会话已在后台运行的任何子代理和工作流。从设备停止其中一个,Claude Code 会停止您的机器上的该任务。163当您连接时,设备显示会话已在后台运行的任何子代理和工作流。从设备停止其中一个,Claude Code 会停止您机器上的该任务。

164 164 

165远程会话标题按以下顺序选择:165远程会话标题按以下顺序选择:

166 166 

1671. 您传递给 `--name`、`--remote-control` 或 `/remote-control` 的名称1671. 您传递给 `--name`、`--remote-control` 或 `/remote-control` 的名称

1682. 您使用 `/rename` 设置的标题1682. 您使用 `/rename` 设置的标题

1693. 现有对话历史中最后一条有意义的消息1693. 现有对话历史中最后一条有意义的消息

1704. 自动生成的名称,如 `myhost-graceful-unicorn`,其中 `myhost` 是您的机器主机名或您使用 `--remote-control-session-name-prefix` 设置的前缀1704. 自动生成的名称,如 `myhost-graceful-unicorn`,其中 `myhost` 是您机器的主机名或您使用 `--remote-control-session-name-prefix` 设置的前缀

171 171 

172如果您未设置显式名称,Claude Code 会在您发送提示后更新标题以反映您的提示。当您从 claude.ai 或 Claude 应用重命名会话时,Claude Code 也会更新 `claude --resume` 中显示的本地标题。172如果您未设置显式名称,Claude Code 会在您发送提示后更新标题以反映您的提示。当您从 claude.ai 或 Claude 应用重命名会话时,Claude Code 也会更新 `claude --resume` 中显示的本地标题。

173 173 

174如果您还没有 Claude 应用,请在 Claude Code 中运行 `/mobile` 以显示 QR 码以访问 [claude.ai/mobile](https://claude.ai/mobile),它会打开您手机的正确应用商店。174如果您还没有 Claude 应用,请在 Claude Code 内运行 `/mobile` 以显示 [claude.ai/mobile](https://claude.ai/mobile) 的 QR 码,该码会打开适合您手机的应用商店。

175 175 

176<h3 id="what-connected-devices-see">176<h3 id="what-connected-devices-see">

177 连接的设备看到的内容177 连接的设备看到的内容


179 179 

180连接的设备显示您终端中的对话。这些情况超出了普通消息:180连接的设备显示您终端中的对话。这些情况超出了普通消息:

181 181 

182* **压缩和 `/clear`**:当 Claude Code [压缩对话](/docs/zh-CN/context-window#what-survives-compaction)时,连接的设备显示进度,然后显示对话被压缩的位置。当您运行 `/clear` 时,对话也会在连接的设备上重置。182* **压缩和 `/clear`**:当 Claude Code [压缩对话](/docs/zh-CN/context-window#what-survives-compaction)时,连接的设备显示进度,然后显示对话被压缩的位置。当您运行 `/clear` 时,对话也在连接的设备上重置。

183* **使用 `/resume` 切换对话**:连接的设备不会接收切换到的对话的标题或早期历史,但双向的新消息进出您的终端中打开的任何对话。要再次从设备处理原始对话,请在您的终端中运行 `/resume` 并切换回它。183* **使用 `/resume` 切换对话**:连接的设备不接收切换到的对话的标题或早期历史,但双向的新消息进出您终端中打开的任何对话。要从设备再次处理原始对话,请在您的终端中运行 `/resume` 并切换回它。

184* **使用 `/teleport` 拉取会话**:当您使用 `/teleport` 将[云会话](/docs/zh-CN/claude-code-on-the-web#from-cloud-to-terminal)拉入您的终端时,连接的设备不会接收拉取的对话的早期历史。双向的新消息进出拉取的对话,该对话现在是您的终端中打开的对话。184* **使用 `/teleport` 拉取会话**:当您使用 `/teleport` 将[云会话](/docs/zh-CN/claude-code-on-the-web#from-cloud-to-terminal)拉入您的终端时,连接的设备不接收拉取的对话的早期历史。双向的新消息进出拉取的对话,该对话现在是您终端中打开的对话。

185* **来自您其他会话的消息**:使用[跨会话消息传递](/docs/zh-CN/cross-session-messaging),相同的连接在不同机器上的您自己的会话之间以及来自您的[云会话](/docs/zh-CN/claude-code-on-the-web)传递消息。185* **来自您其他会话的消息**:使用[跨会话消息传递](/docs/zh-CN/cross-session-messaging),相同的连接在您不同机器上的自己的会话之间以及来自您的[云会话](/docs/zh-CN/claude-code-on-the-web)传递消息。

186* **您的更改的差异**:当会话的目录在 git 存储库中时,连接的设备的差异窗格显示您的更改。在具有超过存储库默认分支的提交的分支上,窗格显示自分支从它分离以来的更改,包括您未提交的编辑。在默认分支本身上,或在不超过它的分支上,窗格仅显示您未提交的更改。186* **您的更改的差异**:当会话的目录在 git 存储库中时,连接的设备的差异窗格显示您的更改。在具有超过存储库默认分支的提交的分支上,窗格显示自分支从它分离以来的更改,包括您未提交的编辑。在默认分支本身上,或在不超过它的分支上,窗格仅显示您未提交的更改。

187* **模型**:当您从连接的设备选择[模型](/docs/zh-CN/model-config)时,Claude Code 在该模型上运行会话。需要 Claude Code v2.1.238 或更高版本。您从设备的模型控制中选择的模型仅适用于当前会话。当您从设备向交互式会话发送 `/model <name>` 时,Claude Code 也会为新会话设置您的默认值。187* **模型**:当您从连接的设备选择[模型](/docs/zh-CN/model-config)时,Claude Code 在该模型上运行会话。需要 Claude Code v2.1.238 或更高版本。您从设备的模型控制中选择的模型仅适用于当前会话。当您从设备向交互式会话发送 `/model <name>` 时,Claude Code 也会为新会话设置您的默认值。

188* **努力级别**:当您从连接的设备使用 `/effort` 或设备的努力控制设置[努力级别](/docs/zh-CN/model-config#adjust-effort-level)时,Claude Code 将其应用于您的机器上的会话。如果您使用 `CLAUDE_CODE_EFFORT_LEVEL` 固定了一个级别,会话保持该级别,Claude Code 拒绝从努力控制中选择不同的级别。从努力控制中选择一个级别需要您的机器上的 Claude Code v2.1.234 或更高版本。188* **努力级别**:当您从连接的设备设置[努力级别](/docs/zh-CN/model-config#adjust-effort-level)时,使用 `/effort` 或设备的努力控制,Claude Code 将其应用于您机器上的会话。如果您使用 `CLAUDE_CODE_EFFORT_LEVEL` 固定了一个级别,会话保持该级别,Claude Code 拒绝从努力控制中选择不同的级别。从努力控制中选择级别需要您机器上的 Claude Code v2.1.234 或更高版本。

189* **连接失败后重新连接**:运行 `/remote-control` 以重新连接。如果压缩重写了对话或您在此期间使用 `/resume` 切换了对话,Claude Code 会存档它正在使用的服务器会话,而不是将其留在会话列表中。您仍然可以通过[过滤存档的会话](/docs/zh-CN/claude-code-on-the-web#archive-sessions)找到它。在设备仍然连接时切换对话不会存档会话。189* **连接失败后重新连接**:运行 `/remote-control` 以重新连接。如果压缩重写了对话或您在此期间使用 `/resume` 切换了对话,Claude Code 会存档它正在使用的服务器会话,而不是将其留在会话列表中。您仍然可以通过[过滤存档的会话](/docs/zh-CN/claude-code-on-the-web#archive-sessions)找到它。在设备仍然连接时切换对话不会存档会话。

190 190 

191<h3 id="enable-remote-control-for-all-sessions">191<h3 id="enable-remote-control-for-all-sessions">

192 为所有会话启用远程控制192 为所有会话启用远程控制

193</h3>193</h3>

194 194 

195远程控制仅在您显式运行 `claude remote-control`、`claude --remote-control` 或 `/remote-control` 时激活,除非打开了自动连接。要为每个交互式会话打开自动连接,请在 Claude Code 中运行 `/config` 并设置**为所有会话启用远程控制**。切换有三个值:195远程控制仅在您显式运行 `claude remote-control`、`claude --remote-control` 或 `/remote-control` 时激活,除非打开了自动连接。要为每个交互式会话打开自动连接,请在 Claude Code 内运行 `/config` 并设置**为所有会话启用远程控制**。切换有三个值:

196 196 

197* **`true`**:当交互式会话启动时自动连接。197* **`true`**:当交互式会话启动时自动连接。

198* **`false`**:关闭自动连接,尽管来自[托管设置](/docs/zh-CN/managed-settings)的 `true` 会优先,因为 Claude Code 将选择保存到您的用户设置。项目或本地设置(`.claude/settings.json`、`.claude/settings.local.json`)中的 `false` 甚至会关闭自动连接,即使托管 `true` 也是如此。198* **`false`**:关闭自动连接,尽管来自[托管设置](/docs/zh-CN/managed-settings)的 `true` 会优先,因为 Claude Code 将选择保存到您的用户设置。项目或本地设置(`.claude/settings.json`、`.claude/settings.local.json`)中的 `false` 即使在托管 `true` 上也会关闭自动连接。

199* **`default`**:清除您的选择并遵循您的组织的管理员默认值(如果已设置),否则遵循 Claude Code 的当前默认值。199* **`default`**:清除您的选择并遵循您组织的管理员默认值(如果已设置),否则遵循 Claude Code 的当前默认值。

200 200 

201相同的切换出现在 CLI 之外:201相同的切换出现在 CLI 之外:

202 202 

203* **Desktop 应用**:**设置 > Claude Code > 默认启用远程控制**。203* **Desktop 应用**:**设置 > Claude Code > 将新会话连接到远程控制**。

204* **VS Code 扩展**:[命令菜单](/docs/zh-CN/vs-code#use-the-prompt-box)的设置部分中的**为所有会话启用远程控制**。204* **VS Code 扩展**:[命令菜单](/docs/zh-CN/vs-code#use-the-prompt-box)的设置部分中的**为所有会话启用远程控制**。

205 205 

206要改为从设置文件打开自动连接,请在您的用户 `~/.claude/settings.json` 或[托管设置](/docs/zh-CN/managed-settings)中将 [`remoteControlAtStartup`](/docs/zh-CN/settings-reference#remotecontrolatstartup) 设置为 `true`。在项目或本地设置(`.claude/settings.json`、`.claude/settings.local.json`)中,Claude Code 遵守 `false` 并为该存储库关闭自动连接,但忽略 `true`,因此已检入的文件无法为打开存储库的每个人打开远程控制。206要改为从设置文件打开自动连接,请在您的用户 `~/.claude/settings.json` 或[托管设置](/docs/zh-CN/managed-settings)中将 [`remoteControlAtStartup`](/docs/zh-CN/settings-reference#remotecontrolatstartup) 设置为 `true`。在项目或本地设置(`.claude/settings.json`、`.claude/settings.local.json`)中,Claude Code 遵守 `false` 并为该存储库关闭自动连接,但忽略 `true`,因此已检入的文件无法为打开存储库的每个人打开远程控制。

207 207 

208自动连接使用您自己的 claude.ai 帐户登录,因此它启动的会话仅出现在您自己的帐户的 Claude 应用中,并且不向任何其他人授予访问权限。208自动连接使用您自己的 claude.ai 帐户登录,因此它启动的会话仅出现在您自己帐户的 Claude 应用中,并且不向任何其他人授予访问权限。

209 209 

210启用此设置后,每个交互式 Claude Code 进程注册一个远程会话。如果您运行多个实例,每个实例都获得自己的远程会话。要从单个进程运行多个并发会话,请改用[服务器模式](#start-a-remote-control-session)。210启用此设置后,每个交互式 Claude Code 进程注册一个远程会话。如果您运行多个实例,每个实例都获得自己的远程会话。要从单个进程运行多个并发会话,请改为使用[服务器模式](#start-a-remote-control-session)。

211 211 

212<h3 id="resume-sessions-after-stopping-the-server">212<h3 id="resume-sessions-after-stopping-the-server">

213 停止服务器后恢复会话213 停止服务器后恢复会话


216当您使用 Ctrl+C 停止 `claude remote-control` 时,它正在服务的会话停止从您的手机或浏览器响应。只要您没有在同一目录中运行另一个 `claude remote-control` 并且没有使用 `--no-create-session-in-dir` 启动此会话,Claude Code 就不会存档它们。要恢复它们,请在同一目录中运行以下命令之一:216当您使用 Ctrl+C 停止 `claude remote-control` 时,它正在服务的会话停止从您的手机或浏览器响应。只要您没有在同一目录中运行另一个 `claude remote-control` 并且没有使用 `--no-create-session-in-dir` 启动此会话,Claude Code 就不会存档它们。要恢复它们,请在同一目录中运行以下命令之一:

217 217 

218* **`claude remote-control`**:恢复服务器正在服务的每个会话。218* **`claude remote-control`**:恢复服务器正在服务的每个会话。

219* **`claude remote-control --continue`**:仅恢复服务器启动的会话,并在该会话结束时退出。如果此目录没有记录,Claude Code 会使用此存储库的其他 git worktree 中最新的。219* **`claude remote-control --continue`**:仅恢复服务器启动的会话,并在该会话结束时退出。如果此目录没有记录,Claude Code 使用此存储库其他 git worktree 中最新的。

220* **`claude remote-control --session-id <id>`**:仅恢复您传递其 ID 的会话,并在该会话结束时退出。ID 是会话 URL 在 claude.ai/code 中 `/code/` 和任何 `?` 之间的部分。220* **`claude remote-control --session-id <id>`**:仅恢复您传递其 ID 的会话,并在该会话结束时退出。ID 是会话 URL 在 claude.ai/code 中 `/code/` 和任何 `?` 之间的部分。

221 221 

222这些命令在服务器停止后约四小时内有效。之后,运行 `claude remote-control` 以启动新会话。如果您在此期间存档了会话,`--continue` 和 `--session-id` 会在 Claude Code v2.1.228 或更高版本上取消存档。222这些命令在服务器停止后约四小时内有效。之后,运行 `claude remote-control` 以启动新会话。如果您在此期间存档了会话,`--continue` 和 `--session-id` 在 Claude Code v2.1.228 或更高版本上取消存档它。

223 223 

224要恢复您使用 `claude --remote-control` 或 `/remote-control` 启动的会话,请使用 `claude --continue` 或 `claude --resume` 恢复对话。如果远程控制不重新连接,请参阅[无法重新连接到您的远程控制会话](#couldnt-reconnect-to-your-remote-control-session)。224要恢复您使用 `claude --remote-control` 或 `/remote-control` 启动的会话,请使用 `claude --continue` 或 `claude --resume` 恢复对话。如果远程控制无法重新连接,请参阅[无法重新连接到您的远程控制会话](#couldnt-reconnect-to-your-remote-control-session)。

225 225 

226如果您在第一个终端仍然打开远程控制的情况下在第二个终端中恢复对话,Claude Code 会在第二个终端中打印 `Remote Control not started here` 通知,并改为在那里关闭远程控制。在第二个终端中运行 `/remote-control` 以将远程控制移动到它。226如果您在第一个终端仍然打开远程控制的情况下在第二个终端中恢复对话,Claude Code 会在第二个终端中打印 `Remote Control not started here` 通知,并改为在那里关闭远程控制,而不是从第一个终端取走会话。在第二个终端中运行 `/remote-control` 以将远程控制移动到它。

227 227 

228当您在具有远程控制的 Claude Desktop 或 IDE 扩展中恢复对话时,Claude Code 会将其重新附加到现有的 claude.ai 会话,而不是向会话列表添加新会话。228当您在具有远程控制的 Claude Desktop 或 IDE 扩展中恢复对话时,Claude Code 会将其重新附加到现有 claude.ai 会话,而不是向会话列表添加新会话。

229 229 

230<h2 id="connection-and-security">230<h2 id="connection-and-security">

231 连接和安全231 连接和安全

sandboxing.md +1 −0

Details

528 528 

529* **默认写入行为**:对当前工作目录及其子目录的读写访问,加上使用 `--add-dir`、`/add-dir` 或 [`permissions.additionalDirectories`](/docs/zh-CN/settings-reference#permissions-additionaldirectories) 添加的任何目录,以及 `$TMPDIR` 指向的会话临时目录529* **默认写入行为**:对当前工作目录及其子目录的读写访问,加上使用 `--add-dir`、`/add-dir` 或 [`permissions.additionalDirectories`](/docs/zh-CN/settings-reference#permissions-additionaldirectories) 添加的任何目录,以及 `$TMPDIR` 指向的会话临时目录

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

531* **读取阻止**:启用 [`permissions.blockReadsOutsideWorkingDirectories`](/docs/zh-CN/settings-reference#permissions-blockreadsoutsideworkingdirectories) 时,沙箱化命令也会失去对你的主目录和其他保存用户文件的目录的读取访问权限,除了 [Sandboxed commands under the block](/docs/zh-CN/settings-reference#sandboxed-commands-under-the-block) 列出的路径。该部分也说明了此阻止部分何时不适用。

531* **被阻止的访问**:无法在没有明确权限的情况下修改工作目录、添加的目录和会话临时目录外的文件,包括 shell 配置文件(例如 `~/.bashrc`)和 `/bin/` 中的系统二进制文件532* **被阻止的访问**:无法在没有明确权限的情况下修改工作目录、添加的目录和会话临时目录外的文件,包括 shell 配置文件(例如 `~/.bashrc`)和 `/bin/` 中的系统二进制文件

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

533* **可配置**:通过设置定义自定义允许和拒绝的路径534* **可配置**:通过设置定义自定义允许和拒绝的路径

Details

170 170 

171如果您的 git 主机拒绝凭证,或您没有配置凭证,运行器重试几次然后失败存储库准备(当存储库是会话推送结果的存储库时)。对于会话仅从中读取的存储库,[故障排除](#troubleshooting)涵盖运行器何时改为跳过它。运行器不会将这些设置传递到会话的环境中。171如果您的 git 主机拒绝凭证,或您没有配置凭证,运行器重试几次然后失败存储库准备(当存储库是会话推送结果的存储库时)。对于会话仅从中读取的存储库,[故障排除](#troubleshooting)涵盖运行器何时改为跳过它。运行器不会将这些设置传递到会话的环境中。

172 172 

173保持您在 `GIT_SSH_COMMAND` 或 `GIT_ASKPASS` 中命名的任何程序,会话无法写入它,就像[加固清单](#harden-your-deployment)要求钩子目录和包装脚本的方式一样。该程序命令行上的任何密钥或文件也是如此。运行器自己的 git 在克隆或获取时运行该程序。

174 

173如果检出目录由与运行器进程不同的 uid 拥有,git 拒绝对其进行操作;添加 `safe.directory`:175如果检出目录由与运行器进程不同的 uid 拥有,git 拒绝对其进行操作;添加 `safe.directory`:

174 176 

175```dockerfile theme={null}177```dockerfile theme={null}


184 186 

185代理需要 `--capacity 1`,因为代理 URL 是按会话的,以及 git 2.32 或更高版本,因为较旧的 git 忽略代理用来隔离会话的配置机制。如果任一要求未满足,运行器拒绝启动。因为代理从 Anthropic 端获取,您的 git 主机必须可从 Anthropic 基础设施到达,与 Anthropic 托管会话相同的要求;对于仅在您的网络内可路由的 git 主机,改用 [`checkout` 生命周期钩子](/docs/zh-CN/self-hosted-environments-configuration#checkout)。每个运行器进程一次处理一个会话,因此运行更多副本以获得并行性。启用代理后,`--git-host-rewrite` 和 `--git-ssh-rewrite` 无效:代理 URL 指向 `api.anthropic.com`,而不是您的 git 主机。187代理需要 `--capacity 1`,因为代理 URL 是按会话的,以及 git 2.32 或更高版本,因为较旧的 git 忽略代理用来隔离会话的配置机制。如果任一要求未满足,运行器拒绝启动。因为代理从 Anthropic 端获取,您的 git 主机必须可从 Anthropic 基础设施到达,与 Anthropic 托管会话相同的要求;对于仅在您的网络内可路由的 git 主机,改用 [`checkout` 生命周期钩子](/docs/zh-CN/self-hosted-environments-configuration#checkout)。每个运行器进程一次处理一个会话,因此运行更多副本以获得并行性。启用代理后,`--git-host-rewrite` 和 `--git-ssh-rewrite` 无效:代理 URL 指向 `api.anthropic.com`,而不是您的 git 主机。

186 188 

189<Warning>

190 本页上的 [Kubernetes](#kubernetes) 和 [Docker Compose](#docker-compose) 配方使用 `--capacity 4`。如果您在不将容量更改为 `1` 的情况下向其中一个添加 `--use-anthropic-git-proxy` 或 `CLAUDE_RUNNER_USE_GIT_PROXY=1`,每次您的编排器重新启动它时,运行器都会在启动时退出。设置 `--capacity 1` 并运行更多副本以获得并行性。[当运行器退出](#when-the-runner-exits)显示运行器打印的行。

191</Warning>

192 

187运行器还在注册时向 Anthropic 报告选择加入,在启动时打印 `Registering as opted in to Anthropic-managed git (--use-anthropic-git-proxy)`。报告选择加入需要 Claude Code v2.1.267 或更高版本,较早的版本接受该标志而不报告它或打印该行。选择加入运行器上的每个会话然后使用 Anthropic 管理的 git 或按会话代理 URL。当会话使用按会话代理 URL 时,运行器记录一行 `[runner:warn]` 说明这一点。193运行器还在注册时向 Anthropic 报告选择加入,在启动时打印 `Registering as opted in to Anthropic-managed git (--use-anthropic-git-proxy)`。报告选择加入需要 Claude Code v2.1.267 或更高版本,较早的版本接受该标志而不报告它或打印该行。选择加入运行器上的每个会话然后使用 Anthropic 管理的 git 或按会话代理 URL。当会话使用按会话代理 URL 时,运行器记录一行 `[runner:warn]` 说明这一点。

188 194 

195<h4 id="trust-a-private-certificate-authority-with-anthropic-managed-git">

196 使用 Anthropic 管理的 git 信任专用证书颁发机构

197</h4>

198 

199如果您在运行器的环境中设置 `GIT_SSL_CAINFO` 或 `GIT_SSL_NO_VERIFY`,其会话使用 Anthropic 管理的 git,本部分适用。它描述的处理需要运行器运行 Claude Code v2.1.283 或更高版本。

200 

201当运行器上的 git 必须信任专用证书颁发机构 (CA)(例如 TLS 检查代理签署的证书颁发机构)时,通常的方法如下所示:

202 

203* **系统证书存储**:在运行器主机的系统证书存储中安装您的 CA,git 无需任何变量即可信任它。

204* **`GIT_SSL_CAINFO`**:将其设置为您的 CA 的 PEM 文件,例如 `GIT_SSL_CAINFO=/etc/ssl/corp-ca.pem`。

205* **`GIT_SSL_NO_VERIFY`**:在重新签名代理后面没有帮助。运行器自己通过 Anthropic 管理的 git 克隆检查证书,即使设置了变量,所以克隆失败,直到 git 通过其他两种方法之一信任您的 CA。

206 

207对于将会话令牌传送到 Anthropic 管理的 git 的 git 连接,运行器应用这两个变量如下。[`command` 钩子](/docs/zh-CN/self-hosted-environments-configuration#command)以会话的环境开始,所以它获得 git 在会话内获得的内容:

208 

209* **`GIT_SSL_CAINFO`**:git 检查 Anthropic 管理的 git 的内容取决于 git 运行的位置:

210 * **运行器自己的克隆和获取**:运行时不使用变量,并根据运行器写入的按会话证书文件检查 Anthropic 管理的 git。该文件保存运行器主机的系统 CA 包加上您的文件中的证书。

211 * **会话内的 Git**:获得 `http.sslCAInfo` 配置,命名您的文件代替变量,加上 `http.<url>.sslCAInfo` 条目,根据按会话文件检查 Anthropic 管理的 git。

212 * **`checkout` 和 `post-session` 钩子**:继承变量不变。

213* **`GIT_SSL_NO_VERIFY`**:哪些证书检查保持关闭取决于 git 运行的位置:

214 * **运行器自己的克隆和获取**:运行时不使用变量,并检查它们呈现的证书。

215 * **会话内的 Git**:获得 `http.sslVerify=false` 配置代替变量,所以检查对其他主机保持关闭。它还获得 `http.<url>.sslVerify=true` 条目,为 Anthropic 管理的 git 保持检查打开。

216 * **`checkout` 和 `post-session` 钩子**:当会话在 Anthropic 管理的 git 上有存储库时,获得 `http.sslVerify=false` 配置代替变量。它们还获得 `http.<url>.sslVerify=true` 条目,为 Anthropic 管理的 git 保持检查打开。

217 

218按会话证书文件需要在运行器主机上的 `/etc/ssl/certs/ca-certificates.crt` 或 `/etc/pki/tls/certs/ca-bundle.crt` 处的系统 CA 包。它还需要一个 `GIT_SSL_CAINFO` 文件,运行器的用户可以读取,保存 PEM `CERTIFICATE` 块,最多 1 MiB。当运行器无法构建按会话文件时,它记录一行 `[runner:warn]` 包含 `did not build the certificate file` 和原因。Git 然后按原样为 Anthropic 管理的 git 使用您的文件。修复该行命名的内容。

219 

220对于使用 Anthropic 管理的 git 的每个会话,运行器还记录一行 `[runner:warn]` 开始于 `governed git: GIT_SSL_CAINFO is set` 或 `governed git: GIT_SSL_NO_VERIFY is set`。该行说明运行器对其自己的 git、会话内的 git 和您的生命周期钩子对该变量所做的操作。它以您是否需要更改任何内容结束。

221 

189<h3 id="rewrite-git-urls-for-private-networks">222<h3 id="rewrite-git-urls-for-private-networks">

190 为专用网络重写 git URL223 为专用网络重写 git URL

191</h3>224</h3>


203 236 

204Anthropic 不发布预构建的运行器镜像。围绕 `claude` 二进制文件构建您自己的,分层您的存储库需要的任何工具链:语言运行时、编译器、包管理器和 [MCP](/docs/zh-CN/mcp) 边车。237Anthropic 不发布预构建的运行器镜像。围绕 `claude` 二进制文件构建您自己的,分层您的存储库需要的任何工具链:语言运行时、编译器、包管理器和 [MCP](/docs/zh-CN/mcp) 边车。

205 238 

206下面的配方使用 `--capacity 4`,所以一个容器为来自同一锁定所有者的最多四个并发会话服务。这不提供[加固部分](#harden-your-deployment)中的按会话容器隔离:在将环境连接到生产系统之前,要么以 `--capacity 1` 运行配方,每个会话一个容器,要么使用[按需运行器](/docs/zh-CN/self-hosted-environments-configuration#on-demand-runners),它也将环境密钥保持在会话运行主机之外。239下面的配方使用 `--capacity 4`,所以一个容器为来自同一锁定所有者的最多四个并发会话服务。这不提供[加固部分](#harden-your-deployment)中的按会话容器隔离:在将环境连接到生产系统之前,要么以 `--capacity 1` 运行配方,每个会话一个容器,要么使用[按需运行器](/docs/zh-CN/self-hosted-environments-configuration#on-demand-runners),它也将环境密钥保持在会话运行主机之外。如果您将[Anthropic git 代理](#use-the-anthropic-git-proxy)添加到这些配方之一,也要将 `--capacity` 更改为 `1`。

207 240 

208这个 Dockerfile 是一个最小的起点:241这个 Dockerfile 是一个最小的起点:

209 242 


338 371 

339下面的 Compose 服务在运行器退出时重启它,这涵盖崩溃和正常退出后的 drain。Docker 重启策略重启同一容器及其可写层完整,所以运行器以重用的文件系统而不是[加固态势](#harden-your-deployment)推荐的新文件系统回来;为评估使用此配方,对于生产要么每次运行重新创建容器,要么使用执行此操作的编排器。372下面的 Compose 服务在运行器退出时重启它,这涵盖崩溃和正常退出后的 drain。Docker 重启策略重启同一容器及其可写层完整,所以运行器以重用的文件系统而不是[加固态势](#harden-your-deployment)推荐的新文件系统回来;为评估使用此配方,对于生产要么每次运行重新创建容器,要么使用执行此操作的编排器。

340 373 

374Docker 在容器不断退出时会在每次重启前等待更长时间,直到达到上限,所以在此配方下无法启动的运行器不会在紧密循环中不断重启。[当运行器退出时](#when-the-runner-exits)描述了发生这种情况时要检查的内容。

375 

341```yaml theme={null}376```yaml theme={null}

342services:377services:

343 claude-runner:378 claude-runner:


451 486 

452每个会话的子 Claude Code 进程运行运行器自己的二进制文件,运行器在它生成的会话内关闭自动更新,所以每个会话运行您在主机上安装或构建到镜像中的版本。主机级更新在运行器下次启动时生效。487每个会话的子 Claude Code 进程运行运行器自己的二进制文件,运行器在它生成的会话内关闭自动更新,所以每个会话运行您在主机上安装或构建到镜像中的版本。主机级更新在运行器下次启动时生效。

453 488 

489您的会话使用的模型可能需要比它们运行的 Claude Code 版本更新的版本。服务器随后会以 [Claude Code does not support this model](/docs/zh-CN/errors#claude-code-does-not-support-this-model) 拒绝对该模型的请求。在您固定版本之前,请检查[模型需要的 Claude Code 版本](/docs/zh-CN/model-config#available-models),以了解您的会话使用的每个模型。

490 

454* **将队列保持在一个版本上**:使用固定版本构建镜像,或在裸主机上安装特定版本并[禁用自动更新](/docs/zh-CN/setup#disable-auto-updates)491* **将队列保持在一个版本上**:使用固定版本构建镜像,或在裸主机上安装特定版本并[禁用自动更新](/docs/zh-CN/setup#disable-auto-updates)

455* **升级**:安装较新版本或重建镜像,然后重启运行器492* **升级**:安装较新版本或重建镜像,然后重启运行器

456* **插件**:插件市场也不自动更新;在运行器的环境中设置 `FORCE_AUTOUPDATE_PLUGINS=1` 以让插件自动更新,同时二进制保持固定493* **插件**:插件市场也不自动更新;在运行器的环境中设置 `FORCE_AUTOUPDATE_PLUGINS=1` 以让插件自动更新,同时二进制保持固定


554 591 

555每个会话的子进程写入单独的调试日志。失败时,运行器在 claude.ai/code 中将日志的尾部与会话一起显示。除非您使用 [`--remove-session-state`](/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags) 启动了运行器,否则它也会在磁盘上保留失败会话的日志,并在运行器日志中打印其路径。592每个会话的子进程写入单独的调试日志。失败时,运行器在 claude.ai/code 中将日志的尾部与会话一起显示。除非您使用 [`--remove-session-state`](/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags) 启动了运行器,否则它也会在磁盘上保留失败会话的日志,并在运行器日志中打印其路径。

556 593 

594<h3 id="when-the-runner-exits">

595 当运行器退出时

596</h3>

597 

598不要重新启动 [按需运行器](/docs/zh-CN/self-hosted-environments-configuration#on-demand-runners),因为其工作订单是一次性的。在启动后立即退出的运行器需要与因任何其他原因退出的运行器不同的处理方式。

599 

600* **正常退出**:运行器完成了其会话并耗尽,达到了其退休时间,或被告知停止。重新启动它以便环境再次具有容量。[运行器生命周期](/docs/zh-CN/self-hosted-environments#runner-lifecycle) 描述了这些退出。

601* **启动失败**:运行器无法使用给定的配置或主机启动,因此它在启动后几秒钟退出,并且每次重新启动时都以相同的方式退出。更快地重新启动它没有帮助。有人需要阅读其输出并修复原因。

602 

603配置您的监督程序在运行器退出时重新启动它,当运行器在启动后立即保持退出时等待更长时间,并在这种情况持续发生时告知某人。

604 

605<h4 id="recognize-a-failed-start">

606 识别启动失败

607</h4>

608 

609当运行器无法启动时,它会打印一行说明原因,然后退出。对于大多数原因,该行包含 `[runner:fatal]`。对于某些原因,该行以 `error:` 开头,包括当运行器无法解析其标志、无法读取环境密钥或无法创建或写入基础目录时。下一行然后指向 `--help`。

610 

611大多数日志行以时间戳和 `[self-hosted-runner]` 开头,下面的示例省略了这些。例如,使用 Anthropic git 代理和容量大于 1 启动的运行器会打印如下一行:

612 

613```text theme={null}

614[runner:fatal] --use-anthropic-git-proxy requires --capacity 1 (the proxy URL is per-session and linked worktrees share origin). Omit --use-anthropic-git-proxy or set --capacity 1.

615```

616 

617在运行器的标准输出和标准错误、您的平台的容器日志或您使用 [`--log-file`](/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags) 设置的文件中查找该行。运行器在打开日志文件之前打印 `error:` 行,因此请在终端或您的容器日志中查找它,如 [故障排除](#troubleshooting) 所述。

618 

619当您阅读启动失败时,这些也有帮助:

620 

621* **根本没有行**:主机杀死的运行器不会打印任何内容。如果输出以没有 `[runner:fatal]` 行和没有 `error:` 行结束,请检查主机或您的编排器是否停止了该进程,例如因为超过了内存限制。

622* **退出代码**:运行器不会为在每次启动时重复的错误预留退出代码。它对配置错误(例如不支持的标志组合)和可以自行清除的失败(例如 API 通过运行器自己的重试保持不可达)退出相同的代码。根据运行器退出的速度快慢来决定是否等待更长时间,并阅读运行器的输出以了解原因。

623* **看起来健康的环境**:某些启动步骤在运行器向您的环境注册后运行,例如 [`--configure-git`](#let-the-runner-configure-git) 和 Anthropic git 代理的凭证设置。如果其中一个步骤失败,环境可以在该进程退出后的几分钟内继续列出该运行器,并且 **Cloud environments** 页面可以读取 **Healthy**,而没有运行器拾取工作。如果会话在看起来健康的环境中保持排队,请检查您的监督程序是否在重新启动运行器。

624 

625<h4 id="restart-with-a-wait-that-grows">

626 使用增长的等待时间重新启动

627</h4>

628 

629如何获得增长的等待时间取决于您的监督程序。

630 

631* **Kubernetes**:此页面上的 [Deployment](#kubernetes) 不需要更改。容器退出后,kubelet 默认在重新启动容器之前等待,并且等待时间在每次重新启动时增长到一个上限。一旦容器运行了一段时间而没有退出,等待就会重新开始。

632 

633 当容器仅运行很短时间时,kubelet 在正常退出后应用相同的等待。经常耗尽的运行器因此也可以显示 `CrashLoopBackOff` 状态,所以在得出运行器无法启动的结论之前请阅读输出。下面的命令从 Deployment 的一个 pod 读取最后一次运行的输出:

634 

635 ```bash theme={null}

636 kubectl logs --previous -n claude-runners deploy/claude-runner

637 ```

638 

639 当最后一次运行是启动失败时,`[runner:fatal]` 或 `error:` 行在输出的最后几行中。要读取另一个 pod 的最后一次运行,请在 `deploy/claude-runner` 的位置命名该 pod。

640* **Docker 和 Docker Compose**:此页面上的 [Compose recipe](#docker-compose) 不需要更改。使用 `restart: always`,Docker 在保持退出的容器的每次重新启动之前等待更长时间,直到一个上限。在下面的命令中用容器的名称替换 `<container>`,该命令读取 Docker 重新启动容器的次数:

641 

642 ```bash theme={null}

643 docker inspect --format '{{.RestartCount}}' <container>

644 ```

645 

646 该命令打印一个数字。不断增加的数字意味着 Docker 不断重新启动运行器。

647* **systemd 单元**:默认情况下,systemd 在每次重新启动之前等待相同的 `RestartSec`,并且不会延长它,因此具有 `Restart=always` 的单元以相同的间隔重新启动无法启动的运行器。当启动速度足够快以达到单元的启动速率限制(默认为 10 秒内 5 次启动)时,systemd 停止重新启动该单元。该单元保持停止状态,直到有人再次启动它,systemd 允许在速率限制的间隔已过或在 `systemctl reset-failed` 之后启动。因为 `RestartSec` 适用于每次重新启动,更长的值也会延迟正常退出后的重新启动。选择一个平衡两者的值,并对单元的重新启动计数进行警报。

648* **shell 循环或您自己的监督程序**:自己应用相同的规则。从 5 秒的等待开始。在每次在一分钟内结束的运行之后,将下一次重新启动的等待加倍,最多 5 分钟。在运行了一分钟或更长时间的运行之后,回到 5 秒。

649 

650<h4 id="check-why-the-runner-keeps-exiting">

651 检查运行器为什么保持退出

652</h4>

653 

654当运行器连续多次在启动后立即退出时,在再次重新启动之前停止并检查这些。

655 

656* **最后的 `[runner:fatal]` 或 `error:` 行**:它说明运行器停止的原因。[故障排除](#troubleshooting) 列出了常见原因。

657* **标志的组合**:[Anthropic git 代理](#use-the-anthropic-git-proxy) 需要 `--capacity 1`。此页面上的配方使用更高的容量,因此当您将代理添加到其中一个时降低它。

658* **服务的环境可以到达什么**:如果运行器手动启动并在您的监督程序下失败,请比较用户、主目录、`PATH` 和内存限制。`--configure-git` 和 Anthropic git 代理需要 `PATH` 上的 git 和可写的 `~/.gitconfig`。

659* **环境密钥**:如果您撤销了密钥或输入错误,运行器会打印一行包含 `RegisterRunner auth failed`。

660* **环境的 Activity 标签**:打开环境并选择 **Activity**。如果新运行器不断出现在那里,但没有拾取工作,您的监督程序正在重新启动运行器。

661 

662如需在运行器主机上进行引导式诊断,请运行 [doctor 子命令](#troubleshooting)。

663 

557<h2 id="what’s-next">664<h2 id="what’s-next">

558 接下来665 接下来

559</h2>666</h2>

Details

105 </Step>105 </Step>

106</Steps>106</Steps>

107 107 

108运行器在其活跃会话完成后按设计退出;请参阅[运行器生命周期](/docs/zh-CN/self-hosted-environments#runner-lifecycle)。对于生产,在编排器下部署它,该编排器在退出时重新启动它。请参阅[部署到生产环境](/docs/zh-CN/self-hosted-environments-deploy)。108运行器在其活跃会话完成后按设计退出;请参阅[运行器生命周期](/docs/zh-CN/self-hosted-environments#runner-lifecycle)。对于生产,在编排器下部署它,该编排器在退出时重新启动它,并在运行器启动后立即继续退出时等待更长的时间再重新启动。请参阅[部署到生产环境](/docs/zh-CN/self-hosted-environments-deploy)和[当运行器退出时](/docs/zh-CN/self-hosted-environments-deploy#when-the-runner-exits)。

109 109 

110<h2 id="send-a-follow-up-message-to-a-running-session">110<h2 id="send-a-follow-up-message-to-a-running-session">

111 向运行中的会话发送后续消息111 向运行中的会话发送后续消息

Details

595| [`agent`](#agent) | 将每个会话作为具有其提示、工具和模型的命名[子代理](/docs/zh-CN/sub-agents)启动 | 代理、会话和工作树 | Any file |595| [`agent`](#agent) | 将每个会话作为具有其提示、工具和模型的命名[子代理](/docs/zh-CN/sub-agents)启动 | 代理、会话和工作树 | Any file |

596| [`agentPushNotifEnabled`](#agentpushnotifenabled) | 让 Claude 在决定时向您的手机发送[推送通知](/docs/zh-CN/remote-control#mobile-push-notifications) | 远程、桌面和通知 | Any file |596| [`agentPushNotifEnabled`](#agentpushnotifenabled) | 让 Claude 在决定时向您的手机发送[推送通知](/docs/zh-CN/remote-control#mobile-push-notifications) | 远程、桌面和通知 | Any file |

597| [`allowAllClaudeAiMcps`](#allowallclaudeaimcps) | 加载[claude.ai 连接器](/docs/zh-CN/mcp),Claude Code 与部署的 [`managed-mcp.json`](/docs/zh-CN/managed-mcp#exclusive-control-with-managed-mcp-json) 一起自行获取 | MCP | Managed |597| [`allowAllClaudeAiMcps`](#allowallclaudeaimcps) | 加载[claude.ai 连接器](/docs/zh-CN/mcp),Claude Code 与部署的 [`managed-mcp.json`](/docs/zh-CN/managed-mcp#exclusive-control-with-managed-mcp-json) 一起自行获取 | MCP | Managed |

598| [`allowClaudeInChromeWithManagedMcp`](#allowclaudeinchromewithmanagedmcp) | 让内置的[Chrome 中的 Claude](/docs/zh-CN/chrome)服务器与部署的 [`managed-mcp.json`](/docs/zh-CN/managed-mcp#exclusive-control-with-managed-mcp-json) 一起运行 | MCP | Managed |

598| [`allowedChannelPlugins`](#allowedchannelplugins) | 替换可以推送消息的[频道插件](/docs/zh-CN/channels#restrict-which-channel-plugins-can-run)的默认允许列表 | 插件和技能 | Managed |599| [`allowedChannelPlugins`](#allowedchannelplugins) | 替换可以推送消息的[频道插件](/docs/zh-CN/channels#restrict-which-channel-plugins-can-run)的默认允许列表 | 插件和技能 | Managed |

599| [`allowedHttpHookUrls`](#allowedhttphookurls) | 限制[HTTP hooks](/docs/zh-CN/hooks)可以针对的 URL | Hooks 和自动化 | Any file |600| [`allowedHttpHookUrls`](#allowedhttphookurls) | 限制[HTTP hooks](/docs/zh-CN/hooks)可以针对的 URL | Hooks 和自动化 | Any file |

600| [`allowedMcpServers`](#allowedmcpservers) | 允许列表用户可以添加的[MCP 服务器](/docs/zh-CN/mcp) | MCP | Any file |601| [`allowedMcpServers`](#allowedmcpservers) | 允许列表用户可以添加的[MCP 服务器](/docs/zh-CN/mcp) | MCP | Any file |


3062</h4>3063</h4>

3063 3064 

3064* 此处的值覆盖在您的 shell 中导出的相同变量,当多个设置文件设置一个变量时,[最高优先级](/docs/zh-CN/settings#settings-precedence)的值适用。[Claude Code 在 `env` 中忽略的变量](#variables-claude-code-ignores-in-env)列出了项目和本地设置的例外。3065* 此处的值覆盖在您的 shell 中导出的相同变量,当多个设置文件设置一个变量时,[最高优先级](/docs/zh-CN/settings#settings-precedence)的值适用。[Claude Code 在 `env` 中忽略的变量](#variables-claude-code-ignores-in-env)列出了项目和本地设置的例外。

3066* 当 Claude Desktop 应用或[自托管环境](/docs/zh-CN/self-hosted-environments)运行器启动会话时,它构建的启动环境优先:Claude Code 忽略任何设置文件中的 `env` 值,用于启动环境已经设置的变量。[调试日志](/docs/zh-CN/debug-your-config)命名每个被忽略的变量。

3065* 要取消 shell 导出,将变量设置为 `""`。Claude Code 将空值视为提供程序选择的未设置,子进程继承空值。3067* 要取消 shell 导出,将变量设置为 `""`。Claude Code 将空值视为提供程序选择的未设置,子进程继承空值。

3066* `NO_COLOR` 和 `FORCE_COLOR` 在此处设置仅到达子进程。要更改 Claude Code 自己的界面颜色,请在启动 `claude` 之前在您的 shell 中设置它们。3068* `NO_COLOR` 和 `FORCE_COLOR` 在此处设置仅到达子进程。要更改 Claude Code 自己的界面颜色,请在启动 `claude` 之前在您的 shell 中设置它们。

3067* 此处的值是设置文件中的纯文本,到达 Claude Code 启动的每个子进程。对于轮换的 OTLP 承载令牌,使用 [`otelHeadersHelper`](#otelheadershelper);对于 API 凭证,使用 [`apiKeyHelper`](#apikeyhelper)。3069* 此处的值是设置文件中的纯文本,到达 Claude Code 启动的每个子进程。对于轮换的 OTLP 承载令牌,使用 [`otelHeadersHelper`](#otelheadershelper);对于 API 凭证,使用 [`apiKeyHelper`](#apikeyhelper)。


5155 5157 

5156[`allowedMcpServers`](#allowedmcpservers) 和 [`deniedMcpServers`](#deniedmcpservers) 仍然适用于此密钥加载的连接器。传递到[云会话](/docs/zh-CN/claude-code-on-the-web)的连接器,其主机携带 `managed-mcp.json`(例如自托管运行器),仍然会被禁止。请参阅[在托管集合旁边允许 claude.ai 连接器](/docs/zh-CN/managed-mcp#allow-claude-ai-connectors-alongside-the-managed-set)。5158[`allowedMcpServers`](#allowedmcpservers) 和 [`deniedMcpServers`](#deniedmcpservers) 仍然适用于此密钥加载的连接器。传递到[云会话](/docs/zh-CN/claude-code-on-the-web)的连接器,其主机携带 `managed-mcp.json`(例如自托管运行器),仍然会被禁止。请参阅[在托管集合旁边允许 claude.ai 连接器](/docs/zh-CN/managed-mcp#allow-claude-ai-connectors-alongside-the-managed-set)。

5157 5159 

5160<h3 id="allowclaudeinchromewithmanagedmcp">

5161 `allowClaudeInChromeWithManagedMcp`

5162</h3>

5163 

5164让内置的 [Chrome 中的 Claude](/docs/zh-CN/chrome) 服务器在部署的 `managed-mcp.json` 旁边运行。如果没有此密钥,部署的 `managed-mcp.json` 会在终端会话中阻止 Chrome 中的 Claude。需要 Claude Code v2.1.282 或更高版本。

5165 

5166* **作用域**: [`Managed`](#scopes),仅来自设备自己的托管设置:MDM 部署的 plist 或 HKLM 注册表密钥,或系统 `managed-settings.json` 文件。Claude Code 在服务器托管的设置、用户可写的 HKCU 注册表以及用户或项目设置中忽略它。

5167* **类型**: 布尔值

5168 * `true`: 内置的 Chrome 中的 Claude 服务器可以在部署的 `managed-mcp.json` 旁边运行

5169 * `false`: 部署的 `managed-mcp.json` 会在终端会话中阻止 Chrome 中的 Claude

5170* **默认值**: `false`,因此部署的 `managed-mcp.json` 会在终端会话中阻止 Chrome 中的 Claude

5171 

5172```json managed-settings.json theme={null}

5173{

5174 "allowClaudeInChromeWithManagedMcp": true

5175}

5176```

5177 

5178[`deniedMcpServers`](#deniedmcpservers) 中的 `claude-in-chrome` 条目仍然会在此密钥打开时阻止服务器。请参阅[在托管集合旁边允许 Chrome 中的 Claude](/docs/zh-CN/managed-mcp#allow-claude-in-chrome-alongside-the-managed-set)。

5179 

5158<h3 id="allowedmcpservers">5180<h3 id="allowedmcpservers">

5159 `allowedMcpServers`5181 `allowedMcpServers`

5160</h3>5182</h3>

5161 5183 

5162允许列表化人们可以添加的 MCP 服务器。Claude Code 会阻止任何不匹配条目的服务器,无论在何处定义,包括插件服务器、使用 `--mcp-config` 传递的服务器以及来自 claude.ai 的服务器。5184允许列表化人们可以添加的 MCP 服务器。Claude Code 会阻止任何不匹配条目的服务器,无论在何处定义,包括插件服务器、使用 `--mcp-config` 传递的服务器以及来自 claude.ai 的服务器。

5163 5185 

5164内置服务器(例如 Chrome 中的 Claude、Claude Code 在运行的 [VS Code](/docs/zh-CN/vs-code#the-built-in-ide-mcp-server) 或 [JetBrains](/docs/zh-CN/jetbrains#the-built-in-ide-mcp-server) IDE 中连接的 `ide` 服务器,以及 CLI 本身配置的服务器)不受允许列表的限制,拒绝列表仍然适用于它们。进程内 `type: "sdk"` 服务器不受两个列表的限制;[启动会话的应用](/docs/zh-CN/mcp#how-connectors-reach-claude-code)会注册它们。5186内置服务器(例如 Chrome 中的 Claude、Claude Code 在运行的 [VS Code](/docs/zh-CN/vs-code#the-built-in-ide-mcp-server) 或 [JetBrains](/docs/zh-CN/jetbrains#the-built-in-ide-mcp-server) IDE 中连接的 `ide` 服务器,以及 CLI 本身配置的服务器)不受允许列表的限制,拒绝列表仍然适用于它们。在 Claude Code v2.1.268 或更高版本上,[Claude Tag](/docs/zh-CN/claude-tag) 会话的 Slack 工具也不受允许列表的限制,拒绝列表仍然适用于它们。进程内 `type: "sdk"` 服务器不受两个列表的限制;[启动会话的应用](/docs/zh-CN/mcp#how-connectors-reach-claude-code)会注册它们。

5165 5187 

5166您的组织提供的服务器也不受允许列表的限制,拒绝列表仍然适用于它们。豁免涵盖每个 [`managedMcpServers`](#managedmcpservers) 条目,以及任何 [`managed-mcp.json`](/docs/zh-CN/managed-mcp#exclusive-control-with-managed-mcp-json) 条目,其值不使用 `${VAR}` 扩展。有关完整的检查顺序,请参阅[如何评估服务器](/docs/zh-CN/managed-mcp#how-a-server-is-evaluated)。在 v2.1.259 之前,来自 `managed-mcp.json` 的服务器也必须匹配。5188您的组织提供的服务器也不受允许列表的限制,拒绝列表仍然适用于它们。豁免涵盖每个 [`managedMcpServers`](#managedmcpservers) 条目,以及任何 [`managed-mcp.json`](/docs/zh-CN/managed-mcp#exclusive-control-with-managed-mcp-json) 条目,其值不使用 `${VAR}` 扩展。有关完整的检查顺序,请参阅[如何评估服务器](/docs/zh-CN/managed-mcp#how-a-server-is-evaluated)。在 v2.1.259 之前,来自 `managed-mcp.json` 的服务器也必须匹配。

5167 5189 


6302 `disableSideloadFlags`6324 `disableSideloadFlags`

6303</h3>6325</h3>

6304 6326 

6305在启动时拒绝 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` CLI 标志,用户可能会传递这些标志来绕过 [`strictKnownMarketplaces`](#strictknownmarketplaces) 进行单次运行。Claude Code 会以错误退出并命名被拒绝的标志,并对在内部使用这些标志启动 CLI 的表面应用相同的检查,目前在桌面应用中的 [Cowork](/docs/zh-CN/desktop) 本地会话。在[云会话](/docs/zh-CN/claude-code-on-the-web)中,Claude Code 会删除服务器通过 `--mcp-config` 传递的 MCP 服务器,除了进程内 `type: "sdk"` 条目,并启动会话。需要 Claude Code v2.1.193 或更高版本。6327在启动时拒绝 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` CLI 标志,用户可能会传递这些标志来绕过 [`strictKnownMarketplaces`](#strictknownmarketplaces) 进行单次运行。Claude Code 会以错误退出并命名被拒绝的标志,并对在内部使用这些标志启动 CLI 的表面应用相同的检查,目前在桌面应用中的 [Cowork](/docs/zh-CN/desktop) 本地会话。在[云会话](/docs/zh-CN/claude-code-on-the-web)中,Claude Code 会启动会话并删除服务器通过 `--mcp-config` 传递的每个条目,除了进程内 `type: "sdk"` 条目和 [Claude Tag](/docs/zh-CN/claude-tag) 会话的 Slack 工具。需要 Claude Code v2.1.193 或更高版本。

6306 6328 

6307* **Scope**: [`Managed`](#scopes)6329* **Scope**: [`Managed`](#scopes)

6308* **Type**: Boolean6330* **Type**: Boolean

6309 * `true`: Claude Code 在启动时拒绝 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config`,并以错误退出并命名它们,除了在云会话中它删除服务器通过 `--mcp-config` 传递的 MCP 服务器,除了进程内 `type: "sdk"` 条目,并启动会话6331 * `true`: Claude Code 在启动时拒绝 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config`,并以错误退出并命名它们。在云会话中,它会启动会话并删除服务器通过 `--mcp-config` 传递的每个条目,除了进程内 `type: "sdk"` 条目和 Claude Tag 会话的 Slack 工具

6310 * `false`: Claude Code 接受这些标志6332 * `false`: Claude Code 接受这些标志

6311* **Default**: `false`6333* **Default**: `false`

6312 6334 


6320 6342 

6321相同的检查涵盖在 [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/zh-CN/env-vars#variables) 环境变量中命名的插件文件夹,这需要 Claude Code v2.1.280 或更高版本。当变量命名一个文件夹时,Claude Code 以相同的错误退出,错误说要取消设置该变量。6343相同的检查涵盖在 [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/zh-CN/env-vars#variables) 环境变量中命名的插件文件夹,这需要 Claude Code v2.1.280 或更高版本。当变量命名一个文件夹时,Claude Code 以相同的错误退出,错误说要取消设置该变量。

6322 6344 

6323在云会话中,Claude Code 也忽略服务器传递的中途 MCP 更新,云会话配置和 SDK `setMcpServers()` 调用背后的路径到达这些会话。进程内 `type: "sdk"` 条目在那里也保持豁免。在 v2.1.239 之前,服务器传递的 `--mcp-config` 阻止云会话启动。6345在云会话中,Claude Code 也忽略服务器传递的中途 MCP 更新,云会话配置和 SDK `setMcpServers()` 调用背后的路径到达这些会话。进程内 `type: "sdk"` 条目和 Claude Tag 会话的 Slack 工具在那里也保持豁免。在 v2.1.268 之前,这个删除和启动删除也删除了 Claude Tag 会话的 Slack 工具。在 v2.1.239 之前,服务器传递的 `--mcp-config` 阻止云会话启动。

6324 6346 

6325<h3 id="forceremotesettingsrefresh">6347<h3 id="forceremotesettingsrefresh">

6326 `forceRemoteSettingsRefresh`6348 `forceRemoteSettingsRefresh`

statusline.md +1 −1

Details

1178**上下文百分比显示意外值**1178**上下文百分比显示意外值**

1179 1179 

1180* 使用 `used_percentage` 获得最简单的准确上下文状态1180* 使用 `used_percentage` 获得最简单的准确上下文状态

1181* 上下文百分比可能与 `/context` 输出不同,因为每个的计算时间不同1181* 状态行报告来自最后一次 API 响应的计数,而 `/context` 添加了自该响应以来添加的消息的估计值,因此 `/context` 可以读取更高的值,直到下一次响应

1182 1182 

1183**OSC 8 链接不可点击**1183**OSC 8 链接不可点击**

1184 1184 

sub-agents.md +4 −4

Details

30 内置 subagents30 内置 subagents

31</h2>31</h2>

32 32 

33Claude Code 包括内置 subagents,Claude 在适当时自动使用。每个都继承父对话的权限;大多数运行时工具集受限。33Claude Code 包括内置 subagents,Claude 在适当时自动使用。每个都继承父对话的权限规则;大多数运行时工具集受限。

34 34 

35Explore 和 Plan 会跳过您的 CLAUDE.md 文件和 git 状态快照,以保持研究快速且成本低廉。所有其他内置和[自定义 subagent](#configure-subagents) 都会加载两者,除非其定义设置了 [`omitClaudeMd`](#supported-frontmatter-fields) 字段以跳过用户、项目和本地 CLAUDE.md 文件。有关到达 subagent 的内容的完整分解,请参阅[启动时加载的内容](#what-loads-at-startup)。35Explore 和 Plan 会跳过您的 CLAUDE.md 文件和 git 状态快照,以保持研究快速且成本低廉。所有其他内置和[自定义 subagent](#configure-subagents) 都会加载两者,除非其定义设置了 [`omitClaudeMd`](#supported-frontmatter-fields) 字段以跳过用户、项目和本地 CLAUDE.md 文件。有关到达 subagent 的内容的完整分解,请参阅[启动时加载的内容](#what-loads-at-startup)。

36 36 


802 - matcher: "Bash"802 - matcher: "Bash"

803 hooks:803 hooks:

804 - type: command804 - type: command

805 command: "./scripts/validate-command.sh $TOOL_INPUT"805 command: "./scripts/validate-command.sh"

806 PostToolUse:806 PostToolUse:

807 - matcher: "Edit|Write"807 - matcher: "Edit|Write"

808 hooks:808 hooks:


897 897 

898您也可以手动输入提及而不使用选择器:`@agent-<name>` 用于本地 subagents,或 `@agent-` 后跟 plugin subagents 的作用域名称,例如 `@agent-my-plugin:code-reviewer`。当您输入这种形式时,类型提前显示文件匹配而不是 agents。当您提交时,agent 提及仍然会解析。898您也可以手动输入提及而不使用选择器:`@agent-<name>` 用于本地 subagents,或 `@agent-` 后跟 plugin subagents 的作用域名称,例如 `@agent-my-plugin:code-reviewer`。当您输入这种形式时,类型提前显示文件匹配而不是 agents。当您提交时,agent 提及仍然会解析。

899 899 

900**将整个会话作为 subagent 运行。** 传递 [`--agent <name>`](/docs/zh-CN/cli-reference) 以启动一个会话,其中主线程本身采用该 subagent 的系统提示、工具限制和模型:900**将整个会话作为 subagent 运行。** 传递 [`--agent <name>`](/docs/zh-CN/cli-reference) 以启动一个会话,其中主线程本身采用该 subagent 的工具限制和模型:

901 901 

902```bash theme={null}902```bash theme={null}

903claude --agent code-reviewer903claude --agent code-reviewer

904```904```

905 905 

906除非代理的 [提示为空](#choose-the-subagent-scope),subagent 的系统提示完全替换默认 Claude Code 系统提示,就像 [`--system-prompt`](/docs/zh-CN/cli-reference) 一样。`CLAUDE.md` 文件和项目内存仍然通过正常消息流加载,即使代理的定义设置了 [`omitClaudeMd`](#supported-frontmatter-fields)。代理名称在启动标题中显示为 `@<name>`,以便您可以确认它是活跃的。906除非代理的 [提示为空](#choose-the-subagent-scope),custom subagent 的系统提示完全替换默认 Claude Code 系统提示,就像 [`--system-prompt`](/docs/zh-CN/cli-reference) 一样。`CLAUDE.md` 文件和项目内存仍然通过正常消息流加载,即使代理的定义设置了 [`omitClaudeMd`](#supported-frontmatter-fields)。代理名称在启动标题中显示为 `@<name>`,以便您可以确认它是活跃的。

907 907 

908这适用于内置和自定义 subagents,当您恢复会话时选择会持续:Claude Code 恢复代理的工具限制和模型以及对话。如果代理在您恢复时不再存在,会话继续使用默认工具并显示 [警告命名代理](/docs/zh-CN/errors#session-agent-no-longer-available)。对于任一情况下的系统提示,请参阅 [已恢复对话中的系统提示标志](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。908这适用于内置和自定义 subagents,当您恢复会话时选择会持续:Claude Code 恢复代理的工具限制和模型以及对话。如果代理在您恢复时不再存在,会话继续使用默认工具并显示 [警告命名代理](/docs/zh-CN/errors#session-agent-no-longer-available)。对于任一情况下的系统提示,请参阅 [已恢复对话中的系统提示标志](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。

909 909 

Details

122 122 

123 <tr>123 <tr>

124 <td>计费</td>124 <td>计费</td>

125 <td><strong>Teams:</strong> \$150/座位(Premium)提供按使用量付费选项<br /><strong>Enterprise:</strong> <a href="https://claude.com/contact-sales?utm_source=claude_code&utm_medium=docs&utm_content=third_party_enterprise">联系销售</a></td>125 <td><strong>Teams:</strong> 按座位订阅,提供按使用量付费选项,请参阅<a href="https://claude.com/pricing?utm_source=claude_code&utm_medium=docs&utm_content=third_party_pricing#team-&-enterprise">定价</a><br /><strong>Enterprise:</strong> <a href="https://claude.com/contact-sales?utm_source=claude_code&utm_medium=docs&utm_content=third_party_enterprise">联系销售</a></td>

126 <td>按使用量付费</td>126 <td>按使用量付费</td>

127 <td>通过 AWS 按使用量付费</td>127 <td>通过 AWS 按使用量付费</td>

128 <td>通过 AWS Marketplace 按使用量付费</td>128 <td>通过 AWS Marketplace 按使用量付费</td>

Details

445 TLS 或 SSL 连接错误445 TLS 或 SSL 连接错误

446</h3>446</h3>

447 447 

448诸如 `curl: (35) TLS connect error`、`schannel: next InitializeSecurityContext failed` 或 PowerShell 的 `Could not establish trust relationship for the SSL/TLS secure channel` 之类的错误表示 TLS 握手失败。448诸如以下错误意味着 TLS 握手失败:

449 

450* `curl: (35) TLS connect error`

451* `schannel: next InitializeSecurityContext failed`

452* PowerShell 的 `Could not create SSL/TLS secure channel`

453* PowerShell 的 `Could not establish trust relationship for the SSL/TLS secure channel`

449 454 

450**解决方案:**455**解决方案:**

451 456 

Details

52 `.heapsnapshot` 文件包含进程中的每个字符串,包括您的完整对话和凭证。不要将其附加到公开问题或共享。52 `.heapsnapshot` 文件包含进程中的每个字符串,包括您的完整对话和凭证。不要将其附加到公开问题或共享。

53</Warning>53</Warning>

54 54 

55该命令还在对话中打印摘要,显示驻留集大小、JS 堆、数组缓冲区和未计算的本机内存,以及它检测到的任何泄漏指示器,例如高内存增长率或异常高的打开句柄数。摘要说明大部分内存是在 JS 堆中(快照捕获)还是在本机内存中(它不捕获)。55该命令还在对话中打印摘要,显示进程的总内存、其中有多少在 JS 堆中,以及有多少在堆外。摘要还列出任何泄漏指示器,例如高内存增长率或异常高的打开句柄数。摘要说明大部分内存是在 JS 堆中(快照捕获),还是在本机内存中(它不捕获)。

56 56 

57对输出执行以下两项操作之一:57对输出执行以下两项操作之一:

58 58 

workflows.md +1 −1

Details

91 观看运行91 观看运行

92</h3>92</h3>

93 93 

94工作流在后台运行,所以会话在代理工作时保持响应。随时运行 `/workflows` 列出运行中和已完成的工作流,然后选择一个打开其进度视图。94工作流在后台运行,所以会话在代理工作时保持响应。随时运行 `/workflows` 列出运行中和已完成的工作流,然后选择一个打开其进度视图。要停止运行中的工作流而不打开它,在列表中选择它并按 `x`。

95 95 

96进度视图显示每个阶段及其代理计数、令牌总数和经过的时间。页脚列出每个操作的键:96进度视图显示每个阶段及其代理计数、令牌总数和经过的时间。页脚列出每个操作的键:

97 97