Documentation — Spybara

admin-setup.md +6 −6

Details

15</Note>15</Note>

16 16

17| 决策 | 您的选择 | 参考 |17| 决策 | 您的选择 | 参考 |

18| :----------------------------------------------- | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |18| :----------------------------------------------- | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

19| [选择您的 API 提供商](#choose-your-api-provider) | Claude Code 的身份验证位置和计费方式 | [Authentication](/zh-CN/authentication)、[Bedrock](/zh-CN/amazon-bedrock)、[Vertex AI](/zh-CN/google-vertex-ai)、[Foundry](/zh-CN/microsoft-foundry) |19| [选择您的 API 提供商](#choose-your-api-provider) | Claude Code 的身份验证位置和计费方式 | [Authentication](/zh-CN/authentication)、[Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud's Agent Platform](/zh-CN/google-vertex-ai)、[Microsoft Foundry](/zh-CN/microsoft-foundry) |

33| Claude for Teams / Enterprise | 您希望 Claude Code 和 claude.ai 在一个按座位订阅下，无需运行基础设施。这是默认建议。 |33| Claude for Teams / Enterprise | 您希望 Claude Code 和 claude.ai 在一个按座位订阅下，无需运行基础设施。这是默认建议。 |

34| Claude Console | 您是 API 优先或希望按使用量付费 |34| Claude Console | 您是 API 优先或希望按使用量付费 |

35| Amazon Bedrock | 您希望继承现有的 AWS 合规控制和计费 |35| Amazon Bedrock | 您希望继承现有的 AWS 合规控制和计费 |

~~36| Google Vertex AI | 您希望继承现有的 GCP 合规控制和计费 |~~36| Google Cloud's Agent Platform | 您希望继承现有的 GCP 合规控制和计费 |

37| Microsoft Foundry | 您希望继承现有的 Azure 合规控制和计费 |37| Microsoft Foundry | 您希望继承现有的 Azure 合规控制和计费 |

38 38

39某些 Claude Code 功能需要 claude.ai 账户。[Claude Code on the web](/zh-CN/claude-code-on-the-web)、[Routines](/zh-CN/routines)、[Code Review](/zh-CN/code-review)、[Remote Control](/zh-CN/remote-control) 和 [Chrome extension](/zh-CN/chrome) 不能仅通过 Console API 密钥或云提供商凭证使用。如果您通过 Bedrock、Vertex 或 Foundry 部署，请计划开发人员是否还需要 Claude for Teams 或 Enterprise 座位。每个功能页面都列出了其计划要求。39某些 Claude Code 功能需要 claude.ai 账户。[Claude Code on the web](/zh-CN/claude-code-on-the-web)、[Routines](/zh-CN/routines)、[Code Review](/zh-CN/code-review)、[Remote Control](/zh-CN/remote-control) 和 [Chrome extension](/zh-CN/chrome) 不能仅通过 Console API 密钥或云提供商凭证使用。如果您通过 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 部署，请计划开发人员是否还需要 Claude for Teams 或 Enterprise 座位。每个功能页面都列出了其计划要求。

40 40

41有关涵盖身份验证、区域和功能奇偶性的完整提供商比较，请参阅 [enterprise deployment overview](/zh-CN/third-party-integrations)。每个提供商的身份验证设置在 [Authentication](/zh-CN/authentication) 中。41有关涵盖身份验证、区域和功能奇偶性的完整提供商比较，请参阅 [enterprise deployment overview](/zh-CN/third-party-integrations)。每个提供商的身份验证设置在 [Authentication](/zh-CN/authentication) 中。

42 42

57 57

58已配置的 [`policyHelper`](/zh-CN/settings#compute-managed-settings-with-a-policy-helper) 会抢占所有四个来源：其输出成为该运行的唯一托管配置。请参阅[设置优先级](/zh-CN/settings#settings-precedence)。58已配置的 [`policyHelper`](/zh-CN/settings#compute-managed-settings-with-a-policy-helper) 会抢占所有四个来源：其输出成为该运行的唯一托管配置。请参阅[设置优先级](/zh-CN/settings#settings-precedence)。

59 59

60Server-managed 设置在身份验证时到达设备，并在活跃会话期间每小时刷新一次，无需端点基础设施。通过 claude.ai 管理控制台传递需要 Claude for Teams 或 Enterprise 计划。在 Bedrock、Vertex AI 或 Foundry 上的部署可以通过运行 [Claude apps gateway](/zh-CN/claude-apps-gateway) 获得相同的远程传递，或改用基于文件或操作系统级别的机制之一。60Server-managed 设置在身份验证时到达设备，并在活跃会话期间每小时刷新一次，无需端点基础设施。通过 claude.ai 管理控制台传递需要 Claude for Teams 或 Enterprise 计划。在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上的部署可以通过运行 [Claude apps gateway](/zh-CN/claude-apps-gateway) 获得相同的远程传递，或改用基于文件或操作系统级别的机制之一。

61 61

62如果您的组织混合使用提供商，请为 claude.ai 用户配置 [server-managed settings](/zh-CN/server-managed-settings) 加上 [file-based 或 plist/registry 回退](/zh-CN/settings#settings-files)，以便其他用户仍然接收托管策略。62如果您的组织混合使用提供商，请为 claude.ai 用户配置 [server-managed settings](/zh-CN/server-managed-settings) 加上 [file-based 或 plist/registry 回退](/zh-CN/settings#settings-files)，以便其他用户仍然接收托管策略。

63 63

153* [Server-managed settings](/zh-CN/server-managed-settings)：从 Claude 管理控制台传递托管策略153* [Server-managed settings](/zh-CN/server-managed-settings)：从 Claude 管理控制台传递托管策略

154* [Settings reference](/zh-CN/settings)：每个设置键、文件位置和优先级规则154* [Settings reference](/zh-CN/settings)：每个设置键、文件位置和优先级规则

155* [Monorepos and large repos](/zh-CN/large-codebases)：为部署到 monorepo 的组织提供的按目录配置模式155* [Monorepos and large repos](/zh-CN/large-codebases)：为部署到 monorepo 的组织提供的按目录配置模式

156* [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Vertex AI](/zh-CN/google-vertex-ai)、[Microsoft Foundry](/zh-CN/microsoft-foundry)：提供商特定部署156* [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud's Agent Platform](/zh-CN/google-vertex-ai)、[Microsoft Foundry](/zh-CN/microsoft-foundry)：提供商特定部署

157* [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide)：SSO、SCIM、座位管理和推出手册157* [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide)：SSO、SCIM、座位管理和推出手册

advisor.md +2 −2

Details

9{/* plan-availability: feature=advisor providers=anthropic */}9{/* plan-availability: feature=advisor providers=anthropic */}

10 10

11<Note>11<Note>

12 顾问工具是实验性的，需要 Claude Code v2.1.98 或更高版本以及 Anthropic API。它在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用。行为、定价和可用性可能会改变。12 顾问工具是实验性的，需要 Claude Code v2.1.98 或更高版本以及 Anthropic API。它在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。行为、定价和可用性可能会改变。

13</Note>13</Note>

14 14

15顾问工具让 Claude 在任务期间的关键时刻咨询第二个通常更强大的模型，例如在提交方法之前、陷入重复错误时或在声明任务完成之前。顾问接收完整的对话，包括每个工具调用和结果，并返回 Claude 在继续之前应用的指导。15顾问工具让 Claude 在任务期间的关键时刻咨询第二个通常更强大的模型，例如在提交方法之前、陷入重复错误时或在声明任务完成之前。顾问接收完整的对话，包括每个工具调用和结果，并返回 Claude 在继续之前应用的指导。

162顾问工具需要以下所有条件：162顾问工具需要以下所有条件：

163 163

164* **Claude Code v2.1.98 或更高版本**：运行 `claude update` 进行升级。164* **Claude Code v2.1.98 或更高版本**：运行 `claude update` 进行升级。

165* **仅 Anthropic API**：顾问是服务器执行的工具。它在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用。通过配置了 `ANTHROPIC_BASE_URL` 的 [LLM 网关](/zh-CN/llm-gateway)，可用性取决于网关是否将请求完整转发到 Anthropic API。165* **仅 Anthropic API**：顾问是服务器执行的工具。它在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。通过配置了 `ANTHROPIC_BASE_URL` 的 [LLM 网关](/zh-CN/llm-gateway)，可用性取决于网关是否将请求完整转发到 Anthropic API。

166* **支持的主模型**：Opus 4.6 或更高版本、Sonnet 4.6 或更高版本，或 Haiku 4.5。{/* min-version: 2.1.170 */}Fable 5 在 Claude Code v2.1.170 或更高版本上也符合条件。166* **支持的主模型**：Opus 4.6 或更高版本、Sonnet 4.6 或更高版本，或 Haiku 4.5。{/* min-version: 2.1.170 */}Fable 5 在 Claude Code v2.1.170 或更高版本上也符合条件。

167 167

168<h2 id="turn-the-advisor-off">168<h2 id="turn-the-advisor-off">

agent-sdk/agent-loop.md +7 −5

Details

202 202

203当达到任一限制时，SDK 返回一个 `ResultMessage`，包含相应的错误子类型（`error_max_turns` 或 `error_max_budget_usd`）。有关如何检查这些子类型，请参阅 [处理结果](#handle-the-result)，有关语法，请参阅 [`ClaudeAgentOptions`](/zh-CN/agent-sdk/python#claudeagentoptions) / [`Options`](/zh-CN/agent-sdk/typescript#options)。203当达到任一限制时，SDK 返回一个 `ResultMessage`，包含相应的错误子类型（`error_max_turns` 或 `error_max_budget_usd`）。有关如何检查这些子类型，请参阅 [处理结果](#handle-the-result)，有关语法，请参阅 [`ClaudeAgentOptions`](/zh-CN/agent-sdk/python#claudeagentoptions) / [`Options`](/zh-CN/agent-sdk/typescript#options)。

204 204

205使用 [流式输入](/zh-CN/agent-sdk/streaming-vs-single-mode)，当轮次在最大轮次限制处结束时，你在轮次仍在运行时发送的消息会保持排队状态，并在其自己的轮次中开始，具有自己的最大轮次限制。在 v2.1.205 之前，到达轮次最后迭代的消息可能会被消耗到结束轮次中并丢失，而不会到达模型。

206

205<h3 id="effort-level">207<h3 id="effort-level">

206 努力级别208 努力级别

207</h3>209</h3>

231权限模式选项（Python 中的 `permission_mode`，TypeScript 中的 `permissionMode`）控制代理是否在使用工具前请求批准：233权限模式选项（Python 中的 `permission_mode`，TypeScript 中的 `permissionMode`）控制代理是否在使用工具前请求批准：

232 234

233| 模式 | 行为 |235| 模式 | 行为 |

234| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |236| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

240| `"bypassPermissions"` | 运行所有允许的工具而不询问，除非显式 [`ask` 规则](/zh-CN/settings#permission-settings) 匹配；有关 ask 规则在优先级顺序中的位置，请参阅 [权限如何被评估](/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)。在 Unix 上以 root 身份运行时无法使用。仅在隔离环境中使用，其中代理的操作无法影响你关心的系统 |242| `"bypassPermissions"` | 运行所有允许的工具而不询问，除非显式 [`ask` 规则](/zh-CN/settings#permission-settings) 匹配；有关 ask 规则在优先级顺序中的位置，请参阅 [权限如何被评估](/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)。在 Unix 上以 root 身份运行时无法使用。仅在隔离环境中使用，其中代理的操作无法影响你关心的系统 |

241 243

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

260以下是每个组件如何影响 SDK 中上下文的方式：262以下是每个组件如何影响 SDK 中上下文的方式：

261 263

262| 源 | 何时加载 | 影响 |264| 源 | 何时加载 | 影响 |

263| :--------------- | :---------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |265| :--------------- | :---------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

266| **工具定义** | 每个请求；MCP 架构默认延迟 | 内置工具架构在每个请求中加载。[工具搜索](/zh-CN/agent-sdk/mcp#mcp-tool-search)默认延迟 MCP 工具架构，在 Vertex AI 或非第一方 `ANTHROPIC_BASE_URL` 上回退到预先加载。有关完整矩阵，请参阅[配置工具搜索](/zh-CN/agent-sdk/tool-search#configure-tool-search) |268| **工具定义** | 每个请求；MCP 架构默认延迟 | 内置工具架构在每个请求中加载。[工具搜索](/zh-CN/agent-sdk/mcp#mcp-tool-search)默认延迟 MCP 工具架构，在 Google Cloud 的 Agent Platform 或非第一方 `ANTHROPIC_BASE_URL` 上回退到预先加载。有关完整矩阵，请参阅[配置工具搜索](/zh-CN/agent-sdk/tool-search#configure-tool-search) |

269 271

305 307

306* **为子任务使用子代理。** 每个子代理以新鲜对话开始（没有先前的消息历史，尽管它确实加载自己的系统提示和项目级上下文，如 CLAUDE.md）。它看不到父级的轮次，只有其最终响应作为工具结果返回给父级。主代理的上下文增长该摘要，而不是完整的子任务成绩单。有关详情，请参阅[子代理继承什么](/zh-CN/agent-sdk/subagents#what-subagents-inherit)。308* **为子任务使用子代理。** 每个子代理以新鲜对话开始（没有先前的消息历史，尽管它确实加载自己的系统提示和项目级上下文，如 CLAUDE.md）。它看不到父级的轮次，只有其最终响应作为工具结果返回给父级。主代理的上下文增长该摘要，而不是完整的子任务成绩单。有关详情，请参阅[子代理继承什么](/zh-CN/agent-sdk/subagents#what-subagents-inherit)。

307* **对工具有选择性。** 每个工具定义占用上下文空间。在 [`AgentDefinition`](/zh-CN/agent-sdk/subagents#agentdefinition-configuration) 上使用 `tools` 字段将子代理限制在它们需要的最小集合。309* **对工具有选择性。** 每个工具定义占用上下文空间。在 [`AgentDefinition`](/zh-CN/agent-sdk/subagents#agentdefinition-configuration) 上使用 `tools` 字段将子代理限制在它们需要的最小集合。

308* **监视 MCP 服务器成本。** [MCP 工具搜索](/zh-CN/agent-sdk/mcp#mcp-tool-search)默认延迟 MCP 工具架构，并按需加载它们。当工具搜索关闭、在 Vertex AI 上或在非第一方 `ANTHROPIC_BASE_URL` 后面时，每个 MCP 服务器将其所有工具架构添加到每个请求，因此具有许多工具的几个服务器可以在代理执行任何工作之前消耗大量上下文。310* **监视 MCP 服务器成本。** [MCP 工具搜索](/zh-CN/agent-sdk/mcp#mcp-tool-search)默认延迟 MCP 工具架构，并按需加载它们。当工具搜索关闭、在 Google Cloud 的 Agent Platform 上或在非第一方 `ANTHROPIC_BASE_URL` 后面时，每个 MCP 服务器将其所有工具架构添加到每个请求，因此具有许多工具的几个服务器可以在代理执行任何工作之前消耗大量上下文。

309* **对常规任务使用较低的努力。** 为仅需要读取文件或列出目录的代理设置[努力](#effort-level)为 `"low"`。这减少了令牌使用和成本。311* **对常规任务使用较低的努力。** 为仅需要读取文件或列出目录的代理设置[努力](#effort-level)为 `"low"`。这减少了令牌使用和成本。

310 312

311有关每个功能上下文成本的详细分解，请参阅[理解上下文成本](/zh-CN/features-overview#understand-context-costs)。313有关每个功能上下文成本的详细分解，请参阅[理解上下文成本](/zh-CN/features-overview#understand-context-costs)。

agent-sdk/cost-tracking.md +2 −2

Details

292 将 prompt cache TTL 扩展到一小时292 将 prompt cache TTL 扩展到一小时

293</h3>293</h3>

294 294

295当您使用 API 密钥进行身份验证或在 Amazon Bedrock、Google Cloud Vertex AI 或 Microsoft Foundry 上运行时，SDK 写入的缓存条目默认使用 5 分钟 TTL。如果您的工作负载针对相同的系统提示和上下文运行许多短会话，且会话之间的间隔超过 5 分钟，缓存会在会话之间过期，每个新会话都会支付完整的输入价格。295当您使用 API 密钥进行身份验证或在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上运行时，SDK 写入的缓存条目默认使用 5 分钟 TTL。如果您的工作负载针对相同的系统提示和上下文运行许多短会话，且会话之间的间隔超过 5 分钟，缓存会在会话之间过期，每个新会话都会支付完整的输入价格。

296 296

297要请求缓存写入的 1 小时 TTL，请设置 [`ENABLE_PROMPT_CACHING_1H`](/zh-CN/env-vars) 环境变量。您可以在 shell 或容器环境中导出它，或通过 `options.env` 传递它。297要请求缓存写入的 1 小时 TTL，请设置 [`ENABLE_PROMPT_CACHING_1H`](/zh-CN/env-vars) 环境变量。您可以在 shell 或容器环境中导出它，或通过 `options.env` 传递它。

298 298

299以下示例为在 Bedrock 上运行的代理启用 1 小时 TTL：299以下示例为在 Amazon Bedrock 上运行的代理启用 1 小时 TTL：

300 300

301<CodeGroup>301<CodeGroup>

302 ```python Python theme={null}302 ```python Python theme={null}

agent-sdk/custom-tools.md +15 −13

Details

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

27| 扩展到许多工具 | 使用[工具搜索](/zh-CN/agent-sdk/tool-search)按需加载工具。 |27| 扩展到许多工具 | 使用[工具搜索](/zh-CN/agent-sdk/tool-search)按需加载工具。 |

356 处理错误356 处理错误

357</h2>357</h2>

358 358

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

360 360

361| 发生的情况 | 结果 |361| 发生的情况 | 结果 |

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

363| 处理程序抛出未捕获的异常 | 代理循环停止。Claude 永远看不到错误，`query` 调用失败。 |363| 处理程序抛出未捕获的异常 | MCP 服务器将其转换为错误结果，携带原始异常消息。Claude 看到该消息，代理循环继续。 |

365 365

366下面的示例在处理程序内部捕获两种失败，而不是让它们抛出。非 200 HTTP 状态从响应中捕获并作为错误结果返回。网络错误或无效 JSON 由周围的 `try/except`（Python）或 `try/catch`（TypeScript）捕获，也作为错误结果返回。在这两种情况下，处理程序正常返回，代理循环继续。366在这两种情况下，Claude 都可以重试、尝试不同的工具或解释失败。当原始异常消息不足以让 Claude 采取行动时，请自己捕获错误。

367

368下面的示例在处理程序内部捕获两种失败并编写 Claude 读取的错误消息。非 200 HTTP 状态从响应中捕获并作为错误结果返回。网络错误或无效 JSON 由周围的 `try/except`（Python）或 `try/catch`（TypeScript）捕获，也作为错误结果返回。在这两种情况下，Claude 都会收到描述失败的消息，而不是裸露的异常字符串。

367 369

368<CodeGroup>370<CodeGroup>

369 ```python Python theme={null}371 ```python Python theme={null}

397 data = response.json()399 data = response.json()

398 return {"content": [{"type": "text", "text": json.dumps(data, indent=2)}]}400 return {"content": [{"type": "text", "text": json.dumps(data, indent=2)}]}

399 except Exception as e:401 except Exception as e:

400 # Catching here keeps the agent loop alive. An uncaught exception402 # Composes the message Claude reads. An uncaught exception would

401 # would end the whole query() call.403 # reach Claude as the raw str(e) with no context.

402 return {404 return {

403 "content": [{"type": "text", "text": f"Failed to fetch data: {str(e)}"}],405 "content": [{"type": "text", "text": f"Failed to fetch data: {str(e)}"}],

404 "is_error": True,406 "is_error": True,

440 ]442 ]

441 };443 };

442 } catch (error) {444 } catch (error) {

443 // Catching here keeps the agent loop alive. An uncaught throw445 // Composes the message Claude reads. An uncaught throw would

444 // would end the whole query() call.446 // reach Claude as the raw error message with no context.

445 return {447 return {

446 content: [448 content: [

447 {449 {

461 返回图像和资源463 返回图像和资源

462</h2>464</h2>

463 465

464工具结果中的 `content` 数组接受 `text`、`image`、`audio`、`resource` 和 `resource_link` 块。您可以在同一响应中混合它们。音频块被保存到磁盘，Claude 接收一个包含保存文件路径的文本块。资源链接块被转换为包含链接名称、URI 和描述的文本块。466工具结果中的 `content` 数组接受 `text`、`image`、`audio`、`resource` 和 `resource_link` 块。您可以在同一响应中混合它们。在 TypeScript 中，音频块被保存到磁盘，Claude 接收一个包含保存文件路径的文本块；在 Python 中，SDK 从工具结果中删除音频块并记录警告。资源链接块被转换为包含链接名称、URI 和描述的文本块。

465 467

466<h3 id="images">468<h3 id="images">

467 图像469 图像

535资源块嵌入由 URI 标识的内容片段。URI 是 Claude 引用的标签；实际内容位于块的 `text` 或 `blob` 字段中。当您的工具生成稍后按名称寻址有意义的内容时使用此功能，例如生成的文件或来自外部系统的记录。537资源块嵌入由 URI 标识的内容片段。URI 是 Claude 引用的标签；实际内容位于块的 `text` 或 `blob` 字段中。当您的工具生成稍后按名称寻址有意义的内容时使用此功能，例如生成的文件或来自外部系统的记录。

536 538

537| 字段 | 类型 | 注释 |539| 字段 | 类型 | 注释 |

538| :------------------ | :----------- | :---------------------------- |540| :------------------ | :----------- | :------------------------------------------------------------- |

543| `resource.mimeType` | `string` | 可选 |545| `resource.mimeType` | `string` | 可选 |

544 546

545此示例显示从工具处理程序内部返回的资源块。URI `file:///tmp/report.md` 是 Claude 可以稍后引用的标签；SDK 不从该路径读取。547此示例显示从工具处理程序内部返回的资源块。URI `file:///tmp/report.md` 是 Claude 可以稍后引用的标签；SDK 不从该路径读取。

agent-sdk/hooks.md +1 −1

Details

250 250

251* **输入数据：** 一个包含事件详细信息的类型化对象。每个 hook 类型都有自己的输入形状。例如，`PreToolUseHookInput` 包括 `tool_name` 和 `tool_input`，而 `NotificationHookInput` 包括 `message`。请参阅 [TypeScript](/zh-CN/agent-sdk/typescript#hookinput) 和 [Python](/zh-CN/agent-sdk/python#hookinput) SDK 参考中的完整类型定义。251* **输入数据：** 一个包含事件详细信息的类型化对象。每个 hook 类型都有自己的输入形状。例如，`PreToolUseHookInput` 包括 `tool_name` 和 `tool_input`，而 `NotificationHookInput` 包括 `message`。请参阅 [TypeScript](/zh-CN/agent-sdk/typescript#hookinput) 和 [Python](/zh-CN/agent-sdk/python#hookinput) SDK 参考中的完整类型定义。

252 * 所有 hook 输入共享 `session_id`、`cwd` 和 `hook_event_name`。252 * 所有 hook 输入共享 `session_id`、`cwd` 和 `hook_event_name`。

253 * 当 hook 在子代理内触发时，`agent_id` 和 `agent_type` 被填充。在 TypeScript 中，这些在基础 hook 输入上，对所有 hook 类型都可用。在 Python 中，它们仅在 `PreToolUse`、`PostToolUse` 和 `PostToolUseFailure` 上。253 * 当 hook 在子代理内触发时，`agent_id` 和 `agent_type` 被填充。在 TypeScript 中，这些在基础 hook 输入上，对所有 hook 类型都可用。在 Python 中，它们是 `PreToolUse`、`PostToolUse`、`PostToolUseFailure` 和 `PermissionRequest` 上的可选字段，以及 `SubagentStart` 和 `SubagentStop` 上的必需字段。

254* **工具使用 ID**（`str | None` / `string | undefined`）：关联同一工具调用的 `PreToolUse` 和 `PostToolUse` 事件。254* **工具使用 ID**（`str | None` / `string | undefined`）：关联同一工具调用的 `PreToolUse` 和 `PostToolUse` 事件。

255* **上下文：** 在 TypeScript 中，包含用于取消的 `signal` 属性（`AbortSignal`）。在 Python 中，此参数保留供将来使用。255* **上下文：** 在 TypeScript 中，包含用于取消的 `signal` 属性（`AbortSignal`）。在 Python 中，此参数保留供将来使用。

256 256

agent-sdk/hosting.md +1 −1

Details

189 网络189 网络

190</h3>190</h3>

191 191

192SDK 需要对 `api.anthropic.com` 的出站 HTTPS，或在 Bedrock 或 Vertex 上运行时对您的提供商的区域端点的出站 HTTPS。如果您的代理使用 [MCP servers](/zh-CN/agent-sdk/mcp) 或外部工具，它们还需要对这些端点的出站访问。对于生产环境，通过强制执行域名允许列表、注入凭证和记录请求的出站代理路由出站流量。有关完整模式，请参阅[安全部署](/zh-CN/agent-sdk/secure-deployment)。192SDK 需要对 `api.anthropic.com` 的出站 HTTPS，或在 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上运行时对您的提供商的区域端点的出站 HTTPS。如果您的代理使用 [MCP servers](/zh-CN/agent-sdk/mcp) 或外部工具，它们还需要对这些端点的出站访问。对于生产环境，通过强制执行域名允许列表、注入凭证和记录请求的出站代理路由出站流量。有关完整模式，请参阅[安全部署](/zh-CN/agent-sdk/secure-deployment)。

193 193

194对于入站流量，在容器上公开 HTTP 或 WebSocket 端口。您的应用程序在该端口上处理客户端请求并在内部调用 SDK；子进程本身不在网络上侦听。194对于入站流量，在容器上公开 HTTP 或 WebSocket 端口。您的应用程序在该端口上处理客户端请求并在内部调用 SDK；子进程本身不在网络上侦听。

195 195

agent-sdk/mcp.md +1 −1

Details

823 连接超时823 连接超时

824</h3>824</h3>

825 825

826MCP SDK 对服务器连接的默认超时为 60 秒。如果您的服务器需要更长时间才能启动，连接将失败。对于需要更多启动时间的服务器，请考虑：826MCP 服务器连接默认超时为 30 秒。如果您的服务器需要更长时间才能启动，连接将失败。使用 [`MCP_TIMEOUT`](/zh-CN/env-vars) 环境变量提高限制，单位为毫秒。对于需要更多启动时间的服务器，还应考虑：

827 827

828* 使用更轻量级的服务器（如果可用）828* 使用更轻量级的服务器（如果可用）

829* 在启动代理之前预热服务器829* 在启动代理之前预热服务器

agent-sdk/modifying-system-prompts.md +5 −1

Details

152 152

153* **CLI**：运行 `/config` 并选择输出样式153* **CLI**：运行 `/config` 并选择输出样式

154* **设置**：在 `.claude/settings.local.json` 中设置 `outputStyle`154* **设置**：在 `.claude/settings.local.json` 中设置 `outputStyle`

155* **TypeScript SDK**：在传递给 `query()` 的内联 `settings` 对象内设置 `outputStyle`，或将 `settings` 指向设置它的设置文件。`outputStyle` 不是顶级 `Options` 字段155* **TypeScript SDK**：在传递给 `query()` 的内联 `settings` 对象内设置 `outputStyle`，或将 `settings` 指向设置它的设置文件。`outputStyle` 不是顶级 `Options` 字段：

156

157 ```typescript theme={null}

158 const options = { settings: { outputStyle: "Explanatory" } };

159 ```

156 160

157Python SDK 没有以编程方式选择输出样式的选项。对于无法写入 `.claude/settings.local.json` 的仅代码部署，请改用 `append` 或自定义提示词字符串。161Python SDK 没有以编程方式选择输出样式的选项。对于无法写入 `.claude/settings.local.json` 的仅代码部署，请改用 `append` 或自定义提示词字符串。

158 162

agent-sdk/observability.md +2 −2

Details

206 206

207CLI 根据它用来调用 Anthropic 的凭证将[身份属性](/zh-CN/monitoring-usage#standard-attributes)附加到每个事件。当您构建一个从一个部署为许多最终用户服务的应用程序时，这些属性标识您的服务的凭证，而不是代理代表其行动的最终用户。207CLI 根据它用来调用 Anthropic 的凭证将[身份属性](/zh-CN/monitoring-usage#standard-attributes)附加到每个事件。当您构建一个从一个部署为许多最终用户服务的应用程序时，这些属性标识您的服务的凭证，而不是代理代表其行动的最终用户。

208 208

209要使工具调用和 MCP 活动可归属于您的应用程序的最终用户，请在每个 `query()` 调用上注入最终用户身份作为资源属性。在插值前对值进行百分比编码，因为 `OTEL_RESOURCE_ATTRIBUTES` [保留逗号、空格和等号](/zh-CN/monitoring-usage#multi-team-organization-support)。以下示例将请求用户和租户附加到来自一个请求的每个跨度和事件：209要使工具调用和 MCP 活动可归属于您的应用程序的最终用户，请在每个 `query()` 调用上注入最终用户身份作为资源属性。在插值前对值进行百分比编码，因为 `OTEL_RESOURCE_ATTRIBUTES` [保留逗号、空格和等号](/zh-CN/monitoring-usage#multi-team-organization-support)。以下示例将请求用户和租户附加到来自一个请求的每个跨度和事件。它假设您的 Web 框架中有一个 `request` 对象，其中包含用户和租户 ID：

210 210

211<CodeGroup>211<CodeGroup>

212 ```python Python theme={null}212 ```python Python theme={null}

231 ```231 ```

232</CodeGroup>232</CodeGroup>

233 233

234附加最终用户身份后，`tool_decision`、`tool_result`、`mcp_server_connection` 和 `permission_mode_changed` 事件成为每个用户的审计跟踪，您可以转发到安全信息和事件管理 (SIEM) 平台。有关完整的安全相关事件列表和每个事件携带的属性，请参阅监控参考中的[审计安全事件](/zh-CN/monitoring-usage#audit-security-events)。234附加最终用户身份后，`tool_decision`、`tool_result`、`mcp_server_connection` 和 `permission_mode_changed` 事件（这些事件导出为以 `claude_code.` 前缀命名的日志记录）成为每个用户的审计跟踪，您可以转发到安全信息和事件管理 (SIEM) 平台。有关完整的安全相关事件列表和每个事件携带的属性，请参阅监控参考中的[审计安全事件](/zh-CN/monitoring-usage#audit-security-events)。

235 235

236<h2 id="control-sensitive-data-in-exports">236<h2 id="control-sensitive-data-in-exports">

237 控制导出中的敏感数据237 控制导出中的敏感数据

agent-sdk/overview.md +2 −2

Details

87 87

88 * **Amazon Bedrock**：设置 `CLAUDE_CODE_USE_BEDROCK=1` 环境变量并配置 AWS 凭证88 * **Amazon Bedrock**：设置 `CLAUDE_CODE_USE_BEDROCK=1` 环境变量并配置 AWS 凭证

89 * **Claude Platform on AWS**：设置 `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` 和 `ANTHROPIC_AWS_WORKSPACE_ID`，然后配置 AWS 凭证89 * **Claude Platform on AWS**：设置 `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` 和 `ANTHROPIC_AWS_WORKSPACE_ID`，然后配置 AWS 凭证

~~90 * **Google Vertex AI**：设置 `CLAUDE_CODE_USE_VERTEX=1` 环境变量并配置 Google Cloud 凭证~~90 * **Google Cloud 的 Agent Platform**：设置 `CLAUDE_CODE_USE_VERTEX=1` 环境变量并配置 Google Cloud 凭证

91 * **Microsoft Azure**：设置 `CLAUDE_CODE_USE_FOUNDRY=1` 环境变量并配置 Azure 凭证91 * **Microsoft Azure**：设置 `CLAUDE_CODE_USE_FOUNDRY=1` 环境变量并配置 Azure 凭证

92 92

93 有关详细信息，请参阅 [Bedrock](/zh-CN/amazon-bedrock)、[Claude Platform on AWS](/zh-CN/claude-platform-on-aws)、[Vertex AI](/zh-CN/google-vertex-ai) 或 [Azure AI Foundry](/zh-CN/microsoft-foundry) 的设置指南。93 有关详细信息，请参阅 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Claude Platform on AWS](/zh-CN/claude-platform-on-aws)、[Google Cloud 的 Agent Platform](/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/zh-CN/microsoft-foundry) 的设置指南。

94 94

95 <Note>95 <Note>

96 除非事先获得批准，否则 Anthropic 不允许第三方开发人员为其产品（包括基于 Claude Agent SDK 构建的代理）提供 claude.ai 登录或速率限制。请改用本文档中描述的 API 密钥身份验证方法。96 除非事先获得批准，否则 Anthropic 不允许第三方开发人员为其产品（包括基于 Claude Agent SDK 构建的代理）提供 claude.ai 登录或速率限制。请改用本文档中描述的 API 密钥身份验证方法。

agent-sdk/permissions.md +2 −2

Details

109SDK 支持这些权限模式：109SDK 支持这些权限模式：

110 110

111| 模式 | 描述 | 工具行为 |111| 模式 | 描述 | 工具行为 |

112| :------------------- | :------- | :--------------------------------------------------------------------------------------------- |112| :------------------ | :------- | :--------------------------------------------------------------------------------------------- |

119 119

120<Warning>120<Warning>

121 **子代理继承：** 当父代理使用 `bypassPermissions`、`acceptEdits` 或 `auto` 时，所有子代理继承该模式，并且不能按子代理覆盖。子代理可能有不同的系统提示和行为约束较少，比您的主代理，所以继承 `bypassPermissions` 授予它们完整的、自主的系统访问权限。显式 [`ask` 规则](#how-permissions-are-evaluated) 仍然会强制提示。121 **子代理继承：** 当父代理使用 `bypassPermissions`、`acceptEdits` 或 `auto` 时，所有子代理继承该模式，并且不能按子代理覆盖。子代理可能有不同的系统提示和行为约束较少，比您的主代理，所以继承 `bypassPermissions` 授予它们完整的、自主的系统访问权限。显式 [`ask` 规则](#how-permissions-are-evaluated) 仍然会强制提示。

agent-sdk/python.md +27 −5

Details

854class ClaudeAgentOptions:854class ClaudeAgentOptions:

855 tools: list[str] | ToolsPreset | None = None855 tools: list[str] | ToolsPreset | None = None

856 allowed_tools: list[str] = field(default_factory=list)856 allowed_tools: list[str] = field(default_factory=list)

858 mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)858 mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)

859 strict_mcp_config: bool = False859 strict_mcp_config: bool = False

860 permission_mode: PermissionMode | None = None860 permission_mode: PermissionMode | None = None

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

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

903| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | 系统提示配置。传递字符串以获取自定义提示，或使用 `{"type": "preset", "preset": "claude_code"}` 获取 Claude Code 的系统提示。添加 `"append"` 以扩展预设 |903| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptFile \| None` | `None` | 系统提示配置。传递字符串以获取自定义提示，`{"type": "preset", "preset": "claude_code"}` 获取 Claude Code 的系统提示（带可选 `"append"`），或 `{"type": "file", "path": "..."}` 从磁盘加载大型提示。见 [`SystemPromptPreset`](#systempromptpreset) 和 [`SystemPromptFile`](#systempromptfile) |

904| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 服务器配置或配置文件路径 |904| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 服务器配置或配置文件路径 |

905| `strict_mcp_config` | `bool` | `False` | 当为 `True` 时，仅使用在 `mcp_servers` 中传递的服务器，忽略项目 `.mcp.json`、用户设置、插件提供的 MCP 服务器和 [claude.ai 连接器](/zh-CN/mcp#use-mcp-servers-from-claude-ai)。映射到 CLI `--strict-mcp-config` 标志 |905| `strict_mcp_config` | `bool` | `False` | 当为 `True` 时，仅使用在 `mcp_servers` 中传递的服务器，忽略项目 `.mcp.json`、用户设置、插件提供的 MCP 服务器和 [claude.ai 连接器](/zh-CN/mcp#use-mcp-servers-from-claude-ai)。映射到 CLI `--strict-mcp-config` 标志 |

1002| `append` | 否 | 要追加到预设系统提示的其他说明 |1002| `append` | 否 | 要追加到预设系统提示的其他说明 |

1003| `exclude_dynamic_sections` | 否 | 将每个会话的上下文（如工作目录、git 状态和内存路径）从系统提示移到第一条用户消息。改进跨用户和机器的提示缓存重用。见 [修改系统提示](/zh-CN/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |1003| `exclude_dynamic_sections` | 否 | 将每个会话的上下文（如工作目录、git 状态和内存路径）从系统提示移到第一条用户消息。改进跨用户和机器的提示缓存重用。见 [修改系统提示](/zh-CN/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

1004 1004

1005<h3 id="systempromptfile">

1006 `SystemPromptFile`

1007</h3>

1008

1009从文件加载自定义系统提示而不是作为字符串传递的配置。SDK 将其映射到 CLI [`--system-prompt-file`](/zh-CN/cli-reference#system-prompt-flags) 标志。当提示很大时使用文件形式：SDK 在 CLI 子进程 argv 上传递字符串 `system_prompt`，这受到 OS 命令行长度限制的限制，然后 SDK 才能发送任何 API 请求。在 Linux 上，单个参数长于大约 128 KB 会在进程生成时失败，出现 `Argument list too long`。在 Windows 上，整个命令行被限制为大约 32 KB，因此字符串形式在更低的阈值处失败。

1010

1011```python theme={null}

1012class SystemPromptFile(TypedDict):

1013 type: Literal["file"]

1014 path: str

1015```

1016

1017| 字段 | 必需 | 描述 |

1018| :----- | :- | :-------------------- |

1019| `type` | 是 | 必须是 `"file"` 以从磁盘加载提示 |

1020| `path` | 是 | 包含系统提示的文件的路径 |

1021

1005<h3 id="settingsource">1022<h3 id="settingsource">

1006 `SettingSource`1023 `SettingSource`

1007</h3>1024</h3>

1192 "plan", # Planning mode - explore without editing1209 "plan", # Planning mode - explore without editing

1193 "dontAsk", # Deny anything not pre-approved instead of prompting1210 "dontAsk", # Deny anything not pre-approved instead of prompting

1194 "bypassPermissions", # Bypass permission checks; explicit ask rules still prompt (use with caution)1211 "bypassPermissions", # Bypass permission checks; explicit ask rules still prompt (use with caution)

1212 "auto", # A model classifier approves or denies each tool call

1195]1213]

1196```1214```

1197 1215

1755```1773```

1756 1774

1757| 字段 | 类型 | 描述 |1775| 字段 | 类型 | 描述 |

1758| :------------------- | :--------------- | :-------------------- |1776| :------------------- | :--------------- | :------------------------------------------------------------------------------- |

1759| `uuid` | `str` | 此事件的唯一标识符 |1777| `uuid` | `str` | 此事件的唯一标识符 |

1760| `session_id` | `str` | 会话标识符 |1778| `session_id` | `str` | 会话标识符 |

1763 1781

1764<h3 id="ratelimitevent">1782<h3 id="ratelimitevent">

1765 `RateLimitEvent`1783 `RateLimitEvent`

2393 tool_name: str2411 tool_name: str

2394 tool_input: dict[str, Any]2412 tool_input: dict[str, Any]

2395 permission_suggestions: NotRequired[list[Any]]2413 permission_suggestions: NotRequired[list[Any]]

2414 agent_id: NotRequired[str]

2415 agent_type: NotRequired[str]

2396```2416```

2397 2417

2398| 字段 | 类型 | 描述 |2418| 字段 | 类型 | 描述 |

2399| :----------------------- | :----------------------------- | :---------------------- |2419| :----------------------- | :----------------------------- | :----------------------- |

2401| `tool_name` | `str` | 请求权限的工具的名称 |2421| `tool_name` | `str` | 请求权限的工具的名称 |

2424| `agent_id` | `str`（可选） | 子代理标识符，当 hook 在子代理内触发时存在 |

2425| `agent_type` | `str`（可选） | 子代理类型，当 hook 在子代理内触发时存在 |

2404 2426

2405<h3 id="hookjsonoutput">2427<h3 id="hookjsonoutput">

2406 `HookJSONOutput`2428 `HookJSONOutput`

agent-sdk/quickstart.md +4 −4

Details

121 121

122 * **Amazon Bedrock**：设置 `CLAUDE_CODE_USE_BEDROCK=1` 环境变量并配置 AWS 凭证122 * **Amazon Bedrock**：设置 `CLAUDE_CODE_USE_BEDROCK=1` 环境变量并配置 AWS 凭证

123 * **Claude Platform on AWS**：设置 `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` 和 `ANTHROPIC_AWS_WORKSPACE_ID`，然后配置 AWS 凭证123 * **Claude Platform on AWS**：设置 `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` 和 `ANTHROPIC_AWS_WORKSPACE_ID`，然后配置 AWS 凭证

124 * **Google Vertex AI**：设置 `CLAUDE_CODE_USE_VERTEX=1` 环境变量并配置 Google Cloud 凭证124 * **Google Cloud 的 Agent Platform**：设置 `CLAUDE_CODE_USE_VERTEX=1` 环境变量并配置 Google Cloud 凭证

125 * **Microsoft Azure**：设置 `CLAUDE_CODE_USE_FOUNDRY=1` 环境变量并配置 Azure 凭证125 * **Microsoft Azure**：设置 `CLAUDE_CODE_USE_FOUNDRY=1` 环境变量并配置 Azure 凭证

126 126

127 有关详细信息，请参阅 [Bedrock](/zh-CN/amazon-bedrock)、[Claude Platform on AWS](/zh-CN/claude-platform-on-aws)、[Vertex AI](/zh-CN/google-vertex-ai) 或 [Azure AI Foundry](/zh-CN/microsoft-foundry) 的设置指南。127 有关详细信息，请参阅 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Claude Platform on AWS](/zh-CN/claude-platform-on-aws)、[Google Cloud 的 Agent Platform](/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/zh-CN/microsoft-foundry) 的设置指南。

128 128

129 <Note>129 <Note>

130 除非事先获得批准，否则 Anthropic 不允许第三方开发者提供 claude.ai 登录或对其产品的速率限制，包括基于 Claude Agent SDK 构建的代理。请改用本文档中描述的 API 密钥身份验证方法。130 除非事先获得批准，否则 Anthropic 不允许第三方开发者提供 claude.ai 登录或对其产品的速率限制，包括基于 Claude Agent SDK 构建的代理。请改用本文档中描述的 API 密钥身份验证方法。

368**权限模式**控制你想要多少人工监督：368**权限模式**控制你想要多少人工监督：

369 369

370| 模式 | 行为 | 用例 |370| 模式 | 行为 | 用例 |

371| -------------------- | ------------------------------------------------------------------------------------------ | -------------- |371| ------------------- | ------------------------------------------------------------------------------------------ | -------------- |

378 378

agent-sdk/streaming-output.md +3 −1

Details

91 uuid: str # 此事件的唯一标识符91 uuid: str # 此事件的唯一标识符

92 session_id: str # 会话标识符92 session_id: str # 会话标识符

93 event: dict[str, Any] # 原始 Claude API 流事件93 event: dict[str, Any] # 原始 Claude API 流事件

~~94 parent_tool_use_id: str | None # 如果来自子代理，则为父工具 ID~~94 parent_tool_use_id: str | None # 始终为 None

95 ```95 ```

96 96

97 ```typescript TypeScript theme={null}97 ```typescript TypeScript theme={null}

106 ```106 ```

107</CodeGroup>107</CodeGroup>

108 108

109`parent_tool_use_id` 字段在 Python 中始终为 `None`，在 TypeScript 中始终为 `null`。流事件仅针对主会话发出；来自子代理的令牌级增量不会被转发。要将输出归属于子代理，请使用完整消息，这些消息携带 `parent_tool_use_id`。请参阅[检测子代理调用](/zh-CN/agent-sdk/subagents#detect-subagent-invocation)。

110

109`event` 字段包含来自 [Claude API](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types) 的原始流事件。常见的事件类型包括：111`event` 字段包含来自 [Claude API](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types) 的原始流事件。常见的事件类型包括：

110 112

111| 事件类型 | 描述 |113| 事件类型 | 描述 |

agent-sdk/structured-outputs.md +4 −0

Details

247 247

248SDK 支持标准 JSON Schema 功能，包括所有基本类型（object、array、string、number、boolean、null）、`enum`、`const`、`required`、嵌套对象和 `$ref` 定义。有关支持的功能和限制的完整列表，请参阅 [JSON Schema 限制](https://platform.claude.com/docs/zh-CN/build-with-claude/structured-outputs#json-schema-limitations)。248SDK 支持标准 JSON Schema 功能，包括所有基本类型（object、array、string、number、boolean、null）、`enum`、`const`、`required`、嵌套对象和 `$ref` 定义。有关支持的功能和限制的完整列表，请参阅 [JSON Schema 限制](https://platform.claude.com/docs/zh-CN/build-with-claude/structured-outputs#json-schema-limitations)。

249 249

250不是有效 JSON Schema 的 schema 在启动时会导致运行失败，并显示一条错误消息，说明问题所在。在 v2.1.205 之前，无效的 schema 会被静默忽略，代理会返回非结构化文本。

251

252`format` 关键字，例如 `"format": "email"`，被接受为注释，SDK 的验证器不会强制执行它。在 v2.1.205 之前，任何包含 `format` 的 schema 都被视为无效。

253

250<h2 id="example-todo-tracking-agent">254<h2 id="example-todo-tracking-agent">

251 示例：TODO 跟踪代理255 示例：TODO 跟踪代理

252</h2>256</h2>

agent-sdk/subagents.md +3 −1

Details

234 父代理逐字接收子代理的最终消息作为 Agent 工具结果，但可能在其自己的响应中总结它。要在面向用户的响应中逐字保留子代理输出，请在您传递给主 `query()` 调用的提示词或 `systemPrompt` 选项中包含一条指令。234 父代理逐字接收子代理的最终消息作为 Agent 工具结果，但可能在其自己的响应中总结它。要在面向用户的响应中逐字保留子代理输出，请在您传递给主 `query()` 调用的提示词或 `systemPrompt` 选项中包含一条指令。

235</Note>235</Note>

236 236

237{/* min-version: 2.1.199 */}从 Claude Code v2.1.199 开始，结束子代理早期的 API 错误（例如速率限制）永远不会作为其结果传递。如果子代理已经产生了输出，Agent 工具会返回该部分输出并注明子代理未完成；否则工具结果是一条错误消息 `Agent terminated early due to an API error`，后跟错误详情。有关前台和后台行为，请参阅 [API errors in subagents](/zh-CN/sub-agents#api-errors-in-subagents)。237{/* min-version: 2.1.199 */}结束子代理早期的 API 错误（例如速率限制）永远不会作为其结果传递。如果速率限制、过载或服务器错误中断了已经产生文本输出的前台子代理，Agent 工具会返回该部分输出并注明子代理未完成。{/* min-version: 2.1.200 */}未产生任何内容的子代理，或其唯一输出仅为工具调用且没有文本的子代理，会失败并显示错误消息 `Agent terminated early due to an API error`，后跟错误详情。有关前台和后台行为，请参阅 [API errors in subagents](/zh-CN/sub-agents#api-errors-in-subagents)。

238

239这种部分输出处理需要 Claude Code v2.1.199 或更高版本。在 v2.1.199 中，速率限制、过载或服务器错误会导致仅工具调用的形状出现空的部分结果，仅包含中断注记。

238 240

239<h2 id="invoke-subagents">241<h2 id="invoke-subagents">

240 调用子代理242 调用子代理

agent-sdk/tool-search.md +4 −4

Details

33 配置工具搜索33 配置工具搜索

34</h2>34</h2>

35 35

36工具搜索默认启用。在Vertex AI上默认禁用，其中支持Claude Sonnet 4.5及更高版本以及Claude Opus 4.5及更高版本。当`ANTHROPIC_BASE_URL`指向非第一方主机时也会禁用，因为大多数代理不转发`tool_reference`块。您可以使用`ENABLE_TOOL_SEARCH`环境变量覆盖任一默认值：36工具搜索默认启用。在Google Cloud的Agent Platform上默认禁用，其中支持Claude Sonnet 4.5及更高版本以及Claude Opus 4.5及更高版本。当`ANTHROPIC_BASE_URL`指向非第一方主机时也会禁用，因为大多数代理不转发`tool_reference`块。您可以使用`ENABLE_TOOL_SEARCH`环境变量覆盖任一默认值：

37 37

38| 值 | 行为 |38| 值 | 行为 |

~~39| :------- | :------------------------------------------------------------------------------------------------------------- |~~39| :------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |

40| （未设置） | 工具搜索处于启用状态。工具定义被延迟并按需发现。在Vertex AI或非第一方`ANTHROPIC_BASE_URL`上回退到预先加载。 |40| （未设置） | 工具搜索处于启用状态。工具定义被延迟并按需发现。在Google Cloud的Agent Platform或非第一方`ANTHROPIC_BASE_URL`上回退到预先加载。 |

41| `true` | 工具搜索始终启用。SDK即使在Vertex AI和通过代理上也会发送beta标头。在Sonnet 4.5或Opus 4.5之前的Vertex AI模型上，或在不支持`tool_reference`块的代理上，请求会失败。 |41| `true` | 工具搜索始终启用。SDK即使在Google Cloud的Agent Platform和通过代理上也会发送beta标头。在Sonnet 4.5或Opus 4.5之前的Google Cloud的Agent Platform模型上，或在不支持`tool_reference`块的代理上，请求会失败。 |

agent-sdk/typescript.md +97 −11

Details

296</h4>296</h4>

297 297

298| 属性 | 类型 | 描述 |298| 属性 | 类型 | 描述 |

299| :------------------- | :---------------------- | :----------------------------------------------------------- |299| :------------------- | :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

305| `parent_agent_id` | `string \| null` | 对于来自[嵌套子代理](/zh-CN/sub-agents#spawn-nested-subagents)的消息，生成该消息的子代理的 `agentId`。对于主会话消息、来自顶级子代理的消息和较旧的会话为 `null`。{/* min-version: 2.1.202 */}需要 Claude Code v2.1.202 或更高版本 |

305 306

306<h4 id="example">307<h4 id="example">

307 示例308 示例

563 564

564```typescript theme={null}565```typescript theme={null}

565interface Query extends AsyncGenerator<SDKMessage, void> {566interface Query extends AsyncGenerator<SDKMessage, void> {

566 interrupt(): Promise<void>;567 interrupt(): Promise<SDKControlInterruptResponse | undefined>;

567 rewindFiles(568 rewindFiles(

568 userMessageId: string,569 userMessageId: string,

569 options?: { dryRun?: boolean }570 options?: { dryRun?: boolean }

593</h4>594</h4>

594 595

595| 方法 | 描述 |596| 方法 | 描述 |

596| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |597| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

597| `interrupt()` | 中断查询（仅在流式输入模式下可用） |598| `interrupt()` | 中断查询。仅在流式输入模式下可用。{/* min-version: 2.1.205 */}当 CLI 在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中通告 `interrupt_receipt_v1` 功能时，使用列出存活中断的排队消息的 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 进行解决。在 v2.1.205 之前的 CLI 上解决为 `undefined` |

598| `rewindFiles(userMessageId, options?)` | 将文件恢复到指定用户消息时的状态。传递 `{ dryRun: true }` 以预览更改。需要 `enableFileCheckpointing: true`。请参阅[文件 checkpointing](/zh-CN/agent-sdk/file-checkpointing) |599| `rewindFiles(userMessageId, options?)` | 将文件恢复到指定用户消息时的状态。传递 `{ dryRun: true }` 以预览更改。需要 `enableFileCheckpointing: true`。请参阅[文件 checkpointing](/zh-CN/agent-sdk/file-checkpointing) |

625* **在下一个轮次应用**：`model`、`effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`awaySummaryEnabled`、`agent`。切换 `agent` 也会在下一个轮次应用该代理的模型覆盖、hooks 和系统提示。626* **在下一个轮次应用**：`model`、`effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`awaySummaryEnabled`、`agent`。切换 `agent` 也会在下一个轮次应用该代理的模型覆盖、hooks 和系统提示。

626* **会话中期无效**：系统提示选项。这些在启动时解决一次，因此运行的会话保持原始值，即使调用成功。要更改它们，请启动新会话。627* **会话中期无效**：系统提示选项。这些在启动时解决一次，因此运行的会话保持原始值，即使调用成功。要更改它们，请启动新会话。

627 628

629`effortLevel` 接受一个[努力级别](/zh-CN/model-config#adjust-effort-level)名称。它也接受 `"ultracode"`，它以 `xhigh` 努力运行会话并打开[ultracode](/zh-CN/workflows#let-claude-decide-with-ultracode)。`Settings` 类型声明 `effortLevel` 不包含该值，因此在 TypeScript 中传递等效的 `{ ultracode: true }`。{/* min-version: 2.1.203 */}`ultracode` 值需要 Claude Code v2.1.203 或更高版本，仅由 `applyFlagSettings()` 接受，不由设置文件中的 `effortLevel` 键接受。

630

628这些值被写入标志设置层，这是内联 `query()` 的 `settings` 选项在启动时填充的同一层。标志设置位于[设置优先级顺序](/zh-CN/settings#settings-precedence)的顶部附近：它们覆盖用户、项目和本地设置，只有托管策略设置可以覆盖它们。这与[优先级部分](#settings-precedence)称为编程选项的层相同。631这些值被写入标志设置层，这是内联 `query()` 的 `settings` 选项在启动时填充的同一层。标志设置位于[设置优先级顺序](/zh-CN/settings#settings-precedence)的顶部附近：它们覆盖用户、项目和本地设置，只有托管策略设置可以覆盖它们。这与[优先级部分](#settings-precedence)称为编程选项的层相同。

629 632

630连续调用浅合并顶级键。第二次调用 `{ permissions: {...} }` 会替换先前调用中的整个 `permissions` 对象，而不是深度合并到其中。要从标志层清除键并回退到较低优先级源，请为该键传递 `null`。传递 `undefined` 无效，因为 JSON 序列化会将其删除。633连续调用浅合并顶级键。第二次调用 `{ permissions: {...} }` 会替换先前调用中的整个 `permissions` 对象，而不是深度合并到其中。要从标志层清除键并回退到较低优先级源，请为该键传递 `null`。传递 `undefined` 无效，因为 JSON 序列化会将其删除。

693 696

694这些是在客户端连接之前发出的请求，仍在等待回复。SDK 为您读取数组并将每个条目分派到您的 [`canUseTool`](#canusetool) 回调，这与 [`reinitialize()`](#query-object) 在传输间隙后触发的相同重新发送。使用重复的请求 ID 幂等地处理，因为条目可以重复回调已在连接断开前收到的请求。697这些是在客户端连接之前发出的请求，仍在等待回复。SDK 为您读取数组并将每个条目分派到您的 [`canUseTool`](#canusetool) 回调，这与 [`reinitialize()`](#query-object) 在传输间隙后触发的相同重新发送。使用重复的请求 ID 幂等地处理，因为条目可以重复回调已在连接断开前收到的请求。

695 698

699<h3 id="sdkcontrolinterruptresponse">

700 `SDKControlInterruptResponse`

701</h3>

702

703中断收据：[`interrupt()`](#query-object) 在通告 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中的 `interrupt_receipt_v1` 功能的 CLI 上解决的值。需要 Claude Code v2.1.205 或更高版本。较早的 CLI 使用空成功有效负载回答中断，因此 `interrupt()` 解决为 `undefined`。

704

705```typescript theme={null}

706type SDKControlInterruptResponse = {

707 still_queued: string[];

708};

709```

710

711`still_queued` 列出存活中断的用户消息的 UUID：仍在队列中的消息，加上已为下一个轮次出队但尚未被中止到达的任何批次。除非您首先取消它，否则每个都作为其自己的轮次在中断后运行。使用收据来决定是否重新发送任何内容；重新发送已列出的消息会产生重复的轮次。

712

713使用这些注意事项解释列表：

714

715* 仅出现已使用 UUID 入队的消息。空数组并不意味着没有其他内容会运行。

716* 仅列出主线程消息。寻址到子代理的消息超出范围。

717* 列表可以包括您的客户端从未发送的 UUID，例如[计划任务](/zh-CN/scheduled-tasks)触发器。忽略您不识别的 UUID，而不是将其视为错误。

718

719收据是在处理中断时拍摄的快照，在干净中断时，它在中断轮次的 [`SDKResultMessage`](#sdkresultmessage) 之前到达。在该结果之后读取收据而不是检查队列：循环立即启动下一个排队的轮次，因此您在结果后检查的队列已经改变。

720

696<h3 id="agentdefinition">721<h3 id="agentdefinition">

697 `AgentDefinition`722 `AgentDefinition`

698</h3>723</h3>

1097 | SDKTaskStartedMessage1122 | SDKTaskStartedMessage

1098 | SDKTaskProgressMessage1123 | SDKTaskProgressMessage

1099 | SDKTaskUpdatedMessage1124 | SDKTaskUpdatedMessage

1125 | SDKBackgroundTasksChangedMessage

1100 | SDKSessionStateChangedMessage1126 | SDKSessionStateChangedMessage

1101 | SDKWorkerShuttingDownMessage1127 | SDKWorkerShuttingDownMessage

1102 | SDKCommandsChangedMessage1128 | SDKCommandsChangedMessage

1110 | SDKPromptSuggestionMessage1136 | SDKPromptSuggestionMessage

1111 | SDKAPIRetryMessage1137 | SDKAPIRetryMessage

1112 | SDKMirrorErrorMessage1138 | SDKMirrorErrorMessage

1113 | SDKInformationalMessage;1139 | SDKInformationalMessage

1140 | SDKConversationResetMessage;

1114```1141```

1115 1142

1116<h3 id="sdkassistantmessage">1143<h3 id="sdkassistantmessage">

1273 output_style: string;1300 output_style: string;

1274 skills: string[];1301 skills: string[];

1275 plugins: { name: string; path: string }[];1302 plugins: { name: string; path: string }[];

1303 capabilities?: string[];

1276};1304};

1277```1305```

1278 1306

1307{/* min-version: 2.1.205 */}

1308

1309`capabilities` 数组命名此 CLI 实现的协议行为，因此您可以进行功能检测而不是比较 `claude_code_version` 字符串。这是一个开放集合：忽略您不认识的值，并检查您依赖其行为的特定功能。该字段需要 Claude Code v2.1.205 或更高版本，在较早的 CLI 上不存在。

1310

1311| 功能 | 含义 |

1312| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |

1313| `interrupt_receipt_v1` | [`interrupt()`](#query-object) 使用命名存活中断的排队消息的 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 收据进行解析 |

1314

1279<h3 id="sdkpartialassistantmessage">1315<h3 id="sdkpartialassistantmessage">

1280 `SDKPartialAssistantMessage`1316 `SDKPartialAssistantMessage`

1281</h3>1317</h3>

1282 1318

1283流式部分消息（仅当 `includePartialMessages` 为 true 时）。1319流式部分消息（仅当 `includePartialMessages` 为 true 时）。`parent_tool_use_id` 字段始终为 `null`：流事件仅针对主会话发出。对于子代理归属，使用携带 `parent_tool_use_id` 的完整消息，或启用 [`forwardSubagentText`](#options) 以接收子代理文本和思考作为完整消息。

1284 1320

1285```typescript theme={null}1321```typescript theme={null}

1286type SDKPartialAssistantMessage = {1322type SDKPartialAssistantMessage = {

1421type SDKMessageOrigin =1457type SDKMessageOrigin =

1422 | { kind: "human" }1458 | { kind: "human" }

1423 | { kind: "channel"; server: string }1459 | { kind: "channel"; server: string }

1424 | { kind: "peer"; from: string; name?: string; senderTaskId?: string }1460 | {

1461 kind: "peer";

1462 from: string;

1463 name?: string;

1464 senderTaskId?: string;

1465 body?: string;

1466 }

1425 | { kind: "task-notification" }1467 | { kind: "task-notification" }

1426 | { kind: "coordinator" }1468 | { kind: "coordinator" }

1427 | { kind: "auto-continuation" };1469 | { kind: "auto-continuation" };

1428```1470```

1429 1471

1430| `kind` | 含义 |1472| `kind` | 含义 |

1431| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1473| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1434| `peer` | 来自另一个代理的消息。对于通过 `SendMessage` 发送到 `main` 的进程内[队友](/zh-CN/agent-teams)，`from` 是队友的名称，`senderTaskId` 是其任务 ID。对于跨会话对等体（例如另一个本地 Claude Code 进程），`from` 是发送者地址，`senderTaskId` 不存在。`name` 字段是保留的。 |1476| `peer` | 来自另一个代理的消息。对于通过 `SendMessage` 发送到 `main` 的进程内[队友](/zh-CN/agent-teams)，`from` 是队友的名称，`senderTaskId` 是其任务 ID。对于跨会话对等体（例如另一个本地 Claude Code 进程），`from` 是发送者地址，`senderTaskId` 不存在。{/* min-version: 2.1.205 */}}`name` 和 `body` 需要 Claude Code v2.1.205 或更高版本。`name` 是发送者的显示名称，由 Claude Code 规范化：它删除 Unicode 控制、格式、代理和行或段落分隔符代码点，然后修剪结果并将其限制为 64 个代码点，并带有省略号。`body` 是解码的消息正文，去除对等信封，与模型看到的字节完全相同。对于队友消息，`body` 始终存在；对于跨会话对等体，仅当轮次恰好是由 Claude Code 形成的一个对等信封时才存在。呈现 `name` 和 `body` 而不是重新解析消息文本。 |

2357 2399

2358```typescript theme={null}2400```typescript theme={null}

2359type ExitPlanModeInput = {2401type ExitPlanModeInput = {

2402 /** 已弃用：不再使用。 */

2360 allowedPrompts?: Array<{2403 allowedPrompts?: Array<{

2361 tool: "Bash";2404 tool: "Bash";

2362 prompt: string;2405 prompt: string;

2364};2407};

2365```2408```

2366 2409

2367退出规划模式。可选地指定实现计划所需的基于提示的权限。2410退出规划模式。`allowedPrompts` 字段已弃用且被忽略；Claude Code 仍然接受它，以便现有调用者和记录验证。在 v2.1.205 之前，它请求基于提示的 Bash 权限以实现计划。

2368 2411

2369<h3 id="listmcpresources">2412<h3 id="listmcpresources">

2370 ListMcpResources2413 ListMcpResources

2408};2451};

2409```2452```

2410 2453

2411创建并进入临时 git worktree 以进行隔离工作。传递 `path` 以切换到当前存储库的现有 worktree 而不是创建新的。`name` 和 `path` 互斥。2454创建并进入临时 git worktree 以进行隔离工作。传递 `path` 以切换到现有 worktree 而不是创建新的。在首次进入时，目标必须是当前存储库的已注册 worktree，或在多存储库工作区中，必须是嵌套在其中的存储库的已注册 worktree；从 worktree 会话内进入时，必须在会话存储库的 `.claude/worktrees/` 下。`name` 和 `path` 互斥。

2412 2455

2413<h2 id="tool-output-types">2456<h2 id="tool-output-types">

2414 工具输出类型2457 工具输出类型

3656};3699};

3657```3700```

3658 3701

3702<h3 id="sdkbackgroundtaskschangedmessage">

3703 `SDKBackgroundTasksChangedMessage`

3704</h3>

3705

3706每当实时后台任务集发生变化时发出：任务启动、完成、被杀死，或前台代理被后台化。`tasks` 数组是完整的实时集。用每个有效负载替换任何缓存的集，而不是配对 `task_started` 和 `task_notification` 事件，以便下一个成员资格变化纠正您错过的任何事件。

3707

3708相对于这些每个任务事件的顺序是未指定的，因此不要关联这两个流。

3709

3710启动时不发出任何内容。每当会话的 CLI 进程启动或重新启动时重置为空集，并让下一个成员资格变化重新填充它。

3711

3712{/* min-version: 2.1.203 */}需要 Claude Code v2.1.203 或更高版本。

3713

3714```typescript theme={null}

3715type SDKBackgroundTasksChangedMessage = {

3716 type: "system";

3717 subtype: "background_tasks_changed";

3718 tasks: {

3719 task_id: string;

3720 task_type: string;

3721 description: string;

3722 }[];

3723 uuid: UUID;

3724 session_id: string;

3725};

3726```

3727

3659<h3 id="sdkfilespersistedevent">3728<h3 id="sdkfilespersistedevent">

3660 `SDKFilesPersistedEvent`3729 `SDKFilesPersistedEvent`

3661</h3>3730</h3>

3745};3814};

3746```3815```

3747 3816

3817<h3 id="sdkconversationresetmessage">

3818 `SDKConversationResetMessage`

3819</h3>

3820

3821当会话的对话被替换而不结束会话时发出，例如在 `/clear` 之后、在计划模式退出时或当新对话启动时。在 `new_conversation_id` 下挂载空记录，并丢弃任何缓存的会话标题。

3822

3823```typescript theme={null}

3824type SDKConversationResetMessage = {

3825 type: "conversation_reset";

3826 new_conversation_id: UUID;

3827 uuid: UUID;

3828 session_id: string;

3829};

3830```

3831

3832{/* min-version: 2.1.203 */}SDK 的已发布类型在 Claude Code v2.1.203 及更高版本中声明 `SDKConversationResetMessage`。在 v2.1.203 之前，`SDKMessage` 引用该类型而不声明它，因此当 `skipLibCheck` 被禁用时，在 `type === "conversation_reset"` 上缩小范围失败类型检查。

3833

3748<h3 id="aborterror">3834<h3 id="aborterror">

3749 `AbortError`3835 `AbortError`

3750</h3>3836</h3>

agent-sdk/user-input.md +3 −1

Details

198</CodeGroup>198</CodeGroup>

199 199

200<Note>200<Note>

201 在 Python 中，`can_use_tool` 需要[流模式](/zh-CN/agent-sdk/streaming-vs-single-mode)和返回 `{"continue_": True}` 的 `PreToolUse` hook 以保持流打开。没有此 hook，流会在权限回调被调用之前关闭。201 在 Python 中，`can_use_tool` 需要[流模式](/zh-CN/agent-sdk/streaming-vs-single-mode)。当您通过 `query(prompt=generator)` 或 `ClaudeSDKClient.connect(prompt=async_iterable)` 传递有限的消息流时，SDK 会在最后一条消息后关闭输入流，在权限回调被调用之前，除非已注册的 hook 或进程内 MCP 服务器保持其打开。上面的示例使用返回 `{"continue_": True}` 的 `PreToolUse` hook 保持其打开。不带提示连接并通过 `ClaudeSDKClient.query()` 发送消息会自动保持流打开，不需要 hook。

202</Note>202</Note>

203 203

204此示例使用 y/n 流，其中除 `y` 之外的任何输入都被视为拒绝。在实践中，您可能会构建一个更丰富的 UI，让用户修改请求、提供反馈或完全重定向 Claude。有关所有响应方式，请参阅[响应工具请求](#respond-to-tool-requests)。204此示例使用 y/n 流，其中除 `y` 之外的任何输入都被视为拒绝。在实践中，您可能会构建一个更丰富的 UI，让用户修改请求、提供反馈或完全重定向 Claude。有关所有响应方式，请参阅[响应工具请求](#respond-to-tool-requests)。

6864. **映射答案**：代码检查输入是数字（使用选项的标签）还是自由文本（使用文本直接）6864. **映射答案**：代码检查输入是数字（使用选项的标签）还是自由文本（使用文本直接）

6875. **返回给 Claude**：响应包括原始 `questions` 数组和 `answers` 映射6875. **返回给 Claude**：响应包括原始 `questions` 数组和 `answers` 映射

688 688

689将 TypeScript 版本保存为 `ask.ts` 并使用 `npx tsx ask.ts` 运行它，或将 Python 版本保存为 `ask.py` 并使用 `python ask.py` 运行它。

690

689<CodeGroup>691<CodeGroup>

690 ```python Python theme={null}692 ```python Python theme={null}

691 import asyncio693 import asyncio

agent-view.md +68 −22

Details

90 90

91```text theme={null}91```text theme={null}

92Pinned92Pinned

~~93 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m~~93 ✽ clawd walk cycle Drawing the walk-cycle sprite frames 3m

94 94

95Ready for review95Ready for review

96 ∙ jump physics Opened PR with collision fix #2048 2h96 ∙ jump physics Opened PR with collision fix #2048 2h

97 97

98Needs input98Needs input

~~99 ✻ power-up design needs input: double jump or wall climb? 1m~~99 ✻ power-up design double jump or wall climb? 1m

100 100

101Working101Working

102 ✽ collision detection Edit src/physics/CollisionSystem.ts 2m102 ✽ collision detection Adding swept-AABB checks to CollisionSystem 2m

103 ✢ playtest level 3 run 12 · all checkpoints cleared in 4m103 ✢ playtest level 3 run 12 · all checkpoints cleared in 4m

104 104

105Completed105Completed

141 141

142会话状态通过自动更新和监督进程重启在磁盘上持久化。会话在你的机器休眠时也会被保留。它们的进程在唤醒时恢复，监督进程重新连接到它们，而不是将时间间隙视为空闲。关闭仍然会停止运行中的会话；请参阅[关闭后会话显示为失败](#sessions-show-as-failed-after-shutdown)了解如何恢复它们。142会话状态通过自动更新和监督进程重启在磁盘上持久化。会话在你的机器休眠时也会被保留。它们的进程在唤醒时恢复，监督进程重新连接到它们，而不是将时间间隙视为空闲。关闭仍然会停止运行中的会话；请参阅[关闭后会话显示为失败](#sessions-show-as-failed-after-shutdown)了解如何恢复它们。

143 143

144当你打开一个已停止响应的会话时，监督进程重启其进程，会话从中断处继续中断的响应。当机器在会话中途响应时休眠时，会话可能会陷入该状态。需要 Claude Code v2.1.200 或更高版本。

145

144<h3 id="row-summaries">146<h3 id="row-summaries">

145 行摘要147 行摘要

146</h3>148</h3>

147 149

148每行中的单行摘要由 [Haiku-class 模型](/zh-CN/model-config)生成，所以该行可以告诉你会话正在做什么、需要什么或生成了什么，无需打开记录。当会话正在积极工作时，摘要最多每 15 秒刷新一次，加上每个回合结束时刷新一次。150每行中的单行摘要由 [Haiku-class 模型](/zh-CN/model-config)生成，所以该行可以告诉你会话正在做什么、需要什么或生成了什么，无需打开记录。当会话正在积极工作时，摘要最多每 15 秒从会话自己的最近输出刷新一次，无需发送模型请求，每个回合结束时模型写入新摘要。

151

152工作中的行显示会话说它正在做什么，被阻止的行显示它提出的问题。在长回合期间，模型也大约每分钟重写一次摘要，每次重写后等待时间加倍，最多四分钟，所以繁忙的行不会继续显示过时的摘要。文本在 64 列处截断；打开[窥视面板](#peek-and-reply)读取整个句子。在 v2.1.205 之前，工作中的行可能显示原始工具调用而不是报告，运行并行工作项的会话在文本之前显示 `done/total` 计数，例如 `2/5`。

153

154当列表[按目录分组](#organize-the-list)时，摘要以会话的状态作为彩色单词开头，例如 `Needs input · double jump or wall climb?`。在默认状态分组中，组标题已经命名了状态，所以行只显示摘要。在 v2.1.205 之前，按目录分组的行不带状态单词。

149 155

150当会话运行两个或更多并行工作项时，例如 subagents、后台 shell 命令或监视器，`done/total` 计数（例如 `2/5`）出现在摘要文本之前。156整个输出不包含字母或数字的回合，例如打印单个符号的安静迭代的 [`/loop`](/zh-CN/scheduled-tasks) 会话，保持行的前一个摘要和状态。在 v2.1.205 之前，该回合被重新分类，可能将等待你输入的会话翻转回 `Working`。

151 157

152每次刷新是通过你的正常提供商的一个短 Haiku-class 请求，按与会话本身相同的[数据使用条款](/zh-CN/data-usage)计费和处理。在第三方提供商（如 Bedrock、Vertex AI、Microsoft Foundry 和自定义网关）上，当没有配置 Haiku 模型时，请求会回退到会话的主模型。设置 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/zh-CN/model-config#environment-variables) 以在这些提供商上为这些摘要选择模型。158结束回合摘要和每次中途重写是通过你的正常提供商的一个短 Haiku-class 请求，按与会话本身相同的[数据使用条款](/zh-CN/data-usage)计费和处理。15 秒的模型重写之间的更新重用会话自己的输出，不发送请求。在第三方提供商（如 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和自定义网关）上，当没有配置 Haiku 模型时，请求会回退到会话的主模型。设置 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/zh-CN/model-config#environment-variables) 以在这些提供商上为这些摘要选择模型。

153 159

154<h3 id="pull-request-status">160<h3 id="pull-request-status">

155 拉取请求状态161 拉取请求状态

157 163

158当会话打开拉取请求时，`#1234` 标签出现在行的右边缘，在支持超链接的终端中链接到拉取请求。当你向会话发送后续内容时标签保持，所以拉取请求在行恢复到实时进度时保持可见。在 worktree 中隔离其更改的后台会话自己打开这些拉取请求；[文件编辑如何隔离](#how-file-edits-are-isolated)涵盖何时发生以及会话在没有询问的情况下永远不会做什么。164当会话打开拉取请求时，`#1234` 标签出现在行的右边缘，在支持超链接的终端中链接到拉取请求。当你向会话发送后续内容时标签保持，所以拉取请求在行恢复到实时进度时保持可见。在 worktree 中隔离其更改的后台会话自己打开这些拉取请求；[文件编辑如何隔离](#how-file-edits-are-isolated)涵盖何时发生以及会话在没有询问的情况下永远不会做什么。

159 165

160当会话打开了多个拉取请求时，标签显示计数，例如 `3 PRs`，按最需要关注的打开拉取请求着色。打开[窥视面板](#peek-and-reply)查看它们全部。166处理现有拉取请求的会话以相同方式链接到它。使用 `gh` 编辑、评论、关闭或标记拉取请求为就绪链接命令自己的输出命名的拉取请求，所以捕获的输出不命名拉取请求的 `gh` 命令不创建链接；`gh pr merge` 是常见情况，因为它仅将其结果打印到交互式终端。使用 `gh pr checkout` 检出拉取请求，或推送到有打开拉取请求的分支，通过改为使用 `gh pr view` 查找该分支来链接它。在 v2.1.205 之前，仅会话创建或检出的拉取请求被链接，推送仅在本地分支名称匹配时链接一个。

167

168Claude Code 从完整命令输出读取拉取请求，包括当命令的输出超过内联限制时保存到文件的部分。在 v2.1.205 之前，在 Bash 调用中创建的拉取请求，其输出超过约 30,000 个字符，未被链接。

169

170当会话链接到多个拉取请求时，标签显示计数，例如 `3 PRs`，按最需要关注的打开拉取请求着色。打开[窥视面板](#peek-and-reply)查看它们全部。

161 171

162拉取请求编号由其状态着色：172拉取请求编号由其状态着色：

163 173

174 窥视和回复184 窥视和回复

175</h3>185</h3>

176 186

177在选定的行上按 `Space` 打开窥视面板。它显示会话需要什么、其最近的输出和它打开的任何拉取请求。大多数时候这就足够了，你永远不需要打开完整的记录。187在选定的行上按 `Space` 打开窥视面板。它打开时显示会话的完整状态句子，该行截断它，以及它上次更改的时间，然后是链接到会话的任何拉取请求。对于等待你的会话，它提出的确切问题也出现在回复输入上方。大多数时候窥视面板就足够了，你不需要打开完整的记录。

178 188

179当会话运行并行工作项时，面板也会命名运行时间最长的一个以及它已经运行了多长时间，所以你可以看到会话在等待什么而无需附加。189在 v2.1.205 之前，面板仅在没有其他内容显示时重复状态句子，并命名运行时间最长的并行工作项。

180 190

181在窥视面板中输入回复并按 `Enter` 将其发送到该会话。当会话提出多选问题时，窥视面板显示选项，你可以按数字键选择一个。对于其他被阻止的会话，按 `Tab` 用建议的回复填充输入，你可以在发送前编辑。用 `!` 前缀回复以发送 Bash 命令。191在窥视面板中输入回复并按 `Enter` 将其发送到该会话。当会话提出多选问题时，窥视面板显示选项，你可以按数字键选择一个。对于其他被阻止的会话，按 `Tab` 用建议的回复填充输入，你可以在发送前编辑。用 `!` 前缀回复以发送 Bash 命令。

182 192

194 204

195附加的会话始终以[全屏模式](/zh-CN/fullscreen)呈现，无论你的 `tui` 设置如何，因为后台会话没有终端滚动历史可追加。使用 `PgUp`、`PgDn` 或鼠标滚轮滚动，按 `Ctrl+O` 进入记录模式。你的终端的原生滚动和 tmux 复制模式仅显示当前视口，与运行任何全屏应用程序时相同。205附加的会话始终以[全屏模式](/zh-CN/fullscreen)呈现，无论你的 `tui` 设置如何，因为后台会话没有终端滚动历史可追加。使用 `PgUp`、`PgDn` 或鼠标滚轮滚动，按 `Ctrl+O` 进入记录模式。你的终端的原生滚动和 tmux 复制模式仅显示当前视口，与运行任何全屏应用程序时相同。

196 206

197在空提示上按 `←` 分离并返回 agent view。从 v2.1.198 开始，这的工作方式与你从 agent view 打开会话或从 shell 用 `claude attach <id>` 运行相同。207在空提示上按 `←` 或运行 `/exit` 分离并返回 agent view。从 v2.1.198 开始，这的工作方式与你从 agent view 打开会话或从 shell 用 `claude attach <id>` 运行相同。

198 208

199`Ctrl+Z` 也分离但返回到你开始的地方：如果你从那里附加则返回 agent view，或如果你运行了 `claude attach` 则返回你的 shell。当对话有焦点且不响应 `←` 时使用 `Ctrl+Z`。209`Ctrl+Z` 也分离但返回到你开始的地方：如果你从那里附加则返回 agent view，或如果你运行了 `claude attach` 则返回你的 shell。当对话有焦点且不响应 `←` 时使用 `Ctrl+Z`。

200 210

206 216

207如果在你按 `←` 时工具正在运行，Claude Code 会等待大约十秒钟让它完成，然后后台，响应在后台会话中继续。再按一次 `←` 以立即后台而不是等待。当进行中的工作无法转移到后台会话时，`Background this session?` 对话首先出现，与 [`/background`](#from-inside-a-session) 相同。217如果在你按 `←` 时工具正在运行，Claude Code 会等待大约十秒钟让它完成，然后后台，响应在后台会话中继续。再按一次 `←` 以立即后台而不是等待。当进行中的工作无法转移到后台会话时，`Background this session?` 对话首先出现，与 [`/background`](#from-inside-a-session) 相同。

208 218

209该行即使从没有对话历史的新会话也会被创建，所以 `→` 会返回到它。当该行是唯一的行时，agent view 在它下方显示一个入门提示。219十秒限制在 [subagents](/zh-CN/sub-agents) 运行时不适用。Claude Code 继续等待以便它们的工作转移，并在等待时显示 `Still backgrounding after the current tool` 通知；再按一次 `←` 以立即后台而不等待，这会从头重新启动 subagents。在 v2.1.203 之前，等待在十秒后结束，运行中的 subagents 在没有警告的情况下从头重新启动。

220

221该行即使从没有对话历史的新会话也会被创建，所以 `→` 会返回到它。{/* max-version: 2.1.202 */}在 v2.1.203 之前，当该行是唯一的行时，agent view 在它下方显示一个入门提示。

210 222

211你可以在 `/config` 中用 `leftArrowOpensAgents` 设置关闭此快捷键。223你可以在 `/config` 中用 `leftArrowOpensAgents` 设置关闭此快捷键。

212 224

302* `/model` 设置 [调度模型](#set-the-model)314* `/model` 设置 [调度模型](#set-the-model)

303* {/* min-version: 2.1.198 */}从 v2.1.198 开始，`/login` 打开登录对话框，以便你可以在不附加到会话的情况下再次登录315* {/* min-version: 2.1.198 */}从 v2.1.198 开始，`/login` 打开登录对话框，以便你可以在不附加到会话的情况下再次登录

304 316

305Skills、你自己的命令和提示扩展内置命令如 `/init` 作为其第一个提示发送到新的后台会话。其他内置命令显示 `attach to a session to run it` 提示。317Skills、你自己的命令和提示扩展内置命令如 `/init` 作为其第一个提示发送到新的后台会话。其他内置命令显示 `attach to a session to run it` 提示。{/* min-version: 2.1.203 */}你输入的所有内容都保留在提示旁边的输入中，以便你可以编辑它。在 v2.1.203 之前，提示清除了输入，输入的文本丢失了。

306 318

307将重复任务打包为 [skill](/zh-CN/skills) 让你从 agent view 多次启动相同的工作流而无需重新输入提示。319将重复任务打包为 [skill](/zh-CN/skills) 让你从 agent view 多次启动相同的工作流而无需重新输入提示。

308 320

315新会话在你打开 agent view 的目录中运行。要针对不同的目录，使用以下任何一种：327新会话在你打开 agent view 的目录中运行。要针对不同的目录，使用以下任何一种：

316 328

317* 在该目录中打开 `claude agents`。329* 在该目录中打开 `claude agents`。

318* 在父目录中打开 `claude agents` 并在提示中用 `@<repo>` 提及一个子存储库。输入 `@` 会列出启动目录下一级的 git 存储库，加上任何已在列表中有会话的目录。名称包含空格的目录不会被列出。330* 在父目录中打开 `claude agents` 并在提示中用 `@<repo>` 提及一个子存储库。输入 `@` 会列出这些目标：

331

332 * 启动目录下一级的 Git 存储库

333 * 你启动的存储库的已注册 [git worktrees](/zh-CN/worktrees)，这些 worktrees 位于其目录树内，例如 Claude 在 `.claude/worktrees/` 下创建的那些，标记有其检出的分支。在存储库外添加的 worktrees，例如用 `git worktree add ../feature` 添加的，不会被列出

334 * 任何已在列表中有会话的目录

335

336 名称包含空格的目录不会被列出。{/* min-version: 2.1.203 */}在 v2.1.203 之前，已注册的 worktrees 不会被列出，所以调度到其中意味着从该 worktree 的目录运行 `claude --bg`。

319* 从 shell，`cd` 进入目录并运行 `claude --bg "<prompt>"`。337* 从 shell，`cd` 进入目录并运行 `claude --bg "<prompt>"`。

320 338

321当 agent view 按目录分组时，突出显示的行的目录成为调度目标，所以你可以滚动到一个组并在不重新输入路径的情况下调度到它。339当 agent view 按目录分组时，突出显示的行的目录成为调度目标，所以你可以滚动到一个组并在不重新输入路径的情况下调度到它。

326 344

327运行 `/background` 或其别名 `/bg` 将当前对话移动到后台会话。传递提示如 `/bg run the test suite and fix any failures` 以在后台化前先给出一个更多指令。如果 Claude 在你运行 `/bg` 时正在响应，响应会在后台会话中继续。345运行 `/background` 或其别名 `/bg` 将当前对话移动到后台会话。传递提示如 `/bg run the test suite and fix any failures` 以在后台化前先给出一个更多指令。如果 Claude 在你运行 `/bg` 时正在响应，响应会在后台会话中继续。

328 346

347退出仍有后台工作运行的交互式会话，例如 subagents、后台 shell 命令、工作流或 [monitors](/zh-CN/tools-reference#monitor-tool)，会显示 `Background work is running` 对话而不是立即退出。{/* min-version: 2.1.198 */}从 v2.1.198 开始，对话提供 `Move to background and exit` 以及 `Exit anyway` 和 `Stay`。选择它会以与 `/background` 相同的方式将会话移动到后台，然后返回你的 shell，所以可以继续的工作保持运行，会话出现在 agent view 中。当 agent view 被 [关闭](#turn-off-agent-view) 时，不显示该选项。

348

329从交互式会话后台化启动一个新的进程，该进程从保存的对话恢复，进行中的工作会转移到它：运行后台 shell 命令、后台 subagents、动态工作流和你用 [`/loop`](/zh-CN/scheduled-tasks) 创建的计划任务会转移到后台会话并在那里继续运行。一个 subagent 与它启动的所有内容一起移动，所以它仅在所有工作都能转移时才转移，包括在 Windows 上。要停止进行中的工作而不是转移它，设置 [`CLAUDE_DISABLE_ADOPT=1`](/zh-CN/env-vars#variables) 环境变量；Claude Code 随后会要求你在后台化前确认。349从交互式会话后台化启动一个新的进程，该进程从保存的对话恢复，进行中的工作会转移到它：运行后台 shell 命令、后台 subagents、动态工作流和你用 [`/loop`](/zh-CN/scheduled-tasks) 创建的计划任务会转移到后台会话并在那里继续运行。一个 subagent 与它启动的所有内容一起移动，所以它仅在所有工作都能转移时才转移，包括在 Windows 上。要停止进行中的工作而不是转移它，设置 [`CLAUDE_DISABLE_ADOPT=1`](/zh-CN/env-vars#variables) 环境变量；Claude Code 随后会要求你在后台化前确认。

330 350

331无法转移的工作，例如运行中的 [monitor](/zh-CN/tools-reference#monitor-tool)，会被停止。拥有监视器的后台 subagent 会与它一起被停止。当任何此类工作正在运行时，Claude Code 显示 `Background this session?` 对话，以便你可以在它被停止前确认。351无法转移的工作，例如运行中的 [monitor](/zh-CN/tools-reference#monitor-tool)，会被停止。拥有监视器的后台 subagent 会与它一起被停止。当任何此类工作正在运行时，Claude Code 显示 `Background this session?` 对话，以便你可以在它被停止前确认。

423 443

424在 git 存储库外，会话直接写入工作目录且彼此不隔离，所以避免调度编辑相同文件的并行会话。如果你使用不同的版本控制系统，配置一个 [`WorktreeCreate` hook](/zh-CN/worktrees#non-git-version-control)，Claude 会以与 git 相同的方式隔离编辑。444在 git 存储库外，会话直接写入工作目录且彼此不隔离，所以避免调度编辑相同文件的并行会话。如果你使用不同的版本控制系统，配置一个 [`WorktreeCreate` hook](/zh-CN/worktrees#non-git-version-control)，Claude 会以与 git 相同的方式隔离编辑。

425 445

446当 hook 在不是 git 存储库的目录中失败时，会话跳过该目录的隔离并就地编辑工作目录。在 git 存储库内，写入保持被阻止，直到会话隔离。在 v2.1.203 之前，处于该状态的后台会话无法编辑任何文件：每次写入都被拒绝，直到它隔离，hook 永远无法隔离该目录。

447

426在 agent view 中删除会话（`Ctrl+X` 两次）会删除 Claude 为其创建的 worktree，包括任何未提交的更改，所以在删除前合并或推送你想保留的更改。从 shell 用 [`claude rm`](#manage-sessions-from-the-shell) 删除会保持有未提交更改的 worktree 并打印其路径，以便你可以自己清理它。你自己创建的 worktree 并在其中启动会话的，无论哪种方式都会保留在原地。448在 agent view 中删除会话（`Ctrl+X` 两次）会删除 Claude 为其创建的 worktree，包括任何未提交的更改，所以在删除前合并或推送你想保留的更改。从 shell 用 [`claude rm`](#manage-sessions-from-the-shell) 删除会保持有未提交更改的 worktree 并打印其路径，以便你可以自己清理它。你自己创建的 worktree 并在其中启动会话的，无论哪种方式都会保留在原地。

427 449

428要找到会话的 worktree 路径，查看会话或附加并检查其工作目录。450要找到会话的 worktree 路径，查看会话或附加并检查其工作目录。

462 484

463后台会话从它运行的目录读取其 [settings](/zh-CN/settings)，就像你在那里启动了 `claude` 一样。这包括项目设置中的 [`env` 值](/zh-CN/settings#available-settings)，所以在那里设置的 `ANTHROPIC_MODEL` 或提供商变量适用于该目录中的后台会话。485后台会话从它运行的目录读取其 [settings](/zh-CN/settings)，就像你在那里启动了 `claude` 一样。这包括项目设置中的 [`env` 值](/zh-CN/settings#available-settings)，所以在那里设置的 `ANTHROPIC_MODEL` 或提供商变量适用于该目录中的后台会话。

464 486

465云提供商选择，如 `CLAUDE_CODE_USE_BEDROCK` 或 `CLAUDE_CODE_USE_VERTEX`，以及 `ANTHROPIC_DEFAULT_*_MODEL` 别名遵循调度会话的 shell。网关端点变量如 `ANTHROPIC_BASE_URL` 及其配对的 `ANTHROPIC_AUTH_TOKEN` 不遵循。参见 [监督者进程](#the-supervisor-process) 了解后台会话如何获取提供商设置和凭证。487云提供商选择，如 `CLAUDE_CODE_USE_BEDROCK` 或 `CLAUDE_CODE_USE_VERTEX`，以及 `ANTHROPIC_DEFAULT_*_MODEL` 别名遵循调度会话的 shell。网关 `ANTHROPIC_BASE_URL` 导出到该 shell 中会跟随它，以及 `ANTHROPIC_CUSTOM_HEADERS`，当监督者使用相同的网关环境运行且会话在你调度的目录中运行或是你自己的会话用 `←` 或 `/background` 后台化时。这是第一个 shell 打开 agent view 或调度后台会话时的正常情况，是网关 shell。用 `@repo` 或 `--cwd` 调度到不同目录不会携带 shell 的网关；该项目的 [settings](/zh-CN/settings) 提供端点。参见 [监督者进程](#the-supervisor-process) 了解后台会话如何获取提供商设置和凭证。

466 488

467[permission mode](/zh-CN/permissions) 取决于你如何启动会话。用 `/bg` 或 `←` 后台化现有会话会保持当前权限模式，所以你切换到 `acceptEdits` 或 `auto` 的会话在分离后仍保持该模式。从 agent view 输入调度或从你的 shell 运行 `claude --bg` 使用该目录设置中的 `defaultMode`，或调度的 [subagent 的 frontmatter](/zh-CN/sub-agents#supported-frontmatter-fields) 中的 `permissionMode`。489[permission mode](/zh-CN/permissions) 取决于你如何启动会话。用 `/bg` 或 `←` 后台化现有会话会保持当前权限模式，所以你切换到 `acceptEdits` 或 `auto` 的会话在分离后仍保持该模式。从 agent view 输入调度或从你的 shell 运行 `claude --bg` 使用该目录设置中的 `defaultMode`，或调度的 [subagent 的 frontmatter](/zh-CN/sub-agents#supported-frontmatter-fields) 中的 `permissionMode`。

468 490

469后台会话启动时的权限模式、模型和工作量，以及它携带的 [配置标志](#from-inside-a-session)，在监督者稍后 [停止并重新启动](#the-supervisor-process) 其进程时都会持续。你用 `claude --bg --dangerously-skip-permissions` 或 `claude --bg --permission-mode bypassPermissions` 启动的会话在该重新启动后仍保持 `bypassPermissions` 而不是回退到目录的 `defaultMode`，以及你在会话中期用 `/model` 或 `/effort` 更改的模型或工作量会被保留。491后台会话启动时的权限模式、模型和工作量，以及它携带的 [配置标志](#from-inside-a-session)，在监督者稍后 [停止并重新启动](#the-supervisor-process) 其进程时都会持续。你用 `claude --bg --dangerously-skip-permissions` 或 `claude --bg --permission-mode bypassPermissions` 启动的会话在该重新启动后仍保持 `bypassPermissions` 而不是回退到目录的 `defaultMode`，以及你在会话中期用 `/model` 或 `/effort` 更改的模型或工作量会被保留。

470 492

493会话从 [`effortLevel` 设置](/zh-CN/settings#available-settings) 而不是从 `--effort` 或 `/effort` 获取的工作量不会在调度时固定：为会话启动的每个进程都会再次读取设置，所以在 `settings.json` 中编辑 `effortLevel` 会到达你用 `←` 或 `/bg` 后台化的会话及其后续重新启动。在 v2.1.203 之前，后台化会话会记录其设置派生的工作量，就像你传递了 `--effort` 一样，所以后续的 `effortLevel` 编辑永远无法到达它。

494

495你用 [`/rename`](/zh-CN/commands) 或 `Ctrl+R` 设置的名称也会在该重新启动中持续，所以 [`claude --resume <name>`](/zh-CN/sessions#name-your-sessions) 仍然解析会话。在 v2.1.202 之前，重新启动会将会话恢复为调度时的名称，新名称停止解析。

496

471要为从 agent view 调度的每个会话设置默认值，在打开它时传递 `--permission-mode`、`--model`、`--effort` 或 `--agent` 中的任何一个：497要为从 agent view 调度的每个会话设置默认值，在打开它时传递 `--permission-mode`、`--model`、`--effort` 或 `--agent` 中的任何一个：

472 498

473```bash theme={null}499```bash theme={null}

542 568

543监督进程及其会话使用与你的交互式会话相同的凭证进行身份验证，并且除了模型 API 外不进行额外的网络连接。提供商选择变量如 `CLAUDE_CODE_USE_BEDROCK` 和 `ANTHROPIC_DEFAULT_*_MODEL` 别名从调度每个会话的 shell 中读取，并应用到其工作进程。569监督进程及其会话使用与你的交互式会话相同的凭证进行身份验证，并且除了模型 API 外不进行额外的网络连接。提供商选择变量如 `CLAUDE_CODE_USE_BEDROCK` 和 `ANTHROPIC_DEFAULT_*_MODEL` 别名从调度每个会话的 shell 中读取，并应用到其工作进程。

544 570

545后台会话不继承网关端点变量如 `ANTHROPIC_BASE_URL`、等效的 Bedrock、Vertex 和 Foundry 基础 URL 变量，或从启动监督进程的 shell 或调度 shell 中配对的 `ANTHROPIC_AUTH_TOKEN`。会话使用你的存储凭证和项目目录的[设置](/zh-CN/settings)中 `env` 块中的任何 `env` 值。要在项目中指向[LLM 网关](/zh-CN/llm-gateway)的后台会话，在该项目的 `.claude/settings.json` `env` 块中设置 `ANTHROPIC_BASE_URL`，而不是在你的 shell 中导出它。571调度 shell 的 `PATH` 以相同的方式应用到工作进程，因此会话运行的 shell 命令会找到你的终端所拥有的相同工具。在 v2.1.203 之前，后台会话保持启动监督进程的 shell 的 `PATH`，因此自那时以来添加到你的 `PATH` 的工具可能会丢失，最常见的是在 Windows 上。

572

573后台会话不继承网关端点变量如 `ANTHROPIC_BASE_URL` 或等效的 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 基础 URL 变量，这些变量来自启动监督进程的 shell。如果没有在你调度的 shell 中导出网关，会话会使用你的存储凭证和项目目录的[设置](/zh-CN/settings)中 `env` 块中的任何 `env` 值。要在项目中指向[LLM 网关](/zh-CN/llm-gateway)的每个会话，在该项目的 `.claude/settings.json` `env` 块中设置 `ANTHROPIC_BASE_URL`。

574

575{/* min-version: 2.1.203 */}在你调度的 shell 中导出的网关 `ANTHROPIC_BASE_URL` 会到达该会话的工作进程，连同 `ANTHROPIC_CUSTOM_HEADERS` 和与它们一起导出的凭证，当监督进程从具有相同网关的环境启动时。监督进程从打开 agent view 或调度后台会话的第一个 shell 中捕获其环境，因此从网关 shell 启动会给它该环境。转发也仅适用于调度到你调度的目录中的会话，或从你自己的会话用 `←` 或 `/background` 后台化的会话：用 `@repo` 或 `--cwd` 调度到不同目录不会携带 shell 的网关，该项目的 `settings.json` `env` 块会改为提供端点。当监督进程的环境携带不同的网关或没有网关时，工作进程会针对默认端点保持你的存储凭证，而不是混合一个环境的凭证与另一个环境的端点。在 v2.1.203 之前，调度 shell 的 `ANTHROPIC_BASE_URL` 被丢弃，而与它一起导出的 `ANTHROPIC_API_KEY` 被保留，因此网关的密钥被发送到默认端点，每个请求都以 401 失败。

576

577转发的端点仅适用于该活跃进程，永远不会写入磁盘。当监督进程停止空闲会话并稍后重新启动它时，重新启动的进程会从你的设置中再次读取其端点：使用网关 `ANTHROPIC_AUTH_TOKEN` 它会回退到你的存储凭证，使用网关颁发的 `ANTHROPIC_API_KEY` 它可能会失败进行身份验证，直到网关在设置中设置。

546 578

547每个后台会话是其自己的 Claude Code 进程，由监督进程管理而不是与你的终端绑定。积极工作、等待你的输入或有终端连接的会话保持其进程运行。运行中的后台 shell 命令、子代理、动态工作流或监视器计为活跃工作，因此长时间运行的进程（如开发服务器）会保持会话活跃。579每个后台会话是其自己的 Claude Code 进程，由监督进程管理而不是与你的终端绑定。积极工作、等待你的输入或有终端连接的会话保持其进程运行。运行中的后台 shell 命令、子代理、动态工作流或监视器计为活跃工作，因此长时间运行的进程（如开发服务器）会保持会话活跃。

548 580

568 600

569监督进程监视磁盘上安装的 Claude Code 二进制文件，在常规[自动更新程序](/zh-CN/setup#auto-updates)替换它后重新启动到新版本。这是本地文件监视，不是网络检查。后台会话是分离的进程，所以它们在重新启动期间继续运行，新的监督进程重新连接到它们。空闲的固定会话也会在原地重新启动到新版本，以便它获取更新而无需你重新附加。601监督进程监视磁盘上安装的 Claude Code 二进制文件，在常规[自动更新程序](/zh-CN/setup#auto-updates)替换它后重新启动到新版本。这是本地文件监视，不是网络检查。后台会话是分离的进程，所以它们在重新启动期间继续运行，新的监督进程重新连接到它们。空闲的固定会话也会在原地重新启动到新版本，以便它获取更新而无需你重新附加。

570 602

603在监督进程重新启动会话时运行 `claude attach`，无论是为了更新、停滞还是迁移，会等待替换进程而不是失败。状态行如 `Agent is updating to the new Claude Code…` 会命名它正在等待的内容并计算经过的秒数，命令在会话准备好后立即连接。大约 60 秒后它停止等待并报告错误。在 v2.1.205 之前，`claude attach` 在几秒后停止重试并在会话仍在重新启动时打印错误。

604

571<h3 id="where-state-is-stored">605<h3 id="where-state-is-stored">

572 状态存储位置606 状态存储位置

573</h3>607</h3>

583 617

584每个后台会话都设置了 `CLAUDE_JOB_DIR` 环境变量指向其 `~/.claude/jobs/<id>` 目录，因此会话运行的 shell 命令可以将临时文件写入 `$CLAUDE_JOB_DIR/tmp` 而不会与并行会话冲突。618每个后台会话都设置了 `CLAUDE_JOB_DIR` 环境变量指向其 `~/.claude/jobs/<id>` 目录，因此会话运行的 shell 命令可以将临时文件写入 `$CLAUDE_JOB_DIR/tmp` 而不会与并行会话冲突。

585 619

586要在不直接读取文件的情况下检查此状态，请运行 `claude daemon status`。它报告监督进程是否可达、其进程 ID 和版本、套接字目录以及有多少后台会话处于活跃状态。`/doctor` 包括相同检查的摘要。620要在不直接读取文件的情况下检查此状态，请运行 `claude daemon status`。它报告监督进程是否可达、其进程 ID 和版本、套接字目录以及有多少后台会话处于活跃状态。

587 621

588该命令还会在运行的监督进程版本与你调用的 `claude` 版本不同时发出警告，这发生在监督进程尚未重新启动到新版本的更新之后。警告显示两个版本，并告诉你运行 `claude daemon stop --any` 以获取新版本。当 Claude Code 作为操作系统服务安装时，建议的命令是 `claude daemon stop` 不带该标志。622该命令还会在运行的监督进程版本与你调用的 `claude` 版本不同时发出警告，这发生在监督进程尚未重新启动到新版本的更新之后。警告显示两个版本，并告诉你运行 `claude daemon stop --any` 以获取新版本。当 Claude Code 作为操作系统服务安装时，建议的命令是 `claude daemon stop` 不带该标志。

589 623

590会话完整地保留该版本不匹配：更新会话 `state.json` 的较旧 Claude Code 版本会保留它不识别的字段并保持会话列出。624会话完整地保留该版本不匹配：更新会话 `state.json` 的较旧 Claude Code 版本会保留它不识别的字段并保持会话列出。{/* min-version: 2.1.200 */}`roster.json` 中的会话列表遵循相同的规则：重写它的较旧版本会保留较新版本写入的字段，因此由较新版本启动的会话保持可达并在监督进程重新启动后继续接受输入。在 v2.1.200 之前，较旧版本可能会在重写时删除这些字段。

591 625

592在 Windows 上，当守护进程的管道密钥文件被锁定或无法读取时，`claude daemon status` 会显示底层文件错误，而不是报告通用连接失败。626在 Windows 上，当守护进程的管道密钥文件被锁定或无法读取时，`claude daemon status` 会显示底层文件错误，而不是报告通用连接失败。

593 627

613 Agent view 打开时没有会话647 Agent view 打开时没有会话

614</h3>648</h3>

615 649

616在你调度你的第一个会话之前，agent view 显示一个简短的入门提示，在会话列表的位置显示示例提示。在底部的输入框中输入提示并按 `Enter` 来调度你的第一个会话。650在你调度你的第一个会话之前，agent view 显示空的部分标题，每个标题下有一个描述，以及输入上方的单行说明，代替会话列表。在底部的输入框中输入提示并按 `Enter` 来调度你的第一个会话。

617 651

618<h3 id="backgrounding-shows-a-background-this-session-dialog">652<h3 id="backgrounding-shows-a-background-this-session-dialog">

619 后台化显示 `Background this session?` 对话653 后台化显示 `Background this session?` 对话

620</h3>654</h3>

621 655

622如果按 `←` 来后台当前会话显示 `Background this session?` 对话，会话有进行中的工作无法转移到后台会话，例如运行中的 [monitor](/zh-CN/tools-reference#monitor-tool)，Claude Code 不会默默停止它。对话命名将被停止的工作，并分别计算转移的任务。运行 `/tasks` 查看正在运行的内容，然后确认无论如何后台或选择 `Stay` 让工作先完成。参见 [从会话内部](#from-inside-a-session) 了解哪些任务类型转移，哪些被停止。656如果按 `←` 来后台当前会话显示 `Background this session?` 对话，会话有进行中的工作无法转移到后台会话，例如运行中的 [monitor](/zh-CN/tools-reference#monitor-tool)，Claude Code 不会默默停止它。对话命名将被停止的工作，并分别计算转移的任务。运行 `/tasks` 查看正在运行的内容，然后确认无论如何后台或选择 `Stay` 让工作先完成。参见[从会话内部](#from-inside-a-session)了解哪些任务类型转移，哪些被停止。

623 657

624<h3 id="prompt-rejected-as-too-short">658<h3 id="prompt-rejected-as-too-short">

625 提示被拒绝，因为太短659 提示被拒绝，因为太短

635 669

636睡眠单独不会导致这种情况。会话在睡眠期间被保留，监督进程在唤醒时重新连接到它们。670睡眠单独不会导致这种情况。会话在睡眠期间被保留，监督进程在唤醒时重新连接到它们。

637 671

672<h3 id="opening-a-session-says-the-conversation-is-already-open">

673 打开会话说对话已经打开

674</h3>

675

676打开一个已停止的行，其对话也由另一个运行中的非交互式 Claude Code 进程持有，例如同一对话的后台工作进程仍在关闭中，会显示 `This conversation is already open in another running Claude session` 而不是启动该行的进程，因为两个进程无法写入同一个记录。在已经持有对话的会话中回复，或退出它并再次打开该行。你在拒绝尝试中输入的回复不会丢失；它会在会话下次启动时发送。

677

678在 v2.1.203 之前，这种状态会启动第二个进程。该进程会以 `currently running as a background agent` 错误退出，该行显示为已失败。

679

638<h3 id="a-session-fails-before-starting-with-a-possibly-low-memory-note">680<h3 id="a-session-fails-before-starting-with-a-possibly-low-memory-note">

639 会话在启动前失败，并显示 `possibly low memory` 注记681 会话在启动前失败，并显示 `possibly low memory` 注记

640</h3>682</h3>

729 771

730| 版本 | 更改 |772| 版本 | 更改 |

731| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |773| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

774| v2.1.205 | {/* min-version: 2.1.205 */}行摘要显示会话自己的单行报告，在 64 列处截断，而不是原始工具调用或 `done/total` 计数；按目录分组的行以彩色状态词打开。窥视面板以完整状态句子打开，对于等待你的会话，其精确问题显示在回复输入上方。编辑、评论、关闭或使用 `gh` 标记拉取请求为就绪的会话与其关联，不仅仅是创建或检出拉取请求的会话，推送即使本地分支名称不匹配也会关联拉取请求，创建命令的输出超过内联限制的拉取请求也会关联。没有可读文本的转向保持会话的前一个状态，而不是将其翻转回 `Working`。`claude attach` 等待重新启动的会话长达约 60 秒，带有命名原因的状态行，而不是失败。 |

775| v2.1.203 | {/* min-version: 2.1.203 */}在调度 shell 中导出的网关 `ANTHROPIC_BASE_URL` 当监督进程共享该网关环境时，会到达从它调度的会话进入同一目录，而不是在保留随之导出的 API 密钥时被丢弃。调度 shell 的 `PATH` 应用于每个会话的工作进程。在子代理运行时按 `←` 会等待它们，而不是在十秒后重新启动它们。空列表始终显示部分标题及其下方的描述。在调度输入中键入 `@` 也会列出启动存储库内其目录树中的已注册 git worktrees。从 `effortLevel` 设置继承的工作量在该设置的后续编辑后跟随，而不是在调度时固定。打开一个已停止的会话（其对话已在另一个运行中的会话中打开）会被拒绝并显示消息，而不是导致行失败。在 agent view 中不可用的命令会在输入中保留已键入的文本。在 git 存储库外失败的 `WorktreeCreate` hook 不再阻止会话编辑文件。 |

776| v2.1.202 | {/* min-version: 2.1.202 */}使用 `/rename` 或 `Ctrl+R` 在后台会话上设置的名称在监督进程停止并重新启动时保持不变，而不是恢复为会话调度时的名称。 |

777| v2.1.200 | {/* min-version: 2.1.200 */}重写 `roster.json` 中会话列表的较旧 Claude Code 版本保留由较新版本写入的字段，与现有的 `state.json` 保证相匹配，因此由较新版本启动的会话在监督进程重新启动后继续接受输入。当你打开已停止响应的会话时，监督进程重新启动其进程，会话从中断处继续响应。 |

732| v2.1.199 | {/* min-version: 2.1.199 */}后台会话的进程在低内存主机上完成启动前退出时，其行状态显示 `possibly low memory — free some up and retry` 而不仅仅是裸退出原因。使用 `←` 或 `/background` 后台会话时将其 `/color` 转移到新行。 |778| v2.1.199 | {/* min-version: 2.1.199 */}后台会话的进程在低内存主机上完成启动前退出时，其行状态显示 `possibly low memory — free some up and retry` 而不仅仅是裸退出原因。使用 `←` 或 `/background` 后台会话时将其 `/color` 转移到新行。 |

733| v2.1.198 | {/* min-version: 2.1.198 */}Agent view 在后台会话需要输入、完成或失败时通过 `preferredNotifChannel` 发送通知，并使用 `agent_needs_input` 或 `agent_completed` 类型触发 `Notification` hook。`←` 和 `/exit` 在 `claude attach <id>` 内返回 agent view 而不是退出到 shell；`Ctrl+Z` 返回到 shell。后台会话在 worktree 中隔离其工作，提交、推送其自己的隔离分支，从不 `main` 或 `master`，并在完成时打开草稿拉取请求而不是先询问。`/login` 在 agent view 中运行并打开登录对话框。`Background work is running` 退出对话框提供 `Move to background and exit`。退出交付也涵盖后台子代理，它们在下次唤醒时从其记录恢复，而不是被报告为失败。`claude --bg` 与 `-p` 或 `--print` 结合被拒绝并出现错误。 |779| v2.1.198 | {/* min-version: 2.1.198 */}Agent view 在后台会话需要输入、完成或失败时通过 `preferredNotifChannel` 发送通知，并使用 `agent_needs_input` 或 `agent_completed` 类型触发 `Notification` hook。`←` 和 `/exit` 在 `claude attach <id>` 内返回 agent view 而不是退出到 shell；`Ctrl+Z` 返回到 shell。后台会话在 worktree 中隔离其工作，提交、推送其自己的隔离分支，从不 `main` 或 `master`，并在完成时打开草稿拉取请求而不是先询问。`/login` 在 agent view 中运行并打开登录对话框。`Background work is running` 退出对话框提供 `Move to background and exit`。退出交付也涵盖后台子代理，它们在下次唤醒时从其记录恢复，而不是被报告为失败。`claude --bg` 与 `-p` 或 `--print` 结合被拒绝并出现错误。 |

734| v2.1.196 | {/* min-version: 2.1.196 */}单次 `←` 按压后台前台会话；早期版本需要两次按压，带有页脚提示和确认。`--dangerously-skip-permissions` 传递给 `claude agents` 显示绕过免责声明而不是被默默丢弃。你从未命名的交互式会话在会话列表和 `claude agents --json` 中携带默认名称，例如 `my-app-3f`。后台 shell 命令和动态工作流在会话的进程被停止、重新启动或更新时存活，包括在 Windows 上；设置 `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1` 关闭交付。在重新启动时误读为空的记录被重命名为 `.orphaned-` 后缀而不是删除。 |780| v2.1.196 | {/* min-version: 2.1.196 */}单次 `←` 按压后台前台会话；早期版本需要两次按压，带有页脚提示和确认。`--dangerously-skip-permissions` 传递给 `claude agents` 显示绕过免责声明而不是被默默丢弃。你从未命名的交互式会话在会话列表和 `claude agents --json` 中携带默认名称，例如 `my-app-3f`。后台 shell 命令和动态工作流在会话的进程被停止、重新启动或更新时存活，包括在 Windows 上；设置 `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1` 关闭交付。在重新启动时误读为空的记录被重命名为 `.orphaned-` 后缀而不是删除。 |

736| v2.1.174 | {/* min-version: 2.1.174 */}后台会话不再从监督进程的启动 shell 继承网关端点变量如 `ANTHROPIC_BASE_URL`；监督进程向预热工作进程提供新的凭证快照，修复虚假的 `Could not resolve authentication method` 错误。 |782| v2.1.174 | {/* min-version: 2.1.174 */}后台会话不再从监督进程的启动 shell 继承网关端点变量如 `ANTHROPIC_BASE_URL`；监督进程向预热工作进程提供新的凭证快照，修复虚假的 `Could not resolve authentication method` 错误。 |

737| v2.1.172 | {/* min-version: 2.1.172 */}调度输入中的 `/model` 设置会话范围的调度模型覆盖。 |783| v2.1.172 | {/* min-version: 2.1.172 */}调度输入中的 `/model` 设置会话范围的调度模型覆盖。 |

738| v2.1.161 | {/* min-version: 2.1.161 */}行摘要显示并行工作项的 `done/total` 计数；窥视面板命名最长运行的并行工作项。 |784| v2.1.161 | {/* min-version: 2.1.161 */}行摘要显示并行工作项的 `done/total` 计数；窥视面板命名最长运行的并行工作项。 |

739| v2.1.157 | {/* min-version: 2.1.157 */}` claude agents` 接受 `--agent`；调度的会话尊重 `agent` 设置。 |785| v2.1.157 | {/* min-version: 2.1.157 */}`claude agents` 接受 `--agent`；调度的会话尊重 `agent` 设置。 |

740| v2.1.145 | {/* min-version: 2.1.145 */}窥视面板回复输入和调度输入中支持语音听写。 |786| v2.1.145 | {/* min-version: 2.1.145 */}窥视面板回复输入和调度输入中支持语音听写。 |

741| v2.1.143 | {/* min-version: 2.1.143 */}添加 `worktree.bgIsolation` 设置；`claude agents` 接受 `--allow-dangerously-skip-permissions`。 |787| v2.1.143 | {/* min-version: 2.1.143 */}添加 `worktree.bgIsolation` 设置；`claude agents` 接受 `--allow-dangerously-skip-permissions`。 |

742| v2.1.142 | {/* min-version: 2.1.142 */}` claude agents` 接受 `--permission-mode`、`--model`、`--effort`、`--dangerously-skip-permissions`、`--settings`、`--add-dir`、`--plugin-dir`、`--mcp-config` 和 `--strict-mcp-config`。 |788| v2.1.142 | {/* min-version: 2.1.142 */}`claude agents` 接受 `--permission-mode`、`--model`、`--effort`、`--dangerously-skip-permissions`、`--settings`、`--add-dir`、`--plugin-dir`、`--mcp-config` 和 `--strict-mcp-config`。 |

743| v2.1.141 | {/* min-version: 2.1.141 */}` claude agents` 接受 `--cwd` 以将列表范围限定到一个项目。 |789| v2.1.141 | {/* min-version: 2.1.141 */}`claude agents` 接受 `--cwd` 以将列表范围限定到一个项目。 |

744| v2.1.139 | {/* min-version: 2.1.139 */}Agent view 作为研究预览版引入。 |790| v2.1.139 | {/* min-version: 2.1.139 */}Agent view 作为研究预览版引入。 |

amazon-bedrock.md +37 −37

Details

82 前置条件82 前置条件

83</h2>83</h2>

84 84

~~85在使用 Bedrock 配置 Claude Code 之前，请确保您拥有：~~85在使用 Amazon Bedrock 配置 Claude Code 之前，请确保您拥有：

86 86

~~87* 启用了 Bedrock 访问权限的 AWS 账户~~87* 启用了 Amazon Bedrock 访问权限的 AWS 账户

~~88* 在 Bedrock 中访问所需的 Claude 模型（例如 Claude Sonnet 4.6）~~88* 在 Amazon Bedrock 中访问所需的 Claude 模型（例如 Claude Sonnet 4.6）

89* 已安装并配置 AWS CLI（可选 - 仅在您没有其他获取凭证的机制时需要）89* 已安装并配置 AWS CLI（可选 - 仅在您没有其他获取凭证的机制时需要）

90* 适当的 IAM 权限90* 适当的 IAM 权限

91 91

92要使用您自己的 Bedrock 凭证登录，请按照下面的[使用 Bedrock 登录](#sign-in-with-bedrock)进行操作。要在团队中部署 Claude Code，请使用[手动设置](#set-up-manually)步骤并在推出前[固定您的模型版本](#4-pin-model-versions)。92要使用您自己的 Amazon Bedrock 凭证登录，请按照下面的[使用 Amazon Bedrock 登录](#sign-in-with-bedrock)进行操作。要在团队中部署 Claude Code，请使用[手动设置](#set-up-manually)步骤并在推出前[固定您的模型版本](#4-pin-model-versions)。

93 93

94<h2 id="sign-in-with-bedrock">94<h2 id="sign-in-with-bedrock">

95 使用 Bedrock 登录95 使用 Bedrock 登录

96</h2>96</h2>

97 97

98如果您拥有 AWS 凭证并想开始通过 Bedrock 使用 Claude Code，登录向导会引导您完成整个过程。您每个账户完成一次 AWS 端的前置条件；向导处理 Claude Code 端。98如果您拥有 AWS 凭证并想开始通过 Amazon Bedrock 使用 Claude Code，登录向导会引导您完成整个过程。您每个账户完成一次 AWS 端的前置条件；向导处理 Claude Code 端。

99 99

100<Steps>100<Steps>

101 <Step title="在您的 AWS 账户中启用 Anthropic 模型">101 <Step title="在您的 AWS 账户中启用 Anthropic 模型">

102 在 [Amazon Bedrock 控制台](https://console.aws.amazon.com/bedrock/)中，打开模型目录，选择一个 Anthropic 模型，并提交用例表单。提交后立即授予访问权限。有关 AWS Organizations，请参阅[提交用例详情](#1-submit-use-case-details)，有关权限，请参阅 [IAM 配置](#iam-configuration)。102 在 [Amazon Bedrock 控制台](https://console.aws.amazon.com/bedrock/)中，打开模型目录，选择一个 Anthropic 模型，并提交用例表单。提交后立即授予访问权限。有关 AWS Organizations，请参阅[提交用例详情](#1-submit-use-case-details)，有关权限，请参阅 [IAM 配置](#iam-configuration)。

103 </Step>103 </Step>

104 104

105 <Step title="启动 Claude Code 并选择 Bedrock">105 <Step title="启动 Claude Code 并选择 Amazon Bedrock">

106 运行 `claude`。在登录提示处，选择 **3rd-party platform**，然后选择 **Amazon Bedrock**。106 运行 `claude`。在登录提示处，选择 **3rd-party platform**，然后选择 **Amazon Bedrock**。

107 </Step>107 </Step>

108 108

109 <Step title="按照向导提示操作">109 <Step title="按照向导提示操作">

110 选择您如何向 AWS 进行身份验证：从您的 `~/.aws` 目录检测到的 AWS 配置文件、Bedrock API 密钥、访问密钥和密钥，或已在您的环境中的凭证。向导会获取您的区域，验证您的账户可以调用哪些 Claude 模型，并让您固定它们。它将结果保存到您的[用户设置文件](/zh-CN/settings)的 `env` 块中，因此您无需自己导出环境变量。110 选择您如何向 AWS 进行身份验证：从您的 `~/.aws` 目录检测到的 AWS 配置文件、Amazon Bedrock API 密钥、访问密钥和密钥，或已在您的环境中的凭证。向导会获取您的区域，验证您的账户可以调用哪些 Claude 模型，并让您固定它们。它将结果保存到您的[用户设置文件](/zh-CN/settings)的 `env` 块中，因此您无需自己导出环境变量。

111 </Step>111 </Step>

112</Steps>112</Steps>

113 113

117 手动设置117 手动设置

118</h2>118</h2>

119 119

120要通过环境变量而不是向导配置 Bedrock，例如在 CI 或脚本化企业推出中，请按照下面的步骤操作。120要通过环境变量而不是向导配置 Amazon Bedrock，例如在 CI 或脚本化企业推出中，请按照下面的步骤操作。

121 121

122<h3 id="1-submit-use-case-details">122<h3 id="1-submit-use-case-details">

123 1. 提交用例详情123 1. 提交用例详情

168 168

169[了解更多](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html)关于 `aws login`。169[了解更多](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html)关于 `aws login`。

170 170

171**选项 E：Bedrock API 密钥**171**选项 E：Amazon Bedrock API 密钥**

172 172

173```bash theme={null}173```bash theme={null}

174export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key174export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

175```175```

176 176

177Bedrock API 密钥提供了一种更简单的身份验证方法，无需完整的 AWS 凭证。[了解更多关于 Bedrock API 密钥](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)。177Amazon Bedrock API 密钥提供了一种更简单的身份验证方法，无需完整的 AWS 凭证。[了解更多关于 Amazon Bedrock API 密钥](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)。

178 178

179<h4 id="advanced-credential-configuration">179<h4 id="advanced-credential-configuration">

180 高级凭证配置180 高级凭证配置

185这两个设置有不同的触发条件：185这两个设置有不同的触发条件：

186 186

187* **`awsAuthRefresh`**：仅当 Claude Code 检测到您的 AWS 凭证已过期时运行，基于本地时间戳或当 API 返回凭证错误时，然后使用刷新的凭证重试请求。187* **`awsAuthRefresh`**：仅当 Claude Code 检测到您的 AWS 凭证已过期时运行，基于本地时间戳或当 API 返回凭证错误时，然后使用刷新的凭证重试请求。

188* **`awsCredentialExport`**：在会话启动和每次凭证重新加载时运行，即使您的 AWS 默认凭证提供商链中的凭证仍然有效。当您的 Bedrock 账户需要与默认提供商链会解析的凭证不同的跨账户凭证时，请使用此选项。188* **`awsCredentialExport`**：在会话启动和每次凭证重新加载时运行，即使您的 AWS 默认凭证提供商链中的凭证仍然有效。当您的 Amazon Bedrock 账户需要与默认提供商链会解析的凭证不同的跨账户凭证时，请使用此选项。

189 189

190<h5 id="example-configuration">190<h5 id="example-configuration">

191 示例配置191 示例配置

227 3. 配置 Claude Code227 3. 配置 Claude Code

228</h3>228</h3>

229 229

230设置以下环境变量以启用 Bedrock：230设置以下环境变量以启用 Amazon Bedrock：

231 231

232```bash theme={null}232```bash theme={null}

233# 启用 Bedrock 集成233# 启用 Bedrock 集成

243# export ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com243# export ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com

244```244```

245 245

246为 Claude Code 启用 Bedrock 时，请记住以下几点：246为 Claude Code 启用 Amazon Bedrock 时，请记住以下几点：

247 247

248* {/* min-version: 2.1.172 */}从 v2.1.172 开始，您只需设置 `AWS_REGION` 来覆盖您的 AWS 配置文件的区域，或在您的配置文件没有区域时设置。Claude Code 按此顺序解析区域：248* {/* min-version: 2.1.172 */}从 v2.1.172 开始，您只需设置 `AWS_REGION` 来覆盖您的 AWS 配置文件的区域，或在您的配置文件没有区域时设置。Claude Code 按此顺序解析区域：

249 249

253 * `us-east-1`253 * `us-east-1`

254 254

255 活跃配置文件是 `AWS_PROFILE`（如果已设置），否则为 `default`。设置 `AWS_SHARED_CREDENTIALS_FILE` 或 `AWS_CONFIG_FILE` 以指向非默认文件路径。运行 `/status` 以查看解析的区域。当区域来自您的 AWS 配置文件或默认回退时，`/status` 也会注明来源。在 v2.1.171 及更早版本上，Claude Code 不读取 AWS 配置文件，因此请显式设置 `AWS_REGION`。255 活跃配置文件是 `AWS_PROFILE`（如果已设置），否则为 `default`。设置 `AWS_SHARED_CREDENTIALS_FILE` 或 `AWS_CONFIG_FILE` 以指向非默认文件路径。运行 `/status` 以查看解析的区域。当区域来自您的 AWS 配置文件或默认回退时，`/status` 也会注明来源。在 v2.1.171 及更早版本上，Claude Code 不读取 AWS 配置文件，因此请显式设置 `AWS_REGION`。

256* 使用 Bedrock 时，`/logout` 命令不可用，因为身份验证通过 AWS 凭证处理。256* 使用 Amazon Bedrock 时，`/logout` 命令不可用，因为身份验证通过 AWS 凭证处理。

257* WebSearch 工具在 Bedrock 上不可用。请参阅 [WebSearch 工具行为](/zh-CN/tools-reference#websearch-tool-behavior)。257* WebSearch 工具在 Amazon Bedrock 上不可用。请参阅 [WebSearch 工具行为](/zh-CN/tools-reference#websearch-tool-behavior)。

258* 您可以使用设置文件来处理环境变量，如 `AWS_PROFILE`，您不希望泄露给其他进程。请参阅[设置](/zh-CN/settings)了解更多信息。258* 您可以使用设置文件来处理环境变量，如 `AWS_PROFILE`，您不希望泄露给其他进程。请参阅[设置](/zh-CN/settings)了解更多信息。

259 259

260<h3 id="4-pin-model-versions">260<h3 id="4-pin-model-versions">

262</h3>262</h3>

263 263

264<Warning>264<Warning>

265 在部署到多个用户时固定特定的模型版本。如果不固定，模型别名（如 `sonnet` 和 `opus`）会解析为 Claude Code 为 Bedrock 内置的默认值，这可能滞后于最新版本，并且可能在您的账户中还不可用。Claude Code 在启动时会[回退](#startup-model-checks)到上一个版本（如果默认版本不可用），但固定让您可以控制用户何时迁移到新模型。265 在部署到多个用户时固定特定的模型版本。如果不固定，模型别名（如 `sonnet` 和 `opus`）会解析为 Claude Code 为 Amazon Bedrock 内置的默认值，这可能滞后于最新版本，并且可能在您的账户中还不可用。Claude Code 在启动时会[回退](#startup-model-checks)到上一个版本（如果默认版本不可用），但固定让您可以控制用户何时迁移到新模型。

266</Warning>266</Warning>

267 267

268将这些环境变量设置为特定的 Bedrock 模型 ID。268将这些环境变量设置为特定的 Amazon Bedrock 模型 ID。

269 269

270如果没有 `ANTHROPIC_DEFAULT_OPUS_MODEL`，Bedrock 上的 `opus` 别名会解析为 Opus 4.6。将其设置为 Opus 4.8 ID 以使用最新模型：270如果没有 `ANTHROPIC_DEFAULT_OPUS_MODEL`，Amazon Bedrock 上的 `opus` 别名会解析为 Opus 4.6。将其设置为 Opus 4.8 ID 以使用最新模型：

271 271

272```bash theme={null}272```bash theme={null}

273export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'273export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'

284| 主模型 | `us.anthropic.claude-sonnet-4-5-20250929-v1:0` |284| 主模型 | `us.anthropic.claude-sonnet-4-5-20250929-v1:0` |

285| 小型/快速模型 | 与主模型相同 |285| 小型/快速模型 | 与主模型相同 |

286 286

287后台任务（如会话标题生成）使用小型/快速模型，通常是 Haiku 级别的模型。在 Bedrock 上，Claude Code 默认将其设置为主模型，因为并非每个账户或区域都启用了 Haiku。要为后台任务使用 Haiku，请将 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 设置为您账户中可用的模型 ID。287后台任务（如会话标题生成）使用小型/快速模型，通常是 Haiku 级别的模型。在 Amazon Bedrock 上，Claude Code 默认将其设置为主模型，因为并非每个账户或区域都启用了 Haiku。要为后台任务使用 Haiku，请将 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 设置为您账户中可用的模型 ID。

288 288

289要进一步自定义模型，请使用以下方法之一：289要进一步自定义模型，请使用以下方法之一：

290 290

305 305

3061 小时缓存 TTL 的计费费率高于 5 分钟默认值。请参阅[缓存生命周期](/zh-CN/prompt-caching#cache-lifetime)。3061 小时缓存 TTL 的计费费率高于 5 分钟默认值。请参阅[缓存生命周期](/zh-CN/prompt-caching#cache-lifetime)。

307 307

308<Note>Prompt caching 可能在所有 Bedrock 区域都不可用。如果缓存令牌计数保持为零，请检查 Bedrock 文档中的[支持的模型、区域和限制](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)。</Note>308<Note>Prompt caching 可能在所有 Amazon Bedrock 区域都不可用。如果缓存令牌计数保持为零，请检查 Amazon Bedrock 文档中的[支持的模型、区域和限制](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)。</Note>

309 309

310<h4 id="map-each-model-version-to-an-inference-profile">310<h4 id="map-each-model-version-to-an-inference-profile">

311 将每个模型版本映射到推理配置文件311 将每个模型版本映射到推理配置文件

326}326}

327```327```

328 328

329当用户在 `/model` 中选择其中一个版本时，Claude Code 使用映射的 ARN 调用 Bedrock。没有覆盖的版本回退到内置的 Bedrock 模型 ID 或启动时发现的任何匹配推理配置文件。请参阅[按版本覆盖模型 ID](/zh-CN/model-config#override-model-ids-per-version)了解覆盖如何与 `availableModels` 和其他模型设置交互的详情。329当用户在 `/model` 中选择其中一个版本时，Claude Code 使用映射的 ARN 调用 Amazon Bedrock。{/* min-version: 2.1.200 */}当您通过 `--model` 或 `ANTHROPIC_MODEL` 直接传递 Anthropic 模型 ID 时，相同的映射也适用。没有覆盖的版本回退到内置的 Amazon Bedrock 模型 ID 或启动时发现的任何匹配推理配置文件。在 v2.1.200 之前，`--model` 和 `ANTHROPIC_MODEL` 值直接到达 Amazon Bedrock，不经过覆盖映射。请参阅[按版本覆盖模型 ID](/zh-CN/model-config#override-model-ids-per-version)了解覆盖如何与 `availableModels` 和其他模型设置交互的详情。

330 330

331<h2 id="startup-model-checks">331<h2 id="startup-model-checks">

332 启动模型检查332 启动模型检查

333</h2>333</h2>

334 334

335当 Claude Code 启动并配置了 Bedrock 时，它会验证它打算使用的模型在您的账户中是否可访问。此检查需要 Claude Code v2.1.94 或更高版本。335当 Claude Code 启动并配置了 Amazon Bedrock 时，它会验证它打算使用的模型在您的账户中是否可访问。此检查需要 Claude Code v2.1.94 或更高版本。

336 336

337如果您固定了一个比当前 Claude Code 默认值更旧的模型版本，并且您的账户可以调用较新版本，Claude Code 会提示您更新固定。接受会将新模型 ID 写入您的[用户设置文件](/zh-CN/settings)并重启 Claude Code。拒绝会被记住，直到下一个默认版本更改。指向[应用推理配置文件 ARN](#map-each-model-version-to-an-inference-profile) 的固定会被跳过，因为这些由您的管理员管理。337如果您固定了一个比当前 Claude Code 默认值更旧的模型版本，并且您的账户可以调用较新版本，Claude Code 会提示您更新固定。接受会将新模型 ID 写入您的[用户设置文件](/zh-CN/settings)并重启 Claude Code。拒绝会被记住，直到下一个默认版本更改。指向[应用推理配置文件 ARN](#map-each-model-version-to-an-inference-profile) 的固定会被跳过，因为这些由您的管理员管理。

338 338

339如果您没有固定模型，并且当前默认值在您的账户中不可用，Claude Code 会在当前会话中回退到上一个版本并显示通知。回退不会被持久化。在您的 Bedrock 账户中启用较新的模型或[固定一个版本](#4-pin-model-versions)以使选择永久化。339如果您没有固定模型，并且当前默认值在您的账户中不可用，Claude Code 会在当前会话中回退到上一个版本并显示通知。回退不会被持久化。在您的 Amazon Bedrock 账户中启用较新的模型或[固定一个版本](#4-pin-model-versions)以使选择永久化。

340 340

341<h2 id="iam-configuration">341<h2 id="iam-configuration">

342 IAM 配置342 IAM 配置

387 387

388如果令牌缺少此权限，Claude Code 会通过使用备用形状重试一次来自动恢复，因此请求仍然会成功，但每个新模型都会增加一个额外的往返。授予该权限可以避免重试。这最常适用于 `AWS_BEARER_TOKEN_BEDROCK` 部署，其中令牌的策略通常比完整的 IAM 角色更窄。388如果令牌缺少此权限，Claude Code 会通过使用备用形状重试一次来自动恢复，因此请求仍然会成功，但每个新模型都会增加一个额外的往返。授予该权限可以避免重试。这最常适用于 `AWS_BEARER_TOKEN_BEDROCK` 部署，其中令牌的策略通常比完整的 IAM 角色更窄。

389 389

390有关详情，请参阅 [Bedrock IAM 文档](https://docs.aws.amazon.com/bedrock/latest/userguide/security-iam.html)。390有关详情，请参阅 [Amazon Bedrock IAM 文档](https://docs.aws.amazon.com/bedrock/latest/userguide/security-iam.html)。

391 391

392<Note>392<Note>

393 为 Claude Code 创建一个专用的 AWS 账户，以简化成本跟踪和访问控制。393 为 Claude Code 创建一个专用的 AWS 账户，以简化成本跟踪和访问控制。

433 使用 Mantle 端点433 使用 Mantle 端点

434</h2>434</h2>

435 435

436Mantle 是一个 Amazon Bedrock 端点，通过原生 Anthropic API 形状而不是 Bedrock Invoke API 提供 Claude 模型。它使用相同的 AWS 凭证、IAM 权限和本页面前面描述的 `awsAuthRefresh` 配置。436Mantle 是一个 Amazon Bedrock 端点，通过原生 Anthropic API 形状而不是 Amazon Bedrock Invoke API 提供 Claude 模型。它使用相同的 AWS 凭证、IAM 权限和本页面前面描述的 `awsAuthRefresh` 配置。

437 437

438<Note>438<Note>

439 Mantle 需要 Claude Code v2.1.94 或更高版本。运行 `claude --version` 来检查。439 Mantle 需要 Claude Code v2.1.94 或更高版本。运行 `claude --version` 来检查。

450export AWS_REGION=us-east-1450export AWS_REGION=us-east-1

451```451```

452 452

453Claude Code 从 AWS 区域构造端点 URL。{/* min-version: 2.1.172 */}从 v2.1.172 开始，区域的解析优先级与[上面的 Bedrock](#3-configure-claude-code) 相同；较早的版本仅使用 `AWS_REGION`。要为自定义端点或网关覆盖 URL，请设置 `ANTHROPIC_BEDROCK_MANTLE_BASE_URL`。453Claude Code 从 AWS 区域构造端点 URL。{/* min-version: 2.1.172 */}从 v2.1.172 开始，区域的解析优先级与[上面的 Amazon Bedrock](#3-configure-claude-code) 相同；较早的版本仅使用 `AWS_REGION`。要为自定义端点或网关覆盖 URL，请设置 `ANTHROPIC_BEDROCK_MANTLE_BASE_URL`。

454 454

455在 Claude Code 内运行 `/status` 来确认。当 Mantle 处于活动状态时，提供者行显示 `Amazon Bedrock (Mantle)`。455在 Claude Code 内运行 `/status` 来确认。当 Mantle 处于活动状态时，提供者行显示 `Amazon Bedrock (Mantle)`。

456 456

470 在 Invoke API 旁边运行 Mantle470 在 Invoke API 旁边运行 Mantle

471</h3>471</h3>

472 472

473您在 Mantle 上可用的模型可能不包括您今天使用的每个模型。设置 `CLAUDE_CODE_USE_BEDROCK` 和 `CLAUDE_CODE_USE_MANTLE` 让 Claude Code 从同一会话调用两个端点。与 Mantle 格式匹配的模型 ID 被路由到 Mantle，所有其他模型 ID 转到 Bedrock Invoke API。473您在 Mantle 上可用的模型可能不包括您今天使用的每个模型。设置 `CLAUDE_CODE_USE_BEDROCK` 和 `CLAUDE_CODE_USE_MANTLE` 让 Claude Code 从同一会话调用两个端点。与 Mantle 格式匹配的模型 ID 被路由到 Mantle，所有其他模型 ID 转到 Amazon Bedrock Invoke API。

474 474

475```bash theme={null}475```bash theme={null}

476export CLAUDE_CODE_USE_BEDROCK=1476export CLAUDE_CODE_USE_BEDROCK=1

508这些变量特定于 Mantle 端点。请参阅[环境变量](/zh-CN/env-vars)了解完整列表。508这些变量特定于 Mantle 端点。请参阅[环境变量](/zh-CN/env-vars)了解完整列表。

509 509

510| 变量 | 目的 |510| 变量 | 目的 |

511| :-------------------------------------- | :--------------------------------- |511| :-------------------------------------- | :---------------------------------------- |

516 516

517<h2 id="troubleshooting">517<h2 id="troubleshooting">

518 故障排除518 故障排除

540 540

541* 将模型指定为[推理配置文件](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html) ID541* 将模型指定为[推理配置文件](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html) ID

542 542

543Claude Code 使用 Bedrock [Invoke API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)，不支持 Converse API。543Claude Code 使用 Amazon Bedrock [Invoke API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)，不支持 Converse API。

544 544

545<h3 id="zero-token-counts-in-/context">545<h3 id="zero-token-counts-in-/context">

546 /context 中的零令牌计数546 /context 中的零令牌计数

547</h3>547</h3>

548 548

549`/context` 命令通过将工具架构发送到 Bedrock count-tokens API 来计算每个工具组的令牌。{/* min-version: 2.1.196 */}在 Claude Code v2.1.196 之前的版本中，Bedrock 拒绝了该请求，因为架构包含其 count-tokens API 不接受的字段，因此每个工具组显示 0 个令牌。分解中的其他行（如消息和内存文件）不受影响。549`/context` 命令通过将工具架构发送到 Amazon Bedrock count-tokens API 来计算每个工具组的令牌。{/* min-version: 2.1.196 */}在 Claude Code v2.1.196 之前的版本中，Amazon Bedrock 拒绝了该请求，因为架构包含其 count-tokens API 不接受的字段，因此每个工具组显示 0 个令牌。分解中的其他行（如消息和内存文件）不受影响。

550 550

551更新到 v2.1.196 或更高版本。551更新到 v2.1.196 或更高版本。

552 552

558 558

559来自 Mantle 端点的 `403`（具有有效凭证）意味着您的 AWS 账户没有被授予访问您请求的模型的权限。联系您的 AWS 账户团队以请求访问。559来自 Mantle 端点的 `403`（具有有效凭证）意味着您的 AWS 账户没有被授予访问您请求的模型的权限。联系您的 AWS 账户团队以请求访问。

560 560

561命名模型 ID 的 `400` 意味着该模型不在 Mantle 上提供。Mantle 有其自己的模型阵容，与标准 Bedrock 目录分开，因此推理配置文件 ID（如 `us.anthropic.claude-sonnet-4-6`）将不起作用。使用 Mantle 格式的 ID，或启用[两个端点](#run-mantle-alongside-the-invoke-api)，以便 Claude Code 将每个请求路由到模型可用的端点。561命名模型 ID 的 `400` 意味着该模型不在 Mantle 上提供。Mantle 有其自己的模型阵容，与标准 Amazon Bedrock 目录分开，因此推理配置文件 ID（如 `us.anthropic.claude-sonnet-4-6`）将不起作用。使用 Mantle 格式的 ID，或启用[两个端点](#run-mantle-alongside-the-invoke-api)，以便 Claude Code 将每个请求路由到模型可用的端点。

562 562

563<h2 id="additional-resources">563<h2 id="additional-resources">

564 其他资源564 其他资源

565</h2>565</h2>

566 566

567* [Bedrock 文档](https://docs.aws.amazon.com/bedrock/)567* [Amazon Bedrock 文档](https://docs.aws.amazon.com/bedrock/)

568* [Bedrock 定价](https://aws.amazon.com/bedrock/pricing/)568* [Amazon Bedrock 定价](https://aws.amazon.com/bedrock/pricing/)

569* [Bedrock 推理配置文件](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html)569* [Amazon Bedrock 推理配置文件](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html)

570* [Bedrock 令牌消耗和配额](https://docs.aws.amazon.com/bedrock/latest/userguide/quotas-token-burndown.html)570* [Amazon Bedrock 令牌消耗和配额](https://docs.aws.amazon.com/bedrock/latest/userguide/quotas-token-burndown.html)

571* [Amazon Bedrock 上的 Claude Code：快速设置指南](https://community.aws/content/2tXkZKrZzlrlu0KfH8gST5Dkppq/claude-code-on-amazon-bedrock-quick-setup-guide)571* [Amazon Bedrock 上的 Claude Code：快速设置指南](https://community.aws/content/2tXkZKrZzlrlu0KfH8gST5Dkppq/claude-code-on-amazon-bedrock-quick-setup-guide)

572* [Claude Code 监控实现 (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)572* [Claude Code 监控实现 (Amazon Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)

authentication.md +18 −6

Details

6 6

7> 登录 Claude Code 并为个人、团队和组织配置身份验证。7> 登录 Claude Code 并为个人、团队和组织配置身份验证。

8 8

9Claude Code 支持多种身份验证方法，具体取决于您的设置。个人用户可以使用 Claude.ai 账户登录，而团队可以使用 Claude for Teams 或 Enterprise、Claude Console 或云提供商（如 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry）。9Claude Code 支持多种身份验证方法，具体取决于您的设置。个人用户可以使用 Claude.ai 账户登录，而团队可以使用 Claude for Teams 或 Enterprise、Claude Console 或云提供商（如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry）。

10 10

11<h2 id="log-in-to-claude-code">11<h2 id="log-in-to-claude-code">

12 登录 Claude Code12 登录 Claude Code

23* **Claude Pro 或 Max 订阅**：使用您的 Claude.ai 账户登录。在 [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_pro_max) 订阅。23* **Claude Pro 或 Max 订阅**：使用您的 Claude.ai 账户登录。在 [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_pro_max) 订阅。

24* **Claude for Teams 或 Enterprise**：使用您的团队管理员邀请您的 Claude.ai 账户登录。24* **Claude for Teams 或 Enterprise**：使用您的团队管理员邀请您的 Claude.ai 账户登录。

25* **Claude Console**：使用您的 Console 凭证登录。您的管理员必须先 [邀请您](#claude-console-authentication)。25* **Claude Console**：使用您的 Console 凭证登录。您的管理员必须先 [邀请您](#claude-console-authentication)。

26* **云提供商**：如果您的组织使用 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Vertex AI](/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/zh-CN/microsoft-foundry)，请在运行 `claude` 之前设置所需的环境变量。不需要浏览器登录。26* **云提供商**：如果您的组织使用 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud's Agent Platform](/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/zh-CN/microsoft-foundry)，请在运行 `claude` 之前设置所需的环境变量。不需要浏览器登录。

27* **云网关**：如果您的组织运行自托管的 [Claude apps gateway](/zh-CN/claude-apps-gateway)，请通过 `/login` 使用企业 SSO 登录。网关颁发的令牌是会话的唯一凭证。27* **云网关**：如果您的组织运行自托管的 [Claude apps gateway](/zh-CN/claude-apps-gateway)，请通过 `/login` 使用企业 SSO 登录。网关颁发的令牌是会话的唯一凭证。

28 28

29要登出并重新身份验证，请在 Claude Code 提示符处输入 `/logout`。29要登出并重新身份验证，请在 Claude Code 提示符处输入 `/logout`。

40* [Claude Console](#claude-console-authentication)40* [Claude Console](#claude-console-authentication)

41* [Claude apps gateway](/zh-CN/claude-apps-gateway)，一个自托管网关，使用您的 IdP 为开发人员签名，并将推理路由到您配置的云提供商41* [Claude apps gateway](/zh-CN/claude-apps-gateway)，一个自托管网关，使用您的 IdP 为开发人员签名，并将推理路由到您配置的云提供商

42* [Amazon Bedrock](/zh-CN/amazon-bedrock)42* [Amazon Bedrock](/zh-CN/amazon-bedrock)

~~43* [Google Vertex AI](/zh-CN/google-vertex-ai)~~43* [Google Cloud's Agent Platform](/zh-CN/google-vertex-ai)

44* [Microsoft Foundry](/zh-CN/microsoft-foundry)44* [Microsoft Foundry](/zh-CN/microsoft-foundry)

45 45

46<h3 id="claude-for-teams-or-enterprise">46<h3 id="claude-for-teams-or-enterprise">

105 云提供商身份验证105 云提供商身份验证

106</h3>106</h3>

107 107

108对于使用 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 的团队：108对于使用 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 的团队：

109 109

110<Steps>110<Steps>

111 <Step title="遵循提供商设置">111 <Step title="遵循提供商设置">

112 遵循 [Bedrock 文档](/zh-CN/amazon-bedrock)、[Vertex 文档](/zh-CN/google-vertex-ai) 或 [Microsoft Foundry 文档](/zh-CN/microsoft-foundry)。112 遵循 [Amazon Bedrock 文档](/zh-CN/amazon-bedrock)、[Google Cloud's Agent Platform 文档](/zh-CN/google-vertex-ai) 或 [Microsoft Foundry 文档](/zh-CN/microsoft-foundry)。

113 </Step>113 </Step>

114 114

115 <Step title="分发配置">115 <Step title="分发配置">

140 140

141`apiKeyHelper`、`ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN` 适用于 CLI 和包装它的表面，包括 VS Code 扩展、Agent SDK 和 GitHub Actions。Claude Desktop 和云会话不会调用 `apiKeyHelper` 或读取这些环境变量：它们使用 OAuth，除了运行 [组织分发的第三方推理配置](/zh-CN/llm-gateway-connect#desktop-app) 的桌面会话外，这些会话使用该配置的凭证进行身份验证。141`apiKeyHelper`、`ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN` 适用于 CLI 和包装它的表面，包括 VS Code 扩展、Agent SDK 和 GitHub Actions。Claude Desktop 和云会话不会调用 `apiKeyHelper` 或读取这些环境变量：它们使用 OAuth，除了运行 [组织分发的第三方推理配置](/zh-CN/llm-gateway-connect#desktop-app) 的桌面会话外，这些会话使用该配置的凭证进行身份验证。

142 142

143<h3 id="renew-an-expiring-login">

144 续期即将过期的登录

145</h3>

146

147当您使用 `/login` 创建的登录在过期前五天内时，Claude Code 会在启动时显示警告：`您的登录将在 3 天后过期 · 运行 /login 以续期`。需要 Claude Code v2.1.203 或更高版本。

148

149运行 `/login` 以续期。该警告仅供参考，永远不会阻止请求：身份验证将继续工作，直到登录实际过期。登录生命周期本身不变；提前警告是 v2.1.203 添加的功能。

150

151该警告仅在 claude.ai 或 Claude Console 登录是活跃凭证时出现，而不是在云提供商、`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 提供凭证时出现。

152

153对于运行无人值守的会话，提前续期最为重要。在 [agent view 中的后台会话](/zh-CN/agent-view) 或 [Remote Control](/zh-CN/remote-control) 会话一旦登录过期，就会停止进行，并且在您再次登录之前无法恢复。

154

143<h3 id="authentication-precedence">155<h3 id="authentication-precedence">

144 身份验证优先级156 身份验证优先级

145</h3>157</h3>

1535. `CLAUDE_CODE_OAUTH_TOKEN` 环境变量。由 [`claude setup-token`](#generate-a-long-lived-token) 生成的长期 OAuth 令牌。用于 CI 管道和脚本，其中浏览器登录不可用。1655. `CLAUDE_CODE_OAUTH_TOKEN` 环境变量。由 [`claude setup-token`](#generate-a-long-lived-token) 生成的长期 OAuth 令牌。用于 CI 管道和脚本，其中浏览器登录不可用。

1546. 来自 `/login` 的订阅 OAuth 凭证。这是 Claude Pro、Max、Team 和 Enterprise 用户的默认设置。1666. 来自 `/login` 的订阅 OAuth 凭证。这是 Claude Pro、Max、Team 和 Enterprise 用户的默认设置。

155 167

156一个已签名的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话位于此列表之外：它是一个提供商选择，如 Bedrock 或 Vertex，并且它优先于它们。当网关会话存在时，即使设置了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY`，CLI 也会使用网关令牌进行身份验证，上面的持有者令牌、API 密钥和 `apiKeyHelper` 条目不会被使用。168一个已签名的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话位于此列表之外：它是一个提供商选择，如 Amazon Bedrock 或 Google Cloud 的 Agent Platform，并且它优先于它们。当网关会话存在时，即使设置了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY`，CLI 也会使用网关令牌进行身份验证，上面的持有者令牌、API 密钥和 `apiKeyHelper` 条目不会被使用。

157 169

158如果您有活跃的 Claude 订阅，但环境中也设置了 `ANTHROPIC_API_KEY`，则 API 密钥在批准后优先。如果密钥属于已禁用或过期的组织，这可能会导致身份验证失败。运行 `unset ANTHROPIC_API_KEY` 以回退到您的订阅，并检查 `/status` 以确认哪种方法处于活跃状态。170如果您有活跃的 Claude 订阅，但环境中也设置了 `ANTHROPIC_API_KEY`，则 API 密钥在批准后优先。如果密钥属于已禁用或过期的组织，这可能会导致身份验证失败。运行 `unset ANTHROPIC_API_KEY` 以回退到您的订阅，并检查 `/status` 以确认哪种方法处于活跃状态。

159 171

auto-mode-config.md +3 −3

Details

9[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)让 Claude Code 无需常规权限提示即可运行，通过将工具调用路由到一个分类器，该分类器会阻止任何不可逆、破坏性或针对您环境外的操作。拒绝和明确询问规则在分类器之前进行评估，仍然会阻止或提示。使用 `autoMode` 设置块告诉该分类器您的组织信任哪些代码库、存储桶和域，以便它停止阻止常规内部操作。9[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)让 Claude Code 无需常规权限提示即可运行，通过将工具调用路由到一个分类器，该分类器会阻止任何不可逆、破坏性或针对您环境外的操作。拒绝和明确询问规则在分类器之前进行评估，仍然会阻止或提示。使用 `autoMode` 设置块告诉该分类器您的组织信任哪些代码库、存储桶和域，以便它停止阻止常规内部操作。

10 10

11<Note>11<Note>

12 自动模式可通过 Anthropic API 供所有用户使用。在 Amazon Bedrock、Google Cloud Vertex AI、Microsoft Foundry 和已登录的[Claude 应用网关](/zh-CN/claude-apps-gateway)会话上，您必须首先[设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`](/zh-CN/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)。如果 Claude Code 报告您的账户无法使用自动模式，请检查[完整要求](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)，其中还涵盖了支持的模型和 Team 及 Enterprise 计划上的所有者启用。12 自动模式可通过 Anthropic API 供所有用户使用。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登录的[Claude 应用网关](/zh-CN/claude-apps-gateway)会话上，您必须首先[设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`](/zh-CN/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)。如果 Claude Code 报告您的账户无法使用自动模式，请检查[完整要求](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)，其中还涵盖了支持的模型和 Team 及 Enterprise 计划上的所有者启用。

13</Note>13</Note>

14 14

15默认情况下，分类器仅信任工作目录和当前代码库的已配置远程。推送到您公司的源代码控制组织或写入团队云存储桶等操作会被阻止，直到您将它们添加到 `autoMode.environment`。15默认情况下，分类器仅信任工作目录和当前代码库的已配置远程。推送到您公司的源代码控制组织或写入团队云存储桶等操作会被阻止，直到您将它们添加到 `autoMode.environment`。

60 * **组织**60 * **组织**

61 * **Claude Code 的主要用途**：默认为软件开发61 * **Claude Code 的主要用途**：默认为软件开发

62 * **云提供商**62 * **云提供商**

~~63 * **代码库可见性**：除非其远程主机和名称另有说明，否则代码库被假定为私有~~63 * **代码库可见性**：除非其远程主机和名称另有说明，{/* min-version: 2.1.200 */}或会话中较早的可见性检查分类器读取的内容显示它是公开的，否则代码库被假定为私有。分类器读取您的消息和 Claude 运行的命令，而不是它们的输出，因此证据必须是它能读取的内容，例如您自己的消息将存储库命名为公开；单独的 `gh repo view` 的输出无法到达它。转录证据检查需要 Claude Code v2.1.200 或更高版本

64 * **内部共享 / 代码片段托管**：公共粘贴和 gist 服务被视为在信任边界之外，直到您命名一个64 * **内部共享 / 代码片段托管**：公共粘贴和 gist 服务被视为在信任边界之外，直到您命名一个

65 * **特定于组织的 CLI**65 * **特定于组织的 CLI**

66 * **密钥管理**66 * **密钥管理**

69 * **网络态势**69 * **网络态势**

70 * **受保护的部署命名空间 / 环境**：回退到敏感远程目标启发式方法，直到您命名它们70 * **受保护的部署命名空间 / 环境**：回退到敏感远程目标启发式方法，直到您命名它们

71 * **数据保留 / 解密**71 * **数据保留 / 解密**

72* **信任槽**：命名分类器视为在您边界内的内容。槽位是受信任的代码库、源代码控制、受信任的内部域、受信任的云存储桶、关键内部服务和内部包注册表。代码库和源代码控制条目默认为工作代码库及其配置的远程。所有其他信任槽默认为 `None configured`，因此在您添加之前没有其他内容是受信任的。72* **信任槽**：命名分类器视为在您边界内的内容。槽位是受信任的代码库、源代码控制、受信任的内部域、受信任的云存储桶、关键内部服务和内部包注册表。代码库和源代码控制条目默认为工作代码库及其配置的远程。所有其他信任槽默认为 `None configured`，因此在您添加之前没有其他内容是受信任的。{/* min-version: 2.1.203 */}存储库的可见性仅限于机密材料：私有存储库是机密材料的可接受目标，但将存储库设为私有永远不会清除秘密、个人或受信任的数据进入其中，分类器将从工作存储库外部移植、重新指向或首次读取的内容视为不是该存储库自己的工作。此范围界定需要 Claude Code v2.1.203 或更高版本。

73* **敏感性槽**：命名保护规则视为高风险的内容。槽位是敏感数据位置和受众、敏感远程目标和受保护的 IaC 范围。每个都默认为广泛的启发式方法，例如将任何名称中包含 `prod` 或 `production` 的主机或命名空间视为敏感远程目标，因此保护规则在您配置任何内容之前就处于活动状态。在敏感性槽中命名具体目标会使这些规则应用于命名的目标而不是启发式方法。73* **敏感性槽**：命名保护规则视为高风险的内容。槽位是敏感数据位置和受众、敏感远程目标和受保护的 IaC 范围。每个都默认为广泛的启发式方法，例如将任何名称中包含 `prod` 或 `production` 的主机或命名空间视为敏感远程目标，因此保护规则在您配置任何内容之前就处于活动状态。在敏感性槽中命名具体目标会使这些规则应用于命名的目标而不是启发式方法。

74 74

75要在默认值旁边添加您自己的条目，请在数组中包含字面字符串 `"$defaults"`。默认条目会在该位置被拼接进去，因此您的自定义条目可以在它们之前或之后。75要在默认值旁边添加您自己的条目，请在数组中包含字面字符串 `"$defaults"`。默认条目会在该位置被拼接进去，因此您的自定义条目可以在它们之前或之后。

channels.md +1 −1

Details

7> 使用 channels 从 MCP 服务器将消息、警报和 webhooks 推送到您的 Claude Code 会话中。转发 CI 结果、聊天消息和监控事件，以便 Claude 在您离开时做出反应。7> 使用 channels 从 MCP 服务器将消息、警报和 webhooks 推送到您的 Claude Code 会话中。转发 CI 结果、聊天消息和监控事件，以便 Claude 在您离开时做出反应。

8 8

9<Note>9<Note>

10 Channels 处于[研究预览](#research-preview)阶段，需要 Claude Code v2.1.80 或更高版本。它们需要通过 claude.ai 或控制台 API 密钥进行 Anthropic 身份验证，在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用。Team 和 Enterprise 组织必须[明确启用它们](#enterprise-controls)。10 Channels 处于[研究预览](#research-preview)阶段，需要 Claude Code v2.1.80 或更高版本。它们需要通过 claude.ai 或控制台 API 密钥进行 Anthropic 身份验证，在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。Team 和 Enterprise 组织必须[明确启用它们](#enterprise-controls)。

11</Note>11</Note>

12 12

13Channel 是一个 MCP 服务器，它将事件推送到您运行中的 Claude Code 会话中，以便 Claude 可以对您不在终端时发生的事情做出反应。Channels 可以是双向的：Claude 读取事件并通过同一 channel 回复，就像聊天桥接一样。事件仅在会话打开时到达，因此对于始终在线的设置，您可以在后台进程或持久终端中运行 Claude。13Channel 是一个 MCP 服务器，它将事件推送到您运行中的 Claude Code 会话中，以便 Claude 可以对您不在终端时发生的事情做出反应。Channels 可以是双向的：Claude 读取事件并通过同一 channel 回复，就像聊天桥接一样。事件仅在会话打开时到达，因此对于始终在线的设置，您可以在后台进程或持久终端中运行 Claude。

channels-reference.md +2 −2

Details

36* **聊天平台**（Telegram、Discord）：您的插件在本地运行并轮询平台的 API 以获取新消息。当有人向您的机器人发送 DM 时，插件接收消息并将其转发给 Claude。无需公开 URL。36* **聊天平台**（Telegram、Discord）：您的插件在本地运行并轮询平台的 API 以获取新消息。当有人向您的机器人发送 DM 时，插件接收消息并将其转发给 Claude。无需公开 URL。

37* **Webhooks**（CI、监控）：您的服务器在本地 HTTP 端口上侦听。外部系统 POST 到该端口，您的服务器将有效负载推送到 Claude。37* **Webhooks**（CI、监控）：您的服务器在本地 HTTP 端口上侦听。外部系统 POST 到该端口，您的服务器将有效负载推送到 Claude。

38 38

39<img src="https://mintlify.s3.us-west-1.amazonaws.com/claude-code/zh-CN/images/channel-architecture.svg" alt="架构图显示外部系统连接到您的本地频道服务器，该服务器通过 stdio 与 Claude Code 通信" />39<img src="https://mintcdn.com/claude-code/9FG0ZKj9uKYiHmbi/images/channel-architecture.svg?fit=max&auto=format&n=9FG0ZKj9uKYiHmbi&q=85&s=9a037b7da80184ae49015c0256b21a1f" alt="架构图显示外部系统连接到您的本地频道服务器，该服务器通过 stdio 与 Claude Code 通信" width="600" height="220" data-path="images/channel-architecture.svg" />

40 40

41<h2 id="what-you-need">41<h2 id="what-you-need">

42 您需要什么42 您需要什么

474 474

475本地终端对话在所有这一切中保持打开。如果终端上的某人在远程判决到达之前回答，该答案将被应用，待处理的远程请求将被删除。475本地终端对话在所有这一切中保持打开。如果终端上的某人在远程判决到达之前回答，该答案将被应用，待处理的远程请求将被删除。

476 476

477<img src="https://mintlify.s3.us-west-1.amazonaws.com/claude-code/zh-CN/images/channel-permission-relay.svg" alt="序列图：Claude Code 向频道服务器发送 permission_request 通知，服务器格式化并将提示发送到聊天应用，人类使用判决回复，服务器将该回复解析为权限通知回到 Claude Code" />477<img src="https://mintcdn.com/claude-code/9FG0ZKj9uKYiHmbi/images/channel-permission-relay.svg?fit=max&auto=format&n=9FG0ZKj9uKYiHmbi&q=85&s=97d57f128f0da55f105ab1e3a7e10240" alt="序列图：Claude Code 向频道服务器发送 permission_request 通知，服务器格式化并将提示发送到聊天应用，人类使用判决回复，服务器将该回复解析为权限通知回到 Claude Code" width="600" height="230" data-path="images/channel-permission-relay.svg" />

478 478

479<h3 id="permission-request-fields">479<h3 id="permission-request-fields">

480 权限请求字段480 权限请求字段

chrome.md +1 −1

Details

40* 直接 Anthropic 计划（Pro、Max、Team 或 Enterprise）40* 直接 Anthropic 计划（Pro、Max、Team 或 Enterprise）

41 41

42<Note>42<Note>

43 Chrome 集成不可通过 Amazon Bedrock、Google Cloud Vertex AI 或 Microsoft Foundry 等第三方提供商获得。如果您仅通过第三方提供商访问 Claude，则需要单独的 claude.ai 账户来使用此功能。43 Chrome 集成不可通过 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 等第三方提供商获得。如果您仅通过第三方提供商访问 Claude，则需要单独的 claude.ai 账户来使用此功能。

44</Note>44</Note>

45 45

46<h2 id="get-started-in-the-cli">46<h2 id="get-started-in-the-cli">

claude-apps-gateway-config.md +8 −6

Details

4 4

5# Claude 应用网关配置5# Claude 应用网关配置

6 6

~~7> 每个 gateway.yaml 选项的参考：监听器和 TLS、OIDC、会话、Postgres 存储、Bedrock/Claude Platform on AWS/Agent Platform/Foundry 上游、模型路由、托管策略和遥测。~~7> 每个 gateway.yaml 选项的参考：监听器和 TLS、OIDC、会话、Postgres 存储、Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上游、模型路由、托管策略和遥测。

8 8

9Claude 应用网关部署由一个 YAML 文件配置，按惯例命名为 `gateway.yaml`。该文件定义网关所做的一切：它在哪里监听、开发者如何登录、推理去往何处，以及应用哪些策略和遥测。本页是该文件中每个选项的参考。要编写你的第一个配置，请从[快速入门](/zh-CN/claude-apps-gateway#quickstart)开始，它构建一个最小的工作配置并运行它；一旦你有了满意的配置，[部署指南](/zh-CN/claude-apps-gateway-deploy)涵盖了在 Kubernetes、Cloud Run 或你自己的平台上容器化和托管它。9Claude 应用网关部署由一个 YAML 文件配置，按惯例命名为 `gateway.yaml`。该文件定义网关所做的一切：它在哪里监听、开发者如何登录、推理去往何处，以及应用哪些策略和遥测。本页是该文件中每个选项的参考。

11要编写你的第一个配置，请从[快速入门](/zh-CN/claude-apps-gateway#quickstart)开始，它构建一个最小的工作配置并运行它。一旦你有了满意的配置，[部署指南](/zh-CN/claude-apps-gateway-deploy)涵盖了在 Kubernetes、Cloud Run 或你自己的平台上容器化和托管它。

10 12

11网关在启动时使用 `claude gateway --config /path/to/gateway.yaml` 读取该文件一次。每个选项都在启动时根据模式进行验证，因此格式错误的配置在启动时失败并显示字段级错误，而不是在首次使用时失败。13网关在启动时使用 `claude gateway --config /path/to/gateway.yaml` 读取该文件一次。每个选项都在启动时根据模式进行验证，因此格式错误的配置在启动时失败并显示字段级错误，而不是在首次使用时失败。

12 14

24* [`oidc`](#oidc)：你的身份提供者 (IdP)，包括发行者、客户端、声明映射和谁可以登录26* [`oidc`](#oidc)：你的身份提供者 (IdP)，包括发行者、客户端、声明映射和谁可以登录

25* [`session`](#session)：网关铸造的持有者令牌，包括密钥和生命周期27* [`session`](#session)：网关铸造的持有者令牌，包括密钥和生命周期

26* [`store`](#store)：PostgreSQL，用于设备授权和速率限制计数器28* [`store`](#store)：PostgreSQL，用于设备授权和速率限制计数器

~~27* [`upstreams`](#upstreams)：推理去往何处，无论是 Anthropic、Bedrock、Claude Platform on AWS、Agent Platform 还是 Foundry~~29* [`upstreams`](#upstreams)：推理去往何处，无论是 Anthropic、Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 还是 Microsoft Foundry

28 30

29**可选部分：**31**可选部分：**

30 32

123 `upstreams`125 `upstreams`

124</h3>126</h3>

125 127

126`upstreams` 是一个有序列表。网关将推理转发到解析请求的模型的第一个上游。在 `5xx`、`429`、`401`、`403`、`404` 或超时时，它故障转移到下一个；其他 `4xx` 不会，因为这些错误归因于请求而不是上游。`401` 或 `403` 意味着网关自己的凭证对该上游失败，`404` 意味着该上游不服务请求的模型，因此列表中的后续上游仍然可以。同一提供者的多个上游必须设置不同的 `name:`。128`upstreams` 是一个有序列表。网关将推理转发到解析请求的模型的第一个上游。在 `5xx`、`429`、`401`、`403`、`404` 或超时时，它故障转移到下一个；其他 `4xx` 不会，因为这些错误归因于请求而不是上游。`401` 或 `403` 意味着网关自己的凭证对该上游失败，`404` 意味着该上游不服务请求的模型，因此列表中的后续上游仍然可以。

127 129

128在 `404` 上故障转移需要网关 v2.1.198 或更高版本。早期版本即使列表中的后续上游服务该模型，也会将第一个 `404` 返回给客户端。130在 `404` 上故障转移需要网关 v2.1.198 或更高版本。早期版本即使列表中的后续上游服务该模型，也会将第一个 `404` 返回给客户端。

129 131

130Bedrock、Claude Platform on AWS、Agent Platform 和 Foundry 客户端在启动时构建一次，它们的 SDK 在内部刷新凭证，因此轮换云凭证不需要重启。静态 Anthropic API 密钥和持有者在启动时读取；请参阅 [Anthropic API](#anthropic-api)。132Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 和 Microsoft Foundry 客户端在启动时构建一次，它们的 SDK 在内部刷新凭证，因此轮换云凭证不需要重启。静态 Anthropic API 密钥和持有者在启动时读取；请参阅 [Anthropic API](#anthropic-api)。

131 133

132<h4 id="anthropic-api">134<h4 id="anthropic-api">

133 Anthropic API135 Anthropic API

401 `models`403 `models`

402</h3>404</h3>

403 405

404`models` 块是可选的管理员策划的模型列表，在 `/v1/models` 提供，用于按上游翻译模型 ID。对于非美国 Bedrock 地区、Bedrock 预配吞吐量 ARN 和 Foundry 部署名称是必需的。406`models` 块是可选的管理员策划的模型列表，在 `/v1/models` 提供，用于按上游翻译模型 ID。对于非美国 Amazon Bedrock 地区、Amazon Bedrock 预配吞吐量 ARN 和 Microsoft Foundry 部署名称是必需的。

405 407

406```yaml theme={null}408```yaml theme={null}

407auto_include_builtin_models: true # false：仅公开下面的列表409auto_include_builtin_models: true # false：仅公开下面的列表

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

Details

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

285| 日志：`token exchange failed: id_token missing email claim` | IdP 默认不在 id\_token 中包含 `email`。此拒绝仅在设置 `allowed_email_domains` 时触发；没有它，缺失的电子邮件铸造没有电子邮件的会话 | 配置 IdP 在 id\_token 中发出 `email`。Okta：将 `email` 添加到自定义授权服务器的 ID 令牌声明。Entra：在应用注册上将 `email` 添加为可选声明。PingFederate：启用发出 `email` 的 OpenID Connect 策略。如果 IdP 从 userinfo 端点提供 `email` 但不会在 id\_token 中包含它，如 Okta 组织授权服务器，设置 `oidc.userinfo_fallback: true`。 |285| 日志：`token exchange failed: id_token missing email claim` | IdP 默认不在 id\_token 中包含 `email`。此拒绝仅在设置 `allowed_email_domains` 时触发；没有它，缺失的电子邮件铸造没有电子邮件的会话 | 配置 IdP 在 id\_token 中发出 `email`。Okta：将 `email` 添加到自定义授权服务器的 ID 令牌声明。Entra：在应用注册上将 `email` 添加为可选声明。PingFederate：启用发出 `email` 的 OpenID Connect 策略。如果 IdP 从 userinfo 端点提供 `email` 但不会在 id\_token 中包含它，如 Okta 组织授权服务器，设置 `oidc.userinfo_fallback: true`。 |

286| 每个 Bedrock 请求返回 502；日志显示 `Could not load credentials from any providers` | 在 EC2 上，IMDSv2 的默认跳数限制为 1 阻止来自容器内的实例元数据请求。启动和 `/readyz` 通过，因为 AWS SDK 在第一个请求时解析实例凭证，而不是在客户端构造时 | 使用 `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2` 提高跳数限制，或在启动模板中设置它。更改适用于实例上的每个容器。在可用的地方优先使用 ECS 任务角色，它从 ECS 容器凭证端点读取凭证，完全避免更改，或在专用网关实例上应用更改以限制暴露。 |286| 每个 Amazon Bedrock 请求返回 502；日志显示 `Could not load credentials from any providers` | 在 EC2 上，IMDSv2 的默认跳数限制为 1 阻止来自容器内的实例元数据请求。启动和 `/readyz` 通过，因为 AWS SDK 在第一个请求时解析实例凭证，而不是在客户端构造时 | 使用 `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2` 提高跳数限制，或在启动模板中设置它。更改适用于实例上的每个容器。在可用的地方优先使用 ECS 任务角色，它从 ECS 容器凭证端点读取凭证，完全避免更改，或在专用网关实例上应用更改以限制暴露。 |

claude-apps-gateway-on-gcp.md +5 −5

Details

17</h2>17</h2>

18 18

19<Frame>19<Frame>

20 <img src="https://mintcdn.com/claude-code/-uq-4JE0W_JO5Er5/images/claude-gateway-gcp-architecture.svg?fit=max&auto=format&n=-uq-4JE0W_JO5Er5&q=85&s=cb705151c69128ac0da235852d5600ab" alt="Google Cloud 上 Claude apps gateway 的图表：Claude Code 客户端通过 HTTPS 连接到网关（Cloud Run 或 GKE），网关在 VPC 内运行，旁边是用于会话状态的私有 IP Cloud SQL 数据库。网关通过 OIDC 针对 Google Workspace 对用户进行签名，从 Secret Manager 读取配置和机密，将模型请求转发到 Agent Platform，并在部署时从 Artifact Registry 拉取其镜像。" width="760" height="400" data-path="images/claude-gateway-gcp-architecture.svg" />20 <img src="https://mintcdn.com/claude-code/-uq-4JE0W_JO5Er5/images/claude-gateway-gcp-architecture.svg?fit=max&auto=format&n=-uq-4JE0W_JO5Er5&q=85&s=cb705151c69128ac0da235852d5600ab" alt="Google Cloud 上 Claude apps gateway 的图表：Claude Code 客户端通过 HTTPS 连接到网关（Cloud Run 或 GKE），网关在 VPC 内运行，旁边是用于会话状态的私有 IP Cloud SQL 数据库。网关通过 OIDC 针对 Google Workspace 对用户进行签名，从 Secret Manager 读取配置和机密，将模型请求转发到 Google Cloud 的 Agent Platform，并在部署时从 Artifact Registry 拉取其镜像。" width="760" height="400" data-path="images/claude-gateway-gcp-architecture.svg" />

21</Frame>21</Frame>

22 22

23参考配置配置以下内容：23参考配置配置以下内容：

80 </Step>80 </Step>

81 81

82 <Step title="创建服务账户并授予 IAM">82 <Step title="创建服务账户并授予 IAM">

~~83 网关作为专用服务账户运行，具有调用 Agent Platform 的权限。它通过 VPC 使用密码用户到达 Cloud SQL，因此不需要 Cloud SQL IAM 角色：~~83 网关作为专用服务账户运行，具有调用 Google Cloud 的 Agent Platform 的权限。它通过 VPC 使用密码用户到达 Cloud SQL，因此不需要 Cloud SQL IAM 角色：

84 84

85 ```bash theme={null}85 ```bash theme={null}

86 gcloud iam service-accounts create claude-gateway --display-name="Claude apps gateway"86 gcloud iam service-accounts create claude-gateway --display-name="Claude apps gateway"

141 </Step>141 </Step>

142 142

143 <Step title="编写 gateway.yaml">143 <Step title="编写 gateway.yaml">

144 `upstreams` 块使用 `auth: {}` 指向 Agent Platform，因此网关通过运行时服务账户的应用默认凭据进行身份验证。有关每个字段，请参阅[配置参考](/zh-CN/claude-apps-gateway-config)。144 `upstreams` 块使用 `auth: {}` 指向 Google Cloud 的 Agent Platform，因此网关通过运行时服务账户的应用默认凭据进行身份验证。有关每个字段，请参阅[配置参考](/zh-CN/claude-apps-gateway-config)。

145 145

146 两个 `listen` 字段取决于什么在网关前面：146 两个 `listen` 字段取决于什么在网关前面：

147 147

226 --no-invoker-iam-check226 --no-invoker-iam-check

227 ```227 ```

228 228

229 直接 VPC 出口，通过 `--network`、`--subnet` 和 `--vpc-egress=private-ranges-only`，让服务直接到达 Cloud SQL 私有 IP。到 Agent Platform 端点和 `accounts.google.com` 的公共出口直接进入互联网，而不是通过 VPC，因此不需要 Cloud NAT。229 直接 VPC 出口，通过 `--network`、`--subnet` 和 `--vpc-egress=private-ranges-only`，让服务直接到达 Cloud SQL 私有 IP。到 Google Cloud 的 Agent Platform 端点和 `accounts.google.com` 的公共出口直接进入互联网，而不是通过 VPC，因此不需要 Cloud NAT。

230 230

231 调用者 IAM 检查必须打开或禁用。网关运行自己的 OIDC，其客户端不携带 GCP 令牌，因此 Cloud Run 的调用者检查必须允许未经身份验证的请求。网关的 OIDC 登录在请求到达容器后对其进行身份验证，使用 `allowed_email_domains` 限制哪些域可以登录。231 调用者 IAM 检查必须打开或禁用。网关运行自己的 OIDC，其客户端不携带 GCP 令牌，因此 Cloud Run 的调用者检查必须允许未经身份验证的请求。网关的 OIDC 登录在请求到达容器后对其进行身份验证，使用 `allowed_email_domains` 限制哪些域可以登录。

232 232

318| `--no-invoker-iam-check` 被拒绝，显示 `invoker_iam_disabled is not currently available` | 被 `constraints/run.managed.requireInvokerIam` 阻止 | 使用 `--allow-unauthenticated`。如果通过 `constraints/iam.allowedPolicyMemberDomains` 的域受限共享也阻止了它，请使用 GKE 路径，它在网络层公开网关，无需 `allUsers` 绑定。 |318| `--no-invoker-iam-check` 被拒绝，显示 `invoker_iam_disabled is not currently available` | 被 `constraints/run.managed.requireInvokerIam` 阻止 | 使用 `--allow-unauthenticated`。如果通过 `constraints/iam.allowedPolicyMemberDomains` 的域受限共享也阻止了它，请使用 GKE 路径，它在网络层公开网关，无需 `allUsers` 绑定。 |

320| 网关启动在 Cloud Run 上以 Postgres 连接超时错误退出 | 服务未附加到 VPC，或 Cloud SQL 在该 VPC 上没有私有 IP；存储在 5 秒后停止等待 | 使用 `--network` 和 `--subnet` 部署以进行直接 VPC 出口，并使用 `--no-assign-ip` 和 `--network` 指向同一 VPC 创建 Cloud SQL 实例 |320| 网关启动在 Cloud Run 上以 Postgres 连接超时错误退出 | 服务未附加到 VPC，或 Cloud SQL 在该 VPC 上没有私有 IP；存储在 5 秒后停止等待 | 使用 `--network` 和 `--subnet` 部署以进行直接 VPC 出口，并使用 `--no-assign-ip` 和 `--network` 指向同一 VPC 创建 Cloud SQL 实例 |

321| Agent Platform 请求返回 `403 PERMISSION_DENIED` | 运行时未使用 `claude-gateway` 服务账户，或模型未在 Model Garden 中为项目启用 | 在 Cloud Run 上设置 `--service-account` 或在 GKE 上绑定 Workload Identity，并在 Model Garden 中为目标区域启用每个 Claude 模型 |321| Google Cloud 的 Agent Platform 请求返回 `403 PERMISSION_DENIED` | 运行时未使用 `claude-gateway` 服务账户，或模型未在 Model Garden 中为项目启用 | 在 Cloud Run 上设置 `--service-account` 或在 GKE 上绑定 Workload Identity，并在 Model Garden 中为目标区域启用每个 Claude 模型 |

323 323

324<h2 id="next-steps">324<h2 id="next-steps">

claude-apps-gateway-spend-limits.md +2 −2

Details

61 61

62在每个响应之后，使用计量器从响应中读取令牌计数，当它流向客户端时，以 USD 列表价格对其进行定价，并为所有三个时期桶增加 Postgres 计数器。计量器是流上的单个读取器，因此客户端的字节不受影响，计量失败不会破坏响应。62在每个响应之后，使用计量器从响应中读取令牌计数，当它流向客户端时，以 USD 列表价格对其进行定价，并为所有三个时期桶增加 Postgres 计数器。计量器是流上的单个读取器，因此客户端的字节不受影响，计量失败不会破坏响应。

63 63

64支出限制从 USD 列表价格的令牌计数估计支出；它们是断路器，而不是发票。对于权威计费，请根据你的提供商自己的使用报告进行协调，例如 Anthropic 使用和成本 Admin API、Bedrock 上的调用日志或 Google Cloud 上的 Cloud Monitoring。64支出限制从 USD 列表价格的令牌计数估计支出；它们是断路器，而不是发票。对于权威计费，请根据你的提供商自己的使用报告进行协调，例如 Anthropic 使用和成本 Admin API、Amazon Bedrock 上的调用日志或 Google Cloud 上的 Cloud Monitoring。

65 65

66定价使用与 Claude Code CLI 用于自己的成本显示相同的表，具有跨 Anthropic、Bedrock (`us.anthropic.…-v1:0`)、Agent Platform (`claude-…@date`) 和 Foundry ID 形式的相同模型 ID 规范化。表无法放置的模型 ID（例如 Foundry 部署名称或推理配置文件 ARN）以未知模型默认层 \$5/\$25 每百万输入/输出令牌的价格定价，而不是零，因此无法识别的 ID 无法通过不计量来绕过上限。网关在启动时和运行时每个 ID 一次警告模型何时通过回退定价。66定价使用与 Claude Code CLI 用于自己的成本显示相同的表，具有跨 Anthropic、Amazon Bedrock (`us.anthropic.…-v1:0`)、Google Cloud 的 Agent Platform (`claude-…@date`) 和 Microsoft Foundry ID 形式的相同模型 ID 规范化。表无法放置的模型 ID（例如 Microsoft Foundry 部署名称或推理配置文件 ARN）以未知模型默认层 \$5/\$25 每百万输入/输出令牌的价格定价，而不是零，因此无法识别的 ID 无法通过不计量来绕过上限。网关在启动时和运行时每个 ID 一次警告模型何时通过回退定价。

67 67

68客户端中止也被计费。上游仅在流的终端帧中报告输出令牌，因此中止的流不会携带它们。计量器从流式内容大小保持保守的下限估计，大约每令牌四个字符，并在终端使用帧缺失时计费。完整流始终计费上游报告的计数。没有这个，一个受限的开发者可以流式输出并在结束前立即中止每个请求，花费而不被计数。68客户端中止也被计费。上游仅在流的终端帧中报告输出令牌，因此中止的流不会携带它们。计量器从流式内容大小保持保守的下限估计，大约每令牌四个字符，并在终端使用帧缺失时计费。完整流始终计费上游报告的计数。没有这个，一个受限的开发者可以流式输出并在结束前立即中止每个请求，花费而不被计数。

69 69

claude-code-on-the-web.md +18 −18

Details

4 4

5# 在网络上使用 Claude Code5# 在网络上使用 Claude Code

6 6

~~7> 配置云环境、设置脚本、网络访问和 Docker，在 Anthropic 的沙箱中运行。使用 `--remote` 和 `--teleport` 在网络和终端之间移动会话。~~7> 配置云环境、设置脚本、网络访问和 Docker，在 Anthropic 的沙箱中运行。使用 `--cloud` 和 `--teleport` 在网络和终端之间移动会话。

8 8

9<Note>9<Note>

10 Claude Code on the web 处于研究预览阶段，适用于 Pro、Max 和 Team 用户，以及拥有高级席位或 Chat + Claude Code 席位的 Enterprise 用户。10 Claude Code on the web 处于研究预览阶段，适用于 Pro、Max 和 Team 用户，以及拥有高级席位或 Chat + Claude Code 席位的 Enterprise 用户。

22* [云环境](#the-cloud-environment)：哪些配置会保留、安装了哪些工具以及如何配置环境22* [云环境](#the-cloud-environment)：哪些配置会保留、安装了哪些工具以及如何配置环境

23* [设置脚本](#setup-scripts)和依赖管理23* [设置脚本](#setup-scripts)和依赖管理

24* [网络访问](#network-access)：级别、代理和默认允许列表24* [网络访问](#network-access)：级别、代理和默认允许列表

~~25* [在网络和终端之间移动任务](#move-tasks-between-web-and-terminal)，使用 `--remote` 和 `--teleport`~~25* [在网络和终端之间移动任务](#move-tasks-between-web-and-terminal)，使用 `--cloud` 和 `--teleport`

26* [处理会话](#work-with-sessions)：审查、共享、归档、删除26* [处理会话](#work-with-sessions)：审查、共享、归档、删除

27* [自动修复拉取请求](#auto-fix-pull-requests)：自动响应 CI 失败和审查评论27* [自动修复拉取请求](#auto-fix-pull-requests)：自动响应 CI 失败和审查评论

28* [安全和隔离](#security-and-isolation)：会话如何隔离28* [安全和隔离](#security-and-isolation)：会话如何隔离

180环境控制[网络访问](#network-access)、环境变量和在会话启动前运行的[设置脚本](#setup-scripts)。有关不需要任何配置即可使用的内容，请参阅[已安装的工具](#installed-tools)。你可以从网络界面或终端管理环境：180环境控制[网络访问](#network-access)、环境变量和在会话启动前运行的[设置脚本](#setup-scripts)。有关不需要任何配置即可使用的内容，请参阅[已安装的工具](#installed-tools)。你可以从网络界面或终端管理环境：

181 181

182| 操作 | 如何操作 |182| 操作 | 如何操作 |

183| :----------------- | :------------------------------------------------------------------------------ |183| :-------------- | :------------------------------------------------------------------------------ |

184| 添加环境 | 选择当前环境以打开选择器，然后选择**添加环境**。对话框包括名称、网络访问级别、环境变量和设置脚本。 |184| 添加环境 | 选择当前环境以打开选择器，然后选择**添加环境**。对话框包括名称、网络访问级别、环境变量和设置脚本。 |

185| 编辑环境 | 选择显示当前环境名称的云图标以打开选择器，悬停在环境上，然后单击右侧出现的设置图标。 |185| 编辑环境 | 选择显示当前环境名称的云图标以打开选择器，悬停在环境上，然后单击右侧出现的设置图标。 |

186| 归档环境 | 打开环境进行编辑并选择**归档**。归档的环境从选择器中隐藏，但现有会话继续运行。 |186| 归档环境 | 打开环境进行编辑并选择**归档**。归档的环境从选择器中隐藏，但现有会话继续运行。 |

188 188

189环境变量使用 `.env` 格式，每行一个 `KEY=value` 对。不要用引号包装值，因为引号会存储为值的一部分。此示例定义了三个变量：189环境变量使用 `.env` 格式，每行一个 `KEY=value` 对。不要用引号包装值，因为引号会存储为值的一部分。此示例定义了三个变量：

190 190

627这些工作流需要[Claude Code CLI](/zh-CN/quickstart)登录到相同的 claude.ai 账户。你可以从终端启动新的云会话，或将云会话拉入终端以在本地继续。云会话即使在关闭笔记本电脑后也会持续，你可以从任何地方（包括 Claude 移动应用）监控它们。627这些工作流需要[Claude Code CLI](/zh-CN/quickstart)登录到相同的 claude.ai 账户。你可以从终端启动新的云会话，或将云会话拉入终端以在本地继续。云会话即使在关闭笔记本电脑后也会持续，你可以从任何地方（包括 Claude 移动应用）监控它们。

628 628

629<Note>629<Note>

630 从 CLI，会话切换是单向的：你可以使用 `--teleport` 将云会话拉入终端，但不能将现有的终端会话推送到网络。`--remote` 标志为你的当前存储库创建一个新的云会话。[Desktop 应用](/zh-CN/desktop#continue-in-another-surface)提供了一个"在...中继续"菜单，可以将本地会话发送到网络。630 从 CLI，会话切换是单向的：你可以使用 `--teleport` 将云会话拉入终端，但不能将现有的终端会话推送到网络。`--cloud` 标志为你的当前存储库创建一个新的云会话。[Desktop 应用](/zh-CN/desktop#continue-in-another-surface)提供了一个"在...中继续"菜单，可以将本地会话发送到网络。

631</Note>631</Note>

632 632

633<h3 id="from-terminal-to-web">633<h3 id="from-terminal-to-web">

634 从终端到网络634 从终端到网络

635</h3>635</h3>

636 636

637使用 `--remote` 标志从命令行启动云会话：637使用 `--cloud` 标志从命令行启动云会话：

638 638

639```bash theme={null}639```bash theme={null}

640claude --remote "Fix the authentication bug in src/auth/login.ts"640claude --cloud "Fix the authentication bug in src/auth/login.ts"

641```641```

642 642

643这在 claude.ai 上创建一个新的云会话。会话克隆你当前目录的 GitHub 远程，位于你的当前分支，所以如果你有本地提交，请先推送，因为 VM 从 GitHub 而不是你的机器克隆。`--remote` 一次只能处理单个存储库。任务在云中运行，而你继续在本地工作。643这在 claude.ai 上创建一个新的云会话。会话克隆你当前目录的 GitHub 远程，位于你的当前分支，所以如果你有本地提交，请先推送，因为 VM 从 GitHub 而不是你的机器克隆。`--cloud` 一次只能处理单个存储库。任务在云中运行，而你继续在本地工作。较旧的 `--remote` 拼写仍然作为 `--cloud` 的已弃用别名工作。

644 644

645{/* min-version: 2.1.195 */}从 v2.1.195 开始，CLI 显示设置步骤的实时清单，例如克隆存储库和运行你的[设置脚本](#setup-scripts)，同时云容器启动。你在容器配置期间输入的消息会被排队，并在会话准备好后发送。645{/* min-version: 2.1.195 */}从 v2.1.195 开始，CLI 显示设置步骤的实时清单，例如克隆存储库和运行你的[设置脚本](#setup-scripts)，同时云容器启动。你在容器配置期间输入的消息会被排队，并在会话准备好后发送。

646 646

647<Note>647<Note>

648 `--remote` 创建云会话。`--remote-control` 无关：它公开本地 CLI 会话以从网络进行监控。请参阅[远程控制](/zh-CN/remote-control)。648 `--cloud` 创建云会话。`--remote-control` 无关：它公开本地 CLI 会话以从网络进行监控。请参阅[Remote Control](/zh-CN/remote-control)。

649</Note>649</Note>

650 650

651在 Claude Code CLI 中使用 `/tasks` 检查进度，或在 claude.ai 或 Claude 移动应用上打开会话以直接交互。从那里你可以引导 Claude、提供反馈或回答问题，就像任何其他对话一样。651在 Claude Code CLI 中使用 `/tasks` 检查进度，或在 claude.ai 或 Claude 移动应用上打开会话以直接交互。从那里你可以引导 Claude、提供反馈或回答问题，就像任何其他对话一样。

663在 Plan Mode 中，Claude 读取文件、运行命令来探索并提出计划，而不编辑源代码。一旦你满意，将计划保存到存储库、提交和推送，以便云 VM 可以克隆它。然后为自主执行启动云会话：663在 Plan Mode 中，Claude 读取文件、运行命令来探索并提出计划，而不编辑源代码。一旦你满意，将计划保存到存储库、提交和推送，以便云 VM 可以克隆它。然后为自主执行启动云会话：

664 664

665```bash theme={null}665```bash theme={null}

666claude --remote "Execute the migration plan in docs/migration-plan.md"666claude --cloud "Execute the migration plan in docs/migration-plan.md"

667```667```

668 668

669这种模式让你可以控制策略，同时让 Claude 在云中自主执行。669这种模式让你可以控制策略，同时让 Claude 在云中自主执行。

670 670

671**在云中使用 ultraplan 规划**：要在网络会话中起草和审查计划本身，请使用[ultraplan](/zh-CN/ultraplan)。Claude 在 Claude Code on the web 上生成计划，而你继续工作，然后你在浏览器中对部分进行评论，并选择远程执行或将计划发送回终端。671**在云中使用 ultraplan 规划**：要在网络会话中起草和审查计划本身，请使用[ultraplan](/zh-CN/ultraplan)。Claude 在 Claude Code on the web 上生成计划，而你继续工作，然后你在浏览器中对部分进行评论，并选择远程执行或将计划发送回终端。

672 672

673**并行运行任务**：每个 `--remote` 命令创建自己的云会话，独立运行。你可以启动多个任务，它们都将在单独的会话中同时运行：673**并行运行任务**：每个 `--cloud` 命令创建自己的云会话，独立运行。你可以启动多个任务，它们都将在单独的会话中同时运行：

674 674

675```bash theme={null}675```bash theme={null}

676claude --remote "Fix the flaky test in auth.spec.ts"676claude --cloud "Fix the flaky test in auth.spec.ts"

677claude --remote "Update the API documentation"677claude --cloud "Update the API documentation"

678claude --remote "Refactor the logger to use structured output"678claude --cloud "Refactor the logger to use structured output"

679```679```

680 680

681使用 Claude Code CLI 中的 `/tasks` 监控所有会话。当会话完成时，你可以从网络界面创建 PR 或[传送](#from-web-to-terminal)会话到终端以继续工作。681使用 Claude Code CLI 中的 `/tasks` 监控所有会话。当会话完成时，你可以从网络界面创建 PR 或[传送](#from-web-to-terminal)会话到终端以继续工作。

684 发送没有 GitHub 的本地存储库684 发送没有 GitHub 的本地存储库

685</h4>685</h4>

686 686

687当你从未连接到 GitHub 的存储库运行 `claude --remote` 时，Claude Code 会捆绑你的本地存储库并直接上传到云会话。捆绑包包括你的完整存储库历史，跨所有分支，加上对跟踪文件的任何未提交更改。687当你从未连接到 GitHub 的存储库运行 `claude --cloud` 时，Claude Code 会捆绑你的本地存储库并直接上传到云会话。捆绑包包括你的完整存储库历史，跨所有分支，加上对跟踪文件的任何未提交更改。

688 688

689当 GitHub 访问不可用时，此回退会自动激活。要即使在 GitHub 已连接时也强制它，请设置 `CCR_FORCE_BUNDLE=1`：689当 GitHub 访问不可用时，此回退会自动激活。要即使在 GitHub 已连接时也强制它，请设置 `CCR_FORCE_BUNDLE=1`：

690 690

691```bash theme={null}691```bash theme={null}

692CCR_FORCE_BUNDLE=1 claude --remote "Run the test suite and fix any failures"692CCR_FORCE_BUNDLE=1 claude --cloud "Run the test suite and fix any failures"

693```693```

694 694

695捆绑的存储库必须满足这些限制：695捆绑的存储库必须满足这些限制：

731 `--teleport` 不可用731 `--teleport` 不可用

732</h4>732</h4>

733 733

734传送需要 claude.ai 订阅身份验证。如果你通过 API 密钥、Bedrock、Vertex AI 或 Microsoft Foundry 进行身份验证，请运行 `/login` 以改为使用你的 claude.ai 账户登录。如果你已通过 claude.ai 登录，`--teleport` 仍不可用，你的组织可能已禁用云会话。734传送需要 claude.ai 订阅身份验证。如果你通过 API 密钥、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 进行身份验证，请运行 `/login` 以改为使用你的 claude.ai 账户登录。如果你已通过 claude.ai 登录，`--teleport` 仍不可用，你的组织可能已禁用云会话。

735 735

736<h2 id="work-with-sessions">736<h2 id="work-with-sessions">

737 处理会话737 处理会话

743 管理上下文743 管理上下文

744</h3>744</h3>

745 745

746云会话支持产生文本输出的[内置命令](/zh-CN/commands)。打开交互式终端选择器的命令，如 `/model` 或 `/config`，不可用。746云会话支持产生文本输出的[内置命令](/zh-CN/commands)。仅在终端界面中运行的命令，如 `/plugin` 或 `/resume`，不可用。{/* min-version: 2.1.205 */}}`/model`、`/effort`、`/fast`、`/color` 和 `/rename` 与值一起作为参数工作，例如 `/model sonnet`，而不是打开终端选择器或滑块；参数形式需要会话环境中的 Claude Code v2.1.205 或更高版本，并遵循每个命令的[可用性说明](/zh-CN/commands#all-commands)，因此当模型的[启动默认工作量保持](/zh-CN/model-config#adjust-effort-level)生效时 `/effort` 报告 `Not applied`，而 `/fast` 仅在以快速模式启动的会话中工作。`/config` 在你传递 `key=value` 时设置一个设置。

747 747

748对于上下文管理特别是：748对于上下文管理特别是：

749 749

claude-platform-on-aws.md +1 −1

Details

270 270

271`ANTHROPIC_AWS_WORKSPACE_ID` 是必需的，并在每个请求中作为 `anthropic-workspace-id` 标头发送。基础 URL 从 `AWS_REGION` 计算为 `https://aws-external-anthropic.{region}.api.aws`。要直接覆盖 URL，请设置 `ANTHROPIC_AWS_BASE_URL`。271`ANTHROPIC_AWS_WORKSPACE_ID` 是必需的，并在每个请求中作为 `anthropic-workspace-id` 标头发送。基础 URL 从 `AWS_REGION` 计算为 `https://aws-external-anthropic.{region}.api.aws`。要直接覆盖 URL，请设置 `ANTHROPIC_AWS_BASE_URL`。

272 272

273即使您的环境中存在 AWS 凭证，AWS 上的 Claude Platform 也是可选的。Bedrock 和 Foundry 在提供程序路由中优先，因此如果设置了 `CLAUDE_CODE_USE_BEDROCK` 和 `CLAUDE_CODE_USE_FOUNDRY`，请取消设置它们。273即使您的环境中存在 AWS 凭证，AWS 上的 Claude Platform 也是可选的。Amazon Bedrock 和 Microsoft Foundry 在提供程序路由中优先，因此如果设置了 `CLAUDE_CODE_USE_BEDROCK` 和 `CLAUDE_CODE_USE_FOUNDRY`，请取消设置它们。

274 274

275<h3 id="3-pin-model-versions">275<h3 id="3-pin-model-versions">

276 3. 固定模型版本276 3. 固定模型版本

cli-reference.md +9 −6

Details

25| `claude gateway` | 启动自托管 [Claude apps gateway](/zh-CN/claude-apps-gateway) 服务器，供在 Bedrock、Vertex AI 或 Foundry 上部署 SSO 和策略在 Claude Code 前面的管理员使用。需要 `--config` 指向 [`gateway.yaml`](/zh-CN/claude-apps-gateway-config)。在 Claude Code v2.1.195 及更高版本中可用。 | `claude gateway --config gateway.yaml` |25| `claude gateway` | 启动自托管 [Claude apps gateway](/zh-CN/claude-apps-gateway) 服务器，供在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上部署 SSO 和策略在 Claude Code 前面的管理员使用。需要 `--config` 指向 [`gateway.yaml`](/zh-CN/claude-apps-gateway-config)。在 Claude Code v2.1.195 及更高版本中可用。 | `claude gateway --config gateway.yaml` |

27| `claude auth login` | 登录您的 Anthropic 账户。使用 `--email` 预填充您的电子邮件地址，使用 `--sso` 强制 SSO 身份验证，使用 `--console` 使用 Anthropic Console 登录以进行 API 使用计费而不是 Claude 订阅 | `claude auth login --console` |27| `claude auth login` | 登录您的 Anthropic 账户。使用 `--email` 预填充您的电子邮件地址，使用 `--sso` 强制 SSO 身份验证，使用 `--console` 使用 Anthropic Console 登录以进行 API 使用计费而不是 Claude 订阅 | `claude auth login --console` |

32| `claude auto-mode defaults` | 以 JSON 格式打印内置 [auto mode](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分类器规则。使用 `claude auto-mode config` 查看应用了设置的有效配置 | `claude auto-mode defaults > rules.json` |32| `claude auto-mode defaults` | 以 JSON 格式打印内置 [auto mode](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分类器规则。使用 `claude auto-mode config` 查看应用了设置的有效配置 | `claude auto-mode defaults > rules.json` |

34| `claude daemon stop --any` | 停止后台会话 [supervisor](/zh-CN/agent-view#the-supervisor-process) 及其托管的会话。传递 `--keep-workers` 以保持后台会话运行，以便下一个 supervisor 重新连接到它们。`--any` 确认停止按需 supervisor，这是默认值。使用此命令从 [无响应的 supervisor](/zh-CN/agent-view#agent-view-says-the-background-service-did-not-respond) 恢复 | `claude daemon stop --any --keep-workers` |34| `claude daemon stop --any` | 停止后台会话 [supervisor](/zh-CN/agent-view#the-supervisor-process) 及其托管的会话。传递 `--keep-workers` 以保持后台会话运行，以便下一个 supervisor 重新连接到它们。`--any` 确认停止按需 supervisor，这是默认值。使用此命令从 [无响应的 supervisor](/zh-CN/agent-view#agent-view-says-the-background-service-did-not-respond) 恢复 | `claude daemon stop --any --keep-workers` |

35| `claude doctor` | 从终端打印只读安装和设置诊断，无需启动会话，包括安装健康状况、设置文件验证错误和远程控制资格。对于可以应用修复的会话内设置检查，请运行 [`/doctor`](/zh-CN/commands#all-commands) | `claude doctor` |

37| `claude mcp login <name>` | {/* min-version: 2.1.186 */}运行配置的 MCP 服务器的 OAuth 流程而不打开交互式 `/mcp` 面板。适用于 HTTP、SSE 和 claude.ai 连接器服务器。在 SSH 上添加 `--no-browser` 以打印授权 URL 而不是打开浏览器，然后在提示处粘贴重定向 URL。需要 Claude Code v2.1.186 或更高版本。请参阅 [从命令行进行身份验证](/zh-CN/mcp#authenticate-from-the-command-line) | `claude mcp login sentry` |38| `claude mcp login <name>` | {/* min-version: 2.1.186 */}运行配置的 MCP 服务器的 OAuth 流程而不打开交互式 `/mcp` 面板。适用于 HTTP、SSE 和 claude.ai 连接器服务器。在 SSH 上添加 `--no-browser` 以打印授权 URL 而不是打开浏览器，然后在提示处粘贴重定向 URL。需要 Claude Code v2.1.186 或更高版本。请参阅 [从命令行进行身份验证](/zh-CN/mcp#authenticate-from-the-command-line) | `claude mcp login sentry` |

63| `--agents` | 通过 JSON 动态定义自定义 subagents。使用与 subagent [frontmatter](/zh-CN/sub-agents#supported-frontmatter-fields) 相同的字段名称，加上代理指令的 `prompt` 字段 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |64| `--agents` | 通过 JSON 动态定义自定义 subagents。使用与 subagent [frontmatter](/zh-CN/sub-agents#supported-frontmatter-fields) 相同的字段名称，加上代理指令的 `prompt` 字段 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |

64| `--allow-dangerously-skip-permissions` | 将 `bypassPermissions` 添加到 `Shift+Tab` 模式循环中而不启动它。允许您以不同的模式（如 `plan`）开始，稍后切换到 `bypassPermissions`。请参阅 [权限模式](/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |65| `--allow-dangerously-skip-permissions` | 将 `bypassPermissions` 添加到 `Shift+Tab` 模式循环中而不启动它。允许您以不同的模式（如 `plan`）开始，稍后切换到 `bypassPermissions`。请参阅 [权限模式](/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |

65| `--allowedTools`, `--allowed-tools` | 无需提示权限即可执行的工具。请参阅 [权限规则语法](/zh-CN/settings#permission-rule-syntax) 了解模式匹配。要限制哪些工具可用，请改用 `--tools` | `"Bash(git log *)" "Bash(git diff *)" "Read"` |66| `--allowedTools`, `--allowed-tools` | 无需提示权限即可执行的工具。请参阅 [权限规则语法](/zh-CN/settings#permission-rule-syntax) 了解模式匹配。要限制哪些工具可用，请改用 `--tools` | `"Bash(git log *)" "Bash(git diff *)" "Read"` |

67| `--append-subagent-system-prompt` | {/* min-version: 2.1.205 */}将自定义文本附加到每个 [subagent](/zh-CN/sub-agents) 的系统提示末尾，包括嵌套的 subagents。仅在非交互模式下与 `-p` 一起应用。需要 Claude Code v2.1.205 或更高版本 | `claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"` |

68| `--ax-screen-reader` | {/* min-version: 2.1.181 */}渲染屏幕阅读器友好的输出：没有装饰性边框或动画的平面文本。强制使用经典渲染器，因此 [`tui`](/zh-CN/settings#available-settings) 设置在会话期间无效。优先于 [`CLAUDE_AX_SCREEN_READER`](/zh-CN/env-vars) 和 [`axScreenReader`](/zh-CN/settings#available-settings) 设置。需要 Claude Code v2.1.181 或更高版本 | `claude --ax-screen-reader` |70| `--ax-screen-reader` | {/* min-version: 2.1.181 */}渲染屏幕阅读器友好的输出：没有装饰性边框或动画的平面文本。强制使用经典渲染器，因此 [`tui`](/zh-CN/settings#available-settings) 设置在会话期间无效。优先于 [`CLAUDE_AX_SCREEN_READER`](/zh-CN/env-vars) 和 [`axScreenReader`](/zh-CN/settings#available-settings) 设置。需要 Claude Code v2.1.181 或更高版本 | `claude --ax-screen-reader` |

71| `--bg`, `--background` | 启动会话作为 [后台代理](/zh-CN/agent-view) 并立即返回。打印会话 ID 和管理命令。与 `--exec` 结合以作为后台作业运行 shell 命令而不是 Claude 会话，或与 `--agent` 结合以运行特定的 subagent。{/* min-version: 2.1.198 */}不能与 `-p`/`--print` 结合；请参阅 [错误参考](/zh-CN/errors#command-line-errors) | `claude --bg "investigate the flaky test"` |73| `--bg`, `--background` | 启动会话作为 [后台代理](/zh-CN/agent-view) 并立即返回。打印会话 ID 和管理命令。与 `--exec` 结合以作为后台作业运行 shell 命令而不是 Claude 会话，或与 `--agent` 结合以运行特定的 subagent。{/* min-version: 2.1.198 */}不能与 `-p`/`--print` 结合；请参阅 [错误参考](/zh-CN/errors#command-line-errors) | `claude --bg "investigate the flaky test"` |

72| `--channels` | （研究预览）MCP 服务器，其 [channel](/zh-CN/channels) 通知 Claude 应在此会话中侦听。以空格分隔的 `plugin:<name>@<marketplace>` 条目列表。需要 Claude.ai 身份验证 | `claude --channels plugin:my-notifier@my-marketplace` |74| `--channels` | （研究预览）MCP 服务器，其 [channel](/zh-CN/channels) 通知 Claude 应在此会话中侦听。以空格分隔的 `plugin:<name>@<marketplace>` 条目列表。需要 Claude.ai 身份验证 | `claude --channels plugin:my-notifier@my-marketplace` |

76| `--cloud` | 在 claude.ai 上创建新的 [网络会话](/zh-CN/claude-code-on-the-web)，提供任务描述 | `claude --cloud "Fix the login bug"` |

75| `--dangerously-load-development-channels` | 启用不在批准的允许列表中的 [channels](/zh-CN/channels-reference#test-during-the-research-preview)，用于本地开发。接受 `plugin:<name>@<marketplace>` 和 `server:<name>` 条目。提示确认 | `claude --dangerously-load-development-channels server:webhook` |78| `--dangerously-load-development-channels` | 启用不在批准的允许列表中的 [channels](/zh-CN/channels-reference#test-during-the-research-preview)，用于本地开发。接受 `plugin:<name>@<marketplace>` 和 `server:<name>` 条目。提示确认 | `claude --dangerously-load-development-channels server:webhook` |

76| `--dangerously-skip-permissions` | 跳过权限提示。等同于 `--permission-mode bypassPermissions`。请参阅 [权限模式](/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode) 了解此操作跳过和不跳过的内容 | `claude --dangerously-skip-permissions` |79| `--dangerously-skip-permissions` | 跳过权限提示。等同于 `--permission-mode bypassPermissions`。请参阅 [权限模式](/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode) 了解此操作跳过和不跳过的内容 | `claude --dangerously-skip-permissions` |

80| `--disallowedTools`, `--disallowed-tools` | 拒绝规则。裸工具名称从模型的上下文中删除匹配的工具：`"Edit"` 删除 Edit，`"*"` 删除每个工具，`"mcp__*"` 删除每个 MCP 工具。作用域规则（如 `Bash(rm *)` ）使工具保持可用，仅拒绝匹配的调用 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |83| `--disallowedTools`, `--disallowed-tools` | 拒绝规则。裸工具名称从模型的上下文中删除匹配的工具：`"Edit"` 删除 Edit，`"*"` 删除每个工具，`"mcp__*"` 删除每个 MCP 工具。作用域规则（如 `Bash(rm *)` ）使工具保持可用，仅拒绝匹配的调用 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |

81| `--effort` | 为当前会话设置 [工作量级别](/zh-CN/model-config#adjust-effort-level)。选项：`low`、`medium`、`high`、`xhigh`、`max`；可用级别取决于模型。覆盖此会话的 [`effortLevel`](/zh-CN/settings#available-settings) 设置，不会持久化 | `claude --effort high` |84| `--effort` | 为当前会话设置 [工作量级别](/zh-CN/model-config#adjust-effort-level)。选项：`low`、`medium`、`high`、`xhigh`、`max` 或 {/* min-version: 2.1.203 */}}`ultracode`。可用级别取决于模型。`ultracode` 以 `xhigh` 工作量启动会话，并启用 [ultracode](/zh-CN/workflows#let-claude-decide-with-ultracode)，需要 Claude Code v2.1.203 或更高版本。覆盖此会话的 [`effortLevel`](/zh-CN/settings#available-settings) 设置，不会持久化 | `claude --effort high` |

82| `--enable-auto-mode` | {/* max-version: 2.1.110 */}在 v2.1.111 中移除。Auto mode 现在默认在 `Shift+Tab` 循环中；使用 `--permission-mode auto` 以它开始 | `claude --permission-mode auto` |85| `--enable-auto-mode` | {/* max-version: 2.1.110 */}在 v2.1.111 中移除。Auto mode 现在默认在 `Shift+Tab` 循环中；使用 `--permission-mode auto` 以它开始 | `claude --permission-mode auto` |

83| `--exclude-dynamic-system-prompt-sections` | 将每台机器的部分从系统提示（工作目录、环境信息、内存路径、git 状态）移到第一条用户消息中。改进在运行相同任务的不同用户和机器之间的提示缓存重用。仅适用于默认系统提示；当设置 `--system-prompt` 或 `--system-prompt-file` 时忽略。与 `-p` 一起用于脚本化的多用户工作负载 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |86| `--exclude-dynamic-system-prompt-sections` | 将每台机器的部分从系统提示（工作目录、环境信息、内存路径、git 状态）移到第一条用户消息中。改进在运行相同任务的不同用户和机器之间的提示缓存重用。仅适用于默认系统提示；当设置 `--system-prompt` 或 `--system-prompt-file` 时忽略。与 `-p` 一起用于脚本化的多用户工作负载 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |

92| `--include-partial-messages` | 在输出中包含部分流事件。需要 `--print` 和 `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-partial-messages "query"` |95| `--include-partial-messages` | 在输出中包含部分流事件。需要 `--print` 和 `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-partial-messages "query"` |

94| `--json-schema` | 在代理完成其工作流后获得与 JSON Schema 匹配的验证 JSON 输出（仅打印模式，请参阅 [结构化输出](/zh-CN/agent-sdk/structured-outputs)） | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |97| `--json-schema` | 在代理完成其工作流后获得与 JSON Schema 匹配的验证 JSON 输出（仅打印模式）。请参阅 [结构化输出](/zh-CN/agent-sdk/structured-outputs)。{/* min-version: 2.1.205 */}Claude Code 在无效的 schema 上以错误退出，并接受 `format` 关键字作为注释而无需客户端验证。在 v2.1.205 之前，无效的 schema 产生无结构的输出且没有错误，使用 `format` 的 schemas 被视为无效 | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |

97| `--max-turns` | 限制代理转数（仅打印模式）。达到限制时以错误退出。默认无限制 | `claude -p --max-turns 3 "query"` |100| `--max-turns` | 限制代理转数（仅打印模式）。达到限制时以错误退出。默认无限制。{/* min-version: 2.1.205 */}使用 `--input-format stream-json` 时，在 Claude 工作时发送的消息保持排队，并在限制结束当前转时作为其自己的转运行，具有其自己的限制。在 v2.1.205 之前，Claude Code 丢弃该消息 | `claude -p --max-turns 3 "query"` |

99| `--model` | 为当前会话设置模型，使用最新模型的别名（`sonnet`、`opus`、`haiku` 或 `fable`）或模型的完整名称。覆盖 [`model`](/zh-CN/settings#available-settings) 设置和 [`ANTHROPIC_MODEL`](/zh-CN/model-config#environment-variables) | `claude --model claude-sonnet-5` |102| `--model` | 为当前会话设置模型，使用最新模型的别名（`sonnet`、`opus`、`haiku` 或 `fable`）或模型的完整名称。覆盖 [`model`](/zh-CN/settings#available-settings) 设置和 [`ANTHROPIC_MODEL`](/zh-CN/model-config#environment-variables) | `claude --model claude-sonnet-5` |

100| `--name`, `-n` | 为会话设置显示名称，显示在 `/resume` 和终端标题中。您可以使用 `claude --resume <name>` 恢复命名会话。<br /><br />[`/rename`](/zh-CN/commands) 在会话中更改名称，也会在提示栏中显示 | `claude -n "my-feature-work"` |103| `--name`, `-n` | 为会话设置显示名称，显示在 `/resume` 和终端标题中。您可以使用 `claude --resume <name>` 恢复命名会话。<br /><br />[`/rename`](/zh-CN/commands) 在会话中更改名称，也会在提示栏中显示 | `claude -n "my-feature-work"` |

102| `--no-session-persistence` | 禁用会话持久化，以便会话不会保存到磁盘且无法恢复。仅打印模式。[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-CN/env-vars) 环境变量在任何模式下都做同样的事情 | `claude -p --no-session-persistence "query"` |105| `--no-session-persistence` | 禁用会话持久化，以便会话不会保存到磁盘且无法恢复。仅打印模式。[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-CN/env-vars) 环境变量在任何模式下都做同样的事情 | `claude -p --no-session-persistence "query"` |

104| `--permission-mode` | 以指定的 [权限模式](/zh-CN/permission-modes) 开始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk` 或 `bypassPermissions`。覆盖设置文件中的 `defaultMode` | `claude --permission-mode plan` |107| `--permission-mode` | 以指定的 [权限模式](/zh-CN/permission-modes) 开始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 或 {/* min-version: 2.1.200 */}}`manual` 作为 `default` 的别名。`manual` 别名选择 UI 标记为"手动"的模式，需要 Claude Code v2.1.200 或更高版本；`claude --help` 用它代替 `default` 列出它，两个值都有效。覆盖设置文件中的 `defaultMode` | `claude --permission-mode plan` |

105| `--permission-prompt-tool` | 指定 MCP 工具以在非交互模式下处理权限提示。{/* min-version: 2.1.199 */}截至 v2.1.199，提示工具无法批准标记为 [需要用户交互](/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具：一个的 `allow` 结果被转换为拒绝 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |108| `--permission-prompt-tool` | 指定 MCP 工具以在非交互模式下处理权限提示。{/* min-version: 2.1.199 */}截至 v2.1.199，提示工具无法批准标记为 [需要用户交互](/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具：一个的 `allow` 结果被转换为拒绝 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

109| `--prompt-suggestions` | 在每轮后发出 `prompt_suggestion` 消息，带有预测的下一个用户提示。需要 `--print`、`--output-format stream-json` 和 `--verbose`。请参阅 [提示建议](/zh-CN/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |112| `--prompt-suggestions` | 在每轮后发出 `prompt_suggestion` 消息，带有预测的下一个用户提示。需要 `--print`、`--output-format stream-json` 和 `--verbose`。请参阅 [提示建议](/zh-CN/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |

111| `--remote-control`, `--rc` | 启动启用了 [Remote Control](/zh-CN/remote-control#start-a-remote-control-session) 的交互式会话，以便您也可以从 claude.ai 或 Claude 应用控制它。可选地为会话传递名称 | `claude --remote-control "My Project"` |114| `--remote-control`, `--rc` | 启动启用了 [Remote Control](/zh-CN/remote-control#start-a-remote-control-session) 的交互式会话，以便您也可以从 claude.ai 或 Claude 应用控制它。可选地为会话传递名称 | `claude --remote-control "My Project"` |

112| `--remote-control-session-name-prefix <prefix>` | 当未设置显式名称时，[Remote Control](/zh-CN/remote-control) 自动生成会话名称的前缀。默认为您的机器的主机名，生成名称如 `myhost-graceful-unicorn`。设置 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以获得相同效果 | `claude remote-control --remote-control-session-name-prefix dev-box` |115| `--remote-control-session-name-prefix <prefix>` | 当未设置显式名称时，[Remote Control](/zh-CN/remote-control) 自动生成会话名称的前缀。默认为您的机器的主机名，生成名称如 `myhost-graceful-unicorn`。设置 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以获得相同效果 | `claude remote-control --remote-control-session-name-prefix dev-box` |

113| `--replay-user-messages` | 从 stdin 重新发出用户消息到 stdout 以进行确认。需要 `--input-format stream-json` 和 `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |116| `--replay-user-messages` | 从 stdin 重新发出用户消息到 stdout 以进行确认。需要 `--input-format stream-json` 和 `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |

code-review.md +1 −1

Details

270 270

271在任何模式下，注释 `@claude review` [选择 PR 进入推送触发审查](#manually-trigger-reviews)，因此在该注释后每次推送都会产生额外成本。要运行单次审查而不订阅未来推送，请改为注释 `@claude review once`。271在任何模式下，注释 `@claude review` [选择 PR 进入推送触发审查](#manually-trigger-reviews)，因此在该注释后每次推送都会产生额外成本。要运行单次审查而不订阅未来推送，请改为注释 `@claude review once`。

272 272

273无论您的组织是否为其他 Claude Code 功能使用 Amazon Bedrock 或 Google Vertex AI，成本都会出现在您的 Anthropic 账单上。要为 Code Review 设置每月支出上限，请转到 [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage) 并为 Claude Code Review 服务配置限制。273无论您的组织是否为其他 Claude Code 功能使用 Amazon Bedrock 或 Google Cloud 的 Agent Platform，成本都会出现在您的 Anthropic 账单上。要为 Code Review 设置每月支出上限，请转到 [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage) 并为 Claude Code Review 服务配置限制。

274 274

275通过[分析](#view-usage)中的每周成本图表或管理员设置中的每个存储库平均成本列监控支出。275通过[分析](#view-usage)中的每周成本图表或管理员设置中的每个存储库平均成本列监控支出。

276 276

commands.md +15 −15

Details

24 24

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

26 26

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

28 28

29**在会话之间。** `/clear` 在保持项目内存的同时开始新任务。`/resume` 和 `/branch` 让您返回或分叉早期的对话。`/teleport` 将网络会话拉入此终端，`/remote-control` 让您从另一台设备继续此本地会话。29**在会话之间。** `/clear` 在保持项目内存的同时开始新任务。`/resume` 和 `/branch` 让您返回或分叉早期的对话。`/teleport` 将网络会话拉入此终端，`/remote-control` 让您从另一台设备继续此本地会话。

30 30

31**当出现问题时。** `/rewind` 将代码和对话回滚到检查点，或总结对话的一部分。`/doctor` 和 `/debug` 诊断安装和运行时问题，`/feedback` 报告附加会话上下文的错误。31**当出现问题时。** `/rewind` 将代码和对话回滚到检查点，或总结对话的一部分。`/doctor` 运行设置检查以诊断安装和配置问题，并可以修复它们，`/debug` 诊断运行时问题，`/feedback` 报告附加会话上下文的错误。

32 32

33<h2 id="all-commands">33<h2 id="all-commands">

34 所有命令34 所有命令

48</Note>48</Note>

49 49

50| 命令 | 用途 |50| 命令 | 用途 |

51| :--------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |51| :--------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

52| `/add-dir <path>` | 为当前会话期间的文件访问添加工作目录。大多数 `.claude/` 配置[不会从添加的目录中发现](/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍后使用 `--continue` 或 `--resume` 从添加的目录恢复会话 |52| `/add-dir <path>` | 为当前会话期间的文件访问添加工作目录。大多数 `.claude/` 配置[不会从添加的目录中发现](/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍后使用 `--continue` 或 `--resume` 从添加的目录恢复会话 |

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

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

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

63| `/clear [name]` | 使用空上下文启动新对话。之前的对话在 `/resume` 中保持可用。传递一个名称以在 `/resume` 选择器中标记之前的对话。要在继续同一对话的同时释放上下文，请改用 `/compact`。别名：`/reset`、`/new` |63| `/clear [name]` | 使用空上下文启动新对话。之前的对话在 `/resume` 中保持可用。传递一个名称以在 `/resume` 选择器中标记之前的对话。要在继续同一对话的同时释放上下文，请改用 `/compact`。别名：`/reset`、`/new` |

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

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

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

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

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

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

78| `/doctor` | 诊断并验证您的 Claude Code 安装和设置。结果显示状态图标。按 `f` 让 Claude 修复任何报告的问题 |78| `/doctor` | **[Skill](/zh-CN/skills#bundled-skills).** 运行设置检查以诊断问题并可以修复它们。检查安装健康状况，包括重复或遗留安装、`PATH` 问题和无法解析的设置文件。查找未使用的 skills、MCP servers 和 plugins 与其上下文成本，针对已检入的文件去重本地 `CLAUDE.md` 文件，将始终加载的指导迁移到 [skills](/zh-CN/skills) 和按需加载的嵌套 `CLAUDE.md` 文件，标记缓慢的 [hooks](/zh-CN/hooks)，并检查是否有更新版本。还提供将 [auto mode](/zh-CN/permissions#permission-modes) 设置为默认值的选项，以及[预先批准](/zh-CN/permissions)经常被拒绝的只读命令。首先报告发现并在更改任何内容之前要求确认。从终端，`claude doctor` 打印只读安装诊断而不启动会话。别名：`/checkup`。{/* min-version: 2.1.205 */}在 v2.1.205 之前，`/doctor` 打开只读诊断屏幕，按 `f` 将报告发送给 Claude |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

147| `/usage-credits` | 配置使用额度以在达到限制时继续工作。之前为 `/extra-usage` |147| `/usage-credits` | 配置使用额度以在达到限制时继续工作。打开使用额度计费页面在您的浏览器中。{/* min-version: 2.1.205 */}当没有浏览器可以打开时，例如通过 SSH，该命令改为打印要访问的 URL；这需要 Claude Code v2.1.205 或更高版本，早期版本在这种情况下没有显示任何内容。之前为 `/extra-usage` |

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

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

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

common-workflows.md +1 −1

Details

255 </Step>255 </Step>

256</Steps>256</Steps>

257 257

258当您使用 `gh pr create` 创建 PR 时，会话会自动链接到该 PR。要稍后返回它，请运行 `claude --from-pr <number>` 或将 PR URL 粘贴到[`/resume` 选择器](/zh-CN/sessions#use-the-session-picker)搜索中。258当您使用 `gh pr create` 创建 PR 时，会话会自动链接到该 PR。要稍后返回它，请运行 `claude --from-pr 123`，将 123 替换为 PR 编号，或将 PR URL 粘贴到[`/resume` 选择器](/zh-CN/sessions#use-the-session-picker)搜索中。

259 259

260<Tip>260<Tip>

261 在提交前审查 Claude 生成的 PR，并要求 Claude 突出显示潜在的风险或注意事项。261 在提交前审查 Claude 生成的 PR，并要求 Claude 突出显示潜在的风险或注意事项。

communications-kit.md +1 −1

Details

275 275

276有时您希望 Claude 在每次编辑之前请求许可。有时您只是希望它发货。您不应该永远选择一个。276有时您希望 Claude 在每次编辑之前请求许可。有时您只是希望它发货。您不应该永远选择一个。

277 277

278*Shift+Tab* 循环通过 Claude 获得多少自由度：*default* 在有风险的东西之前请求，*acceptEdits* 让文件编辑和常见文件系统命令流通，同时仍在其他 shell 命令之前检查，*plan* 在触及任何东西之前为您的批准提议更改。Plan 模式是信任构建者，所以对于任何触及多个文件的东西，从那里开始。278*Shift+Tab* 循环通过 Claude 获得多少自由度：*Manual*（`default` 设置值）在每个操作之前请求，*acceptEdits* 让文件编辑和常见文件系统命令流通，同时仍在其他 shell 命令之前检查，*plan* 在触及任何东西之前为您的批准提议更改。Plan 模式是信任构建者，所以对于任何触及多个文件的东西，从那里开始。

279 279

280*现在尝试：* 在您的下一个重构上，按 Shift+Tab 直到您看到"plan"，然后描述更改。您将在单个文件移动之前获得完整的提议。280*现在尝试：* 在您的下一个重构上，按 Shift+Tab 直到您看到"plan"，然后描述更改。您将在单个文件移动之前获得完整的提议。

281 281

computer-use.md +1 −1

Details

238* 您在 macOS 上。Computer use 在 CLI 中在 Linux 或 Windows 上不可用。在 Windows 上，改用 [Desktop 中的 computer use](/zh-CN/desktop#let-claude-use-your-computer)。238* 您在 macOS 上。Computer use 在 CLI 中在 Linux 或 Windows 上不可用。在 Windows 上，改用 [Desktop 中的 computer use](/zh-CN/desktop#let-claude-use-your-computer)。

239* 您运行的是 Claude Code v2.1.85 或更高版本。运行 `claude --version` 来检查。239* 您运行的是 Claude Code v2.1.85 或更高版本。运行 `claude --version` 来检查。

240* 您在 Pro 或 Max 计划上。运行 `/status` 来确认您的订阅。240* 您在 Pro 或 Max 计划上。运行 `/status` 来确认您的订阅。

241* 您通过 claude.ai 进行身份验证。Computer use 不适用于第三方提供商，如 Amazon Bedrock、Google Cloud Vertex AI 或 Microsoft Foundry。如果您仅通过第三方提供商访问 Claude，您需要单独的 claude.ai 账户来使用此功能。241* 您通过 claude.ai 进行身份验证。Computer use 不适用于第三方提供商，如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。如果您仅通过第三方提供商访问 Claude，您需要单独的 claude.ai 账户来使用此功能。

242* 您在交互式会话中。Computer use 在使用 `-p` 标志的非交互式模式下不可用。242* 您在交互式会话中。Computer use 在使用 `-p` 标志的非交互式模式下不可用。

243 243

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

costs.md +1 −1

Details

51 对于具有自定义速率限制的组织，此工作区中的 Claude Code 流量计入您的组织整体 API 速率限制。您可以在 Claude Console 的此工作区的 Limits 页面上设置[工作区速率限制](https://platform.claude.com/docs/zh-CN/api/rate-limits#setting-lower-limits-for-workspaces)，以限制 Claude Code 的份额并保护其他生产工作负载。51 对于具有自定义速率限制的组织，此工作区中的 Claude Code 流量计入您的组织整体 API 速率限制。您可以在 Claude Console 的此工作区的 Limits 页面上设置[工作区速率限制](https://platform.claude.com/docs/zh-CN/api/rate-limits#setting-lower-limits-for-workspaces)，以限制 Claude Code 的份额并保护其他生产工作负载。

52</Note>52</Note>

53 53

54在 Bedrock、Vertex 和 Foundry 上，Claude Code 不会从您的云中发送指标。自托管的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 提供按用户使用情况归因、带有令牌计数的 OTLP 指标，以及这些提供商上的[按用户支出限制](/zh-CN/claude-apps-gateway-spend-limits)。通过不同 [LLM gateway](/zh-CN/llm-gateway) 路由 Claude Code 的组织可以在网关处跟踪支出，因为网关会看到每个请求。54在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，Claude Code 不会从您的云中发送指标。自托管的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 提供按用户使用情况归因、带有令牌计数的 OTLP 指标，以及这些提供商上的[按用户支出限制](/zh-CN/claude-apps-gateway-spend-limits)。通过不同 [LLM gateway](/zh-CN/llm-gateway) 路由 Claude Code 的组织可以在网关处跟踪支出，因为网关会看到每个请求。

55 55

56<h3 id="rate-limit-recommendations">56<h3 id="rate-limit-recommendations">

57 速率限制建议57 速率限制建议

data-usage.md +8 −8

Details

23 开发者合作伙伴计划23 开发者合作伙伴计划

24</h3>24</h3>

25 25

26如果您明确选择加入通过[开发者合作伙伴计划](https://support.claude.com/en/articles/11174108-about-the-development-partner-program)等方式向我们提供训练材料的方法，我们可能会使用这些提供的材料来训练我们的模型。组织管理员可以明确选择为其组织加入开发者合作伙伴计划。请注意，此计划仅适用于 Anthropic 第一方 API，不适用于 Bedrock 或 Vertex 用户。26如果您明确选择加入通过[开发者合作伙伴计划](https://support.claude.com/en/articles/11174108-about-the-development-partner-program)等方式向我们提供训练材料的方法，我们可能会使用这些提供的材料来训练我们的模型。组织管理员可以明确选择为其组织加入开发者合作伙伴计划。请注意，此计划仅适用于 Anthropic 第一方 API，不适用于 Amazon Bedrock 或 Google Cloud 的 Agent Platform 用户。

27 27

28<h3 id="feedback-using-the-/feedback-command">28<h3 id="feedback-using-the-/feedback-command">

29 使用 `/feedback` 命令的反馈29 使用 `/feedback` 命令的反馈

39 39

40在评分提示之后，您可能会看到一个单独的后续问题，询问"Anthropic 可以查看您的会话记录以帮助我们改进 Claude Code 吗？"。这是一个与评分不同的可选第二步：40在评分提示之后，您可能会看到一个单独的后续问题，询问"Anthropic 可以查看您的会话记录以帮助我们改进 Claude Code 吗？"。这是一个与评分不同的可选第二步：

41 41

42* **是**：将您的对话记录、任何子代理记录和来自磁盘的原始会话日志文件上传到 Anthropic。已知的 API 密钥和令牌模式在上传前被编辑。源代码、文件内容和其他对话内容按原样上传。共享的记录保留最多 6 个月。在 Bedrock、Vertex AI、Foundry 和已登录的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话上，"是"会将相同的有效负载写入 `~/.claude/feedback-bundles/` 下的本地存档，而不是上传；在您转发该文件之前，没有任何内容离开您的计算机。42* **是**：将您的对话记录、任何子代理记录和来自磁盘的原始会话日志文件上传到 Anthropic。已知的 API 密钥和令牌模式在上传前被编辑。源代码、文件内容和其他对话内容按原样上传。共享的记录保留最多 6 个月。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登录的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话上，"是"会将相同的有效负载写入 `~/.claude/feedback-bundles/` 下的本地存档，而不是上传；在您转发该文件之前，没有任何内容离开您的计算机。

43* **否**：拒绝而不发送任何内容43* **否**：拒绝而不发送任何内容

44* **不再询问**：拒绝并停止此后续在未来会话中出现44* **不再询问**：拒绝并停止此后续在未来会话中出现

45 45

90静止时的加密取决于您的模型提供商：90静止时的加密取决于您的模型提供商：

91 91

92| 提供商 | 静止时加密 |92| 提供商 | 静止时加密 |

~~93| ---------------------- | ------------------------------------------------------------------------------------- |~~93| ----------------------------- | ------------------------------------------------------------------------------------- |

94| Anthropic API | 基础设施级磁盘加密 (AES-256)。启用 [Zero Data Retention](/zh-CN/zero-data-retention) 以实现无服务器端持久化。 |94| Anthropic API | 基础设施级磁盘加密 (AES-256)。启用 [Zero Data Retention](/zh-CN/zero-data-retention) 以实现无服务器端持久化。 |

95| Amazon Bedrock | AES-256，使用 AWS 管理的密钥。可通过 AWS KMS 获得客户管理的密钥。 |95| Amazon Bedrock | AES-256，使用 AWS 管理的密钥。可通过 AWS KMS 获得客户管理的密钥。 |

~~96| Google Cloud Vertex AI | Google 管理的加密密钥。CMEK 可用。 |~~96| Google Cloud 的 Agent Platform | Google 管理的加密密钥。CMEK 可用。 |

97| Microsoft Foundry | 请求路由到 Anthropic 基础设施，使用 AES-256 磁盘加密。 |97| Microsoft Foundry | 请求路由到 Anthropic 基础设施，使用 AES-256 磁盘加密。 |

98 98

99Claude Code 基于 Anthropic 的 API 构建。有关 API 安全控制的详情，包括 API 日志记录程序，请参阅 [Anthropic 信任中心](https://trust.anthropic.com)中的合规工件。99Claude Code 基于 Anthropic 的 API 构建。有关 API 安全控制的详情，包括 API 日志记录程序，请参阅 [Anthropic 信任中心](https://trust.anthropic.com)中的合规工件。

121 121

122当您运行 `/feedback` 命令时，您的对话历史记录（包括代码）的副本被发送到 Anthropic。在提交之前，您可以选择包含多少历史记录：仅当前会话（这是默认设置），或者也包括来自同一项目在过去 24 小时或 7 天内的其他会话。数据通过 TLS 在传输中加密并存储在 Google Cloud Storage 中，Google Cloud Storage 默认对静止数据进行加密。可选地，在公共存储库中创建 GitHub 问题。要选择退出，请将 `DISABLE_FEEDBACK_COMMAND` 环境变量设置为 `1`。122当您运行 `/feedback` 命令时，您的对话历史记录（包括代码）的副本被发送到 Anthropic。在提交之前，您可以选择包含多少历史记录：仅当前会话（这是默认设置），或者也包括来自同一项目在过去 24 小时或 7 天内的其他会话。数据通过 TLS 在传输中加密并存储在 Google Cloud Storage 中，Google Cloud Storage 默认对静止数据进行加密。可选地，在公共存储库中创建 GitHub 问题。要选择退出，请将 `DISABLE_FEEDBACK_COMMAND` 环境变量设置为 `1`。

123 123

124当您使用第三方提供商（如 Bedrock 或 Vertex）或未配置 Anthropic 凭据时，`/feedback` 会将报告写入 `~/.claude/feedback-bundles/` 下的本地存档，而不是将其发送到 Anthropic。已知的 API 密钥和令牌模式在写入存档之前被编辑。在您将该文件发送给您的 Anthropic 账户代表或将其附加到支持请求之前，没有任何内容离开您的机器。124当您使用第三方提供商（如 Amazon Bedrock 或 Google Cloud 的 Agent Platform），或未配置 Anthropic 凭据时，`/feedback` 会将报告写入 `~/.claude/feedback-bundles/` 下的本地存档，而不是将其发送到 Anthropic。已知的 API 密钥和令牌模式在写入存档之前被编辑。在您将该文件发送给您的 Anthropic 账户代表或将其附加到支持请求之前，没有任何内容离开您的机器。

125 125

126<h2 id="default-behaviors-by-api-provider">126<h2 id="default-behaviors-by-api-provider">

127 按 API 提供商的默认行为127 按 API 提供商的默认行为

128</h2>128</h2>

129 129

130默认情况下，当使用 Bedrock、Vertex、Foundry 或 Claude Platform on AWS 时，错误报告、遥测和错误报告被禁用。会话质量调查和 WebFetch 域安全检查是例外，无论提供商如何都会运行。在已登录的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话上，使用分析、错误报告和向 Anthropic 的调查评分由网关凭证本身禁用，没有重新启用的设置。您可以通过设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 一次选择退出所有非必需的流量，包括调查。此变量不影响 WebFetch 检查，它有自己的选择退出选项。以下是完整的默认行为：130默认情况下，当使用 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 时，错误报告、遥测和错误报告被禁用。会话质量调查和 WebFetch 域安全检查是例外，无论提供商如何都会运行。在已登录的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话上，使用分析、错误报告和向 Anthropic 的调查评分由网关凭证本身禁用，没有重新启用的设置。您可以通过设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 一次选择退出所有非必需的流量，包括调查。此变量不影响 WebFetch 检查，它有自己的选择退出选项。以下是完整的默认行为：

131 131

133| ------------------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |133| ------------------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |

139 139

140所有环境变量都可以检查到 `settings.json`（请参阅 [settings 参考](/zh-CN/settings)）。140所有环境变量都可以检查到 `settings.json`（请参阅 [settings 参考](/zh-CN/settings)）。

141 141

142从 v2.1.126 开始，当主机平台设置 `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` 时，Vertex、Bedrock 和 Foundry 的指标默认开启，并遵循标准的 `DISABLE_TELEMETRY` 选择退出。Sentry 错误报告和 `/feedback` 报告在这些提供商上仍然默认关闭。142从 v2.1.126 开始，当主机平台设置 `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` 时，Google Cloud 的 Agent Platform、Amazon Bedrock 和 Microsoft Foundry 的指标默认开启，并遵循标准的 `DISABLE_TELEMETRY` 选择退出。Sentry 错误报告和 `/feedback` 报告在这些提供商上仍然默认关闭。

143 143

144<h3 id="webfetch-domain-safety-check">144<h3 id="webfetch-domain-safety-check">

145 WebFetch 域安全检查145 WebFetch 域安全检查

debug-your-config.md +11 −5

Details

19对于特定类别的详细信息，请使用专用命令：19对于特定类别的详细信息，请使用专用命令：

20 20

21| 命令 | 显示内容 |21| 命令 | 显示内容 |

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

23| `/memory` | 加载了哪些 `CLAUDE.md` 和规则文件，加上自动内存条目 |23| `/memory` | 加载了哪些 `CLAUDE.md` 和规则文件，加上自动内存条目 |

24| `/skills` | 来自项目、用户和插件源的可用 skills |24| `/skills` | 来自项目、用户和插件源的可用 skills |

25| `/hooks` | 活跃的 hook 配置 |25| `/hooks` | 活跃的 hook 配置 |

26| `/mcp` | 连接的 MCP 服务器及其状态 |26| `/mcp` | 连接的 MCP 服务器及其状态 |

27| `/permissions` | 当前生效的已解析允许和拒绝规则 |27| `/permissions` | 当前生效的已解析允许和拒绝规则 |

28| `/doctor` | 配置诊断：无效的键、schema 错误、安装健康状况。{/* min-version: 2.1.196 */}从 v2.1.196 开始，还会报告在同一作用域中定义的重复[子代理](/zh-CN/sub-agents)名称，并标记哪一个是活跃的 |28| `/doctor` | 配置检查：安装健康状况、无效的设置文件、未使用的扩展和同一目录中重复的[子代理](/zh-CN/sub-agents)名称，以及建议的修复 |

29| `/debug [issue]` | 为会话启用调试日志记录，并提示 Claude 使用日志输出和设置路径进行诊断 |29| `/debug [issue]` | 为会话启用调试日志记录，并提示 Claude 使用日志输出和设置路径进行诊断 |

30| `/status` | 活跃的设置源，包括是否启用了托管设置 |30| `/status` | 活跃的设置源，包括是否启用了托管设置 |

31 31

45 45

46设置在托管、用户、项目和本地范围内合并。当存在时，托管设置总是优先。在其余的中，更接近的范围按本地、项目、用户的顺序覆盖更广泛的范围。某些设置也可以由命令行标志或[环境变量](/zh-CN/env-vars)设置，它们充当另一个覆盖层。当设置似乎不适用时，你设置的值通常被另一个范围或环境变量覆盖。46设置在托管、用户、项目和本地范围内合并。当存在时，托管设置总是优先。在其余的中，更接近的范围按本地、项目、用户的顺序覆盖更广泛的范围。某些设置也可以由命令行标志或[环境变量](/zh-CN/env-vars)设置，它们充当另一个覆盖层。当设置似乎不适用时，你设置的值通常被另一个范围或环境变量覆盖。

47 47

~~48运行 `/doctor` 来验证你的配置文件并显示无效的键或 schema 错误。当 `/doctor` 报告问题时，按 `f` 将诊断报告发送给 Claude，让它与你一起逐步解决问题。~~48运行 `/doctor` 来检查你的配置和安装。它报告它发现的内容，包括无效的设置文件、重复的安装和未使用的扩展，然后提议仅在你确认后应用的修复。在 v2.1.205 之前，`/doctor` 打开一个只读诊断屏幕，按 `f` 将报告发送给 Claude 来修复。

50从终端，`claude doctor` 打印只读安装和设置诊断，而不启动会话。

49 51

50运行 `/status` 来查看哪些设置源是活跃的，包括是否启用了托管设置。要了解给定键哪个范围优先，请参阅[范围如何交互](/zh-CN/settings#how-scopes-interact)。52运行 `/status` 来查看哪些设置源是活跃的，包括是否启用了托管设置。要了解给定键哪个范围优先，请参阅[范围如何交互](/zh-CN/settings#how-scopes-interact)。

51 53

67 69

68运行 `/hooks` 来列出当前会话注册的每个 hook，按事件分组。如果你定义的 hook 没有出现，它没有被读取：hooks 在设置文件中的 `"hooks"` 键下，而不是在独立文件中。70运行 `/hooks` 来列出当前会话注册的每个 hook，按事件分组。如果你定义的 hook 没有出现，它没有被读取：hooks 在设置文件中的 `"hooks"` 键下，而不是在独立文件中。

69 71

70如果 hook 出现但没有触发，匹配器通常是原因。`matcher` 字段是一个使用 `|` 来匹配多个工具名称的单个字符串，例如 `"Edit|Write"`。{/* min-version: 2.1.191 */}在 Claude Code v2.1.191 或更高版本上，`,` 也可以作为分隔符，所以 `"Edit,Write"` 是等效的。在更早的版本上，逗号会进入正则表达式评估，匹配器永远不会匹配，所以如果你不在 v2.1.191 上，请使用 `|`。拼写错误的工具名称会无声地失败，原因相同。数组值是一个 schema 错误：Claude Code 显示设置错误通知，`/doctor` 报告验证失败，hook 条目被删除，所以它不会出现在 `/hooks` 中。72如果 hook 出现但没有触发，匹配器通常是原因。检查它是否有这些错误：

74* `matcher` 字段是一个使用 `|` 来匹配多个工具名称的单个字符串，例如 `"Edit|Write"`。{/* min-version: 2.1.191 */}`,` 分隔符是等效的，所以 `"Edit,Write"` 匹配相同的工具。在 v2.1.191 之前，逗号会进入正则表达式评估，匹配器永远不会匹配，所以如果你不在 v2.1.191 上，请使用 `|`。

75* 拼写错误的工具名称会产生一个不匹配任何内容的匹配器，所以 hook 会无声地失败。

76* 数组值是一个 schema 错误：Claude Code 显示设置错误通知并拒绝整个用户、项目或本地设置文件，`claude doctor` 报告验证失败，该文件中没有 hook 出现在 `/hooks` 中。在[托管设置](/zh-CN/settings#settings-files)中，只有无效条目被删除，文件的其他 hooks 仍然适用。

71 77

72对 `settings.json` 的编辑在短暂的文件稳定延迟后在运行的会话中生效。你不需要重新启动。如果保存后几秒钟 `/hooks` 仍然显示旧定义，再次运行 `/hooks` 来刷新视图。78对 `settings.json` 的编辑在短暂的文件稳定延迟后在运行的会话中生效。你不需要重新启动。如果保存后几秒钟 `/hooks` 仍然显示旧定义，再次运行 `/hooks` 来刷新视图。

73 79

77 针对干净配置进行测试83 针对干净配置进行测试

78</h2>84</h2>

79 85

80{/* min-version: 2.1.169 */}使用 [`claude --safe-mode`](/zh-CN/cli-reference#cli-flags) 开始，它会启动一个会话，禁用所有自定义，包括 `CLAUDE.md`、skills、plugins、hooks、MCP 服务器以及自定义命令和代理。身份验证、模型选择、内置工具和权限正常工作。如果问题在安全模式下消失，则其中一个方面是原因；使用上面的针对性检查来找出是哪一个。由你的组织部署的托管设置仍然部分适用，因此策略配置的 hooks 和状态行即使在安全模式下也会运行。86{/* min-version: 2.1.169 */}使用 [`claude --safe-mode`](/zh-CN/cli-reference#cli-flags) 开始，它会启动一个会话，禁用所有自定义，包括 `CLAUDE.md`、skills、plugins、hooks、MCP 服务器以及自定义命令和代理。身份验证、模型选择、内置工具和权限正常工作。如果问题在安全模式下消失，则其中一个方面是原因；使用上面的针对性检查来找出是哪一个。安全模式仍然应用来自你的组织的托管 hooks 和设置策略。托管 plugins、skills、CLAUDE.md 和 MCP 服务器被关闭。

81 87

82如果问题在安全模式下仍然存在，或你的设置本身可疑，请与从你的常规设置中不加载任何内容的会话进行比较。将 [`CLAUDE_CONFIG_DIR`](/zh-CN/env-vars) 指向一个空目录以绕过 `~/.claude` 下的所有内容，并从没有 `.claude` 文件夹、`.mcp.json` 或 `CLAUDE.md` 的目录启动，以便也跳过项目配置。88如果问题在安全模式下仍然存在，或你的设置本身可疑，请与从你的常规设置中不加载任何内容的会话进行比较。将 [`CLAUDE_CONFIG_DIR`](/zh-CN/env-vars) 指向一个空目录以绕过 `~/.claude` 下的所有内容，并从没有 `.claude` 文件夹、`.mcp.json` 或 `CLAUDE.md` 的目录启动，以便也跳过项目配置。

83 89

desktop.md +66 −32

Details

29在 Code 选项卡中，每个对话都是一个**会话**：它有自己的聊天历史、项目文件夹和代码更改，独立于任何其他会话。侧边栏列出你的会话，让你可以并行运行多个会话。在一个会话中，你可以：29在 Code 选项卡中，每个对话都是一个**会话**：它有自己的聊天历史、项目文件夹和代码更改，独立于任何其他会话。侧边栏列出你的会话，让你可以并行运行多个会话。在一个会话中，你可以：

30 30

31* [使用 diff 视图审查和评论更改](#review-changes-with-diff-view)，然后[通过 CI 监控生成的 PR](#monitor-pull-request-status)31* [使用 diff 视图审查和评论更改](#review-changes-with-diff-view)，然后[通过 CI 监控生成的 PR](#monitor-pull-request-status)

~~32* [在嵌入式浏览器中预览你的运行应用](#preview-your-app)，同时 Claude 验证自己的更改~~32* [在浏览器窗格中预览你的运行应用](#preview-your-app)，同时 Claude 验证自己的更改，并[在其旁边打开外部网站](#browse-external-sites)

~~33* [整理窗格](#arrange-your-workspace)，将聊天、diff、预览、终端和文件编辑器并排放置~~33* [整理窗格](#arrange-your-workspace)，将聊天、diff、浏览器、终端和文件编辑器并排放置

34* 提出[侧边问题](#ask-a-side-question-without-derailing-the-session)，使用会话的上下文而不偏离主线34* 提出[侧边问题](#ask-a-side-question-without-derailing-the-session)，使用会话的上下文而不偏离主线

35* [连接外部工具](#connect-external-tools)，如 GitHub、Slack 和 Linear35* [连接外部工具](#connect-external-tools)，如 GitHub、Slack 和 Linear

36* 让 Claude [打开应用和控制你的屏幕](#let-claude-use-your-computer)36* 让 Claude [打开应用和控制你的屏幕](#let-claude-use-your-computer)

78 选择权限模式78 选择权限模式

79</h3>79</h3>

80 80

81权限模式控制 Claude 在会话期间拥有多少自主权：它是否在编辑文件、运行命令或两者之前询问。你可以随时使用发送按钮旁的模式选择器切换模式。从"询问权限"开始以准确查看 Claude 的操作，然后随着你变得更舒适，转移到"自动接受编辑"或 Plan Mode。81权限模式控制 Claude 在会话期间拥有多少自主权：它是否在编辑文件、运行命令或两者之前询问。你可以随时使用发送按钮旁的模式选择器切换模式。从 Manual 开始以准确查看 Claude 的操作，然后随着你变得更舒适，转移到 Accept edits 或 Plan。

82 82

83| 模式 | 设置键 | 行为 |83| 模式 | 设置键 | 行为 |

~~84| ------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |~~84| ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

89| **绕过权限** | `bypassPermissions` | Claude 运行时没有任何权限提示，等同于 CLI 中的 `--dangerously-skip-permissions`。在设置 → Claude Code 中的"允许绕过权限模式"下启用。仅在沙箱容器或虚拟机中使用。企业管理员可以禁用此选项。 |89| **Bypass permissions** | `bypassPermissions` | Claude 运行时没有任何权限提示，除了由显式[询问规则](/zh-CN/permissions#manage-permissions)强制的权限提示或当 Claude [在外部网站上操作](#browse-external-sites)时由安全分类器强制的权限提示；等同于 CLI 中的 `--dangerously-skip-permissions`。在设置 → Claude Code 中的"允许绕过权限模式"下启用。仅在沙箱容器或虚拟机中使用。企业管理员可以禁用此选项。 |

91代码选项卡的早期版本将这些模式标记为 Ask permissions、Auto accept edits 和 Plan mode。

90 92

91`dontAsk` 权限模式仅在 [CLI](/zh-CN/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) 中可用。93`dontAsk` 权限模式仅在 [CLI](/zh-CN/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) 中可用。

92 94

93<span id="auto-mode-availability" />95<span id="auto-mode-availability" />

94 96

95Auto mode 是一个研究预览版，在 Anthropic API 上对所有用户可用，需要 Claude Opus 4.6 或更高版本，或 Sonnet 4.6 或更高版本。在路由到 Google Cloud Vertex AI 的企业部署中，Auto mode 处于关闭状态，直到你[设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`](/zh-CN/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)，并且只有 Claude Sonnet 5、Opus 4.7 和 Opus 4.8 在那里受支持。97Auto mode 是一个研究预览版，在 Anthropic API 上对所有用户可用，需要 Claude Opus 4.6 或更高版本，或 Sonnet 4.6 或更高版本。在路由到 Google Cloud 的 Agent Platform 的企业部署中，Auto mode 处于关闭状态，直到你[设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`](/zh-CN/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)，并且只有 Claude Sonnet 5、Opus 4.7 和 Opus 4.8 在那里受支持。

96 98

97<Tip title="最佳实践">99<Tip title="最佳实践">

98 在 Plan Mode 中启动复杂任务，以便 Claude 在进行更改之前制定方法。一旦你批准计划，切换到"自动接受编辑"或"询问权限"来执行它。有关此工作流的更多信息，请参阅[先探索，然后计划，然后编码](/zh-CN/best-practices#explore-first-then-plan-then-code)。100 在 Plan 中启动复杂任务，以便 Claude 在进行更改之前制定方法。一旦你批准计划，切换到 Accept edits 或 Manual 来执行它。有关此工作流的更多信息，请参阅[先探索，然后计划，然后编码](/zh-CN/best-practices#explore-first-then-plan-then-code)。

99</Tip>101</Tip>

100 102

101云会话支持"自动接受编辑"、Plan Mode 和 Auto mode。"自动接受编辑"对应于 `default` 模式：云会话预先批准文件编辑，所以选择器显示"自动接受编辑"而不是"询问权限"。"绕过权限"不可用，因为云环境已经是沙箱化的。103云会话支持 Accept edits、Plan 和 Auto。Accept edits 对应于 `default` 模式：云会话预先批准文件编辑，所以选择器显示 Accept edits 而不是 Manual。Bypass permissions 不可用，因为云环境已经是沙箱化的。

102 104

103企业管理员可以限制哪些权限模式可用。有关详细信息，请参阅[企业配置](#enterprise-configuration)。105企业管理员可以限制哪些权限模式可用。有关详细信息，请参阅[企业配置](#enterprise-configuration)。

104 106

106 预览你的应用108 预览你的应用

107</h3>109</h3>

108 110

109Claude 可以启动开发服务器并打开嵌入式浏览器来验证其更改。这适用于前端 Web 应用以及后端服务器：Claude 可以测试 API 端点、查看服务器日志并迭代它发现的问题。在大多数情况下，Claude 在编辑项目文件后自动启动服务器。你也可以随时要求 Claude 预览。默认情况下，Claude [自动验证](#auto-verify-changes)每次编辑后的更改。111Claude 可以启动开发服务器并在浏览器窗格中打开它来验证其更改。这适用于前端 Web 应用以及后端服务器：Claude 可以测试 API 端点、查看服务器日志并迭代它发现的问题。在大多数情况下，Claude 在编辑项目文件后自动启动服务器。你也可以随时要求 Claude 预览。默认情况下，Claude [自动验证](#auto-verify-changes)每次编辑后的更改。

110 112

111预览窗格也可以打开项目中的静态 HTML 文件、PDF、图像和视频。点击聊天中的 HTML、PDF、图像或视频路径在预览中打开它。113浏览器窗格也可以打开项目中的静态 HTML 文件、PDF、图像和视频。点击聊天中的 HTML、PDF、图像或视频路径在那里打开它。

112 114

113从预览窗格，你可以：115从浏览器窗格，你可以：

114 116

115* 在嵌入式浏览器中直接与你运行的应用交互117* 在浏览器窗格中直接与你运行的应用交互

116* 观看 Claude 自动验证其自己的更改：它拍摄屏幕截图、检查 DOM、点击元素、填充表单并修复它发现的问题118* 观看 Claude 自动验证其自己的更改：它拍摄屏幕截图、检查 DOM、点击元素、填充表单并修复它发现的问题

117* 从会话工具栏中的 **Preview** 下拉菜单启动或停止服务器119* 从会话工具栏中的服务器下拉菜单启动或停止服务器

118* 通过在下拉菜单中选择 **Persist sessions** 来在服务器重启时保持 cookie 和本地存储，这样你就不必在开发期间重新登录120* 通过在下拉菜单中选择 **Persist sessions** 来在服务器重启时保持 cookie 和本地存储，这样你就不必在开发期间重新登录

119* 编辑服务器配置或一次停止所有服务器121* 编辑服务器配置或一次停止所有服务器

120 122

121Claude 根据你的项目创建初始服务器配置。如果你的应用使用自定义开发命令，编辑 `.claude/launch.json` 以匹配你的设置。有关完整参考，请参阅[配置预览服务器](#configure-preview-servers)。123Claude 根据你的项目创建初始服务器配置。如果你的应用使用自定义开发命令，编辑 `.claude/launch.json` 以匹配你的设置。有关完整参考，请参阅[配置预览服务器](#configure-preview-servers)。

122 124

123要清除保存的会话数据，在设置 → Claude Code 中切换 **Persist preview sessions** 关闭。要完全禁用预览，在设置 → Claude Code 中切换 **Preview** 关闭。125要清除保存的会话数据，或完全关闭浏览器，请使用设置 → Claude Code 中的切换开关。

126

127<h3 id="browse-external-sites">

128 浏览外部网站

129</h3>

130

131浏览器窗格是一个选项卡式浏览器，所以你可以在你运行的应用旁边打开文档、问题跟踪器或任何其他网站。要打开浏览器，在 macOS 上按 **Cmd+Shift+B** 或在 Windows 上按 **Ctrl+Shift+B**，或从 **Views** 菜单中选择它。当你点击聊天中的外部链接时，一个选择器提供 **Open in app** 来使用浏览器窗格或 **Default browser** 来使用你自己的；在 macOS 上 **Cmd** 点击或在 Windows 上 **Ctrl** 点击直接在你的系统浏览器中打开链接。你可以登录窗格中的网站，包括弹出式登录流程，如 Google OAuth。

132

133Claude 可以使用与[验证你的应用](#preview-your-app)相同的工具来读取和交互外部页面，并有两个额外的安全检查：

134

135* 安全分类器在每个权限模式中审查 Claude 在外部页面上的写入操作，如点击和输入。这些是与[自动模式](#choose-a-permission-mode)相同的分类器，当它们标记一个操作时，你会获得一个权限提示，无论模式如何。

136* 在除 Auto 和 Bypass permissions 之外的权限模式中，在 Claude 导航到新网站之前，域名允许列表检查也适用。

137

138<h4 id="approve-claude’s-actions-on-a-site">

139 批准 Claude 在网站上的操作

140</h4>

141

142Claude 第一次在外部网站上操作时，会出现一个权限卡，Claude 等待你的选择：**Allow once**、**Always allow** 或 **Deny**。**Allow once** 批准操作而不保存任何内容。**Always allow** 在你的设备上保存该网站的批准，你可以在设置中撤销它。每个网站都需要自己的批准，包括子域。你的本地开发服务器和项目文件不需要批准，所以[自动验证](#auto-verify-changes)继续工作而不提示。

143

144即使在批准的网站上，Claude 也不会在没有你的输入的情况下购买物品、创建账户或绕过 CAPTCHA。在浏览器窗格中浏览使用与 [Chrome 中的 Claude 扩展](/zh-CN/chrome)相同的安全模型。有关 Claude 如何处理敏感网站和风险操作的信息，请参阅[安全使用 Chrome 中的 Claude](https://support.claude.com/en/articles/12902428-using-claude-in-chrome-safely)。

145

146<h4 id="choose-between-the-browser-and-the-chrome-extension">

147 在浏览器和 Chrome 扩展之间选择

148</h4>

149

150浏览器窗格使用干净的浏览器配置文件，与你的个人浏览器分开，没有你保存的登录或历史记录。使用它来构建和测试你的应用以及不需要你的身份的网站。当你想让 Claude 在你的登录会话中充当你时，改用 [Chrome 中的 Claude 扩展](/zh-CN/chrome)，它共享你的浏览器的登录状态。

151

152<h4 id="restrict-external-browsing-for-your-organization">

153 限制你的组织的外部浏览

154</h4>

155

156浏览器遵循与 [Chrome 中的 Claude 扩展](https://support.claude.com/en/articles/13065128-claude-in-chrome-admin-controls)相同的[网站允许列表和阻止列表控制](https://support.claude.com/en/articles/13065128-claude-in-chrome-admin-controls)。如果你的组织已经为扩展配置了这些列表，浏览器会自动尊重它们。管理员也可以使用 [`browserExternalPageTools` 托管设置](#managed-settings)关闭 Claude 在外部页面上的工具。禁用工具后，用户仍然可以导航到外部网站；Claude 的工具无法读取或对其进行操作。

124 157

125<h3 id="review-changes-with-diff-view">158<h3 id="review-changes-with-diff-view">

126 使用 diff 视图审查更改159 使用 diff 视图审查更改

151 184

152打开拉取请求后，CI 状态栏出现在会话中。Claude Code 使用 GitHub CLI 轮询检查结果并显示失败。185打开拉取请求后，CI 状态栏出现在会话中。Claude Code 使用 GitHub CLI 轮询检查结果并显示失败。

153 186

154* **自动修复**：启用后，Claude 通过读取失败输出并迭代来自动尝试修复失败的 CI 检查。187* **Auto-fix**：启用后，Claude 通过读取失败输出并迭代来自动尝试修复失败的 CI 检查。

155* **自动合并**：启用后，Claude 在所有检查通过后合并 PR。合并方法是压缩。自动合并必须在你的 GitHub 存储库设置中[启用](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository)才能工作。188* **Auto-merge**：启用后，Claude 在所有检查通过后合并 PR。合并方法是压缩。Auto-merge 必须在你的 GitHub 存储库设置中[启用](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository)才能工作。

156 189

157使用 CI 状态栏中的 **Auto-fix** 和 **Auto-merge** 切换来启用任一选项。Claude Code 还在 CI 完成时发送桌面通知。要在 PR 合并或关闭后自动存档会话，在设置 → Claude Code 中打开[自动存档](#work-in-parallel-with-sessions)。190使用 CI 状态栏中的 **Auto-fix** 和 **Auto-merge** 切换来启用任一选项。Claude Code 还在 CI 完成时发送桌面通知。要在 PR 合并或关闭后自动存档会话，在设置 → Claude Code 中打开[自动存档](#work-in-parallel-with-sessions)。

158 191

164 整理工作区197 整理工作区

165</h2>198</h2>

166 199

167Code 选项卡围绕你可以以任何布局排列的窗格构建：聊天、diff、预览、终端、文件、plan、tasks 和 subagent。通过其标题拖动窗格来重新定位它，或拖动窗格边缘来调整大小。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 来关闭焦点窗格。从会话工具栏中的 **Views** 菜单打开其他窗格。200Code 选项卡围绕你可以以任何布局排列的窗格构建：聊天、diff、浏览器、终端、文件、plan、tasks 和 subagent。通过其标题拖动窗格来重新定位它，或拖动窗格边缘来调整大小。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 来关闭焦点窗格。从会话工具栏中的 **Views** 菜单打开其他窗格。

168 201

169<Note>202<Note>

170 本部分中的窗格布局、终端、文件编辑器和视图模式需要 Claude Desktop v1.2581.0 或更高版本。在 macOS 上打开 **Claude → Check for Updates** 或在 Windows 上打开 **Help → Check for Updates** 来更新。203 本部分中的窗格布局、终端、文件编辑器和视图模式需要 Claude Desktop v1.2581.0 或更高版本。在 macOS 上打开 **Claude → Check for Updates** 或在 Windows 上打开 **Help → Check for Updates** 来更新。

180 打开和编辑文件213 打开和编辑文件

181</h3>214</h3>

182 215

183点击聊天或 diff 查看器中的文件路径在文件窗格中打开它。HTML、PDF、图像和视频路径改为在[预览窗格](#preview-your-app)中打开。进行现场编辑并点击 **Save** 来写回。如果文件自你打开它以来在磁盘上更改，窗格会警告你并让你覆盖或丢弃。点击 **Discard** 来恢复你的编辑，或点击窗格标题中的路径来复制绝对路径。216点击聊天或 diff 查看器中的文件路径在文件窗格中打开它。HTML、PDF、图像和视频路径改为在[浏览器窗格](#preview-your-app)中打开。进行现场编辑并点击 **Save** 来写回。如果文件自你打开它以来在磁盘上更改，窗格会警告你并让你覆盖或丢弃。点击 **Discard** 来恢复你的编辑，或点击窗格标题中的路径来复制绝对路径。

184 217

185文件窗格在本地和 SSH 会话中可用。对于远程会话，要求 Claude 进行更改。218文件窗格在本地和 SSH 会话中可用。对于云会话，要求 Claude 进行更改。

186 219

187<h3 id="open-files-in-other-apps">220<h3 id="open-files-in-other-apps">

188 在其他应用中打开文件221 在其他应用中打开文件

225| `Esc` | 停止 Claude 的响应 |258| `Esc` | 停止 Claude 的响应 |

230| `Cmd` `\` | 关闭焦点窗格 |263| `Cmd` `\` | 关闭焦点窗格 |

231| `Cmd` `;` | 打开侧边聊天 |264| `Cmd` `;` | 打开侧边聊天 |

437 470

438Claude 自动检测你的开发服务器设置并将配置存储在启动会话时选择的文件夹根目录的 `.claude/launch.json` 中。Preview 使用此文件夹作为其工作目录，因此如果你选择了父文件夹，具有自己开发服务器的子文件夹将不会自动检测。要使用子文件夹的服务器，要么直接在该文件夹中启动会话，要么手动添加配置。471Claude 自动检测你的开发服务器设置并将配置存储在启动会话时选择的文件夹根目录的 `.claude/launch.json` 中。Preview 使用此文件夹作为其工作目录，因此如果你选择了父文件夹，具有自己开发服务器的子文件夹将不会自动检测。要使用子文件夹的服务器，要么直接在该文件夹中启动会话，要么手动添加配置。

439 472

440要自定义服务器的启动方式，例如使用 `yarn dev` 而不是 `npm run dev` 或更改端口，手动编辑文件或点击 Preview 下拉菜单中的 **Edit configuration** 在你的代码编辑器中打开它。该文件支持带注释的 JSON。473要自定义服务器的启动方式，例如使用 `yarn dev` 而不是 `npm run dev` 或更改端口，手动编辑文件或点击服务器下拉菜单中的 **Edit configuration** 在你的代码编辑器中打开它。该文件支持带注释的 JSON。

441 474

442```json theme={null}475```json theme={null}

443{476{

461 494

462启用 `autoVerify` 时，Claude 在编辑文件后自动验证代码更改。它拍摄屏幕截图、检查错误并在完成响应之前确认更改有效。495启用 `autoVerify` 时，Claude 在编辑文件后自动验证代码更改。它拍摄屏幕截图、检查错误并在完成响应之前确认更改有效。

463 496

464自动验证默认打开。通过在 `.claude/launch.json` 中添加 `"autoVerify": false` 来按项目禁用它，或从 **Preview** 下拉菜单切换它。497自动验证默认打开。通过在 `.claude/launch.json` 中添加 `"autoVerify": false` 来按项目禁用它，或从服务器下拉菜单切换它。

465 498

466```json theme={null}499```json theme={null}

467{500{

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

738| `browserExternalPageTools` | 设置为 `"disabled"` 以防止 Claude 使用工具在[浏览器窗格](#browse-external-sites)中读取或作用于外部页面。用户仍然可以自己导航到外部网站，本地开发服务器预览不受影响。 |

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

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

754 788

755如果你已经使用 Claude Code CLI，Desktop 运行相同的底层引擎，具有图形界面。你可以在同一机器上同时运行两者，甚至在同一项目上。每个维护单独的会话历史，但它们通过 CLAUDE.md 文件共享配置和项目内存。789如果你已经使用 Claude Code CLI，Desktop 运行相同的底层引擎，具有图形界面。你可以在同一机器上同时运行两者，甚至在同一项目上。每个维护单独的会话历史，但它们通过 CLAUDE.md 文件共享配置和项目内存。

756 790

757要将 CLI 会话移动到 Desktop，在终端中运行 `/desktop`。Claude 保存你的会话并在桌面应用中打开它，然后退出 CLI。此命令在 macOS 和 Windows 上可用，当你使用 Claude 订阅登录时。它不适用于 API 密钥身份验证或 Bedrock、Vertex 或 Foundry。791要将 CLI 会话移动到 Desktop，在终端中运行 `/desktop`。Claude 保存你的会话并在桌面应用中打开它，然后退出 CLI。此命令在 macOS 和 Windows 上可用，当你使用 Claude 订阅登录时。它不适用于 API 密钥身份验证或 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。

758 792

759<Tip>793<Tip>

760 何时使用 Desktop vs CLI：当你想要管理一个窗口中的并行会话、并排排列窗格或可视化审查更改时，使用 Desktop。当你需要脚本、自动化或更喜欢终端工作流时，使用 CLI。794 何时使用 Desktop vs CLI：当你想要管理一个窗口中的并行会话、并排排列窗格或可视化审查更改时，使用 Desktop。当你需要脚本、自动化或更喜欢终端工作流时，使用 CLI。

804此表比较了 CLI 和 Desktop 之间的核心功能。有关 CLI 标志的完整列表，请参阅 [CLI 参考](/zh-CN/cli-reference)。838此表比较了 CLI 和 Desktop 之间的核心功能。有关 CLI 标志的完整列表，请参阅 [CLI 参考](/zh-CN/cli-reference)。

805 839

806| 功能 | CLI | Desktop |840| 功能 | CLI | Desktop |

807| ----------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |841| ----------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

810| [第三方提供商](/zh-CN/third-party-integrations) | Bedrock、Vertex AI、Foundry | Anthropic 的 API 默认。企业部署可以配置 Vertex AI 和网关提供商。请参阅[企业配置指南](https://support.claude.com/en/articles/12622667-enterprise-configuration)。要在 Bedrock、Vertex AI、Foundry 或自托管 LLM 网关上运行 Code 选项卡，请参阅 [Cowork on 3P research preview](https://claude.com/docs/cowork/3p/overview)。 |844| [第三方提供商](/zh-CN/third-party-integrations) | Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry | Anthropic 的 API 默认。企业部署可以配置 Google Cloud 的 Agent Platform 和网关提供商。请参阅[企业配置指南](https://support.claude.com/en/articles/12622667-enterprise-configuration)。要在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自托管 LLM 网关上运行 Code 选项卡，请参阅 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)。 |

825 859

826以下功能仅在 CLI 或 VS Code 扩展中可用，除非另有说明：860以下功能仅在 CLI 或 VS Code 扩展中可用，除非另有说明：

827 861

828* **第三方提供商**：Desktop 默认连接到 Anthropic 的 API。企业部署可以通过[托管设置](https://support.claude.com/en/articles/12622667-enterprise-configuration)配置 Vertex AI 和网关提供商。对于 CLI 中的 Bedrock 或 Foundry，请参阅[快速入门](/zh-CN/quickstart)。作为上述部分的例外，[Cowork on 3P research preview](https://claude.com/docs/cowork/3p/overview)在 Bedrock、Vertex AI、Foundry 或自托管 LLM 网关上运行 Code 选项卡。862* **第三方提供商**：Desktop 默认连接到 Anthropic 的 API。企业部署可以通过[托管设置](https://support.claude.com/en/articles/12622667-enterprise-configuration)配置 Google Cloud 的 Agent Platform 和网关提供商。对于 CLI 中的 Amazon Bedrock 或 Microsoft Foundry，请参阅[快速入门](/zh-CN/quickstart)。作为上述部分的例外，[Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自托管 LLM 网关上运行 Code 选项卡。

829* **Linux (beta)**：Linux 桌面应用中尚不提供计算机使用。请参阅 [Claude Desktop on Linux](/zh-CN/desktop-linux)。863* **Linux (beta)**：Linux 桌面应用中尚不提供计算机使用。请参阅 [Claude Desktop on Linux](/zh-CN/desktop-linux)。

830* **内联代码建议**：Desktop 不提供自动完成风格的建议。它通过对话提示和显式代码更改工作。864* **内联代码建议**：Desktop 不提供自动完成风格的建议。它通过对话提示和显式代码更改工作。

831* **Agent teams**：并行 Claude Code 会话相互通信在 [CLI](/zh-CN/agent-teams) 中可用，不在 Desktop 中。对于一个会话内的多 agent 工作，使用[动态工作流](/zh-CN/workflows)，它在 Desktop 中运行。865* **Agent teams**：并行 Claude Code 会话相互通信在 [CLI](/zh-CN/agent-teams) 中可用，不在 Desktop 中。对于一个会话内的多 agent 工作，使用[动态工作流](/zh-CN/workflows)，它在 Desktop 中运行。

832* **Terminal-dialog 命令**：在终端中打开交互式面板的内置命令，例如 `/permissions`、`/config` 和 `/doctor`，在 Code 选项卡中不可用，并回复 `isn't available in this environment`。直接编辑[设置文件](/zh-CN/settings)来管理权限规则和配置，或从独立 CLI 运行命令。866* **Terminal-dialog 命令**：在终端中打开交互式面板的内置命令，例如 `/permissions` 和 `/config`，在 Code 选项卡中不可用，并回复 `isn't available in this environment`。`/config` 在你传递 `key=value` 时设置设置，例如 `/config theme=dark`；仅其选择器形式不可用。直接编辑[设置文件](/zh-CN/settings)来管理权限规则和配置，或从独立 CLI 运行命令。

833 867

834<h2 id="troubleshooting">868<h2 id="troubleshooting">

835 故障排除869 故障排除

desktop-linux.md +26 −2

Details

25 安装25 安装

26</h2>26</h2>

27 27

~~28从 Anthropic 的 apt 存储库安装，以便更新通过系统的常规包更新到达。~~28从 Anthropic 的 apt 存储库安装，以便更新通过系统的常规包更新到达。打开终端并运行每个步骤中的命令。

29 29

30<Steps>30<Steps>

31 <Step title="添加 Anthropic 的 apt 存储库">31 <Step title="添加 Anthropic 的 apt 存储库">

32 此步骤使用 `curl` 下载签名密钥，新的 Debian 和 Ubuntu 安装可能不包含此工具。如果下载命令失败并显示 `sudo: curl: command not found`，请先安装 curl：

34 ```bash theme={null}

35 sudo apt install curl

36 ```

32 下载 Anthropic 的签名密钥：38 下载 Anthropic 的签名密钥：

33 39

34 ```bash theme={null}40 ```bash theme={null}

69 从下载的文件安装75 从下载的文件安装

70</h3>76</h3>

71 77

72如果您无法使用 apt 存储库，请从 [claude.com/download](https://claude.com/download) 下载适用于您的架构（x64 或 arm64）的 `.deb` 软件包，然后使用软件安装程序打开它或从下载目录运行：78如果您无法使用 apt 存储库，请首先从 [claude.com/download](https://claude.com/download) 下载适用于您的架构（x64 或 arm64）的 `.deb` 软件包。然后使用软件安装程序打开下载的文件，或从包含下载文件的目录使用 apt 安装它：

73 79

74```bash theme={null}80```bash theme={null}

75sudo apt install ./claude-desktop_*.deb81sudo apt install ./claude-desktop_*.deb

76```82```

77 83

84如果 apt 报告 `E: Unsupported file ./claude-desktop_*.deb given on commandline`，则该模式与当前目录中的 `.deb` 文件不匹配。确认下载已完成，然后从包含该文件的目录再次运行该命令。

78以这种方式安装的 `.deb` 不会接收更新。要通过 apt 获取更新，请添加上面显示的存储库，或取消注释软件包写入 `/etc/apt/sources.list.d/claude-desktop.list` 的占位符条目中的 `deb` 行。86以这种方式安装的 `.deb` 不会接收更新。要通过 apt 获取更新，请添加上面显示的存储库，或取消注释软件包写入 `/etc/apt/sources.list.d/claude-desktop.list` 的占位符条目中的 `deb` 行。

79 87

80<h2 id="update">88<h2 id="update">

103sudo rm /etc/apt/sources.list.d/claude-desktop.list111sudo rm /etc/apt/sources.list.d/claude-desktop.list

104```112```

105 113

114<h2 id="troubleshoot">

115 故障排除

116</h2>

117

118<h3 id="unable-to-locate-package-claude-desktop">

119 无法定位软件包 claude-desktop

120</h3>

121

122如果 `sudo apt install claude-desktop` 失败并显示 `E: Unable to locate package claude-desktop`，说明 apt 没有找到您添加的存储库。请检查以下内容：

123

124* 确认存储库条目已写入。`cat /etc/apt/sources.list.d/claude-desktop.list` 应该显示来自[添加 Anthropic 的 apt 存储库](#install)步骤的 `deb` 行。如果文件为空或缺失，请再次运行该步骤。

125* 确认您的架构受支持。`dpkg --print-architecture` 应该打印 `amd64` 或 `arm64`。该存储库不为其他架构发布软件包。

126* 再次运行 `sudo apt update` 并检查其输出中是否有与 `downloads.claude.ai` 相关的错误。那里的网络或密钥错误意味着存储库已添加但无法访问或验证。

127

128如果存储库已就位且可访问，但仍然找不到该软件包，请改为[从下载的文件安装](#install-from-a-downloaded-file)。

129

106<h2 id="what’s-not-in-the-linux-beta-yet">130<h2 id="what’s-not-in-the-linux-beta-yet">

107 Linux 测试版中尚未包含的内容131 Linux 测试版中尚未包含的内容

108</h2>132</h2>

desktop-quickstart.md +7 −3

Details

113 113

114**在提交前审查更改。** Claude 编辑文件后，会出现 `+12 -1` 指示器。点击它以打开[差异视图](/zh-CN/desktop#review-changes-with-diff-view)，逐个文件审查修改，并对特定行进行评论。Claude 会读取您的评论并进行修订。点击 **Review code** 让 Claude 自己评估差异并留下内联建议。114**在提交前审查更改。** Claude 编辑文件后，会出现 `+12 -1` 指示器。点击它以打开[差异视图](/zh-CN/desktop#review-changes-with-diff-view)，逐个文件审查修改，并对特定行进行评论。Claude 会读取您的评论并进行修订。点击 **Review code** 让 Claude 自己评估差异并留下内联建议。

115 115

116**调整您拥有的控制量。** 您的[权限模式](/zh-CN/desktop#choose-a-permission-mode)控制平衡。询问权限（默认）在每次编辑前需要批准。自动接受编辑会自动接受文件编辑以加快迭代。Plan mode 让 Claude 在不接触任何文件的情况下规划方法，这在大型重构前很有用。116**调整您拥有的控制量。** 您的[权限模式](/zh-CN/desktop#choose-a-permission-mode)设置了 Claude 在不请求批准的情况下可以做多少事情：

117

118* **Manual**：默认设置。Claude 在编辑文件或运行命令前会请求批准。

119* **Accept edits**：Claude 自动接受文件编辑以加快迭代。

120* **Plan**：Claude 提出一种方法而不编辑任何文件，这在大型重构前很有用。

117 121

118**添加插件以获得更多功能。** 点击提示框旁的 **+** 按钮并选择 **Plugins** 以浏览和安装[插件](/zh-CN/desktop#install-plugins)，这些插件添加 skills、代理、MCP servers 等。122**添加插件以获得更多功能。** 点击提示框旁的 **+** 按钮并选择 **Plugins** 以浏览和安装[插件](/zh-CN/desktop#install-plugins)，这些插件添加 skills、代理、MCP servers 等。

119 123

120**整理您的工作区。** 将聊天、差异、终端、文件和预览窗格拖放到您想要的任何布局中。使用 **Ctrl+\`** 打开终端以在会话旁运行命令，或点击文件路径以在文件窗格中打开它。请参阅[整理您的工作区](/zh-CN/desktop#arrange-your-workspace)。124**整理您的工作区。** 将聊天、差异、终端、文件和浏览器窗格拖放到您想要的任何布局中。使用 **Ctrl+\`** 打开终端以在会话旁运行命令，或点击文件路径以在文件窗格中打开它。请参阅[整理您的工作区](/zh-CN/desktop#arrange-your-workspace)。

121 125

122**预览您的应用。** 点击 **Preview** 下拉菜单以直接在桌面中运行您的开发服务器。Claude 可以查看正在运行的应用、测试端点、检查日志并对其看到的内容进行迭代。请参阅[预览您的应用](/zh-CN/desktop#preview-your-app)。126**预览您的应用。** 当您在桌面中运行开发服务器时，您的应用会在浏览器窗格中打开，该窗格也可以[打开外部网站](/zh-CN/desktop#browse-external-sites)。Claude 可以查看正在运行的应用、测试端点、检查日志并对其看到的内容进行迭代。请参阅[预览您的应用](/zh-CN/desktop#preview-your-app)。

123 127

124**跟踪您的拉取请求。** 打开 PR 后，Claude Code 监控 CI 检查结果，可以自动修复失败或在所有检查通过后合并 PR。请参阅[监控拉取请求状态](/zh-CN/desktop#monitor-pull-request-status)。128**跟踪您的拉取请求。** 打开 PR 后，Claude Code 监控 CI 检查结果，可以自动修复失败或在所有检查通过后合并 PR。请参阅[监控拉取请求状态](/zh-CN/desktop#monitor-pull-request-status)。

125 129

devcontainer.md +2 −2

Details

75您在身份验证提示处看到的内容取决于您的提供商：75您在身份验证提示处看到的内容取决于您的提供商：

76 76

77* **Anthropic**：通过浏览器使用您的 Claude 或 Anthropic Console 账户登录77* **Anthropic**：通过浏览器使用您的 Claude 或 Anthropic Console 账户登录

~~78* **[Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry](/zh-CN/third-party-integrations)**：Claude Code 使用您的云提供商凭证，无需浏览器提示~~78* **[Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry](/zh-CN/third-party-integrations)**：Claude Code 使用您的云提供商凭证，无需浏览器提示

79 79

80对于云提供商，通过 `containerEnv`、Codespaces 密钥或您的云的工作负载身份将凭证传递到容器中，而不是从主机挂载凭证文件。有关凭证链的详细信息，请参阅 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Vertex AI](/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/zh-CN/microsoft-foundry)，Claude Code 会读取这些信息。80对于云提供商，通过 `containerEnv`、Codespaces 密钥或您的云的工作负载身份将凭证传递到容器中，而不是从主机挂载凭证文件。有关凭证链的详细信息，请参阅 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/zh-CN/microsoft-foundry)，Claude Code 会读取这些信息。

81 81

82请参阅[选择您的 API 提供商](/zh-CN/admin-setup#choose-your-api-provider)以决定哪条路径适合您的组织。82请参阅[选择您的 API 提供商](/zh-CN/admin-setup#choose-your-api-provider)以决定哪条路径适合您的组织。

83 83

discover-plugins.md +11 −2

Details

332* 输入以按插件名称或描述筛选332* 输入以按插件名称或描述筛选

333* 按 Enter 打开插件的详细视图并启用、禁用或卸载它333* 按 Enter 打开插件的详细视图并启用、禁用或卸载它

334 334

335卸载项目的 `.claude/settings.json` 启用的插件会询问您指的是哪个范围：仅为您禁用它，这会将覆盖写入您的 `.claude/settings.local.json` 并为项目保留已安装的插件，或为所有人卸载它，这会将其从共享的 `.claude/settings.json` 中删除。需要 Claude Code v2.1.203 或更高版本。在 v2.1.203 之前，对话框仅提供本地禁用选项。

336

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

336 338

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

340

341两种类型的插件永远不会被列为未使用：

342

343* 您的组织管理的插件或您使用 `--plugin-dir` 加载的插件

344* 贡献主题、输出样式、监视器或工作流的插件，因为这些提供的价值无需跟踪调用

345

346当您的组织使用 [`strictKnownMarketplaces`](/zh-CN/settings#strictknownmarketplaces) 限制市场时，**最近未使用**标题和**最后使用**行都被隐藏。

338 347

339您的组织管理的插件或您使用 `--plugin-dir` 加载的插件永远不会被列为未使用，贡献 LSP server、主题、输出样式、监视器或工作流的插件也永远不会被列出，因为这些提供的价值无需跟踪调用。当您的组织使用 [`strictKnownMarketplaces`](/zh-CN/settings#strictknownmarketplaces) 限制市场时，该组和**最后使用**行都被隐藏。348插件的[语言服务器](/zh-CN/plugins#add-lsp-servers-to-your-plugin)在提供诊断或回答代码导航请求时被计为已使用，因此其服务器在您的会话中处于活跃状态的 LSP 插件不会被列为未使用。在 v2.1.203 之前，无法计算语言服务器活动作为使用，因此贡献 LSP 服务器的插件完全免除，与主题和输出样式插件仍然相同的方式。

340 349

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

342 351

env-vars.md +53 −51

Details

96</h2>96</h2>

97 97

98| 变量 | 目的 |98| 变量 | 目的 |

99| :------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |99| :------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

100| `ANTHROPIC_API_KEY` | 作为 `X-Api-Key` 标头发送的 API 密钥。设置后，即使您已登录，此密钥也会用于替代您的 Claude Pro、Max、Team 或 Enterprise 订阅。在非交互模式（`-p`）中，存在时始终使用该密钥。在交互模式中，系统会提示您在密钥覆盖订阅之前批准一次。要改用您的订阅，请运行 `unset ANTHROPIC_API_KEY` |100| `ANTHROPIC_API_KEY` | 作为 `X-Api-Key` 标头发送的 API 密钥。设置后，即使您已登录，此密钥也会用于替代您的 Claude Pro、Max、Team 或 Enterprise 订阅。在非交互模式（`-p`）中，存在时始终使用该密钥。在交互模式中，系统会提示您在密钥覆盖订阅之前批准一次。要改用您的订阅，请运行 `unset ANTHROPIC_API_KEY` |

102| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 的工作区 API 密钥，在 AWS 控制台中生成。作为 `x-api-key` 发送，优先于 AWS SigV4 |102| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 的工作区 API 密钥，在 AWS 控制台中生成。作为 `x-api-key` 发送，优先于 AWS SigV4 |

103| `ANTHROPIC_AWS_BASE_URL` | 覆盖 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 端点 URL。用于自定义区域或通过 [LLM 网关](/zh-CN/llm-gateway)路由时。默认为 `https://aws-external-anthropic.{AWS_REGION}.api.aws` |103| `ANTHROPIC_AWS_BASE_URL` | 覆盖 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 端点 URL。用于自定义区域或通过 [LLM 网关](/zh-CN/llm-gateway)路由时。默认为 `https://aws-external-anthropic.{AWS_REGION}.api.aws` |

104| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 所需。在每个请求中作为 `anthropic-workspace-id` 标头发送 |104| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 所需。在每个请求中作为 `anthropic-workspace-id` 标头发送 |

105| `ANTHROPIC_BASE_URL` | 覆盖 API 端点以通过代理或网关路由请求。设置为非第一方主机时，[MCP 工具搜索](/zh-CN/mcp#scale-with-mcp-tool-search)默认禁用。如果您的代理转发 `tool_reference` 块，请设置 `ENABLE_TOOL_SEARCH=true`。从 v2.1.196 开始，当此变量指向 `api.anthropic.com` 以外的主机时，[Remote Control](/zh-CN/remote-control#requirements) 被禁用，与其在 Bedrock、Vertex AI 和 Foundry 上的行为相匹配 |105| `ANTHROPIC_BASE_URL` | 覆盖 API 端点以通过代理或网关路由请求。设置为非第一方主机时，[MCP 工具搜索](/zh-CN/mcp#scale-with-mcp-tool-search)默认禁用。如果您的代理转发 `tool_reference` 块，请设置 `ENABLE_TOOL_SEARCH=true`。从 v2.1.196 开始，当此变量指向 `api.anthropic.com` 以外的主机时，[Remote Control](/zh-CN/remote-control#requirements) 被禁用，与其在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的行为相匹配 |

106| `ANTHROPIC_BEDROCK_BASE_URL` | 覆盖 Bedrock 端点 URL。用于自定义 Bedrock 端点或通过 [LLM 网关](/zh-CN/llm-gateway)路由时。请参阅 [Amazon Bedrock](/zh-CN/amazon-bedrock) |106| `ANTHROPIC_BEDROCK_BASE_URL` | 覆盖 Amazon Bedrock 端点 URL。用于自定义 Amazon Bedrock 端点或通过 [LLM 网关](/zh-CN/llm-gateway)路由时。请参阅 [Amazon Bedrock](/zh-CN/amazon-bedrock) |

107| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆盖 Bedrock Mantle 端点 URL。请参阅 [Mantle 端点](/zh-CN/amazon-bedrock#use-the-mantle-endpoint) |107| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆盖 Amazon Bedrock Mantle 端点 URL。请参阅 [Mantle 端点](/zh-CN/amazon-bedrock#use-the-mantle-endpoint) |

108| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Bedrock [服务层](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。作为 `X-Amzn-Bedrock-Service-Tier` 标头发送。请参阅 [Amazon Bedrock](/zh-CN/amazon-bedrock#service-tiers) |108| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [服务层](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。作为 `X-Amzn-Bedrock-Service-Tier` 标头发送。请参阅 [Amazon Bedrock](/zh-CN/amazon-bedrock#service-tiers) |

109| `ANTHROPIC_BETAS` | 逗号分隔的其他 `anthropic-beta` 标头值列表，以包含在 API 请求中。Claude Code 已发送其需要的 beta 标头；使用此选项可在 Claude Code 添加原生支持之前选择加入 [Anthropic API beta](https://platform.claude.com/docs/en/api/beta-headers)。与需要 API 密钥身份验证的 [`--betas` 标志](/zh-CN/cli-reference#cli-flags)不同，此变量适用于所有身份验证方法，包括 Claude.ai 订阅 |109| `ANTHROPIC_BETAS` | 逗号分隔的其他 `anthropic-beta` 标头值列表，以包含在 API 请求中。Claude Code 已发送其需要的 beta 标头；使用此选项可在 Claude Code 添加原生支持之前选择加入 [Anthropic API beta](https://platform.claude.com/docs/en/api/beta-headers)。与需要 API 密钥身份验证的 [`--betas` 标志](/zh-CN/cli-reference#cli-flags)不同，此变量适用于所有身份验证方法，包括 Claude.ai 订阅 |

111| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要在 `/model` 选择器中添加为自定义条目的模型 ID。使用此选项可以使非标准或网关特定的模型可选择，而无需替换内置别名。请参阅[模型配置](/zh-CN/model-config#add-a-custom-model-option) |111| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要在 `/model` 选择器中添加为自定义条目的模型 ID。使用此选项可以使非标准或网关特定的模型可选择，而无需替换内置别名。请参阅[模型配置](/zh-CN/model-config#add-a-custom-model-option) |

130| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 请参阅[模型配置](/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |130| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 请参阅[模型配置](/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

132| `ANTHROPIC_FOUNDRY_BASE_URL` | Foundry 资源的完整基础 URL（例如，`https://my-resource.services.ai.azure.com/anthropic`）。`ANTHROPIC_FOUNDRY_RESOURCE` 的替代方案（请参阅 [Microsoft Foundry](/zh-CN/microsoft-foundry)） |132| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | Microsoft Foundry 身份验证的 Bearer 令牌，例如 Microsoft Entra 访问令牌。Claude Code 将其作为 `Authorization: Bearer` 标头发送。优先于 `ANTHROPIC_FOUNDRY_API_KEY` 和 Azure 默认凭证链。请参阅 [Microsoft Foundry](/zh-CN/microsoft-foundry)。需要 Claude Code v2.1.203 或更高版本 |

133| `ANTHROPIC_FOUNDRY_RESOURCE` | Foundry 资源名称（例如，`my-resource`）。如果未设置 `ANTHROPIC_FOUNDRY_BASE_URL`，则为必需（请参阅 [Microsoft Foundry](/zh-CN/microsoft-foundry)） |133| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 资源的完整基础 URL（例如，`https://my-resource.services.ai.azure.com/anthropic`）。`ANTHROPIC_FOUNDRY_RESOURCE` 的替代方案（请参阅 [Microsoft Foundry](/zh-CN/microsoft-foundry)） |

134| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 资源名称（例如，`my-resource`）。如果未设置 `ANTHROPIC_FOUNDRY_BASE_URL`，则为必需（请参阅 [Microsoft Foundry](/zh-CN/microsoft-foundry)） |

136| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Bedrock 或 Bedrock Mantle 时覆盖 Haiku 级模型的 AWS 区域。在 Bedrock 上，仅当同时设置 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已弃用的 `ANTHROPIC_SMALL_FAST_MODEL` 时才生效，因为 Bedrock 否则会为后台任务使用主模型 |137| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 时覆盖 Haiku 级模型的 AWS 区域。在 Amazon Bedrock 上，仅当同时设置 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已弃用的 `ANTHROPIC_SMALL_FAST_MODEL` 时才生效，因为 Amazon Bedrock 否则会为后台任务使用主模型 |

137| `ANTHROPIC_VERTEX_BASE_URL` | 覆盖 Vertex AI 端点 URL。用于自定义 Vertex 端点或通过 [LLM 网关](/zh-CN/llm-gateway)路由时。请参阅 [Google Vertex AI](/zh-CN/google-vertex-ai) |138| `ANTHROPIC_VERTEX_BASE_URL` | 覆盖 Google Cloud's Agent Platform 端点 URL。用于自定义 Google Cloud's Agent Platform 端点或通过 [LLM 网关](/zh-CN/llm-gateway)路由时。请参阅 [Google Cloud's Agent Platform](/zh-CN/google-vertex-ai) |

138| `ANTHROPIC_VERTEX_PROJECT_ID` | Vertex AI 请求的 GCP 项目 ID。被 `GCLOUD_PROJECT`、`GOOGLE_CLOUD_PROJECT` 或您的 `GOOGLE_APPLICATION_CREDENTIALS` 凭证文件中的项目覆盖。请参阅 [Google Vertex AI](/zh-CN/google-vertex-ai) |139| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 请求的 GCP 项目 ID。被 `GCLOUD_PROJECT`、`GOOGLE_CLOUD_PROJECT` 或您的 `GOOGLE_APPLICATION_CREDENTIALS` 凭证文件中的项目覆盖。请参阅 [Google Cloud's Agent Platform](/zh-CN/google-vertex-ai) |

139| `ANTHROPIC_WORKSPACE_ID` | [工作负载身份联合](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)的工作区 ID。当您的联合规则的范围超过一个工作区时设置此选项，以便令牌交换知道要针对哪个工作区 |140| `ANTHROPIC_WORKSPACE_ID` | [工作负载身份联合](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)的工作区 ID。当您的联合规则的范围超过一个工作区时设置此选项，以便令牌交换知道要针对哪个工作区 |

140| `API_FORCE_IDLE_TIMEOUT` | 覆盖 5 分钟空闲超时，该超时在没有字节到达时中止流式模型响应。设置为 `0` 以禁用超时，例如当缓慢的[网关](/zh-CN/llm-gateway)或本地模型在块之间暂停超过 5 分钟时。设置为 `1` 以在每个提供商上保持超时。未设置时，超时在直接 Anthropic API 和 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 连接上不活跃，其中 Claude Code 自己的字节级流监视程序运行，在所有其他提供商上活跃，包括 [Vertex AI](/zh-CN/google-vertex-ai)、[Foundry](/zh-CN/microsoft-foundry)、[Mantle](/zh-CN/amazon-bedrock#use-the-mantle-endpoint)、[Bedrock](/zh-CN/amazon-bedrock) 和网关连接，因此停滞的流会中止而不是挂起。从 v2.1.169 开始 |141| `API_FORCE_IDLE_TIMEOUT` | 覆盖 5 分钟空闲超时，该超时在没有字节到达时中止流式模型响应。设置为 `0` 以禁用超时，例如当缓慢的[网关](/zh-CN/llm-gateway)或本地模型在块之间暂停超过 5 分钟时。设置为 `1` 以在每个提供商上保持超时。未设置时，超时在直接 Anthropic API 和 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 连接上不活跃，其中 Claude Code 自己的字节级流监视程序运行，在所有其他提供商上活跃，包括 [Google Cloud's Agent Platform](/zh-CN/google-vertex-ai)、[Microsoft Foundry](/zh-CN/microsoft-foundry)、[Mantle](/zh-CN/amazon-bedrock#use-the-mantle-endpoint)、[Amazon Bedrock](/zh-CN/amazon-bedrock) 和网关连接，因此停滞的流会中止而不是挂起。从 v2.1.169 开始 |

141| `API_TIMEOUT_MS` | API 请求的超时时间（以毫秒为单位）（默认值：600000，或 10 分钟；最大值：2147483647）。在缓慢网络上请求超时或通过代理路由时增加此值。超过最大值的值会导致底层计时器溢出，导致请求立即失败 |142| `API_TIMEOUT_MS` | API 请求的超时时间（以毫秒为单位）（默认值：600000，或 10 分钟；最大值：2147483647）。在缓慢网络上请求超时或通过代理路由时增加此值。超过最大值的值会导致底层计时器溢出，导致请求立即失败 |

142| `AWS_BEARER_TOKEN_BEDROCK` | 用于身份验证的 Bedrock API 密钥（请参阅 [Bedrock API 密钥](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |143| `AWS_BEARER_TOKEN_BEDROCK` | 用于身份验证的 Amazon Bedrock API 密钥（请参阅 [Amazon Bedrock API 密钥](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |

144| `BASH_MAX_OUTPUT_LENGTH` | bash 输出中的最大字符数，超过此数字后将完整输出保存到文件，Claude 接收路径加上简短预览。请参阅 [Bash 工具行为](/zh-CN/tools-reference#bash-tool-behavior) |145| `BASH_MAX_OUTPUT_LENGTH` | bash 输出中的最大字符数，超过此数字后将完整输出保存到文件，Claude 接收路径加上简短预览。请参阅 [Bash 工具行为](/zh-CN/tools-reference#bash-tool-behavior) |

146| `CCR_FORCE_BUNDLE` | 设置为 `1` 以强制 [`claude --remote`](/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) 捆绑并上传您的本地存储库，即使 GitHub 访问可用 |147| `CCR_FORCE_BUNDLE` | 设置为 `1` 以强制 [`claude --cloud`](/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) 捆绑并上传您的本地存储库，即使 GitHub 访问可用 |

147| `CLAUDECODE` | 在 Claude Code 生成的子进程中设置为 `1`（Bash 和 PowerShell 工具、tmux 会话、[hook](/zh-CN/hooks) 命令、[状态行](/zh-CN/statusline)命令、stdio [MCP server](/zh-CN/mcp) 子进程）。IDE 扩展也在其集成终端中设置此选项。用于检测脚本何时在 Claude Code 生成的子进程内运行。要检查当前进程是否由工具调用或 hook 直接生成，而不是在 Claude Code 启动的 stdio MCP 服务器内，请改用 `CLAUDE_CODE_CHILD_SESSION` |148| `CLAUDECODE` | 在 Claude Code 生成的子进程中设置为 `1`（Bash 和 PowerShell 工具、tmux 会话、[hook](/zh-CN/hooks) 命令、[状态行](/zh-CN/statusline)命令、stdio [MCP server](/zh-CN/mcp) 子进程）。IDE 扩展也在其集成终端中设置此选项。用于检测脚本何时在 Claude Code 生成的子进程内运行。要检查当前进程是否由工具调用或 hook 直接生成，而不是在 Claude Code 启动的 stdio MCP 服务器内，请改用 `CLAUDE_CODE_CHILD_SESSION` |

148| `CLAUDE_AFK_COUNTDOWN_MS` | 自动继续前屏幕倒计时出现在未回答的 `AskUserQuestion` 对话框上的毫秒数。默认 `20000`（20 秒）。请参阅 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更高版本 |149| `CLAUDE_AFK_COUNTDOWN_MS` | 自动继续前屏幕倒计时出现在未回答的 [`AskUserQuestion`](/zh-CN/tools-reference) 对话框上的毫秒数。默认 `20000`（20 秒），上限为自动继续超时。除非启用自动继续，否则无效；请参阅 [`askUserQuestionTimeout`](/zh-CN/settings#available-settings) 设置和 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更高版本 |

149| `CLAUDE_AFK_TIMEOUT_MS` | 未回答的 [`AskUserQuestion`](/zh-CN/tools-reference) 对话框自动继续前的空闲时间（以毫秒为单位）。默认 `60000`（60 秒）。要在您离开时保持问题打开，请设置大值如 `86400000`（24 小时）。设置 `0` 不会关闭超时；它会立即关闭对话框。需要 Claude Code v2.1.198 或更高版本 |150| `CLAUDE_AFK_TIMEOUT_MS` | 未回答的 [`AskUserQuestion`](/zh-CN/tools-reference) 对话框自动继续前的空闲时间（以毫秒为单位）。自动继续默认关闭；使用 [`askUserQuestionTimeout`](/zh-CN/settings#available-settings) 设置选择加入。此变量是演示和自动化测试的覆盖：设置后，它优先于该设置并打开自动继续，即使设置未设置或为 `never`。设置 `0` 不会关闭超时；它会立即关闭对话框。在 v2.1.198 和 v2.1.199 中，自动继续默认启用，超时为 `60000`（60 秒）。需要 Claude Code v2.1.198 或更高版本 |

150| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 设置为 `1` 以禁用所有内置 [subagent](/zh-CN/sub-agents) 类型，如 Explore 和 Plan。仅适用于非交互模式（`-p` 标志）。对于想要空白状态的 SDK 用户很有用 |151| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 设置为 `1` 以禁用所有内置 [subagent](/zh-CN/sub-agents) 类型，如 Explore 和 Plan。仅适用于非交互模式（`-p` 标志）。对于想要空白状态的 SDK 用户很有用 |

152| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 后台 subagents 的停滞超时（以毫秒为单位）。默认 `600000`（10 分钟）。计时器在每个流式进度事件时重置；如果在窗口内没有进度到达，subagent 会被中止，任务被标记为失败，将任何部分结果呈现给父级 |153| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 后台 subagents 的停滞超时（以毫秒为单位）。默认 `600000`（10 分钟）。计时器在每个流式进度事件时重置；如果在窗口内没有进度到达，subagent 会被中止，任务被标记为失败，将任何部分结果呈现给父级 |

184| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 设置为 `1` 以禁用所有后台任务功能，包括 Bash 和 subagent 工具上的 `run_in_background` 参数、自动后台处理和 Ctrl+B 快捷键 |185| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 设置为 `1` 以禁用所有后台任务功能，包括 Bash 和 subagent 工具上的 `run_in_background` 参数、自动后台处理和 Ctrl+B 快捷键 |

185| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 设置为 `1` 以在[监督员](/zh-CN/agent-view#the-supervisor-process)停止、重启或更新该会话的进程时停止[后台会话](/zh-CN/agent-view)的运行后台 shell 命令、动态工作流和（从 v2.1.198 开始）后台 subagents，而不是将它们交给会话的下一个进程。仅影响该交接：使用 `←` 或 [`/background`](/zh-CN/agent-view#from-inside-a-session) 后台处理会话仍会进行中的工作，`CLAUDE_DISABLE_ADOPT` 关闭两者。需要 Claude Code v2.1.196 或更高版本 |186| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 设置为 `1` 以在[监督员](/zh-CN/agent-view#the-supervisor-process)停止、重启或更新该会话的进程时停止[后台会话](/zh-CN/agent-view)的运行后台 shell 命令、动态工作流和（从 v2.1.198 开始）后台 subagents，而不是将它们交给会话的下一个进程。仅影响该交接：使用 `←` 或 [`/background`](/zh-CN/agent-view#from-inside-a-session) 后台处理会话仍会进行中的工作，`CLAUDE_DISABLE_ADOPT` 关闭两者。需要 Claude Code v2.1.196 或更高版本 |

186| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 设置为 `1` 以停止 Claude Code 在操作系统报告内存压力时终止[后台 shell 命令](/zh-CN/interactive-mode#background-bash-commands)。默认情况下，在 macOS 和 Linux 上，Claude Code 在会话空闲 30 分钟且没有转换或 subagent 运行后，在内存压力信号上终止在主会话中启动的后台 shell。Windows 没有内存压力信号，因此此变量对其无效。需要 Claude Code v2.1.193 或更高版本 |187| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 设置为 `1` 以停止 Claude Code 在操作系统报告内存压力时终止[后台 shell 命令](/zh-CN/interactive-mode#background-bash-commands)。默认情况下，在 macOS 和 Linux 上，Claude Code 在会话空闲 30 分钟且没有转换或 subagent 运行后，在内存压力信号上终止在主会话中启动的后台 shell。Windows 没有内存压力信号，因此此变量对其无效。需要 Claude Code v2.1.193 或更高版本 |

187| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 设置为 `1` 以禁用 Claude Code 附带的 [skills](/zh-CN/skills) 和工作流：捆绑的 skills 和工作流被完全删除，而内置的斜杠命令如 `/init` 保持可输入但对模型隐藏。来自插件、`.claude/skills/` 和 `.claude/commands/` 的 skills 不受影响。等同于 [`disableBundledSkills`](/zh-CN/settings#available-settings) 设置；`0` 不会覆盖它 |188| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 设置为 `1` 以禁用 Claude Code 附带的 [skills](/zh-CN/skills) 和工作流：捆绑的 skills 和工作流被完全删除，而内置的斜杠命令如 `/init` 保持可输入但对模型隐藏。`/doctor` 保持可输入，如内置命令；使用 `DISABLE_DOCTOR_COMMAND` 隐藏它。来自插件、`.claude/skills/` 和 `.claude/commands/` 的 skills 不受影响。等同于 [`disableBundledSkills`](/zh-CN/settings#available-settings) 设置；`0` 不会覆盖它 |

189| `CLAUDE_CODE_DISABLE_CRON` | 设置为 `1` 以禁用[计划任务](/zh-CN/scheduled-tasks)。`/loop` skill 和 cron 工具变为不可用，任何已计划的任务停止触发，包括已在会话中运行的任务 |190| `CLAUDE_CODE_DISABLE_CRON` | 设置为 `1` 以禁用[计划任务](/zh-CN/scheduled-tasks)。`/loop` skill 和 cron 工具变为不可用，任何已计划的任务停止触发，包括已在会话中运行的任务 |

190| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 设置为 `1` 以从 API 请求中删除 Anthropic 特定的 `anthropic-beta` 请求标头和 beta 工具架构字段（如 `defer_loading` 和 `eager_input_streaming`）。当代理网关拒绝请求并出现"Unexpected value(s) for the `anthropic-beta` header"或"Extra inputs are not permitted"之类的错误时，请使用此选项。标准字段（`name`、`description`、`input_schema`、`cache_control`）被保留 |191| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 设置为 `1` 以从 API 请求中删除 Anthropic 特定的 `anthropic-beta` 请求标头和 beta 工具架构字段（如 `defer_loading` 和 `eager_input_streaming`）。当代理网关拒绝请求并出现"Unexpected value(s) for the `anthropic-beta` header"或"Extra inputs are not permitted"之类的错误时，请使用此选项。标准字段（`name`、`description`、`input_schema`、`cache_control`）被保留 |

193| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 设置为 `1` 以禁用"Claude 表现如何？"会话质量调查。在设置 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时也会禁用调查，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 选择重新启用。要设置样本率而不是完全禁用，请使用 [`feedbackSurveyRate`](/zh-CN/settings#available-settings) 设置。请参阅[会话质量调查](/zh-CN/data-usage#session-quality-surveys) |194| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 设置为 `1` 以禁用"Claude 表现如何？"会话质量调查。在设置 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时也会禁用调查，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 选择重新启用。要设置样本率而不是完全禁用，请使用 [`feedbackSurveyRate`](/zh-CN/settings#available-settings) 设置。请参阅[会话质量调查](/zh-CN/data-usage#session-quality-surveys) |

195| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 设置为 `1` 以从 Claude 的系统提示中删除内置的提交和 PR 工作流说明和 git 状态快照。在使用您自己的 git 工作流 skills 时很有用。设置后优先于 [`includeGitInstructions`](/zh-CN/settings#available-settings) 设置 |196| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 设置为 `1` 以从 Claude 的系统提示中删除内置的提交和 PR 工作流说明和 git 状态快照。在使用您自己的 git 工作流 skills 时很有用。设置后优先于 [`includeGitInstructions`](/zh-CN/settings#available-settings) 设置 |

196| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 设置为 `1` 以防止在 Anthropic API 上自动重新映射 Opus 4.0 和 4.1 到当前 Opus 版本。当您想要有意固定较旧的模型时使用。重新映射不在 Bedrock、Vertex 或 Foundry 上运行 |197| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 设置为 `1` 以防止在 Anthropic API 上自动重新映射 Opus 4.0 和 4.1 到当前 Opus 版本。当您想要有意固定较旧的模型时使用。重新映射不在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上运行 |

197| `CLAUDE_CODE_DISABLE_MOUSE` | 设置为 `1` 以禁用[全屏渲染](/zh-CN/fullscreen)中的鼠标跟踪。使用 `PgUp` 和 `PgDn` 的键盘滚动仍然有效。使用此选项可保持终端的原生选择复制行为 |198| `CLAUDE_CODE_DISABLE_MOUSE` | 设置为 `1` 以禁用[全屏渲染](/zh-CN/fullscreen)中的鼠标跟踪。使用 `PgUp` 和 `PgDn` 的键盘滚动仍然有效。使用此选项可保持终端的原生选择复制行为 |

198| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 设置为 `1` 以禁用[全屏渲染](/zh-CN/fullscreen)中的点击、拖动和悬停处理，同时保持鼠标滚轮滚动。当您希望滚轮滚动在 Claude Code 内工作但不希望点击定位光标、展开工具输出或打开链接时使用此选项。当两者都设置时，`CLAUDE_CODE_DISABLE_MOUSE` 优先。需要 Claude Code v2.1.195 或更高版本 |199| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 设置为 `1` 以禁用[全屏渲染](/zh-CN/fullscreen)中的点击、拖动和悬停处理，同时保持鼠标滚轮滚动。当您希望滚轮滚动在 Claude Code 内工作但不希望点击定位光标、展开工具输出或打开链接时使用此选项。当两者都设置时，`CLAUDE_CODE_DISABLE_MOUSE` 优先。需要 Claude Code v2.1.195 或更高版本 |

199| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 等同于设置 `DISABLE_AUTOUPDATER`、`DISABLE_FEEDBACK_COMMAND`、`DISABLE_ERROR_REPORTING` 和 `DISABLE_TELEMETRY` |200| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 等同于设置 `DISABLE_AUTOUPDATER`、`DISABLE_FEEDBACK_COMMAND`、`DISABLE_ERROR_REPORTING` 和 `DISABLE_TELEMETRY` |

206| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 设置为 `1` 以禁用[全屏渲染](/zh-CN/fullscreen)中的虚拟滚动并渲染转录中的每条消息。如果全屏模式中的滚动显示应该出现消息的空白区域，请使用此选项 |207| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 设置为 `1` 以禁用[全屏渲染](/zh-CN/fullscreen)中的虚拟滚动并渲染转录中的每条消息。如果全屏模式中的滚动显示应该出现消息的空白区域，请使用此选项 |

207| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 设置为 `1` 以禁用[工作流](/zh-CN/workflows#turn-workflows-off)。等同于 [`disableWorkflows`](/zh-CN/settings#available-settings) 设置 |208| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 设置为 `1` 以禁用[工作流](/zh-CN/workflows#turn-workflows-off)。等同于 [`disableWorkflows`](/zh-CN/settings#available-settings) 设置 |

208| `CLAUDE_CODE_EFFORT_LEVEL` | 为支持的模型设置努力级别。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型默认值。可用级别取决于模型。优先于 `/effort` 和 `effortLevel` 设置。请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level) |209| `CLAUDE_CODE_EFFORT_LEVEL` | 为支持的模型设置努力级别。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型默认值。可用级别取决于模型。优先于 `/effort` 和 `effortLevel` 设置。请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level) |

209| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 设置为 `1` 以在 Amazon Bedrock、Google Cloud Vertex AI、Microsoft Foundry 和已登录的 [Claude apps 网关](/zh-CN/claude-apps-gateway)会话上提供[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)。需要 Claude Code v2.1.158 或更高版本。对 Anthropic API 无效，自动模式在那里默认可用。请参阅[在 Bedrock、Vertex AI 或 Foundry 上启用自动模式](/zh-CN/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry) |210| `CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT` | 设置为 `1` 以启用将额外文本附加到每个 [subagent](/zh-CN/sub-agents) 系统提示的末尾。[`--append-subagent-system-prompt`](/zh-CN/cli-reference#cli-flags) 标志提供附加的文本并自动设置此变量，因此您不需要自己设置它。需要 Claude Code v2.1.205 或更高版本 |

211| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 设置为 `1` 以在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和已登录的 [Claude apps 网关](/zh-CN/claude-apps-gateway)会话上提供[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)。需要 Claude Code v2.1.158 或更高版本。对 Anthropic API 无效，自动模式在那里默认可用。请参阅[在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上启用自动模式](/zh-CN/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry) |

210| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆盖[会话回顾](/zh-CN/interactive-mode#session-recap)可用性。设置为 `0` 以强制关闭回顾，无论 `/config` 切换如何。设置为 `1` 以在 [`awaySummaryEnabled`](/zh-CN/settings#available-settings) 为 `false` 时强制启用回顾。优先于设置和 `/config` 切换 |212| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆盖[会话回顾](/zh-CN/interactive-mode#session-recap)可用性。设置为 `0` 以强制关闭回顾，无论 `/config` 切换如何。设置为 `1` 以在 [`awaySummaryEnabled`](/zh-CN/settings#available-settings) 为 `false` 时强制启用回顾。优先于设置和 `/config` 切换 |

211| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 设置为 `1` 以在[非交互模式](/zh-CN/headless)中的转换边界处刷新插件状态，在后台安装完成后。默认关闭，因为刷新会在会话中途更改系统提示，这会使该转换的 [prompt caching](/zh-CN/prompt-caching) 失效 |213| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 设置为 `1` 以在[非交互模式](/zh-CN/headless)中的转换边界处刷新插件状态，在后台安装完成后。默认关闭，因为刷新会在会话中途更改系统提示，这会使该转换的 [prompt caching](/zh-CN/prompt-caching) 失效 |

212| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 设置为 `1` 以在 Anthropic 绑定的非必要流量被阻止时将"Claude 表现如何？"会话质量调查路由到您自己的 [OpenTelemetry 收集器](/zh-CN/monitoring-usage)。调查评分仅作为 OTEL 事件发送到您配置的收集器。在此模式下，不会向 Anthropic 发送任何调查数据。在设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 时应用，否则无效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和组织产品反馈政策优先 |214| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 设置为 `1` 以在 Anthropic 绑定的非必要流量被阻止时将"Claude 表现如何？"会话质量调查路由到您自己的 [OpenTelemetry 收集器](/zh-CN/monitoring-usage)。调查评分仅作为 OTEL 事件发送到您配置的收集器。在此模式下，不会向 Anthropic 发送任何调查数据。在设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 时应用，否则无效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和组织产品反馈政策优先 |

213| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具调用输入是否在 API 生成时从 API 流式传输。关闭此选项时，大型工具输入（如长文件写入）仅在 Claude 完成生成后才到达，这可能看起来像是挂起。对于 Anthropic API 默认启用。在 Bedrock 和 Vertex 上，按模型启用，其中部署的容器支持它。设置为 `0` 以选择退出。设置为 `1` 以在通过 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 路由到代理时强制启用。对 Foundry 和[网关](/zh-CN/llm-gateway)连接默认关闭 |215| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具调用输入是否在 API 生成时从 API 流式传输。关闭此选项时，大型工具输入（如长文件写入）仅在 Claude 完成生成后才到达，这可能看起来像是挂起。对于 Anthropic API 默认启用。在 Amazon Bedrock 和 Google Cloud's Agent Platform 上，按模型启用，其中部署的容器支持它。设置为 `0` 以选择退出。设置为 `1` 以在通过 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 路由到代理时强制启用。对 Microsoft Foundry 和[网关](/zh-CN/llm-gateway)连接默认关闭 |

214| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 设置为 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 兼容网关（如 LiteLLM、Kong 或内部代理）时从网关的 `/v1/models` 端点填充 `/model` 选择器。默认关闭，因为由共享 API 密钥支持的网关会显示该密钥可以访问的每个用户的每个模型。发现的模型仍由 [`availableModels`](/zh-CN/settings#available-settings) 允许列表过滤，会话接收；通过 [MDM 或托管设置文件](/zh-CN/settings#settings-files)传递列表，因为[服务器管理的交付在网关配置上不可用](/zh-CN/server-managed-settings#platform-availability) |216| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 设置为 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 兼容网关（如 LiteLLM、Kong 或内部代理）时从网关的 `/v1/models` 端点填充 `/model` 选择器。默认关闭，因为由共享 API 密钥支持的网关会显示该密钥可以访问的每个用户的每个模型。发现的模型仍由 [`availableModels`](/zh-CN/settings#available-settings) 允许列表过滤，会话接收；通过 [MDM 或托管设置文件](/zh-CN/settings#settings-files)传递列表，因为[服务器管理的交付在网关配置上不可用](/zh-CN/server-managed-settings#platform-availability) |

216| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 设置为 `false` 以禁用提示建议（`/config` 中的"提示建议"切换）。这些是在 Claude 响应后出现在提示输入中的灰显预测。请参阅[提示建议](/zh-CN/interactive-mode#prompt-suggestions) |218| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 设置为 `false` 以禁用提示建议（`/config` 中的"提示建议"切换）。这些是在 Claude 响应后出现在提示输入中的灰显预测。请参阅[提示建议](/zh-CN/interactive-mode#prompt-suggestions) |

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

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

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

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

260| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 设置为 `1` 以停止 Claude Code 在生成 PowerShell 以进行工具调用、hooks 和状态行命令时传递 `-ExecutionPolicy Bypass`，并改为尊重机器的有效执行策略。默认情况下，Claude Code 在进程范围内绕过执行策略，以便 `.ps1` 脚本和模块导入在默认受限的 Windows 安装上工作。无论此设置如何，进程范围的绕过永远不会覆盖组策略 `MachinePolicy` 或 `UserPolicy` |262| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 设置为 `1` 以停止 Claude Code 在生成 PowerShell 以进行工具调用、hooks 和状态行命令时传递 `-ExecutionPolicy Bypass`，并改为尊重机器的有效执行策略。默认情况下，Claude Code 在进程范围内绕过执行策略，以便 `.ps1` 脚本和模块导入在默认受限的 Windows 安装上工作。无论此设置如何，进程范围的绕过永远不会覆盖组策略 `MachinePolicy` 或 `UserPolicy` |

261| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | [非交互模式](/zh-CN/headless#background-tasks-at-exit)中带有 `-p` 标志的最大时间（以毫秒为单位），在最后一个转换后等待其结果是输出一部分的后台 subagents 和工作流。默认值：`600000`，或 10 分钟。超过上限时，剩余的后台任务被终止，进程退出。设置为 `0` 以无限期等待。此上限与适用于纯后台 shells 的 5 秒宽限期分开 |263| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | [非交互模式](/zh-CN/headless#background-tasks-at-exit)中带有 `-p` 标志的最大时间（以毫秒为单位），在最后一个转换后等待其结果是输出一部分的后台 subagents 和工作流。默认值：`600000`，或 10 分钟。超过上限时，剩余的后台任务被终止，进程退出。设置为 `0` 以无限期等待。此上限与适用于纯后台 shells 的 5 秒宽限期分开 |

262| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 设置为 `1` 以在 `ANTHROPIC_BASE_URL` 指向自定义代理时传播 W3C 跟踪上下文。传播涵盖模型和 HTTP MCP 请求上的 `traceparent` 标头以及 Bash、PowerShell 和 hook 子进程的 `TRACEPARENT` 环境变量。默认情况下，仅当直接连接到 Anthropic API 时才启用传播。在 v2.1.152 中添加。请参阅[跟踪（测试版）](/zh-CN/monitoring-usage#traces-beta) |264| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 设置为 `1` 以在 `ANTHROPIC_BASE_URL` 指向自定义代理时传播 W3C 跟踪上下文。传播涵盖模型和 HTTP MCP 请求上的 `traceparent` 标头以及 Bash、PowerShell 和 hook 子进程的 `TRACEPARENT` 环境变量。默认情况下，仅当直接连接到 Anthropic API 时才启用传播。在 v2.1.152 中添加。请参阅[跟踪（测试版）](/zh-CN/monitoring-usage#traces-beta) |

263| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 的主机平台设置，并代表其管理模型提供商路由。设置后，提供商选择、端点和身份验证变量（如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`）在设置文件中被忽略，以便用户设置无法覆盖主机的路由。Bedrock、Vertex 和 Foundry 的自动遥测选择退出也被跳过，因此遥测遵循标准 `DISABLE_TELEMETRY` 选择退出。请参阅[按 API 提供商的默认行为](/zh-CN/data-usage#default-behaviors-by-api-provider) |265| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 的主机平台设置，并代表其管理模型提供商路由。设置后，提供商选择、端点和身份验证变量（如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`）在设置文件中被忽略，以便用户设置无法覆盖主机的路由。Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 的自动遥测选择退出也被跳过，因此遥测遵循标准 `DISABLE_TELEMETRY` 选择退出。请参阅[按 API 提供商的默认行为](/zh-CN/data-usage#default-behaviors-by-api-provider) |

266| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[云会话](/zh-CN/claude-code-on-the-web)中自动设置为当前会话的 ID。读取此值以构造返回会话转录的链接。请参阅[将输出链接回会话](/zh-CN/claude-code-on-the-web#link-output-back-to-the-session) |268| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[云会话](/zh-CN/claude-code-on-the-web)中自动设置为当前会话的 ID。读取此值以构造返回会话转录的链接。请参阅[将输出链接回会话](/zh-CN/claude-code-on-the-web#link-output-back-to-the-session) |

277| `CLAUDE_CODE_SIMPLE` | 设置为 `1` 以使用最小系统提示和仅 Bash、文件读取和文件编辑工具运行。MCP 工具来自 `--mcp-config` 仍然可用。禁用 hooks、skills、plugins、MCP servers、自动内存和 CLAUDE.md 的自动发现。OAuth 令牌和钥匙链凭证不被读取，所以 Anthropic 身份验证必须来自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同于传递 [`--bare`](/zh-CN/headless#start-faster-with-bare-mode) |279| `CLAUDE_CODE_SIMPLE` | 设置为 `1` 以使用最小系统提示和仅 Bash、文件读取和文件编辑工具运行。MCP 工具来自 `--mcp-config` 仍然可用。禁用 hooks、skills、plugins、MCP servers、自动内存和 CLAUDE.md 的自动发现。OAuth 令牌和钥匙链凭证不被读取，所以 Anthropic 身份验证必须来自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同于传递 [`--bare`](/zh-CN/headless#start-faster-with-bare-mode) |

278| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 设置为 `1` 以在任何模型上使用较短的系统提示和缩写的工具描述。设置为 `0`、`false`、`no` 或 `off` 以选择退出，即使在实验或服务器配置会以其他方式启用它的模型上。完整的工具集、hooks、MCP 服务器和 CLAUDE.md 发现保持启用 |280| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 设置为 `1` 以在任何模型上使用较短的系统提示和缩写的工具描述。设置为 `0`、`false`、`no` 或 `off` 以选择退出，即使在实验或服务器配置会以其他方式启用它的模型上。完整的工具集、hooks、MCP 服务器和 CLAUDE.md 发现保持启用 |

279| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 跳过 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 的客户端身份验证，用于自己签署请求的网关 |281| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 跳过 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 的客户端身份验证，用于自己签署请求的网关 |

281| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 跳过 Microsoft Foundry 的 Azure 身份验证。对于网关，请改为在 `ANTHROPIC_FOUNDRY_API_KEY` 中设置凭证；没有 API 密钥，此变量会使 Foundry 客户端无法发送请求 |283| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 跳过 Microsoft Foundry 的 Azure 身份验证，用于代理或网关，这些代理或网关注入自己的 `Authorization` 标头。Claude Code 发送没有 Azure 凭证的请求，并保留您提供的 `Authorization` 标头，例如通过 `ANTHROPIC_CUSTOM_HEADERS`。当设置 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 时被忽略。在 v2.1.203 之前，此变量使 Microsoft Foundry 客户端无法在没有同时设置 API 密钥的情况下发送请求 |

283| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 设置为 `1` 以跳过将提示历史和会话转录写入磁盘。使用此变量启动的会话不会出现在 `--resume`、`--continue` 或向上箭头历史中。对于临时脚本会话很有用 |285| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 设置为 `1` 以跳过将提示历史和会话转录写入磁盘。使用此变量启动的会话不会出现在 `--resume`、`--continue` 或向上箭头历史中。对于临时脚本会话很有用 |

285| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/zh-CN/hooks#stop) 或 [SubagentStop](/zh-CN/hooks#subagentstop) hook 可能在 Claude Code 覆盖它并无论如何结束转换之前阻止转换结束的最大连续次数（默认值：8）。设置为 `0` 以禁用上限。如果您的 hook 合法需要更多迭代来解决，请提高此值 |287| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/zh-CN/hooks#stop) 或 [SubagentStop](/zh-CN/hooks#subagentstop) hook 可能在 Claude Code 覆盖它并无论如何结束转换之前阻止转换结束的最大连续次数（默认值：8）。设置为 `0` 以禁用上限。如果您的 hook 合法需要更多迭代来解决，请提高此值 |

286| `CLAUDE_CODE_SUBAGENT_MODEL` | 请参阅[模型配置](/zh-CN/model-config)。从 v2.1.196 开始，将其设置为 `inherit` 与不设置相同；较早的版本将 `inherit` 视为覆盖，强制每个 subagent 进入主对话的模型 |288| `CLAUDE_CODE_SUBAGENT_MODEL` | 请参阅[模型配置](/zh-CN/model-config)。从 v2.1.196 开始，将其设置为 `inherit` 与不设置相同；较早的版本将 `inherit` 视为覆盖，强制每个 subagent 进入主对话的模型 |

287| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 设置为 `1` 以从子进程环境（Bash 工具、hooks、MCP stdio 服务器）中删除 Anthropic 和云提供商凭证。父 Claude 进程为 API 调用保留这些凭证，但子进程无法读取它们，减少了通过 shell 扩展尝试窃取机密的提示注入攻击的暴露。在 Linux 上，这也在隔离的 PID 命名空间中运行 Bash 子进程，以便它们无法通过 `/proc` 读取主机进程环境；作为副作用，`ps`、`pgrep` 和 `kill` 无法看到或信号主机进程。当配置了 `allowed_non_write_users` 时，`claude-code-action` 会自动设置此选项 |289| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 设置为 `1` 以从子进程环境（Bash 工具、hooks、MCP stdio 服务器）中删除 Anthropic 和云提供商凭证。父 Claude 进程为 API 调用保留这些凭证，但子进程无法读取它们，减少了通过 shell 扩展尝试窃取机密的提示注入攻击的暴露。在 Linux 上，这也在隔离的 PID 命名空间中运行 Bash 子进程，以便它们无法通过 `/proc` 读取主机进程环境；作为副作用，`ps`、`pgrep` 和 `kill` 无法看到或信号主机进程。当配置了 `allowed_non_write_users` 时，`claude-code-action` 会自动设置此选项 |

296| `CLAUDE_CODE_TMPDIR` | 覆盖用于内部临时文件的临时目录。Claude Code 将 `/claude-{uid}/`（Unix）或 `/claude/`（Windows）附加到此路径。默认值：macOS 上为 `/tmp`，Linux/Windows 上为 `os.tmpdir()`。从 v2.1.161 开始，在 macOS 和 Linux 上，[沙箱化](/zh-CN/sandboxing) Bash 子进程在系统默认值下接收短回退 `$TMPDIR`，当您的覆盖是长路径时，因为某些工具在临时路径过长时会失败。未沙箱化的 Bash 命令继承您的 shell 的 `$TMPDIR` 不变。Claude Code 自己的临时文件始终使用您的覆盖 |298| `CLAUDE_CODE_TMPDIR` | 覆盖用于内部临时文件的临时目录。Claude Code 将 `/claude-{uid}/`（Unix）或 `/claude/`（Windows）附加到此路径。默认值：macOS 上为 `/tmp`，Linux/Windows 上为 `os.tmpdir()`。从 v2.1.161 开始，在 macOS 和 Linux 上，[沙箱化](/zh-CN/sandboxing) Bash 子进程在系统默认值下接收短回退 `$TMPDIR`，当您的覆盖是长路径时，因为某些工具在临时路径过长时会失败。未沙箱化的 Bash 命令继承您的 shell 的 `$TMPDIR` 不变。Claude Code 自己的临时文件始终使用您的覆盖 |

297| `CLAUDE_CODE_TMUX_TRUECOLOR` | 设置为 `1` 以允许 tmux 内的 24 位真彩色输出。默认情况下，当设置 `$TMUX` 时，Claude Code 限制为 256 色，因为 tmux 不会通过真彩色转义序列，除非配置为这样做。在将 `set -ga terminal-overrides ',*:Tc'` 添加到您的 `~/.tmux.conf` 后设置此选项。请参阅[终端配置](/zh-CN/terminal-config)了解其他 tmux 设置 |299| `CLAUDE_CODE_TMUX_TRUECOLOR` | 设置为 `1` 以允许 tmux 内的 24 位真彩色输出。默认情况下，当设置 `$TMUX` 时，Claude Code 限制为 256 色，因为 tmux 不会通过真彩色转义序列，除非配置为这样做。在将 `set -ga terminal-overrides ',*:Tc'` 添加到您的 `~/.tmux.conf` 后设置此选项。请参阅[终端配置](/zh-CN/terminal-config)了解其他 tmux 设置 |

302| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 设置为 `1` 以使用 Node.js 文件 API 而不是 ripgrep 发现自定义命令、subagents 和输出样式。如果捆绑的 ripgrep 二进制文件在您的环境中不可用或被阻止，请设置此选项。不影响 Grep 或文件搜索工具 |304| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 设置为 `1` 以使用 Node.js 文件 API 而不是 ripgrep 发现自定义命令、subagents 和输出样式。如果捆绑的 ripgrep 二进制文件在您的环境中不可用或被阻止，请设置此选项。不影响 Grep 或文件搜索工具 |

303| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在没有 Git Bash 的 Windows 上，该工具会自动启用；设置为 `0` 以禁用它。在安装了 Git Bash 的 Windows 上，该工具正在逐步推出：设置为 `1` 以选择加入或 `0` 以选择退出。在 Linux、macOS 和 WSL 上，设置为 `1` 以启用它，这需要您的 `PATH` 上有 `pwsh`。在 Windows 上启用时，Claude 可以本地运行 PowerShell 命令，而不是通过 Git Bash 路由。请参阅 [PowerShell 工具](/zh-CN/tools-reference#powershell-tool) |305| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在没有 Git Bash 的 Windows 上，该工具会自动启用；设置为 `0` 以禁用它。在安装了 Git Bash 的 Windows 上，该工具正在逐步推出：设置为 `1` 以选择加入或 `0` 以选择退出。在 Linux、macOS 和 WSL 上，设置为 `1` 以启用它，这需要您的 `PATH` 上有 `pwsh`。在 Windows 上启用时，Claude 可以本地运行 PowerShell 命令，而不是通过 Git Bash 路由。请参阅 [PowerShell 工具](/zh-CN/tools-reference#powershell-tool) |

305| `CLAUDE_CONFIG_DIR` | 覆盖配置目录（默认值：`~/.claude`）。所有设置、凭证、会话历史和插件都存储在此路径下。对于并行运行多个帐户很有用：例如，`alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |307| `CLAUDE_CONFIG_DIR` | 覆盖配置目录（默认值：`~/.claude`）。所有设置、凭证、会话历史和插件都存储在此路径下。对于并行运行多个帐户很有用：例如，`alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |

306| `CLAUDE_DISABLE_ADOPT` | 设置为 `1` 以在您通过按 `←` 或使用 [`/background`](/zh-CN/agent-view#from-inside-a-session) 后台处理会话时停止进行中的后台工作，而不是进行中的工作。Claude Code 要求您在后台处理前确认，然后停止会以其他方式进行的任务。需要 Claude Code v2.1.195 或更高版本 |308| `CLAUDE_DISABLE_ADOPT` | 设置为 `1` 以在您通过按 `←` 或使用 [`/background`](/zh-CN/agent-view#from-inside-a-session) 后台处理会话时停止进行中的后台工作，而不是进行中的工作。Claude Code 要求您在后台处理前确认，然后停止会以其他方式进行的任务。需要 Claude Code v2.1.195 或更高版本 |

307| `CLAUDE_EFFORT` | 在 Bash 工具子进程和 hook 命令中自动设置为该转换的活动[努力级别](/zh-CN/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是一个不同的级别，报告为 `xhigh`。与传递给 [hooks](/zh-CN/hooks) 的 `effort.level` 字段匹配。仅在当前模型支持努力参数时设置 |309| `CLAUDE_EFFORT` | 在 Bash 工具子进程和 hook 命令中自动设置为该转换的活动[努力级别](/zh-CN/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是一个不同的级别，报告为 `xhigh`。与传递给 [hooks](/zh-CN/hooks) 的 `effort.level` 字段匹配。仅在当前模型支持努力参数时设置 |

308| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 设置为 `1` 以强制启用字节级流式空闲监视程序，或设置为 `0` 以强制禁用它。未设置时，监视程序对 Anthropic API 和 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 连接默认启用。字节监视程序在 180 秒（直接 Anthropic API 连接）、300 秒（Claude Platform on AWS 和其他提供商）或 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 设置的值（限制为最少 5 分钟）内没有字节到达线路时中止连接，独立于事件级监视程序 |310| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 设置为 `1` 以强制启用字节级流式空闲监视程序，或设置为 `0` 以强制禁用它。未设置时，监视程序对 Anthropic API 和 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 连接默认启用。字节监视程序在 180 秒（直接 Anthropic API 连接）、300 秒（Claude Platform on AWS 和其他提供商）或 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 设置的值（限制为最少 5 分钟）内没有字节到达线路时中止连接，独立于事件级监视程序 |

309| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 设置为 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 响应上启用字节级流式空闲监视程序。默认关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时 |311| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 设置为 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 响应上启用字节级流式空闲监视程序。默认关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时 |

310| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 设置为 `0` 以强制禁用事件级流式空闲监视程序，或设置为 `1` 以强制启用它。未设置时，监视程序对所有提供商默认启用。在 v2.1.196 之前，未设置的默认值在直接 Anthropic API 上由服务器控制，在其他提供商上关闭。从 v2.1.169 开始，直接 Anthropic API 和 Claude Platform on AWS 以外的提供商也有默认启用的 5 分钟体空闲超时，独立于此变量；请参阅 `API_FORCE_IDLE_TIMEOUT`。在 Bedrock 上，您也可以使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` 启用独立的字节级监视程序；当两者都设置时，它们一起运行。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时 |312| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 设置为 `0` 以强制禁用事件级流式空闲监视程序，或设置为 `1` 以强制启用它。未设置时，监视程序对所有提供商默认启用。在 v2.1.196 之前，未设置的默认值在直接 Anthropic API 上由服务器控制，在其他提供商上关闭。从 v2.1.169 开始，直接 Anthropic API 和 Claude Platform on AWS 以外的提供商也有默认启用的 5 分钟体空闲超时，独立于此变量；请参阅 `API_FORCE_IDLE_TIMEOUT`。在 Amazon Bedrock 上，您也可以使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` 启用独立的字节级监视程序；当两者都设置时，它们一起运行。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时 |

311| `CLAUDE_ENV_FILE` | Claude Code 在每个 Bash 命令之前在同一 shell 进程中运行的 shell 脚本的路径，因此文件中的导出对命令可见。用于在命令之间保持 virtualenv 或 conda 激活。也由 [SessionStart](/zh-CN/hooks#persist-environment-variables)、[Setup](/zh-CN/hooks#setup)、[CwdChanged](/zh-CN/hooks#cwdchanged) 和 [FileChanged](/zh-CN/hooks#filechanged) hooks 动态填充 |313| `CLAUDE_ENV_FILE` | Claude Code 在每个 Bash 命令之前在同一 shell 进程中运行的 shell 脚本的路径，因此文件中的导出对命令可见。用于在命令之间保持 virtualenv 或 conda 激活。也由 [SessionStart](/zh-CN/hooks#persist-environment-variables)、[Setup](/zh-CN/hooks#setup)、[CwdChanged](/zh-CN/hooks#cwdchanged) 和 [FileChanged](/zh-CN/hooks#filechanged) hooks 动态填充 |

312| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 当未提供显式名称时，自动生成的[远程控制](/zh-CN/remote-control)会话名称的前缀。默认为您的机器的主机名，生成名称如 `myhost-graceful-unicorn`。`--remote-control-session-name-prefix` CLI 标志为单个调用设置相同的值 |314| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 当未提供显式名称时，自动生成的[远程控制](/zh-CN/remote-control)会话名称的前缀。默认为您的机器的主机名，生成名称如 `myhost-graceful-unicorn`。`--remote-control-session-name-prefix` CLI 标志为单个调用设置相同的值 |

313| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 流式空闲监视程序关闭停滞连接前的超时（以毫秒为单位）。当您明确设置此变量时，最小值为 `300000`（5 分钟）；较低的值被静默限制以吸收扩展思考暂停和代理缓冲。未设置时，事件级监视程序默认为 300 秒，字节级监视程序在直接 Anthropic API 连接上默认为 180 秒（Claude Platform on AWS 和其他提供商上为 300 秒）。未设置的 180 秒字节监视程序默认值是一个单独的值，不受 5 分钟限制。体空闲超时在 `API_FORCE_IDLE_TIMEOUT` 下描述，独立应用。在 Bedrock 上，也在 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` 时应用 |315| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 流式空闲监视程序关闭停滞连接前的超时（以毫秒为单位）。当您明确设置此变量时，最小值为 `300000`（5 分钟）；较低的值被静默限制以吸收扩展思考暂停和代理缓冲。未设置时，事件级监视程序默认为 300 秒，字节级监视程序在直接 Anthropic API 连接上默认为 180 秒（Claude Platform on AWS 和其他提供商上为 300 秒）。未设置的 180 秒字节监视程序默认值是一个单独的值，不受 5 分钟限制。体空闲超时在 `API_FORCE_IDLE_TIMEOUT` 下描述，独立应用。在 Amazon Bedrock 上，也在 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` 时应用 |

314| `DEBUG` | 设置为 `1` 以启用调试模式，等同于使用 [`--debug`](/zh-CN/cli-reference#cli-flags) 启动。调试日志写入 `~/.claude/debug/<session-id>.txt`，或写入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 设置的路径。仅真值 `1`、`true`、`yes` 和 `on` 启用调试模式，因此为其他工具设置的命名空间模式如 `DEBUG=express:*` 不会触发它 |316| `DEBUG` | 设置为 `1` 以启用调试模式，等同于使用 [`--debug`](/zh-CN/cli-reference#cli-flags) 启动。调试日志写入 `~/.claude/debug/<session-id>.txt`，或写入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 设置的路径。仅真值 `1`、`true`、`yes` 和 `on` 启用调试模式，因此为其他工具设置的命名空间模式如 `DEBUG=express:*` 不会触发它 |

319| `DISABLE_DOCTOR_COMMAND` | 设置为 `1` 以隐藏 `/doctor` 命令。对于用户不应运行安装诊断的托管部署很有用 |321| `DISABLE_DOCTOR_COMMAND` | 设置为 `1` 以隐藏 [`/doctor`](/zh-CN/commands#all-commands) 设置检查 skill 及其 `/checkup` 别名。对于用户不应运行设置诊断的托管部署很有用。不影响 `claude doctor` 终端命令。在 v2.1.205 之前，此变量隐藏了 `/doctor` 诊断屏幕命令 |

325| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 设置为 `1` 以隐藏 `/install-github-app` 命令。使用第三方提供商（Bedrock、Vertex 或 Foundry）时已隐藏 |327| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 设置为 `1` 以隐藏 `/install-github-app` 命令。使用第三方提供商（Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry）时已隐藏 |

326| `DISABLE_INTERLEAVED_THINKING` | 设置为 `1` 以防止发送交错思考 beta 标头。当您的 LLM 网关或提供商不支持[交错思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)时很有用 |328| `DISABLE_INTERLEAVED_THINKING` | 设置为 `1` 以防止发送交错思考 beta 标头。当您的 LLM 网关或提供商不支持[交错思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)时很有用 |

338| `ENABLE_CLAUDEAI_MCP_SERVERS` | 设置为 `false` 以禁用 Claude Code 中的 [claude.ai MCP servers](/zh-CN/mcp#use-mcp-servers-from-claude-ai)。对于已登录的用户默认启用。要按项目或按组织禁用，请改用设置中的 [`disableClaudeAiConnectors`](/zh-CN/settings#available-settings) |340| `ENABLE_CLAUDEAI_MCP_SERVERS` | 设置为 `false` 以禁用 Claude Code 中的 [claude.ai MCP servers](/zh-CN/mcp#use-mcp-servers-from-claude-ai)。对于已登录的用户默认启用。要按项目或按组织禁用，请改用设置中的 [`disableClaudeAiConnectors`](/zh-CN/settings#available-settings) |

339| `ENABLE_PROMPT_CACHING_1H` | 设置为 `1` 以请求 1 小时的 prompt cache TTL 而不是默认的 5 分钟。适用于 API 密钥、[Bedrock](/zh-CN/amazon-bedrock)、[Vertex](/zh-CN/google-vertex-ai)、[Foundry](/zh-CN/microsoft-foundry) 和 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 用户。订阅用户自动获得 1 小时 TTL。1 小时缓存写入按更高费率计费 |341| `ENABLE_PROMPT_CACHING_1H` | 设置为 `1` 以请求 1 小时的 prompt cache TTL 而不是默认的 5 分钟。适用于 API 密钥、[Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud's Agent Platform](/zh-CN/google-vertex-ai)、[Microsoft Foundry](/zh-CN/microsoft-foundry) 和 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 用户。订阅用户自动获得 1 小时 TTL。1 小时缓存写入按更高费率计费 |

341| `ENABLE_TOOL_SEARCH` | 控制 [MCP 工具搜索](/zh-CN/mcp#scale-with-mcp-tool-search)。未设置：默认延迟所有 MCP 工具，但在 Vertex AI 上或当 `ANTHROPIC_BASE_URL` 指向非第一方主机时提前加载。值：`true`（始终延迟并发送 beta 标头，在 Vertex AI 上支持 Sonnet 4.5 及更高版本或 Opus 4.5 及更高版本的请求失败，或在不支持 `tool_reference` 的代理上）、`auto`（阈值模式：如果工具适合在上下文的 10% 内则提前加载）、`auto:N`（自定义阈值，例如 `auto:5` 表示 5%）、`false`（提前加载所有） |343| `ENABLE_TOOL_SEARCH` | 控制 [MCP 工具搜索](/zh-CN/mcp#scale-with-mcp-tool-search)。未设置：默认延迟所有 MCP 工具，但在 Google Cloud's Agent Platform 上或当 `ANTHROPIC_BASE_URL` 指向非第一方主机时提前加载。值：`true`（始终延迟并发送 beta 标头，在 Google Cloud's Agent Platform 上支持 Sonnet 4.5 及更高版本或 Opus 4.5 及更高版本的请求失败，或在不支持 `tool_reference` 的代理上）、`auto`（阈值模式：如果工具适合在上下文的 10% 内则提前加载）、`auto:N`（自定义阈值，例如 `auto:5` 表示 5%）、`false`（提前加载所有） |

342| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 设置为任何非空值以在任何主模型上重复过载错误后触发回退。从 v2.1.160 开始，配置的[回退模型链](/zh-CN/model-config#fallback-model-chains)在任何主模型的重复过载错误时触发，因此此变量不影响切换到回退模型 |344| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 设置为任何非空值以在任何主模型上重复过载错误后触发回退。从 v2.1.160 开始，配置的[回退模型链](/zh-CN/model-config#fallback-model-chains)在任何主模型的重复过载错误时触发，因此此变量不影响切换到回退模型 |

358| `MCP_TOOL_TIMEOUT` | MCP 工具执行的超时（以毫秒为单位）（默认值：100000000，约 28 小时）。`.mcp.json` 中的每个服务器 `timeout` 字段会覆盖该服务器的此值。对于 env 变量，低于 1000 的值被限制为一秒；对于每个服务器字段，低于 1000 的值被忽略 |360| `MCP_TOOL_TIMEOUT` | MCP 工具执行的超时（以毫秒为单位）（默认值：100000000，约 28 小时）。`.mcp.json` 中的每个服务器 `timeout` 字段会覆盖该服务器的此值。从 v2.1.203 开始，`.mcp.json` 中至少 1000 的每个服务器 `timeout` 也会将该服务器的工具调用的最小空闲窗口设置为至少 `timeout` 值，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 永远不会更早中止它们；此下限需要 Claude Code v2.1.203 或更高版本。对于 env 变量，低于 1000 的值被限制为一秒；对于每个服务器字段，低于 1000 的值被忽略 |

360| `OTEL_LOG_ASSISTANT_RESPONSES` | 设置为 `1` 以在 `assistant_response` OpenTelemetry 日志事件中包含模型的响应文本。未设置时，使用 `OTEL_LOG_USER_PROMPTS` 的值。设置为 `0` 以在设置 `OTEL_LOG_USER_PROMPTS` 时保持响应编辑。需要 Claude Code v2.1.193 或更高版本。请参阅[监控](/zh-CN/monitoring-usage#assistant-response-event) |362| `OTEL_LOG_ASSISTANT_RESPONSES` | 设置为 `1` 以在 `assistant_response` OpenTelemetry 日志事件中包含模型的响应文本。未设置时，使用 `OTEL_LOG_USER_PROMPTS` 的值。设置为 `0` 以在设置 `OTEL_LOG_USER_PROMPTS` 时保持响应编辑。需要 Claude Code v2.1.193 或更高版本。请参阅[监控](/zh-CN/monitoring-usage#assistant-response-event) |

361| `OTEL_LOG_RAW_API_BODIES` | 设置为 `1` 以将完整的 Anthropic Messages API 请求和响应 JSON 作为 `api_request_body` / `api_response_body` 日志事件发出，截断为 60 KB，或 `file:<dir>` 以将未截断的主体写入磁盘并发出 `body_ref` 路径。默认禁用；主体包括整个对话历史。请参阅[监控](/zh-CN/monitoring-usage#api-request-body-event) |363| `OTEL_LOG_RAW_API_BODIES` | 设置为 `1` 以将完整的 Anthropic Messages API 请求和响应 JSON 作为 `api_request_body` / `api_response_body` 日志事件发出，截断为 60 KB，或 `file:<dir>` 以将未截断的主体写入磁盘并发出 `body_ref` 路径。默认禁用；主体包括整个对话历史。请参阅[监控](/zh-CN/monitoring-usage#api-request-body-event) |

363| `OTEL_LOG_TOOL_DETAILS` | 设置为 `1` 以在 OpenTelemetry 跟踪和日志中包含工具输入参数、MCP 服务器名称、工具失败时的原始错误字符串、`api_refusal` 事件上的拒绝 `category` 和其他工具详情。默认禁用以保护 PII。请参阅[监控](/zh-CN/monitoring-usage) |365| `OTEL_LOG_TOOL_DETAILS` | 设置为 `1` 以在 OpenTelemetry 跟踪和日志中包含工具输入参数、MCP 服务器名称、用户创作的工作流名称、工具失败时的原始错误字符串、`api_refusal` 事件上的拒绝 `category` 和其他工具详情。默认禁用以保护 PII。请参阅[监控](/zh-CN/monitoring-usage) |

370| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆盖显示给 [Skill tool](/zh-CN/skills#control-who-invokes-a-skill) 的 skill 元数据的字符预算。预算在上下文窗口的 1% 处动态扩展，回退为 8,000 个字符。为了向后兼容而保留的旧名称 |372| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆盖显示给 [Skill tool](/zh-CN/skills#control-who-invokes-a-skill) 的 skill 元数据的字符预算。预算在上下文窗口的 1% 处动态扩展，回退为 8,000 个字符。为了向后兼容而保留的旧名称 |

371| `TASK_MAX_OUTPUT_LENGTH` | [subagent](/zh-CN/sub-agents) 输出中的最大字符数，超过此数字后将进行截断（默认值：32000，最大值：160000）。截断时，完整输出保存到磁盘，路径包含在截断的响应中 |373| `TASK_MAX_OUTPUT_LENGTH` | [subagent](/zh-CN/sub-agents) 输出中的最大字符数，超过此数字后将进行截断（默认值：32000，最大值：160000）。截断时，完整输出保存到磁盘，路径包含在截断的响应中 |

388 390

389标准 OpenTelemetry 导出器变量（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 和信号特定变体）也受支持。请参阅[监控](/zh-CN/monitoring-usage)了解配置详情。391标准 OpenTelemetry 导出器变量（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 和信号特定变体）也受支持。请参阅[监控](/zh-CN/monitoring-usage)了解配置详情。

390 392

errors.md +488 −272

Details

53| `SSL certificate verification failed` | [网络](#ssl-certificate-errors) |53| `SSL certificate verification failed` | [网络](#ssl-certificate-errors) |

54| `SSL certificate error (...)` during login or startup | [网络](#ssl-certificate-errors) |54| `SSL certificate error (...)` during login or startup | [网络](#ssl-certificate-errors) |

55| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [网络](#host-not-allowed-in-a-cloud-session) |55| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [网络](#host-not-allowed-in-a-cloud-session) |

56| `Couldn't reconnect to your Remote Control session` | [网络](#couldn%E2%80%99t-reconnect-to-your-remote-control-session) |

56| `Prompt is too long` | [请求错误](#prompt-is-too-long) |57| `Prompt is too long` | [请求错误](#prompt-is-too-long) |

57| `Error during compaction: Conversation too long` | [请求错误](#error-during-compaction-conversation-too-long) |58| `Error during compaction: Conversation too long` | [请求错误](#error-during-compaction-conversation-too-long) |

58| `Request too large` | [请求错误](#request-too-large) |59| `Request too large` | [请求错误](#request-too-large) |

61| `PDF too large` / `PDF is password protected` | [请求错误](#pdf-errors) |62| `PDF too large` / `PDF is password protected` | [请求错误](#pdf-errors) |

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

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

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

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

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

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

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

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

69| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [请求错误](#usage-policy-refusal) |71| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [请求错误](#usage-policy-refusal) |

72| `<model> has safety measures that flagged this message for a cybersecurity topic` | [请求错误](#safety-measures-flagged-a-cybersecurity-topic) |

73| `Installation was killed before it could finish (exit code 137)` | [安装错误](#installation-was-killed-before-it-could-finish) |

74| `The connection dropped while downloading the update` | [安装错误](#the-connection-dropped-while-downloading-the-update) |

75| `Download timed out: exceeded the total deadline` | [安装错误](#the-connection-dropped-while-downloading-the-update) |

70| `--bg and --print conflict` | [命令行错误](#command-line-errors) |76| `--bg and --print conflict` | [命令行错误](#command-line-errors) |

77| `Error: --json-schema is not a valid JSON Schema` | [命令行错误](#command-line-errors) |

78| `Could not import <server>: <reason>` | [命令行错误](#could-not-import-a-server-from-claude-desktop) |

79| `Marketplace "<name>" is registered from an untrusted source` | [插件错误](#marketplace-is-registered-from-an-untrusted-source) |

80| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [配置警告](#workspace-has-not-been-trusted) |

71| 响应质量似乎低于平常 | [响应质量](#responses-seem-lower-quality-than-usual) |81| 响应质量似乎低于平常 | [响应质量](#responses-seem-lower-quality-than-usual) |

72 82

73<h2 id="automatic-retries">83<h2 id="automatic-retries">

99 服务器错误109 服务器错误

100</h2>110</h2>

101 111

102这些错误来自推理提供商，而不是您的帐户或请求。在 Anthropic API 上，这意味着 Anthropic 基础设施。在 Bedrock、Vertex AI、Foundry 或自定义网关上，这意味着该提供商的基础设施。112这些错误来自推理提供商，而不是您的账户或请求。在 Anthropic API 上，这意味着 Anthropic 基础设施。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自定义网关上，这意味着该提供商的基础设施。

103 113

104<h3 id="api-error-500-internal-server-error">114<h3 id="api-error-500-internal-server-error">

105 API Error: 500 Internal server error115 API 错误：500 内部服务器错误

106</h3>116</h3>

107 117

108Claude Code 为任何 5xx 响应显示状态代码和 API 的错误消息。下面的示例显示了 Anthropic API 上的 500 响应：118Claude Code 显示任何 5xx 响应的状态代码和 API 的错误消息。下面的示例显示了 Anthropic API 上的 500 响应：

109 119

110```text theme={null}120```text theme={null}

111API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com.121API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com.

112```122```

113 123

114末尾的句子指出了检查服务健康状况的位置，并因提供商而异。Bedrock、Vertex AI 和 Foundry 配置会指出该提供商的服务状态。自定义 `ANTHROPIC_BASE_URL` 会指出网关主机。124末尾的句子指出了检查服务健康状态的位置，因提供商而异。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 配置会指出该提供商的服务状态。自定义 `ANTHROPIC_BASE_URL` 会指出网关主机。

115 125

116这表示 API 内部出现意外故障。它不是由您的提示、设置或帐户引起的。126这表示 API 内部出现了意外故障。它不是由您的提示、设置或账户引起的。

117 127

118**要做什么：**128**应该做什么：**

119 129

120* 检查 [status.claude.com](https://status.claude.com) 或消息中指出的提供商状态页面，了解活跃事件130* 检查 [status.claude.com](https://status.claude.com) 或消息中指定的提供商状态页面，查看是否有活跃的事件

121* 等待一分钟，然后再次发送您的消息。您的原始消息仍在对话中，因此对于长提示，您可以输入 `try again` 而不是粘贴整个内容。131* 等待一分钟，然后重新发送您的消息。您的原始消息仍在对话中，所以对于较长的提示，您可以输入 `try again` 而不是粘贴整个内容。

122* 如果错误持续存在且没有发布的事件，请运行 `/feedback`，以便 Anthropic 可以使用您的请求详情进行调查。如果您的环境中 `/feedback` 不可用，请参阅[报告错误](#report-an-error)。132* 如果错误持续存在且没有发布的事件，请运行 `/feedback`，以便 Anthropic 可以使用您的请求详情进行调查。如果 `/feedback` 在您的环境中不可用，请参阅[报告错误](#report-an-error)。

123 133

124<h3 id="api-error-repeated-529-overloaded-errors">134<h3 id="api-error-repeated-529-overloaded-errors">

125 API Error: Repeated 529 Overloaded errors135 API 错误：重复的 529 过载错误

126</h3>136</h3>

127 137

128API 在所有用户中暂时处于容量限制。Claude Code 在显示此消息之前已经重试了多次：138API 在所有用户中暂时处于容量限制。Claude Code 在显示此消息之前已经重试了多次：

135 145

136529 不是您的使用限制，也不会计入您的配额。146529 不是您的使用限制，也不会计入您的配额。

137 147

138**要做什么：**148**应该做什么：**

139 149

140* 检查 [status.claude.com](https://status.claude.com) 或消息中指出的提供商状态页面，了解容量通知150* 检查 [status.claude.com](https://status.claude.com) 或消息中指定的提供商状态页面，查看容量通知

141* 几分钟后重试151* 几分钟后重试

142* 运行 `/model` 并切换到不同的模型以继续工作，因为容量是按模型跟踪的。当一个模型处于特别高的负载下时，Claude Code 会提示您这样做，例如 `Opus is experiencing high load, please use /model to switch to Sonnet`。152* 运行 `/model` 并切换到不同的模型以继续工作，因为容量是按模型跟踪的。当某个模型处于特别高的负载下时，Claude Code 会提示您这样做，例如 `Opus is experiencing high load, please use /model to switch to Sonnet`。

143 153

144<h3 id="request-timed-out">154<h3 id="request-timed-out">

145 Request timed out155 请求超时

146</h3>156</h3>

147 157

148API 在连接截止时间之前没有响应。158API 在连接截止时间之前没有响应。

151Request timed out161Request timed out

152```162```

153 163

154这可能在高负载期间或生成非常大的响应时发生。默认请求超时为 10 分钟。164这可能发生在高负载期间或模型生成非常大的响应时。默认请求超时为 10 分钟。

155 165

156**要做什么：**166**应该做什么：**

157 167

158* 重试请求168* 重试请求

159* 对于长时间运行的任务，将工作分解为较小的提示169* 对于长时间运行的任务，将工作分解为较小的提示

160* 如果是慢速网络或代理导致的，请按照[自动重试](#automatic-retries)中的说明提高 `API_TIMEOUT_MS`170* 如果是由于网络缓慢或代理引起的，请按照[自动重试](#automatic-retries)中的说明提高 `API_TIMEOUT_MS`

161* 如果超时频繁且您的网络状况良好，请参阅下面的[网络和连接错误](#network-and-connection-errors)171* 如果超时频繁且您的网络状况良好，请参阅下面的[网络和连接错误](#network-and-connection-errors)

162 172

163<h3 id="the-response-above-may-be-incomplete">173<h3 id="the-response-above-may-be-incomplete">

164 The response above may be incomplete174 上面的响应可能不完整

165</h3>175</h3>

166 176

167流式响应在 Claude 已经产生可见输出后失败。重新发送请求可能会运行相同的工具调用两次，因此 Claude Code 保留已经流出的内容并附加此通知，而不是丢弃轮次。您看到的变体命名了原因：177流式响应在 Claude 已经生成可见输出后失败。重新发送请求可能会运行相同的工具调用两次，因此 Claude Code 保留已经流式传输的内容，并附加此通知，而不是丢弃该轮次。您看到的变体指出了原因：

168 178

169```text theme={null}179```text theme={null}

170API Error: Server error mid-response. The response above may be incomplete.180API Error: Server error mid-response. The response above may be incomplete.

172API Error: Response stalled mid-stream. The response above may be incomplete.182API Error: Response stalled mid-stream. The response above may be incomplete.

173```183```

174 184

175* {/* min-version: 2.1.199 */}}`Server error mid-response`：流中途过载或 5xx 服务器错误。此变体需要 Claude Code v2.1.199 或更高版本；在此之前，该情况丢弃了部分输出并将整个轮次报告为错误。185* {/* min-version: 2.1.199 */}}`Server error mid-response`：流中的过载或 5xx 服务器错误。此变体需要 Claude Code v2.1.199 或更高版本；在此之前，该情况会丢弃部分输出并将整个轮次报告为错误。

176* `Connection closed mid-response`：连接断开。186* `Connection closed mid-response`：连接断开。

177* `Response stalled mid-stream`：流停止发送数据。187* `Response stalled mid-stream`：流停止发送数据。

178 188

179**要做什么：**189**应该做什么：**

180 190

181* 阅读流出的响应。没有任何内容丢失，但最后的句子或工具调用可能缺失。191* 阅读流式传输的响应。没有任何内容丢失，但最后的句子或工具调用可能缺失。

182* 回复 `continue` 以让 Claude 从停止的地方继续192* 回复 `continue` 让 Claude 从停止的地方继续

183* 如果在任何可见输出之前出现相同的错误，Claude Code 会重试请求而不是完成它。请参阅[自动重试](#automatic-retries)。193* 如果在任何可见输出之前出现相同的错误，Claude Code 会重试请求而不是完成它。请参阅[自动重试](#automatic-retries)。

184 194

185<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">195<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">

186 Auto mode cannot determine the safety of an action196 自动模式无法确定操作的安全性

187</h3>197</h3>

188 198

189[auto mode](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 用来分类操作的模型无法做出决定，因此 auto mode 没有自动批准该操作。您看到的消息取决于分类器失败的原因。199[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)用来分类操作的模型无法做出决定，因此自动模式没有自动批准该操作。您看到的消息取决于分类器失败的原因。

190 200

191在您的工作目录中的读取、搜索和编辑会跳过分类器，因此它们在所有这些情况下都继续工作。201在您的工作目录内的读取、搜索和编辑会跳过分类器，因此在所有这些情况下都能继续工作。

192 202

193当分类器模型过载时：203当分类器模型过载时：

194 204

196<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait briefly and then try this action again.206<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait briefly and then try this action again.

197```207```

198 208

199**要做什么：**209**应该做什么：**

200 210

201* 几秒钟后重试；Claude 看到相同的消息，通常会自动重试211* 几秒钟后重试；Claude 会看到相同的消息，通常会自动重试

202* 如果重试继续失败，继续进行只读任务，稍后再回到被阻止的操作212* 如果重试继续失败，继续执行只读任务，稍后再回到被阻止的操作

203* 这是暂时的，与 [auto mode 资格](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)无关；您不需要更改设置213* 这是暂时的，与[自动模式资格](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)无关；您不需要更改设置

204 214

205当分类器返回无法解析的响应时：215当分类器返回无法解析的响应时：

206 216

208Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details218Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details

209```219```

210 220

211**要做什么：**221**应该做什么：**

212 222

213* 重试该操作；这通常在下一次尝试时成功223* 重试该操作；这通常在下一次尝试时成功

214* 运行 `claude --debug` 并重复该操作以在调试日志中查看底层分类器响应224* 运行 `claude --debug` 并重复该操作以在调试日志中查看底层分类器响应

215 225

216当对话增长超过分类器的上下文窗口时：226当单独的 API 安全检查因早期对话内容而阻止了分类器请求时：

227

228```text theme={null}

229Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details

230```

231

232**应该做什么：**

233

234* 这不是关于您的操作的决定。您对话中已有的内容在自动模式将对话发送给分类器时触发了 API 上的安全过滤器

235* 重试无法帮助；相同的对话内容将再次触发过滤器

236* 切换到不同的[权限模式](/zh-CN/permission-modes)，以便在提示时可以批准该操作，或开始一个没有触发内容的新对话

237

238当对话大小超过分类器的上下文窗口时：

217 239

218```text theme={null}240```text theme={null}

219Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)241Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)

220```242```

221 243

222在交互式会话中，auto mode 会为该操作回退到正常权限提示，以便您可以手动批准或拒绝它。在[非交互式模式](/zh-CN/headless)中，运行会中止，因为记录只会增长，重试无法成功。244在交互式会话中，自动模式会为该操作回退到正常权限提示，以便您可以手动批准或拒绝它。在[非交互式模式](/zh-CN/headless)中，运行会中止，因为记录只会增长，重试无法成功。

223 245

224**要做什么：**246**应该做什么：**

225 247

226* 在出现的提示中批准或拒绝该操作248* 在出现的提示中批准或拒绝该操作

227* 运行 `/compact` 以减少对话大小，以便后续操作再次适应分类器窗口249* 运行 `/compact` 以减少对话大小，以便后续操作再次适应分类器窗口

228 250

229<h3 id="agent-terminated-early-due-to-an-api-error">251<h3 id="agent-terminated-early-due-to-an-api-error">

230 Agent terminated early due to an API error252 代理因 API 错误而提前终止

231</h3>253</h3>

232 254

233{/* min-version: 2.1.199 */}[subagent](/zh-CN/sub-agents) 的 API 请求终止失败，例如因为达到了使用限制或服务器错误的重试用尽，所以 subagent 在完成其任务之前停止。此消息需要 Claude Code v2.1.199 或更高版本；在此之前，API 错误文本被返回给 Claude，就像它是 subagent 的结果一样。255{/* min-version: 2.1.199 */}[子代理](/zh-CN/sub-agents)的 API 请求终止失败，例如因为达到了使用限制或服务器错误的重试用尽，所以子代理在完成其任务之前停止。此消息需要 Claude Code v2.1.199 或更高版本；在此之前，API 错误文本被返回给 Claude，就像它是子代理的结果一样。

234 256

235```text theme={null}257```text theme={null}

236Agent terminated early due to an API error: <error detail>258Agent terminated early due to an API error: <error detail>

237```259```

238 260

239**要做什么：**261**应该做什么：**

240 262

241* 将冒号后的错误详情与本页上的其他部分相匹配，例如[使用限制](#usage-limits)或[服务器错误](#server-errors)，并按照该部分的步骤操作263* 将冒号后的错误详情与此页面上的其自己的部分相匹配，例如[使用限制](#usage-limits)或[服务器错误](#server-errors)，并按照该部分的步骤操作

242* 一旦底层错误清除，要求 Claude 重试任务或[恢复 subagent](/zh-CN/sub-agents#resume-subagents)264* 一旦底层错误清除，请要求 Claude 重试任务或[恢复子代理](/zh-CN/sub-agents#resume-subagents)

243 265

244当速率限制、过载或服务器错误中断已经产生输出的前台 subagent 时，Claude 会收到该部分输出标记为不完整，而不是此错误。请参阅 [subagent 中的 API 错误](/zh-CN/sub-agents#api-errors-in-subagents)。266当速率限制、过载或服务器错误中断已经生成文本输出的前台子代理时，Claude 会收到该部分输出标记为不完整，而不是此错误。{/* min-version: 2.1.200 */}仅输出为工具调用的子代理也会收到此错误；在 v2.1.199 中，该形状返回了空的部分结果。请参阅[子代理中的 API 错误](/zh-CN/sub-agents#api-errors-in-subagents)。

245 267

246<h2 id="usage-limits">268<h2 id="usage-limits">

247 使用限制269 使用限制

248</h2>270</h2>

249 271

250这些错误意味着与您的帐户或计划相关的配额已达到。它们与影响所有人的[服务器错误](#server-errors)不同。272这些错误表示与您的账户或计划相关的配额已达到。它们不同于[服务器错误](#server-errors)，后者会影响所有人。

251 273

252<h3 id="you’ve-hit-your-session-limit">274<h3 id="you’ve-hit-your-session-limit">

253 You've hit your session limit275 您已达到会话限制

254</h3>276</h3>

255 277

256订阅计划包括滚动使用额度。当它用完时，您会看到以下消息之一：278订阅计划包括滚动使用额度。当额度用尽时，您会看到以下消息之一：

257 279

258```text theme={null}280```text theme={null}

259You've hit your session limit · resets 3:45pm281You've hit your session limit · resets 3:45pm

261You've hit your Opus limit · resets 3:45pm283You've hit your Opus limit · resets 3:45pm

262```284```

263 285

264Claude Code 阻止进一步的请求，直到消息中显示的重置时间。286Claude Code 会阻止进一步的请求，直到消息中显示的重置时间。

265 287

266**要做什么：**288**应该怎么做：**

267 289

268* 等待错误中显示的重置时间290* 等待错误消息中显示的重置时间

269* 运行 `/usage` 以查看您的计划限制以及它们何时重置291* 运行 `/usage` 查看您的计划限制以及它们何时重置

270* 运行 `/usage-credits` 以在 Pro 和 Max 上购买额外使用，或在 Team 和 Enterprise 上向您的管理员请求。有关如何计费的信息，请参阅[付费计划的使用信用](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。292* 运行 `/usage-credits` 在 Pro 和 Max 上购买额外使用量，或在 Team 和 Enterprise 上向您的管理员请求。有关如何计费，请参阅[付费计划的使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。

271* 要升级您的计划以获得更高的基础限制，请参阅 [claude.com/pricing](https://claude.com/pricing)293* 要升级您的计划以获得更高的基础限制，请参阅 [claude.com/pricing](https://claude.com/pricing)

272 294

273要在达到限制之前监视您的剩余额度，请将 `rate_limits` 字段添加到[自定义状态行](/zh-CN/statusline#rate-limit-usage)，或在桌面应用中单击模型选择器旁边的[使用环](/zh-CN/desktop#check-usage)。295要在达到限制之前监控您的剩余额度，请将 `rate_limits` 字段添加到[自定义状态行](/zh-CN/statusline#rate-limit-usage)，或在桌面应用中单击模型选择器旁边的[使用量环](/zh-CN/desktop#check-usage)。

274 296

275<h3 id="usage-credits-required-for-1m-context">297<h3 id="usage-credits-required-for-1m-context">

276 Usage credits required for 1M context298 1M 上下文需要使用额度

277</h3>299</h3>

278 300

279所选模型使用 1M 令牌扩展上下文窗口，而您的计划仅通过使用信用包含它。301所选模型使用 1M 令牌扩展上下文窗口，而您的计划仅通过使用额度包含它。

280 302

281```text theme={null}303```text theme={null}

282API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context304API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context

283```305```

284 306

285这是一个权利检查，而不是配额耗尽。即使您的会话和每周额度仍有容量，它也会触发。请参阅[扩展上下文](/zh-CN/model-config#extended-context)以了解哪些计划直接包含 1M 上下文，哪些需要使用信用。307这是一项权利检查，而不是配额耗尽。即使您的会话和每周额度仍有容量，它也会触发。有关哪些计划直接包含 1M 上下文以及哪些需要使用额度，请参阅[扩展上下文](/zh-CN/model-config#extended-context)。

286 308

287{/* min-version: 2.1.172 */}当此错误在对话中途出现，因为上下文增长超过 200K 令牌时，Claude Code 会自动将对话压缩回标准上下文限制以下，并在之后将会话保持在该限制，因此无需采取任何操作。在 v2.1.172 之前的版本上，错误在每个后续请求（包括 `/compact`）上重复；在这些版本上运行 `/clear` 以恢复。以下步骤适用于您明确选择 `[1m]` 模型的情况。309{/* min-version: 2.1.172 */}当此错误在对话中期出现，因为上下文增长超过 200K 令牌时，Claude Code 会自动将对话压缩回标准上下文限制以下，并在之后将会话保持在该限制，因此无需采取任何操作。在 v2.1.172 之前的版本上，错误会在每个后续请求（包括 `/compact`）上重复出现；在这些版本上运行 `/clear` 以恢复。以下步骤适用于您明确选择 `[1m]` 模型的情况。

288 310

289**要做什么：**311**应该怎么做：**

290 312

291* 运行 `/model` 并选择不带 `[1m]` 后缀的变体以回退到标准上下文窗口313* 运行 `/model` 并选择不带 `[1m]` 后缀的变体以回退到标准上下文窗口

292* 运行 `/usage-credits` 以在 Pro 和 Max 上启用 1M 变体的计量计费，或在 Team 和 Enterprise 上向您的管理员请求314* 运行 `/usage-credits` 在 Pro 和 Max 上为 1M 变体启用按量计费，或在 Team 和 Enterprise 上向您的管理员请求

293* 如果在 `/model` 后错误仍然存在，1M 模型 ID 可能在其他地方设置。请参阅[所选模型存在问题](#there%E2%80%99s-an-issue-with-the-selected-model)以按优先级顺序检查配置位置。315* 如果 `/model` 后错误仍然存在，1M 模型 ID 可能在其他地方设置。有关要按优先级顺序检查的配置位置，请参阅[所选模型存在问题](#there%E2%80%99s-an-issue-with-the-selected-model)。

294* 要从模型选择器中完全删除 1M 变体，请设置 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/zh-CN/env-vars)316* 要从模型选择器中完全删除 1M 变体，请设置 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/zh-CN/env-vars)

295 317

296<h3 id="server-is-temporarily-limiting-requests">318<h3 id="server-is-temporarily-limiting-requests">

297 Server is temporarily limiting requests319 服务器暂时限制请求

298</h3>320</h3>

299 321

300API 应用了与您的计划配额无关的短期限流。322API 应用了与您的计划配额无关的短期限流。

303API Error: Server is temporarily limiting requests (not your usage limit)325API Error: Server is temporarily limiting requests (not your usage limit)

304```326```

305 327

306Claude Code 通过缺少真实限制响应携带的统一配额标头来区分这些。{/* min-version: 2.1.199 */}从 v2.1.199 开始，这会在显示之前[自动重试](#automatic-retries)，无论您如何进行身份验证。在早期版本上，使用 claude.ai 订阅登录的会话在第一次出现时失败轮次；仅 API 密钥和企业登录重试它。328Claude Code 通过真实限制响应所携带的统一配额标头的缺失来区分这些与您的计划限制。{/* min-version: 2.1.199 */}从 v2.1.199 开始，无论您如何进行身份验证，这都会[自动重试](#automatic-retries)并进行退避，然后才会显示。在早期版本上，使用 claude.ai 订阅登录的会话在第一次出现时失败；只有 API 密钥和 Enterprise 登录会重试。

307 329

308**要做什么：**330**应该怎么做：**

309 331

310* 等待片刻后重试332* 稍等片刻后重试

311* 如果持续存在，请检查 [status.claude.com](https://status.claude.com)333* 如果问题仍然存在，请检查 [status.claude.com](https://status.claude.com)

312 334

313<h3 id="request-rejected-429">335<h3 id="request-rejected-429">

314 Request rejected (429)336 请求被拒绝 (429)

315</h3>337</h3>

316 338

317您已达到为您的 API 密钥、Amazon Bedrock 项目或 Google Vertex AI 项目配置的速率限制。339您已达到为 API 密钥、Amazon Bedrock 项目或 Google Cloud 项目配置的速率限制。

318 340

319```text theme={null}341```text theme={null}

320API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.342API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.

321```343```

322 344

323末尾的句子命名了检查服务健康的位置，并因提供商而异。Bedrock、Vertex AI 和 Foundry 配置命名该提供商的服务状态，而不是 Anthropic 状态页面。自定义 `ANTHROPIC_BASE_URL` 命名网关主机。345尾部句子指出检查服务健康状况的位置，因提供商而异。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 配置会指出该提供商的服务状态，而不是 Anthropic 状态页面。自定义 `ANTHROPIC_BASE_URL` 会指出网关主机。

324 346

325**要做什么：**347**应该怎么做：**

326 348

327* 运行 `/status` 并确认活跃凭证是您期望的凭证。环境中的流浪 `ANTHROPIC_API_KEY` 可能会通过低层密钥而不是您的订阅路由请求。349* 运行 `/status` 并确认活跃凭证是您期望的凭证。环境中的杂散 `ANTHROPIC_API_KEY` 可能会通过低级密钥而不是您的订阅来路由请求。

328* 检查您的提供商控制台以了解活跃限制，如果需要，请请求更高的层级350* 检查您的提供商控制台以了解活跃限制，如果需要，请请求更高的层级

329* 对于 Anthropic API 密钥，请参阅[速率限制参考](https://platform.claude.com/docs/en/api/rate-limits)以了解层级如何工作以及如何设置每个工作区的上限351* 对于 Anthropic API 密钥，请参阅[速率限制参考](https://platform.claude.com/docs/en/api/rate-limits)了解层级如何工作以及如何设置每个工作区的上限

330* 降低并发：降低 [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/zh-CN/env-vars)，避免运行许多并行子代理，或使用 `/model` 切换到较小的模型以进行高容量脚本运行352* 降低并发：降低 [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/zh-CN/env-vars)，避免运行许多并行子代理，或使用 `/model` 切换到较小的模型以进行大容量脚本运行

331 353

332<h3 id="credit-balance-is-too-low">354<h3 id="credit-balance-is-too-low">

333 Credit balance is too low355 信用余额过低

334</h3>356</h3>

335 357

336您的 Console 组织已用完预付信用。358您的 Console 组织已用尽预付信用。

337 359

338```text theme={null}360```text theme={null}

339Credit balance is too low361Credit balance is too low

340```362```

341 363

342**要做什么：**364**应该怎么做：**

343 365

344* 在 [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing) 添加信用，并考虑在那里启用自动重新加载，以便在余额达到零之前重新填充366* 在 [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing) 添加信用，并考虑在那里启用自动重新加载，以便在余额达到零之前进行补充

345* 如果您有 Pro、Max、Team 或 Enterprise 计划，请使用 `/login` 切换到订阅身份验证367* 如果您有 Pro、Max、Team 或 Enterprise 计划，请使用 `/login` 切换到订阅身份验证

346* 在 Console 中设置每个工作区的支出上限，以防止单个项目耗尽组织余额。请参阅[有效管理成本](/zh-CN/costs)。368* 在 Console 中设置每个工作区的支出上限，以防止单个项目耗尽组织余额。请参阅[有效管理成本](/zh-CN/costs)。

347 369

349 身份验证错误371 身份验证错误

350</h2>372</h2>

351 373

352这些错误意味着 Claude Code 无法向 API 证明您的身份。随时运行 `/status` 以查看当前活跃的凭证。374这些错误意味着 Claude Code 无法向 API 证明您的身份。随时运行 `/status` 查看当前活跃的凭证。

353 375

354<h3 id="not-logged-in">376<h3 id="not-logged-in">

355 Not logged in377 未登录

356</h3>378</h3>

357 379

358此会话没有有效的凭证可用。380此会话没有可用的有效凭证。

359 381

360```text theme={null}382```text theme={null}

361Not logged in · Please run /login383Not logged in · Please run /login

362```384```

363 385

364**要做什么：**386**应该做什么：**

365 387

366* 运行 `/login` 以使用您的 Claude 订阅或 Console 帐户进行身份验证388* 运行 `/login` 使用您的 Claude 订阅或 Console 账户进行身份验证

367* 如果您期望环境变量对您进行身份验证，请确认 `ANTHROPIC_API_KEY` 已在您启动 `claude` 的 shell 中设置和导出389* 如果您期望使用环境变量进行身份验证，请确认 `ANTHROPIC_API_KEY` 已在启动 `claude` 的 shell 中设置并导出

368* 对于 CI 或无法进行交互式登录的自动化，配置一个[`apiKeyHelper`](/zh-CN/settings#available-settings) 脚本，在启动时获取密钥390* 对于无法进行交互式登录的 CI 或自动化环境，配置一个 [`apiKeyHelper`](/zh-CN/settings#available-settings) 脚本，在启动时获取密钥

369* 请参阅[身份验证优先级](/zh-CN/authentication#authentication-precedence)以了解当存在多个凭证时哪个凭证获胜391* 查看 [身份验证优先级](/zh-CN/authentication#authentication-precedence) 了解当存在多个凭证时 Claude Code 使用哪个凭证

370 392

371如果您被重复提示登录，请参阅[未登录或令牌过期](/zh-CN/troubleshoot-install#not-logged-in-or-token-expired)以了解系统时钟和 macOS Keychain 修复。393如果您被反复提示登录，请参阅 [未登录或令牌过期](/zh-CN/troubleshoot-install#not-logged-in-or-token-expired) 了解系统时钟和 macOS Keychain 修复。

372 394

373<h3 id="could-not-resolve-authentication-method">395<h3 id="could-not-resolve-authentication-method">

374 Could not resolve authentication method396 无法解析身份验证方法

375</h3>397</h3>

376 398

377会话到达 API 客户端时没有任何凭证。这出现在[后台会话](/zh-CN/agent-view)、云会话和 Agent SDK 上下文中，其中交互式登录检查在第一个请求之前不运行。399会话到达 API 客户端时没有任何凭证。这出现在 [后台会话](/zh-CN/agent-view)、云会话和 Agent SDK 上下文中，其中交互式登录检查在第一个请求之前不会运行。

378 400

379```text theme={null}401```text theme={null}

380Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted402Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted

382 404

383{/* min-version: 2.1.174 */}在 v2.1.174 之前，分配给空闲预初始化工作进程的后台或云会话即使配置了有效凭证也可能以这种方式失败。升级以恢复。在当前版本中，该错误意味着工作进程没有可用的凭证。405{/* min-version: 2.1.174 */}在 v2.1.174 之前，分配给空闲预初始化工作进程的后台或云会话即使配置了有效凭证也可能以这种方式失败。升级以恢复。在当前版本中，该错误意味着工作进程没有可用的凭证。

384 406

385**要做什么：**407**应该做什么：**

386 408

387* 如果这出现在后台或云会话中且您的凭证已配置，请升级到 v2.1.174 或更高版本409* 如果这出现在后台或云会话中且您的凭证已配置，请升级到 v2.1.174 或更高版本

388* 确认 `ANTHROPIC_API_KEY`、`CLAUDE_CODE_OAUTH_TOKEN` 或您的云提供商凭证已在启动工作进程的环境中设置，而不仅仅在您的交互式 shell 中410* 确认 `ANTHROPIC_API_KEY`、`CLAUDE_CODE_OAUTH_TOKEN` 或您的云提供商凭证已在启动工作进程的环境中设置，而不仅仅在您的交互式 shell 中

389* 对于 Agent SDK，请参阅[身份验证设置](/zh-CN/agent-sdk/overview#get-started)411* 对于 Agent SDK，请参阅 [身份验证设置](/zh-CN/agent-sdk/overview#get-started)

390* 在同一环境中的交互式会话中运行 `/status` 以确认哪个凭证源解析412* 在同一环境中的交互式会话中运行 `/status` 以确认哪个凭证源可以解析

391 413

392<h3 id="invalid-api-key">414<h3 id="invalid-api-key">

393 Invalid API key415 无效的 API 密钥

394</h3>416</h3>

395 417

396`ANTHROPIC_API_KEY` 环境变量或 `apiKeyHelper` 脚本返回了 API 拒绝的密钥。418`ANTHROPIC_API_KEY` 环境变量或 `apiKeyHelper` 脚本返回的密钥被 API 拒绝。

397 419

398```text theme={null}420```text theme={null}

399Invalid API key · Fix external API key421Invalid API key · Fix external API key

400```422```

401 423

402**要做什么：**424**应该做什么：**

403 425

404* 检查拼写错误，并确认密钥未在 [Console](https://platform.claude.com/settings/keys) 中被撤销426* 检查拼写错误并确认密钥未在 [Console](https://platform.claude.com/settings/keys) 中被撤销

405* 在同一 shell 中运行 `env | grep ANTHROPIC`。direnv、dotenv shell 插件和 IDE 终端等工具可以从项目中的 `.env` 文件加载过时的密钥，而无需您显式设置它427* 在同一 shell 中运行 `env | grep ANTHROPIC`。direnv、dotenv shell 插件和 IDE 终端等工具可以从项目中的 `.env` 文件加载过时的密钥，而无需您显式设置它

406* 取消设置 `ANTHROPIC_API_KEY` 并运行 `/login` 以改用订阅身份验证428* 取消设置 `ANTHROPIC_API_KEY` 并运行 `/login` 改用订阅身份验证

407* 如果密钥来自 [`apiKeyHelper`](/zh-CN/settings#available-settings) 脚本，请直接运行脚本以确认它在 stdout 上打印有效的密钥429* 如果密钥来自 [`apiKeyHelper`](/zh-CN/settings#available-settings) 脚本，直接运行该脚本以确认它在 stdout 上打印有效密钥

408* 运行 `/status` 以确认 Claude Code 实际使用的凭证源430* 运行 `/status` 确认 Claude Code 实际使用的凭证源

409 431

410<h3 id="this-organization-has-been-disabled">432<h3 id="this-organization-has-been-disabled">

411 This organization has been disabled433 此组织已被禁用

412</h3>434</h3>

413 435

414来自禁用的 Console 组织的过时 `ANTHROPIC_API_KEY` 正在覆盖您的订阅登录。436来自已禁用 Console 组织的过时 `ANTHROPIC_API_KEY` 正在覆盖您的订阅登录。

415 437

416```text theme={null}438```text theme={null}

417Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your other credentials439Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your other credentials

418API Error: 400 ... This organization has been disabled.440API Error: 400 ... This organization has been disabled.

419```441```

420 442

421环境变量优先于 `/login`，因此在您的 shell 配置文件中导出或从 `.env` 文件加载的密钥即使您有有效的 Pro 或 Max 订阅也会被使用。在非交互模式 (`-p`) 中，当存在密钥时总是使用该密钥。443环境变量优先于 `/login`，因此即使您有有效的 Pro 或 Max 订阅，在 shell 配置文件中导出或从 `.env` 文件加载的密钥也会被使用。在非交互模式 (`-p`) 中，当密钥存在时始终使用该密钥。

422 444

423**要做什么：**445**应该做什么：**

424 446

425* 在当前 shell 中取消设置 `ANTHROPIC_API_KEY` 并从您的 shell 配置文件中删除它，然后重新启动 `claude`447* 在当前 shell 中取消设置 `ANTHROPIC_API_KEY` 并从 shell 配置文件中删除它，然后重新启动 `claude`

426* 之后运行 `/status` 以确认活跃凭证是您的订阅448* 之后运行 `/status` 确认活跃凭证是您的订阅

427* 如果未设置环境变量且错误仍然存在，则禁用的组织是与您的 `/login` 相关联的组织。联系支持或使用不同的帐户登录。449* 如果未设置环境变量且错误仍然存在，则禁用的组织是与您的 `/login` 关联的组织。联系支持或使用不同的账户登录。

428 450

429<h3 id="your-organization-has-disabled-api-key-authentication">451<h3 id="your-organization-has-disabled-api-key-authentication">

430 Your organization has disabled API key authentication452 您的组织已禁用 API 密钥身份验证

431</h3>453</h3>

432 454

433{/* min-version: 2.1.169 */}}455此消息需要 Claude Code v2.1.169 或更高版本。您的 Console 组织管理员已关闭 API 密钥身份验证，因此 API 拒绝 Claude Code 发送的密钥。`·` 之后的恢复提示因密钥来源而异：

434您的 Console 组织的管理员已关闭 API 密钥身份验证，因此 API 拒绝了 Claude Code 正在发送的密钥。`·` 之后的恢复提示因密钥的来源而异：

435 456

436```text theme={null}457```text theme={null}

437Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account458Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account

440Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account461Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account

441```462```

442 463

443环境变量和 `apiKeyHelper` 优先于 `/login`，因此仅运行 `/login` 在任一仍在提供密钥时无法帮助。请参阅[身份验证优先级](/zh-CN/authentication#authentication-precedence)。464环境变量和 `apiKeyHelper` 优先于 `/login`，因此仅运行 `/login` 在任一仍在提供密钥时无法帮助。请参阅 [身份验证优先级](/zh-CN/authentication#authentication-precedence)。

444 465

445**要做什么：**466**应该做什么：**

446 467

447* 如果消息命名 `ANTHROPIC_API_KEY`，在当前 shell 中取消设置它并从您的 shell 配置文件或 `.env` 文件中删除它，然后重新启动 `claude`468* 如果消息提到 `ANTHROPIC_API_KEY`，在当前 shell 中取消设置它并从 shell 配置文件或 `.env` 文件中删除它，然后重新启动 `claude`

448* 如果消息命名 `apiKeyHelper`，从您的 `settings.json` 中删除 [`apiKeyHelper`](/zh-CN/settings#available-settings) 设置469* 如果消息提到 `apiKeyHelper`，从您的 `settings.json` 中删除 [`apiKeyHelper`](/zh-CN/settings#available-settings) 设置

449* 运行 `/login` 以使用您的 claude.ai 帐户登录470* 运行 `/login` 使用您的 claude.ai 账户登录

450* 之后运行 `/status` 以确认活跃凭证是您的订阅而不是 API 密钥471* 之后运行 `/status` 确认活跃凭证是您的订阅而不是 API 密钥

451* 如果您需要 API 密钥身份验证用于自动化，请要求您的组织管理员在 Console 中重新启用它472* 如果您需要 API 密钥身份验证用于自动化，请要求您的组织管理员在 Console 中重新启用它

452 473

453<h3 id="your-organization-has-disabled-claude-subscription-access">474<h3 id="your-organization-has-disabled-claude-subscription-access">

454 Your organization has disabled Claude subscription access475 您的组织已禁用 Claude 订阅访问

455</h3>476</h3>

456 477

457您的 Claude 组织不允许使用订阅登录登录到 Claude Code。使用同一帐户再次运行 `/login` 会返回相同的错误。478您的 Claude 组织不允许使用订阅登录登录到 Claude Code。使用同一账户再次运行 `/login` 会返回相同的错误。

458 479

459```text theme={null}480```text theme={null}

460Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access481Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access

461```482```

462 483

463这是一个服务器端组织设置，因此无法从本地设置、环境变量或 CLI 标志覆盖。484这是服务器端组织设置，因此无法从本地设置、环境变量或 CLI 标志覆盖。

464 485

465Agent SDK 和 `-p` 非交互模式将其显示为 `oauth_org_not_allowed` 错误代码。486Agent SDK 和 `-p` 非交互模式将其显示为 `oauth_org_not_allowed` 错误代码。

466 487

467**要做什么：**488**应该做什么：**

468 489

469* 要求您的管理员为您的组织启用 Claude Code 访问权限490* 要求您的管理员为您的组织启用 Claude Code 访问

470* 改用 Console API 密钥进行身份验证，而不是您的订阅。有关设置，请参阅 [Claude Console 身份验证](/zh-CN/authentication#claude-console-authentication)。491* 使用 Console API 密钥而不是您的订阅进行身份验证。有关设置，请参阅 [Claude Console 身份验证](/zh-CN/authentication#claude-console-authentication)。

471* 如果您是管理员且看不到启用访问权限的选项，请联系 [Anthropic 支持](https://support.claude.com)492* 如果您是管理员且看不到启用访问的选项，请联系 [Anthropic 支持](https://support.claude.com)

472 493

473<h3 id="routines-are-disabled-by-your-organization’s-policy">494<h3 id="routines-are-disabled-by-your-organization’s-policy">

474 Routines are disabled by your organization's policy495 例程被您的组织的策略禁用

475</h3>496</h3>

476 497

477您的团队或企业组织中的所有者已在组织级别关闭了例程。当您尝试创建或运行例程时会出现该错误，包括从 `/schedule` 和 claude.ai/code 上的 [Routines](/zh-CN/routines) UI。498您的 Team 或 Enterprise 组织中的所有者已在组织级别关闭例程。当您尝试创建或运行例程时会出现该错误，包括从 `/schedule` 和 claude.ai/code 上的 [Routines](/zh-CN/routines) UI。

478 499

479```text theme={null}500```text theme={null}

480Routines are disabled by your organization's policy.501Routines are disabled by your organization's policy.

481```502```

482 503

483这是一个服务器端设置，因此无法从本地设置、环境变量或 CLI 标志覆盖。504这是服务器端设置，因此无法从本地设置、环境变量或 CLI 标志覆盖。

484 505

485**要做什么：**506**应该做什么：**

486 507

487* 要求您的组织中的所有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 启用**例程**切换508* 要求您的组织中的所有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 启用 **Routines** 切换

488* 对于不需要组织级别例程的一次性计划工作，请参阅[计划任务](/zh-CN/scheduled-tasks)509* 对于不需要组织级例程的一次性计划工作，请参阅 [计划任务](/zh-CN/scheduled-tasks)

489 510

490<h3 id="remote-control-requires-the-anthropic-api">511<h3 id="remote-control-requires-the-anthropic-api">

491 Remote Control requires the Anthropic API512 Remote Control 需要 Anthropic API

492</h3>513</h3>

493 514

494该会话不是直接与 Anthropic API 通信，因此没有 claude.ai 后端供 [Remote Control](/zh-CN/remote-control) 配对。515会话不是直接与 Anthropic API 通信，因此没有 claude.ai 后端供 [Remote Control](/zh-CN/remote-control) 配对。

495 516

496```text theme={null}517```text theme={null}

497Remote Control is only available when using Claude via api.anthropic.com.518Remote Control is only available when using Claude via api.anthropic.com.

498```519```

499 520

500这出现在 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 上。{/* min-version: 2.1.196 */}从 v2.1.196 开始，当 [`ANTHROPIC_BASE_URL`](/zh-CN/env-vars) 指向 `api.anthropic.com` 以外的主机时，它也会出现，例如 [LLM gateway](/zh-CN/llm-gateway) 或代理，即使您使用 claude.ai 登录。521这出现在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上。{/* min-version: 2.1.196 */}从 v2.1.196 开始，当 [`ANTHROPIC_BASE_URL`](/zh-CN/env-vars) 指向 `api.anthropic.com` 以外的主机时，例如 [LLM 网关](/zh-CN/llm-gateway) 或代理，即使您使用 claude.ai 登录，它也会出现。

501 522

502**要做什么：**523**应该做什么：**

503 524

504* 取消设置 `ANTHROPIC_BASE_URL` 并重新启动会话，或从直接与 Anthropic API 通信的会话启动 Remote Control525* 取消设置 `ANTHROPIC_BASE_URL` 并重启会话，或从直接与 Anthropic API 通信的会话启动 Remote Control

505* 对于此错误和其他 Remote Control 启动消息，请参阅[故障排除 Remote Control](/zh-CN/remote-control#troubleshooting)526* 对于此错误和其他 Remote Control 启动消息，请参阅 [Remote Control 故障排除](/zh-CN/remote-control#troubleshooting)

506 527

507<h3 id="oauth-token-revoked-or-expired">528<h3 id="oauth-token-revoked-or-expired">

508 OAuth token revoked or expired529 OAuth 令牌被撤销或过期

509</h3>530</h3>

510 531

511您保存的登录不再有效。撤销的令牌意味着您在任何地方都签出或管理员删除了访问权限；过期的令牌意味着自动刷新在会话中途失败。532您保存的登录不再有效。撤销的令牌意味着您在任何地方都已登出或管理员删除了访问权限；过期的令牌意味着自动刷新在会话中途失败。

512 533

513```text theme={null}534```text theme={null}

514OAuth token revoked · Please run /login535OAuth token revoked · Please run /login

516API Error: 401 ... authentication_error537API Error: 401 ... authentication_error

517```538```

518 539

519**要做什么：**540**应该做什么：**

520 541

521* 运行 `/login` 以再次登录542* 运行 `/login` 重新登录

522* 如果在重新身份验证后错误在同一会话中返回，请先运行 `/logout` 以完全清除存储的令牌，然后运行 `/login`543* 如果在同一会话中重新身份验证后错误返回，请先运行 `/logout` 完全清除存储的令牌，然后运行 `/login`

523* 对于跨启动的重复登录提示，请参阅[故障排除](/zh-CN/troubleshoot-install#not-logged-in-or-token-expired)中的系统时钟和 macOS Keychain 检查544* 对于跨启动的重复登录提示，请参阅 [故障排除](/zh-CN/troubleshoot-install#not-logged-in-or-token-expired) 中的系统时钟和 macOS Keychain 检查

524* 对于其他故障，包括 `403 Forbidden` 和 OAuth 浏览器问题，请参阅[登录和身份验证](/zh-CN/troubleshoot-install#login-and-authentication)545* 对于其他故障，包括 `403 Forbidden` 和 OAuth 浏览器问题，请参阅 [登录和身份验证](/zh-CN/troubleshoot-install#login-and-authentication)

525 546

526<h3 id="oauth-scope-requirement">547<h3 id="oauth-scope-requirement">

527 OAuth scope requirement548 OAuth 范围要求

528</h3>549</h3>

529 550

530存储的令牌早于较新功能所需的权限范围。您最常从 `/usage` 和状态行使用指示器看到这一点：551存储的令牌早于较新功能需要的权限范围。您最常从 `/usage` 和状态行使用情况指示器看到这一点：

531 552

532```text theme={null}553```text theme={null}

533OAuth token does not meet scope requirement: user:profile554OAuth token does not meet scope requirement: user:profile

534```555```

535 556

536**要做什么：**557**应该做什么：**

537 558

538* 运行 `/login` 以使用当前范围铸造新令牌。您不需要先登出。559* 运行 `/login` 获取具有当前范围的新令牌。您不需要先登出。

539 560

540<h3 id="aws-credentials-expired-or-invalid">561<h3 id="aws-credentials-expired-or-invalid">

541 AWS credentials expired or invalid562 AWS 凭证已过期或无效

542</h3>563</h3>

543 564

544{/* min-version: 2.1.198 */}}此消息需要 Claude Code v2.1.198 或更高版本，仅当在您的设置文件中设置了 [`awsAuthRefresh`](/zh-CN/amazon-bedrock#advanced-credential-configuration) 时才出现。您的 AWS 会话令牌过期或被拒绝，Claude Code 已经运行的自动刷新没有产生 API 接受的凭证。它出现在来自 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 或 [Mantle 端点](/zh-CN/amazon-bedrock#use-the-mantle-endpoint) 的 401，这是这些提供商报告过期安全令牌的方式。565{/* min-version: 2.1.198 */}此消息需要 Claude Code v2.1.198 或更高版本，仅当在您的设置文件中设置了 [`awsAuthRefresh`](/zh-CN/amazon-bedrock#advanced-credential-configuration) 时才会出现。您的 AWS 会话令牌已过期或被拒绝，Claude Code 已运行的自动刷新未产生 API 接受的凭证。它出现在来自 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 或 [Mantle 端点](/zh-CN/amazon-bedrock#use-the-mantle-endpoint) 的 401 上，这是这些提供商报告过期安全令牌的方式。

545 566

546中间的操作提示命名了您的设置中的 `awsAuthRefresh` 命令，因此它会有所不同。稳定的部分是前导 `AWS credentials expired or invalid`：567中间的操作提示命名了您的设置中的 `awsAuthRefresh` 命令，因此它会有所不同。稳定的部分是前导的 `AWS credentials expired or invalid`：

547 568

548```text theme={null}569```text theme={null}

549AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...570AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...

550```571```

551 572

552如果未配置 `awsAuthRefresh`，相同的 401 会显示通用 `Please run /login` 消息，该消息无法刷新 AWS 凭证。573如果未配置 `awsAuthRefresh`，相同的 401 会显示通用的 `Please run /login` 消息，该消息无法刷新 AWS 凭证。

553 574

554**要做什么：**575**应该做什么：**

555 576

556* 在另一个终端中运行消息中命名的 `awsAuthRefresh` 命令（例如 `aws sso login --profile myprofile`）并完成浏览器登录，然后重试577* 在另一个终端中运行消息中命名的 `awsAuthRefresh` 命令，例如 `aws sso login --profile myprofile`，完成浏览器登录，然后重试

557* 在交互式会话中，运行 `/login`，选择 **3rd-party platform**，然后在 **Using 3rd-party platforms** 下选择 **Claude Platform on AWS · refresh credentials** 以运行相同的命令而无需重新启动 Claude Code。有关设置，请参阅[配置 AWS 凭证](/zh-CN/claude-platform-on-aws#1-configure-aws-credentials)578* 在交互式会话中，运行 `/login`，选择 **3rd-party platform**，然后在 **Using 3rd-party platforms** 下选择 **Claude Platform on AWS · refresh credentials** 以运行相同的命令而无需重启 Claude Code。请参阅 [配置 AWS 凭证](/zh-CN/claude-platform-on-aws#1-configure-aws-credentials)

558* 如果刷新命令成功后错误重复，请在同一 shell 和配置文件中使用 `aws sts get-caller-identity` 确认身份在 Claude Code 外部有效579* 如果刷新命令成功后错误重复出现，请在同一 shell 和配置文件中使用 `aws sts get-caller-identity` 确认身份在 Claude Code 外部有效

559 580

560<h3 id="aws-authentication-failed">581<h3 id="aws-authentication-failed">

561 AWS authentication failed582 AWS 身份验证失败

562</h3>583</h3>

563 584

564{/* min-version: 2.1.198 */}}此消息需要 Claude Code v2.1.198 或更高版本，仅当在您的设置文件中设置了 [`awsAuthRefresh`](/zh-CN/amazon-bedrock#advanced-credential-configuration) 时才出现。您的 AWS 提供商返回了 403，或 [Amazon Bedrock](/zh-CN/amazon-bedrock) 返回了 401。585{/* min-version: 2.1.198 */}此消息需要 Claude Code v2.1.198 或更高版本，仅当在您的设置文件中设置了 [`awsAuthRefresh`](/zh-CN/amazon-bedrock#advanced-credential-configuration) 时才会出现。您的 AWS 提供商返回了 403，或 [Amazon Bedrock](/zh-CN/amazon-bedrock) 返回了 401。

565 586

566Claude Code 无法判断您遇到了哪个原因。Amazon Bedrock 将过期的安全令牌报告为 403，但 403 也是它报告授权拒绝的方式，例如来自缺少 IAM 权限或未为您的帐户启用的模型的 `AccessDeniedException`。587Claude Code 无法判断您遇到了哪个原因。Amazon Bedrock 将过期的安全令牌报告为 403，但 403 也是它报告授权拒绝的方式，例如来自缺失 IAM 权限或未为您的账户启用的模型的 `AccessDeniedException`。

567 588

568来自 Amazon Bedrock 的 401 也会落在这里，而不是在 [AWS credentials expired or invalid](#aws-credentials-expired-or-invalid) 下，因为 Bedrock 不将过期令牌报告为 401。来自该端点的 401 通常来自请求路径中的其他内容，例如公司代理。589来自 Amazon Bedrock 的 401 也会落在这里而不是在 [AWS 凭证已过期或无效](#aws-credentials-expired-or-invalid) 下，因为 Amazon Bedrock 不会将过期令牌报告为 401。来自该端点的 401 通常来自请求路径中的其他内容，例如公司代理。

569 590

570凭证刷新可以修复过期令牌，无法修复其他原因，因此消息提供两者：591凭证刷新可以修复过期的令牌，无法修复其他原因，因此消息提供两者：

571 592

572```text theme={null}593```text theme={null}

573AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...594AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...

574```595```

575 596

576中间的操作提示命名了您的设置中的 `awsAuthRefresh` 命令，因此它会有所不同。稳定的部分是前导 `AWS authentication failed`。597中间的操作提示命名了您的设置中的 `awsAuthRefresh` 命令，因此它会有所不同。稳定的部分是前导的 `AWS authentication failed`。

577 598

578**要做什么：**599**应该做什么：**

579 600

580* 运行消息中命名的 `awsAuthRefresh` 命令或 `aws sso login`，以防过期凭证是原因601* 运行消息中命名的 `awsAuthRefresh` 命令或 `aws sso login`，以防过期凭证是原因

581* 如果您的凭证是最新的，请确认 [IAM 配置](/zh-CN/amazon-bedrock#iam-configuration) 中的 IAM 权限已附加到您使用的身份，并且所选模型已为您的帐户和区域启用602* 如果您的凭证是最新的，请确认 [IAM 配置](/zh-CN/amazon-bedrock#iam-configuration) 中的 IAM 权限已附加到您使用的身份，并且所选模型已为您的账户和区域启用

582* 运行 `aws sts get-caller-identity` 以确认您的请求使用哪个身份；过时的 `AWS_PROFILE` 或默认配置文件是权限不匹配的常见原因603* 运行 `aws sts get-caller-identity` 确认您的请求使用哪个身份；过时的 `AWS_PROFILE` 或默认配置文件是权限不匹配的常见原因

583 604

584<h2 id="network-and-connection-errors">605<h2 id="network-and-connection-errors">

585 网络和连接错误606 网络和连接错误

586</h2>607</h2>

587 608

588这些错误意味着来自 Claude Code 的网络请求无法到达其目的地。它们通常源于您的本地网络、代理或防火墙，或云环境的网络策略。609这些错误表示来自 Claude Code 的网络请求未能到达其目的地。它们通常源于您的本地网络、代理或防火墙，或云环境的网络策略。

589 610

590<h3 id="unable-to-connect-to-api">611<h3 id="unable-to-connect-to-api">

591 Unable to connect to API612 无法连接到 API

592</h3>613</h3>

593 614

594到 API 的 TCP 连接失败或从未完成。615与 API 的 TCP 连接失败或从未完成。

595 616

596```text theme={null}617```text theme={null}

597Unable to connect to API. Check your internet connection618Unable to connect to API. Check your internet connection

602Request timed out. Check your internet connection and proxy settings623Request timed out. Check your internet connection and proxy settings

603```624```

604 625

605常见原因包括没有互联网访问、阻止 `api.anthropic.com` 的 VPN 或未配置的必需公司代理。626常见原因包括没有互联网访问、阻止 `api.anthropic.com` 的 VPN，或未配置的必需企业代理。

606 627

607**要做什么：**628**应该做什么：**

608 629

609* 通过从同一 shell 运行 `curl -I https://api.anthropic.com` 来确认您可以到达 API 主机。在 Windows PowerShell 上使用 `curl.exe -I https://api.anthropic.com`，以便不使用内置的 `Invoke-WebRequest` 别名。630* 通过在同一 shell 中运行 `curl -I https://api.anthropic.com` 来确认您可以到达 API 主机。在 Windows PowerShell 上使用 `curl.exe -I https://api.anthropic.com`，以便不使用内置的 `Invoke-WebRequest` 别名。

610* 如果您在公司代理后面，请在启动 Claude Code 之前设置 `HTTPS_PROXY` 并参阅[网络配置](/zh-CN/network-config)631* 如果您在企业代理后面，请在启动 Claude Code 之前设置 `HTTPS_PROXY`，并参阅[网络配置](/zh-CN/network-config)

611* 如果您通过 LLM 网关或中继路由，请将 [`ANTHROPIC_BASE_URL`](/zh-CN/env-vars) 设置为其地址。有关设置，请参阅[将 Claude Code 连接到 LLM 网关](/zh-CN/llm-gateway-connect)。632* 如果您通过 LLM 网关或中继路由，请将 [`ANTHROPIC_BASE_URL`](/zh-CN/env-vars) 设置为其地址。有关设置，请参阅[将 Claude Code 连接到 LLM 网关](/zh-CN/llm-gateway-connect)。

612* 确保您的防火墙允许[网络访问要求](/zh-CN/network-config#network-access-requirements)中列出的主机633* 确保您的防火墙允许[网络访问要求](/zh-CN/network-config#network-access-requirements)中列出的主机

613* 间歇性故障会[自动重试](#automatic-retries)；持续故障指向本地网络问题634* 间歇性故障会[自动重试](#automatic-retries)；持续故障指向本地网络问题

614 635

615如果 `curl` 成功但 Claude Code 仍然失败，原因通常是运行时和网络之间的某些东西，而不是网络本身：636如果 `curl` 成功但 Claude Code 仍然失败，原因通常是运行时和网络之间的某些东西，而不是网络本身：

616 637

617* 在 Linux 和 WSL 上，检查 `/etc/resolv.conf` 是否有无法到达的名称服务器。特别是 WSL 可以从主机继承损坏的解析器。638* 在 Linux 和 WSL 上，检查 `/etc/resolv.conf` 是否有无法到达的名称服务器。特别是 WSL 可能会从主机继承损坏的解析器。

618* 在 macOS 上，已断开连接或卸载的 VPN 客户端可能会留下隧道接口或路由规则。检查 `ifconfig` 以查找过时的 `utun` 接口，并在系统设置中删除 VPN 的网络扩展。639* 在 macOS 上，已断开连接或卸载的 VPN 客户端可能会留下隧道接口或路由规则。检查 `ifconfig` 是否有过时的 `utun` 接口，并在系统设置中删除 VPN 的网络扩展。

619* Docker Desktop 和类似的容器运行时可以拦截出站流量。退出它们并重试以排除这一点。640* Docker Desktop 和类似的容器运行时可能会拦截出站流量。退出它们并重试以排除这种可能性。

620 641

621<h3 id="ssl-certificate-errors">642<h3 id="ssl-certificate-errors">

622 SSL certificate errors643 SSL 证书错误

623</h3>644</h3>

624 645

625您网络上的代理或安全设备正在使用其自己的证书拦截 TLS 流量，而 Claude Code 不信任它。646您网络上的代理或安全设备正在用其自己的证书拦截 TLS 流量，而 Claude Code 不信任它。

626 647

627```text theme={null}648```text theme={null}

628Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates649Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates

629Unable to connect to API: Self-signed certificate detected650Unable to connect to API: Self-signed certificate detected

630```651```

631 652

632{/* min-version: 2.1.199 */}}从 v2.1.199 开始，证书验证失败不会重试，因此此错误出现在第一次尝试而不是在完整[重试预算](#automatic-retries)之后。早期版本在显示之前花费几分钟重试。瞬时 TLS 条件（例如握手超时）仍然会重试。653{/* min-version: 2.1.199 */}从 v2.1.199 开始，证书验证失败不会重试，因此此错误在第一次尝试时出现，而不是在完整[重试预算](#automatic-retries)之后。早期版本在显示它之前花费几分钟重试。瞬时 TLS 条件（例如握手超时）仍然会重试。

633 654

634在 `/login` 和启动连接检查期间，相同的失败会报告为 OpenSSL 代码和内联修复：655在 `/login` 和启动连接检查期间，使用 OpenSSL 代码和内联修复报告相同的失败：

635 656

636```text theme={null}657```text theme={null}

637SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run /doctor for details.658SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run `claude doctor` for details.

638```659```

639 660

640**要做什么：**661**应该做什么：**

641 662

642* 导出您组织的 CA 包并使用 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` 指向 Claude Code663* 导出您组织的 CA 包，并使用 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` 将 Claude Code 指向它

643* 有关完整设置说明，请参阅[网络配置](/zh-CN/network-config#custom-ca-certificates)664* 有关完整设置说明，请参阅[网络配置](/zh-CN/network-config#custom-ca-certificates)

644* 不要设置 `NODE_TLS_REJECT_UNAUTHORIZED=0`，这会完全禁用证书验证665* 不要设置 `NODE_TLS_REJECT_UNAUTHORIZED=0`，这会完全禁用证书验证

645 666

646<h3 id="host-not-allowed-in-a-cloud-session">667<h3 id="host-not-allowed-in-a-cloud-session">

647 Host not allowed in a cloud session668 云会话中不允许的主机

648</h3>669</h3>

649 670

650来自云会话或例程的出站 HTTP 请求被环境的网络策略阻止。671来自云会话或例程的出站 HTTP 请求被环境的网络策略阻止。

656 677

657您也可能看到与目的地真实证书不匹配的 TLS 证书。云环境通过代理路由出站流量以强制执行网络策略，因此证书不匹配意味着代理终止了连接，而不是目的地。678您也可能看到与目的地真实证书不匹配的 TLS 证书。云环境通过代理路由出站流量以强制执行网络策略，因此证书不匹配意味着代理终止了连接，而不是目的地。

658 679

659这不是客户端网络问题。云会话和[例程](/zh-CN/routines)在沙箱环境内运行，其出站流量被过滤到环境的允许列表。**Default** 环境使用 **Trusted** 访问，允许[默认允许列表](/zh-CN/claude-code-on-the-web#default-allowed-domains)中的包注册表、云提供商 API、容器注册表和常见开发域，但阻止其他所有内容。680这不是客户端网络问题。云会话和[例程](/zh-CN/routines)在沙箱环境内运行，其出站流量被过滤到环境的允许列表。**默认**环境使用**受信任**访问，允许[默认允许列表](/zh-CN/claude-code-on-the-web#default-allowed-domains)中的包注册表、云提供商 API、容器注册表和常见开发域，但阻止其他所有内容。

660 681

661**要做什么：**682**应该做什么：**

662 683

663* 打开例程进行编辑，或启动云会话。选择显示您的环境名称（如 **Default**）的云图标以打开选择器。将鼠标悬停在您的环境上并单击设置图标。684* 打开例程进行编辑，或启动云会话。选择显示您的环境名称（例如**默认**）的云图标以打开选择器。将鼠标悬停在您的环境上，然后单击设置图标。

664* 在 **Update cloud environment** 对话框中，将 **Network access** 从 **Trusted** 更改为 **Custom**，然后将被阻止的域添加到 **Allowed domains**。每行输入一个域。选中 **Also include default list of common package managers** 以在自定义域旁边保留[默认允许列表](/zh-CN/claude-code-on-the-web#default-allowed-domains)。如果您想要不受限制的访问，请改为选择 **Full**。685* 在**更新云环境**对话框中，将**网络访问**从**受信任**更改为**自定义**，然后将被阻止的域添加到**允许的域**。每行输入一个域。选中**也包括常见包管理器的默认列表**以在自定义域旁边保留[默认允许列表](/zh-CN/claude-code-on-the-web#default-allowed-domains)。如果您想要不受限制的访问，请改为选择**完全**。

665* 单击 **Save changes**。下一次运行使用更新的允许列表。686* 单击**保存更改**。下一次运行使用更新的允许列表。

666 687

667有关访问级别和默认允许列表，请参阅[网络访问](/zh-CN/claude-code-on-the-web#network-access)。本地 CLI 会话不受此策略影响。688有关访问级别和默认允许列表，请参阅[网络访问](/zh-CN/claude-code-on-the-web#network-access)。本地 CLI 会话不受此策略影响。

668 689

690<h3 id="couldn’t-reconnect-to-your-remote-control-session">

691 无法重新连接到您的 Remote Control 会话

692</h3>

693

694```text theme={null}

695Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.

696```

697

698使用 `claude --resume` 或 `claude --continue` 恢复会重新连接到该对话中记录的 [Remote Control](/zh-CN/remote-control) 会话。此消息意味着重新连接因可能是临时的原因（例如网络中断或服务器错误）而失败，因此 Claude Code 无法确认远程会话是否仍然存在。您的本地会话继续运行而不使用 Remote Control。

699

700**应该做什么：**

701

702* 运行 `/remote-control` 以重试连接

703* 启动 Claude Code 而不使用 `--resume` 以创建新的 Remote Control 会话

704* 有关其他 Remote Control 启动消息，请参阅[排查 Remote Control 故障](/zh-CN/remote-control#troubleshooting)

705

706当服务器确认前一个会话不再存在时，您不会看到此消息；Claude Code 在这种情况下会创建一个新的会话。{/* min-version: 2.1.200 */}在 v2.1.200 之前，任何重新连接失败都会创建一个新的 Remote Control 会话，这在 claude.ai/code 的会话列表中留下了额外的会话。

707

669<h2 id="request-errors">708<h2 id="request-errors">

670 请求错误709 请求错误

671</h2>710</h2>

672 711

673这些错误意味着 API 收到了您的请求但拒绝了其内容。712这些错误与您的请求内容有关。大多数来自 API 在拒绝请求后的返回；少数是由 Claude Code 在发送任何请求之前在本地生成的。

674 713

675<h3 id="prompt-is-too-long">714<h3 id="prompt-is-too-long">

676 Prompt is too long715 Prompt is too long

682Prompt is too long721Prompt is too long

683```722```

684 723

685**要做什么：**724**应该做什么：**

686 725

687* 运行 `/compact` 以总结早期轮次并释放空间，或运行 `/clear` 以重新开始726* 运行 `/compact` 来总结早期的回合并释放空间，或运行 `/clear` 来重新开始

688* 运行 `/context` 以查看消耗窗口的内容的分解：系统提示、工具、内存文件和消息727* 运行 `/context` 来查看消耗窗口的内容分解：系统提示、工具、内存文件和消息

689* 使用 `/mcp disable <name>` 禁用您未使用的 MCP 服务器，以从上下文中删除其工具定义728* 使用 `/mcp disable <name>` 禁用您未使用的 MCP 服务器，以从上下文中移除其工具定义

690* 修剪大型 `CLAUDE.md` 内存文件，或将说明移到仅在相关时加载的[路径范围规则](/zh-CN/memory#path-specific-rules)中729* 修剪大型 `CLAUDE.md` 内存文件，或将说明移到[路径范围规则](/zh-CN/memory#path-specific-rules)中，这些规则仅在相关时加载

691* 子代理从父会话继承每个 MCP 工具定义，这可能在第一轮之前填满它们的上下文窗口。在生成子代理之前禁用您未使用的 MCP 服务器。730* 子代理从父会话继承每个 MCP 工具定义，这可能会在第一个回合之前填满它们的上下文窗口。在生成子代理之前禁用您未使用的 MCP 服务器。

692* 自动压缩默认启用，通常可防止此错误。如果您已设置 [`DISABLE_AUTO_COMPACT`](/zh-CN/env-vars)，请重新启用它或在窗口填满之前手动运行 `/compact`。731* 自动压缩默认启用，通常可以防止此错误。如果您设置了 [`DISABLE_AUTO_COMPACT`](/zh-CN/env-vars)，请重新启用它或在窗口填满之前手动运行 `/compact`。

693 732

694有关上下文如何填满的交互式视图，请参阅[探索上下文窗口](/zh-CN/context-window)。733请参阅[探索上下文窗口](/zh-CN/context-window)以获得上下文如何填充的交互式视图。

695 734

696<h3 id="error-during-compaction-conversation-too-long">735<h3 id="error-during-compaction-conversation-too-long">

697 Error during compaction: Conversation too long736 Error during compaction: Conversation too long

698</h3>737</h3>

699 738

700`/compact` 本身失败，因为没有足够的可用上下文来保存它生成的摘要。739`/compact` 本身失败，因为没有足够的可用上下文来容纳它生成的摘要。

701 740

702```text theme={null}741```text theme={null}

703Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.742Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.

704```743```

705 744

706当窗口在自动压缩触发时已满，或在看到 `Prompt is too long` 后运行 `/compact` 时，可能会发生这种情况。745当窗口在自动压缩触发时已经满了，或者在看到 `Prompt is too long` 后运行 `/compact` 时，可能会发生这种情况。

707 746

708**要做什么：**747**应该做什么：**

709 748

710* 按 Esc 两次打开消息列表并回退几轮。这会从上下文中删除最近的消息。然后再次运行 `/compact`。749* 按 Esc 两次打开消息列表并回退几个回合。这会从上下文中删除最近的消息。然后再次运行 `/compact`。

711* 如果回退没有释放足够的空间，请运行 `/clear` 以启动新的会话。您之前的对话已保存，可以使用 `/resume` 重新打开。750* 如果回退没有释放足够的空间，运行 `/clear` 来启动新的会话。您之前的对话会被保留，可以使用 `/resume` 重新打开。

712 751

713<h3 id="request-too-large">752<h3 id="request-too-large">

714 Request too large753 Request too large

722 761

723这是 HTTP 请求的大小限制，与[上下文窗口限制](#prompt-is-too-long)分开。762这是 HTTP 请求的大小限制，与[上下文窗口限制](#prompt-is-too-long)分开。

724 763

725**要做什么：**764**应该做什么：**

726 765

727* 按 Esc 两次并回退到添加超大内容的轮次之前766* 按 Esc 两次并回退到添加超大内容的回合之前

728* 按路径引用大文件而不是粘贴其内容，以便 Claude 可以分块读取它们767* 通过路径引用大文件而不是粘贴其内容，以便 Claude 可以分块读取它们

729* 对于图像，请参阅下面的[图像太大](#image-was-too-large)768* 对于图像，请参阅下面的[图像太大](#image-was-too-large)

730 769

731<h3 id="image-was-too-large">770<h3 id="image-was-too-large">

739API Error: 400 ... image dimensions exceed max allowed size778API Error: 400 ... image dimensions exceed max allowed size

740```779```

741 780

742{/* min-version: 2.1.142 */}}Claude Code 将无法处理的图像替换为文本占位符并重试，因此后续消息成功。在 2.1.142 之前的版本上，粘贴的图像可能保留在对话中，并在每个后续消息上重复相同的错误。要在这些版本上恢复，请按 Esc 两次并回退到添加图像的轮次之前。781{/* min-version: 2.1.142 */}Claude Code 将无法处理的图像替换为文本占位符并重试，因此后续消息成功。在 2.1.142 之前的版本中，粘贴的图像可能会保留在对话中，并在后续的每条消息上重复相同的错误。要在这些版本上恢复，请按 Esc 两次并回退到添加图像的回合之前。

743 782

744**要做什么：**783**应该做什么：**

745 784

746* 在粘贴之前调整图像大小。API 接受单个图像最长边最多 8000 像素的图像，或当许多图像在上下文中时为 2000 像素。785* 在粘贴之前调整图像大小。API 接受单个图像最长边最多 8000 像素的图像，或当许多图像在上下文中时为 2000 像素。

747* 拍摄相关区域的更紧密屏幕截图，而不是整个屏幕786* 拍摄相关区域的更紧密屏幕截图，而不是整个屏幕

750 Unable to resize image789 Unable to resize image

751</h3>790</h3>

752 791

753Claude Code 无法在将附加的图像发送到 API 之前缩小其大小。792Claude Code 无法在将附加图像发送到 API 之前对其进行缩小。

754 793

755```text theme={null}794```text theme={null}

756Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.795Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.

759Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.798Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.

760```799```

761 800

762Claude Code 通常会自动调整大型图像的大小。这些错误意味着本机图像处理器无法加载或返回了错误，因此无法调整图像大小以适应 API 限制。801Claude Code 通常会自动调整大型图像的大小。这些错误意味着本机图像处理器无法加载或返回错误，因此无法调整图像大小以适应 API 限制。

763 802

764**要做什么：**803**应该做什么：**

765 804

766* 如果消息要求您转换图像，请将其转换为 PNG、JPEG、GIF 或 WebP 并再次附加。Claude Code 可以验证这些格式的尺寸，而无需图像处理器。805* 如果消息要求您转换图像，请将其转换为 PNG、JPEG、GIF 或 WebP，然后再次附加。Claude Code 可以在不使用图像处理器的情况下验证这些格式的尺寸。

767* 如果消息报告尺寸或大小限制，请在附加之前将图像调整大小或重新压缩到该限制以下。806* 如果消息报告尺寸或大小限制，请在附加之前将图像调整大小或重新压缩到该限制以下。

768 807

769<h3 id="pdf-errors">808<h3 id="pdf-errors">

778The PDF file was not valid. Try converting to a different format first.817The PDF file was not valid. Try converting to a different format first.

779```818```

780 819

781**要做什么：**820**应该做什么：**

782 821

783* 对于超大 PDF，要求 Claude 使用 Read 工具读取页面范围而不是附加整个文件，或使用 `pdftotext` 等工具提取文本并按路径引用输出文件822* 对于超大 PDF，要求 Claude 使用 Read 工具读取页面范围而不是附加整个文件，或使用 `pdftotext` 之类的工具提取文本并通过路径引用输出文件

784* 对于受保护或无效的 PDF，删除密码或从其源应用程序重新导出文件，然后重试823* 对于受保护或无效的 PDF，删除密码或从其源应用程序重新导出文件，然后重试

785 824

786<h3 id="extra-inputs-are-not-permitted">825<h3 id="extra-inputs-are-not-permitted">

787 Extra inputs are not permitted826 Extra inputs are not permitted

788</h3>827</h3>

789 828

790Claude Code 和 API 之间的代理或 LLM 网关删除了 `anthropic-beta` 请求标头，因此 API 拒绝了依赖它的字段。829Claude Code 和 API 之间的代理或 LLM 网关删除了 `anthropic-beta` 请求头，因此 API 拒绝了依赖它的字段。

791 830

792```text theme={null}831```text theme={null}

793API Error: 400 ... Extra inputs are not permitted ... context_management832API Error: 400 ... Extra inputs are not permitted ... context_management

795API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header834API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header

796```835```

797 836

798Claude Code 发送仅限 beta 的字段，如 `context_management`、`effort` 和工具 `input_examples`，以及启用它们的 `anthropic-beta` 标头。当网关转发正文但删除标头时，API 看到它不识别的字段。837Claude Code 发送仅限测试版的字段，如 `context_management`、`effort` 和工具 `input_examples`，以及启用它们的 `anthropic-beta` 头。当网关转发正文但删除头时，API 会看到它不识别的字段。

799 838

800**要做什么：**839**应该做什么：**

801 840

802* 配置您的网关以转发 `anthropic-beta` 标头。请参阅[功能传递](/zh-CN/llm-gateway-protocol#feature-pass-through)了解网关必须转发的内容。841* 配置您的网关以转发 `anthropic-beta` 头。请参阅[功能传递](/zh-CN/llm-gateway-protocol#feature-pass-through)了解网关必须转发的内容。

803* 作为后备，在启动之前设置 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/zh-CN/env-vars)。这会禁用需要 beta 标头的功能，以便请求通过无法转发它的网关成功。842* 作为备选方案，在启动前设置 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/zh-CN/env-vars)。这会禁用需要测试版头的功能，以便请求通过无法转发它的网关成功。

804 843

805<h3 id="there’s-an-issue-with-the-selected-model">844<h3 id="there’s-an-issue-with-the-selected-model">

806 There's an issue with the selected model845 There's an issue with the selected model

807</h3>846</h3>

808 847

809{/* min-version: 2.1.160 */}}848配置的模型名称未被识别，或您的账户无权访问它。从 v2.1.160 开始，尾部提示（此处以其交互形式显示）因表面而异。

810配置的模型名称未被识别或您的帐户缺少对它的访问权限。从 v2.1.160 开始，尾部提示（此处以其交互式形式显示）因表面而异。

811 849

812```text theme={null}850```text theme={null}

813There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.851There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.

814```852```

815 853

816**要做什么：**854**应该做什么：**

855

856* **交互式 CLI**：运行 `/model` 从您账户可用的模型中选择。

857* **非交互模式 (`-p`)**：使用有效的别名或 ID 传递 `--model`，或设置 [`ANTHROPIC_MODEL`](/zh-CN/env-vars)。错误文本在此表面上显示 `Run --model`。

858* **Agent SDK**：错误文本省略提示，因为模型是以编程方式设置的。在 TypeScript 中设置 [`Options` 上的 `model`](/zh-CN/agent-sdk/typescript#options) 或在 Python 中设置 [`ClaudeAgentOptions(model=...)`](/zh-CN/agent-sdk/python#claudeagentoptions)，并处理结构化的 `model_not_found` 错误以显示您自己的重试或模型选择器。

859* 使用别名（如 `sonnet` 或 `opus`）而不是完整的版本化 ID。别名解析为维护的默认值，因此不会过时。请参阅[模型配置](/zh-CN/model-config)。

860* 如果 CLI 中一直返回错误的模型，则某处设置了过时的 ID。按[优先级顺序](/zh-CN/model-config#setting-your-model)检查：`--model` 标志、`ANTHROPIC_MODEL` 环境变量，然后是 `.claude/settings.local.json` 中的 `model` 字段、您项目的 `.claude/settings.json` 和 `~/.claude/settings.json`。删除过时的值，Claude Code 会回退到您的账户默认值。

861* 对于 Google Cloud 的 Agent Platform 部署，请参阅 [Google Cloud 的 Agent Platform 故障排除](/zh-CN/google-vertex-ai#troubleshooting)。

862

863<h3 id="model-is-not-a-recognized-model-id">

864 Model is not a recognized model id

865</h3>

817 866

818* **交互式 CLI**：运行 `/model` 以从您的帐户可用的模型中选择。867您传递给模型切换的模型字符串不是模型别名、此 Claude Code 版本知道的模型 ID，也不是以 `claude-` 开头的 ID。常见原因是 ID 中的拼写错误、显示名称（如 `Sonnet 5`，其中需要 ID `claude-sonnet-5`）或仅较新 Claude Code 版本识别的别名。Claude Code 立即拒绝切换。在 v2.1.200 之前，Claude Code 保存字符串并在下一个请求时失败，出现[所选模型有问题](#there%E2%80%99s-an-issue-with-the-selected-model)。

819* **非交互模式（`-p`）**：使用有效的别名或 ID 传递 `--model`，或设置 [`ANTHROPIC_MODEL`](/zh-CN/env-vars)。错误文本在此表面上显示 `Run --model`。868

820* **Agent SDK**：错误文本省略提示，因为模型是以编程方式设置的。在 TypeScript 中的 [`Options`](/zh-CN/agent-sdk/typescript#options) 上设置 [`model`](/zh-CN/agent-sdk/typescript#options)，或在 Python 中设置 [`ClaudeAgentOptions(model=...)`](/zh-CN/agent-sdk/python#claudeagentoptions)，并处理结构化的 `model_not_found` 错误以显示您自己的重试或模型选择器。869```text theme={null}

821* 使用别名（如 `sonnet` 或 `opus`）而不是完整的版本化 ID。别名跟踪最新版本，因此它们不会过时。请参阅[模型配置](/zh-CN/model-config)。870Model "claud-sonnet-5" is not a recognized model id. Did you mean 'claude-sonnet-5'?

822* 如果错误的模型一直出现在 CLI 中，则某处设置了过时的 ID。按[优先级顺序](/zh-CN/model-config#setting-your-model)检查：`--model` 标志、`ANTHROPIC_MODEL` 环境变量，然后是 `.claude/settings.local.json` 中的 `model` 字段、您项目的 `.claude/settings.json` 和 `~/.claude/settings.json`。删除过时的值，Claude Code 将回退到您的帐户默认值。871```

823* 对于 Vertex AI 部署，请参阅 [Vertex AI 故障排除](/zh-CN/google-vertex-ai#troubleshooting)。872

873尾部提示命名最接近的匹配别名或模型 ID。当没有足够接近的内容时，它读作 `Run /model to see available models.`。

874

875Claude Code 在请求切换时在本地生成此错误，在发出任何 API 请求之前。它适用于通过 [Agent SDK](/zh-CN/agent-sdk/typescript) `setModel()` 方法或为您运行 Claude Code CLI 的应用程序（如 [Desktop app](/zh-CN/desktop)）设置模型的情况。

876

877**应该做什么：**

878

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

880* 如果您使用了较新 Claude Code 版本支持的别名，运行 `claude update`。以 `claude-` 开头的完整 ID 即使模型比您的 Claude Code 版本更新，也会通过此检查，因此不需要升级。

881* v2.1.200 之前保存的模型不会被此检查修复。如果过时的值一直出现，请从[所选模型有问题](#there%E2%80%99s-an-issue-with-the-selected-model)下列出的位置中删除它。

882* 检查仅在 Anthropic API 上运行。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 和 [LLM 网关](/zh-CN/llm-gateway)后面或自定义 `ANTHROPIC_BASE_URL`，您的提供商或网关定义模型名称，因此 Claude Code 接受任何字符串并将其传递。

824 883

825<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">884<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">

826 Claude Opus is not available with the Claude Pro plan885 Claude Opus is not available with the Claude Pro plan

832Claude Opus is not available with the Claude Pro plan · Select a different model in /model891Claude Opus is not available with the Claude Pro plan · Select a different model in /model

833```892```

834 893

835**要做什么：**894**应该做什么：**

836 895

837* 运行 `/model` 并选择您的计划包括的模型896* 运行 `/model` 并选择您的计划包含的模型

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

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

840 899

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

842 Model is restricted by your organization's settings901 Model is restricted by your organization's settings

843</h3>902</h3>

844 903

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

846 905

847```text theme={null}906```text theme={null}

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

849```908```

850 909

851**要做什么：**910Claude Code 将模型族别名（`opus`、`sonnet`、`haiku` 或 `fable` 之一）视为对该族的请求，而不是对其最新版本的请求。在 Anthropic API 和 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 上，受限的族别名解析为您的组织和 `availableModels` 允许列表允许的族的最新版本，替换通知命名该版本。Claude Code 仅当族的每个版本都受限时才拒绝 `/model <alias>`。在 v2.1.205 之前，族别名基于其最新版本单独替换或拒绝，即使同一族的较旧版本被允许。

911

912**应该做什么：**

852 913

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

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

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

856 917

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

858 thinking.type.enabled is not supported for this model919 thinking.type.enabled is not supported for this model

859</h3>920</h3>

860 921

861您的 Claude Code 版本早于 Sonnet 5、Opus 4.8 或 Opus 4.7 的最低版本。CLI 发送了模型不再接受的思考配置。922您的 Claude Code 版本比 Sonnet 5、Opus 4.8 或 Opus 4.7 的最低版本更旧。CLI 发送了模型不再接受的思考配置。

862 923

863```text theme={null}924```text theme={null}

864API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.925API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

865```926```

866 927

867**要做什么：**928**应该做什么：**

~~868~~

869{/* min-version: 2.1.197 */}}

870 929

871* 运行 `claude update` 并重新启动 Claude Code。Opus 4.7 需要 v2.1.111 或更高版本。Opus 4.8 需要 v2.1.154 或更高版本。Sonnet 5 需要 v2.1.197 或更高版本930* 运行 `claude update` 并重启 Claude Code。Opus 4.7 需要 v2.1.111 或更高版本。Opus 4.8 需要 v2.1.154 或更高版本。Sonnet 5 需要 v2.1.197 或更高版本

872* 如果您无法升级，请运行 `/model` 并选择 Opus 4.6 或 Sonnet 4.6 代替931* 如果您无法升级，运行 `/model` 并改为选择 Opus 4.6 或 Sonnet 4.6

873* {/* min-version: agent-sdk@0.3.197 */}}如果您在 [Agent SDK](/zh-CN/agent-sdk/overview) 中遇到这个，请升级 SDK 包。Opus 4.8 需要 TypeScript SDK v0.3.154 或更高版本和 Python SDK v0.2.88 或更高版本。Sonnet 5 需要 TypeScript SDK v0.3.197 或更高版本932* {/* min-version: agent-sdk@0.3.197 */}如果您在 [Agent SDK](/zh-CN/agent-sdk/overview) 中遇到这个问题，请升级 SDK 包。Opus 4.8 需要 TypeScript SDK v0.3.154 或更高版本和 Python SDK v0.2.88 或更高版本。Sonnet 5 需要 TypeScript SDK v0.3.197 或更高版本

874 933

875<h3 id="thinking-budget-exceeds-output-limit">934<h3 id="thinking-budget-exceeds-output-limit">

876 Thinking budget exceeds output limit935 Thinking budget exceeds output limit

882API Error: 400 ... max_tokens must be greater than thinking.budget_tokens941API Error: 400 ... max_tokens must be greater than thinking.budget_tokens

883```942```

884 943

885Claude Code 在 Anthropic API 上自动调整这些值。当 [`MAX_THINKING_TOKENS`](/zh-CN/env-vars) 设置高于提供商的输出限制时，或当计划模式提高思考预算时，您通常会在 Amazon Bedrock 或 Google Vertex AI 上看到此错误。944Claude Code 在 Anthropic API 上自动调整这些值。您通常在 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上看到此错误，当 [`MAX_THINKING_TOKENS`](/zh-CN/env-vars) 设置高于提供商的输出限制时，或当计划模式提高思考预算时。

886 945

887**要做什么：**946**应该做什么：**

888 947

889* 降低 `MAX_THINKING_TOKENS`，或将 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/zh-CN/env-vars) 提高到思考预算之上948* 降低 `MAX_THINKING_TOKENS`，或将 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/zh-CN/env-vars) 提高到思考预算之上

890* 有关预算如何与输出长度交互的信息，请参阅[扩展思考](/zh-CN/model-config#extended-thinking)949* 请参阅[扩展思考](/zh-CN/model-config#extended-thinking)了解预算如何与输出长度相互作用

891 950

892<h3 id="tool-use-or-thinking-block-mismatch">951<h3 id="tool-use-or-thinking-block-mismatch">

893 Tool use or thinking block mismatch952 Tool use or thinking block mismatch

894</h3>953</h3>

895 954

896对话历史以不一致的状态到达 API，通常是在工具调用被中断或轮次在流中途被编辑后。955对话历史以不一致的状态到达 API，通常是在工具调用被中断或回合在流中途被编辑后。

897 956

898```text theme={null}957```text theme={null}

899API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.958API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.

903 962

904所有三个变体都意味着同一件事：历史中 `tool_use`、`tool_result` 和 `thinking` 块的序列不再与 API 期望的相匹配。963所有三个变体都意味着同一件事：历史中 `tool_use`、`tool_result` 和 `thinking` 块的序列不再与 API 期望的相匹配。

905 964

906**要做什么：**965**应该做什么：**

907 966

908* {/* max-version: 2.1.155 */}}如果您使用的是 Opus 4.7 或 Opus 4.8，请先运行 `claude update`。v2.1.156 之前的版本可能在正常工具使用期间触发此错误，并且 `/rewind` 无法清除它。967* {/* max-version: 2.1.155 */}如果您使用的是 Opus 4.7 或 Opus 4.8，请先运行 `claude update`。v2.1.156 之前的版本可能在正常工具使用期间触发此错误，`/rewind` 不会清除它。

909* 运行 `/rewind`，或按 Esc 两次，回退到损坏轮次之前的检查点并从那里继续。有关如何创建和恢复检查点的信息，请参阅[检查点](/zh-CN/checkpointing)。968* 运行 `/rewind` 或按 Esc 两次，回退到损坏回合之前的检查点并从那里继续。请参阅[检查点](/zh-CN/checkpointing)了解如何创建和恢复检查点。

910 969

911<h3 id="usage-policy-refusal">970<h3 id="usage-policy-refusal">

912 Usage Policy refusal971 Usage Policy refusal

913</h3>972</h3>

914 973

915API 拒绝响应，因为对话中的内容触发了[使用政策](https://www.anthropic.com/legal/aup)检查。该消息包含一个请求 ID，如果您认为拒绝不正确，可以向支持部门引用。974API 拒绝响应，因为对话中的内容触发了[使用政策](https://www.anthropic.com/legal/aup)检查。消息包含一个请求 ID，如果您认为拒绝不正确，可以向支持部门引用。

916 975

917```text theme={null}976```text theme={null}

918API Error: Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.977API Error: Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.

919```978```

920 979

921该检查评估整个对话，而不仅仅是您的最新提示，因此在同一会话中发送新消息通常会重新触发相同的拒绝。使用 `--continue` 或 `--resume` 退出并重新打开会话后也是如此，因为磁盘上的记录仍然包含触发内容。980检查评估完整对话，而不仅仅是您的最新提示，因此在同一会话中发送新消息通常会重新触发相同的拒绝。在使用 `--continue` 或 `--resume` 退出并重新打开会话后也是如此，因为磁盘上的记录仍然包含触发内容。在 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/zh-CN/microsoft-foundry) 上，此消息也涵盖模型的安全措施标记为网络安全主题的请求。请参阅[安全措施标记了网络安全主题](#safety-measures-flagged-a-cybersecurity-topic)。

922 981

923**要做什么：**982**应该做什么：**

924 983

925* 按 Esc 两次或运行 `/rewind` 以回退到触发拒绝的轮次之前的检查点，然后重新表述或采取不同的方法。有关检查点的信息，请参阅[检查点](/zh-CN/checkpointing)。984* 按 Esc 两次或运行 `/rewind` 回退到触发拒绝的回合之前的检查点，然后重新表述或采取不同的方法。请参阅[检查点](/zh-CN/checkpointing)。

926* 如果您无法识别哪个轮次导致了它，请运行 `/clear` 以在同一项目中启动新的对话。您之前的对话已保存在磁盘上，并且在 `/resume` 中仍然可用。985* 如果您无法识别哪个回合导致了它，运行 `/clear` 在同一项目中启动新对话。您之前的对话保留在磁盘上，在 `/resume` 中仍然可用。

927* 在[非交互模式](/zh-CN/headless)（`-p`）中，其中 rewind 不可用，使用重新表述的提示重试或启动新会话而不使用 `--continue`。986* 在[非交互模式](/zh-CN/headless)(`-p`) 中，其中 rewind 不可用，在没有 `--continue` 的新会话中使用重新表述的提示重试。政策检查因模型而异，因此使用 `--model` 切换到不同的模型也可能在某些情况下解决拒绝。

987

988<h3 id="safety-measures-flagged-a-cybersecurity-topic">

989 Safety measures flagged a cybersecurity topic

990</h3>

991

992模型的安全措施将对话中的内容标记为网络安全主题。消息命名标记请求的模型：

993

994```text theme={null}

995API Error: Opus 4.8 has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude.

996

997If you were not engaging in a cybersecurity topic, please send feedback via /feedback.

998```

999

1000消息链接到[网络验证计划](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)，该计划为合法网络安全工作授予访问权限。保护措施本身是服务器端的，早于 v2.1.203；此版本仅更改了消息的措辞和它链接到的页面。

1001

1002您看到的内容取决于您的提供商和模式：

1003

1004* 在 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/zh-CN/microsoft-foundry) 上，网络安全标志会产生[使用政策拒绝](#usage-policy-refusal)消息。

1005* [非交互模式](/zh-CN/headless)省略 `/feedback` 句子。

1006

1007{/* max-version: 2.1.202 */}在 v2.1.203 之前，消息读作 `<model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:` 后跟豁免表单链接。

1008

1009**应该做什么：**

1010

1011* 如果您的工作需要此内容，请通过[网络验证计划](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)申请访问权限

1012* 如果您的请求不是关于网络安全主题，运行 `/feedback` 来报告误报

1013* 要在同一会话中继续工作，按 Esc 两次或运行 `/rewind` 回退到触发标志的回合之前的检查点，然后采取不同的方法。请参阅[检查点](/zh-CN/checkpointing)。

1014

1015<h2 id="installation-errors">

1016 安装错误

1017</h2>

1018

1019这些错误在安装或更新 Claude Code 时出现，来自[安装脚本](/zh-CN/setup#install-claude-code)、`claude install` 或 `claude update`。对于设置期间的 `command not found`、PATH、权限和 TLS 问题，请参阅[排查安装和登录问题](/zh-CN/troubleshoot-install)。

1020

1021<h3 id="installation-was-killed-before-it-could-finish">

1022 安装在完成前被中止

1023</h3>

1024

1025安装脚本会报告 `claude install` 步骤何时被信号终止。在 Linux 上，退出代码 137 表示进程收到了 SIGKILL，在低内存主机上通常是内核内存不足 (OOM) 杀手。脚本打印此说明并以代码 137 退出：

1026

1027```text theme={null}

1028Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.

1029Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

1030```

1031

1032对于任何其他致命信号，以及 macOS 上的退出代码 137，脚本打印 `Installation was killed before it could finish (exit code <N>)`，其中包含实际退出代码，并省略内存不足的说明。该消息来自 macOS 和 Linux 使用的安装脚本，该脚本也涵盖 WSL 内的安装；本机 Windows 安装脚本永远不会打印它。在 v2.1.200 之前，脚本仅以 shell 的裸 `Killed` 行退出。

1033

1034**应该做什么：**

1035

1036* 停止其他进程以释放内存，然后重新运行安装程序

1037* 添加交换空间或移至更大的实例。有关交换文件命令，请参阅[在低内存 Linux 服务器上安装被中止](/zh-CN/troubleshoot-install#install-killed-on-low-memory-linux-servers)。

1038

1039<h3 id="the-connection-dropped-while-downloading-the-update">

1040 下载更新时连接断开

1041</h3>

1042

1043在 `claude install`、`claude update` 或[自动更新程序](/zh-CN/setup#auto-updates)获取 Claude Code 二进制文件时，与下载服务器的连接关闭，重试未能恢复。当连接断开、传输停滞或下载的文件未通过校验和时，Claude Code 会重试下载，总共最多尝试三次。已完成的 HTTP 错误（例如 404）不会重试，因为服务器已经响应。{/* min-version: 2.1.202 */}在 v2.1.202 之前，单个断开的连接会立即导致下载失败，显示裸错误 `aborted`，而不是重试。

1044

1045```text theme={null}

1046The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

1047```

1048

1049括号中的文本命名失败的尝试和底层网络错误。`claude update` 在 stderr 上以 `Error: Failed to install native update` 开头的消息。

1050

1051保持连接但在 10 分钟内未完成的下载失败，显示 `Download timed out: exceeded the total deadline`。Claude Code 不会重试超时的下载，因为连接速度太慢而无法在截止时间内完成，在立即重试时也不会完成。以下步骤适用于两条消息。在 v2.1.205 之前，相同的 10 分钟截止时间被报告为 HTTP 客户端的通用 `timeout of 600000ms exceeded`。

1052

1053通常的原因是代理或网关在长传输完成前关闭它。Claude Code 二进制文件是一个大型下载，因此永远不会影响正常 API 流量的代理连接限制仍然可能中断它。

1054

1055**应该做什么：**

1056

1057* 再次运行 `claude update`。在网络状况良好的情况下，下载通常在下次运行时成功。对于超时消息，从更快或限制较少的网络再次运行它。

1058* 如果您的网络需要代理，请在运行安装程序或 `claude update` 之前设置 `HTTPS_PROXY`。请参阅[检查网络连接](/zh-CN/troubleshoot-install#check-network-connectivity)。

1059* 如果公司代理持续关闭传输，请要求您的网络团队允许从 `downloads.claude.ai` 进行完整下载。请参阅[网络访问要求](/zh-CN/network-config#network-access-requirements)。

1060* 从您的 shell 运行 `claude doctor` 以进行安装诊断

928 1061

929<h2 id="command-line-errors">1062<h2 id="command-line-errors">

930 命令行错误1063 命令行错误

931</h2>1064</h2>

932 1065

933这些错误来自 Claude Code 自己对 `claude` 命令行的验证。Claude Code 立即打印它们，然后再创建会话或发送任何 API 请求。1066这些错误来自 `claude` 命令行及其子命令。Claude Code 在运行您的提示或发送任何 API 请求之前会打印这些错误。

934 1067

935<h3 id="conflict-between-bg-and-print">1068<h3 id="conflict-between-bg-and-print">

936 Conflict between --bg and --print1069 \--bg 和 --print 之间的冲突

1070</h3>

1071

1072此消息需要 Claude Code v2.1.198 或更高版本。您在同一个 `claude` 调用中将 `--bg` 与 `-p` 或 `--print` 组合在一起。`--bg` 启动一个[后台会话](/zh-CN/agent-view#from-your-shell)，您稍后可以使用 `claude agents` 附加到该会话，而 `--print` 以[非交互方式](/zh-CN/headless)运行，永远不会启动 `claude agents` 附加到的交互式会话。在 v2.1.198 之前，此组合会静默创建一个永远无法附加的后台作业。

1073

1074```text theme={null}

1075--bg 和 --print 冲突：--print 永远不会启动 `claude agents` 附加到的交互式会话，因此该作业将无法附加。提示是位置参数 — 删除 --print：`claude --bg '<task>'`。

1076```

1077

1078**应该怎么做：**

1079

1080* 删除 `-p` 或 `--print`。`--bg` 将提示作为其位置参数，因此 `claude --bg "<task>"` 是完整命令。请参阅[从您的 shell 分派新代理](/zh-CN/agent-view#from-your-shell)。

1081* 要以非交互方式运行提示并打印结果而不是创建后台会话，请删除 `--bg` 并运行 `claude -p "<task>"`

1082

1083<h3 id="the-json-schema-value-is-not-a-valid-json-schema">

1084 \--json-schema 值不是有效的 JSON Schema

1085</h3>

1086

1087您在[非交互模式](/zh-CN/headless#get-structured-output)中传递给 [`--json-schema`](/zh-CN/cli-reference#cli-flags) 的架构未能通过 JSON Schema 编译，因此 `claude` 以代码 1 退出，而不是运行提示。在 v2.1.205 之前，无效的架构会产生无结构的输出且没有错误，任何使用 `format` 关键字的架构都被视为无效。

1088

1089```text theme={null}

1090Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values

1091```

1092

1093第二个冒号后面的文本是验证器的诊断，并命名了失败的关键字或位置。使用 `format` 关键字的架构（例如 `"format": "email"`）是有效的：Claude Code 接受 `format` 作为注释，不强制执行它。

1094

1095Claude Code 在架构编译之前运行两项检查：它拒绝不可解析的 JSON 值，并显示 `Error: --json-schema is not valid JSON`，以及不是对象的有效 JSON，并显示 `Error: --json-schema must be a JSON object`。

1096

1097**应该怎么做：**

1098

1099* 修复诊断命名的架构部分，然后重新运行命令

1100* 如果诊断是 `schema too large`，请减少架构的嵌套和 `$ref` 重用

1101* 请参阅[获取结构化输出](/zh-CN/headless#get-structured-output)以获取有效的架构和命令

1102

1103<h3 id="could-not-import-a-server-from-claude-desktop">

1104 无法从 Claude Desktop 导入服务器

1105</h3>

1106

1107Claude Code 无法添加您在 `claude mcp add-from-claude-desktop` 中选择的其中一个服务器。该命令仍会导入其他选定的服务器，并为每个无法添加的服务器打印一行。在 v2.1.205 之前，第一个失败的服务器会停止导入，所有选定的服务器都不会被添加。

1108

1109```text theme={null}

1110Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.

1111```

1112

1113服务器名称后面的文本是原因。最常见的是名称检查：Claude Desktop 允许服务器名称中的字符（例如空格和句号），而 `claude mcp` 限制为字母、数字、连字符和下划线。其他原因包括未通过验证的服务器配置以及被您组织的 [MCP 策略](/zh-CN/managed-mcp)阻止的服务器。

1114

1115**应该怎么做：**

1116

1117* 在 `claude_desktop_config.json` 中重命名服务器，仅使用字母、数字、连字符和下划线，然后再次运行 `claude mcp add-from-claude-desktop`

1118* 使用 `claude mcp add` 或 `claude mcp add-json` 在有效名称下直接添加该服务器。请参阅[从 Claude Desktop 导入 MCP 服务器](/zh-CN/mcp#import-mcp-servers-from-claude-desktop)。

1119

1120<h2 id="plugin-errors">

1121 Plugin 错误

1122</h2>

1123

1124这些错误来自 [plugin](/zh-CN/plugins) 和 [marketplace](/zh-CN/plugin-marketplaces) 配置。对于不会产生此页面上的消息之一的 plugin 问题，例如无法加载的 marketplace URL 或已安装但不显示的 plugin，请参阅 [Plugin troubleshooting](/zh-CN/discover-plugins#troubleshooting)。

1125

1126<h3 id="marketplace-is-registered-from-an-untrusted-source">

1127 Marketplace 从不受信任的源注册

937</h3>1128</h3>

938 1129

939{/* min-version: 2.1.198 */}}1130marketplace 以 [为官方 Anthropic marketplace 保留的名称](/zh-CN/plugin-marketplaces#marketplace-schema) 注册，但其注册源不是 `anthropics` GitHub 存储库。Claude Code 每次加载或刷新 marketplace 时都会重新检查保留的名称，因此 marketplace 和从中安装的 plugin 停止加载。在 v2.1.205 之前，仅在添加 marketplace 时检查名称，因此在其名称被保留之前注册的条目继续加载。

940此消息需要 Claude Code v2.1.198 或更高版本。您在同一 `claude` 调用中组合了 `--bg` 与 `-p` 或 `--print`。`--bg` 启动[后台会话](/zh-CN/agent-view#from-your-shell)，您稍后使用 `claude agents` 附加到，而 `--print` 运行[非交互式](/zh-CN/headless)并从不启动 `claude agents` 附加到的交互式会话。在 v2.1.198 之前，此组合默默创建了一个无法附加到的后台作业。

941 1131

942```text theme={null}1132```text theme={null}

1133Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.

943```1134```

944 1135

945**要做什么：**1136**应该做什么：**

1137

1138* 运行 `claude plugin marketplace remove <name>`，然后从官方 `github.com/anthropics` 存储库重新添加 marketplace

1139* 如果您发布了在名称被保留之前使用该名称的第三方 marketplace，请重命名它并要求用户从您的源重新添加它

1140* 查看 [Marketplace schema](/zh-CN/plugin-marketplaces#marketplace-schema) 下的保留名称列表

1141

1142<h2 id="configuration-warnings">

1143 配置警告

1144</h2>

1145

1146Claude Code 在启动时将这些消息写入 stderr，而不是在对话中显示错误。它们报告 Claude Code 读取但未应用的配置。

1147

1148<h3 id="workspace-has-not-been-trusted">

1149 工作区尚未被信任

1150</h3>

946 1151

947* 删除 `-p` 或 `--print`。`--bg` 将提示作为其位置参数，因此 `claude --bg "<task>"` 是完整的命令。请参阅[从您的 shell 分派新代理](/zh-CN/agent-view#from-your-shell)。1152Claude Code 在项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中找到了 `permissions.allow` 规则或 `permissions.additionalDirectories` 条目，但没有应用它们，因为[来自项目设置的允许规则需要工作区信任](/zh-CN/permissions#project-allow-rules-and-workspace-trust)。消息中的计数、设置名称和文件名会根据您的配置而变化。`deny` 和 `ask` 规则不受影响。

948* 要非交互式运行提示并打印结果而不是创建后台会话，请删除 `--bg` 并运行 `claude -p "<task>"`1153

1154```text theme={null}

1155Ignoring 2 permissions.allow entries from .claude/settings.local.json: this workspace has not been trusted. Run Claude Code interactively here once and accept the trust dialog, or set projects["/Users/you/project"].hasTrustDialogAccepted: true in /Users/you/.claude.json.

1156```

1157

1158**应该怎么做：**

1159

1160* 在目录中运行 `claude` 并接受信任对话框。{/* min-version: 2.1.200 */}即使父目录已被信任，对话框也会出现，列出被保留的规则，并让您可以拒绝并继续工作而不应用这些规则。在 v2.1.200 之前，在这种情况下不会出现对话框，因此无法在那里完成此步骤。

1161* 在[非交互模式](/zh-CN/headless)中使用 `-p` 不会显示对话框。使用消息打印的确切 `projects` 键在 `~/.claude.json` 中设置 `hasTrustDialogAccepted` 条目。

1162* {/* min-version: 2.1.200 */}如果消息命名 `.claude/settings.local.json` 并且您在 git 存储库外部或在主目录中启动了 Claude Code，请更新到 v2.1.200 或更高版本。版本 2.1.196 至 2.1.199 在这些工作区中将您自己的 `.claude/settings.local.json` 视为存储库提供的。请参阅[项目允许规则和工作区信任](/zh-CN/permissions#project-allow-rules-and-workspace-trust)。

949 1163

950<h2 id="responses-seem-lower-quality-than-usual">1164<h2 id="responses-seem-lower-quality-than-usual">

951 响应质量似乎低于平常1165 响应质量似乎低于预期

952</h2>1166</h2>

953 1167

954如果 Claude 的答案似乎不如您期望的那样有能力，但没有显示错误，原因通常是对话状态而不是模型本身。Claude Code 不会默默更改模型版本。它可以在三种特定情况下切换到后备模型：1168如果 Claude 的回答似乎不如你预期的那样有能力，但没有显示错误，原因通常是对话状态而不是模型本身。Claude Code 不会无声地更改模型版本。它只能在三种特定情况下切换到备用模型：

955 1169

956* 配置的 [`--fallback-model`](/zh-CN/cli-reference#cli-flags) 在可用性错误后接管该轮次，并在记录中显示通知1170* 配置的 [`--fallback-model`](/zh-CN/cli-reference#cli-flags) 在可用性错误后接管该轮次，并在记录中显示通知

957* Bedrock 或 Vertex AI 启动检查发现您的默认模型不可用1171* Amazon Bedrock 或 Google Cloud 的 Agent Platform 启动检查发现你的默认模型不可用

958* [自动模型后备](/zh-CN/model-config#automatic-model-fallback)在 Fable 5 上将会话移至默认 Opus 模型，并在记录中显示通知1172* [自动模型备用](/zh-CN/model-config#automatic-model-fallback)在 Fable 5 上将会话移至默认 Opus 模型，并在记录中显示通知

959 1173

960下面的模型选择检查会捕获第二和第三种情况；第一种情况显示为记录通知而不是 `/model` 更改。[模型配置](/zh-CN/model-config)解释了何时应用每个后备。1174下面的模型选择检查捕获第二和第三种情况；第一种情况显示为记录通知而不是 `/model` 更改。[模型配置](/zh-CN/model-config)解释了每种备用何时适用。

961 1175

962首先检查这些：1176首先检查这些：

963 1177

964* **模型选择**：运行 `/model` 以确认您在期望的模型上。之前的 `/model` 选择或 `ANTHROPIC_MODEL` 环境变量可能会让您使用比您打算的更小的模型。1178* **模型选择**：运行 `/model` 以确认你在预期的模型上。之前的 `/model` 选择或 `ANTHROPIC_MODEL` 环境变量可能使你在比预期更小的模型上。

965* **努力级别**：运行 `/effort` 以检查当前推理级别并为困难的调试或设计工作提高它。默认值因模型而异，因此在假设您低于最大值之前检查。有关每个模型的默认值和 `ultrathink` 快捷方式，请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level)。1179* **努力级别**：运行 `/effort` 以检查当前推理级别，并为困难的调试或设计工作提高它。默认值因模型而异，所以在假设你低于最大值之前请检查。有关每个模型的默认值和 `ultrathink` 快捷方式，请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level)。

966* **上下文压力**：运行 `/context` 以查看窗口有多满。如果接近容量，请在自然断点处运行 `/compact` 或运行 `/clear` 以重新开始。有关自动压缩如何影响早期轮次的信息，请参阅[探索上下文窗口](/zh-CN/context-window)。1180* **上下文压力**：运行 `/context` 以查看窗口有多满。如果接近容量，在自然断点处运行 `/compact` 或运行 `/clear` 以重新开始。有关自动压缩如何影响早期轮次的信息，请参阅[探索上下文窗口](/zh-CN/context-window)。

967* **过时的说明**：大型或过时的 `CLAUDE.md` 文件和 MCP 工具定义消耗上下文并可能引导响应。`/doctor` 标记超大内存文件和子代理定义；`/context` 显示 MCP 工具令牌使用。1181* **过时的指令**：大型或过时的 `CLAUDE.md` 文件和 MCP 工具定义会消耗上下文并可能引导响应。{/* min-version: 2.1.205 */}`/doctor` 检查会标记超大内存文件和未使用的扩展，`/context` 显示 MCP 工具令牌使用情况。在 v2.1.205 之前，`/doctor` 打开一个诊断屏幕，标记超大内存文件和子代理定义。

1182

1183当响应出错时，回退通常比用更正进行回复效果更好。按两次 Esc 或运行 `/rewind` 以回到错误轮次之前，然后用更具体的内容重新表述提示。在线程中更正会将错误的尝试保留在上下文中，这可能会将后来的答案锚定到它。请参阅[检查点](/zh-CN/checkpointing)。

968 1184

969当响应出错时，回退通常比用更正回复效果更好。按 Esc 两次或运行 `/rewind` 以回退到坏轮次之前，然后用更多细节重新表述提示。在线程中更正会将错误的尝试保留在上下文中，这可能会将后来的答案锚定到它。请参阅[检查点](/zh-CN/checkpointing)。1185如果在检查上述内容后质量仍然似乎不对，请运行 `/feedback` 并描述你期望的内容与你得到的内容。以这种方式提交的反馈包括对话记录，这是 Anthropic 诊断真实回归的最快方式。如果 `/feedback` 在你的环境中不可用，请参阅[报告错误](#report-an-error)。

970 1186

971如果在检查上述内容后质量仍然似乎有问题，请运行 `/feedback` 并描述您期望的内容与您得到的内容。以这种方式提交的反馈包括对话记录，这是 Anthropic 诊断真实回归的最快方式。如果您的环境中 `/feedback` 不可用，请参阅[报告错误](#report-an-error)。1187{/* min-version: 2.1.201 */}如果 Sonnet 5 拒绝请求并在 Claude Code v2.1.200 或更早版本上引用可疑的提示注入，请运行 `claude update` 以获取 v2.1.201 修复。

972 1188

973<h2 id="report-an-error">1189<h2 id="report-an-error">

974 报告错误1190 报告错误

975</h2>1191</h2>

976 1192

977对于本页不涵盖的组件的错误，请参阅相关指南：1193对于此页面未涵盖的组件错误，请参阅相关指南：

978 1194

979* MCP 服务器无法连接或身份验证：[MCP](/zh-CN/mcp)1195* MCP 服务器连接或身份验证失败：[MCP](/zh-CN/mcp)

980* Hook 脚本失败或阻止了工具：[调试 hooks](/zh-CN/hooks#debug-hooks)1196* Hook 脚本失败或阻止了工具：[调试 hooks](/zh-CN/hooks#debug-hooks)

981* 安装期间权限被拒绝或文件系统错误：[故障排除安装和登录](/zh-CN/troubleshoot-install)1197* 安装期间权限被拒绝或文件系统错误：[排查安装和登录问题](/zh-CN/troubleshoot-install)

982 1198

983如果此处未列出错误或建议的修复无法帮助：1199如果此处未列出错误或建议的修复方法无法帮助：

984 1200

985* 在 Claude Code 中运行 `/feedback` 以将记录和描述发送给 Anthropic。该命令还提供打开预填充的 GitHub 问题。在 Bedrock、Vertex AI、Foundry 和其他第三方提供商上，`/feedback` 会保存一个本地存档，您可以将其发送给您的 Anthropic 账户代表。1201* 在 Claude Code 中运行 `/feedback` 将记录和描述发送给 Anthropic。该命令还提供打开预填充的 GitHub issue 的选项。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和其他第三方提供商上，`/feedback` 保存本地存档，您可以将其发送给您的 Anthropic 账户代表。

986* 运行 `/doctor` 以检查本地配置问题1202* 从您的 shell 运行 `claude doctor` 以获取安装的只读诊断，或在 Claude Code 中运行 `/doctor` 检查以查找和修复设置问题

987* 检查 [status.claude.com](https://status.claude.com) 以了解活跃事件1203* 检查 [status.claude.com](https://status.claude.com) 以了解活跃事件

988* 在 GitHub 上搜索[现有问题](https://github.com/anthropics/claude-code/issues)1204* 在 GitHub 上搜索[现有 issue](https://github.com/anthropics/claude-code/issues)

fast-mode.md +2 −2

Details

38* 输入 `/fast` 并按 Tab 键打开或关闭38* 输入 `/fast` 并按 Tab 键打开或关闭

39* 在您的[用户设置文件](/zh-CN/settings)中设置 `"fastMode": true`39* 在您的[用户设置文件](/zh-CN/settings)中设置 `"fastMode": true`

40 40

41默认情况下，快速模式在会话之间保持。管理员可以配置快速模式在每个会话时重置。有关详细信息，请参阅[要求每个会话选择加入](#require-per-session-opt-in)。41默认情况下，在交互式会话中打开的快速模式在会话之间保持。{/* min-version: 2.1.205 */}在[非交互式模式](/zh-CN/headless)中，使用 `-p` 标志，`/fast` 仅在使用快速模式在其 [`--settings`](/zh-CN/cli-reference#cli-flags) 值中启动的会话中工作，例如 `claude -p --settings '{"fastMode": true}'`；切换然后仅适用于该会话，不会保存为您的默认值，在任何其他非交互式会话中，该命令报告快速模式不可用。管理员可以配置快速模式在每个会话时重置。有关详细信息，请参阅[要求每个会话选择加入](#require-per-session-opt-in)。

42 42

43为了获得最佳成本效率，在会话开始时启用快速模式，而不是在对话中途切换。有关详细信息，请参阅[了解成本权衡](#understand-the-cost-tradeoff)。43为了获得最佳成本效率，在会话开始时启用快速模式，而不是在对话中途切换。有关详细信息，请参阅[了解成本权衡](#understand-the-cost-tradeoff)。

44 44

103 103

104快速模式需要以下所有条件：104快速模式需要以下所有条件：

105 105

106* **仅限 Anthropic API 或订阅**：快速模式可通过 Anthropic 控制台 API 和使用使用额度的 Claude 订阅计划获得。它在 Amazon Bedrock、Google Vertex AI、Microsoft Azure Foundry 或 AWS 上的 Claude Platform 上不可用。106* **仅限 Anthropic API 或订阅**：快速模式可通过 Anthropic 控制台 API 和使用使用额度的 Claude 订阅计划获得。它在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 上不可用。

107* **启用使用额度**：您的账户必须启用使用额度，这允许在您的计划包含的使用量之外进行计费。对于个人账户，在您的[控制台计费设置](https://platform.claude.com/settings/organization/billing)中启用此功能。对于团队和企业，管理员必须为组织启用使用额度。107* **启用使用额度**：您的账户必须启用使用额度，这允许在您的计划包含的使用量之外进行计费。对于个人账户，在您的[控制台计费设置](https://platform.claude.com/settings/organization/billing)中启用此功能。对于团队和企业，管理员必须为组织启用使用额度。

108 108

109<Note>109<Note>

feature-availability.md +16 −16

Details

4 4

5# 功能可用性5# 功能可用性

6 6

~~7> 比较 Claude Code 功能在 Anthropic 订阅计划、Anthropic Console、Amazon Bedrock、AWS 上的 Claude Platform、Google Vertex AI 和 Microsoft Foundry 中的可用性。~~7> 比较 Claude Code 功能在 Anthropic 订阅计划、Anthropic Console、Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 和 Microsoft Foundry 中的可用性。

8 8

9Claude Code CLI 和所有本地运行的功能在每个提供商上的工作方式完全相同。有关每个提供商的设置说明，请参阅[企业部署概述](/zh-CN/third-party-integrations)。要直接跳到您的提供商上缺少的功能，请参阅[按提供商汇总](#summary-by-provider)选项卡。9Claude Code CLI 和所有本地运行的功能在每个提供商上的工作方式完全相同。有关每个提供商的设置说明，请参阅[企业部署概述](/zh-CN/third-party-integrations)。要直接跳到您的提供商上缺少的功能，请参阅[按提供商汇总](#summary-by-provider)选项卡。

10 10

18 18

19* **Claude 订阅**：您使用 claude.ai 账户登录 Pro、Max、Team 或 Enterprise 计划19* **Claude 订阅**：您使用 claude.ai 账户登录 Pro、Max、Team 或 Enterprise 计划

20* **Anthropic Console**：您使用 Anthropic API 密钥进行身份验证20* **Anthropic Console**：您使用 Anthropic API 密钥进行身份验证

21* **Amazon Bedrock**：您从 Bedrock 模型目录中使用 Claude 模型并设置 `CLAUDE_CODE_USE_BEDROCK`。[Mantle 端点](/zh-CN/amazon-bedrock#use-the-mantle-endpoint)（`CLAUDE_CODE_USE_MANTLE`）由此列涵盖21* **Amazon Bedrock**：您从 Amazon Bedrock 模型目录中使用 Claude 模型并设置 `CLAUDE_CODE_USE_BEDROCK`。[Mantle 端点](/zh-CN/amazon-bedrock#use-the-mantle-endpoint)（`CLAUDE_CODE_USE_MANTLE`）由此列涵盖

22* **Claude Platform on AWS**：您通过 AWS Marketplace 购买了 Claude，但调用 Anthropic API，并设置 `CLAUDE_CODE_USE_ANTHROPIC_AWS`22* **Claude Platform on AWS**：您通过 AWS Marketplace 购买了 Claude，但调用 Anthropic API，并设置 `CLAUDE_CODE_USE_ANTHROPIC_AWS`

~~23* **Google Vertex AI**：由 Google 运营；您设置 `CLAUDE_CODE_USE_VERTEX`~~23* **Google Cloud's Agent Platform**：由 Google 运营；您设置 `CLAUDE_CODE_USE_VERTEX`

24* **Microsoft Foundry**：由 Anthropic 在 Azure 上运营；您设置 `CLAUDE_CODE_USE_FOUNDRY`24* **Microsoft Foundry**：由 Anthropic 在 Azure 上运营；您设置 `CLAUDE_CODE_USE_FOUNDRY`

25 25

26<h3 id="features-available-on-every-provider">26<h3 id="features-available-on-every-provider">

53* [Artifacts](/zh-CN/artifacts)：Pro、Max、Team 和 Enterprise 计划53* [Artifacts](/zh-CN/artifacts)：Pro、Max、Team 和 Enterprise 计划

54* [Voice dictation](/zh-CN/voice-dictation)54* [Voice dictation](/zh-CN/voice-dictation)

55 55

56Desktop 是部分例外：Enterprise 部署可以通过[托管设置](https://support.claude.com/en/articles/12622667-enterprise-configuration)将 Desktop 路由到 Vertex AI 或网关提供商，[Cowork on 3P 研究预览](https://claude.com/docs/cowork/3p/overview)在 Bedrock、Vertex AI、Foundry 或自托管 LLM 网关上运行 Code 选项卡。有关这些功能的按计划可用性，请参阅[按订阅计划的可用性](#availability-by-subscription-plan)。56Desktop 是部分例外：Enterprise 部署可以通过[托管设置](https://support.claude.com/en/articles/12622667-enterprise-configuration)将 Desktop 路由到 Google Cloud's Agent Platform 或网关提供商，[Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview) 在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 或自托管 LLM 网关上运行 Code 选项卡。有关这些功能的按计划可用性，请参阅[按订阅计划的可用性](#availability-by-subscription-plan)。

57 57

58<h3 id="cli-capabilities-that-vary-by-provider">58<h3 id="cli-capabilities-that-vary-by-provider">

59 按提供商变化的 CLI 功能59 按提供商变化的 CLI 功能

69 <th>Anthropic Console</th>69 <th>Anthropic Console</th>

70 <th>Amazon Bedrock</th>70 <th>Amazon Bedrock</th>

71 <th>Claude Platform on AWS</th>71 <th>Claude Platform on AWS</th>

~~72 <th>Google Vertex AI</th>~~72 <th>Google Cloud's Agent Platform</th>

73 <th>Microsoft Foundry</th>73 <th>Microsoft Foundry</th>

74 </tr>74 </tr>

75 </thead>75 </thead>

161 <th>Anthropic Console</th>161 <th>Anthropic Console</th>

162 <th>Amazon Bedrock</th>162 <th>Amazon Bedrock</th>

163 <th>Claude Platform on AWS</th>163 <th>Claude Platform on AWS</th>

164 <th>Google Vertex AI</th>164 <th>Google Cloud's Agent Platform</th>

165 <th>Microsoft Foundry</th>165 <th>Microsoft Foundry</th>

166 </tr>166 </tr>

167 </thead>167 </thead>

199 </tbody>199 </tbody>

200</table>200</table>

201 201

202<span id="fn1" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>1</sup> 在 Vertex AI 上，web search 适用于 Claude 4 及更高版本的模型。<br />202<span id="fn1" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>1</sup> 在 Google Cloud's Agent Platform 上，web search 适用于 Claude 4 及更高版本的模型。<br />

203<span id="fn2" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>2</sup> 需要 `CLAUDE_CODE_ENABLE_AUTO_MODE`。请参阅 [Auto mode 配置](/zh-CN/auto-mode-config)。<br />203<span id="fn2" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>2</sup> 需要 `CLAUDE_CODE_ENABLE_AUTO_MODE`。请参阅 [Auto mode 配置](/zh-CN/auto-mode-config)。<br />

204<span id="fn3" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>3</sup> 显式间隔（如 `/loop every 2 hours`）在每个提供商上都有效。在 Bedrock、Vertex AI 和 Foundry 上，`/loop` 无法选择自己的间隔或提供默认维护提示，因此没有间隔的提示每 10 分钟运行一次，没有参数的 `/loop` 显示使用消息。请参阅[计划任务](/zh-CN/scheduled-tasks)。<br />204<span id="fn3" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>3</sup> 显式间隔（如 `/loop every 2 hours`）在每个提供商上都有效。在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，`/loop` 无法选择自己的间隔或提供默认维护提示，因此没有间隔的提示每 10 分钟运行一次，没有参数的 `/loop` 显示使用消息。请参阅[计划任务](/zh-CN/scheduled-tasks)。<br />

205<span id="fn4" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>4</sup> 受您与云提供商的协议约束。<br />205<span id="fn4" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>4</sup> 受您与云提供商的协议约束。<br />

206<span id="fn5" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>5</sup> 仅限仪表板和 API。[贡献指标](/zh-CN/analytics#enable-contribution-metrics)需要 claude.ai Team 或 Enterprise 组织。206<span id="fn5" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>5</sup> 仅限仪表板和 API。[贡献指标](/zh-CN/analytics#enable-contribution-metrics)需要 claude.ai Team 或 Enterprise 组织。

207 207

213 按提供商汇总213 按提供商汇总

214</h3>214</h3>

215 215

216每个选项卡列出了该提供商上不可用或部分支持的内容，以及存在替代方案的地方。未列出的所有内容的工作方式与 Claude 订阅上相同。在 Bedrock、Vertex AI、Foundry 和 Claude Platform on AWS 上，错误报告和遥测到 Anthropic 默认处于关闭状态。请参阅[按 API 提供商的默认行为](/zh-CN/data-usage#default-behaviors-by-api-provider)了解哪些流量仍然到达 Anthropic 以及如何选择退出。216每个选项卡列出了该提供商上不可用或部分支持的内容，以及存在替代方案的地方。未列出的所有内容的工作方式与 Claude 订阅上相同。在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和 Claude Platform on AWS 上，错误报告和遥测到 Anthropic 默认处于关闭状态。请参阅[按 API 提供商的默认行为](/zh-CN/data-usage#default-behaviors-by-api-provider)了解哪些流量仍然到达 Anthropic 以及如何选择退出。

217 217

218<Tabs>218<Tabs>

219 <Tab title="Amazon Bedrock">219 <Tab title="Amazon Bedrock">

221 221

222 **部分支持：**222 **部分支持：**

223 223

224 * [Desktop](/zh-CN/desktop)：仅通过 [Cowork on 3P 研究预览](https://claude.com/docs/cowork/3p/overview)224 * [Desktop](/zh-CN/desktop)：仅通过 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

225 * [Auto mode](/zh-CN/auto-mode-config)：设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`225 * [Auto mode](/zh-CN/auto-mode-config)：设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`

226 * [`/loop`](/zh-CN/scheduled-tasks)：仅显式间隔226 * [`/loop`](/zh-CN/scheduled-tasks)：仅显式间隔

227 * [Zero Data Retention](/zh-CN/zero-data-retention)：受您的 AWS 协议约束227 * [Zero Data Retention](/zh-CN/zero-data-retention)：受您的 AWS 协议约束

237 **替代方案：** 对于调度，使用 [`/loop`](/zh-CN/scheduled-tasks) 而不是 `/schedule`。对于云会话，使用 [GitHub Actions](/zh-CN/github-actions) 或 [GitLab CI/CD](/zh-CN/gitlab-ci-cd)。237 **替代方案：** 对于调度，使用 [`/loop`](/zh-CN/scheduled-tasks) 而不是 `/schedule`。对于云会话，使用 [GitHub Actions](/zh-CN/github-actions) 或 [GitLab CI/CD](/zh-CN/gitlab-ci-cd)。

238 </Tab>238 </Tab>

239 239

240 <Tab title="Google Vertex AI">240 <Tab title="Google Cloud's Agent Platform">

241 **不可用：** 所有[需要 Claude 订阅的功能](#features-that-require-a-claude-subscription)，加上 [fast mode](/zh-CN/fast-mode)、[Advisor](/zh-CN/advisor)、[Channels](/zh-CN/channels)、[analytics dashboard](/zh-CN/analytics) 和 [server-managed settings](/zh-CN/server-managed-settings)。241 **不可用：** 所有[需要 Claude 订阅的功能](#features-that-require-a-claude-subscription)，加上 [fast mode](/zh-CN/fast-mode)、[Advisor](/zh-CN/advisor)、[Channels](/zh-CN/channels)、[analytics dashboard](/zh-CN/analytics) 和 [server-managed settings](/zh-CN/server-managed-settings)。

242 242

243 **部分支持：**243 **部分支持：**

244 244

245 * [Desktop](/zh-CN/desktop)：通过[托管设置](https://support.claude.com/en/articles/12622667-enterprise-configuration)或 [Cowork on 3P 研究预览](https://claude.com/docs/cowork/3p/overview)245 * [Desktop](/zh-CN/desktop)：通过[托管设置](https://support.claude.com/en/articles/12622667-enterprise-configuration)或 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

246 * [Web search](/zh-CN/tools-reference#websearch-tool-behavior)：Claude 4 及更高版本的模型246 * [Web search](/zh-CN/tools-reference#websearch-tool-behavior)：Claude 4 及更高版本的模型

247 * [Auto mode](/zh-CN/auto-mode-config)：设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`247 * [Auto mode](/zh-CN/auto-mode-config)：设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`

248 * [`/loop`](/zh-CN/scheduled-tasks)：仅显式间隔248 * [`/loop`](/zh-CN/scheduled-tasks)：仅显式间隔

256 256

257 **部分支持：**257 **部分支持：**

258 258

259 * [Desktop](/zh-CN/desktop)：仅通过 [Cowork on 3P 研究预览](https://claude.com/docs/cowork/3p/overview)259 * [Desktop](/zh-CN/desktop)：仅通过 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

260 * [Auto mode](/zh-CN/auto-mode-config)：设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`260 * [Auto mode](/zh-CN/auto-mode-config)：设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`

261 * [`/loop`](/zh-CN/scheduled-tasks)：仅显式间隔261 * [`/loop`](/zh-CN/scheduled-tasks)：仅显式间隔

262 * [Zero Data Retention](/zh-CN/zero-data-retention)：受您的 Azure 协议约束262 * [Zero Data Retention](/zh-CN/zero-data-retention)：受您的 Azure 协议约束

275 按订阅计划的可用性275 按订阅计划的可用性

276</h2>276</h2>

277 277

278如果您通过 Bedrock、Vertex AI、Foundry 或 Anthropic Console API 密钥进行身份验证，本部分不适用于您。当您使用 claude.ai 账户登录时，您的计划决定了以下哪些功能可用。278如果您通过 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Anthropic Console API 密钥进行身份验证，本部分不适用于您。当您使用 claude.ai 账户登录时，您的计划决定了以下哪些功能可用。

279 279

280| 功能 | Pro | Max | Team | Enterprise |280| 功能 | Pro | Max | Team | Enterprise |

281| :-------------------------------------------------------------------------------------- | :-- | :-- | :------------ | :-------------------------------- |281| :-------------------------------------------------------------------------------------- | :-- | :-- | :------------ | :-------------------------------- |

303 模型可用性303 模型可用性

304</h2>304</h2>

305 305

306有关每个提供商和地区可用的 Claude 模型和上下文窗口大小，请参阅[模型配置](/zh-CN/model-config)和[模型概述](https://platform.claude.com/docs/en/about-claude/models/overview)。Vision、PDF 输入和扩展思考是模型功能而不是 Claude Code 功能，在提供该模型的每个提供商上都有效。[Prompt caching](/zh-CN/prompt-caching) 在大多数提供商上的工作方式相同；在 Bedrock 上，支持因模型而异。306有关每个提供商和地区可用的 Claude 模型和上下文窗口大小，请参阅[模型配置](/zh-CN/model-config)和[模型概述](https://platform.claude.com/docs/en/about-claude/models/overview)。Vision、PDF 输入和扩展思考是模型功能而不是 Claude Code 功能，在提供该模型的每个提供商上都有效。[Prompt caching](/zh-CN/prompt-caching) 在大多数提供商上的工作方式相同；在 Amazon Bedrock 上，支持因模型而异。

307 307

308<h2 id="related-resources">308<h2 id="related-resources">

309 相关资源309 相关资源

310</h2>310</h2>

311 311

312* [企业部署概述](/zh-CN/third-party-integrations)：比较提供商之间的身份验证、计费和地区312* [企业部署概述](/zh-CN/third-party-integrations)：比较提供商之间的身份验证、计费和地区

313* 提供商设置指南：[Amazon Bedrock](/zh-CN/amazon-bedrock)、[Claude Platform on AWS](/zh-CN/claude-platform-on-aws)、[Google Vertex AI](/zh-CN/google-vertex-ai)、[Microsoft Foundry](/zh-CN/microsoft-foundry)313* 提供商设置指南：[Amazon Bedrock](/zh-CN/amazon-bedrock)、[Claude Platform on AWS](/zh-CN/claude-platform-on-aws)、[Google Cloud's Agent Platform](/zh-CN/google-vertex-ai)、[Microsoft Foundry](/zh-CN/microsoft-foundry)

314* [平台和集成](/zh-CN/platforms)：Claude Code 运行的地方，包括 CLI、Desktop、IDE 扩展、网络、移动和 CI/CD314* [平台和集成](/zh-CN/platforms)：Claude Code 运行的地方，包括 CLI、Desktop、IDE 扩展、网络、移动和 CI/CD

fullscreen.md +3 −1

Details

170 170

171全屏渲染与 iTerm2 的 tmux 集成模式不兼容，这是您使用 `tmux -CC` 进入的模式。在集成模式中，iTerm2 将每个 tmux 窗格渲染为原生分割，而不是让 tmux 绘制到终端。备用屏幕缓冲区和鼠标跟踪在那里无法正确工作：鼠标滚轮不起作用，双击可能会损坏终端状态。不要在 `tmux -CC` 会话中启用全屏渲染。常规 tmux 在 iTerm2 内，没有 `-CC`，工作正常。171全屏渲染与 iTerm2 的 tmux 集成模式不兼容，这是您使用 `tmux -CC` 进入的模式。在集成模式中，iTerm2 将每个 tmux 窗格渲染为原生分割，而不是让 tmux 绘制到终端。备用屏幕缓冲区和鼠标跟踪在那里无法正确工作：鼠标滚轮不起作用，双击可能会损坏终端状态。不要在 `tmux -CC` 会话中启用全屏渲染。常规 tmux 在 iTerm2 内，没有 `-CC`，工作正常。

172 172

173tmux 不支持同步输出，因此在重绘期间您可能会看到比直接在终端中运行 Claude Code 时更多的闪烁。如果闪烁很明显，特别是在 SSH 上，请在 tmux 外的自己的终端标签页中运行 Claude Code。173并非每个 tmux 版本都应用来自应用程序的同步输出，因此在 tmux 下重绘期间您可能会看到比直接在终端中运行 Claude Code 时更多的闪烁。如果闪烁很明显，特别是在 SSH 上，请升级到最新的 tmux 或在 tmux 外的自己的终端标签页中运行 Claude Code。使用 `tmux -V` 检查您的 tmux 版本。

174

175{/* min-version: 2.1.200 */}Claude Code 在从 `TERM_PROGRAM_VERSION` 变量检测到 tmux 3.4 或更高版本时自动打开同步输出，当无法确定版本时回退到直接查询终端以获取同步输出支持。重绘是否实际上变成原子操作取决于您的 tmux 版本是否遵守同步输出；如果您在 tmux 3.4 或更高版本下仍然看到闪烁，请升级到最新的 tmux。此检测需要 Claude Code v2.1.200 或更高版本。

174 176

175<h2 id="keep-native-text-selection">177<h2 id="keep-native-text-selection">

176 保持原生文本选择178 保持原生文本选择

github-actions.md +25 −25

Details

51<Note>51<Note>

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

53 * GitHub 应用将请求对内容、Issue 和拉取请求的读写权限53 * GitHub 应用将请求对内容、Issue 和拉取请求的读写权限

54 * 此快速启动方法仅适用于直接 Claude API 用户。如果您使用 Amazon Bedrock 或 Google Vertex AI，请参阅 [使用 Amazon Bedrock 和 Google Vertex AI](#using-with-amazon-bedrock-%26-google-vertex-ai) 部分。54 * 此快速启动方法仅适用于直接 Claude API 用户。如果您使用 Amazon Bedrock 或 Google Cloud 的 Agent Platform，请参阅 [使用 Amazon Bedrock 和 Google Cloud](#using-with-amazon-bedrock-and-google-cloud) 部分。

55</Note>55</Note>

56 56

57<h2 id="manual-setup">57<h2 id="manual-setup">

320 当响应 issue 或 PR 评论时，Claude 会自动响应 @claude 提及。对于其他事件，使用 `prompt` 参数提供说明。320 当响应 issue 或 PR 评论时，Claude 会自动响应 @claude 提及。对于其他事件，使用 `prompt` 参数提供说明。

321</Tip>321</Tip>

322 322

323<h2 id="using-with-amazon-bedrock--google-vertex-ai">323<h2 id="using-with-amazon-bedrock-and-google-cloud">

324 使用 Amazon Bedrock 和 Google Vertex AI324 使用 Amazon Bedrock 和 Google Cloud

325</h2>325</h2>

326 326

327对于企业环境，您可以将 Claude Code GitHub Actions 与您自己的云基础设施一起使用。这种方法让您可以控制数据驻留和计费，同时保持相同的功能。327对于企业环境，您可以将 Claude Code GitHub Actions 与您自己的云基础设施一起使用。这种方法让您可以控制数据驻留和计费，同时保持相同的功能。

332 332

333在使用云提供商设置 Claude Code GitHub Actions 之前，您需要：333在使用云提供商设置 Claude Code GitHub Actions 之前，您需要：

334 334

335<h4 id="for-google-cloud-vertex-ai">335<h4 id="for-google-cloud’s-agent-platform">

336 对于 Google Cloud Vertex AI：336 对于 Google Cloud 的 Agent Platform：

337</h4>337</h4>

338 338

3391. 启用了 Vertex AI 的 Google Cloud 项目3391. 启用了 Google Cloud 的 Agent Platform 的 Google Cloud 项目

3402. 为 GitHub Actions 配置的工作负载身份联合3402. 为 GitHub Actions 配置的工作负载身份联合

3413. 具有所需权限的服务账户3413. 具有所需权限的服务账户

3424. GitHub 应用（推荐）或使用默认 GITHUB\_TOKEN3424. GitHub 应用（推荐）或使用默认 GITHUB\_TOKEN

347 347

3481. 启用了 Amazon Bedrock 的 AWS 账户3481. 启用了 Amazon Bedrock 的 AWS 账户

3492. 在 AWS 中配置的 GitHub OIDC 身份提供商3492. 在 AWS 中配置的 GitHub OIDC 身份提供商

3503. 具有 Bedrock 权限的 IAM 角色3503. 具有 Amazon Bedrock 权限的 IAM 角色

3514. GitHub 应用（推荐）或使用默认 GITHUB\_TOKEN3514. GitHub 应用（推荐）或使用默认 GITHUB\_TOKEN

352 352

353<Steps>353<Steps>

354 <Step title="创建自定义 GitHub 应用（推荐用于第三方提供商）">354 <Step title="创建自定义 GitHub 应用（推荐用于第三方提供商）">

355 为了在使用 Vertex AI 或 Bedrock 等第三方提供商时获得最佳控制和安全性，我们建议创建您自己的 GitHub 应用：355 为了在使用 Google Cloud 的 Agent Platform 或 Amazon Bedrock 等第三方提供商时获得最佳控制和安全性，我们建议创建您自己的 GitHub 应用：

356 356

357 1. 转到 [https://github.com/settings/apps/new](https://github.com/settings/apps/new)357 1. 转到 [https://github.com/settings/apps/new](https://github.com/settings/apps/new)

358 2. 填写基本信息：358 2. 填写基本信息：

428 有关详细的 OIDC 设置说明，请参阅 [AWS 文档](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)。428 有关详细的 OIDC 设置说明，请参阅 [AWS 文档](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)。

429 </Accordion>429 </Accordion>

430 430

431 <Accordion title="Google Vertex AI">431 <Accordion title="Google Cloud 的 Agent Platform">

432 **配置 Google Cloud 以允许 GitHub Actions 安全地进行身份验证，而无需存储凭证。**432 **配置 Google Cloud 以允许 GitHub Actions 安全地进行身份验证，而无需存储凭证。**

433 433

434 > **安全说明**：使用特定于仓库的配置并仅授予最少所需的权限。434 > **安全说明**：使用特定于仓库的配置并仅授予最少所需的权限。

438 1. **在您的 Google Cloud 项目中启用 API**：438 1. **在您的 Google Cloud 项目中启用 API**：

439 * IAM Credentials API439 * IAM Credentials API

440 * Security Token Service (STS) API440 * Security Token Service (STS) API

441 * Vertex AI API441 * Google Cloud 的 Agent Platform API

442 442

443 2. **创建工作负载身份联合资源**：443 2. **创建工作负载身份联合资源**：

444 * 创建工作负载身份池444 * 创建工作负载身份池

483 * `APP_ID`：您的 GitHub 应用的 ID483 * `APP_ID`：您的 GitHub 应用的 ID

484 * `APP_PRIVATE_KEY`：私钥 (.pem) 内容484 * `APP_PRIVATE_KEY`：私钥 (.pem) 内容

485 485

486 #### 对于 Google Cloud Vertex AI486 #### 对于 Google Cloud 的 Agent Platform

487 487

488 1. **对于 GCP 身份验证**：488 1. **对于 GCP 身份验证**：

489 * `GCP_WORKLOAD_IDENTITY_PROVIDER`489 * `GCP_WORKLOAD_IDENTITY_PROVIDER`

504 </Step>504 </Step>

505 505

506 <Step title="创建工作流文件">506 <Step title="创建工作流文件">

507 创建与您的云提供商集成的 GitHub Actions 工作流文件。下面的示例显示了 Amazon Bedrock 和 Google Vertex AI 的完整配置：507 创建与您的云提供商集成的 GitHub Actions 工作流文件。下面的示例显示了 Amazon Bedrock 和 Google Cloud 的 Agent Platform 的完整配置：

508 508

509 <AccordionGroup>509 <AccordionGroup>

510 <Accordion title="Amazon Bedrock 工作流">510 <Accordion title="Amazon Bedrock 工作流">

512 512

513 * 启用了 Amazon Bedrock 访问权限，具有 Claude 模型权限513 * 启用了 Amazon Bedrock 访问权限，具有 Claude 模型权限

514 * GitHub 在 AWS 中配置为 OIDC 身份提供商514 * GitHub 在 AWS 中配置为 OIDC 身份提供商

515 * 具有 Bedrock 权限的 IAM 角色，信任 GitHub Actions515 * 具有 Amazon Bedrock 权限的 IAM 角色，信任 GitHub Actions

516 516

517 **所需的 GitHub 密钥：**517 **所需的 GitHub 密钥：**

518 518

519 | 密钥名称 | 描述 |519 | 密钥名称 | 描述 |

520 | -------------------- | ----------------------- |520 | -------------------- | ------------------------------ |

524 524

573 ```573 ```

574 574

575 <Tip>575 <Tip>

576 Bedrock 的模型 ID 格式包括区域前缀（例如，`us.anthropic.claude-sonnet-4-6`）。576 Amazon Bedrock 的模型 ID 格式包括区域前缀（例如，`us.anthropic.claude-sonnet-4-6`）。

577 </Tip>577 </Tip>

578 </Accordion>578 </Accordion>

579 579

580 <Accordion title="Google Vertex AI 工作流">580 <Accordion title="Google Cloud 的 Agent Platform 工作流">

581 **前置条件：**581 **前置条件：**

582 582

583 * 在您的 GCP 项目中启用了 Vertex AI API583 * 在您的 GCP 项目中启用了 Google Cloud 的 Agent Platform API

584 * 为 GitHub 配置了工作负载身份联合584 * 为 GitHub 配置了工作负载身份联合

585 * 具有 Vertex AI 权限的服务账户585 * 具有 Google Cloud 的 Agent Platform 权限的服务账户

586 586

587 **所需的 GitHub 密钥：**587 **所需的 GitHub 密钥：**

588 588

589 | 密钥名称 | 描述 |589 | 密钥名称 | 描述 |

590 | -------------------------------- | -------------------------- |590 | -------------------------------- | ---------------------------------------------- |

595 595

675 身份验证错误675 身份验证错误

676</h3>676</h3>

677 677

678确认 API 密钥有效且具有足够的权限。对于 Bedrock/Vertex，检查凭证配置并确保密钥在工作流中正确命名。678确认 API 密钥有效且具有足够的权限。对于 Amazon Bedrock 或 Google Cloud 的 Agent Platform，检查凭证配置并确保密钥在工作流中正确命名。

679 679

680<h2 id="advanced-configuration">680<h2 id="advanced-configuration">

681 高级配置681 高级配置

688Claude Code Action v1 使用简化的配置：688Claude Code Action v1 使用简化的配置：

689 689

690| 参数 | 描述 | 必需 |690| 参数 | 描述 | 必需 |

691| --------------------- | ------------------------------------------ | ----- |691| --------------------- | ----------------------------------------------- | ----- |

692| `prompt` | Claude 的说明（纯文本或 [skill](/zh-CN/skills) 名称） | 否\* |692| `prompt` | Claude 的说明（纯文本或 [skill](/zh-CN/skills) 名称） | 否\* |

693| `claude_args` | 传递给 Claude Code 的 CLI 参数 | 否 |693| `claude_args` | 传递给 Claude Code 的 CLI 参数 | 否 |

694| `plugin_marketplaces` | 插件市场 Git URL 的换行符分隔列表 | 否 |694| `plugin_marketplaces` | 插件市场 Git URL 的换行符分隔列表 | 否 |

697| `github_token` | 用于 API 访问的 GitHub 令牌 | 否 |697| `github_token` | 用于 API 访问的 GitHub 令牌 | 否 |

698| `trigger_phrase` | 自定义触发短语（默认："@claude"） | 否 |698| `trigger_phrase` | 自定义触发短语（默认："@claude"） | 否 |

699| `use_bedrock` | 使用 Amazon Bedrock 而不是 Claude API | 否 |699| `use_bedrock` | 使用 Amazon Bedrock 而不是 Claude API | 否 |

700| `use_vertex` | 使用 Google Vertex AI 而不是 Claude API | 否 |700| `use_vertex` | 使用 Google Cloud 的 Agent Platform 而不是 Claude API | 否 |

701 701

702\*提示是可选的 - 当对 issue/PR 评论省略时，Claude 响应触发短语\702\*提示是可选的 - 当对 issue/PR 评论省略时，Claude 响应触发短语\

703\*\*对于直接 Claude API 是必需的，对于 Bedrock/Vertex 不是必需的703\*\*对于直接 Claude API 是必需的，对于 Amazon Bedrock 或 Google Cloud 的 Agent Platform 不是必需的

704 704

705<h4 id="pass-cli-arguments">705<h4 id="pass-cli-arguments">

706 传递 CLI 参数706 传递 CLI 参数

github-enterprise-server.md +61 −26

Details

10 GitHub Enterprise Server 支持适用于 Team 和 Enterprise 计划。10 GitHub Enterprise Server 支持适用于 Team 和 Enterprise 计划。

11</Note>11</Note>

12 12

13GitHub Enterprise Server (GHES) 支持让您的组织使用 Claude Code 处理托管在自管理 GitHub 实例上的存储库，而不是 github.com。一旦所有者连接您的 GHES 实例，开发人员可以运行网络会话、获得自动化代码审查，并从内部市场安装插件，无需任何按存储库的配置。13GitHub Enterprise Server (GHES) 支持让您的组织使用 Claude Code 处理托管在自管理 GitHub 实例上的存储库，而不是 github.com。一旦所有者连接您的 GHES 实例，开发人员可以运行网络会话和获得自动化代码审查，无需任何按存储库的配置。您实例上托管的插件市场也受支持；凭证要求因表面而异，如 [GHES 上的插件市场](#plugin-marketplaces-on-ghes) 中所述。

14 14

15对于 github.com 上的存储库，请参阅 [网络上的 Claude Code](/zh-CN/claude-code-on-the-web) 和 [代码审查](/zh-CN/code-review)。要在您自己的 CI 基础设施中运行 Claude，请参阅 [GitHub Actions](/zh-CN/github-actions)。15对于 github.com 上的存储库，请参阅 [网络上的 Claude Code](/zh-CN/claude-code-on-the-web) 和 [代码审查](/zh-CN/code-review)。要在您自己的 CI 基础设施中运行 Claude，请参阅 [GitHub Actions](/zh-CN/github-actions)。

16 16

21下表显示了哪些 Claude Code 功能支持 GHES 以及与 github.com 行为的任何差异。21下表显示了哪些 Claude Code 功能支持 GHES 以及与 github.com 行为的任何差异。

22 22

23| 功能 | GHES 支持 | 备注 |23| 功能 | GHES 支持 | 备注 |

~~24| :---------------- | :------ | :--------------------------------------------------------------------------------------- |~~24| :---------------- | :------ | :-------------------------------------------------------------------------------------- |

~~25| 网络上的 Claude Code | ✅ 支持 | 所有者连接 GHES 实例一次；开发人员像往常一样使用 `claude --remote` 或 [claude.ai/code](https://claude.ai/code) |~~25| 网络上的 Claude Code | ✅ 支持 | 所有者连接 GHES 实例一次；开发人员像往常一样使用 `claude --cloud` 或 [claude.ai/code](https://claude.ai/code) |

26| 代码审查 | ✅ 支持 | 与 github.com 相同的自动化 PR 审查 |26| 代码审查 | ✅ 支持 | 与 github.com 相同的自动化 PR 审查 |

27| Claude Security | ✅ 支持 | 在 [claude.ai/security](https://claude.ai/security) 为 Enterprise 计划提供公开测试版 |27| Claude Security | ✅ 支持 | 在 [claude.ai/security](https://claude.ai/security) 为 Enterprise 计划提供公开测试版 |

28| Teleport 会话 | ✅ 支持 | 使用 `--teleport` 在网络和终端之间移动会话 |28| Teleport 会话 | ✅ 支持 | 使用 `--teleport` 在网络和终端之间移动会话 |

~~29| 插件市场 | ✅ 支持 | 使用完整的 git URL 而不是 `owner/repo` 简写 |~~29| 插件市场 | ✅ 支持 | 凭证要求因表面而异。请参阅 [GHES 上的插件市场](#plugin-marketplaces-on-ghes) |

30| 贡献指标 | ✅ 支持 | 通过 webhook 传递到 [分析仪表板](/zh-CN/analytics) |30| 贡献指标 | ✅ 支持 | 通过 webhook 传递到 [分析仪表板](/zh-CN/analytics) |

31| GitHub Actions | ✅ 支持 | 需要手动工作流设置；`/install-github-app` 仅适用于 github.com |31| GitHub Actions | ✅ 支持 | 需要手动工作流设置；`/install-github-app` 仅适用于 github.com |

32| GitHub MCP server | ❌ 不支持 | GitHub MCP server 不适用于 GHES 实例 |32| GitHub MCP server | ❌ 不支持 | GitHub MCP server 不适用于 GHES 实例 |

107然后启动网络会话。Claude 从您的 git 远程检测 GHES 主机，并通过您组织的配置实例路由会话：107然后启动网络会话。Claude 从您的 git 远程检测 GHES 主机，并通过您组织的配置实例路由会话：

108 108

109```bash theme={null}109```bash theme={null}

110claude --remote "Add retry logic to the payment webhook handler"110claude --cloud "Add retry logic to the payment webhook handler"

111```111```

112 112

113会话在 Anthropic 基础设施上运行，从 GHES 克隆您的存储库，并将更改推送回分支。使用 `/tasks` 或在 [claude.ai/code](https://claude.ai/code) 监控进度。有关完整的远程会话工作流（包括差异审查、自动修复和例程），请参阅 [网络上的 Claude Code](/zh-CN/claude-code-on-the-web)。113会话在 Anthropic 基础设施上运行，从 GHES 克隆您的存储库，并将更改推送回分支。使用 `/tasks` 或在 [claude.ai/code](https://claude.ai/code) 监控进度。有关完整的远程会话工作流（包括差异审查、自动修复和例程），请参阅 [网络上的 Claude Code](/zh-CN/claude-code-on-the-web)。

122 GHES 上的插件市场122 GHES 上的插件市场

123</h2>123</h2>

124 124

125在您的 GHES 实例上托管插件市场，以在您的组织中分发内部工具。市场结构与 github.com 托管的市场相同；唯一的区别是您如何引用它们。125在您的 GHES 实例上托管插件市场，以在您的组织中分发内部工具。市场结构与 github.com 托管的市场相同，但安装方式因您添加市场的位置而异，并且凭证在不同的界面上有所不同：

126

127| 界面 | 安装方式 | 每个用户需要什么 |

128| :----------------------------- | :----------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- |

129| Claude Code CLI 和桌面应用 | Claude Code 使用机器现有的 git 凭证克隆市场存储库 | 从其机器对您的 GHES 主机的 Git 访问权限 |

130| 托管设置（`extraKnownMarketplaces`） | Claude Code 注册条目并使用机器现有的 git 凭证克隆存储库 | 从其机器对您的 GHES 主机的 Git 访问权限 |

131| claude.ai 组织插件设置 | 所有者选择 GHES 实例作为源；Anthropic 的后端使用来自 [admin setup](#admin-setup) 的 GitHub App 获取并同步存储库 | 添加后每个用户无需任何操作。添加它的所有者需要连接自己的 GitHub Enterprise 账户作为访问检查，并且 GitHub App 必须安装在市场存储库上 |

132| claude.ai 用户设置 | Anthropic 的后端使用提交用户的 GitHub Enterprise 连接获取存储库 | 连接到 Claude 的自己的 GitHub Enterprise 账户 |

133| Claude Code 网页版 | 云会话在会话沙箱内克隆市场。沙箱只有在会话的存储库位于同一实例上时才能访问您的 GHES 实例，其 git 凭证的范围限于会话的存储库 | 对于 GHES 托管的市场不可靠：与会话存储库不同的主机无法访问，即使是同一实例的安装也可能失败。改用 CLI、托管设置或 claude.ai |

134

135<Warning>

136 当从用户设置添加市场时，claude.ai 上的 GitHub Enterprise 连接是按用户的。[admin setup](#admin-setup) 将您的 GHES 实例连接到您的组织，但它不连接单个用户账户：每个从自己的设置添加 GHES 市场的用户必须首先连接自己的 GitHub Enterprise 账户，一个用户的连接（包括所有者的）不会覆盖任何其他人。由所有者在组织插件设置中添加的市场不会对用户施加此要求，因为持续的获取使用组织的 GitHub App。添加市场的所有者仍然需要在添加时连接自己的 GitHub Enterprise 账户。

137</Warning>

126 138

127<h3 id="add-a-ghes-marketplace">139<h3 id="add-a-ghes-marketplace">

128 添加 GHES 市场140 添加 GHES 市场

129</h3>141</h3>

130 142

131`owner/repo` 简写始终解析为 github.com。对于 GHES 托管的市场，使用完整的 git URL：143`owner/repo` 简写始终解析为 github.com。对于 GHES 托管的市场，使用完整的 git URL。建议使用 HTTPS URL：

132 144

133```bash theme={null}145```bash theme={null}

134/plugin marketplace add git@github.example.com:platform/claude-plugins.git146/plugin marketplace add https://github.example.com/platform/claude-plugins.git

135```147```

136 148

137HTTPS URL 也可以工作：149如果机器已经信任您的 GHES 主机，SSH URL 也可以工作：

138 150

139```bash theme={null}151```bash theme={null}

140/plugin marketplace add https://github.example.com/platform/claude-plugins.git152/plugin marketplace add git@github.example.com:platform/claude-plugins.git

141```153```

142 154

155Claude Code 以非交互方式运行 git，并拒绝连接到不在机器 `known_hosts` 文件中的主机的 SSH 连接。带有 git 凭证助手的 HTTPS URL 避免了 `known_hosts` 要求。

156

143有关构建市场的完整指南，请参阅 [创建和分发插件市场](/zh-CN/plugin-marketplaces)。157有关构建市场的完整指南，请参阅 [创建和分发插件市场](/zh-CN/plugin-marketplaces)。

144 158

159<h3 id="pre-register-ghes-marketplaces-with-managed-settings">

160 使用托管设置预注册 GHES 市场

161</h3>

162

163`extraKnownMarketplaces` 设置预注册市场，以便开发人员无需手动设置即可获得它。它可以从 [任何设置文件](/zh-CN/settings#extraknownmarketplaces) 工作，包括存储库的 `.claude/settings.json`；托管设置在整个组织范围内提供它：

164

165```json theme={null}

166{

167 "extraKnownMarketplaces": {

168 "internal-tools": {

169 "source": {

170 "source": "git",

171 "url": "https://github.example.com/platform/claude-plugins.git"

172 }

173 }

174 }

175}

176```

177

178Claude Code 在本地安装这些市场：它注册每个条目并使用机器现有的 git 凭证克隆存储库。此路径不经过 claude.ai，因此不需要按用户的 GitHub Enterprise 连接。为了成功推出：

179

180* **使用完整的 git URL。** `owner/repo` 简写始终解析为 github.com，无法引用 GHES 主机。

181* **优先使用 HTTPS URL。** SSH 克隆在不信任您的 GHES 主机密钥的机器上失败。带有您组织标准 git 凭证助手的 HTTPS URL 在任何配置了凭证的机器上都可以工作。

182* **确认每台机器都可以从您的 GHES 主机克隆。** 如果机器缺少凭证，市场会被注册但永远不会安装，其插件报告为未找到而不是提示输入凭证。

183* **确认设置到达每台机器。** 托管设置文件仅在部署到的机器上生效，例如通过您的设备管理系统。有关文件位置，请参阅 [托管设置](/zh-CN/settings#settings-files)。

184

145<h3 id="allowlist-ghes-marketplaces-in-managed-settings">185<h3 id="allowlist-ghes-marketplaces-in-managed-settings">

146 在托管设置中将 GHES 市场加入白名单186 在托管设置中将 GHES 市场加入白名单

147</h3>187</h3>

159}199}

160```200```

161 201

162您也可以为开发人员预注册市场，以便它们无需手动设置即可显示。此示例使内部工具市场在整个组织中可用：

~~163~~

164```json theme={null}

165{

166 "extraKnownMarketplaces": {

167 "internal-tools": {

168 "source": {

169 "source": "git",

170 "url": "git@github.example.com:platform/claude-plugins.git"

171 }

172 }

173 }

174}

175```

~~176~~

177有关完整的架构，请参阅 [strictKnownMarketplaces](/zh-CN/settings#strictknownmarketplaces) 和 [extraKnownMarketplaces](/zh-CN/settings#extraknownmarketplaces) 设置参考。202有关完整的架构，请参阅 [strictKnownMarketplaces](/zh-CN/settings#strictknownmarketplaces) 和 [extraKnownMarketplaces](/zh-CN/settings#extraknownmarketplaces) 设置参考。

178 203

179<h2 id="limitations">204<h2 id="limitations">

193 网络会话无法克隆存储库218 网络会话无法克隆存储库

194</h3>219</h3>

195 220

196如果 `claude --remote` 因克隆错误而失败，请验证 Owner 已完成您的 GHES 实例的设置，并且 GitHub App 已安装在您正在处理的存储库上。与连接该实例的 Owner 确认在 Claude 设置中注册的主机名与您的 git 远程中的主机名匹配。221如果 `claude --cloud` 因克隆错误而失败，请验证 Owner 已完成您的 GHES 实例的设置，并且 GitHub App 已安装在您正在处理的存储库上。与连接该实例的 Owner 确认在 Claude 设置中注册的主机名与您的 git 远程中的主机名匹配。

197 222

198<h3 id="marketplace-add-fails-with-a-policy-error">223<h3 id="marketplace-add-fails-with-a-policy-error">

199 市场添加因策略错误而失败224 市场添加因策略错误而失败

201 226

202如果 `/plugin marketplace add` 因您的 GHES URL 而被阻止，您的组织已限制市场源。要求您的管理员在 [托管设置](#allowlist-ghes-marketplaces-in-managed-settings) 中为您的 GHES 主机名添加 `hostPattern` 条目。227如果 `/plugin marketplace add` 因您的 GHES URL 而被阻止，您的组织已限制市场源。要求您的管理员在 [托管设置](#allowlist-ghes-marketplaces-in-managed-settings) 中为您的 GHES 主机名添加 `hostPattern` 条目。

203 228

229<h3 id="marketplace-add-on-claude-ai-fails-with-a-github-access-error">

230 claude.ai 上的市场添加因 GitHub 访问错误而失败

231</h3>

232

233如果从您的用户设置添加 GHES 市场失败并出现通用错误（如"无法添加市场"），请先检查您的 GitHub Enterprise 连接。这是当您自己的 GitHub Enterprise 账户未连接到 Claude 时出现的情况，即使您的组织的 GHES 实例已配置且其他用户已连接。该对话框不会指向 GitHub Enterprise 连接流程，"浏览"选项卡上的"连接到 GitHub"选项会登录到 github.com，这不会授予对 GHES 存储库的访问权限。

234

235要连接您的 GitHub Enterprise 账户：[claude.ai/code](https://claude.ai/code) 上的存储库选择器为每个已配置的 GHES 实例提供连接选项，Owner 也可以从 [Claude Code 管理员设置](https://claude.ai/admin-settings/claude-code) 的 GitHub Enterprise 部分进行连接。然后再次添加市场。或者，要求 Owner 在组织插件设置中添加市场，这样可以消除每个用户的连接要求。

236

237在其他 claude.ai 界面上，GHES 市场上的"找不到存储库。如果是私有的，需要 GitHub 访问"错误通常表示相同的缺失连接。通过上述路径之一连接您的 GitHub Enterprise 账户，然后重试。

238

204<h3 id="ghes-instance-not-reachable">239<h3 id="ghes-instance-not-reachable">

205 GHES 实例无法访问240 GHES 实例无法访问

206</h3>241</h3>

gitlab-ci-cd.md +30 −30

Details

24* **自动化实现**：使用单个命令或提及将问题转化为可工作的代码24* **自动化实现**：使用单个命令或提及将问题转化为可工作的代码

25* **项目感知**：Claude 遵循您的 `CLAUDE.md` 指南和现有代码模式25* **项目感知**：Claude 遵循您的 `CLAUDE.md` 指南和现有代码模式

26* **简单设置**：向 `.gitlab-ci.yml` 添加一个作业和一个掩码 CI/CD 变量26* **简单设置**：向 `.gitlab-ci.yml` 添加一个作业和一个掩码 CI/CD 变量

~~27* **企业就绪**：选择 Claude API、Amazon Bedrock 或 Google Vertex AI 以满足数据驻留和采购需求~~27* **企业就绪**：选择 Claude API、Amazon Bedrock 或 Google Cloud 的 Agent Platform 以满足数据驻留和采购需求

28* **默认安全**：在您的 GitLab runners 中运行，具有您的分支保护和批准28* **默认安全**：在您的 GitLab runners 中运行，具有您的分支保护和批准

29 29

30<h2 id="how-it-works">30<h2 id="how-it-works">

382. **提供商抽象**：使用适合您环境的提供商：382. **提供商抽象**：使用适合您环境的提供商：

39 * Claude API (SaaS)39 * Claude API (SaaS)

40 * Amazon Bedrock（基于 IAM 的访问、跨区域选项）40 * Amazon Bedrock（基于 IAM 的访问、跨区域选项）

~~41 * Google Vertex AI（GCP 原生、Workload Identity Federation）~~41 * Google Cloud 的 Agent Platform（GCP 原生、Workload Identity Federation）

42 42

433. **沙箱执行**：每次交互都在具有严格网络和文件系统规则的容器中运行。Claude Code 强制执行工作区范围的权限以限制写入。每项更改都通过 MR 流动，以便审查者可以看到差异，批准仍然适用。433. **沙箱执行**：每次交互都在具有严格网络和文件系统规则的容器中运行。Claude Code 强制执行工作区范围的权限以限制写入。每项更改都通过 MR 流动，以便审查者可以看到差异，批准仍然适用。

44 44

108添加作业和您的 `ANTHROPIC_API_KEY` 变量后，通过从 **CI/CD** → **Pipelines** 手动运行作业进行测试，或从 MR 触发它，让 Claude 在分支中提议更新并在需要时打开 MR。108添加作业和您的 `ANTHROPIC_API_KEY` 变量后，通过从 **CI/CD** → **Pipelines** 手动运行作业进行测试，或从 MR 触发它，让 Claude 在分支中提议更新并在需要时打开 MR。

109 109

110<Note>110<Note>

111 要改为在 Amazon Bedrock 或 Google Vertex AI 上运行而不是 Claude API，请参阅下面的 [Using with Amazon Bedrock & Google Vertex AI](#using-with-amazon-bedrock-%26-google-vertex-ai) 部分，了解身份验证和环境设置。111 要改为在 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上运行而不是 Claude API，请参阅下面的 [Using with Amazon Bedrock and Google Cloud](#using-with-amazon-bedrock-and-google-cloud) 部分，了解身份验证和环境设置。

112</Note>112</Note>

113 113

114<h3 id="manual-setup-recommended-for-production">114<h3 id="manual-setup-recommended-for-production">

119 119

1201. **配置提供商访问**：1201. **配置提供商访问**：

121 * **Claude API**：创建并将 `ANTHROPIC_API_KEY` 存储为掩码 CI/CD 变量121 * **Claude API**：创建并将 `ANTHROPIC_API_KEY` 存储为掩码 CI/CD 变量

122 * **Amazon Bedrock**：**Configure GitLab** → **AWS OIDC** 并为 Bedrock 创建 IAM 角色122 * **Amazon Bedrock**：**Configure GitLab** → **AWS OIDC** 并为 Amazon Bedrock 创建 IAM 角色

123 * **Google Vertex AI**：**Configure Workload Identity Federation for GitLab** → **GCP**123 * **Google Cloud 的 Agent Platform**：**Configure Workload Identity Federation for GitLab** → **GCP**

124 124

1252. **为 GitLab API 操作添加项目凭证**：1252. **为 GitLab API 操作添加项目凭证**：

126 * 默认使用 `CI_JOB_TOKEN`，或创建具有 `api` 范围的项目访问令牌126 * 默认使用 `CI_JOB_TOKEN`，或创建具有 `api` 范围的项目访问令牌

172 172

173Claude 定位错误，实现修复，并更新分支或打开新 MR。173Claude 定位错误，实现修复，并更新分支或打开新 MR。

174 174

175<h2 id="using-with-amazon-bedrock--google-vertex-ai">175<h2 id="using-with-amazon-bedrock-and-google-cloud">

176 使用 Amazon Bedrock 和 Google Vertex AI176 使用 Amazon Bedrock 和 Google Cloud

177</h2>177</h2>

178 178

179对于企业环境，您可以在云基础设施上完全运行 Claude Code，具有相同的开发者体验。179对于企业环境，您可以在云基础设施上完全运行 Claude Code，具有相同的开发者体验。

186 186

187 1. 具有对所需 Claude 模型的 Amazon Bedrock 访问权限的 AWS 账户187 1. 具有对所需 Claude 模型的 Amazon Bedrock 访问权限的 AWS 账户

188 2. 在 AWS IAM 中配置为 OIDC 身份提供商的 GitLab188 2. 在 AWS IAM 中配置为 OIDC 身份提供商的 GitLab

189 3. 具有 Bedrock 权限和信任策略的 IAM 角色，限制为您的 GitLab 项目/refs189 3. 具有 Amazon Bedrock 权限和信任策略的 IAM 角色，限制为您的 GitLab 项目/refs

190 4. 用于角色假设的 GitLab CI/CD 变量：190 4. 用于角色假设的 GitLab CI/CD 变量：

191 * `AWS_ROLE_TO_ASSUME`（角色 ARN）191 * `AWS_ROLE_TO_ASSUME`（角色 ARN）

192 * `AWS_REGION`（Bedrock 区域）192 * `AWS_REGION`（Amazon Bedrock 区域）

193 193

194 ### 设置说明194 ### 设置说明

195 195

200 1. 启用 Amazon Bedrock 并请求访问您的目标 Claude 模型200 1. 启用 Amazon Bedrock 并请求访问您的目标 Claude 模型

201 2. 如果尚未存在，为 GitLab 创建 IAM OIDC 提供商201 2. 如果尚未存在，为 GitLab 创建 IAM OIDC 提供商

202 3. 创建由 GitLab OIDC 提供商信任的 IAM 角色，限制为您的项目和受保护的 refs202 3. 创建由 GitLab OIDC 提供商信任的 IAM 角色，限制为您的项目和受保护的 refs

203 4. 为 Bedrock 调用 API 附加最小权限203 4. 为 Amazon Bedrock 调用 API 附加最小权限

204 204

205 **需要存储在 CI/CD 变量中的必需值：**205 **需要存储在 CI/CD 变量中的必需值：**

206 206

218 使用上面的 Amazon Bedrock 作业示例在运行时交换 GitLab 作业令牌以获取临时 AWS 凭证。218 使用上面的 Amazon Bedrock 作业示例在运行时交换 GitLab 作业令牌以获取临时 AWS 凭证。

219 </Tab>219 </Tab>

220 220

221 <Tab title="Google Vertex AI">221 <Tab title="Google Cloud's Agent Platform">

222 ### 前置条件222 ### 前置条件

223 223

224 在使用 Google Vertex AI 设置 Claude Code 之前，您需要：224 在使用 Google Cloud's Agent Platform 设置 Claude Code 之前，您需要：

225 225

226 1. 具有以下条件的 Google Cloud 项目：226 1. 具有以下条件的 Google Cloud 项目：

227 * 启用了 Vertex AI API227 * 启用了 Google Cloud's Agent Platform API

228 * 配置了 Workload Identity Federation 以信任 GitLab OIDC228 * 配置了 Workload Identity Federation 以信任 GitLab OIDC

229 2. 仅具有所需 Vertex AI 角色的专用服务账户229 2. 仅具有所需 Google Cloud's Agent Platform 角色的专用服务账户

230 3. 用于 WIF 的 GitLab CI/CD 变量：230 3. 用于 WIF 的 GitLab CI/CD 变量：

231 * `GCP_WORKLOAD_IDENTITY_PROVIDER`（完整资源名称）231 * `GCP_WORKLOAD_IDENTITY_PROVIDER`（完整资源名称）

232 * `GCP_SERVICE_ACCOUNT`（服务账户电子邮件）232 * `GCP_SERVICE_ACCOUNT`（服务账户电子邮件）

237 237

238 **必需的设置：**238 **必需的设置：**

239 239

240 1. 启用 IAM Credentials API、STS API 和 Vertex AI API240 1. 启用 IAM Credentials API、STS API 和 Google Cloud's Agent Platform API

241 2. 为 GitLab OIDC 创建 Workload Identity Pool 和提供商241 2. 为 GitLab OIDC 创建 Workload Identity Pool 和提供商

242 3. 创建具有 Vertex AI 角色的专用服务账户242 3. 创建具有 Google Cloud's Agent Platform 角色的专用服务账户

243 4. 授予 WIF 主体权限以模拟服务账户243 4. 授予 WIF 主体权限以模拟服务账户

244 244

245 **需要存储在 CI/CD 变量中的必需值：**245 **需要存储在 CI/CD 变量中的必需值：**

250 在 Settings → CI/CD → Variables 中添加变量：250 在 Settings → CI/CD → Variables 中添加变量：

251 251

252 ```yaml theme={null}252 ```yaml theme={null}

253 # 对于 Google Vertex AI：253 # 对于 Google Cloud's Agent Platform：

254 - GCP_WORKLOAD_IDENTITY_PROVIDER254 - GCP_WORKLOAD_IDENTITY_PROVIDER

255 - GCP_SERVICE_ACCOUNT255 - GCP_SERVICE_ACCOUNT

256 - CLOUD_ML_REGION（例如，us-east5）256 - CLOUD_ML_REGION（例如，us-east5）

257 ```257 ```

258 258

259 使用上面的 Google Vertex AI 作业示例在不存储密钥的情况下进行身份验证。259 使用上面的 Google Cloud's Agent Platform 作业示例在不存储密钥的情况下进行身份验证。

260 </Tab>260 </Tab>

261</Tabs>261</Tabs>

262 262

305 305

306* 启用了 Amazon Bedrock 并可访问您选择的 Claude 模型306* 启用了 Amazon Bedrock 并可访问您选择的 Claude 模型

307* 在 AWS 中配置了 GitLab OIDC，具有信任您的 GitLab 项目和 refs 的角色307* 在 AWS 中配置了 GitLab OIDC，具有信任您的 GitLab 项目和 refs 的角色

308* 具有 Bedrock 权限的 IAM 角色（建议最小权限）308* 具有 Amazon Bedrock 权限的 IAM 角色（建议最小权限）

309 309

310**必需的 CI/CD 变量：**310**必需的 CI/CD 变量：**

311 311

312* `AWS_ROLE_TO_ASSUME`：用于 Bedrock 访问的 IAM 角色的 ARN312* `AWS_ROLE_TO_ASSUME`：用于 Amazon Bedrock 访问的 IAM 角色的 ARN

313* `AWS_REGION`：Bedrock 区域（例如，`us-west-2`）313* `AWS_REGION`：Amazon Bedrock 区域（例如，`us-west-2`）

314 314

315```yaml theme={null}315```yaml theme={null}

316claude-bedrock:316claude-bedrock:

347```347```

348 348

349<Note>349<Note>

350 Bedrock 的模型 ID 包括特定于区域的前缀（例如，`us.anthropic.claude-sonnet-4-6`）。如果您的工作流支持，通过您的作业配置或提示传递所需的模型。350 Amazon Bedrock 的模型 ID 包括特定于区域的前缀（例如，`us.anthropic.claude-sonnet-4-6`）。如果您的工作流支持，通过您的作业配置或提示传递所需的模型。

351</Note>351</Note>

352 352

353<h3 id="google-vertex-ai-job-example-workload-identity-federation">353<h3 id="agent-platform-job-example-workload-identity-federation">

354 Google Vertex AI 作业示例（Workload Identity Federation）354 Agent Platform 作业示例（Workload Identity Federation）

355</h3>355</h3>

356 356

357**前置条件：**357**前置条件：**

358 358

359* 在您的 GCP 项目中启用了 Vertex AI API359* 在您的 GCP 项目中启用了 Google Cloud 的 Agent Platform API

360* 配置了 Workload Identity Federation 以信任 GitLab OIDC360* 配置了 Workload Identity Federation 以信任 GitLab OIDC

361* 具有 Vertex AI 权限的服务账户361* 具有 Google Cloud 的 Agent Platform 权限的服务账户

362 362

363**必需的 CI/CD 变量：**363**必需的 CI/CD 变量：**

364 364

365* `GCP_WORKLOAD_IDENTITY_PROVIDER`：完整的提供商资源名称365* `GCP_WORKLOAD_IDENTITY_PROVIDER`：完整的提供商资源名称

366* `GCP_SERVICE_ACCOUNT`：服务账户电子邮件366* `GCP_SERVICE_ACCOUNT`：服务账户电子邮件

367* `CLOUD_ML_REGION`：Vertex 区域（例如，`us-east5`）367* `CLOUD_ML_REGION`：Google Cloud 的 Agent Platform 区域（例如，`us-east5`）

368 368

369```yaml theme={null}369```yaml theme={null}

370claude-vertex:370claude-vertex:

490</h3>490</h3>

491 491

492* **对于 Claude API**：确认 `ANTHROPIC_API_KEY` 有效且未过期492* **对于 Claude API**：确认 `ANTHROPIC_API_KEY` 有效且未过期

493* **对于 Bedrock/Vertex**：验证 OIDC/WIF 配置、角色模拟和密钥名称；确认区域和模型可用性493* **对于 Amazon Bedrock 或 Google Cloud 的 Agent Platform**：验证 OIDC/WIF 配置、角色模拟和密钥名称；确认区域和模型可用性

494 494

495<h2 id="advanced-configuration">495<h2 id="advanced-configuration">

496 高级配置496 高级配置

505* `prompt` / `prompt_file`：内联提供说明（`-p`）或通过文件505* `prompt` / `prompt_file`：内联提供说明（`-p`）或通过文件

506* `max_turns`：限制来回迭代的次数506* `max_turns`：限制来回迭代的次数

507* `timeout_minutes`：限制总执行时间507* `timeout_minutes`：限制总执行时间

508* `ANTHROPIC_API_KEY`：Claude API 所需（不用于 Bedrock/Vertex）508* `ANTHROPIC_API_KEY`：Claude API 所需（不用于 Amazon Bedrock 或 Google Cloud 的 Agent Platform）

509* 提供商特定的环境：`AWS_REGION`、Vertex 的项目/区域变量509* 提供商特定的环境：`AWS_REGION`、Google Cloud 的 Agent Platform 的项目/区域变量

510 510

511<Note>511<Note>

512 确切的标志和参数可能因 `@anthropic-ai/claude-code` 的版本而异。在您的作业中运行 `claude --help` 以查看支持的选项。512 确切的标志和参数可能因 `@anthropic-ai/claude-code` 的版本而异。在您的作业中运行 `claude --help` 以查看支持的选项。

glossary.md +3 −1

Details

262 262

263会话的基线批准行为。在 CLI 中使用 `Shift+Tab` 循环或在 VS Code、Desktop 和 claude.ai 中使用模式选择器。可用模式为 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk` 和 `bypassPermissions`。263会话的基线批准行为。在 CLI 中使用 `Shift+Tab` 循环或在 VS Code、Desktop 和 claude.ai 中使用模式选择器。可用模式为 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk` 和 `bypassPermissions`。

264 264

265`default` 模式在 CLI 中标记为 Manual，在 VS Code 和 JetBrains 扩展中也标记为 Manual，Claude Code 接受 `manual` 作为该值的别名。

266

265了解更多：[选择权限模式](/zh-CN/permission-modes)267了解更多：[选择权限模式](/zh-CN/permission-modes)

266 268

267<h3 id="permission-rule">269<h3 id="permission-rule">

388 Teleport390 Teleport

389</h3>391</h3>

390 392

391一个命令 `/teleport`，将云 Claude Code 会话拉入您的本地终端。Claude 获取分支、加载对话历史并从 web 会话的最后状态恢复。反向方向是 `--remote`，它将本地任务发送到 web 上运行。393一个命令 `/teleport`，将云 Claude Code 会话拉入您的本地终端。Claude 获取分支、加载对话历史并从 web 会话的最后状态恢复。反向方向是 `--cloud`，它将本地任务发送到 web 上运行。

392 394

393了解更多：[从 web 到终端](/zh-CN/claude-code-on-the-web#from-web-to-terminal)395了解更多：[从 web 到终端](/zh-CN/claude-code-on-the-web#from-web-to-terminal)

394 396

google-vertex-ai.md +38 −38

Details

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.

4 4

~~5# Google Vertex AI 上的 Claude Code~~5# Google Cloud 的 Agent Platform 上的 Claude Code

6 6

~~7> 了解如何通过 Google Vertex AI 配置 Claude Code，包括设置、IAM 配置和故障排除。~~7> 了解如何通过 Google Cloud 的 Agent Platform（原 Vertex AI）配置 Claude Code，包括设置、IAM 配置和故障排除。

8 8

9export const ContactSalesCard = ({surface}) => {9export const ContactSalesCard = ({surface}) => {

10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;

82 前置条件82 前置条件

83</h2>83</h2>

84 84

~~85在使用 Vertex AI 配置 Claude Code 之前，请确保您拥有：~~85在使用 Google Cloud 的 Agent Platform（原 Vertex AI）配置 Claude Code 之前，请确保您拥有：

86 86

87* 启用了计费的 Google Cloud Platform (GCP) 账户87* 启用了计费的 Google Cloud Platform (GCP) 账户

~~88* 启用了 Vertex AI API 的 GCP 项目~~88* 启用了 Google Cloud 的 Agent Platform API 的 GCP 项目

89* 对所需 Claude 模型的访问权限（例如，Claude Sonnet 4.6）89* 对所需 Claude 模型的访问权限（例如，Claude Sonnet 4.6）

90* 已安装并配置的 Google Cloud SDK (`gcloud`)90* 已安装并配置的 Google Cloud SDK (`gcloud`)

91* 在所需 GCP 区域中分配的配额91* 在所需 GCP 区域中分配的配额

92 92

93要使用您自己的 Vertex AI 凭证登录，请按照下面的[使用 Vertex AI 登录](#sign-in-with-vertex-ai)进行操作。要在团队中部署 Claude Code，请使用[手动设置](#set-up-manually)步骤并在推出前[固定您的模型版本](#5-pin-model-versions)。93要使用您自己的 Google Cloud 的 Agent Platform 凭证登录，请按照下面的[使用 Google Cloud 的 Agent Platform 登录](#sign-in-with-agent-platform)进行操作。要在团队中部署 Claude Code，请使用[手动设置](#set-up-manually)步骤并在推出前[固定您的模型版本](#5-pin-model-versions)。

94 94

~~95<h2 id="sign-in-with-vertex-ai">~~95<h2 id="sign-in-with-agent-platform">

~~96 使用 Vertex AI 登录~~96 使用 Agent Platform 登录

97</h2>97</h2>

98 98

99如果您拥有 Google Cloud 凭证并想开始通过 Vertex AI 使用 Claude Code，登录向导会引导您完成整个过程。您需要在每个项目中完成一次 GCP 端的前置条件；向导会处理 Claude Code 端的事务。99如果您拥有 Google Cloud 凭证并想开始通过 Google Cloud 的 Agent Platform 使用 Claude Code，登录向导会引导您完成整个过程。您需要在每个项目中完成一次 GCP 端的前置条件；向导会处理 Claude Code 端的事务。

100 100

101<Note>101<Note>

102 Vertex AI 设置向导需要 Claude Code v2.1.98 或更高版本。运行 `claude --version` 来检查。102 Google Cloud 的 Agent Platform 设置向导需要 Claude Code v2.1.98 或更高版本。运行 `claude --version` 来检查。

103</Note>103</Note>

104 104

105<Steps>105<Steps>

106 <Step title="在您的 GCP 项目中启用 Claude 模型">106 <Step title="在您的 GCP 项目中启用 Claude 模型">

107 为您的项目[启用 Vertex AI API](#1-enable-vertex-ai-api)，然后在 [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中请求访问您想要的 Claude 模型。有关您的账户需要的权限，请参阅 [IAM 配置](#iam-configuration)。107 为您的项目[启用 Google Cloud 的 Agent Platform API](#1-enable-agent-platform-api)，然后在 [Google Cloud 的 Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中请求访问您想要的 Claude 模型。有关您的账户需要的权限，请参阅 [IAM 配置](#iam-configuration)。

108 </Step>108 </Step>

109 109

110 <Step title="启动 Claude Code 并选择 Vertex AI">110 <Step title="启动 Claude Code 并选择 Google Cloud 的 Agent Platform">

111 运行 `claude`。在登录提示处，选择 **3rd-party platform**，然后选择 **Google Vertex AI**。111 运行 `claude`。在登录提示处，选择 **3rd-party platform**，然后选择 **Google Vertex AI**，这是登录提示仍然用于 Google Cloud 的 Agent Platform 的标签。

112 </Step>112 </Step>

113 113

114 <Step title="按照向导提示进行操作">114 <Step title="按照向导提示进行操作">

122 区域配置122 区域配置

123</h2>123</h2>

124 124

125Claude Code 支持 Vertex AI [全局](https://cloud.google.com/blog/products/ai-machine-learning/global-endpoint-for-claude-models-generally-available-on-vertex-ai)、多区域和区域端点。将 `CLOUD_ML_REGION` 设置为 `global`、多区域位置（如 `eu` 或 `us`）或特定区域（如 `us-east5`）。Claude Code 为每种形式选择正确的 Vertex AI 主机名，包括多区域位置的 `aiplatform.eu.rep.googleapis.com` 和 `aiplatform.us.rep.googleapis.com` 主机。125Claude Code 支持 Google Cloud 的 Agent Platform [全局](https://cloud.google.com/blog/products/ai-machine-learning/global-endpoint-for-claude-models-generally-available-on-vertex-ai)、多区域和区域端点。将 `CLOUD_ML_REGION` 设置为 `global`、多区域位置（如 `eu` 或 `us`）或特定区域（如 `us-east5`）。Claude Code 为每种形式选择正确的 Google Cloud 的 Agent Platform 主机名，包括多区域位置的 `aiplatform.eu.rep.googleapis.com` 和 `aiplatform.us.rep.googleapis.com` 主机。

126 126

127<Note>127<Note>

128 Vertex AI 可能不支持 Claude Code 默认模型在每个端点类型上。模型可用性在[特定区域](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations#genai-partner-models)、多区域位置和[全局端点](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#supported_models)之间有所不同。您可能需要切换到支持的位置或指定支持的模型。128 Google Cloud 的 Agent Platform 可能不支持 Claude Code 默认模型在每个端点类型上。模型可用性在[特定区域](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations#genai-partner-models)、多区域位置和[全局端点](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#supported_models)之间有所不同。您可能需要切换到支持的位置或指定支持的模型。

129</Note>129</Note>

130 130

131<h2 id="set-up-manually">131<h2 id="set-up-manually">

132 手动设置132 手动设置

133</h2>133</h2>

134 134

135要通过环境变量而不是向导配置 Vertex AI，例如在 CI 或脚本化企业推出中，请按照下面的步骤进行。135要通过环境变量而不是向导配置 Google Cloud 的 Agent Platform，例如在 CI 或脚本化企业推出中，请按照下面的步骤进行。

136 136

137<h3 id="1-enable-vertex-ai-api">137<h3 id="1-enable-agent-platform-api">

138 1. 启用 Vertex AI API138 1. 启用 Agent Platform API

139</h3>139</h3>

140 140

141在您的 GCP 项目中启用 Vertex AI API：141在您的 GCP 项目中启用 Google Cloud 的 Agent Platform API：

142 142

143```bash theme={null}143```bash theme={null}

144# 设置您的项目 ID144# 设置您的项目 ID

145gcloud config set project YOUR-PROJECT-ID145gcloud config set project YOUR-PROJECT-ID

146 146

147# 启用 Vertex AI API147# 启用 Agent Platform API

148gcloud services enable aiplatform.googleapis.com148gcloud services enable aiplatform.googleapis.com

149```149```

150 150

152 2. 请求模型访问权限152 2. 请求模型访问权限

153</h3>153</h3>

154 154

155请求访问 Vertex AI 中的 Claude 模型：155请求访问 Google Cloud 的 Agent Platform 中的 Claude 模型：

156 156

1571. 导航到 [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)1571. 导航到 [Google Cloud 的 Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)

1582. 搜索"Claude"模型1582. 搜索"Claude"模型

1593. 请求访问所需的 Claude 模型（例如，Claude Sonnet 4.6）1593. 请求访问所需的 Claude 模型（例如，Claude Sonnet 4.6）

1604. 等待批准（可能需要 24-48 小时）1604. 等待批准（可能需要 24-48 小时）

170Claude Code v2.1.121 或更高版本通过相同的应用默认凭证链支持[基于 X.509 证书的工作负载身份联合](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates)。将 `GOOGLE_APPLICATION_CREDENTIALS` 设置为您的凭证配置文件的路径。170Claude Code v2.1.121 或更高版本通过相同的应用默认凭证链支持[基于 X.509 证书的工作负载身份联合](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates)。将 `GOOGLE_APPLICATION_CREDENTIALS` 设置为您的凭证配置文件的路径。

171 171

172<Note>172<Note>

173 Claude Code 使用 `ANTHROPIC_VERTEX_PROJECT_ID` 作为 Vertex AI 请求的项目 ID。`GCLOUD_PROJECT` 和 `GOOGLE_CLOUD_PROJECT` 环境变量以及 `GOOGLE_APPLICATION_CREDENTIALS` 引用的凭证文件优先于它。如果这些都未设置，项目 ID 将从您的 `gcloud` 配置或附加的服务账户解析。173 Claude Code 使用 `ANTHROPIC_VERTEX_PROJECT_ID` 作为 Google Cloud 的 Agent Platform 请求的项目 ID。`GCLOUD_PROJECT` 和 `GOOGLE_CLOUD_PROJECT` 环境变量以及 `GOOGLE_APPLICATION_CREDENTIALS` 引用的凭证文件优先于它。如果这些都未设置，项目 ID 将从您的 `gcloud` 配置或附加的服务账户解析。

174</Note>174</Note>

175 175

176<h4 id="advanced-credential-configuration">176<h4 id="advanced-credential-configuration">

197设置以下环境变量：197设置以下环境变量：

198 198

199```bash theme={null}199```bash theme={null}

200# 启用 Vertex AI 集成200# 启用 Agent Platform 集成

201export CLAUDE_CODE_USE_VERTEX=1201export CLAUDE_CODE_USE_VERTEX=1

202export CLOUD_ML_REGION=global202export CLOUD_ML_REGION=global

203export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID203export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

204 204

205# 可选：为自定义端点或网关覆盖 Vertex 端点 URL205# 可选：为自定义端点或网关覆盖 Agent Platform 端点 URL

206# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com206# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

207 207

208# 可选：如果需要，禁用 prompt caching208# 可选：如果需要，禁用 prompt caching

216export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1216export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

217```217```

218 218

219大多数模型版本都有对应的 `VERTEX_REGION_CLAUDE_*` 变量。有关完整列表，请参阅[环境变量参考](/zh-CN/env-vars)。检查 [Vertex Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 以确定哪些模型支持全局端点与仅区域端点。219大多数模型版本都有对应的 `VERTEX_REGION_CLAUDE_*` 变量。有关完整列表，请参阅[环境变量参考](/zh-CN/env-vars)。检查 [Google Cloud 的 Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 以确定哪些模型支持全局端点与仅区域端点。

220 220

221[Prompt caching](/zh-CN/prompt-caching) 会自动启用。要禁用它，请设置 `DISABLE_PROMPT_CACHING=1`。要请求 1 小时的缓存 TTL 而不是 5 分钟的默认值，请设置 `ENABLE_PROMPT_CACHING_1H=1`；具有 1 小时 TTL 的缓存写入按更高费率计费。如需提高速率限制，请联系 Google Cloud 支持。使用 Vertex AI 时，`/logout` 命令不可用，因为身份验证通过 Google Cloud 凭证处理。221[Prompt caching](/zh-CN/prompt-caching) 会自动启用。要禁用它，请设置 `DISABLE_PROMPT_CACHING=1`。要请求 1 小时的缓存 TTL 而不是 5 分钟的默认值，请设置 `ENABLE_PROMPT_CACHING_1H=1`；具有 1 小时 TTL 的缓存写入按更高费率计费。如需提高速率限制，请联系 Google Cloud 支持。使用 Google Cloud 的 Agent Platform 时，`/logout` 命令不可用，因为身份验证通过 Google Cloud 凭证处理。

222 222

223Claude Code 在 Vertex AI 上默认禁用 [MCP tool search](/zh-CN/mcp#scale-with-mcp-tool-search)，因此 MCP 工具定义会预先加载。Vertex AI 支持 Claude Sonnet 4.5 及更高版本以及 Claude Opus 4.5 及更高版本的工具搜索。设置 `ENABLE_TOOL_SEARCH=true` 以在这些模型上启用它。Vertex AI 上的早期模型不接受所需的 beta 标头，如果您对它们启用工具搜索，请求将失败。223Claude Code 在 Google Cloud 的 Agent Platform 上默认禁用 [MCP tool search](/zh-CN/mcp#scale-with-mcp-tool-search)，因此 MCP 工具定义会预先加载。Google Cloud 的 Agent Platform 支持 Claude Sonnet 4.5 及更高版本以及 Claude Opus 4.5 及更高版本的工具搜索。设置 `ENABLE_TOOL_SEARCH=true` 以在这些模型上启用它。Google Cloud 的 Agent Platform 上的早期模型不接受所需的 beta 标头，如果您对它们启用工具搜索，请求将失败。

224 224

225<h3 id="5-pin-model-versions">225<h3 id="5-pin-model-versions">

226 5. 固定模型版本226 5. 固定模型版本

227</h3>227</h3>

228 228

229<Warning>229<Warning>

230 在部署到多个用户时固定特定的模型版本。如果不固定，模型别名（如 `sonnet` 和 `opus`）会解析为 Claude Code 的 Vertex AI 内置默认值，该默认值可能滞后于最新版本，并且可能尚未在您的项目中启用。Claude Code 在启动时当默认值不可用时会[回退](#startup-model-checks)到之前的版本，但固定让您可以控制用户何时迁移到新模型。230 在部署到多个用户时固定特定的模型版本。如果不固定，模型别名（如 `sonnet` 和 `opus`）会解析为 Claude Code 的 Google Cloud 的 Agent Platform 内置默认值，该默认值可能滞后于最新版本，并且可能尚未在您的项目中启用。Claude Code 在启动时当默认值不可用时会[回退](#startup-model-checks)到之前的版本，但固定让您可以控制用户何时迁移到新模型。

231</Warning>231</Warning>

232 232

233将这些环境变量设置为特定的 Vertex AI 模型 ID。233将这些环境变量设置为特定的 Google Cloud 的 Agent Platform 模型 ID。

234 234

235如果没有 `ANTHROPIC_DEFAULT_OPUS_MODEL`，Vertex 上的 `opus` 别名会解析为 Opus 4.6。将其设置为 Opus 4.8 ID 以使用最新模型：235如果没有 `ANTHROPIC_DEFAULT_OPUS_MODEL`，Google Cloud 的 Agent Platform 上的 `opus` 别名会解析为 Opus 4.6。将其设置为 Opus 4.8 ID 以使用最新模型：

236 236

237```bash theme={null}237```bash theme={null}

238export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'238export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'

249| 主模型 | `claude-sonnet-4-5@20250929` |249| 主模型 | `claude-sonnet-4-5@20250929` |

250| 小型/快速模型 | 与主模型相同 |250| 小型/快速模型 | 与主模型相同 |

251 251

252后台任务（如会话标题生成）使用小型/快速模型，通常是 Haiku 级别的模型。在 Vertex AI 上，Claude Code 默认将其设置为主模型，因为 Haiku 可能不会在每个项目或区域中启用。要为后台任务使用 Haiku，请将 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 设置为在您的项目中可用的模型 ID。252后台任务（如会话标题生成）使用小型/快速模型，通常是 Haiku 级别的模型。在 Google Cloud 的 Agent Platform 上，Claude Code 默认将其设置为主模型，因为 Haiku 可能不会在每个项目或区域中启用。要为后台任务使用 Haiku，请将 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 设置为在您的项目中可用的模型 ID。

253 253

254要进一步自定义模型：254要进一步自定义模型：

255 255

262 启动模型检查262 启动模型检查

263</h2>263</h2>

264 264

265当 Claude Code 启动并配置了 Vertex AI 时，它会验证它打算使用的模型在您的项目中是否可访问。此检查需要 Claude Code v2.1.98 或更高版本。265当 Claude Code 启动并配置了 Google Cloud 的 Agent Platform 时，它会验证它打算使用的模型在您的项目中是否可访问。此检查需要 Claude Code v2.1.98 或更高版本。

266 266

267如果您固定了一个比当前 Claude Code 默认值更旧的模型版本，并且您的项目可以调用较新版本，Claude Code 会提示您更新固定。接受会将新的模型 ID 写入您的[用户设置文件](/zh-CN/settings)并重启 Claude Code。拒绝会被记住，直到下一个默认版本更改。267如果您固定了一个比当前 Claude Code 默认值更旧的模型版本，并且您的项目可以调用较新版本，Claude Code 会提示您更新固定。接受会将新的模型 ID 写入您的[用户设置文件](/zh-CN/settings)并重启 Claude Code。拒绝会被记住，直到下一个默认版本更改。

268 268

280 280

281对于更严格的权限，请创建仅包含上述权限的自定义角色。281对于更严格的权限，请创建仅包含上述权限的自定义角色。

282 282

283有关详细信息，请参阅 [Vertex IAM 文档](https://cloud.google.com/vertex-ai/docs/general/access-control)。283有关详细信息，请参阅 [Google Cloud 的 Agent Platform IAM 文档](https://cloud.google.com/vertex-ai/docs/general/access-control)。

284 284

285<Note>285<Note>

286 为 Claude Code 创建专用的 GCP 项目，以简化成本跟踪和访问控制。286 为 Claude Code 创建专用的 GCP 项目，以简化成本跟踪和访问控制。

290 1M token context window290 1M token context window

291</h2>291</h2>

292 292

293Claude Sonnet 5、Opus 4.6 及更高版本以及 Sonnet 4.6 在 Vertex AI 上支持 [1M token context window](https://platform.claude.com/docs/zh-CN/build-with-claude/context-windows#1m-token-context-window)。Sonnet 5 始终以 1M 窗口运行，没有 `[1m]` 变体可选择。对于其他模型，当您选择 1M 模型变体时，Claude Code 会自动启用扩展 context window。293Claude Sonnet 5、Opus 4.6 及更高版本以及 Sonnet 4.6 在 Google Cloud 的 Agent Platform 上支持 [1M token context window](https://platform.claude.com/docs/zh-CN/build-with-claude/context-windows#1m-token-context-window)。Sonnet 5 始终以 1M 窗口运行，没有 `[1m]` 变体可选择。对于其他模型，当您选择 1M 模型变体时，Claude Code 会自动启用扩展 context window。

294 294

295[设置向导](#sign-in-with-vertex-ai)在固定模型时提供 1M context 选项。要为手动固定的模型启用它，请在模型 ID 后附加 `[1m]`。有关详细信息，请参阅[为第三方部署固定模型](/zh-CN/model-config#pin-models-for-third-party-deployments)。295[设置向导](#sign-in-with-agent-platform)在固定模型时提供 1M context 选项。要为手动固定的模型启用它，请在模型 ID 后附加 `[1m]`。有关详细信息，请参阅[为第三方部署固定模型](/zh-CN/model-config#pin-models-for-third-party-deployments)。

296 296

297<h2 id="troubleshooting">297<h2 id="troubleshooting">

298 故障排除298 故障排除

325 其他资源325 其他资源

326</h2>326</h2>

327 327

328* [Vertex AI 文档](https://cloud.google.com/vertex-ai/docs)328* [Google Cloud 的 Agent Platform 文档](https://cloud.google.com/vertex-ai/docs)

329* [Vertex AI 定价](https://cloud.google.com/vertex-ai/pricing)329* [Google Cloud 的 Agent Platform 定价](https://cloud.google.com/vertex-ai/pricing)

330* [Vertex AI 配额和限制](https://cloud.google.com/vertex-ai/docs/quotas)330* [Google Cloud 的 Agent Platform 配额和限制](https://cloud.google.com/vertex-ai/docs/quotas)

headless.md +9 −3

Details

56| 自定义 agents | `--agents <json>` |56| 自定义 agents | `--agents <json>` |

57| 插件 | `--plugin-dir <path>`, `--plugin-url <url>` |57| 插件 | `--plugin-dir <path>`, `--plugin-url <url>` |

58 58

59裸模式跳过 OAuth 和钥匙链读取。Anthropic 身份验证必须来自 `ANTHROPIC_API_KEY` 或传递给 `--settings` 的 JSON 中的 `apiKeyHelper`。Bedrock、Vertex 和 Foundry 使用其常规提供商凭证。59裸模式跳过 OAuth 和钥匙链读取。Anthropic 身份验证必须来自 `ANTHROPIC_API_KEY` 或传递给 `--settings` 的 JSON 中的 `apiKeyHelper`。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 使用其常规提供商凭证。

60 60

61<Note>61<Note>

62 `--bare` 是脚本和 SDK 调用的推荐模式，将在未来版本中成为 `-p` 的默认值。62 `--bare` 是脚本和 SDK 调用的推荐模式，将在未来版本中成为 `-p` 的默认值。

136 --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'136 --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

137```137```

138 138

139如果该值不是有效的 JSON Schema，`claude` 会以 `Error: --json-schema is not a valid JSON Schema` 退出，后跟验证器的诊断。Claude Code 接受使用 `format` 关键字的架构，例如 `"format": "email"`，但将 `format` 视为注释，不强制执行它。在 v2.1.205 之前，Claude Code 会静默忽略无效的架构并返回非结构化文本，并将任何包含 `format` 的架构视为无效。

140

139<Tip>141<Tip>

140 使用 [jq](https://jqlang.github.io/jq/) 之类的工具来解析响应并提取特定字段：142 使用 [jq](https://jqlang.github.io/jq/) 之类的工具来解析响应并提取特定字段：

141 143

182| `uuid` | 字符串 | 唯一事件标识符 |184| `uuid` | 字符串 | 唯一事件标识符 |

183| `session_id` | 字符串 | 事件所属的会话 |185| `session_id` | 字符串 | 事件所属的会话 |

184 186

185`system/init` 事件报告会话元数据，包括模型、工具、MCP 服务器和加载的插件。它是流中的第一个事件，除非设置了 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/zh-CN/env-vars)，在这种情况下 `plugin_install` 事件在其之前。使用插件字段在插件未加载时使 CI 失败：187`system/init` 事件报告会话元数据，包括模型、工具、MCP 服务器和加载的插件。它是流中的第一个事件，除非设置了 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/zh-CN/env-vars)，在这种情况下 `plugin_install` 事件在其之前。

188

189该事件还携带一个可选的 `capabilities` 字符串数组，命名此 Claude Code 版本实现的协议行为，例如 `interrupt_receipt_v1`。检查它以进行功能检测，而不是比较版本字符串，并忽略您不认识的值。该字段需要 Claude Code v2.1.205 或更高版本，在早期版本中不存在。有关功能列表，请参阅 [`SDKSystemMessage`](/zh-CN/agent-sdk/typescript#sdksystemmessage)。

190

191使用插件字段在插件未加载时使 CI 失败：

186 192

187| 字段 | 类型 | 描述 |193| 字段 | 类型 | 描述 |

188| --------------- | -- | --------------------------------------------------------------------------------------------------------------------------- |194| --------------- | -- | --------------------------------------------------------------------------------------------------------------------------- |

234`--allowedTools` 标志使用 [权限规则语法](/zh-CN/settings#permission-rule-syntax)。尾部的 ` *` 启用前缀匹配，因此 `Bash(git diff *)` 允许任何以 `git diff` 开头的命令。空格在 `*` 之前很重要：没有它，`Bash(git diff*)` 也会匹配 `git diff-index`。240`--allowedTools` 标志使用 [权限规则语法](/zh-CN/settings#permission-rule-syntax)。尾部的 ` *` 启用前缀匹配，因此 `Bash(git diff *)` 允许任何以 `git diff` 开头的命令。空格在 `*` 之前很重要：没有它，`Bash(git diff*)` 也会匹配 `git diff-index`。

235 241

236<Note>242<Note>

237 用户调用的 [skills](/zh-CN/skills) 和自定义命令在 `-p` 模式下工作：在提示字符串中包含 `/skill-name`，Claude Code 会在运行前展开它。打开交互对话框的内置命令，例如 `/login`，在 `-p` 模式下不可用。{/* min-version: 2.1.181 */}要从 `-p` 调用更改设置，请将 `key=value` 传递给 `/config`，例如 `/config thinking=false`。243 用户调用的 [skills](/zh-CN/skills) 和自定义命令在 `-p` 模式下工作：在提示字符串中包含 `/skill-name`，Claude Code 会在运行前展开它。打开交互对话框的内置命令，例如 `/login`，在 `-p` 模式下不可用。{/* min-version: 2.1.205 */}`/model`、`/effort`、`/fast`、`/color` 和 `/rename` 接受该值作为参数，例如 `/model sonnet`，`/mcp` 不带参数打印服务器状态的文本摘要；这些形式需要 Claude Code v2.1.205 或更高版本，并遵循每个命令的 [可用性说明](/zh-CN/commands#all-commands)。{/* min-version: 2.1.181 */}要从 `-p` 调用更改设置，请将 `key=value` 传递给 `/config`，例如 `/config thinking=false`。

238</Note>244</Note>

239 245

240<h3 id="customize-the-system-prompt">246<h3 id="customize-the-system-prompt">

hooks.md +17 −11

Details

280 280

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

282 282

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

284

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

284 286

285```json theme={null}287```json theme={null}

456除了[通用字段](#common-fields)外，MCP 工具 hooks 还接受这些字段：458除了[通用字段](#common-fields)外，MCP 工具 hooks 还接受这些字段：

457 459

458| 字段 | 必需 | 描述 |460| 字段 | 必需 | 描述 |

459| :------- | :- | :----------------------------------------------------------------------------------------------------- |461| :------- | :- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

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

463 465

638| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |640| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

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

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

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

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

646 648

1591 ExitPlanMode1593 ExitPlanMode

1592</h5>1594</h5>

1593 1595

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

1595 1597

1596| 字段 | 类型 | 示例 | 描述 |1598| 字段 | 类型 | 示例 | 描述 |

1597| :--------------- | :----- | :------------------------------------------ | :------------------------------------------------------- |1599| :--------------- | :----- | :------------------------------------------ | :-------------------------------------------------------------------------------------------- |

1600| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | 可选。Claude 请求实现计划的基于提示的权限，每个都有 `tool` 名称和描述操作类别的 `prompt` |1602| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | {/* min-version: 2.1.205 */}已弃用。Claude Code 接受该字段但忽略它。在 v2.1.205 之前，它携带 Claude 请求实现计划的基于提示的权限 |

1601 1603

1602在 `PostToolUse` 中，`tool_response` 是一个对象，具有 `plan` 和 `filePath` 字段，保存批准的计划，加上内部状态标志。读取 `tool_response.plan` 以获取计划内容，而不是从磁盘重新读取文件。1604在 `PostToolUse` 中，`tool_response` 是一个对象，具有 `plan` 和 `filePath` 字段，保存批准的计划，加上内部状态标志。读取 `tool_response.plan` 以获取计划内容，而不是从磁盘重新读取文件。

1603 1605

1756`updatedPermissions` 输出字段和[`permission_suggestions` 输入字段](#permissionrequest-input)都使用相同的条目对象数组。每个条目都有一个 `type` 来确定其其他字段，以及一个 `destination` 来控制更改的写入位置。1758`updatedPermissions` 输出字段和[`permission_suggestions` 输入字段](#permissionrequest-input)都使用相同的条目对象数组。每个条目都有一个 `type` 来确定其其他字段，以及一个 `destination` 来控制更改的写入位置。

1757 1759

1758| `type` | 字段 | 效果 |1760| `type` | 字段 | 效果 |

1759| :------------------ | :------------------------------- | :------------------------------------------------------------------------------------------------------------------- |1761| :------------------ | :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1760| `addRules` | `rules`、`behavior`、`destination` | 添加权限规则。`rules` 是 `{toolName, ruleContent?}` 对象的数组。省略 `ruleContent` 以匹配整个工具。`behavior` 是 `"allow"`、`"deny"` 或 `"ask"` |1762| `addRules` | `rules`、`behavior`、`destination` | 添加权限规则。`rules` 是 `{toolName, ruleContent?}` 对象的数组。省略 `ruleContent` 以匹配整个工具。`behavior` 是 `"allow"`、`"deny"` 或 `"ask"` |

1763| `setMode` | `mode`、`destination` | 更改权限模式。有效模式为 `default`、`auto`、`acceptEdits`、`dontAsk`、`bypassPermissions` 和 `plan` |1765| `setMode` | `mode`、`destination` | 更改权限模式。有效模式为 `default`、`auto`、`acceptEdits`、`dontAsk`、`bypassPermissions`、`plan` 和 {/* min-version: 2.1.200 */}`manual` 作为 `default` 的别名。`manual` 别名需要 Claude Code v2.1.200 或更高版本 |

1766 1768

2650 2652

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

2652 2654

2653Hook 必须返回创建的 worktree 目录的绝对路径。Claude Code 使用此路径作为隔离会话的工作目录。命令 hooks 在 stdout 上打印它；HTTP hooks 通过 `hookSpecificOutput.worktreePath` 返回它。2655Hook 必须返回创建的 worktree 目录的绝对路径。Claude Code 使用此路径作为隔离会话的工作目录。请参阅[WorktreeCreate 输出](#worktreecreate-output)了解每个 hook 类型如何返回路径。

2654 2656

2655此示例创建 SVN 工作副本并打印路径供 Claude Code 使用。用您自己的替换仓库 URL：2657此示例创建 SVN 工作副本并打印路径供 Claude Code 使用。用您自己的替换仓库 URL：

2656 2658

2695 2697

2696WorktreeCreate hooks 不使用标准的允许/阻止决定模型。相反，hook 的成功或失败决定结果。Hook 必须返回创建的 worktree 目录的绝对路径：2698WorktreeCreate hooks 不使用标准的允许/阻止决定模型。相反，hook 的成功或失败决定结果。Hook 必须返回创建的 worktree 目录的绝对路径：

2697 2699

2698* **命令 hooks**（`type: "command"`）：在 stdout 上打印路径。2700* **命令 hooks**（`type: "command"`）：在 stdout 上打印路径作为最后一个非空行。Claude Code 在读取该行之前剥离 ANSI 转义代码，因此在您的 `echo` 之前打印的 shell 启动横幅被忽略。将任何其他 hook 输出重定向到 stderr。

2699* **HTTP hooks**（`type: "http"`）：在响应体中返回 `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }`。2701* **HTTP hooks**（`type: "http"`）：在响应体中返回 `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }`。

2700 2702

2701如果 hook 失败或不产生路径，worktree 创建失败并出现错误。2703如果 hook 失败或不产生路径，worktree 创建失败并出现错误。

2702 2704

2705Claude Code 根据 hook 运行的目录解析相对路径。如果生成的路径不是 Claude Code 可以进入的目录，会话打印一个错误，命名路径并以代码 1 退出。在 v2.1.205 之前，相对路径或磁盘上不存在的路径会在启动时使会话崩溃，使用 `-p` 时会停滞约 30 秒，然后以代码 0 退出。

2706

2703<h3 id="worktreeremove">2707<h3 id="worktreeremove">

2704 WorktreeRemove2708 WorktreeRemove

2705</h3>2709</h3>

3221 3225

3222后台进程退出后，如果 hook 产生了带有 `additionalContext` 字段的 JSON 响应，该内容在下一个对话轮次作为上下文传递给 Claude。`systemMessage` 字段显示给你，而不是 Claude。3226后台进程退出后，如果 hook 产生了带有 `additionalContext` 字段的 JSON 响应，该内容在下一个对话轮次作为上下文传递给 Claude。`systemMessage` 字段显示给你，而不是 Claude。

3223 3227

3228Claude Code 根据与同步 hooks 相同的[输出架构](#json-output)验证 JSON 响应，并删除任何值类型错误的字段，例如不是字符串的 `systemMessage`，而不是传递它。使用 `--debug` 运行以查看命名每个删除字段的警告。在 v2.1.202 之前，来自异步 hook 的格式错误的 JSON 输出可能会导致会话崩溃，并且每次恢复会话时崩溃都会重复发生。

3229

3224异步 hook 完成通知默认被抑制。要查看它们，请使用 `Ctrl+O` 启用详细模式或使用 `--verbose` 启动 Claude Code。3230异步 hook 完成通知默认被抑制。要查看它们，请使用 `Ctrl+O` 启用详细模式或使用 `--verbose` 启动 Claude Code。

3225 3231

3226<h3 id="run-tests-after-file-changes">3232<h3 id="run-tests-after-file-changes">

how-claude-code-works.md +5 −5

Details

186 186

187按 `Shift+Tab` 循环通过权限模式：187按 `Shift+Tab` 循环通过权限模式：

188 188

189* **Default**：Claude 在文件编辑和 shell 命令之前询问189* **Manual**：Claude 在文件编辑和 shell 命令之前询问

190* **Auto-accept edits**：Claude 编辑文件并运行常见的文件系统命令（如 `mkdir` 和 `mv`）而不询问，仍然询问其他命令190* **Accept edits**：Claude 编辑文件并运行常见的文件系统命令（如 `mkdir` 和 `mv`）而不询问，仍然询问其他命令

191* **Plan Mode**：Claude 探索并提出计划而不编辑您的源文件；权限提示仍然适用，如默认模式191* **Plan**：Claude 探索并提出计划而不编辑您的源文件；权限提示仍然适用，如 Manual 模式

192* **Auto mode**：Claude 使用后台安全检查评估所有操作。目前是研究预览192* **Auto**：Claude 使用后台安全检查评估所有操作。目前是研究预览

193 193

194您也可以在 `.claude/settings.json` 中允许特定命令，以便 Claude 不会每次都询问。这对于受信任的命令（如 `npm test` 或 `git status`）很有用。设置可以从组织范围的策略范围到个人偏好。有关详细信息，请参阅[权限](/zh-CN/permissions)。194您也可以在 `.claude/settings.json` 中允许特定命令，以便 Claude 不会每次都询问。这对于受信任的命令（如 `npm test` 或 `git status`）很有用。设置可以从组织范围的策略范围到个人偏好。有关详细信息，请参阅[权限](/zh-CN/permissions)。

195 195

210内置命令也会指导您完成设置：210内置命令也会指导您完成设置：

211 211

212* `/init` 引导您为项目创建 CLAUDE.md212* `/init` 引导您为项目创建 CLAUDE.md

213* `/doctor` 诊断您的安装的常见问题213* `/doctor` 运行设置检查，诊断安装和配置问题，并可以修复它们

214 214

215<h3 id="it’s-a-conversation">215<h3 id="it’s-a-conversation">

216 这是一个对话216 这是一个对话

interactive-mode.md +5 −3

Details

27</h3>27</h3>

28 28

29| 快捷键 | 描述 | 上下文 |29| 快捷键 | 描述 | 上下文 |

30| :------------------------------------------------- | :------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |30| :------------------------------------------------- | :------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |

42| `Up/Down arrows` 或 `Ctrl+P`/`Ctrl+N` | 移动光标或导航命令历史 | 当输入跨越多个可视行时，无论是换行还是多行，首先在提示内移动光标。一旦光标在第一行或最后一行，再次按下会导航命令历史。{/* min-version: 2.1.169 */}从 v2.1.169 开始，换行的单行输入的行为与多行输入相同 |42| `Up/Down arrows` 或 `Ctrl+P`/`Ctrl+N` | 移动光标或导航命令历史 | 当输入跨越多个可视行时，无论是换行还是多行，首先在提示内移动光标。一旦光标在第一行或最后一行，再次按下会导航命令历史。{/* min-version: 2.1.169 */}从 v2.1.169 开始，换行的单行输入的行为与多行输入相同 |

43| `Esc` | 中断 Claude | 停止当前响应或工具调用中途，以便您可以重定向。Claude 保留迄今为止完成的工作 |43| `Esc` | 中断 Claude，或关闭对话框 | 停止当前响应或工具调用中途，以便您可以重定向。Claude 保留迄今为止完成的工作。当权限提示等对话框打开时，`Esc` 关闭对话框而不是中断 Claude。{/* min-version: 2.1.202 */}在 v2.1.202 之前，某些对话框上的 `Esc` 会中断 Claude 并保持对话框打开 |

47| `Option+T`（macOS）或 `Alt+T`（Windows/Linux） | 切换扩展思考 | 启用或禁用扩展思考模式。对 Fable 5 无效，它始终使用扩展思考。{/* min-version: 2.1.132 */}从 v2.1.132 开始，此快捷键在 macOS 上无需配置 Option 作为 Meta 即可工作 |47| `Option+T`（macOS）或 `Alt+T`（Windows/Linux） | 切换扩展思考 | 启用或禁用扩展思考模式。对 Fable 5 无效，它始终使用扩展思考。{/* min-version: 2.1.132 */}从 v2.1.132 开始，此快捷键在 macOS 上无需配置 Option 作为 Meta 即可工作 |

270 270

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

272 272

273接受匹配或取消搜索会立即生效，即使 Claude Code 仍在加载历史记录。在 v2.1.202 之前，在加载期间接受或取消可能会报告内部错误。

274

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

274 后台 Bash 命令276 后台 Bash 命令

275</h2>277</h2>

keybindings.md +12 −13

Details

71| `Select` | 通用选择/列表组件 |71| `Select` | 通用选择/列表组件 |

72| `Plugin` | 插件对话框（浏览、发现、管理） |72| `Plugin` | 插件对话框（浏览、发现、管理） |

73| `Scroll` | 对话滚动和全屏模式下的文本选择 |73| `Scroll` | 对话滚动和全屏模式下的文本选择 |

~~74| `Doctor` | `/doctor` 诊断屏幕 |~~74

75{/* max-version: 2.1.204 */}在 v2.1.205 之前，`/doctor` 诊断屏幕存在 `Doctor` 上下文和 `doctor:fix` 操作。

75 76

76<h2 id="available-actions">77<h2 id="available-actions">

77 可用操作78 可用操作

358 359

359<h3 id="doctor-actions">

360 Doctor 操作

361</h3>

~~362~~

363在 `Doctor` 上下文中可用的操作：

~~364~~

365| 操作 | 默认 | 描述 |

366| :----------- | :- | :--------------------------------- |

367| `doctor:fix` | F | 将诊断报告发送给 Claude 以修复报告的问题。仅在发现问题时活跃 |

~~368~~

369<h3 id="voice-actions">360<h3 id="voice-actions">

370 语音操作361 语音操作

371</h3>362</h3>

477}468}

478```469```

479 470

480这也适用于和弦绑定。取消绑定共享前缀的每个和弦会释放该前缀以用作单键绑定：471这也适用于和弦绑定。取消绑定共享前缀的每个和弦会释放该前缀以用作单键绑定。任何活跃上下文中的和弦都会保留其前缀，因此您必须在定义该和弦的上下文中取消绑定每个和弦。

472

473默认的 `Ctrl+X` 系列跨越两个上下文：`Chat` 中的 `ctrl+x ctrl+k` 和 `ctrl+x ctrl+e`，以及 `Task` 中的 `ctrl+x ctrl+b`。要将 `ctrl+x` 本身回收为单键绑定，请取消绑定所有这些：

481 474

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

483{476{

484 "bindings": [477 "bindings": [

478 {

479 "context": "Task",

480 "bindings": {

481 "ctrl+x ctrl+b": null

482 }

483 },

485 {484 {

486 "context": "Chat",485 "context": "Chat",

487 "bindings": {486 "bindings": {

546* 终端多路复用器冲突545* 终端多路复用器冲突

547* 同一上下文中的重复绑定546* 同一上下文中的重复绑定

548 547

549运行 `/doctor` 查看任何快捷键警告。548Claude Code 在文件加载时报告警告，并将每个警告写入调试日志。使用 [`--debug`](/zh-CN/cli-reference#cli-flags) 启动 Claude Code 以查看详细信息。

legal-and-compliance.md +1 −1

Details

23 商业协议23 商业协议

24</h3>24</h3>

25 25

26无论您是直接使用 Claude API（1P）还是通过 Amazon Bedrock 或 Google Vertex（3P）访问，您现有的商业协议将适用于 Claude Code 的使用，除非我们已相互同意另行安排。26无论您是直接使用 Claude API（1P）还是通过 Amazon Bedrock 或 Google Cloud 的 Agent Platform（3P）访问，您现有的商业协议将适用于 Claude Code 的使用，除非我们已相互同意另行安排。

27 27

28<h2 id="compliance">28<h2 id="compliance">

29 合规29 合规

llm-gateway-connect.md +8 −6

Details

209 桌面应用209 桌面应用

210</h3>210</h3>

211 211

212桌面应用从[管理员分发的配置](https://claude.com/docs/cowork/3p/gateway)读取网关路由，而不是从 `ANTHROPIC_BASE_URL` 或 `settings.json` 读取。如果您的组织已分发它，桌面应用通过网关路由，无需您进行任何设置；如果没有，请使用终端 CLI 或 VS Code 扩展进行网关会话。管理员按照[组织推出](/zh-CN/llm-gateway-rollout#distribute-through-managed-settings)中所述分发配置。212桌面应用从[管理员分发的配置](https://claude.com/docs/third-party/claude-desktop/gateway)读取网关路由，而不是从 `ANTHROPIC_BASE_URL` 或 `settings.json` 读取。如果您的组织已分发它，桌面应用通过网关路由，无需您进行任何设置；如果没有，请使用终端 CLI 或 VS Code 扩展进行网关会话。管理员按照[组织推出](/zh-CN/llm-gateway-rollout#distribute-through-managed-settings)中所述分发配置。

213 213

214如果桌面应用显示 `Gateway was unreachable`，应用在启动时无法到达配置的基础 URL；使用上面的 [curl 测试](#verify-the-connection)检查 URL 和网络路径。214如果桌面应用显示 `Gateway was unreachable`，应用在启动时无法到达配置的基础 URL；使用上面的 [curl 测试](#verify-the-connection)检查 URL 和网络路径。

215 215

287 287

288[远程控制](/zh-CN/remote-control)和[语音听写](/zh-CN/voice-dictation)都依赖于 claude.ai 身份：远程控制将实时会话与您的账户配对，语音听写到达 claude.ai 转录端点。当 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 处于活动状态时，它们不可用。{/* min-version: 2.1.196 */}从 v2.1.196 开始，当 `ANTHROPIC_BASE_URL` 指向非 Anthropic 主机时，远程控制也被禁用，因此仅使用 claude.ai 登录是不够的。288[远程控制](/zh-CN/remote-control)和[语音听写](/zh-CN/voice-dictation)都依赖于 claude.ai 身份：远程控制将实时会话与您的账户配对，语音听写到达 claude.ai 转录端点。当 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 处于活动状态时，它们不可用。{/* min-version: 2.1.196 */}从 v2.1.196 开始，当 `ANTHROPIC_BASE_URL` 指向非 Anthropic 主机时，远程控制也被禁用，因此仅使用 claude.ai 登录是不够的。

289 289

290要恢复任一功能，请使用 claude.ai 登录并取消设置它检查的网关变量。`/doctor` 命名要取消设置的凭证变量。290要恢复任一功能，请使用 claude.ai 登录并取消设置它检查的网关变量。`claude doctor` 的远程控制部分命名要取消设置的凭证变量。

291 291

292* 语音听写：取消设置网关凭证292* 语音听写：取消设置网关凭证

293* 远程控制：取消设置网关凭证和 `ANTHROPIC_BASE_URL`293* 远程控制：取消设置网关凭证和 `ANTHROPIC_BASE_URL`

393 通过网关路由到云提供商393 通过网关路由到云提供商

394</h3>394</h3>

395 395

396这些配置使用提供商特定的基础 URL 变量代替 `ANTHROPIC_BASE_URL` 将 Claude Code 指向通过网关的云提供商。Bedrock 和 Agent Platform 网关接受这些提供商的本机请求格式；Foundry 和 AWS 上的 Claude Platform 网关接受 Anthropic Messages 格式，仅在哪个基础 URL 变量到达它们方面有所不同。396这些配置使用提供商特定的基础 URL 变量代替 `ANTHROPIC_BASE_URL` 将 Claude Code 指向通过网关的云提供商。Amazon Bedrock 和 Google Cloud 的 Agent Platform 网关接受这些提供商的本机请求格式；Microsoft Foundry 和 AWS 上的 Claude Platform 网关接受 Anthropic Messages 格式，仅在哪个基础 URL 变量到达它们方面有所不同。

397 397

398仅在您的网关团队特别命名 Bedrock、Agent Platform、Foundry 或 AWS 上的 Claude Platform 时使用一个。如果上面的[验证请求](#verify-the-connection)返回 JSON，您可以跳过本部分。398仅在您的网关团队特别命名 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 时使用一个。如果上面的[验证请求](#verify-the-connection)返回 JSON，您可以跳过本部分。

399 399

400为您的网关团队命名的提供商设置块。跳过身份验证变量告诉 Claude Code 不要使用提供商凭证签署请求，因为网关持有这些。如果网关需要自己的令牌，请在块后添加 `ANTHROPIC_AUTH_TOKEN`，除了 Foundry，它使用 `ANTHROPIC_FOUNDRY_API_KEY`，如所示。400为您的网关团队命名的提供商设置块。跳过身份验证变量告诉 Claude Code 不要使用提供商凭证签署请求，因为网关持有这些。如果网关需要自己的令牌，请在块后添加 `ANTHROPIC_AUTH_TOKEN`，除了 Microsoft Foundry，它使用 `ANTHROPIC_FOUNDRY_API_KEY`，如所示。{/* min-version: 2.1.203 */}期望持有者令牌的 Microsoft Foundry 网关可以改用 [`ANTHROPIC_FOUNDRY_AUTH_TOKEN`](/zh-CN/env-vars)；当两者都设置时，它优先于 `ANTHROPIC_FOUNDRY_API_KEY`。`ANTHROPIC_FOUNDRY_AUTH_TOKEN` 需要 Claude Code v2.1.203 或更高版本。

401 401

402<h4 id="amazon-bedrock">402<h4 id="amazon-bedrock">

403 Amazon Bedrock403 Amazon Bedrock

451 Microsoft Foundry451 Microsoft Foundry

452</h4>452</h4>

453 453

454将网关的凭证放在 `ANTHROPIC_FOUNDRY_API_KEY` 中；它作为 `x-api-key` 标头发送到网关。`CLAUDE_CODE_SKIP_FOUNDRY_AUTH` 在这里不适用：没有 API 密钥，Foundry 客户端在它离开机器之前会使每个请求失败。454将网关的凭证放在 `ANTHROPIC_FOUNDRY_API_KEY` 中；它作为 `x-api-key` 标头发送到网关。{/* min-version: 2.1.203 */}期望持有者令牌的网关可以改用 [`ANTHROPIC_FOUNDRY_AUTH_TOKEN`](/zh-CN/env-vars)。Claude Code 将该值作为 `Authorization: Bearer` 标头发送，当两者都设置时，它优先于 `ANTHROPIC_FOUNDRY_API_KEY`。需要 Claude Code v2.1.203 或更高版本。

455

456对于注入自己的 `Authorization` 标头的网关，设置 `CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1` 并将两个凭证变量都保留为未设置。Claude Code 然后发送没有 Azure 凭证的请求，并保留您提供的 `Authorization` 标头，例如通过 `ANTHROPIC_CUSTOM_HEADERS`。{/* min-version: 2.1.203 */}在 v2.1.203 之前，`CLAUDE_CODE_SKIP_FOUNDRY_AUTH` 没有 API 密钥会使 Microsoft Foundry 客户端无法发送请求。

455 457

456<Tabs>458<Tabs>

457 <Tab title="Bash or Zsh">459 <Tab title="Bash or Zsh">

llm-gateway-protocol.md +13 −13

Details

34 API 格式34 API 格式

35</h2>35</h2>

36 36

37gateway 必须向 Claude Code 客户端公开以下至少一种 API 格式。Claude Code 使用哪种格式由客户端的配置决定：下表"选择者"列中的变量指向您的 gateway 使用该格式。Agent Platform 是 Google Cloud 的 Claude 端点，原名 Vertex AI；其变量名保留 `VERTEX` 拼写。37gateway 必须向 Claude Code 客户端公开以下至少一种 API 格式。Claude Code 使用哪种格式由客户端的配置决定：下表"选择者"列中的变量指向您的 gateway 使用该格式。Google Cloud 的 Agent Platform 是 Google Cloud 的 Claude 端点，原名 Vertex AI；其变量名保留 `VERTEX` 拼写。

38 38

39| 格式 | 选择者 | 端点 | 转发不变 |39| 格式 | 选择者 | 端点 | 转发不变 |

40| :------------------------ | :---------------------------------------------------------- | :------------------------------------------------------------------- | :---------------------------------------------------------------------- |40| :--------------------------------------- | :---------------------------------------------------------- | :------------------------------------------------------------------- | :---------------------------------------------------------------------- |

42| Bedrock InvokeModel | `ANTHROPIC_BEDROCK_BASE_URL` 配合 `CLAUDE_CODE_USE_BEDROCK=1` | `/model/{model}/invoke`、`/model/{model}/invoke-with-response-stream` | `anthropic_beta` 和 `anthropic_version` 请求体字段 |42| Amazon Bedrock InvokeModel | `ANTHROPIC_BEDROCK_BASE_URL` 配合 `CLAUDE_CODE_USE_BEDROCK=1` | `/model/{model}/invoke`、`/model/{model}/invoke-with-response-stream` | `anthropic_beta` 和 `anthropic_version` 请求体字段 |

43| Agent Platform rawPredict | `ANTHROPIC_VERTEX_BASE_URL` 配合 `CLAUDE_CODE_USE_VERTEX=1` | `:rawPredict`、`:streamRawPredict`、`count-tokens:rawPredict`（可选） | `anthropic-beta` 和 `anthropic-version` 请求头，以及 `anthropic_version` 请求体字段 |43| Google Cloud 的 Agent Platform rawPredict | `ANTHROPIC_VERTEX_BASE_URL` 配合 `CLAUDE_CODE_USE_VERTEX=1` | `:rawPredict`、`:streamRawPredict`、`count-tokens:rawPredict`（可选） | `anthropic-beta` 和 `anthropic-version` 请求头，以及 `anthropic_version` 请求体字段 |

44 44

45<h3 id="foundry-and-claude-platform-on-aws">45<h3 id="foundry-and-claude-platform-on-aws">

46 Foundry 和 AWS 上的 Claude Platform46 Foundry 和 AWS 上的 Claude Platform

52 可选端点和启动流量52 可选端点和启动流量

53</h3>53</h3>

54 54

55令牌计数端点是唯一可选的：当它们不存在时，Claude Code 在本地估计上下文使用情况。推理请求发送到 `/v1/messages?beta=true`，因此请匹配路径，而不是完整 URL。Agent Platform 方法后缀附加到发布者模型路径，如 `/projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict`。55令牌计数端点是唯一可选的：当它们不存在时，Claude Code 在本地估计上下文使用情况。推理请求发送到 `/v1/messages?beta=true`，因此请匹配路径，而不是完整 URL。Google Cloud 的 Agent Platform 方法后缀附加到发布者模型路径，如 `/projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict`。

56 56

57gateway 还会看到尽力而为的启动流量，它可以拒绝而不会破坏任何东西：一个 `HEAD /` 连接探针，以及在 Bedrock 格式 gateway 上的 `GET /inference-profiles?type=SYSTEM_DEFINED` 请求。57gateway 还会看到尽力而为的启动流量，它可以拒绝而不会破坏任何东西：一个 `HEAD /` 连接探针，以及在 Amazon Bedrock 格式 gateway 上的 `GET /inference-profiles?type=SYSTEM_DEFINED` 请求。

58 58

59<h3 id="streaming">59<h3 id="streaming">

60 流式传输60 流式传输

68 68

69客户端使用的格式决定了您的 gateway 接收的内容。常见的失败模式是客户端发送到您的 gateway 的格式与上游提供商接受的格式之间的不匹配。69客户端使用的格式决定了您的 gateway 接收的内容。常见的失败模式是客户端发送到您的 gateway 的格式与上游提供商接受的格式之间的不匹配。

70 70

~~71* 当客户端使用 Bedrock 或 Agent Platform 格式时，Claude Code 仅发送这些提供商接受的完整功能集的子集~~71* 当客户端使用 Amazon Bedrock 或 Google Cloud 的 Agent Platform 格式时，Claude Code 仅发送这些提供商接受的完整功能集的子集

~~72* 当客户端使用 Anthropic Messages 格式时，Claude Code 发送完整集合，即使您的 gateway 转发到 Bedrock 或 Agent Platform 上游~~72* 当客户端使用 Anthropic Messages 格式时，Claude Code 发送完整集合，即使您的 gateway 转发到 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上游

73 73

74弥合这种差异是您的 gateway 的工作。[功能传递](#feature-pass-through)描述了当它不这样做时会破坏什么。74弥合这种差异是您的 gateway 的工作。[功能传递](#feature-pass-through)描述了当它不这样做时会破坏什么。

75 75

82| 请求头 | 描述 |82| 请求头 | 描述 |

83| :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |83| :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

84| `Authorization`、`x-api-key` | 开发者的 gateway 凭证，根据他们设置的[凭证变量](/zh-CN/llm-gateway-connect#set-the-credential-variable)在一个或两个请求头中 |84| `Authorization`、`x-api-key` | 开发者的 gateway 凭证，根据他们设置的[凭证变量](/zh-CN/llm-gateway-connect#set-the-credential-variable)在一个或两个请求头中 |

85| `anthropic-version` | API 版本，目前为 `2023-06-01`。Bedrock 和 Agent Platform 格式请求也携带 `anthropic_version` 请求体字段，其值是提供商方言字符串，而不是此请求头的值 |85| `anthropic-version` | API 版本，目前为 `2023-06-01`。Amazon Bedrock 和 Google Cloud 的 Agent Platform 格式请求也携带 `anthropic_version` 请求体字段，其值是提供商方言字符串，而不是此请求头的值 |

86| `anthropic-beta` | 请求的逗号分隔功能值。逐字转发请求头；不要将单个值列入白名单，因为该集合随 Claude Code 版本而变化。当开发者使用 claude.ai 登录进行身份验证时（当设置 `ANTHROPIC_BASE_URL` 而不设置 gateway 凭证变量时可能），此请求头还携带上游需要的 OAuth 功能，删除它会导致这些请求失败，返回 `401` |86| `anthropic-beta` | 请求的逗号分隔功能值。逐字转发请求头；不要将单个值列入白名单，因为该集合随 Claude Code 版本而变化。当开发者使用 claude.ai 登录进行身份验证时（当设置 `ANTHROPIC_BASE_URL` 而不设置 gateway 凭证变量时可能），此请求头还携带上游需要的 OAuth 功能，删除它会导致这些请求失败，返回 `401` |

100 100

101转发到 Anthropic 格式上游时，将 `anthropic-*` 请求头和请求体字段原封不动地传递，而不是将您今天看到的列入白名单。固定到观察列表的 gateway 会删除下一个功能的请求头或字段，并在引入它的版本上破坏它。101转发到 Anthropic 格式上游时，将 `anthropic-*` 请求头和请求体字段原封不动地传递，而不是将您今天看到的列入白名单。固定到观察列表的 gateway 会删除下一个功能的请求头或字段，并在引入它的版本上破坏它。

102 102

103例外是非 Anthropic 上游，如 Bedrock 或 Agent Platform，其中弥合架构差异是 gateway 的工作；请参阅[功能传递](#feature-pass-through)。103例外是非 Anthropic 上游，如 Amazon Bedrock 或 Google Cloud 的 Agent Platform，其中弥合架构差异是 gateway 的工作；请参阅[功能传递](#feature-pass-through)。

104 104

105<h2 id="system-prompt-attribution-block">105<h2 id="system-prompt-attribution-block">

106 系统提示归属块106 系统提示归属块

129细粒度工具流式传输是直接连接默认值之一：每当请求通过自定义基础 URL 路由时，它默认关闭，当开发者设置 [`CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1`](/zh-CN/env-vars) 时，gateway 会接收它。129细粒度工具流式传输是直接连接默认值之一：每当请求通过自定义基础 URL 路由时，它默认关闭，当开发者设置 [`CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1`](/zh-CN/env-vars) 时，gateway 会接收它。

130 130

131| 功能 | 请求头和请求体对 | 破坏时的症状 | 补救 |131| 功能 | 请求头和请求体对 | 破坏时的症状 | 补救 |

132| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------- |132| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------- |

133| [自适应推理](/zh-CN/model-config#adjust-effort-level) | 无 beta 请求头。Claude Code 为 Claude 4.6 及更高版本发送 `thinking: {"type": "adaptive"}`，并将它不识别的模型名称（如 gateway 别名）视为接收该字段的当前模型 | 当上游模型构建不接受它时，命名 `thinking` 字段或 `adaptive` 标签的 `400` | 升级上游。在 Opus 4.6 和 Sonnet 4.6 上，开发者可以改为设置 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` |133| [自适应推理](/zh-CN/model-config#adjust-effort-level) | 无 beta 请求头。Claude Code 为 Claude 4.6 及更高版本发送 `thinking: {"type": "adaptive"}`，并将它不识别的模型名称（如 gateway 别名）视为接收该字段的当前模型 | 当上游模型构建不接受它时，命名 `thinking` 字段或 `adaptive` 标签的 `400` | 升级上游。在 Opus 4.6 和 Sonnet 4.6 上，开发者可以改为设置 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` |

134| [上下文管理](https://platform.claude.com/docs/en/build-with-claude/context-management) | 上下文管理 beta 请求头与 `context_management` 请求体字段配对 | `400` 带有 `Extra inputs are not permitted`。常见于 gateway 接受 Anthropic 格式请求但将其转发到 Bedrock 时 | 转发两者，或 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/zh-CN/env-vars) |134| [上下文管理](https://platform.claude.com/docs/en/build-with-claude/context-management) | 上下文管理 beta 请求头与 `context_management` 请求体字段配对 | `400` 带有 `Extra inputs are not permitted`。常见于 gateway 接受 Anthropic 格式请求但将其转发到 Amazon Bedrock 时 | 转发两者，或 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/zh-CN/env-vars) |

135| [扩展上下文](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)和[交错思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) | 仅 Beta 请求头，无请求体字段 | 当请求头被删除时无声地不可用；上游永远不会看到功能请求 | 逐字转发 `anthropic-beta` |135| [扩展上下文](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)和[交错思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) | 仅 Beta 请求头，无请求体字段 | 当请求头被删除时无声地不可用；上游永远不会看到功能请求 | 逐字转发 `anthropic-beta` |

136| Beta [工具字段](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | 工具相关的 beta 请求头与工具架构字段（如 `strict` 和 `defer_loading`）配对 | 当请求体通过而没有其请求头时，命名无法识别的工具架构字段的 `400` | 转发两者，或 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` |136| Beta [工具字段](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | 工具相关的 beta 请求头与工具架构字段（如 `strict` 和 `defer_loading`）配对 | 当请求体通过而没有其请求头时，命名无法识别的工具架构字段的 `400` | 转发两者，或 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` |

137| [努力](https://platform.claude.com/docs/en/build-with-claude/effort)和[结构化输出](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | `output_config` 请求体字段携带努力、结构化输出格式和任务预算设置；每个都与自己的 beta 请求头配对 | 在 Bedrock 和 Agent Platform 上游上命名 `output_config` 的 `400`，通常是 `Extra inputs are not permitted` | 一起转发字段及其请求头 |137| [努力](https://platform.claude.com/docs/en/build-with-claude/effort)和[结构化输出](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | `output_config` 请求体字段携带努力、结构化输出格式和任务预算设置；每个都与自己的 beta 请求头配对 | 在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上游上命名 `output_config` 的 `400`，通常是 `Extra inputs are not permitted` | 一起转发字段及其请求头 |

139 139

140`ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES` [变量](/zh-CN/model-config)仅在提供商配置中声明模型功能：`CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY` 和 [`CLAUDE_CODE_USE_MANTLE`](/zh-CN/amazon-bedrock#use-the-mantle-endpoint)。它们在 `ANTHROPIC_BASE_URL` gateway 后面没有效果。140`ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES` [变量](/zh-CN/model-config)仅在提供商配置中声明模型功能：`CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY` 和 [`CLAUDE_CODE_USE_MANTLE`](/zh-CN/amazon-bedrock#use-the-mantle-endpoint)。它们在 `ANTHROPIC_BASE_URL` gateway 后面没有效果。

llm-gateway-rollout.md +4 −4

Details

180无论您选择哪条路径，都适用相同的变量集。大多数推出只需要 `ANTHROPIC_BASE_URL` 和凭证；当您的网关设置需要时包括条件行。180无论您选择哪条路径，都适用相同的变量集。大多数推出只需要 `ANTHROPIC_BASE_URL` 和凭证；当您的网关设置需要时包括条件行。

181 181

183| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |183| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

184| `ANTHROPIC_BASE_URL` | 将 Claude Code 的 API 请求发送到网关而不是 `api.anthropic.com` | 总是 |184| `ANTHROPIC_BASE_URL` | 将 Claude Code 的 API 请求发送到网关而不是 `api.anthropic.com` | 总是 |

188| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 停止 Claude Code 发送预发布功能标头和正文字段 | 您的网关转发到拒绝 beta 字段的 Bedrock 或 Agent Platform 上游；请参阅[网关要求](#gateway-requirements) |188| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 停止 Claude Code 发送预发布功能标头和正文字段 | 您的网关转发到拒绝 beta 字段的 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上游；请参阅[网关要求](#gateway-requirements) |

189| `ANTHROPIC_MODEL` 或 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/zh-CN/model-config) | 设置 Claude Code 为主会话和后台流量请求的模型名称 | 您的网关路由与 Claude Code 默认值不匹配的模型名称，或您将[后台功能](/zh-CN/costs#background-token-usage)路由到不同的模型。在网关处路由覆盖名称和 Claude Code 的默认名称，因为某些子调用可以请求默认名称，无论覆盖如何；[模型配置](/zh-CN/model-config)涵盖了会话的每个部分使用哪个模型 |189| `ANTHROPIC_MODEL` 或 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/zh-CN/model-config) | 设置 Claude Code 为主会话和后台流量请求的模型名称 | 您的网关路由与 Claude Code 默认值不匹配的模型名称，或您将[后台功能](/zh-CN/costs#background-token-usage)路由到不同的模型。在网关处路由覆盖名称和 Claude Code 的默认名称，因为某些子调用可以请求默认名称，无论覆盖如何；[模型配置](/zh-CN/model-config)涵盖了会话的每个部分使用哪个模型 |

190| `ANTHROPIC_BEDROCK_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL`、`ANTHROPIC_FOUNDRY_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 以及[该提供商的变量](/zh-CN/llm-gateway-connect#route-to-a-cloud-provider-through-a-gateway) | 通过网关将 Claude Code 指向网关。Bedrock 和 Agent Platform 也切换到这些提供商的本机请求格式 | 您的网关前置 Bedrock、Agent Platform、Foundry 或 AWS 上的 Claude 平台；请参阅 [API 格式](/zh-CN/llm-gateway-protocol#api-formats) |190| `ANTHROPIC_BEDROCK_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL`、`ANTHROPIC_FOUNDRY_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 以及[该提供商的变量](/zh-CN/llm-gateway-connect#route-to-a-cloud-provider-through-a-gateway) | 通过网关将 Claude Code 指向网关。Amazon Bedrock 和 Google Cloud 的 Agent Platform 也切换到这些提供商的本机请求格式 | 您的网关前置 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude 平台；请参阅 [API 格式](/zh-CN/llm-gateway-protocol#api-formats) |

191 191

192<h4 id="distribute-through-managed-settings">192<h4 id="distribute-through-managed-settings">

193 通过托管设置分发193 通过托管设置分发

214 214

215某些环境需要单独的交付：215某些环境需要单独的交付：

216 216

217* 桌面应用仅从其 MDM 交付的第三方推理配置读取网关路由；部署该文件以及托管设置，以便桌面会话也通过网关路由。请参阅[桌面第三方配置文档](https://claude.com/docs/cowork/3p/configuration)和[桌面网关文档](https://claude.com/docs/cowork/3p/gateway)217* 桌面应用仅从其 MDM 交付的第三方推理配置读取网关路由；部署该文件以及托管设置，以便桌面会话也通过网关路由。请参阅[桌面第三方配置文档](https://claude.com/docs/third-party/claude-desktop/configuration)和[桌面网关文档](https://claude.com/docs/third-party/claude-desktop/gateway)

218* CI 运行器需要在[运行器的环境](/zh-CN/llm-gateway-connect#configure-each-surface)中设置 `ANTHROPIC_BASE_URL` 和凭证218* CI 运行器需要在[运行器的环境](/zh-CN/llm-gateway-connect#configure-each-surface)中设置 `ANTHROPIC_BASE_URL` 和凭证

219* 托管 Windows 机器上的 WSL 仅在 [`wslInheritsWindowsSettings`](/zh-CN/settings#available-settings) 为 `true` 时读取 Windows 托管设置219* 托管 Windows 机器上的 WSL 仅在 [`wslInheritsWindowsSettings`](/zh-CN/settings#available-settings) 为 `true` 时读取 Windows 托管设置

220 220

mcp.md +34 −15

Details

85 85

86在通过 `.mcp.json`、`~/.claude.json` 或 `claude mcp add-json` 中的 JSON 配置 MCP 服务器时，`type` 字段接受 `streamable-http` 作为 `http` 的别名。MCP 规范对此传输使用名称 `streamable-http`，因此从服务器文档复制的配置无需修改即可工作。86在通过 `.mcp.json`、`~/.claude.json` 或 `claude mcp add-json` 中的 JSON 配置 MCP 服务器时，`type` 字段接受 `streamable-http` 作为 `http` 的别名。MCP 规范对此传输使用名称 `streamable-http`，因此从服务器文档复制的配置无需修改即可工作。

87 87

88没有 `type` 但有 `url` 的 JSON 条目是配置错误，因为 Claude Code 将没有 `type` 的条目读取为 stdio 服务器。Claude Code 会跳过该服务器并报告 `MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry`。在 v2.1.202 之前，Claude Code 将此配置错误报告为 `command: expected string, received undefined`。

88<h3 id="option-2-add-a-remote-sse-server">90<h3 id="option-2-add-a-remote-sse-server">

89 选项 2：添加远程 SSE 服务器91 选项 2：添加远程 SSE 服务器

90</h3>92</h3>

111 113

112Stdio 服务器作为您机器上的本地进程运行。它们非常适合需要直接系统访问或自定义脚本的工具。114Stdio 服务器作为您机器上的本地进程运行。它们非常适合需要直接系统访问或自定义脚本的工具。

113 115

114Claude Code 在生成的服务器的环境中设置 `CLAUDE_PROJECT_DIR`，指向项目根目录，因此您的服务器可以解析项目相对路径，而无需依赖工作目录。这与 hooks 在其 `CLAUDE_PROJECT_DIR` 变量中接收的目录相同。从服务器进程内部读取它，例如 Node 中的 `process.env.CLAUDE_PROJECT_DIR` 或 Python 中的 `os.environ["CLAUDE_PROJECT_DIR"]`。您的服务器也可以调用 MCP `roots/list` 请求，该请求返回启动 Claude Code 的目录。116Claude Code 在生成的服务器的环境中设置 `CLAUDE_PROJECT_DIR`，指向项目根目录，因此您的服务器可以解析项目相对路径，而无需依赖工作目录。这与 hooks 在其 `CLAUDE_PROJECT_DIR` 变量中接收的目录相同。从服务器进程内部读取它，例如 Node 中的 `process.env.CLAUDE_PROJECT_DIR` 或 Python 中的 `os.environ["CLAUDE_PROJECT_DIR"]`。

117

118`CLAUDE_PROJECT_DIR` 是稳定的项目根目录，在会话中途添加或删除工作目录时不会改变。限制自己的文件系统访问到一组允许目录的服务器应该改为实现 MCP `roots/list` 请求。Claude Code 使用会话的启动目录加上您通过 `--add-dir`、`/add-dir` 或 `additionalDirectories` 设置授予的每个[额外工作目录](/zh-CN/permissions#working-directories)来回答 `roots/list`。当该集合改变时，Claude Code 发送 `notifications/roots/list_changed`。在 v2.1.203 之前，`roots/list` 仅返回启动目录，Claude Code 不发送 `notifications/roots/list_changed`。

115 119

116此变量在服务器的环境中设置，而不是在 Claude Code 自己的环境中，因此在项目或用户范围的 `.mcp.json` `command` 或 `args` 中通过 `${VAR}` 扩展引用它需要一个默认值，例如 `${CLAUDE_PROJECT_DIR:-.}`。插件提供的 MCP 配置直接替换 `${CLAUDE_PROJECT_DIR}`，不需要默认值。120此变量在服务器的环境中设置，而不是在 Claude Code 自己的环境中，因此在项目或用户范围的 `.mcp.json` `command` 或 `args` 中通过 `${VAR}` 扩展引用它需要一个默认值，例如 `${CLAUDE_PROJECT_DIR:-.}`。插件提供的 MCP 配置直接替换 `${CLAUDE_PROJECT_DIR}`，不需要默认值。

117 121

189 193

190`/mcp` 面板在每个连接的服务器旁边显示工具计数，并标记声称工具功能但未公开任何工具的服务器。194`/mcp` 面板在每个连接的服务器旁边显示工具计数，并标记声称工具功能但未公开任何工具的服务器。

191 195

192如果您的请求需要来自仍在后台连接的服务器的工具，Claude 会在继续之前等待该服务器。启用[工具搜索](#scale-with-mcp-tool-search)（这是默认设置）后，等待发生在 `ToolSearch` 调用内部。在没有工具搜索的配置中，例如 Vertex AI、自定义 `ANTHROPIC_BASE_URL` 或 `ENABLE_TOOL_SEARCH=false`，Claude 改为使用 `WaitForMcpServers` 工具。196如果您的请求需要来自仍在后台连接的服务器的工具，Claude 会在继续之前等待该服务器。启用[工具搜索](#scale-with-mcp-tool-search)（这是默认设置）后，等待发生在 `ToolSearch` 调用内部。在没有工具搜索的配置中，例如 Google Cloud 的 Agent Platform、自定义 `ANTHROPIC_BASE_URL` 或 `ENABLE_TOOL_SEARCH=false`，Claude 改为使用 `WaitForMcpServers` 工具。

197

198某些服务器名称为 Claude Code 的内置服务器保留：`workspace`、`claude-in-chrome`、`computer-use`、`Claude Preview` 和 `Claude Browser`。如果您的配置定义了具有保留名称的服务器，Claude Code 会在加载时跳过它，并显示一条警告，要求您重命名它。`claude mcp add` 会以错误拒绝保留名称。

193 199

194服务器名称 `workspace` 保留供内部使用。如果您的配置定义了具有该名称的服务器，Claude Code 会在加载时跳过它，并显示一条警告，要求您重命名它。200`Claude Preview` 和 `Claude Browser` 都命名了 [Claude Code 桌面应用的预览窗格](/zh-CN/desktop#preview-your-app)使用的内置服务器。在 v2.1.205 之前，`Claude Browser` 不是保留的，因此用户配置的服务器可以在该名称下注册。

195 201

196<h3 id="dynamic-tool-updates">202<h3 id="dynamic-tool-updates">

197 动态工具更新203 动态工具更新

207 213

208相同的退避策略也适用于 HTTP 或 SSE 服务器在启动时初始连接失败的情况。从 v2.1.121 开始，Claude Code 在瞬时错误（如 5xx 响应、连接被拒绝或超时）上最多重试初始连接三次，如果仍然无法连接，则将服务器标记为失败。身份验证和未找到错误不会重试，因为它们需要配置更改才能解决。214相同的退避策略也适用于 HTTP 或 SSE 服务器在启动时初始连接失败的情况。从 v2.1.121 开始，Claude Code 在瞬时错误（如 5xx 响应、连接被拒绝或超时）上最多重试初始连接三次，如果仍然无法连接，则将服务器标记为失败。身份验证和未找到错误不会重试，因为它们需要配置更改才能解决。

209 215

216当配置的服务器无法连接时，Claude Code 告诉 Claude 哪个服务器失败及其连接错误，包括在 `ToolSearch` 结果中找不到匹配工具，因此 Claude 在其响应中报告连接失败。需要[工具搜索](#scale-with-mcp-tool-search)，默认启用。在没有工具搜索的配置中，例如自定义 `ANTHROPIC_BASE_URL`、`ENABLE_TOOL_SEARCH=false` 或 Haiku 模型，以及在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，Claude Code 不会向 Claude 报告失败的服务器连接。在 v2.1.205 之前，Claude Code 不会将连接错误传递给 Claude，Claude 可能会响应，就像失败的服务器的工具从未配置过一样。

217

210从 v2.1.191 开始，在成功连接后运行的功能发现请求（如 `tools/list`、`prompts/list` 和 `resources/list`）也会在短退避的情况下最多重试三次瞬时网络和服务器错误。身份验证错误、4xx 响应和请求超时不会重试。218从 v2.1.191 开始，在成功连接后运行的功能发现请求（如 `tools/list`、`prompts/list` 和 `resources/list`）也会在短退避的情况下最多重试三次瞬时网络和服务器错误。身份验证错误、4xx 响应和请求超时不会重试。

211 219

212<h3 id="push-messages-with-channels">220<h3 id="push-messages-with-channels">

218<Tip>226<Tip>

219 提示：227 提示：

220 228

221 * 使用 `--scope` 标志指定配置的存储位置：229 * 使用 `-s` 或 `--scope` 标志指定配置的存储位置：

222 * `local`（默认）：仅在当前项目中对您可用。较旧版本称此范围为 `project`230 * `local`（默认）：仅在当前项目中对您可用。较旧版本称此范围为 `project`

223 * `project`：通过 `.mcp.json` 文件与项目中的每个人共享231 * `project`：通过 `.mcp.json` 文件与项目中的每个人共享

224 * `user`：在所有项目中对您可用。较旧版本称此范围为 `global`232 * `user`：在所有项目中对您可用。较旧版本称此范围为 `global`

225 * 使用 `--env` 标志设置环境变量（例如，`--env KEY=value`）233 * 使用 `-e` 或 `--env` 标志设置环境变量（例如，`-e KEY=value`）

234 * `--transport` 和 `--header` 标志也接受 `-t` 和 `-H` 短形式

226 * 使用 `MCP_TIMEOUT` 环境变量配置 MCP 服务器启动超时（例如，`MCP_TIMEOUT=10000 claude` 设置 10 秒超时）235 * 使用 `MCP_TIMEOUT` 环境变量配置 MCP 服务器启动超时（例如，`MCP_TIMEOUT=10000 claude` 设置 10 秒超时）

227 * 通过向该服务器的 `.mcp.json` 条目添加 `timeout` 字段（以毫秒为单位）来设置每个服务器的工具执行超时，例如 `"timeout": 600000` 表示十分钟。这仅对该服务器覆盖 `MCP_TOOL_TIMEOUT` 环境变量236 * 通过向该服务器的 `.mcp.json` 条目添加 `timeout` 字段（以毫秒为单位）来设置每个服务器的工具执行超时，例如 `"timeout": 600000` 表示十分钟。这仅对该服务器覆盖 `MCP_TOOL_TIMEOUT` 环境变量

228 * 当 MCP 工具输出超过 10,000 个令牌时，Claude Code 将显示警告。要增加此限制，请设置 `MAX_MCP_OUTPUT_TOKENS` 环境变量（例如，`MAX_MCP_OUTPUT_TOKENS=50000`）237 * 当 MCP 工具输出超过 10,000 个令牌时，Claude Code 将显示警告。要增加此限制，请设置 `MAX_MCP_OUTPUT_TOKENS` 环境变量（例如，`MAX_MCP_OUTPUT_TOKENS=50000`）

229 * 使用 `/mcp` 对需要 OAuth 2.0 身份验证的远程服务器进行身份验证238 * 使用 `/mcp` 对需要 OAuth 2.0 身份验证的远程服务器进行身份验证

230</Tip>239</Tip>

231 240

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

242

243每个服务器至少 1000 的 `timeout` 也充当下面描述的空闲超时的下限：Claude Code 永远不会因为空闲而在每个服务器的 `timeout` 之前中止该服务器的工具调用。需要 Claude Code v2.1.203 或更高版本。

233 244

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

246

247对 MCP 服务器的工具调用如果在空闲窗口内没有发送响应和进度通知，将以错误中止，而不是等待时钟限制。空闲超时需要 Claude Code v2.1.187 或更高版本。{/* min-version: 2.1.203 */}它适用于除 IDE 服务器和 SDK 进程内服务器之外的每种服务器类型。空闲窗口对于 HTTP、SSE、WebSocket 和 [claude.ai connector](#use-mcp-servers-from-claude-ai) 服务器默认为五分钟，对于 stdio 服务器默认为 30 分钟。在 v2.1.203 之前，stdio 服务器不受空闲超时的限制。

248

249在毫秒中设置 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/zh-CN/env-vars) 环境变量以更改空闲窗口，或将其设置为 `0` 以禁用检查。

235 250

236<h3 id="plugin-provided-mcp-servers">251<h3 id="plugin-provided-mcp-servers">

237 插件提供的 MCP 服务器252 插件提供的 MCP 服务器

302mcp__plugin_my-plugin_database-tools__query317mcp__plugin_my-plugin_database-tools__query

303```318```

304 319

305在[权限规则](/zh-CN/permissions)中、技能的 `allowed-tools` 列表中或[子代理的 `tools` 字段](/zh-CN/sub-agents#available-tools)中引用工具时，使用此完整名称。320在[权限规则](/zh-CN/permissions)中、技能的 `allowed-tools` 列表中、[子代理的 `tools` 字段](/zh-CN/sub-agents#available-tools)中或[钩子匹配器](/zh-CN/hooks#match-mcp-tools)中引用工具时，使用此完整名称。针对裸服务器密钥（如 `mcp__database-tools__.*`）编写的钩子匹配器永远不会对插件捆绑的服务器触发。

321

322服务器本身在作用域名称 `plugin:<plugin-name>:<server-name>`（如 `plugin:my-plugin:database-tools`）下注册。在需要配置的服务器名称的地方使用该名称，例如[`mcp_tool` 钩子的 `server` 字段](/zh-CN/hooks#mcp-tool-hook-fields)。

306 323

307**插件 MCP 服务器的优势**：324**插件 MCP 服务器的优势**：

308 325

856 </Step>873 </Step>

857</Steps>874</Steps>

858 875

876通过 `claude mcp` 命令添加的服务器名称只能包含字母、数字、连字符和下划线。Claude Desktop 不应用该限制，因此名称中包含任何其他字符（如空格）的 Claude Desktop 服务器无法导入。导入会报告它拒绝的每个名称，并仍然导入您选择的其他服务器。在 v2.1.205 之前，第一个无效名称会停止导入，所选的服务器都不会被添加。

877

859<Tip>878<Tip>

860 提示：879 提示：

861 880

862 * 此功能仅在 macOS 和 Windows Subsystem for Linux (WSL) 上有效881 * 此功能仅在 macOS 和 Windows Subsystem for Linux (WSL) 上有效

863 * 它从这些平台上的标准位置读取 Claude Desktop 配置文件882 * 它从这些平台上的标准位置读取 Claude Desktop 配置文件

864 * 使用 `--scope user` 标志将服务器添加到您的用户配置883 * 使用 `--scope user` 标志将服务器添加到您的用户配置

865 * 导入的服务器将具有与 Claude Desktop 中相同的名称884 * 导入的服务器将保持与 Claude Desktop 中相同的名称，当名称仅包含字母、数字、连字符和下划线时。Claude Code 会报告名称中包含任何其他字符的服务器并跳过它

866 * 如果具有相同名称的服务器已存在，它们将获得数字后缀（例如，`server_1`）885 * 如果具有相同名称的服务器已存在，它们将获得数字后缀（例如，`server_1`）

867</Tip>886</Tip>

868 887

894 913

895从 v2.1.161 开始，您从未登录过的连接器会折叠在 claude.ai 部分末尾的 `Show unused connectors` 行后面，因此组织预配的列表不会填满面板。选择该行以展开它们。您之前登录过的连接器即使当前需要重新身份验证，也会保持可见。914从 v2.1.161 开始，您从未登录过的连接器会折叠在 claude.ai 部分末尾的 `Show unused connectors` 行后面，因此组织预配的列表不会填满面板。选择该行以展开它们。您之前登录过的连接器即使当前需要重新身份验证，也会保持可见。

896 915

897Claude.ai 连接器仅在您的活跃[身份验证方法](/zh-CN/authentication#authentication-precedence)是您的 Claude.ai 订阅时才会被获取。当 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`apiKeyHelper` 或第三方提供商（如 Bedrock 或 Vertex）处于活跃状态时，它们不会被加载，即使您之前运行过 `/login`。如果 `/mcp` 未列出您添加的连接器，请运行 `/status` 以确认哪种身份验证方法处于活跃状态，取消设置该环境变量或删除 `apiKeyHelper` 设置，然后运行 `/login` 以选择您的 Claude.ai 帐户。916Claude.ai 连接器仅在您的活跃[身份验证方法](/zh-CN/authentication#authentication-precedence)是您的 Claude.ai 订阅时才会被获取。当 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`apiKeyHelper` 或第三方提供商（如 Amazon Bedrock 或 Google Cloud 的 Agent Platform）处于活跃状态时，它们不会被加载，即使您之前运行过 `/login`。如果 `/mcp` 未列出您添加的连接器，请运行 `/status` 以确认哪种身份验证方法处于活跃状态，取消设置该环境变量或删除 `apiKeyHelper` 设置，然后运行 `/login` 以选择您的 claude.ai 帐户。

898 917

899您在 Claude Code 中添加的服务器优先于指向相同 URL 的 claude.ai 连接器。发生这种情况时，`/mcp` 会将连接器列为隐藏，并显示如何删除重复项（如果您更希望使用连接器）。918您在 Claude Code 中添加的服务器优先于指向相同 URL 的 claude.ai 连接器。发生这种情况时，`/mcp` 会将连接器列为隐藏，并显示如何删除重复项（如果您更希望使用连接器）。

900 919

1170 配置工具搜索1189 配置工具搜索

1171</h3>1190</h3>

1172 1191

1173工具搜索默认启用：MCP 工具被延迟并按需发现。Claude Code 在 Vertex AI 上默认禁用它。当 `ANTHROPIC_BASE_URL` 指向非第一方主机时，它也被禁用，因为大多数代理不转发 `tool_reference` 块。显式设置 `ENABLE_TOOL_SEARCH` 以覆盖任一回退。1192工具搜索默认启用：MCP 工具被延迟并按需发现。Claude Code 在 Google Cloud 的 Agent Platform 上默认禁用它。当 `ANTHROPIC_BASE_URL` 指向非第一方主机时，它也被禁用，因为大多数代理不转发 `tool_reference` 块。显式设置 `ENABLE_TOOL_SEARCH` 以覆盖任一回退。

1174 1193

1175工具搜索需要支持 `tool_reference` 块的模型。Haiku 模型不支持它。在 Vertex AI 上，工具搜索支持 Claude Sonnet 4.5 及更高版本以及 Claude Opus 4.5 及更高版本。1194工具搜索需要支持 `tool_reference` 块的模型。Haiku 模型不支持它。在 Google Cloud 的 Agent Platform 上，工具搜索支持 Claude Sonnet 4.5 及更高版本以及 Claude Opus 4.5 及更高版本。

1176 1195

1177使用 `ENABLE_TOOL_SEARCH` 环境变量控制工具搜索行为：1196使用 `ENABLE_TOOL_SEARCH` 环境变量控制工具搜索行为：

1178 1197

1179| 值 | 行为 |1198| 值 | 行为 |

1180| :------- | :---------------------------------------------------------------------------------------------------------------------------------- |1199| :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1181| （未设置） | 所有 MCP 工具被延迟并按需加载。在 Vertex AI 上或当 `ANTHROPIC_BASE_URL` 是非第一方主机时回退到预先加载 |1200| （未设置） | 所有 MCP 工具被延迟并按需加载。在 Google Cloud 的 Agent Platform 上或当 `ANTHROPIC_BASE_URL` 是非第一方主机时回退到预先加载 |

1182| `true` | 所有 MCP 工具被延迟。Claude Code 即使在 Vertex AI 上和通过代理也会发送 beta 标头。对于早于 Sonnet 4.5 或 Opus 4.5 的 Vertex AI 模型或不支持 `tool_reference` 块的代理，请求会失败 |1201| `true` | 所有 MCP 工具被延迟。Claude Code 即使在 Google Cloud 的 Agent Platform 上和通过代理也会发送 beta 标头。对于早于 Sonnet 4.5 或 Opus 4.5 的 Google Cloud 的 Agent Platform 模型或不支持 `tool_reference` 块的代理，请求会失败 |

mcp-quickstart.md +1 −1

Details

315 Claude Code 没有为当前目录找到任何服务器。最常见的原因：315 Claude Code 没有为当前目录找到任何服务器。最常见的原因：

316 316

317 * 您从不同的项目运行了 `claude mcp add`。本地范围的服务器与您添加它们的项目相关联：存储库根目录，或如果您不在 git 存储库中，则为确切目录。从您现在所在的项目重新添加服务器，或使用 `--scope user` 添加它，以便它不与项目相关联。317 * 您从不同的项目运行了 `claude mcp add`。本地范围的服务器与您添加它们的项目相关联：存储库根目录，或如果您不在 git 存储库中，则为确切目录。从您现在所在的项目重新添加服务器，或使用 `--scope user` 添加它，以便它不与项目相关联。

318 * 您在错误的路径编辑了配置文件。正确的文件是 `~/.claude.json` 和 `<project>/.mcp.json`。Claude Code 不读取 `~/.claude/config/mcp.json`、`~/.claude/mcp.json` 或 `%APPDATA%\Claude\mcp.json` 等路径。318 * 您在错误的路径编辑了配置文件。正确的文件是 `~/.claude.json` 和 `<project>/.mcp.json`。Claude Code 不读取 `~/.claude/.mcp.json`、`~/.claude/config/mcp.json`、`~/.claude/mcp.json` 或 `%APPDATA%\Claude\mcp.json` 等路径。对于用户范围的服务器，运行 `claude mcp add --scope user`，它会写入 `~/.claude.json` 中的 `mcpServers` 密钥；对于项目范围的服务器，编辑项目根目录中的 `.mcp.json`。

319 </Accordion>319 </Accordion>

320 320

321 <Accordion title="状态显示连接失败或连接错误">321 <Accordion title="状态显示连接失败或连接错误">

microsoft-foundry.md +18 −6

Details

113 2) 配置 Azure 凭证113 2) 配置 Azure 凭证

114</h3>114</h3>

115 115

116Claude Code 支持两种 Microsoft Foundry 身份验证方法。选择最适合您安全要求的方法。116Claude Code 支持三种 Microsoft Foundry 身份验证方法。选择最适合您安全要求的方法。

117 117

118**选项 A：API 密钥身份验证**118**选项 A：API 密钥身份验证**

119 119

128 128

129**选项 B：Microsoft Entra ID 身份验证**129**选项 B：Microsoft Entra ID 身份验证**

130 130

131当未设置 `ANTHROPIC_FOUNDRY_API_KEY` 时，Claude Code 会自动使用 Azure SDK [默认凭证链](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview)。131当未设置 `ANTHROPIC_FOUNDRY_API_KEY` 和 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 时，Claude Code 会自动使用 Azure SDK [默认凭证链](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview)。

132这支持多种方法来验证本地和远程工作负载。132这支持多种方法来验证本地和远程工作负载。

133 133

134在本地环境中，您通常可以使用 Azure CLI：134在本地环境中，您通常可以使用 Azure CLI：

137az login137az login

138```138```

139 139

140**选项 C：Bearer 令牌身份验证**

141

142{/* min-version: 2.1.203 */}Claude Code 在每个请求中将 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 的值作为 `Authorization: Bearer` 标头发送。当另一个进程（例如主机应用程序或登录脚本）已经为您获取了访问令牌时，请使用此选项。需要 Claude Code v2.1.203 或更高版本。

143

144将变量设置为 Microsoft Entra ID 为您的资源颁发的 Bearer 令牌：

145

146```bash theme={null}

147export ANTHROPIC_FOUNDRY_AUTH_TOKEN=your-entra-access-token

148```

149

150`ANTHROPIC_FOUNDRY_AUTH_TOKEN` 优先于 `ANTHROPIC_FOUNDRY_API_KEY` 和默认凭证链。

151

140<Note>152<Note>

141 使用 Microsoft Foundry 时，`/logout` 命令不可用，因为身份验证通过 Azure 凭证处理。153 使用 Microsoft Foundry 时，`/logout` 命令不可用，因为身份验证通过 Azure 凭证处理。

142</Note>154</Note>

162</h3>174</h3>

163 175

164<Warning>176<Warning>

165 为每个部署固定特定的模型版本。如果不固定版本，模型别名（如 `sonnet` 和 `opus`）会解析为 Claude Code 为 Foundry 内置的默认值，这可能滞后于最新版本，并且可能在您的账户中尚不可用。Foundry 没有启动模型检查，因此当默认值不可用时请求会失败。创建 Azure 部署时，请选择特定的模型版本而不是"自动更新到最新版本"。177 为每个部署固定特定的模型版本。如果不固定版本，模型别名（如 `sonnet` 和 `opus`）会解析为 Claude Code 为 Microsoft Foundry 内置的默认值，这可能滞后于最新版本，并且可能在您的账户中尚不可用。Microsoft Foundry 没有启动模型检查，因此当默认值不可用时请求会失败。创建 Azure 部署时，请选择特定的模型版本而不是"自动更新到最新版本"。

166</Warning>178</Warning>

167 179

168设置模型变量以匹配您在第 1 步中创建的部署名称。180设置模型变量以匹配您在第 1 步中创建的部署名称。

169 181

170如果没有 `ANTHROPIC_DEFAULT_OPUS_MODEL`，Foundry 上的 `opus` 别名会解析为 Opus 4.6。将其设置为 Opus 4.8 ID 以使用最新模型：182如果没有 `ANTHROPIC_DEFAULT_OPUS_MODEL`，Microsoft Foundry 上的 `opus` 别名会解析为 Opus 4.6。将其设置为 Opus 4.8 ID 以使用最新模型：

171 183

172```bash theme={null}184```bash theme={null}

173export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'185export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'

175export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'187export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'

176```188```

177 189

178后台任务（如会话标题生成）使用小型/快速模型，通常是 Haiku 级别的模型。在 Foundry 上，Claude Code 默认使用主模型，因为并非每个账户都有 Haiku 部署。要为后台任务使用 Haiku，请将 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 设置为您账户中可用的 Haiku 部署，如上所示。190后台任务（如会话标题生成）使用小型/快速模型，通常是 Haiku 级别的模型。在 Microsoft Foundry 上，Claude Code 默认使用主模型，因为并非每个账户都有 Haiku 部署。要为后台任务使用 Haiku，请将 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 设置为您账户中可用的 Haiku 部署，如上所示。

179 191

180有关当前和旧版模型 ID，请参阅[模型概览](https://platform.claude.com/docs/en/about-claude/models/overview)。有关完整的环境变量列表，请参阅[模型配置](/zh-CN/model-config#pin-models-for-third-party-deployments)。192有关当前和旧版模型 ID，请参阅[模型概览](https://platform.claude.com/docs/en/about-claude/models/overview)。有关完整的环境变量列表，请参阅[模型配置](/zh-CN/model-config#pin-models-for-third-party-deployments)。

181 193

195claude207claude

196```208```

197 209

198Claude Code 从环境中读取 `CLAUDE_CODE_USE_FOUNDRY` 和其他 Foundry 变量，并在第一个提示时连接到您的 Azure 资源。与 Bedrock 和 Vertex AI 不同，Foundry 没有交互式设置向导，因此第 3 和第 4 步中的环境变量是唯一的配置路径。210Claude Code 从环境中读取 `CLAUDE_CODE_USE_FOUNDRY` 和其他 Microsoft Foundry 变量，并在第一个提示时连接到您的 Azure 资源。与 Amazon Bedrock 和 Google Cloud 的 Agent Platform 不同，Microsoft Foundry 没有交互式设置向导，因此第 3 和第 4 步中的环境变量是唯一的配置路径。

199 211

200<h2 id="azure-rbac-configuration">212<h2 id="azure-rbac-configuration">

201 Azure RBAC 配置213 Azure RBAC 配置

model-config.md +78 −30

Details

15* 一个**模型别名**15* 一个**模型别名**

16* 一个**模型名称**16* 一个**模型名称**

17 * Anthropic API：完整的\*\*[模型名称](https://platform.claude.com/docs/zh-CN/about-claude/models/overview)\*\*17 * Anthropic API：完整的\*\*[模型名称](https://platform.claude.com/docs/zh-CN/about-claude/models/overview)\*\*

~~18 * Bedrock：推理配置文件 ARN~~18 * Amazon Bedrock：推理配置文件 ARN

~~19 * Foundry：部署名称~~19 * Microsoft Foundry：部署名称

~~20 * Vertex：版本名称~~20 * Google Cloud 的 Agent Platform：版本名称

21 21

22<Note>22<Note>

23 `ANTHROPIC_BASE_URL` 改变请求发送的位置，而不是哪个模型回答它们。要通过 LLM 网关路由 Claude，请参阅 [LLM 网关](/zh-CN/llm-gateway)。23 `ANTHROPIC_BASE_URL` 改变请求发送的位置，而不是哪个模型回答它们。要通过 LLM 网关路由 Claude，请参阅 [LLM 网关](/zh-CN/llm-gateway)。

41| **`opus[1m]`** | 使用 Opus 和[100 万令牌上下文窗口](https://platform.claude.com/docs/zh-CN/build-with-claude/context-windows#1m-token-context-window)用于长会话 |41| **`opus[1m]`** | 使用 Opus 和[100 万令牌上下文窗口](https://platform.claude.com/docs/zh-CN/build-with-claude/context-windows#1m-token-context-window)用于长会话 |

43 43

44在 Anthropic API 上，`opus` 解析为 Opus 4.8，`sonnet` 解析为 Sonnet 5。在 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 上，`opus` 解析为 Opus 4.7，`sonnet` 解析为 Sonnet 4.6。在 Bedrock、Vertex 和 Foundry 上，`opus` 解析为 Opus 4.6，`sonnet` 解析为 Sonnet 4.5；通过显式选择完整模型名称或设置 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 可以在这些提供商上获得更新的模型。44在 Anthropic API 上，`opus` 解析为 Opus 4.8，`sonnet` 解析为 Sonnet 5。在 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 上，`opus` 解析为 Opus 4.7，`sonnet` 解析为 Sonnet 4.6。在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，`opus` 解析为 Opus 4.6，`sonnet` 解析为 Sonnet 4.5；通过显式选择完整模型名称或设置 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 可以在这些提供商上获得更新的模型。

45 45

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

47 47

84* `Enter`：切换模型并保存为您的默认值84* `Enter`：切换模型并保存为您的默认值

85* `s`：仅为此会话切换模型85* `s`：仅为此会话切换模型

86 86

87直接输入 `/model <name>` 的行为类似于 `Enter`。项目和托管设置仍然优先级最高，并在下次启动时重新应用。{/* min-version: 2.1.196 */}您的管理员配置的[组织默认模型](#organization-default-model)也会在下次启动时重新应用。87直接输入 `/model <name>` 的行为类似于 `Enter`。{/* min-version: 2.1.205 */}在[非交互模式](/zh-CN/headless)中使用 `-p` 标志通过 `/model` 设置的模型仅适用于当前会话，不会保存为您的默认值。项目和托管设置仍然优先级最高，并在下次启动时重新应用。{/* min-version: 2.1.196 */}您的管理员配置的[组织默认模型](#organization-default-model)也会在下次启动时重新应用。

88 88

89在 v2.1.144 到 v2.1.152 中，`/model` 仅适用于当前会话，选择器中的 `d` 保存默认值。89在 v2.1.144 到 v2.1.152 中，`/model` 仅适用于当前会话，选择器中的 `d` 保存默认值。

90 90

92 92

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

94 94

95您为新启动选择的模型使用 `--model` 或 `ANTHROPIC_MODEL` 仍然优先于恢复的模型。{/* min-version: 2.1.195 */}从 v2.1.195 开始，[`ANTHROPIC_DEFAULT_OPUS_MODEL`](#environment-variables) 系列变量也是如此。

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

96 98

99当通过 [Agent SDK](/zh-CN/agent-sdk/overview) `setModel()` 方法或由运行 Claude Code CLI 的应用程序（如 [Desktop app](/zh-CN/desktop)）请求模型切换时，Claude Code 会检查该字符串是否是它识别的字符串，然后再保存它。此检查需要 Claude Code v2.1.200 或更高版本。在 Anthropic API 上，Claude Code 识别：

100

101* 一个模型别名

102* 来自 `/model` 选择器的条目

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

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

105

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

107

108该检查仅在 Anthropic API 上运行。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 和 [LLM 网关](/zh-CN/llm-gateway)后面或自定义 `ANTHROPIC_BASE_URL` 上，您的提供商或网关定义模型名称，所以 Claude Code 会通过任何字符串而不检查它。该检查也不涵盖 `--model` 标志、`ANTHROPIC_MODEL` 环境变量或 `model` 设置；那里的拼写错误值会在第一个请求时产生[所选模型出现问题](/zh-CN/errors#there%E2%80%99s-an-issue-with-the-selected-model)。

109

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

98 111

99使用示例：112使用示例：

133* **顾问模型**：配置的 [`advisorModel`](/zh-CN/advisor) 设置和 `--advisor` 标志146* **顾问模型**：配置的 [`advisorModel`](/zh-CN/advisor) 设置和 `--advisor` 标志

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

135 148

136使用 `/model` 切换到被阻止的模型会被拒绝并显示错误，而被阻止的 `--model` 标志、`ANTHROPIC_MODEL` 或 `model` 设置值在启动时会被替换为警告，命名请求的和替换的模型，会话会在默认模型上启动。被阻止的子代理、技能或命令覆盖会回退到继承或默认模型，而不是导致请求失败；被阻止的 `advisorModel` 设置会禁用该会话的顾问，而被阻止的 `--advisor` 标志值会在启动时退出并显示错误。被排除的模型在 `/model` 选择器中被隐藏。{/* min-version: 2.1.199 */}从 v2.1.199 开始，列表中没有内置选择器行的完整模型 ID（如列表固定的较旧版本）在 `/model` 选择器中显示为其自己的标记行。在较早的版本上，这样的 ID 仅可通过键入 `/model <id>` 来选择。149在 Anthropic API 和 [AWS 上的 Claude Platform](/zh-CN/claude-platform-on-aws) 上，模型系列别名 `opus`、`sonnet`、`haiku` 或 `fable` 解析为允许列表允许的该系列的最新版本。当允许列表固定特定版本时，例如 `["sonnet", "claude-opus-4-6"]`，`/model opus` 和 `--model opus` 都会选择 Claude Opus 4.6（最新允许的 Opus），并显示一条通知，命名请求的和替换的模型。在 v2.1.205 之前，其最新发布版本在列表外的别名会被拒绝或替换，就像任何其他被阻止的选择一样，即使列表允许较旧版本。

150

151Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 [Mantle](/zh-CN/amazon-bedrock#use-the-mantle-endpoint) 使用特定于提供商的部署 ID 而不是 Anthropic 模型 ID，因此被阻止的别名在那里遵循下面的拒绝和替换行为。

152

153Claude Code 根据模型的设置位置处理任何其他被阻止的选择：

154

155* **`/model`**：切换被拒绝并显示错误

156* **`--model` 标志、`ANTHROPIC_MODEL` 或 `model` 设置**：该值在启动时被替换为警告，命名请求的和替换的模型，会话在默认模型上启动

157* **子代理、技能或命令覆盖**：覆盖回退到继承或默认模型，而不是导致请求失败

158* **`advisorModel` 设置**：该会话的顾问被禁用

159* **`--advisor` 标志**：Claude Code 在启动时以错误退出

160

161被排除的模型在 `/model` 选择器中被隐藏。{/* min-version: 2.1.199 */}列表中没有内置选择器行的完整模型 ID（如列表固定的较旧版本）在 `/model` 选择器中显示为其自己的标记行。在 v2.1.199 之前，这样的 ID 仅可通过键入 `/model <id>` 来选择。

137 162

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

164

165* **[回退模型链](#fallback-model-chains)**：允许列表外的元素被删除

166* **Plan Mode 升级**：在 Anthropic API 和 AWS 上的 Claude Platform 上，升级（如 [`opusplan`](#opusplan-model-setting)）到被排除的模型会使用升级系列的最新允许版本。在具有特定于提供商的模型 ID 的提供商上，以及当没有版本被允许时，升级被跳过，规划继续在会话的模型上进行

167* **[自动模型回退](#automatic-model-fallback)**：目标被排除的回退不会运行，因此标记的请求以拒绝结束

168* **[快速模式](/zh-CN/fast-mode)**：当会话之后运行的模型在允许列表外时，启用快速模式被拒绝

139 169

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

141{171{

156 186

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

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

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

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

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

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

228 Mantle 模型 ID258 Mantle 模型 ID

229</h3>259</h3>

230 260

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

232 262

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

234 组织模型限制264 组织模型限制

242 272

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

244 274

275[模型系列别名](#restrict-model-selection)（如 `opus`）解析为组织允许的该系列的最新版本，显示相同的替换通知。`/model <alias>` 仅在其系列的每个版本都被限制时被拒绝；使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 设置的别名在这种情况下仍在启动时被替换。在 v2.1.205 之前，系列别名基于其最新发布版本单独被替换或拒绝，即使列表允许较旧版本。

276

245限制应用于组织范围或按角色：277限制应用于组织范围或按角色：

246 278

247* 在组织级别禁用模型会为每个成员删除它。279* 在组织级别禁用模型会为每个成员删除它。

249* Haiku 模型始终可用，无法禁用，因此每个成员至少保持一个可用模型。281* Haiku 模型始终可用，无法禁用，因此每个成员至少保持一个可用模型。

250* 访问更改在约一分钟内对新请求生效；`/model` 选择器在下次会话启动时反映它。282* 访问更改在约一分钟内对新请求生效；`/model` 选择器在下次会话启动时反映它。

251 283

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

253 285

254<h2 id="organization-default-model">286<h2 id="organization-default-model">

255 组织默认模型287 组织默认模型

308* **Max、Team Premium、Enterprise 按使用量付费和 Anthropic API**：默认为 Opus 4.8340* **Max、Team Premium、Enterprise 按使用量付费和 Anthropic API**：默认为 Opus 4.8

309* **AWS 上的 Claude Platform**：默认为 Opus 4.7341* **AWS 上的 Claude Platform**：默认为 Opus 4.7

310* **Pro、Team Standard 和 Enterprise 订阅席位**：默认为 Sonnet 5342* **Pro、Team Standard 和 Enterprise 订阅席位**：默认为 Sonnet 5

311* **Bedrock、Vertex 和 Foundry**：默认为 Sonnet 4.5343* **Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry**：默认为 Sonnet 4.5

312 344

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

314 346

331 363

332Plan Mode 中的 Opus 阶段使用与 `opus` 模型设置相同的上下文窗口。在[自动升级到 1M 上下文](#extended-context)的订阅层上，`opusplan` 在 Plan Mode 中也会获得升级。要在您不在自动升级层上时为两个阶段强制使用 1M 上下文，请将模型设置为 `opusplan[1m]`。364Plan Mode 中的 Opus 阶段使用与 `opus` 模型设置相同的上下文窗口。在[自动升级到 1M 上下文](#extended-context)的订阅层上，`opusplan` 在 Plan Mode 中也会获得升级。要在您不在自动升级层上时为两个阶段强制使用 1M 上下文，请将模型设置为 `opusplan[1m]`。

333 365

334当 [`availableModels`](#restrict-model-selection) 排除 Opus 时，`opusplan` 在 Plan Mode 中保持在 Sonnet 上，而不是切换。当 Sonnet 被排除时，隐含的 Haiku 到 Sonnet Plan Mode 升级也是如此。366当 [`availableModels`](#restrict-model-selection) 排除最新的 Opus 但允许较旧版本时，例如 `["sonnet", "claude-opus-4-6"]`，`opusplan` 为规划使用最新的允许 Opus，仅当每个 Opus 都被排除时才保持在 Sonnet 上。通常会在 Plan Mode 中升级到 Sonnet 的 Haiku 会话同样使用最新的允许 Sonnet，仅当每个 Sonnet 都被排除时才保持在 Haiku 上。在 v2.1.205 之前，当最新版本的升级系列被排除时，Plan Mode 保持在会话的模型上，即使允许列表允许较旧的版本。

367

368较旧的允许版本的替换适用于 Anthropic API 和 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws)。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Mantle 上，其部署使用特定于提供商的模型 ID，当升级模型被排除时，Plan Mode 保持在会话的模型上。

335 369

336有关 Claude 在任务中途决定何时咨询第二个模型而不是在 Plan 边界处切换的混合方法，请参阅 [advisor tool](/zh-CN/advisor)。370有关 Claude 在任务中途决定何时咨询第二个模型而不是在 Plan 边界处切换的混合方法，请参阅 [advisor tool](/zh-CN/advisor)。

337 371

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

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

399 433

400<h4 id="enable-fallback-on-bedrock-vertex-ai-and-foundry">434<h4 id="enable-fallback-on-bedrock-agent-platform-and-foundry">

401 在 Bedrock、Vertex AI 和 Foundry 上启用回退435 在 Bedrock、Agent Platform 和 Foundry 上启用回退

402</h4>436</h4>

403 437

404在 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Vertex AI](/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/zh-CN/microsoft-foundry) 上，模型 ID 是特定于提供商的，因此自动回退仅在 Claude Code 可以识别两个涉及的模型时运行：438在 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/zh-CN/microsoft-foundry) 上，模型 ID 是特定于提供商的，因此自动回退仅在 Claude Code 可以识别两个涉及的模型时运行：

405 439

406* Claude Code 必须将当前模型识别为 Fable 5：模型 ID 包含 `claude-fable-5`，匹配 `ANTHROPIC_DEFAULT_FABLE_MODEL` 的值，或使用 [`modelOverrides`](#override-model-ids-per-version) 映射。440* Claude Code 必须将当前模型识别为 Fable 5：模型 ID 包含 `claude-fable-5`，匹配 `ANTHROPIC_DEFAULT_FABLE_MODEL` 的值，或使用 [`modelOverrides`](#override-model-ids-per-version) 映射。

407* 回退目标必须解析为 Opus 模型：`ANTHROPIC_DEFAULT_OPUS_MODEL` 的值（如果设置），否则提供商模型列表中的 Opus 4.8 条目。441* 回退目标必须解析为 Opus 模型：`ANTHROPIC_DEFAULT_OPUS_MODEL` 的值（如果设置），否则提供商模型列表中的 Opus 4.8 条目。

434 468

435Fable 5、Sonnet 5、Opus 4.8、Opus 4.6 和 Sonnet 4.6 上的默认工作量是 `high`，Opus 4.7 上的默认工作量是 `xhigh`。469Fable 5、Sonnet 5、Opus 4.8、Opus 4.6 和 Sonnet 4.6 上的默认工作量是 `high`，Opus 4.7 上的默认工作量是 `xhigh`。

436 470

437当您首次运行 Fable 5、Opus 4.8 或 Opus 4.7 时，Claude Code 会应用该模型的默认工作量，即使您之前为另一个模型设置了不同的级别：Fable 5 和 Opus 4.8 上的 `high`，Opus 4.7 上的 `xhigh`。切换后再次运行 `/effort` 以选择不同的级别。471当您首次运行 Fable 5、Opus 4.8 或 Opus 4.7 时，Claude Code 会应用该模型的默认工作量，即使您之前为另一个模型设置了不同的级别：Fable 5 和 Opus 4.8 上的 `high`，Opus 4.7 上的 `xhigh`。切换后再次运行 `/effort` 以选择不同的级别。该默认值在会话间保持，直到您做出明确的工作量选择，例如在交互式会话中运行 `/effort` 或使用 `--effort` 启动。{/* min-version: 2.1.205 */}`low`、`medium`、`high` 和 `xhigh` 在会话间持续存在。`max` 提供最深入的推理，对令牌支出没有限制，仅适用于当前会话，除非通过 `CLAUDE_CODE_EFFORT_LEVEL` 环境变量设置。在 [non-interactive mode](/zh-CN/headless) 中使用 `/effort` 时，带有 `-p` 标志，仅适用于当前会话，不会保存为您的默认值。非交互式 `/effort` 也无法释放上面的模型默认保持：在 Fable 5、Opus 4.8 和 Opus 4.7 上，它报告 `Not applied`，会话保持在模型的默认工作量，因此改为在启动时传递 `--effort`。`max` 提供最深入的推理，对令牌支出没有限制，仅适用于当前会话，除非通过 `CLAUDE_CODE_EFFORT_LEVEL` 环境变量设置。

472

473`/effort` 菜单还提供 `ultracode`。Ultracode 是一个 Claude Code 设置，而不是模型工作量级别：它向模型发送 `xhigh`，并且还让 Claude 为实质性任务编排[动态工作流](/zh-CN/workflows)。它仅适用于当前会话。

474

475您可以通过以下任何方式打开 ultracode：

438 476

439`low`、`medium`、`high` 和 `xhigh` 在会话间持续存在。`max` 提供最深入的推理，对令牌支出没有限制，仅适用于当前会话，除非通过 `CLAUDE_CODE_EFFORT_LEVEL` 环境变量设置。477* **`/effort`**：运行 `/effort ultracode`，或从菜单中选择它

478* **`--effort` 标志**：使用 `claude --effort ultracode` 启动，这会在 `xhigh` 工作量下启动会话并打开 ultracode

479* **`--settings` 或 Agent SDK 控制请求**：传递 `"ultracode": true`。[`applyFlagSettings()`](/zh-CN/agent-sdk/typescript#applyflagsettings) 请求也接受 `effortLevel: "ultracode"`

440 480

441`/effort` 菜单还提供 `ultracode`。Ultracode 是一个 Claude Code 设置，而不是模型工作量级别：它向模型发送 `xhigh`，并且还让 Claude 为实质性任务编排[动态工作流](/zh-CN/workflows)。它仅适用于当前会话。通过 `/effort` 设置它，或通过 `--settings` 或 Agent SDK 控制请求传递 `"ultracode": true`。它不是 `effortLevel` 设置、`--effort` 标志或 `CLAUDE_CODE_EFFORT_LEVEL` 的一部分。481将 `ultracode` 传递给 `--effort` 标志或 Agent SDK `effortLevel` 值需要 Claude Code v2.1.203 或更高版本。在 v2.1.203 之前，`--effort ultracode` 打印 `Unknown --effort value 'ultracode'`，会话以默认工作量启动。

482

483持久化的 `effortLevel` 设置和 `CLAUDE_CODE_EFFORT_LEVEL` 环境变量不接受 `ultracode`。

484

485当 ultracode 不可用时，例如当[工作流被关闭](/zh-CN/workflows#turn-workflows-off)时，`--effort ultracode` 仅设置 `xhigh` 工作量。

442 486

443<h4 id="choose-an-effort-level">487<h4 id="choose-an-effort-level">

444 选择工作量级别488 选择工作量级别

595 为第三方部署固定模型639 为第三方部署固定模型

596</h3>640</h3>

597 641

598当通过 [Bedrock](/zh-CN/amazon-bedrock)、[Vertex AI](/zh-CN/google-vertex-ai)、[Foundry](/zh-CN/microsoft-foundry) 或 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 部署 Claude Code 时，在向用户推出前固定模型版本。642当通过 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud's Agent Platform](/zh-CN/google-vertex-ai)、[Microsoft Foundry](/zh-CN/microsoft-foundry) 或 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 部署 Claude Code 时，在向用户推出前固定模型版本。

599 643

600不固定模型，Claude Code 会使用模型别名（如 `fable`、`opus`、`sonnet` 和 `haiku`），这些别名会解析为每个提供商的内置默认模型 ID。该默认值可能滞后于最新的 Anthropic 版本，并且它指向的模型可能尚未在用户账户中启用。当默认值不可用时，Bedrock 和 Vertex AI 用户会看到通知并回退到该会话的先前版本，而 Foundry 用户会看到错误，因为 Foundry 没有等效的启动检查。644不固定模型，Claude Code 会使用模型别名（如 `fable`、`opus`、`sonnet` 和 `haiku`），这些别名会解析为每个提供商的内置默认模型 ID。该默认值可能滞后于最新的 Anthropic 版本，并且它指向的模型可能尚未在用户账户中启用。当默认值不可用时，Amazon Bedrock 和 Google Cloud's Agent Platform 用户会看到通知并回退到该会话的先前版本，而 Microsoft Foundry 用户会看到错误，因为 Microsoft Foundry 没有等效的启动检查。

601 645

602<Warning>646<Warning>

603 在初始设置中将模型环境变量设置为特定版本 ID。固定让您控制用户何时迁移到新模型。647 在初始设置中将模型环境变量设置为特定版本 ID。固定让您控制用户何时迁移到新模型。

606对您的提供商使用以下环境变量和特定版本的模型 ID：650对您的提供商使用以下环境变量和特定版本的模型 ID：

607 651

608| 提供商 | 示例 |652| 提供商 | 示例 |

609| :-------- | :------------------------------------------------------------------- |653| :---------------------------- | :------------------------------------------------------------------- |

613 657

614对 `ANTHROPIC_DEFAULT_FABLE_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 应用相同的模式。有关所有提供商的当前和旧版模型 ID，请参阅[模型概览](https://platform.claude.com/docs/en/about-claude/models/overview)。要将用户升级到新模型版本，请更新这些环境变量并重新部署。658对 `ANTHROPIC_DEFAULT_FABLE_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 应用相同的模式。有关所有提供商的当前和旧版模型 ID，请参阅[模型概览](https://platform.claude.com/docs/en/about-claude/models/overview)。要将用户升级到新模型版本，请更新这些环境变量并重新部署。

615 659

623 667

624* Claude Code 在将模型 ID 发送到您的提供商之前会删除该后缀。668* Claude Code 在将模型 ID 发送到您的提供商之前会删除该后缀。

625* 仅当底层模型[支持 1M 上下文](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)时才附加 `[1m]`。669* 仅当底层模型[支持 1M 上下文](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)时才附加 `[1m]`。

626* 该后缀按变量读取，而不是按模型读取。在 Bedrock、Vertex 和 Foundry 上，一个变量中没有 `[1m]` 的模型 ID 使用 200K 上下文，即使另一个变量使用相同的模型和后缀。Sonnet 5 在这些提供商上始终以 1M 窗口运行，从不需要该后缀。670* 该后缀按变量读取，而不是按模型读取。在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，一个变量中没有 `[1m]` 的模型 ID 使用 200K 上下文，即使另一个变量使用相同的模型和后缀。Sonnet 5 在这些提供商上始终以 1M 窗口运行，从不需要该后缀。

627 671

628<Note>672<Note>

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

635 679

636当您在第三方提供商上固定模型时，提供商特定的 ID 在 `/model` 选择器中按原样显示，Claude Code 可能无法识别模型支持的功能。您可以使用每个固定模型的伴随环境变量覆盖显示名称并声明功能。680当您在第三方提供商上固定模型时，提供商特定的 ID 在 `/model` 选择器中按原样显示，Claude Code 可能无法识别模型支持的功能。您可以使用每个固定模型的伴随环境变量覆盖显示名称并声明功能。

637 681

638这些变量在第三方提供商（如 Bedrock、Vertex AI 和 Foundry）上生效。`_NAME` 和 `_DESCRIPTION` 变量在 `ANTHROPIC_BASE_URL` 指向 [LLM gateway](/zh-CN/llm-gateway) 时也生效。当直接连接到 `api.anthropic.com` 时无效。682这些变量在第三方提供商（如 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry）上生效。`_NAME` 和 `_DESCRIPTION` 变量在 `ANTHROPIC_BASE_URL` 指向 [LLM gateway](/zh-CN/llm-gateway) 时也生效。当直接连接到 `api.anthropic.com` 时无效。

639 683

640| 环境变量 | 描述 |684| 环境变量 | 描述 |

641| ----------------------------------------------------- | ---------------------------------------------------------- |685| ----------------------------------------------------- | ---------------------------------------------------------- |

645 689

646相同的 `_NAME`、`_DESCRIPTION` 和 `_SUPPORTED_CAPABILITIES` 后缀可用于 `ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL`、`ANTHROPIC_DEFAULT_FABLE_MODEL` 和 `ANTHROPIC_CUSTOM_MODEL_OPTION`。690相同的 `_NAME`、`_DESCRIPTION` 和 `_SUPPORTED_CAPABILITIES` 后缀可用于 `ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL`、`ANTHROPIC_DEFAULT_FABLE_MODEL` 和 `ANTHROPIC_CUSTOM_MODEL_OPTION`。

647 691

648Claude Code 通过将模型 ID 与已知模式匹配来启用[工作量级别](#adjust-effort-level)和[扩展思考](#extended-thinking)等功能。提供商特定的 ID（如 Bedrock ARN 或自定义部署名称）通常与这些模式不匹配，导致支持的功能被禁用。设置 `_SUPPORTED_CAPABILITIES` 以告诉 Claude Code 模型实际支持的功能：692Claude Code 通过将模型 ID 与已知模式匹配来启用[工作量级别](#adjust-effort-level)和[扩展思考](#extended-thinking)等功能。提供商特定的 ID（如 Amazon Bedrock ARN 或自定义部署名称）通常与这些模式不匹配，导致支持的功能被禁用。设置 `_SUPPORTED_CAPABILITIES` 以告诉 Claude Code 模型实际支持的功能：

649 693

650| 功能值 | 启用 |694| 功能值 | 启用 |

651| ---------------------- | ------------------------------------------- |695| ---------------------- | ------------------------------------------- |

658 702

659设置 `_SUPPORTED_CAPABILITIES` 时，列出的功能对匹配的固定模型启用，未列出的功能被禁用。未设置变量时，Claude Code 回退到基于模型 ID 的内置检测。703设置 `_SUPPORTED_CAPABILITIES` 时，列出的功能对匹配的固定模型启用，未列出的功能被禁用。未设置变量时，Claude Code 回退到基于模型 ID 的内置检测。

660 704

661此示例将 Opus 固定到 Bedrock 自定义模型 ARN，设置友好名称，并声明其功能：705此示例将 Opus 固定到 Amazon Bedrock 自定义模型 ARN，设置友好名称，并声明其功能：

662 706

663```bash theme={null}707```bash theme={null}

664export ANTHROPIC_DEFAULT_OPUS_MODEL='arn:aws:bedrock:us-east-1:123456789012:custom-model/abc'708export ANTHROPIC_DEFAULT_OPUS_MODEL='arn:aws:bedrock:us-east-1:123456789012:custom-model/abc'

675 719

676`modelOverrides` 将单个 Anthropic 模型 ID 映射到 Claude Code 发送到您的提供商 API 的提供商特定字符串。当用户在 `/model` 选择器中选择映射的模型时，Claude Code 会使用您配置的值而不是内置默认值。720`modelOverrides` 将单个 Anthropic 模型 ID 映射到 Claude Code 发送到您的提供商 API 的提供商特定字符串。当用户在 `/model` 选择器中选择映射的模型时，Claude Code 会使用您配置的值而不是内置默认值。

677 721

678这让企业管理员可以将每个模型版本路由到特定的 Bedrock 推理配置文件 ARN、Vertex AI 版本名称或 Foundry 部署名称，用于治理、成本分配或区域路由。722这让企业管理员可以将每个模型版本路由到特定的 Amazon Bedrock 推理配置文件 ARN、Google Cloud's Agent Platform 版本名称或 Microsoft Foundry 部署名称，用于治理、成本分配或区域路由。

679 723

680在您的[设置文件](/zh-CN/settings#settings-files)中设置 `modelOverrides`：724在您的[设置文件](/zh-CN/settings#settings-files)中设置 `modelOverrides`：

681 725

691 735

692键必须是[模型概览](https://platform.claude.com/docs/en/about-claude/models/overview)中列出的 Anthropic 模型 ID。对于带日期的模型 ID，请包含日期后缀，完全按照其显示的方式。未知的键会被忽略。736键必须是[模型概览](https://platform.claude.com/docs/en/about-claude/models/overview)中列出的 Anthropic 模型 ID。对于带日期的模型 ID，请包含日期后缀，完全按照其显示的方式。未知的键会被忽略。

693 737

694覆盖替换了支持 `/model` 选择器中每个条目的内置模型 ID。在 Bedrock 上，覆盖优先于 Claude Code 在启动时自动发现的任何推理配置文件。您直接通过 `ANTHROPIC_MODEL`、`--model` 或 `ANTHROPIC_DEFAULT_*_MODEL` 环境变量提供的值会按原样传递给提供商，不会被 `modelOverrides` 转换。738覆盖替换了支持 `/model` 选择器中每个条目的内置模型 ID。在 Amazon Bedrock 上，`modelOverrides` 条目优先于 Claude Code 在启动时自动发现的任何推理配置文件。Claude Code 将已经是提供商原生的值（如 Amazon Bedrock 推理配置文件 ARN 或 Microsoft Foundry 部署名称）按原样传递给提供商。

739

740{/* min-version: 2.1.200 */}当您通过 `--model`、`ANTHROPIC_MODEL` 环境变量或 `ANTHROPIC_DEFAULT_*_MODEL` 环境变量直接传递 Anthropic 模型 ID 时，覆盖也适用。在 Amazon Bedrock、Google Cloud's Agent Platform 和 [Mantle](/zh-CN/amazon-bedrock#use-the-mantle-endpoint) 上，没有 `modelOverrides` 条目的 Anthropic 模型 ID 解析为与该版本的 `/model` 选择器行相同的提供商特定 ID（当提供商支持该版本时）。Mantle 支持版本的子集。对于该子集之外的 Anthropic 模型 ID，Claude Code 将原始 ID 发送到 Mantle 而不进行映射，除非 `modelOverrides` 条目覆盖它。在 v2.1.200 之前，`--model` 和环境变量值直接到达提供商，不经过覆盖映射。

695 741

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

697 743

744{/* min-version: 2.1.200 */}当 `availableModels` 在[托管设置](/zh-CN/settings#settings-files)中设置时，仅来自该托管源的 `modelOverrides` 适用于通过 `--model` 或上述环境变量直接传递的 Anthropic 模型 ID。Claude Code 忽略用户或项目设置中针对这些 ID 的覆盖，并且永远不会通过任何设置源的 `modelOverrides` 解析托管列表排除的 ID。此托管源限制需要 Claude Code v2.1.200 或更高版本。有关如何处理被阻止的 ID，请参阅[限制模型选择](#restrict-model-selection)。

745

698<h3 id="prompt-caching-configuration">746<h3 id="prompt-caching-configuration">

699 Prompt caching 配置747 Prompt caching 配置

700</h3>748</h3>

monitoring-usage.md +15 −7

Details

191**`claude_code.llm_request`**191**`claude_code.llm_request`**

192 192

193| 属性 | 描述 | 门控条件 |193| 属性 | 描述 | 门控条件 |

194| -------------------------------- | --------------------------------------------------------------------------------------------------- | ---- |194| -------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------- |

201| `workflow.run_id` | [Workflow](/zh-CN/workflows) 工具运行的运行标识符，前缀为 `wf_`，生成此代理。对于不是由工作流生成的代理不存在 | |

202| `workflow.name` | 生成此代理的工作流的名称。用户编写的名称被替换为 `custom`，除非设置了门控条件 | `OTEL_LOG_TOOL_DETAILS` |

233| `workflow.run_id` | 生成此代理的 Workflow 工具运行的运行标识符，前缀为 `wf_`。对于不是由工作流生成的代理不存在 | |

234| `workflow.name` | 生成此代理的工作流的名称。用户编写的名称被替换为 `custom`，除非设置了门控条件 | `OTEL_LOG_TOOL_DETAILS` |

231| `tool_use_id` | 此调用的模型 `tool_use` 块 id。与 [tool\_result](#tool-result-event) 和 [tool\_decision](#tool-decision-event) 事件以及 hook 有效负载中的 `tool_use_id` 匹配，因此您可以将 span 连接到这些记录 | |235| `tool_use_id` | 此调用的模型 `tool_use` 块 id。与 [tool\_result](#tool-result-event) 和 [tool\_decision](#tool-decision-event) 事件以及 hook 有效负载中的 `tool_use_id` 匹配，因此您可以将 span 连接到这些记录 | |

309 313

310如果助手失败或打印不符合这些要求的输出，Claude Code 会在以下位置报告错误：314如果助手失败或打印不符合这些要求的输出，Claude Code 会在以下位置报告错误：

311 315

312* `/doctor` 输出316* `/status` 输出

313* 调试日志，当使用 [`--debug`](/zh-CN/cli-reference#cli-flags) 运行或在会话中运行 `/debug` 后317* 调试日志，当使用 [`--debug`](/zh-CN/cli-reference#cli-flags) 运行或在会话中运行 `/debug` 后

314* stderr，在使用 `-p` 启动的非交互式会话中318* stderr，在使用 `-p` 启动的非交互式会话中

315 319

443 447

444* `prompt.id`：UUID 将用户提示与所有后续事件关联到下一个提示。请参阅 [事件关联属性](#event-correlation-attributes)。448* `prompt.id`：UUID 将用户提示与所有后续事件关联到下一个提示。请参阅 [事件关联属性](#event-correlation-attributes)。

445* `workspace.host_paths`：在桌面应用中选择的主机工作区目录，作为字符串数组449* `workspace.host_paths`：在桌面应用中选择的主机工作区目录，作为字符串数组

450* `workflow.run_id`：运行标识符，前缀为 `wf_`，在属于 [Workflow](/zh-CN/workflows) 工具运行的代理发出的 API 和工具事件上。按一个 `workflow.run_id` 过滤事件可以重建该运行的 API 请求和工具结果。标识符涵盖工作流脚本生成的代理以及这些代理依次生成的任何代理，例如技能调用。它与 Workflow 工具结果中报告的运行标识符匹配。在所有其他事件上不存在。{/* min-version: 2.1.202 */}需要 Claude Code v2.1.202 或更高版本

451* `workflow.name`：工作流的名称，其脚本的 `meta.name`，与 `workflow.run_id` 一起发出。内置工作流名称在运行执行未修改的内置脚本时按原样出现。用户创作的名称（包括内置脚本的编辑副本）被替换为 `custom`，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`。{/* min-version: 2.1.202 */}需要 Claude Code v2.1.202 或更高版本

446 452

447<h3 id="metrics">453<h3 id="metrics">

448 指标454 指标

884 内部错误事件890 内部错误事件

885</h4>891</h4>

886 892

887当 Claude Code 捕获意外的内部错误时记录。仅记录错误类名和 errno 风格的代码。永远不包括错误消息和堆栈跟踪。在针对 Bedrock、Vertex 或 Foundry 运行或设置了 `DISABLE_ERROR_REPORTING` 时不会发出此事件。893当 Claude Code 捕获意外的内部错误时记录。仅记录错误类名和 errno 风格的代码。永远不包括错误消息和堆栈跟踪。在针对 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 运行或设置了 `DISABLE_ERROR_REPORTING` 时不会发出此事件。

888 894

889**事件名称**：`claude_code.internal_error`895**事件名称**：`claude_code.internal_error`

890 896

1163* 通过 `skill.name`、`plugin.name` 和 `agent.name` 属性将支出归属于特定技能、插件或子代理类型1169* 通过 `skill.name`、`plugin.name` 和 `agent.name` 属性将支出归属于特定技能、插件或子代理类型

1164 1170

1165<Note>1171<Note>

1166 成本指标是近似值。有关官方计费数据，请参阅您的 API 提供商（Claude 控制台、Amazon Bedrock 或 Google Cloud Vertex）。1172 成本指标是近似值。有关官方计费数据，请参阅您的 API 提供商（Claude 控制台、Amazon Bedrock 或 Google Cloud 的 Agent Platform）。

1167</Note>1173</Note>

1168 1174

1169<h3 id="alerting-and-segmentation">1175<h3 id="alerting-and-segmentation">

1176* 异常的令牌消耗1182* 异常的令牌消耗

1177* 来自特定用户的高会话量1183* 来自特定用户的高会话量

1178 1184

1179所有指标都可以按[标准属性](#standard-attributes)进行分段。`model` 属性在 `claude_code.token.usage`、`claude_code.cost.usage` 上可用，以及从 v2.1.172 开始，`claude_code.lines_of_code.count` 上也可用。代码行数或提交的按模型分解只能通过在 `session.id` 上与令牌或成本指标进行联接来近似，因为一个会话可以跨越多个模型。筛选令牌或成本端的行，使 `query_source` 为 `"main"`，以便辅助和子代理请求不会将会话的提交归属于未进行这些提交的模型。1185所有指标都可以按[标准属性](#standard-attributes)进行分段。`model` 属性在 `claude_code.token.usage`、`claude_code.cost.usage` 上可用，以及从 v2.1.172 开始，`claude_code.lines_of_code.count` 上也可用。

1186

1187按模型的提交分解只能通过在 `session.id` 上与令牌或成本指标进行联接来近似，因为一个会话可以跨越多个模型。筛选令牌或成本端的行，使 `query_source` 为 `"main"`，以便辅助和子代理请求不会将会话的提交归属于未进行这些提交的模型。

1180 1188

1181<h3 id="detect-retry-exhaustion">1189<h3 id="detect-retry-exhaustion">

1182 检测重试耗尽1190 检测重试耗尽

1217 1225

1218MCP 工具调用、Bash 命令和文件编辑因此归属于启动会话的开发人员。Claude Code 不在单独的服务账户下运行；每个事件上记录的身份是开发人员自己的 Claude 账户，或开发人员在 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话上的 IdP 身份。1226MCP 工具调用、Bash 命令和文件编辑因此归属于启动会话的开发人员。Claude Code 不在单独的服务账户下运行；每个事件上记录的身份是开发人员自己的 Claude 账户，或开发人员在 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话上的 IdP 身份。

1219 1227

1220当 Claude Code 使用直接 API 密钥进行身份验证，或针对 Bedrock、Vertex AI 或 Microsoft Foundry 进行身份验证时，会话中没有 Claude 账户，仅填充 `user.id` 和 `session.id`。在这些部署中，使用 `OTEL_RESOURCE_ATTRIBUTES` 自己附加用户身份，通过 [托管设置](#administrator-configuration) 文件或启动包装器按用户设置。Claude apps gateway 会话不需要任何这些：CLI 自动标记 IdP 身份，如 [标准属性](#standard-attributes) 中所述。1228当 Claude Code 使用直接 API 密钥进行身份验证，或针对 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 进行身份验证时，会话中没有 Claude 账户，仅填充 `user.id` 和 `session.id`。在这些部署中，使用 `OTEL_RESOURCE_ATTRIBUTES` 自己附加用户身份，通过 [托管设置](#administrator-configuration) 文件或启动包装器按用户设置。Claude apps gateway 会话不需要任何这些：CLI 自动标记 IdP 身份，如 [标准属性](#standard-attributes) 中所述。

1221 1229

1222```bash theme={null}1230```bash theme={null}

1223export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."1231export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."

1352 在 Amazon Bedrock 上监控 Claude Code1360 在 Amazon Bedrock 上监控 Claude Code

1353</h2>1361</h2>

1354 1362

1355有关 Amazon Bedrock 的 Claude Code 使用情况监控指南的详细信息，请参阅 [Claude Code 监控实现 (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)。1363有关 Amazon Bedrock 的 Claude Code 使用情况监控指南的详细信息，请参阅 [Claude Code 监控实现 (Amazon Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)。

network-config.md +3 −1

Details

110export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"110export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

111```111```

112 112

113Claude Code 在启动时读取证书和密钥文件，并在每次应用设置时重新读取它们，包括在会话期间设置更改时。要轮换证书和密钥，请替换相同路径上的文件。

114

113<h2 id="network-access-requirements">115<h2 id="network-access-requirements">

114 网络访问要求116 网络访问要求

115</h2>117</h2>

131 133

132Claude Code 默认还会发送可选的操作遥测数据，您可以使用环境变量禁用它。请参阅 [遥测服务](/zh-CN/data-usage#telemetry-services) 了解如何在最终确定您的白名单之前禁用它。134Claude Code 默认还会发送可选的操作遥测数据，您可以使用环境变量禁用它。请参阅 [遥测服务](/zh-CN/data-usage#telemetry-services) 了解如何在最终确定您的白名单之前禁用它。

133 135

134使用 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Vertex AI](/zh-CN/google-vertex-ai)、[Microsoft Foundry](/zh-CN/microsoft-foundry) 或已登录的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话时，模型流量和身份验证会转到您的提供商或网关，而不是 `api.anthropic.com`、`claude.ai` 或 `platform.claude.com`。WebFetch 工具仍会调用 `api.anthropic.com` 进行其 [域名安全检查](/zh-CN/data-usage#webfetch-domain-safety-check)，除非您在 [settings](/zh-CN/settings) 中设置 `skipWebFetchPreflight: true`。136使用 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-CN/google-vertex-ai)、[Microsoft Foundry](/zh-CN/microsoft-foundry) 或已登录的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话时，模型流量和身份验证会转到您的提供商或网关，而不是 `api.anthropic.com`、`claude.ai` 或 `platform.claude.com`。WebFetch 工具仍会调用 `api.anthropic.com` 进行其 [域名安全检查](/zh-CN/data-usage#webfetch-domain-safety-check)，除非您在 [settings](/zh-CN/settings) 中设置 `skipWebFetchPreflight: true`。

135 137

136[Claude Code on the web](/zh-CN/claude-code-on-the-web) 和 [Code Review](/zh-CN/code-review) 从 Anthropic 管理的基础设施连接到您的存储库。如果您的 GitHub Enterprise Cloud 组织按 IP 地址限制访问，请启用 [已安装 GitHub Apps 的 IP 允许列表继承](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps)。Claude GitHub App 注册了其 IP 范围，因此启用此设置允许访问而无需手动配置。要 [手动将范围添加到您的允许列表](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address)，或配置其他防火墙，请参阅 [Anthropic API IP 地址](https://platform.claude.com/docs/en/api/ip-addresses)。138[Claude Code on the web](/zh-CN/claude-code-on-the-web) 和 [Code Review](/zh-CN/code-review) 从 Anthropic 管理的基础设施连接到您的存储库。如果您的 GitHub Enterprise Cloud 组织按 IP 地址限制访问，请启用 [已安装 GitHub Apps 的 IP 允许列表继承](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps)。Claude GitHub App 注册了其 IP 范围，因此启用此设置允许访问而无需手动配置。要 [手动将范围添加到您的允许列表](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address)，或配置其他防火墙，请参阅 [Anthropic API IP 地址](https://platform.claude.com/docs/en/api/ip-addresses)。

137 139

overview.md +3 −3

Details

12 开始使用12 开始使用

13</h2>13</h2>

14 14

15选择你的环境来开始使用。大多数界面需要 [Claude 订阅](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=overview_pricing) 或 [Anthropic 控制台](https://console.anthropic.com/) 账户。终端 CLI 和 VS Code 也支持[第三方提供商](/zh-CN/third-party-integrations)。15Claude Code 在多个平台上运行：终端、IDE 扩展、桌面应用和网络。从下面的标签页中选择一个来开始使用。大多数平台需要 [Claude 订阅](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=overview_pricing) 或 [Anthropic 控制台](https://console.anthropic.com/) 账户。终端 CLI 和 VS Code 也支持[第三方提供商](/zh-CN/third-party-integrations)。

16 16

17<Tabs>17<Tabs>

18 <Tab title="Terminal">18 <Tab title="Terminal">

221 在任何地方使用 Claude Code221 在任何地方使用 Claude Code

222</h2>222</h2>

223 223

224每个界面都连接到相同的底层 Claude Code 引擎，因此你的 CLAUDE.md 文件、设置和 MCP 服务器可在所有界面中工作。224每个[界面](/zh-CN/glossary#surface)都连接到相同的底层 Claude Code 引擎，因此你的 CLAUDE.md 文件、设置和 MCP 服务器可在所有界面中工作。

225 225

226除了上面的[终端](/zh-CN/quickstart)、[VS Code](/zh-CN/vs-code)、[JetBrains](/zh-CN/jetbrains)、[桌面](/zh-CN/desktop)和[网络](/zh-CN/claude-code-on-the-web)环境外，Claude Code 还与 CI/CD、聊天和浏览器工作流集成：226除了上面的[终端](/zh-CN/quickstart)、[VS Code](/zh-CN/vs-code)、[JetBrains](/zh-CN/jetbrains)、[桌面](/zh-CN/desktop)和[网络](/zh-CN/claude-code-on-the-web)界面外，Claude Code 还与 CI/CD、聊天和浏览器工作流集成：

227 227

228| 我想要... | 最佳选项 |228| 我想要... | 最佳选项 |

229| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |229| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |

permission-modes.md +47 −22

Details

6 6

7> 控制 Claude 在编辑文件或运行命令前是否询问。在 CLI 中使用 Shift+Tab 循环切换模式，或在 VS Code、Desktop 和 claude.ai 中使用模式选择器。7> 控制 Claude 在编辑文件或运行命令前是否询问。在 CLI 中使用 Shift+Tab 循环切换模式，或在 VS Code、Desktop 和 claude.ai 中使用模式选择器。

8 8

9当 Claude 想要编辑文件、运行 shell 命令或发出网络请求时，它会暂停并要求您批准该操作。权限模式控制暂停发生的频率。您选择的模式塑造了会话的流程：默认模式让您在操作进行时审查每个操作，而更宽松的模式让 Claude 在更长的不间断时间内工作，然后报告完成情况。为敏感工作选择更多监督，或在您信任方向时选择更少中断。9当 Claude 想要编辑文件、运行 shell 命令或发出网络请求时，它会暂停并要求您批准该操作。权限模式控制暂停发生的频率。您选择的模式塑造了会话的流程：Manual mode 让您在操作进行时审查每个操作，而更宽松的模式让 Claude 在更长的不间断时间内工作，然后报告完成情况。为敏感工作选择更多监督，或在您信任方向时选择更少中断。

10 10

11<h2 id="available-modes">11<h2 id="available-modes">

12 可用模式12 可用模式

16 16

17| 模式 | 无需询问即可运行的操作 | 最适合 |17| 模式 | 无需询问即可运行的操作 | 最适合 |

18| :------------------------------------------------------------------ | :-------------------------------------------- | :----------- |18| :------------------------------------------------------------------ | :-------------------------------------------- | :----------- |

21| [`plan`](#analyze-before-you-edit-with-plan-mode) | 仅读取 | 在更改代码库前进行探索 |21| [`plan`](#analyze-before-you-edit-with-plan-mode) | 仅读取 | 在更改代码库前进行探索 |

25 25

26在 CLI、`claude --help` 中以及 VS Code 和 JetBrains 扩展中，审查每个操作的模式被命名为 **Manual**。其配置值为 `default`，这是 hooks 和 SDK 集成使用的值。CLI 在您输入值的任何地方都接受 `manual` 作为别名，例如 `claude --permission-mode manual` 或 `"defaultMode": "manual"`。Manual 标签和 `manual` 别名需要 Claude Code v2.1.200 或更高版本。

26在除 `bypassPermissions` 外的每种模式中，对[受保护路径](#protected-paths)的写入永远不会自动批准，保护仓库状态和 Claude 自己的配置免受意外破坏。28在除 `bypassPermissions` 外的每种模式中，对[受保护路径](#protected-paths)的写入永远不会自动批准，保护仓库状态和 Claude 自己的配置免受意外破坏。

27 29

28模式设置基线。在顶部分层[权限规则](/zh-CN/permissions#manage-permissions)以预先批准或阻止特定工具。拒绝规则和显式询问规则适用于每种模式，包括 `bypassPermissions`。允许规则在该模式中无效，因为其他所有操作都已被批准。30模式设置基线。在顶部分层[权限规则](/zh-CN/permissions#manage-permissions)以预先批准或阻止特定工具。拒绝规则和显式询问规则适用于每种模式，包括 `bypassPermissions`。允许规则在该模式中无效，因为其他所有操作都已被批准。

35 37

36<Tabs>38<Tabs>

37 <Tab title="CLI">39 <Tab title="CLI">

~~38 **在会话期间**：按 `Shift+Tab` 循环切换 `default` → `acceptEdits` → `plan`。当前模式显示在状态栏中。并非每种模式都在默认循环中：~~40 **在会话期间**：按 `Shift+Tab` 循环切换 `default` → `acceptEdits` → `plan`。当前模式显示在状态栏中。{/* min-version: 2.1.203 */}Manual 模式（即循环中的 `default`）显示灰色的 `⏸ manual mode on` 徽章。在 v2.1.203 之前，状态栏在 Manual 模式下不显示徽章。

42 并非每种模式都在默认循环中：

39 43

40 * `auto`：当您的账户满足 [auto mode 要求](#eliminate-prompts-with-auto-mode)时出现；循环到它会在不确认提示的情况下切换模式44 * `auto`：当您的账户满足 [auto mode 要求](#eliminate-prompts-with-auto-mode)时出现；循环到它会在不确认提示的情况下切换模式

41 * `bypassPermissions`：在您使用 `--permission-mode bypassPermissions`、`--dangerously-skip-permissions` 或 `--allow-dangerously-skip-permissions` 启动后出现；`--allow-` 变体将模式添加到循环中而不激活它45 * `bypassPermissions`：在您使用 `--permission-mode bypassPermissions`、`--dangerously-skip-permissions` 或 `--allow-dangerously-skip-permissions` 启动后出现；`--allow-` 变体将模式添加到循环中而不激活它

71 75

72 | UI 标签 | 模式 |76 | UI 标签 | 模式 |

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

75 | Edit automatically | `acceptEdits` |79 | Edit automatically | `acceptEdits` |

78 | Bypass permissions | `bypassPermissions` |82 | Bypass permissions | `bypassPermissions` |

79 83

84 在 v2.1.205 之前，扩展将 `plan` 标记为 Plan mode，将 `auto` 标记为 Auto mode。

80 当您的账户满足 [auto mode 部分](#eliminate-prompts-with-auto-mode)中列出的每个要求时，Auto mode 出现在模式指示器中。`claudeCode.initialPermissionMode` 设置不接受 `auto`。要默认以 auto mode 启动，请改为在您的[用户设置](/zh-CN/settings#settings-files)中设置 `defaultMode`。Claude Code 忽略项目和本地设置中的 `defaultMode: "auto"`。86 当您的账户满足 [auto mode 部分](#eliminate-prompts-with-auto-mode)中列出的每个要求时，Auto mode 出现在模式指示器中。`claudeCode.initialPermissionMode` 设置不接受 `auto`。要默认以 auto mode 启动，请改为在您的[用户设置](/zh-CN/settings#settings-files)中设置 `defaultMode`。Claude Code 忽略项目和本地设置中的 `defaultMode: "auto"`。

81 87

82 Bypass permissions 需要扩展设置中的**允许危险地跳过权限**切换才能在模式指示器中出现。88 Bypass permissions 需要扩展设置中的**允许危险地跳过权限**切换才能在模式指示器中出现。

95 <Tab title="Web and mobile">101 <Tab title="Web and mobile">

96 在 [claude.ai/code](https://claude.ai/code) 或移动应用中使用提示框旁边的模式下拉菜单。权限提示出现在 claude.ai 中以供批准。哪些模式出现取决于会话在哪里运行：102 在 [claude.ai/code](https://claude.ai/code) 或移动应用中使用提示框旁边的模式下拉菜单。权限提示出现在 claude.ai 中以供批准。哪些模式出现取决于会话在哪里运行：

97 103

98 * **云会话**在 [Claude Code on the web](/zh-CN/claude-code-on-the-web)：Accept edits、Plan mode 和 Auto mode。Accept edits 对应于 `default` 模式：云环境预先批准文件编辑，无论模式如何，因此下拉菜单显示 Accept edits 而不是 Ask permissions。来自设置的 `defaultMode: "acceptEdits"` 仍然被遵守。Auto mode 仅在您的组织允许且所选模型支持时出现。Bypass permissions 不可用。104 * **云会话**在 [Claude Code on the web](/zh-CN/claude-code-on-the-web)：Accept edits、Plan 和 Auto。Accept edits 对应于 `default` 模式：云环境预先批准文件编辑，无论模式如何，因此下拉菜单显示 Accept edits 而不是 Manual。来自设置的 `defaultMode: "acceptEdits"` 仍然被遵守。Auto mode 仅在您的组织允许且所选模型支持时出现。Bypass permissions 不可用。

~~99 * **[Remote Control](/zh-CN/remote-control) 会话**在您的本地机器上：Ask permissions、Auto accept edits 和 Plan mode。Auto 和 Bypass permissions 不可用。~~105 * **[Remote Control](/zh-CN/remote-control) 会话**在您的本地机器上：Manual、Accept edits 和 Plan。您无法从应用中选择 Auto 或 Bypass permissions。{/* min-version: 2.1.202 */}下拉菜单显示本地会话所在的模式，包括从终端设置的模式，并在应用或终端中模式更改时更新。唯一的例外是 Bypass permissions：会话永远不会向 claude.ai 报告该模式，因此从终端切换到它不会改变下拉菜单显示的内容。在 v2.1.202 之前，使用 `/remote-control` 或 `claude --remote-control` 连接的会话根本不报告其模式，因此 claude.ai 和移动应用可能显示会话不在的模式。不匹配仅影响标签：Claude Code 从会话的实际模式生成权限提示，仍然出现在应用中以供批准。

100 106

101 对于 Remote Control，您也可以在启动主机时设置起始模式：107 对于 Remote Control，您也可以在启动主机时设置起始模式：

102 108

116 122

117当启用 [PowerShell tool](/zh-CN/tools-reference#powershell-tool) 时，`acceptEdits` mode 也会自动批准 `Set-Content`、`Add-Content`、`Clear-Content` 和 `Remove-Item` 在范围内的路径上，以及它们的常见别名。相同的范围和受保护路径规则适用。123当启用 [PowerShell tool](/zh-CN/tools-reference#powershell-tool) 时，`acceptEdits` mode 也会自动批准 `Set-Content`、`Add-Content`、`Clear-Content` 和 `Remove-Item` 在范围内的路径上，以及它们的常见别名。相同的范围和受保护路径规则适用。

118 124

119当您想在编辑器中或通过 `git diff` 之后审查更改而不是逐个批准每个编辑时，使用 `acceptEdits`。从默认模式按 `Shift+Tab` 一次进入它，或直接启动它：125当您想在编辑器中或通过 `git diff` 之后审查更改而不是逐个批准每个编辑时，使用 `acceptEdits`。从 Manual mode 按 `Shift+Tab` 一次进入它，或直接启动它：

120 126

121```bash theme={null}127```bash theme={null}

122claude --permission-mode acceptEdits128claude --permission-mode acceptEdits

126 使用 plan mode 在编辑前进行分析132 使用 plan mode 在编辑前进行分析

127</h2>133</h2>

128 134

129Plan mode 告诉 Claude 研究并提议更改而不进行更改。Claude 读取文件、运行 shell 命令进行探索，并编写计划，但不编辑您的源代码。权限提示的应用方式与默认模式相同。135Plan mode 告诉 Claude 研究并提议更改而不进行更改。Claude 读取文件、运行 shell 命令进行探索，并编写计划，但不编辑您的源代码。权限提示的应用方式与手动模式相同。

130 136

131通过按 `Shift+Tab` 或在单个提示前加上 `/plan` 进入 plan mode。您也可以从 CLI 以 plan mode 启动：137通过按 `Shift+Tab` 或在单个提示前加上 `/plan` 进入 plan mode。您也可以从 CLI 以 plan mode 启动：

132 138

188 194

189* **计划**：所有计划。195* **计划**：所有计划。

190* **所有者**：在 Team 和 Enterprise 上，所有者必须在 [Claude Code 管理员设置](https://claude.ai/admin-settings/claude-code)中启用它，然后用户才能打开它。管理员也可以通过在[托管设置](/zh-CN/permissions#managed-settings)中将 `permissions.disableAutoMode` 设置为 `"disable"` 来锁定它。196* **所有者**：在 Team 和 Enterprise 上，所有者必须在 [Claude Code 管理员设置](https://claude.ai/admin-settings/claude-code)中启用它，然后用户才能打开它。管理员也可以通过在[托管设置](/zh-CN/permissions#managed-settings)中将 `permissions.disableAutoMode` 设置为 `"disable"` 来锁定它。

191* **模型**：在 Anthropic API 上，Claude Opus 4.6 或更高版本，或 Sonnet 4.6 或更高版本。在 Amazon Bedrock、Google Cloud Vertex AI、Microsoft Foundry 和已登录的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话上，仅支持 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。不支持其他模型，包括 Sonnet 4.5、Opus 4.5、Haiku 和 claude-3 模型，在任何提供商上都不支持。197* **模型**：在 Anthropic API 上，Claude Opus 4.6 或更高版本，或 Sonnet 4.6 或更高版本。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登录的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话上，仅支持 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。不支持其他模型，包括 Sonnet 4.5、Opus 4.5、Haiku 和 claude-3 模型，在任何提供商上都不支持。

192* **提供商**：在 Anthropic API 上默认可用。在 Amazon Bedrock、Google Cloud Vertex AI、Microsoft Foundry 和已登录的 Claude apps gateway 会话上，auto mode 处于关闭状态，直到您[设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`](#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)。198* **提供商**：在 Anthropic API 上默认可用。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登录的 Claude apps gateway 会话上，auto mode 处于关闭状态，直到您[设置 `CLAUDE_CODE_ENABLE_AUTO_MODE`](#enable-auto-mode-on-bedrock-agent-platform-or-foundry)。

193 199

194如果 Claude Code 报告 auto mode 不可用，其中一个要求未满足；这不是暂时中断。一个单独的消息命名一个模型并说 auto mode "cannot determine the safety" 的操作是暂时分类器中断；请参阅[错误参考](/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)。200如果 Claude Code 报告 auto mode 不可用，其中一个要求未满足；这不是暂时中断。一个单独的消息命名一个模型并说 auto mode "cannot determine the safety" 的操作是暂时分类器中断；请参阅[错误参考](/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)。

195 201

196如果您在[设置](/zh-CN/settings#available-settings)中设置 `defaultMode: "auto"` 并且会话以 `default` 模式启动且没有错误，该设置可能在 `.claude/settings.json` 或 `.claude/settings.local.json` 中。Claude Code v2.1.142 及更高版本忽略来自这些文件的 `auto`，因此仓库无法授予自己 auto mode。将其移动到 `~/.claude/settings.json`。202如果您在[设置](/zh-CN/settings#available-settings)中设置 `defaultMode: "auto"` 并且会话以 `default` 模式启动且没有错误，该设置可能在 `.claude/settings.json` 或 `.claude/settings.local.json` 中。Claude Code v2.1.142 及更高版本忽略来自这些文件的 `auto`，因此仓库无法授予自己 auto mode。将其移动到 `~/.claude/settings.json`。

197 203

198<h3 id="enable-auto-mode-on-bedrock-vertex-ai-or-foundry">204<h3 id="enable-auto-mode-on-bedrock-agent-platform-or-foundry">

199 在 Bedrock、Vertex AI 或 Foundry 上启用 auto mode205 在 Bedrock、Agent Platform 或 Foundry 上启用 auto mode

200</h3>206</h3>

201 207

202在 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud Vertex AI](/zh-CN/google-vertex-ai)、[Microsoft Foundry](/zh-CN/microsoft-foundry) 和已登录的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话上，auto mode 不会出现在 `Shift+Tab` 循环中，直到 `CLAUDE_CODE_ENABLE_AUTO_MODE` 被设置为 `1`。该变量在 Claude Code v2.1.158 及更高版本中有效。仅在这些提供商上支持 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。208在 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-CN/google-vertex-ai)、[Microsoft Foundry](/zh-CN/microsoft-foundry) 和已登录的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 会话上，auto mode 不会出现在 `Shift+Tab` 循环中，直到 `CLAUDE_CODE_ENABLE_AUTO_MODE` 被设置为 `1`。该变量在 Claude Code v2.1.158 及更高版本中有效。仅在这些提供商上支持 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。

203 209

204要为一个开发者启用它，请将变量添加到 `~/.claude/settings.json` 中的 `env` 块：210要为一个开发者启用它，请将变量添加到 `~/.claude/settings.json` 中的 `env` 块：

205 211

223 分类器默认阻止的内容229 分类器默认阻止的内容

224</h3>230</h3>

225 231

226分类器信任您的工作目录和您的仓库的配置的远程。其他所有内容都被视为外部，直到您[配置受信任的基础设施](/zh-CN/auto-mode-config)。232分类器信任您的工作目录和会话启动时为其配置的远程。{/* min-version: 2.1.200 */}使用 `git remote add` 或 `git remote set-url` 在会话期间添加或重新指向的远程不受信任，其他所有内容都被视为外部，直到您[配置受信任的基础设施](/zh-CN/auto-mode-config)。在 v2.1.200 之前，会话中期添加的远程也受信任。

227 233

228**默认阻止**：234**默认阻止**：

229 235

234* 授予 IAM 或仓库权限240* 授予 IAM 或仓库权限

235* 修改共享基础设施241* 修改共享基础设施

236* 不可逆地销毁会话开始前存在的文件242* 不可逆地销毁会话开始前存在的文件

237* 强制推送或直接推送到 `main`243* 强制推送

238* {/* min-version: 2.1.182 */}`git reset --hard`、`git checkout -- .`、`git restore .`、`git clean -fd`、`git stash drop` 或 `git stash clear`，分类器推测这些会丢弃未提交的更改244* {/* min-version: 2.1.203 */}当推送携带敏感内容（如密钥或个人或受信任数据）、携带相对于您要求的隐瞒或误述的更改、携带从仓库外部导入或首次读取的内容，或绕过您要求的拉取请求、审查或检查时，推送到仓库的默认分支。纯粹推送到默认分支本身不被阻止，清除标记的推送需要命名标记的内容或绕过的审查，而不仅仅是推送。分类器是一层：[`permissions.deny` 规则](/zh-CN/permissions#manage-permissions)在每种模式下应用，可以完全阻止推送到默认分支，远程自己的分支保护仍然适用。在 v2.1.203 之前，任何直接推送到默认分支都被阻止

245* {/* min-version: 2.1.182 */}}`git reset --hard`、`git checkout -- .`、`git restore .`、`git clean -fd`、`git stash drop` 或 `git stash clear`，分类器推测这些会丢弃未提交的更改

239* `git commit --amend`，当 HEAD 处的提交不是在此会话中创建的246* `git commit --amend`，当 HEAD 处的提交不是在此会话中创建的

240* {/* min-version: 2.1.198 */}}从 v2.1.198 开始，`git commit --amend` 当 HEAD 处的提交已经被推送时。仅消息重述不被阻止：`--amend -m` 没有新暂存的内容，在 Claude 在此会话中创建的提交上247* {/* min-version: 2.1.198 */}从 v2.1.198 开始，`git commit --amend` 当 HEAD 处的提交已经被推送时。仅消息重述不被阻止：`--amend -m` 没有新暂存的内容，在 Claude 在此会话中创建的提交上

241* `terraform destroy`、`pulumi destroy`、`cdk destroy` 或 `terragrunt destroy`，以及应用会销毁资源的计划248* `terraform destroy`、`pulumi destroy`、`cdk destroy` 或 `terragrunt destroy`，以及应用会销毁资源的计划

242 249

243Claude Code v2.1.195 及更高版本默认阻止更多类别。其中几个取决于[环境](/zh-CN/auto-mode-config#define-trusted-infrastructure)条目，例如敏感的远程目标和受保护的 IaC 范围，您可以将其缩小到具体名称。250Claude Code v2.1.195 及更高版本默认阻止更多类别。其中几个取决于[环境](/zh-CN/auto-mode-config#define-trusted-infrastructure)条目，例如敏感的远程目标和受保护的 IaC 范围，您可以将其缩小到具体名称。

256* 绕过您的内部包注册表将包安装路由到公共注册表。{/* min-version: 2.1.198 */}从 v2.1.198 开始，这也适用于您在对话中告诉 Claude 内部注册表或镜像存在的情况，不仅仅是在您的环境中列出的情况263* 绕过您的内部包注册表将包安装路由到公共注册表。{/* min-version: 2.1.198 */}从 v2.1.198 开始，这也适用于您在对话中告诉 Claude 内部注册表或镜像存在的情况，不仅仅是在您的环境中列出的情况

257* 使用禁用安全防护的标志运行命令，如 `--insecure`264* 使用禁用安全防护的标志运行命令，如 `--insecure`

258* 启动自主代理循环，在没有人类批准或沙箱的情况下运行，例如使用 `--dangerously-skip-permissions` 或 `--no-sandbox` 启动的循环。{/* min-version: 2.1.198 */}从 v2.1.198 开始，这也涵盖运行第三方代理或评估工具，禁用隔离和按操作批准，例如使用 `--yes-always` 启动的运行器265* 启动自主代理循环，在没有人类批准或沙箱的情况下运行，例如使用 `--dangerously-skip-permissions` 或 `--no-sandbox` 启动的循环。{/* min-version: 2.1.198 */}从 v2.1.198 开始，这也涵盖运行第三方代理或评估工具，禁用隔离和按操作批准，例如使用 `--yes-always` 启动的运行器

259* [Chrome 中的 Claude](/zh-CN/chrome) 浏览器操作可能会发送页面内容、cookie 或凭证跨源266* [Chrome 中的 Claude](/zh-CN/chrome)浏览器操作可能会发送页面内容、cookie 或凭证跨源

260 267

261Claude Code v2.1.198 及更高版本也默认阻止这些：268Claude Code v2.1.198 及更高版本也默认阻止这些：

262 269

263* 通过通配符、glob 或年龄过滤器而不是特定命名路径删除 `/tmp`、`$TMPDIR` 或另一个共享暂存或缓存目录中的文件270* 通过通配符、glob 或年龄过滤器而不是特定命名路径删除 `/tmp`、`$TMPDIR` 或另一个共享暂存或缓存目录中的文件

264* 在您自己的消息未授权这些详情给该收件人时，在发送、上传、发布或写入其他人或共享系统的内容中包含敏感详情271* 在您自己的消息未授权这些详情给该收件人时，在发送、上传、发布或写入其他人或共享系统的内容中包含敏感详情。{/* min-version: 2.1.200 */}PR 和问题正文、提交消息和评论在仓库在信任边界外或公开时计为这种类型的出站内容，包括您组织自己的公开仓库；内部文件路径、代码名称、实时 API 响应数据（如电子邮件或账户标识符）和基础设施标识符计为敏感详情。PR、问题和提交消息范围需要 Claude Code v2.1.200 或更高版本。{/* min-version: 2.1.203 */}PR 或问题正文中的实时个人数据（如电子邮件地址、账户或组织标识符或使用指标）需要您命名这些详情和收件人，无论仓库的可见性或信任边界如何。该检查需要 Claude Code v2.1.203 或更高版本

265* 向 Claude Code 自己的 tmux 窗格发送击键以驱动其自己的界面，分类器将其视为 Claude 改变自己的权限或监督272* 向 Claude Code 自己的 tmux 窗格发送击键以驱动其自己的界面，分类器将其视为 Claude 改变自己的权限或监督

266 273

274Claude Code v2.1.200 及更高版本也默认阻止这些：

275

276* 注释掉、删除或强制通过保护安全行为的测试或断言，例如身份验证、访问控制、输入验证或沙箱

277* 删除或拆除 Claude 在会话中未创建的有状态资源，当没有更具体的删除规则适用且您未命名该资源时

278* 将 API 基础 URL、代理端点、webhook 接收器或注册表镜像重新指向不适合任务的第三方主机，包括在示例文件（如 `.env.example`）中

279* 使用 `git remote set-url` 或 `git remote add` 改变推送去向，除非您命名了新远程

280* 推送密钥或个人或受信任数据到已知为公开的仓库，或推送不是该仓库自己工作一部分的机密材料到那里。{/* min-version: 2.1.203 */}dotfiles 仓库自己的主题是个人或受信任数据的唯一例外，来自私有仓库到任何公开表面的内容以相同方式被阻止；两个改进都需要 Claude Code v2.1.203 或更高版本。在 v2.1.203 之前，个人数据与机密材料分组，仅在不是该仓库自己工作的一部分时被阻止。当仓库的可见性未确定时，分类器不会仅基于此阻止；它改为根据其他规则判断内容

281* 针对不同的仓库或组织打开拉取请求、使用 `gh repo fork` 进行分叉或推送到第三方仓库，除非您命名了该外部目标

282

283Claude Code v2.1.203 及更高版本也默认阻止这些：

284

285* 来自敏感本地存储或来自其名称、路径或类型将其标记为敏感的文件的内容进入提交、推送、PR 或问题文本、gist 或粘贴或包发布，除非您命名了源和目标。会话记录和对话日志、凭证和配置点文件夹（如 SSH 密钥、云凭证、浏览器配置文件和 shell 历史记录）以及用户数据导出都计为此类，仓库是私有的不会清除它

286

287Claude Code v2.1.205 及更高版本也默认阻止这些：

288

289* 写入 Claude Code 会话记录、`~/.claude/projects/` 下的 `.jsonl` 历史文件或您配置的配置目录，无论是直接还是通过 shell 命令。该规则也涵盖 Claude Code 为其自己的检查附加到每个记录条目的元数据行。记录是 Claude Code 写入的会话状态，而不是工作文件，篡改的条目在您恢复会话后到达每个后续检查，因此 auto mode 作为深度防御阻止这些写入。读取记录不被阻止

290* 递归强制删除，例如 `rm -rf "$VAR"` 或 `Remove-Item -Recurse -Force $dir`，其目标是 shell 变量或以其为根的 glob，在分类器看到的对话中任何地方都未分配。该值仅来自早期命令输出，分类器永远不会收到，因此分类器无法根据其他删除规则验证删除目标。分类器按设计读取对话而不是命令输出，因此它阻止调用而不是猜测目标。当您命名被删除的确切路径或当 Claude 使用写入命令中的已解析文字路径重新运行删除时，阻止清除。目标分类器可以解析的删除不受影响

291

267**默认允许**：292**默认允许**：

268 293

269* 工作目录中的本地文件操作294* 工作目录中的本地文件操作

278* 作为您的任务的一部分读取、审查或编写与安全相关的代码、配置和威胁模型303* 作为您的任务的一部分读取、审查或编写与安全相关的代码、配置和威胁模型

279* 在同一多代理会话中协同工作的代理之间的消息304* 在同一多代理会话中协同工作的代理之间的消息

280* 向您在 [`environment`](/zh-CN/auto-mode-config#define-trusted-infrastructure) 中列出的受信任域、桶和服务发送数据。这仅涵盖数据流，不涵盖相同基础设施上的破坏性或凭证操作305* 向您在 [`environment`](/zh-CN/auto-mode-config#define-trusted-infrastructure) 中列出的受信任域、桶和服务发送数据。这仅涵盖数据流，不涵盖相同基础设施上的破坏性或凭证操作

281* [Chrome 中的 Claude](/zh-CN/chrome) 导航到受信任的内部域、localhost 或您命名的 URL306* [Chrome 中的 Claude](/zh-CN/chrome)导航到受信任的内部域、localhost 或您命名的 URL

282 307

283Sandbox 网络访问请求通过分类器路由而不是默认允许。{/* min-version: 2.1.198 */}从 v2.1.198 开始，分类器重用其对网络主机和端口的判决，而不是在每次连接时重新运行：308Sandbox 网络访问请求通过分类器路由而不是默认允许。{/* min-version: 2.1.198 */}从 v2.1.198 开始，分类器重用其对网络主机和端口的判决，而不是在每次连接时重新运行：

284 309

permissions.md +32 −6

Details

47Claude Code 支持多种权限模式来控制工具的批准方式。请参阅[权限模式](/zh-CN/permission-modes)了解何时使用每种模式。在您的[设置文件](/zh-CN/settings#settings-files)中设置 `defaultMode`：47Claude Code 支持多种权限模式来控制工具的批准方式。请参阅[权限模式](/zh-CN/permission-modes)了解何时使用每种模式。在您的[设置文件](/zh-CN/settings#settings-files)中设置 `defaultMode`：

48 48

49| 模式 | 描述 |49| 模式 | 描述 |

~~50| :------------------ | :------------------------------------------------------------------------------- |~~50| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |

~~51| `default` | 标准行为：在首次使用每个工具时提示权限 |~~51| `default` | 标准行为：在首次使用每个工具时提示权限。{/* min-version: 2.1.200 */}在 CLI 和 VS Code 及 JetBrains 扩展中标记为 Manual，Claude Code 接受 `manual` 作为别名。标签和别名需要 Claude Code v2.1.200 或更高版本 |

215 215

216对于每个标志都是只读的命令，允许未引用的 glob 模式，因此 `ls *.ts` 和 `wc -l src/*.py` 无需提示即可运行。带有写入能力或执行能力标志的命令，如 `find`、`sort`、`sed` 和 `git`，在存在未引用的 glob 时仍然提示，因为 glob 可能扩展为像 `-delete` 这样的标志。216对于每个标志都是只读的命令，允许未引用的 glob 模式，因此 `ls *.ts` 和 `wc -l src/*.py` 无需提示即可运行。带有写入能力或执行能力标志的命令，如 `find`、`sort`、`sed` 和 `git`，在存在未引用的 glob 时仍然提示，因为 glob 可能扩展为像 `-delete` 这样的标志。

217 217

218`cd` 进入工作目录或[其他目录](#working-directories)内的路径也是只读的。像 `cd packages/api && ls` 这样的复合命令在每个部分都符合条件时无需提示即可运行。在一个复合命令中组合 `cd` 和 `git` 总是提示，无论目标目录如何。218`cd` 进入工作目录或[其他目录](#working-directories)内的路径也是只读的。像 `cd packages/api && ls` 这样的复合命令在每个部分都符合条件时无需提示即可运行。在一个复合命令中组合 `cd` 和 `git` 时，当 `cd` 改变到不同目录时会提示，因为在新目录中运行 `git` 可以执行该目录的钩子。`cd` 的目标解析到当前工作目录是无操作的，不会触发此提示。

219 219

220<Warning>220<Warning>

221 尝试约束命令参数的 Bash 权限模式很脆弱。例如，`Bash(curl http://github.com/ *)` 旨在将 curl 限制为 GitHub URL，但不会匹配以下变体：221 尝试约束命令参数的 Bash 权限模式很脆弱。例如，`Bash(curl http://github.com/ *)` 旨在将 curl 限制为 GitHub URL，但不会匹配以下变体：

222 222

223 * URL 前的选项：`curl -X GET http://github.com/...`223 * URL 前的选项：`curl -X GET http://github.com/...`

224 * 不同的协议：`curl https://github.com/...`224 * 不同的协议：`curl https://github.com/...`

225 * 重定向：`curl -L http://bit.ly/xyz`（重定向到 GitHub）225 * 重定向：`curl -L http://bit.ly/xyz`，重定向到 GitHub

226 * 变量：`URL=http://github.com && curl $URL`226 * 变量：`URL=http://github.com && curl $URL`

227 * 额外空格：`curl http://github.com`227 * 额外空格：`curl http://github.com`

228 228

310| `Read(//**/.env)` | 文件系统上任何地方的任何 `.env` | 无；规则锚定在文件系统根目录 |310| `Read(//**/.env)` | 文件系统上任何地方的任何 `.env` | 无；规则锚定在文件系统根目录 |

311 311

312<Note>312<Note>

313 在 gitignore 模式中，`*` 匹配单个目录中的文件，而 `**` 递归匹配目录。要允许所有文件访问，只需使用工具名称而不带括号：`Read`、`Edit` 或 `Write`。313 在 gitignore 模式中，`*` 匹配单个路径段内的文本，可以出现在模式中的任何位置，而 `**` 匹配跨目录。要允许所有文件访问，只需使用工具名称而不带括号：`Read`、`Edit` 或 `Write`。

314</Note>314</Note>

315 315

316当您使用"是，不再询问"批准文件路径时，Claude Code 会转义该路径中的 gitignore 模式字符，如 `[`、`]` 和 `*`，因此生成的规则仅匹配您批准的字面路径。您自己编写的规则不会被转义。在 v2.1.202 之前，Claude Code 保存未转义的路径，因此为名为 `[2024-06] Reports` 的目录生成的规则可能无法匹配其自己的路径或匹配意外的兄弟目录。

317

316当 Claude 访问符号链接时，权限规则检查两个路径：符号链接本身和它解析到的文件。Allow 和 deny 规则对该对的处理方式不同：allow 规则回退到提示您，而 deny 规则直接阻止。318当 Claude 访问符号链接时，权限规则检查两个路径：符号链接本身和它解析到的文件。Allow 和 deny 规则对该对的处理方式不同：allow 规则回退到提示您，而 deny 规则直接阻止。

317 319

318* **Allow 规则**：仅在符号链接路径及其目标都匹配时适用。允许目录内的符号链接指向其外部仍然会提示您。320* **Allow 规则**：仅在符号链接路径及其目标都匹配时适用。允许目录内的符号链接指向其外部仍然会提示您。

505 507

506嵌入主机可以在 [`parentSettingsBehavior`](/zh-CN/settings#settings-precedence) 设置为 `"merge"` 时，通过 SDK `managedSettings` 选项提供额外的托管策略；嵌入器值可以收紧策略但不能放松它。508嵌入主机可以在 [`parentSettingsBehavior`](/zh-CN/settings#settings-precedence) 设置为 `"merge"` 时，通过 SDK `managedSettings` 选项提供额外的托管策略；嵌入器值可以收紧策略但不能放松它。

507 509

510<h2 id="project-allow-rules-and-workspace-trust">

511 项目允许规则和工作区信任

512</h2>

513

514项目的 `.claude/settings.json` 中的 `permissions.allow` 规则和 `permissions.additionalDirectories` 条目授予功能，因此 Claude Code 仅在您接受该工作区的[工作区信任对话框](/zh-CN/security#additional-safeguards)后才应用它们。在此之前，Claude Code 会读取规则但不应用它们。信任对话框列出了该文件夹将授予的允许规则和其他目录，以便您可以在接受前查看它们。`deny` 和 `ask` 规则不受影响，因为它们仅限制。

515

516Claude Code 按工作区保存信任，以 git 存储库根目录为键，或在存储库外，以您启动 Claude Code 的目录为键。当您从主目录启动时，信任仅在当前会话期间保持，不会写入磁盘；请参阅[其他保护措施](/zh-CN/security#additional-safeguards)说明。信任父目录不会应用嵌套项目的允许规则。

517

518`.claude/settings.local.json` 是您自己的文件，因此工作区信任检查通常不适用于它。当存储库可能提供了该文件时，例如当它提交到 git 或 `.claude` 是符号链接时，其允许规则和其他目录会像项目设置一样通过信任检查。

519

520`.claude/settings.local.json` 中的允许规则和其他目录在两种情况下也可以在没有工作区信任的情况下应用：

521

522* 您启动 Claude Code 的目录不在 git 存储库内。

523* 会话在您自己的配置主目录中运行：您的主目录或任何您已将其 `.claude` 子目录设置为 [`CLAUDE_CONFIG_DIR`](/zh-CN/env-vars) 的目录。

524

525在这两种情况下，该文件都是您创建的，而不是存储库可能提供的文件，并且存储库提交的 `.claude/settings.local.json` 仍然需要工作区信任。版本 2.1.196 至 2.1.199 在这些工作区中将该文件视为存储库提供的文件，忽略其允许规则，并向 stderr 打印 [`this workspace has not been trusted`](/zh-CN/errors#workspace-has-not-been-trusted) 警告。上述两个例外与 v2.1.195 及更早版本相匹配，并在 v2.1.200 中恢复。

526

527同样从 v2.1.200 开始，一个工作区的允许规则或其他目录仍未被应用，但由于父目录已被信任而从未显示信任对话框，会在您下次在那里交互式启动 Claude Code 时显示对话框。对话框提供两个选择：

528

529* **Yes, I trust this folder**：保存该工作区的信任并在同一会话中应用规则。

530* **No, continue without these permissions**：继续工作，忽略这些规则。对话框将在下一个会话中再次出现。

531

532在[非交互模式](/zh-CN/headless)中使用 `-p`，不会出现对话框，规则保持被忽略。

533

508<h2 id="example-configurations">534<h2 id="example-configurations">

509 示例配置535 示例配置

510</h2>536</h2>

platforms.md +1 −1

Details

25 25

26CLI 是终端原生工作的最完整界面：脚本编写和 Agent SDK 仅限 CLI。第三方提供商也可在 [VS Code](/zh-CN/vs-code#use-third-party-providers) 中使用。企业 [Desktop](/zh-CN/desktop) 部署支持 Vertex AI 和网关提供商；对于 Bedrock 或 Foundry，请使用 CLI 或 VS Code，或 [Cowork on 3P research preview](https://claude.com/docs/cowork/3p/overview)，它在这些提供商上运行 Code 选项卡。Desktop 和 IDE 扩展为了视觉审查和更紧密的编辑器集成而放弃了一些仅限 CLI 的功能。Web 在 Anthropic 的云中运行，因此任务在您断开连接后继续进行。Mobile 是这些相同云会话的瘦客户端，或通过 Remote Control 进入本地会话，并可以使用 Dispatch 向 Desktop 发送任务。26CLI 是终端原生工作的最完整界面：脚本编写和 Agent SDK 仅限 CLI。第三方提供商也可在 [VS Code](/zh-CN/vs-code#use-third-party-providers) 中使用。企业 [Desktop](/zh-CN/desktop) 部署支持 Google Cloud 的 Agent Platform 和网关提供商；对于 Amazon Bedrock 或 Microsoft Foundry，请使用 CLI 或 VS Code，或 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)，它在这些提供商上运行 Code 选项卡。Desktop 和 IDE 扩展为了视觉审查和更紧密的编辑器集成而放弃了一些仅限 CLI 的功能。Web 在 Anthropic 的云中运行，因此任务在您断开连接后继续进行。Mobile 是这些相同云会话的瘦客户端，或通过 Remote Control 进入本地会话，并可以使用 Dispatch 向 Desktop 发送任务。

27 27

28您可以在同一项目上混合使用多个界面。配置、项目内存和 MCP 服务器在本地界面之间共享。28您可以在同一项目上混合使用多个界面。配置、项目内存和 MCP 服务器在本地界面之间共享。

29 29

plugin-dependencies.md +2 −2

Details

125| `~2.1` | `~3.0` | 插件 B 的安装失败，显示 `range-conflict`。插件 A 和依赖保持原样。 |125| `~2.1` | `~3.0` | 插件 B 的安装失败，显示 `range-conflict`。插件 A 和依赖保持原样。 |

126| `=2.1.0` | 无 | 依赖保持在 `2.1.0`。在安装了插件 A 时，自动更新会跳过较新版本。 |126| `=2.1.0` | 无 | 依赖保持在 `2.1.0`。在安装了插件 A 时，自动更新会跳过较新版本。 |

127 127

128自动更新在满足每个已安装插件范围的最高 git 标签处获取受约束的依赖，而不是在 marketplace 的最新版本处，因此依赖继续在其允许的范围内接收更新。如果没有标签满足所有范围，更新会被跳过，跳过消息会出现在 `/doctor` 和 `/plugin` 错误选项卡中，并命名约束插件。128自动更新在满足每个已安装插件范围的最高 git 标签处获取受约束的依赖，而不是在 marketplace 的最新版本处，因此依赖继续在其允许的范围内接收更新。如果没有标签满足所有范围，自动更新会跳过该依赖，并在 `/plugin` 错误选项卡中列出跳过情况，命名约束插件。

129 129

130当你卸载最后一个约束依赖的插件时，该依赖不再被保持，并在下次更新时恢复跟踪其 marketplace 条目。130当你卸载最后一个约束依赖的插件时，该依赖不再被保持，并在下次更新时恢复跟踪其 marketplace 条目。

131 131

181 解决依赖错误181 解决依赖错误

182</h2>182</h2>

183 183

184依赖问题会在 `claude plugin list`、`/plugin` 界面和 `/doctor` 中显示。受影响的插件会被禁用，直到你解决错误。最常见的错误及其修复方法如下所示。184依赖问题会在 `claude plugin list` 和 `/plugin` 界面中显示。Claude Code 会禁用受影响的插件，直到你解决错误。下表列出了最常见的错误及其解决方法。

185 185

186| 错误 | 含义 | 如何解决 |186| 错误 | 含义 | 如何解决 |

187| :------------------------------- | :--------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |187| :------------------------------- | :--------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |

plugin-marketplaces.md +3 −1

Details

171 171

172<Note>172<Note>

173 **保留名称**：以下 marketplace 名称为 Anthropic 官方使用保留，第三方 marketplaces 无法使用：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`claude-plugins-community`、`claude-community`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`knowledge-work-plugins`、`life-sciences`、`claude-for-legal`、`claude-for-financial-services`、`financial-services-plugins`。冒充官方 marketplaces 的名称（如 `official-claude-plugins` 或 `anthropic-tools-v2`）也被阻止。173 **保留名称**：以下 marketplace 名称为 Anthropic 官方使用保留，第三方 marketplaces 无法使用：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`claude-plugins-community`、`claude-community`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`knowledge-work-plugins`、`life-sciences`、`claude-for-legal`、`claude-for-financial-services`、`financial-services-plugins`、`first-party-plugins`、`healthcare`。冒充官方 marketplaces 的名称（如 `official-claude-plugins` 或 `anthropic-plugins-v2`）也被阻止。保留这些名称可防止第三方 marketplace 将自己呈现为 Anthropic 发布的来源。

174

175 Claude Code 每次加载 marketplace 时都会重新检查保留名称，而不仅仅是在添加时。在该名称成为保留名称之前以其中一个名称注册的 marketplace 停止加载，并报告它是[从不受信任的来源注册的](/zh-CN/errors#marketplace-is-registered-from-an-untrusted-source)。移除该 marketplace 并从官方 Anthropic 来源重新添加它。受新保留名称影响的第三方 marketplace 在你以不同名称重新添加它后立即再次加载。在 v2.1.205 之前，`first-party-plugins` 和 `healthcare` 不是保留的，已在保留名称下注册的 marketplace 继续加载。

174</Note>176</Note>

175 177

176<h3 id="owner-fields">178<h3 id="owner-fields">

plugins.md +2 −0

Details

203 203

204<Warning>204<Warning>

205 **常见错误**：不要将 `commands/`、`agents/`、`skills/` 或 `hooks/` 放在 `.claude-plugin/` 目录内。只有 `plugin.json` 应该在 `.claude-plugin/` 内。所有其他目录必须在插件根级别。205 **常见错误**：不要将 `commands/`、`agents/`、`skills/` 或 `hooks/` 放在 `.claude-plugin/` 目录内。只有 `plugin.json` 应该在 `.claude-plugin/` 内。所有其他目录必须在插件根级别。

206

207 插件根是单个插件自己的目录：包含 `.claude-plugin/plugin.json` 的目录。它永远不是 `~/.claude/`。例如，Claude Code 不会读取放在 `~/.claude/.mcp.json` 的 `.mcp.json`。

206</Warning>208</Warning>

207 209

208| 目录 | 位置 | 目的 |210| 目录 | 位置 | 目的 |

plugins-reference.md +16 −2

Details

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

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

161 161

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

163

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

163 MCP servers165 MCP servers

164</h3>166</h3>

271| `shutdownTimeout` | 等待正常关闭的最长时间（毫秒）。当超时时间过去时，Claude Code 会终止 server 进程。未设置时，不适用超时 |

272| `restartOnCrash` | server 崩溃后是否重启。默认为 `true`。设置为 `false` 以保持崩溃的 server 停止而不是重启它 |

271 275

276`restartOnCrash` 和 `shutdownTimeout` 需要 Claude Code v2.1.205 或更高版本。在 v2.1.205 之前，配置架构接受两个选项，但设置其中任何一个会导致 Claude Code 在启动时完全跳过该 LSP server，原因仅在 `claude --debug` 输出中可见。

277

278**同一扩展名的多个 servers**：当多个启用的 LSP server 在 `extensionToLanguage` 中声明相同的文件扩展名时，无论 servers 来自一个插件还是来自不同的插件，第一个注册的 server 处理具有该扩展名的文件，其他的永远不会启动。`/plugin` 界面显示一个警告，命名其 server 处于活动状态的插件。

279

280**初始化失败的 Servers**：Claude Code 会跳过配置无效的 server，例如缺少 `command` 或 `extensionToLanguage` 的 server，其他配置的 servers 仍然会启动。运行 `claude --debug` 以查看为什么 server 被跳过。

281

282被跳过的 server 不会声明其文件扩展名，因此声明相同扩展名的另一个有效 server（来自同一个或不同的插件）仍然会处理这些文件。在 v2.1.205 之前，初始化失败的 server 仍然会声明其扩展名并阻止另一个有效 server 处理相同的扩展名。

283

272<Warning>284<Warning>

273 **您必须单独安装语言服务器二进制文件。** LSP plugins 配置 Claude Code 如何连接到语言服务器，但它们不包括服务器本身。如果在 `/plugin` Errors 选项卡中看到 `Executable not found in $PATH`，请为您的语言安装所需的二进制文件。285 **您必须单独安装语言服务器二进制文件。** LSP plugins 配置 Claude Code 如何连接到语言服务器，但它们不包括服务器本身。如果在 `/plugin` Errors 选项卡中看到 `Executable not found in $PATH`，请为您的语言安装所需的二进制文件。

274</Warning>286</Warning>

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

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

637 649

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

639 651

640对于所有路径字段：652对于所有路径字段：

641 653

673 685

674**`${CLAUDE_PLUGIN_DATA}`**：用于 plugin 状态的持久目录，在更新后保留。使用此目录用于已安装的依赖项，如 `node_modules` 或 Python 虚拟环境、生成的代码、缓存以及任何应在 plugin 版本之间保留的其他文件。首次引用此变量时，目录会自动创建。686**`${CLAUDE_PLUGIN_DATA}`**：用于 plugin 状态的持久目录，在更新后保留。使用此目录用于已安装的依赖项，如 `node_modules` 或 Python 虚拟环境、生成的代码、缓存以及任何应在 plugin 版本之间保留的其他文件。首次引用此变量时，目录会自动创建。

675 687

676**`${CLAUDE_PROJECT_DIR}`**：项目根目录。这是 hooks 在其 `CLAUDE_PROJECT_DIR` 变量中接收的相同目录。使用此路径引用项目本地脚本或配置文件。用引号包装以处理包含空格的路径，例如 `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`。MCP servers 也可以调用 MCP `roots/list` 请求，该请求返回启动 Claude Code 的目录。688**`${CLAUDE_PROJECT_DIR}`**：项目根目录。这是 hooks 在其 `CLAUDE_PROJECT_DIR` 变量中接收的相同目录。使用此路径引用项目本地脚本或配置文件。用引号包装以处理包含空格的路径，例如 `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`。

689

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

677 691

678```json theme={null}692```json theme={null}

679{693{

prompt-caching.md +5 −5

Details

50缓存发生在服务器端，在为您的模型提供服务的任何基础设施中。它的位置取决于您如何进行身份验证：50缓存发生在服务器端，在为您的模型提供服务的任何基础设施中。它的位置取决于您如何进行身份验证：

51 51

52* **API 密钥、Claude 订阅或 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws)**：缓存位于 Anthropic 的基础设施中，通过 [Claude API](https://platform.claude.com/docs) 访问52* **API 密钥、Claude 订阅或 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws)**：缓存位于 Anthropic 的基础设施中，通过 [Claude API](https://platform.claude.com/docs) 访问

~~53* **Bedrock 或 Vertex AI**：缓存位于您的云提供商的服务基础设施中~~53* **Amazon Bedrock 或 Google Cloud 的 Agent Platform**：缓存位于您的云提供商的服务基础设施中

~~54* **Foundry**：请求路由到 Anthropic 的基础设施~~54* **Microsoft Foundry**：请求路由到 Anthropic 的基础设施

55* **自定义 `ANTHROPIC_BASE_URL` 或 [LLM gateway](/zh-CN/llm-gateway)**：缓存位于您的请求转发到的任何地方，缓存是否工作取决于网关55* **自定义 `ANTHROPIC_BASE_URL` 或 [LLM gateway](/zh-CN/llm-gateway)**：缓存位于您的请求转发到的任何地方，缓存是否工作取决于网关

56 56

57有关每个提供商存储和处理的内容，请参阅[数据使用](/zh-CN/data-usage)。无论缓存位于何处，条目在不活动期间后过期，[缓存生命周期](#cache-lifetime)下面涵盖 TTL 以及如何延长它。57有关每个提供商存储和处理的内容，请参阅[数据使用](/zh-CN/data-usage)。无论缓存位于何处，条目在不活动期间后过期，[缓存生命周期](#cache-lifetime)下面涵盖 TTL 以及如何延长它。

106工具定义位于系统提示层中，所以当请求之间的工具定义集合更改时，缓存会失效。切换[顾问工具](/zh-CN/advisor)是一个例外：其定义位于缓存断点之后，所以启用或禁用 `/advisor` 会保持缓存的前缀完整。[MCP 服务器](/zh-CN/mcp)更改是否执行此操作取决于其工具是否由[工具搜索](/zh-CN/mcp#scale-with-mcp-tool-search)延迟或加载到前缀中：106工具定义位于系统提示层中，所以当请求之间的工具定义集合更改时，缓存会失效。切换[顾问工具](/zh-CN/advisor)是一个例外：其定义位于缓存断点之后，所以启用或禁用 `/advisor` 会保持缓存的前缀完整。[MCP 服务器](/zh-CN/mcp)更改是否执行此操作取决于其工具是否由[工具搜索](/zh-CN/mcp#scale-with-mcp-tool-search)延迟或加载到前缀中：

107 107

108* **延迟工具**，在支持的模型上是默认设置：服务器连接、断开连接或更改其工具列表仅附加新内容，不会扰乱已缓存的任何内容。108* **延迟工具**，在支持的模型上是默认设置：服务器连接、断开连接或更改其工具列表仅附加新内容，不会扰乱已缓存的任何内容。

109* **加载到前缀中的工具**：对它们的任何更改都会使缓存失效。这发生在[工具搜索不可用或被禁用](/zh-CN/mcp#configure-tool-search)时，例如在 Haiku 模型上、在 Vertex AI 上或使用自定义 `ANTHROPIC_BASE_URL` 网关时。它也发生在标记为 [`alwaysLoad`](/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器或工具上，以及由[基于阈值的加载](/zh-CN/mcp#configure-tool-search)保持在前面的定义上。109* **加载到前缀中的工具**：对它们的任何更改都会使缓存失效。这发生在[工具搜索不可用或被禁用](/zh-CN/mcp#configure-tool-search)时，例如在 Haiku 模型上、在 Google Cloud 的 Agent Platform 上或使用自定义 `ANTHROPIC_BASE_URL` 网关时。它也发生在标记为 [`alwaysLoad`](/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器或工具上，以及由[基于阈值的加载](/zh-CN/mcp#configure-tool-search)保持在前面的定义上。

110 110

111当工具加载到前缀中时，失效的最常见原因是服务器在会话中期连接或断开连接，这可能在没有您采取任何操作的情况下发生：stdio 服务器的进程退出、HTTP 会话过期或服务器[在暂时故障后自动重新连接](/zh-CN/mcp#automatic-reconnection)。连接的服务器也可以推送[动态工具更新](/zh-CN/mcp#dynamic-tool-updates)来更改其工具列表。111当工具加载到前缀中时，失效的最常见原因是服务器在会话中期连接或断开连接，这可能在没有您采取任何操作的情况下发生：stdio 服务器的进程退出、HTTP 会话过期或服务器[在暂时故障后自动重新连接](/zh-CN/mcp#automatic-reconnection)。连接的服务器也可以推送[动态工具更新](/zh-CN/mcp#dynamic-tool-updates)来更改其工具列表。

112 112

235 在 API 密钥或第三方提供商上235 在 API 密钥或第三方提供商上

236</h3>236</h3>

237 237

238在 API 密钥、Bedrock、Vertex、Foundry 或 Claude Platform on AWS 上，您支付按令牌费率，所以 TTL 默认保持在更便宜的五分钟。要选择加入[一小时 TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration)，设置 `ENABLE_PROMPT_CACHING_1H=1`。238在 API 密钥、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 上，您支付按令牌费率，所以 TTL 默认保持在更便宜的五分钟。要选择加入[一小时 TTL](https://platform.claude.com/docs/zh-CN/build-with-claude/prompt-caching#1-hour-cache-duration)，设置 `ENABLE_PROMPT_CACHING_1H=1`。

239 239

240在 Bedrock 上，prompt caching 支持、最小可缓存前缀长度和一小时 TTL 可用性都因模型而异。如果缓存令牌计数保持为零，请检查 Bedrock 文档中的[支持的模型、区域和限制](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)。240在 Amazon Bedrock 上，prompt caching 支持、最小可缓存前缀长度和一小时 TTL 可用性都因模型而异。如果缓存令牌计数保持为零，请检查 Amazon Bedrock 文档中的[支持的模型、区域和限制](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)。

241 241

242<h3 id="override-the-ttl">242<h3 id="override-the-ttl">

243 覆盖 TTL243 覆盖 TTL

quickstart.md +1 −1

Details

105 105

106* [Claude Pro、Max、Team 或 Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login)（推荐）106* [Claude Pro、Max、Team 或 Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login)（推荐）

107* [Claude Console](https://console.anthropic.com/)（具有预付费额度的 API 访问）。首次登录时，Console 中会自动为集中成本跟踪创建一个"Claude Code"工作区。107* [Claude Console](https://console.anthropic.com/)（具有预付费额度的 API 访问）。首次登录时，Console 中会自动为集中成本跟踪创建一个"Claude Code"工作区。

108* [Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry](/zh-CN/third-party-integrations)（企业云提供商）108* [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry](/zh-CN/third-party-integrations)（企业云提供商）

109* 自托管的 [Claude apps gateway](/zh-CN/claude-apps-gateway)（如果您的组织运行一个）：您的管理员会预先配置网关 URL，`/login` 会直接在 **Cloud gateway** 屏幕上打开，供您使用企业 SSO 登录109* 自托管的 [Claude apps gateway](/zh-CN/claude-apps-gateway)（如果您的组织运行一个）：您的管理员会预先配置网关 URL，`/login` 会直接在 **Cloud gateway** 屏幕上打开，供您使用企业 SSO 登录

110 110

111登录后，您的凭证将被存储，您无需再次登录。111登录后，您的凭证将被存储，您无需再次登录。

remote-control.md +21 −6

Details

16 16

17* **远程使用您的完整本地环境**：您的文件系统、[MCP servers](/zh-CN/mcp)、工具和项目配置都保持可用，输入 `@` 会自动完成本地项目中的文件路径17* **远程使用您的完整本地环境**：您的文件系统、[MCP servers](/zh-CN/mcp)、工具和项目配置都保持可用，输入 `@` 会自动完成本地项目中的文件路径

18* **同时从两个界面工作**：对话在所有连接的设备上保持同步，因此您可以从终端、浏览器和手机交替发送消息18* **同时从两个界面工作**：对话在所有连接的设备上保持同步，因此您可以从终端、浏览器和手机交替发送消息

19* **从您的手机或浏览器发送图像和文件**：当您在 Claude 应用或 claude.ai/code 中添加附件时，Claude Code 会将其下载到您的机器并将其作为 `@` 文件引用传递给 Claude，可以带有或不带有标题。{/* min-version: 2.1.202 */}在 v2.1.202 之前，Claude Code 可能会在不带标题的附件到达会话之前将其丢弃。

19* **在中断后恢复**：如果您的笔记本电脑进入睡眠状态或网络断开，当您的机器重新上线时，会话会自动重新连接20* **在中断后恢复**：如果您的笔记本电脑进入睡眠状态或网络断开，当您的机器重新上线时，会话会自动重新连接

20 21

21与[网络上的 Claude Code](/zh-CN/claude-code-on-the-web)（在云基础设施上运行）不同，Remote Control 会话直接在您的机器上运行并与您的本地文件系统交互。网络和移动界面只是该本地会话的一个窗口。22与[网络上的 Claude Code](/zh-CN/claude-code-on-the-web)（在云基础设施上运行）不同，Remote Control 会话直接在您的机器上运行并与您的本地文件系统交互。网络和移动界面只是该本地会话的一个窗口。

34 35

35* **订阅**：在 Pro、Max、Team 和 Enterprise 计划中可用。不支持 API 密钥。在 Team 和 Enterprise 上，Owner 必须首先在 [Claude Code 管理员设置](https://claude.ai/admin-settings/claude-code)中启用 Remote Control 切换。36* **订阅**：在 Pro、Max、Team 和 Enterprise 计划中可用。不支持 API 密钥。在 Team 和 Enterprise 上，Owner 必须首先在 [Claude Code 管理员设置](https://claude.ai/admin-settings/claude-code)中启用 Remote Control 切换。

36* **身份验证**：运行 `claude` 并使用 `/login` 通过 claude.ai 登录（如果您还没有登录）。37* **身份验证**：运行 `claude` 并使用 `/login` 通过 claude.ai 登录（如果您还没有登录）。

37* **API 端点**：在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用。{/* min-version: 2.1.196 */}从 v2.1.196 开始，当 [`ANTHROPIC_BASE_URL`](/zh-CN/env-vars) 指向 `api.anthropic.com` 以外的主机（例如 [LLM gateway](/zh-CN/llm-gateway) 或代理）时，Remote Control 也会被禁用。取消设置该变量以使用 Remote Control。38* **API 端点**：在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。{/* min-version: 2.1.196 */}从 v2.1.196 开始，当 [`ANTHROPIC_BASE_URL`](/zh-CN/env-vars) 指向 `api.anthropic.com` 以外的主机（例如 [LLM gateway](/zh-CN/llm-gateway) 或代理）时，Remote Control 也会被禁用。取消设置该变量以使用 Remote Control。

38* **工作区信任**：在您的项目目录中至少运行一次 `claude` 以接受工作区信任对话框。39* **工作区信任**：在您的项目目录中至少运行一次 `claude` 以接受工作区信任对话框。

39 40

40<h2 id="start-a-remote-control-session">41<h2 id="start-a-remote-control-session">

59 | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |60 | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

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

63 | `-c`, `--continue` | {/* min-version: 2.1.200 */}恢复从此目录启动的最近的 Remote Control 会话，而不是创建新会话。不能与 `--session-id`、`--spawn`、`--capacity` 或 `--create-session-in-dir` 结合使用。需要 Claude Code v2.1.200 或更高版本；早期版本会将该标志拒绝为未知参数。 |

64 | `--session-id <id>` | {/* min-version: 2.1.200 */}通过其 ID 恢复特定的 Remote Control 会话。不能与 `--continue`、`--spawn`、`--capacity` 或 `--create-session-in-dir` 结合使用。需要 Claude Code v2.1.200 或更高版本；早期版本会将该标志拒绝为未知参数。 |

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

67 | `--[no-]create-session-in-dir` | 在服务器启动时在当前目录中预创建一个会话，以便您有地方立即输入。在 `worktree` 模式下，此会话保留在当前目录中，而按需会话获得隔离的 worktrees。默认启用；传递 `--no-create-session-in-dir` 以不创建任何会话启动。 |

66 </Tab>70 </Tab>

149 为所有会话启用 Remote Control153 为所有会话启用 Remote Control

150</h3>154</h3>

151 155

152默认情况下，Remote Control 仅在您显式运行 `claude remote-control`、`claude --remote-control` 或 `/remote-control` 时激活。要为每个交互式会话自动启用它，请在 Claude Code 中运行 `/config` 并将**为所有会话启用 Remote Control** 设置为 `true`。将其设置为 `false` 以禁用，或将其保留为未设置以遵循您的组织的默认值。在桌面应用中，您也可以从**设置 → Claude Code → 默认启用远程控制**切换此选项。156默认情况下，Remote Control 仅在您显式运行 `claude remote-control`、`claude --remote-control` 或 `/remote-control` 时激活。要为每个交互式会话自动启用它，请在 Claude Code 中运行 `/config` 并将**为所有会话启用 Remote Control** 设置为 `true`。将其设置为 `false` 以禁用，或将其保留为未设置以遵循您的组织的默认值。在桌面应用中，您也可以从**设置 → Claude Code → 默认启用远程控制**切换此选项。{/* min-version: 2.1.203 */}在 [VS Code 扩展](/zh-CN/vs-code#use-the-prompt-box)中，相同的切换显示为命令菜单的设置部分中的**为所有会话启用 Remote Control**；需要 Claude Code v2.1.203 或更高版本。

153 157

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

155 159

280* **本地进程必须保持运行**：Remote Control 作为本地进程运行。如果您关闭终端、退出 VS Code 或以其他方式停止 `claude` 进程，会话结束。284* **本地进程必须保持运行**：Remote Control 作为本地进程运行。如果您关闭终端、退出 VS Code 或以其他方式停止 `claude` 进程，会话结束。

281* **扩展网络中断**：如果您的机器处于唤醒状态但无法在大约 10 分钟以上的时间内到达网络，会话超时并且进程退出。再次运行 `claude remote-control` 以启动新会话。285* **扩展网络中断**：如果您的机器处于唤醒状态但无法在大约 10 分钟以上的时间内到达网络，会话超时并且进程退出。再次运行 `claude remote-control` 以启动新会话。

282* **Ultraplan 断开 Remote Control**：启动 [ultraplan](/zh-CN/ultraplan) 会话会断开任何活动的 Remote Control 会话，因为两个功能都占据 claude.ai/code 界面，一次只能连接一个。286* **Ultraplan 断开 Remote Control**：启动 [ultraplan](/zh-CN/ultraplan) 会话会断开任何活动的 Remote Control 会话，因为两个功能都占据 claude.ai/code 界面，一次只能连接一个。

283* **某些命令仅限本地**：在终端中打开交互式选择器的命令，例如 `/plugin` 或 `/resume`，仅从本地 CLI 工作。以下命令可从移动和网络工作：287* **某些命令仅限本地**：仅在终端界面中运行的命令，例如 `/plugin` 或 `/resume`，仅从本地 CLI 工作，无论您是否传递参数。以下命令可从移动和网络工作：

284 * 文本输出命令：`/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/usage-credits`、`/recap`、`/reload-plugins`288 * 文本输出命令：`/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/usage-credits`、`/recap`、`/reload-plugins`

285 * {/* min-version: 2.1.166 */}从 v2.1.166 开始的 `/mcp`：返回服务器状态的文本摘要而不是打开选择器，并接受 `reconnect`、`enable` 和 `disable` [子命令](/zh-CN/commands#all-commands)。与本地 CLI 不同，不带服务器名称的 `/mcp reconnect` 会重新连接每个已失败或需要身份验证的服务器。289 * `/model`、`/effort`、`/fast`、`/color` 和 `/rename`：将值作为参数传递，例如 `/model sonnet` 或 `/effort high`。从移动和网络，`/model` 和 `/effort` 在终端选择器或滑块的位置接受参数。

286 * {/* min-version: 2.1.181 */}从 v2.1.181 开始的 `/config`：传递 `key=value` 以设置一个设置，或不带参数运行它以列出您可以设置的键。290 * {/* min-version: 2.1.166 */}`/mcp`，从 v2.1.166 开始：返回服务器状态的文本摘要而不是打开选择器，并接受 `reconnect`、`enable` 和 `disable` [子命令](/zh-CN/commands#all-commands)。与本地 CLI 不同，不带服务器名称的 `/mcp reconnect` 会重新连接每个已失败或需要身份验证的服务器。

291 * {/* min-version: 2.1.181 */}`/config`，从 v2.1.181 开始：传递 `key=value` 以设置一个设置，或不带参数运行它以列出您可以设置的键。

287 292

288<h2 id="troubleshooting">293<h2 id="troubleshooting">

289 故障排除294 故障排除

323 "Remote Control 仅在通过 api.anthropic.com 使用 Claude 时可用"328 "Remote Control 仅在通过 api.anthropic.com 使用 Claude 时可用"

324</h3>329</h3>

325 330

326该会话不是直接与 Anthropic API 通信，因此没有 claude.ai 后端可配对。这发生在 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 上。{/* min-version: 2.1.196 */}从 v2.1.196 开始，当 [`ANTHROPIC_BASE_URL`](/zh-CN/env-vars) 指向 `api.anthropic.com` 以外的主机时，例如 [LLM 网关](/zh-CN/llm-gateway) 或代理，即使您使用 claude.ai 登录，也会发生这种情况。取消设置 `ANTHROPIC_BASE_URL` 并重启会话以使用 Remote Control。331该会话不是直接与 Anthropic API 通信，因此没有 claude.ai 后端可配对。这发生在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上。{/* min-version: 2.1.196 */}从 v2.1.196 开始，当 [`ANTHROPIC_BASE_URL`](/zh-CN/env-vars) 指向 `api.anthropic.com` 以外的主机时，例如 [LLM 网关](/zh-CN/llm-gateway) 或代理，即使您使用 claude.ai 登录，也会发生这种情况。取消设置 `ANTHROPIC_BASE_URL` 并重启会话以使用 Remote Control。

327 332

328<h3 id="remote-control-is-disabled-by-your-organization’s-policy">333<h3 id="remote-control-is-disabled-by-your-organization’s-policy">

329 "Remote Control 被您的组织的策略禁用"334 "Remote Control 被您的组织的策略禁用"

352* 网络或代理问题：防火墙或代理可能阻止出站 HTTPS 请求。Remote Control 需要访问端口 443 上的 Anthropic API。357* 网络或代理问题：防火墙或代理可能阻止出站 HTTPS 请求。Remote Control 需要访问端口 443 上的 Anthropic API。

353* 会话创建失败：如果您还看到 `Session creation failed — see debug log`，失败发生在设置的早期。检查您的订阅是否处于活动状态。358* 会话创建失败：如果您还看到 `Session creation failed — see debug log`，失败发生在设置的早期。检查您的订阅是否处于活动状态。

354 359

360<h3 id="couldn’t-reconnect-to-your-remote-control-session">

361 "无法重新连接到您的 Remote Control 会话"

362</h3>

363

364当您使用 `claude --resume` 或 `claude --continue` 恢复对话时，Claude Code 会重新连接到该对话中记录的 Remote Control 会话。此消息意味着重新连接因可能是临时的原因（例如网络中断或服务器错误）而失败，因此 Claude Code 无法确认远程会话是否仍然存在。当服务器确认之前的会话不再存在时，Claude Code 会创建新的 Remote Control 会话而不显示此消息。

365

366您的本地会话继续运行而不使用 Remote Control。运行 `/remote-control` 以重试连接，或启动 Claude Code 而不使用 `--resume` 以创建新的 Remote Control 会话。

367

368{/* min-version: 2.1.200 */}在 v2.1.200 之前，重新连接失败会创建新的 Remote Control 会话而不是显示此消息，这在 claude.ai/code 的会话列表中留下了额外的会话。

369

355<h3 id="your-organization-requires-trusted-devices-for-remote-control-but-this-device-is-not-enrolled">370<h3 id="your-organization-requires-trusted-devices-for-remote-control-but-this-device-is-not-enrolled">

356 "您的组织需要受信任的设备用于 Remote Control，但此设备未注册"371 "您的组织需要受信任的设备用于 Remote Control，但此设备未注册"

357</h3>372</h3>

routines.md +1 −1

Details

416 416

417当不满足其中一个要求时，CLI 会隐藏 `/schedule`，因此命令菜单在您输入时显示 `No commands match "/schedule"`，提交它会返回 `Unknown command: /schedule`。原因通常是以下之一：417当不满足其中一个要求时，CLI 会隐藏 `/schedule`，因此命令菜单在您输入时显示 `No commands match "/schedule"`，提交它会返回 `Unknown command: /schedule`。原因通常是以下之一：

418 418

419* 您使用 Console API 密钥或云提供商（如 Bedrock、Vertex 或 Foundry）进行身份验证。`/schedule` 需要 claude.ai 订阅登录。如果在您的 shell 中设置了 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，或在 `settings.json` 中设置了 `apiKeyHelper`，请先删除它，因为这些会优先于 claude.ai 登录419* 您使用 Console API 密钥或云提供商（如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry）进行身份验证。`/schedule` 需要 claude.ai 订阅登录。如果在您的 shell 中设置了 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，或在 `settings.json` 中设置了 `apiKeyHelper`，请先删除它，因为这些会优先于 claude.ai 登录

420* `DISABLE_TELEMETRY`、`DO_NOT_TRACK`、`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 或 `DISABLE_GROWTHBOOK` 在您的 shell 环境或 [`settings.json` 文件](/zh-CN/settings#available-settings)的 `env` 块中设置。这些会禁用功能标志获取，而 `/schedule` 依赖于此420* `DISABLE_TELEMETRY`、`DO_NOT_TRACK`、`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 或 `DISABLE_GROWTHBOOK` 在您的 shell 环境或 [`settings.json` 文件](/zh-CN/settings#available-settings)的 `env` 块中设置。这些会禁用功能标志获取，而 `/schedule` 依赖于此

421* 您在 Claude Code 网页会话中。改为从 [web UI](https://claude.ai/code/routines) 管理例程421* 您在 Claude Code 网页会话中。改为从 [web UI](https://claude.ai/code/routines) 管理例程

422* {/* min-version: 2.1.81 */}您的 CLI 版本早于 v2.1.81。运行 `claude update`422* {/* min-version: 2.1.81 */}您的 CLI 版本早于 v2.1.81。运行 `claude update`

sandboxing.md +1 −1

Details

237 237

238使用 `mask`，沙箱化命令看到的是每个会话的哨兵值，而不是真实值。当请求离开沙箱前往凭证的 `injectHosts` 之一时，[sandbox proxy](#network-isolation) 将哨兵值替换为真实值。命令及其记录的任何内容都不会持有真实凭证，但其请求仍然进行身份验证。238使用 `mask`，沙箱化命令看到的是每个会话的哨兵值，而不是真实值。当请求离开沙箱前往凭证的 `injectHosts` 之一时，[sandbox proxy](#network-isolation) 将哨兵值替换为真实值。命令及其记录的任何内容都不会持有真实凭证，但其请求仍然进行身份验证。

239 239

240代理在请求内容中替换凭证，因此它必须看到它们。设置 [`network.tlsTerminate`](/zh-CN/settings#sandbox-settings) 以便代理自己终止 HTTPS。没有它，掩盖会失败关闭：命令仍然只看到哨兵值，但哨兵值不变地到达服务器，身份验证失败。Claude Code 在启动时和 `/doctor` 中报告此配置错误。240代理在请求内容中替换凭证，因此它必须看到它们。设置 [`network.tlsTerminate`](/zh-CN/settings#sandbox-settings) 以便代理自己终止 TLS。没有它，掩盖会失败关闭：命令仍然只看到哨兵值，但哨兵值不变地到达服务器，身份验证失败。Claude Code 在启动时报告此配置错误。

241 241

242下面的示例掩盖两个令牌。`GH_TOKEN` 仅在对 `api.github.com` 的请求上被替换，而 `NPM_TOKEN` 没有 `injectHosts`，在对 `network.allowedDomains` 中每个主机的请求上被替换。每个 `injectHosts` 条目本身必须被 `network.allowedDomains` 覆盖。242下面的示例掩盖两个令牌。`GH_TOKEN` 仅在对 `api.github.com` 的请求上被替换，而 `NPM_TOKEN` 没有 `injectHosts`，在对 `network.allowedDomains` 中每个主机的请求上被替换。每个 `injectHosts` 条目本身必须被 `network.allowedDomains` 覆盖。

243 243

scheduled-tasks.md +6 −4

Details

86动态计划的循环出现在您的[计划任务列表](#manage-scheduled-tasks)中，就像任何其他任务一样，所以您可以以相同的方式列出或取消它。[抖动规则](#jitter)不适用于它，但[七天过期](#seven-day-expiry)适用：循环在您启动它七天后自动结束。86动态计划的循环出现在您的[计划任务列表](#manage-scheduled-tasks)中，就像任何其他任务一样，所以您可以以相同的方式列出或取消它。[抖动规则](#jitter)不适用于它，但[七天过期](#seven-day-expiry)适用：循环在您启动它七天后自动结束。

87 87

88<Note>88<Note>

~~89 在 Bedrock、Vertex AI 和 Microsoft Foundry 上，没有间隔的提示词在固定的 10 分钟计划上运行。~~89 在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，没有间隔的提示词在固定的 10 分钟计划上运行。

90</Note>90</Note>

91 91

92<h3 id="run-the-built-in-maintenance-prompt">92<h3 id="run-the-built-in-maintenance-prompt">

108裸 `/loop` 在[动态选择的间隔](#let-claude-choose-the-interval)上运行此提示词。添加间隔，例如 `/loop 15m`，以在固定计划上运行它。要用您自己的默认值替换内置提示词，请参阅[使用 loop.md 自定义默认提示词](#customize-the-default-prompt-with-loop-md)。108裸 `/loop` 在[动态选择的间隔](#let-claude-choose-the-interval)上运行此提示词。添加间隔，例如 `/loop 15m`，以在固定计划上运行它。要用您自己的默认值替换内置提示词，请参阅[使用 loop.md 自定义默认提示词](#customize-the-default-prompt-with-loop-md)。

109 109

110<Note>110<Note>

111 在 Bedrock、Vertex AI 和 Microsoft Foundry 上，没有提示词的 `/loop` 会打印使用消息而不是运行维护提示词。111 在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，没有提示词的 `/loop` 会打印使用消息而不是运行维护提示词。

112</Note>112</Note>

113 113

114<h3 id="customize-the-default-prompt-with-loop-md">114<h3 id="customize-the-default-prompt-with-loop-md">

136对 `loop.md` 的编辑在下一次迭代时生效，所以您可以在循环运行时优化说明。当任一位置都不存在 `loop.md` 时，循环回退到内置维护提示词。保持文件简洁：超过 25,000 字节的内容会被截断。136对 `loop.md` 的编辑在下一次迭代时生效，所以您可以在循环运行时优化说明。当任一位置都不存在 `loop.md` 时，循环回退到内置维护提示词。保持文件简洁：超过 25,000 字节的内容会被截断。

137 137

138<Note>138<Note>

139 在 Bedrock、Vertex AI 和 Microsoft Foundry 上，`loop.md` 不被读取，没有提示词的 `/loop` 会打印使用消息。139 在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，`loop.md` 不被读取，没有提示词的 `/loop` 会打印使用消息。

140</Note>140</Note>

141 141

142<h3 id="stop-a-loop">142<h3 id="stop-a-loop">

145 145

146要在 `/loop` 等待下一次迭代时停止它，请按 `Esc`。这会清除待处理的唤醒，所以循环不会再次触发。您通过[直接询问 Claude](#manage-scheduled-tasks)计划的任务不受 `Esc` 影响，会保留在原位，直到您删除它们。146要在 `/loop` 等待下一次迭代时停止它，请按 `Esc`。这会清除待处理的唤醒，所以循环不会再次触发。您通过[直接询问 Claude](#manage-scheduled-tasks)计划的任务不受 `Esc` 影响，会保留在原位，直到您删除它们。

147 147

148在[自主进行模式](#let-claude-choose-the-interval)中，Claude 也可以在任务可证明完成后通过不计划下一次唤醒来自己结束循环。固定间隔上的循环会一直运行，直到您停止它们或[七天过去](#seven-day-expiry)。148在[自主进行模式](#let-claude-choose-the-interval)中，Claude 也可以在任务完成后通过调用 [`ScheduleWakeup` tool](/zh-CN/tools-reference) 并设置 `stop: true` 来自己结束循环，这会立即取消待处理的唤醒。如果迭代结束时既没有重新计划也没有停止，Claude Code 会在大约 20 分钟后计划一个备用唤醒，并在该迭代也不重新计划时结束循环。在 v2.1.202 之前，不重新计划是 Claude 自己结束循环的唯一方式。

149

150固定间隔上的循环会一直运行，直到您停止它们或[七天过去](#seven-day-expiry)。

149 151

150<h2 id="set-a-one-time-reminder">152<h2 id="set-a-one-time-reminder">

151 设置一次性提醒153 设置一次性提醒

security-guidance.md +1 −1

Details

219/plugin uninstall security-guidance@claude-plugins-official219/plugin uninstall security-guidance@claude-plugins-official

220```220```

221 221

222如果插件通过项目的 `.claude/settings.json` 启用，从 `/plugin` 禁用它会将覆盖写入您的 `.claude/settings.local.json`，而不是编辑已检入的文件，因此该插件对您保持关闭，而不影响队友。如果它通过 [托管设置](/zh-CN/admin-setup) 启用，只有管理员可以禁用它。222如果插件通过项目的 `.claude/settings.json` 启用，从 `/plugin` 禁用它会将覆盖写入您的 `.claude/settings.local.json`，而不是编辑已检入的文件，因此该插件对您保持关闭，而不影响队友。同一对话框还提供了通过从共享的 `.claude/settings.json` 中删除插件来为所有人卸载该插件的选项；该选项需要 Claude Code v2.1.203 或更高版本。如果它通过 [托管设置](/zh-CN/admin-setup) 启用，只有管理员可以禁用它。

223 223

224<h2 id="how-the-plugin-integrates-with-claude-code">224<h2 id="how-the-plugin-integrates-with-claude-code">

225 插件如何与 Claude Code 集成225 插件如何与 Claude Code 集成

server-managed-settings.md +2 −2

Details

255在使用第三方模型提供商时，服务器管理的设置不可用：255在使用第三方模型提供商时，服务器管理的设置不可用：

256 256

257* Amazon Bedrock257* Amazon Bedrock

258* Google Vertex AI258* Google Cloud 的 Agent Platform

259* Microsoft Foundry259* Microsoft Foundry

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

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

262 262

263对于 Bedrock、Vertex AI 和 Foundry 部署，自托管的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 提供等效的远程管理设置交付：网关登录的客户端从网关而不是 `api.anthropic.com` 获取管理设置。启动时的失败语义不同：无法到达网关的网关客户端以错误退出，而不是回退到缓存的设置，而每小时的后台刷新在两个通道上都是故障开放的。263对于 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 部署，自托管的 [Claude apps gateway](/zh-CN/claude-apps-gateway) 提供等效的远程管理设置交付：网关登录的客户端从网关而不是 `api.anthropic.com` 获取管理设置。启动时的失败语义不同：无法到达网关的网关客户端以错误退出，而不是回退到缓存的设置，而每小时的后台刷新在两个通道上都是故障开放的。

264 264

265<h2 id="audit-logging">265<h2 id="audit-logging">

266 审计日志266 审计日志

settings.md +20 −15

Details

95* **项目设置**保存在您的项目目录中：95* **项目设置**保存在您的项目目录中：

96 * `.claude/settings.json` 用于检入源代码管理并与您的团队共享的设置96 * `.claude/settings.json` 用于检入源代码管理并与您的团队共享的设置

97 * `.claude/settings.local.json` 用于未检入的设置，适用于个人偏好和实验。Claude Code 创建 `.claude/settings.local.json` 时，会配置 git 以忽略该文件。如果您自己创建该文件，请手动将其添加到 gitignore。97 * `.claude/settings.local.json` 用于未检入的设置，适用于个人偏好和实验。Claude Code 创建 `.claude/settings.local.json` 时，会配置 git 以忽略该文件。如果您自己创建该文件，请手动将其添加到 gitignore。

99 因为此文件属于您而不是存储库，其权限 `allow` 规则生效时无需 [workspace trust](/zh-CN/permissions#project-allow-rules-and-workspace-trust) 步骤，而 `.claude/settings.json` allow 规则需要此步骤。如果存储库提供该文件，例如通过提交它，workspace trust 仍然适用。

98* **Managed 设置**：对于需要集中控制的组织，Claude Code 支持多种 managed 设置的交付机制。所有机制都使用相同的 JSON 格式，无法被用户或项目设置覆盖：100* **Managed 设置**：对于需要集中控制的组织，Claude Code 支持多种 managed 设置的交付机制。所有机制都使用相同的 JSON 格式，无法被用户或项目设置覆盖：

99 101

100 * **服务器管理的设置**：通过 Anthropic 的服务器从 claude.ai 管理员控制台交付，或从自托管的 [Claude apps gateway](/zh-CN/claude-apps-gateway)。请参阅[服务器管理的设置](/zh-CN/server-managed-settings)。102 * **服务器管理的设置**：通过 Anthropic 的服务器从 claude.ai 管理员控制台交付，或从自托管的 [Claude apps gateway](/zh-CN/claude-apps-gateway)。请参阅[服务器管理的设置](/zh-CN/server-managed-settings)。

211`settings.json` 支持多个选项：213`settings.json` 支持多个选项：

212 214

213| 键 | 描述 | 示例 |215| 键 | 描述 | 示例 |

214| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------ |216| :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |

215| `advisorModel` | {/* min-version: 2.1.98 */}服务器端 [advisor tool](/zh-CN/advisor) 的模型。接受模型别名，如 `"opus"`、`"sonnet"` 或 `"fable"`（{/* min-version: 2.1.170 */}v2.1.170+），或完整模型 ID。当您运行 `/advisor` 时自动写入。取消设置以禁用 advisor。需要 Claude Code v2.1.98 或更高版本 | `"opus"` |217| `advisorModel` | {/* min-version: 2.1.98 */}服务器端 [advisor tool](/zh-CN/advisor) 的模型。接受模型别名，如 `"opus"`、`"sonnet"` 或 `"fable"`（{/* min-version: 2.1.170 */}v2.1.170+），或完整模型 ID。当您运行 `/advisor` 时自动写入。取消设置以禁用 advisor。需要 Claude Code v2.1.98 或更高版本 | `"opus"` |

216| `agent` | 将主线程作为命名 subagent 运行，并为从 `claude agents` 分派的会话设置默认 agent。应用该 subagent 的系统提示、工具限制和模型。请参阅[显式调用 subagents](/zh-CN/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |218| `agent` | 将主线程作为命名 subagent 运行，并为从 `claude agents` 分派的会话设置默认 agent。应用该 subagent 的系统提示、工具限制和模型。请参阅[显式调用 subagents](/zh-CN/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |

217| `agentPushNotifEnabled` | {/* min-version: 2.1.119 */}**默认**：`false`。当[远程控制](/zh-CN/remote-control)已连接时，允许 Claude 向您的手机发送主动推送通知，例如当长任务完成时。在 `/config` 中显示为**Claude 决定时推送**。请参阅[移动推送通知](/zh-CN/remote-control#mobile-push-notifications)。需要 Claude Code v2.1.119 或更高版本 | `true` |219| `agentPushNotifEnabled` | {/* min-version: 2.1.119 */}**默认**：`false`。当[远程控制](/zh-CN/remote-control)已连接时，允许 Claude 向您的手机发送主动推送通知，例如当长任务完成时。在 `/config` 中显示为**Claude 决定时推送**。请参阅[移动推送通知](/zh-CN/remote-control#mobile-push-notifications)。需要 Claude Code v2.1.119 或更高版本 | `true` |

224| `allowManagedPermissionRulesOnly` | （仅 Managed 设置）防止用户和项目设置定义 `allow`、`ask` 或 `deny` 权限规则。仅应用 managed 设置中的规则。请参阅 [Managed 专用设置](/zh-CN/permissions#managed-only-settings) | `true` |226| `allowManagedPermissionRulesOnly` | （仅 Managed 设置）防止用户和项目设置定义 `allow`、`ask` 或 `deny` 权限规则。仅应用 managed 设置中的规则。请参阅 [Managed 专用设置](/zh-CN/permissions#managed-only-settings) | `true` |

225| `alwaysThinkingEnabled` | 为所有会话默认启用[扩展思考](/zh-CN/model-config#extended-thinking)。通常通过 `/config` 命令而不是直接编辑来配置。要强制禁用思考，无论此设置如何，请在 `env` 中设置 [`MAX_THINKING_TOKENS=0`](/zh-CN/env-vars)，这会禁用 Anthropic API 上的思考，除了 Fable 5，它无法关闭思考。在[第三方提供商](/zh-CN/third-party-integrations)上，这会省略 `thinking` 参数，自适应推理模型仍可能思考 | `true` |227| `alwaysThinkingEnabled` | 为所有会话默认启用[扩展思考](/zh-CN/model-config#extended-thinking)。通常通过 `/config` 命令而不是直接编辑来配置。要强制禁用思考，无论此设置如何，请在 `env` 中设置 [`MAX_THINKING_TOKENS=0`](/zh-CN/env-vars)，这会禁用 Anthropic API 上的思考，除了 Fable 5，它无法关闭思考。在[第三方提供商](/zh-CN/third-party-integrations)上，这会省略 `thinking` 参数，自适应推理模型仍可能思考 | `true` |

226| `apiKeyHelper` | 自定义脚本，在系统 shell（macOS 和 Linux 上为 `/bin/sh`，Windows 上为 `cmd`）中运行，以生成身份验证值。此值将作为 `X-Api-Key` 和 `Authorization: Bearer` 标头发送用于模型请求。使用 [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/zh-CN/env-vars) 设置刷新间隔 | `/bin/generate_temp_api_key.sh` |228| `apiKeyHelper` | 自定义脚本，在系统 shell（macOS 和 Linux 上为 `/bin/sh`，Windows 上为 `cmd`）中运行，以生成身份验证值。此值将作为 `X-Api-Key` 和 `Authorization: Bearer` 标头发送用于模型请求。使用 [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/zh-CN/env-vars) 设置刷新间隔 | `/bin/generate_temp_api_key.sh` |

229| `askUserQuestionTimeout` | {/* min-version: 2.1.200 */}**默认**：`"never"`。未回答的 [`AskUserQuestion`](/zh-CN/tools-reference) 对话框自动继续的空闲时间，使用您已选择的任何选项。接受 `"60s"`、`"5m"`、`"10m"` 或 `"never"`。使用默认值，问题等待您回答。在 `/config` 中显示为**问题自动继续超时**，将此键写入用户设置。不从项目或本地设置读取。需要 Claude Code v2.1.200 或更高版本 | `"5m"` |

227| `attribution` | 自定义 git 提交和拉取请求的归属。请参阅[归属设置](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |230| `attribution` | 自定义 git 提交和拉取请求的归属。请参阅[归属设置](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

228| `autoCompactEnabled` | {/* min-version: 2.1.119 */}**默认**：`true`。当上下文接近限制时自动压缩对话。在 `/config` 中显示为**自动压缩**。要通过环境变量禁用，请在 `env` 中设置 [`DISABLE_AUTO_COMPACT`](/zh-CN/env-vars) | `false` |231| `autoCompactEnabled` | {/* min-version: 2.1.119 */}**默认**：`true`。当上下文接近限制时自动压缩对话。在 `/config` 中显示为**自动压缩**。要通过环境变量禁用，请在 `env` 中设置 [`DISABLE_AUTO_COMPACT`](/zh-CN/env-vars) | `false` |

239| `axScreenReader` | {/* min-version: 2.1.181 */}渲染屏幕阅读器友好的输出：没有装饰性边框或动画的平面文本。屏幕阅读器模式始终使用经典渲染器，因此在其活跃时 `tui` 设置无效。[`CLAUDE_AX_SCREEN_READER`](/zh-CN/env-vars) 环境变量和 [`--ax-screen-reader`](/zh-CN/cli-reference#cli-flags) 标志优先。需要 Claude Code v2.1.181 或更高版本 | `true` |242| `axScreenReader` | {/* min-version: 2.1.181 */}渲染屏幕阅读器友好的输出：没有装饰性边框或动画的平面文本。屏幕阅读器模式始终使用经典渲染器，因此在其活跃时 `tui` 设置无效。[`CLAUDE_AX_SCREEN_READER`](/zh-CN/env-vars) 环境变量和 [`--ax-screen-reader`](/zh-CN/cli-reference#cli-flags) 标志优先。需要 Claude Code v2.1.181 或更高版本 | `true` |

240| `blockedMarketplaces` | （仅 Managed 设置）市场源的阻止列表。在市场添加和插件安装、更新、刷新和自动更新时强制执行，因此在设置策略之前添加的市场无法用于获取插件。被阻止的源在下载前被检查，因此它们永远不会接触文件系统。请参阅 [Managed 市场限制](/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |243| `blockedMarketplaces` | （仅 Managed 设置）市场源的阻止列表。在市场添加和插件安装、更新、刷新和自动更新时强制执行，因此在设置策略之前添加的市场无法用于获取插件。被阻止的源在下载前被检查，因此它们永远不会接触文件系统。请参阅 [Managed 市场限制](/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

244| `browserExternalPageTools` | （仅 Managed 设置）设置为 `"disabled"` 以防止 Claude 使用工具读取或作用于桌面应用[浏览器窗格](/zh-CN/desktop#browse-external-sites)中的外部页面。用户仍可以自己导航到外部站点，本地开发服务器预览不受影响 | `"disabled"` |

241| `channelsEnabled` | （仅 Managed 设置）为组织允许 [channels](/zh-CN/channels)。在 claude.ai Team 和 Enterprise 计划上，当此项未设置或为 `false` 时，channels 被阻止。对于使用 API 密钥身份验证的 [Anthropic Console](/zh-CN/authentication#claude-console-authentication) 账户，channels 默认被允许，除非您的组织部署 managed 设置，在这种情况下此键必须设置为 `true` | `true` |245| `channelsEnabled` | （仅 Managed 设置）为组织允许 [channels](/zh-CN/channels)。在 claude.ai Team 和 Enterprise 计划上，当此项未设置或为 `false` 时，channels 被阻止。对于使用 API 密钥身份验证的 [Anthropic Console](/zh-CN/authentication#claude-console-authentication) 账户，channels 默认被允许，除非您的组织部署 managed 设置，在这种情况下此键必须设置为 `true` | `true` |

242| `claudeMd` | （仅 Managed 设置）CLAUDE.md 风格的说明，作为组织管理的内存注入。仅在 managed 或策略设置中设置时被尊重，在用户、项目和本地设置中被忽略。请参阅[组织范围的 CLAUDE.md](/zh-CN/memory#deploy-organization-wide-claude-md) | `"Always run make lint before committing."` |246| `claudeMd` | （仅 Managed 设置）CLAUDE.md 风格的说明，作为组织管理的内存注入。仅在 managed 或策略设置中设置时被尊重，在用户、项目和本地设置中被忽略。请参阅[组织范围的 CLAUDE.md](/zh-CN/memory#deploy-organization-wide-claude-md) | `"Always run make lint before committing."` |

243| `claudeMdExcludes` | 加载[内存](/zh-CN/memory)时要跳过的 `CLAUDE.md` 文件的 Glob 模式或绝对路径。模式与绝对文件路径匹配。仅适用于用户、项目和本地内存；managed 策略文件无法被排除 | `["**/vendor/**/CLAUDE.md"]` |247| `claudeMdExcludes` | 加载[内存](/zh-CN/memory)时要跳过的 `CLAUDE.md` 文件的 Glob 模式或绝对路径。模式与绝对文件路径匹配。仅适用于用户、项目和本地内存；managed 策略文件无法被排除 | `["**/vendor/**/CLAUDE.md"]` |

244| `cleanupPeriodDays` | **默认**：`30` 天，最少 `1`。非活跃时间超过此期间的会话在启动时被删除。设置为 `0` 会被拒绝并显示验证错误。也控制[孤立 subagent worktrees](/zh-CN/worktrees#clean-up-worktrees) 在启动时自动删除的年龄截止。要完全禁用记录写入，请设置 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-CN/env-vars) 环境变量，或在非交互模式（`-p`）中使用 `--no-session-persistence` 标志或 `persistSession: false` SDK 选项。 | `20` |248| `cleanupPeriodDays` | **默认**：`30` 天，最少 `1`。Claude Code 删除[会话文件和其他应用程序数据](/zh-CN/claude-directory#cleaned-up-automatically)早于此期间的在启动时。设置 `0` 会被拒绝并显示验证错误。相同的年龄截止也适用于[孤立 worktrees](/zh-CN/worktrees#clean-up-worktrees) 在启动时自动删除。{/* min-version: 2.1.203 */}如果 Claude Code 无法读取或解析设置文件，它会暂停保留清理扫描并在 `/status` 中显示警告，直到您修复文件，除非 [managed 设置](/zh-CN/server-managed-settings)提供 `cleanupPeriodDays`，在这种情况下扫描以 managed 值运行。在 v2.1.203 之前，清理以 30 天默认值在该状态下运行，可能删除较长 `cleanupPeriodDays` 打算保留的记录；30 天以上的文件从未被删除。要完全禁用记录写入，请设置 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-CN/env-vars) 环境变量。在非交互模式中，与 `-p` 一起传递 `--no-session-persistence` 或在 Agent SDK 中设置 `persistSession: false`。 | `20` |

246| `defaultShell` | **默认**：`"bash"`，或在 Bash 不可用时在 Windows 上为 `"powershell"`。输入框 `!` 命令的默认 shell。接受 `"bash"` 或 `"powershell"`。设置 `"powershell"` 会在 Windows 上通过 PowerShell 路由交互式 `!` 命令。需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。请参阅 [PowerShell tool](/zh-CN/tools-reference#powershell-tool) | `"powershell"` |250| `defaultShell` | **默认**：`"bash"`，或在 Bash 不可用时在 Windows 上为 `"powershell"`。输入框 `!` 命令的默认 shell。接受 `"bash"` 或 `"powershell"`。设置 `"powershell"` 会在 Windows 上通过 PowerShell 路由交互式 `!` 命令。需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。请参阅 [PowerShell tool](/zh-CN/tools-reference#powershell-tool) | `"powershell"` |

247| `deniedMcpServers` | 在 managed-settings.json 中设置时，明确阻止的 MCP servers 的拒绝列表。适用于所有作用域，包括 managed servers。拒绝列表优先于允许列表。请参阅 [Managed MCP 配置](/zh-CN/managed-mcp) | `[{ "serverName": "filesystem" }]` |251| `deniedMcpServers` | 在 managed-settings.json 中设置时，明确阻止的 MCP servers 的拒绝列表。适用于所有作用域，包括 managed servers。拒绝列表优先于允许列表。请参阅 [Managed MCP 配置](/zh-CN/managed-mcp) | `[{ "serverName": "filesystem" }]` |

251| `disableAutoMode` | 设置为 `"disable"` 以防止[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)被激活。从 `Shift+Tab` 循环中删除 `auto` 并在启动时拒绝 `--permission-mode auto`。在[managed 设置](/zh-CN/permissions#managed-settings)中最有用，用户无法覆盖它 | `"disable"` |255| `disableAutoMode` | 设置为 `"disable"` 以防止[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)被激活。从 `Shift+Tab` 循环中删除 `auto` 并在启动时拒绝 `--permission-mode auto`。在[managed 设置](/zh-CN/permissions#managed-settings)中最有用，用户无法覆盖它 | `"disable"` |

252| `disableBundledSkills` | 设置为 `true` 以禁用 Claude Code 附带的 [skills](/zh-CN/skills) 和工作流：捆绑的 skills 和工作流被完全删除，而内置斜杠命令（如 `/init`）保持可键入但对模型隐藏。来自插件、`.claude/skills/` 和 `.claude/commands/` 的 skills 不受影响。等同于将 `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` 设置为 `1` | `true` |256| `disableBundledSkills` | 设置为 `true` 以禁用 Claude Code 附带的 [skills](/zh-CN/skills) 和工作流：捆绑的 skills 和工作流被完全删除，而内置斜杠命令（如 `/init`）保持可键入但对模型隐藏。`/doctor` 保持可键入，如内置命令；用 [`DISABLE_DOCTOR_COMMAND`](/zh-CN/env-vars) 隐藏它。来自插件、`.claude/skills/` 和 `.claude/commands/` 的 skills 不受影响。等同于将 `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` 设置为 `1` | `true` |

253| `disableClaudeAiConnectors` | {/* min-version: 2.1.182 */}禁用 [claude.ai MCP connectors](/zh-CN/mcp#use-mcp-servers-from-claude-ai)，以便它们不被自动获取或连接。在任何设置作用域中设置。任何源中的 `true` 优先，因此已检入的项目 `.claude/settings.json` 可以选择存储库退出云连接器，但项目级 `false` 无法覆盖用户或策略级 `true`。通过 `--mcp-config` 显式传递的 servers 不受影响。要拒绝单个连接器而不是所有连接器，请改用 [`deniedMcpServers`](/zh-CN/managed-mcp)。需要 Claude Code v2.1.182 或更高版本 | `true` |257| `disableClaudeAiConnectors` | {/* min-version: 2.1.182 */}禁用 [claude.ai MCP connectors](/zh-CN/mcp#use-mcp-servers-from-claude-ai)，以便它们不被自动获取或连接。在任何设置作用域中设置。任何源中的 `true` 优先，因此已检入的项目 `.claude/settings.json` 可以选择存储库退出云连接器，但项目级 `false` 无法覆盖用户或策略级 `true`。通过 `--mcp-config` 显式传递的 servers 不受影响。要拒绝单个连接器而不是所有连接器，请改用 [`deniedMcpServers`](/zh-CN/managed-mcp)。需要 Claude Code v2.1.182 或更高版本 | `true` |

254| `disableDeepLinkRegistration` | 设置为 `"disable"` 以防止 Claude Code 在启动时向操作系统注册 `claude-cli://` 协议处理程序。[深链接](/zh-CN/deep-links)让外部工具通过预填充的提示打开 Claude Code 会话。在协议处理程序注册受限或单独管理的环境中很有用 | `"disable"` |258| `disableDeepLinkRegistration` | 设置为 `"disable"` 以防止 Claude Code 在启动时向操作系统注册 `claude-cli://` 协议处理程序。[深链接](/zh-CN/deep-links)让外部工具通过预填充的提示打开 Claude Code 会话。在协议处理程序注册受限或单独管理的环境中很有用 | `"disable"` |

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

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

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

269| `feedbackSurveyRate` | 概率（0–1）[会话质量调查](/zh-CN/data-usage#session-quality-surveys)在符合条件时出现。设置为 `0` 以完全抑制，或在 `env` 中设置 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/zh-CN/env-vars)。在使用 Bedrock、Vertex 或 Foundry 时很有用，其中默认采样率不适用 | `0.05` |273| `feedbackSurveyRate` | 概率（0–1）[会话质量调查](/zh-CN/data-usage#session-quality-surveys)在符合条件时出现。设置为 `0` 以完全抑制，或在 `env` 中设置 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/zh-CN/env-vars)。在使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 时很有用，其中默认采样率不适用 | `0.05` |

270| `fileCheckpointingEnabled` | {/* min-version: 2.1.119 */}**默认**：`true`。在每次编辑前快照文件，以便 [`/rewind`](/zh-CN/checkpointing) 可以恢复它们。在 `/config` 中显示为**回退代码（checkpoints）**。要通过环境变量禁用，请在 `env` 中设置 [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/zh-CN/env-vars) | `false` |274| `fileCheckpointingEnabled` | {/* min-version: 2.1.119 */}**默认**：`true`。在每次编辑前快照文件，以便 [`/rewind`](/zh-CN/checkpointing) 可以恢复它们。在 `/config` 中显示为**回退代码（checkpoints）**。要通过环境变量禁用，请在 `env` 中设置 [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/zh-CN/env-vars) | `false` |

271| `fileSuggestion` | 为 `@` 文件自动完成配置自定义脚本。请参阅[文件建议设置](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |275| `fileSuggestion` | 为 `@` 文件自动完成配置自定义脚本。请参阅[文件建议设置](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |

272| `footerLinksRegexes` | {/* min-version: 2.1.176 */}当正则表达式匹配轮次输出时渲染额外的可点击徽章在页脚中。每个条目有一个 `pattern`、一个 URL 模板，其中 `{name}` 占位符从命名捕获组填充，以及一个可选的 `label`。仅从用户、`--settings` 标志和 managed 设置读取。请参阅[页脚链接徽章](#footer-link-badges)了解 URL 约束、方案允许列表和限制。需要 Claude Code v2.1.176 或更高版本 | `[{"type": "regex", "pattern": "\\b(?<key>PROJ-\\d+)\\b", "url": "https://issues.example.com/browse/{key}", "label": "{key}"}]` |276| `footerLinksRegexes` | {/* min-version: 2.1.176 */}当正则表达式匹配轮次输出时渲染额外的可点击徽章在页脚中。每个条目有一个 `pattern`、一个 URL 模板，其中 `{name}` 占位符从命名捕获组填充，以及一个可选的 `label`。仅从用户、`--settings` 标志和 managed 设置读取。请参阅[页脚链接徽章](#footer-link-badges)了解 URL 约束、方案允许列表和限制。需要 Claude Code v2.1.176 或更高版本 | `[{"type": "regex", "pattern": "\\b(?<key>PROJ-\\d+)\\b", "url": "https://issues.example.com/browse/{key}", "label": "{key}"}]` |

273| `forceLoginMethod` | 使用 `claudeai` 限制登录到 Claude.ai 账户，`console` 限制登录到 Claude Console 账户，或 `gateway` 限制登录到云网关；请参阅 [Claude apps gateway](/zh-CN/claude-apps-gateway)。在 managed 设置中设置为任何值时，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 进行身份验证的会话在启动时被阻止，因为环境凭证无法满足所需的登录方法。第三方提供商会话（如 Bedrock、Vertex 和 Foundry）不被阻止：它们针对您的云提供商而不是 Anthropic 进行身份验证 | `claudeai` |277| `forceLoginMethod` | 使用 `claudeai` 限制登录到 Claude.ai 账户，`console` 限制登录到 Claude Console 账户，或 `gateway` 限制登录到云网关；请参阅 [Claude apps gateway](/zh-CN/claude-apps-gateway)。在 managed 设置中设置为任何值时，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 进行身份验证的会话在启动时被阻止，因为环境凭证无法满足所需的登录方法。第三方提供商会话（如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry）不被阻止：它们针对您的云提供商而不是 Anthropic 进行身份验证 | `claudeai` |

274| `forceLoginGatewayUrl` | 在 `/login` 云网关屏幕上预填充并锁定网关 URL。此键或 `forceLoginMethod: "gateway"` 中的任一个都会显示该屏幕；同时设置两者以便 URL 被填充。仅在 managed 策略层受尊重；在用户和项目设置中被忽略。请参阅 [Claude apps gateway](/zh-CN/claude-apps-gateway#set-the-gateway-url) | `"https://claude-gateway.example.com"` |278| `forceLoginGatewayUrl` | 在 `/login` 云网关屏幕上预填充并锁定网关 URL。此键或 `forceLoginMethod: "gateway"` 中的任一个都会显示该屏幕；同时设置两者以便 URL 被填充。仅在 managed 策略层受尊重；在用户和项目设置中被忽略。请参阅 [Claude apps gateway](/zh-CN/claude-apps-gateway#set-the-gateway-url) | `"https://claude-gateway.example.com"` |

275| `forceLoginOrgUUID` | 要求登录属于特定 Anthropic 组织。接受单个 UUID 字符串（也在登录期间预选该组织）或 UUID 数组，其中任何列出的组织都被接受而无需预选。在 managed 设置中设置时，如果经过身份验证的账户不属于列出的组织，登录失败；由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 进行身份验证的会话在启动时被阻止，因为无法为它们验证组织成员身份。第三方提供商会话（如 Bedrock、Vertex 和 Foundry）不被阻止：使用您的云 IAM 限制哪些云账户可以被使用。空数组失败关闭并使用配置错误消息阻止登录 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 或 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |279| `forceLoginOrgUUID` | 要求登录属于特定 Anthropic 组织。接受单个 UUID 字符串（也在登录期间预选该组织）或 UUID 数组，其中任何列出的组织都被接受而无需预选。在 managed 设置中设置时，如果经过身份验证的账户不属于列出的组织，登录失败；由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 进行身份验证的会话在启动时被阻止，因为无法为它们验证组织成员身份。第三方提供商会话（如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry）不被阻止：使用您的云 IAM 限制哪些云账户可以被使用。空数组失败关闭并使用配置错误消息阻止登录 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 或 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |

276| `forceRemoteSettingsRefresh` | （仅 Managed 设置）阻止 CLI 启动，直到从服务器新鲜获取远程 managed 设置。如果获取失败，CLI 退出而不是继续使用缓存或无设置。未设置时，启动继续而不等待远程设置。请参阅[失败关闭强制执行](/zh-CN/server-managed-settings#enforce-fail-closed-startup) | `true` |280| `forceRemoteSettingsRefresh` | （仅 Managed 设置）阻止 CLI 启动，直到从服务器新鲜获取远程 managed 设置。如果获取失败，CLI 退出而不是继续使用缓存或无设置。未设置时，启动继续而不等待远程设置。请参阅[失败关闭强制执行](/zh-CN/server-managed-settings#enforce-fail-closed-startup) | `true` |

277| `gcpAuthRefresh` | 当 GCP Application Default Credentials 过期或无法加载时刷新它们的自定义脚本。请参阅[高级凭证配置](/zh-CN/google-vertex-ai#advanced-credential-configuration) | `gcloud auth application-default login` |281| `gcpAuthRefresh` | 当 GCP Application Default Credentials 过期或无法加载时刷新它们的自定义脚本。请参阅[高级凭证配置](/zh-CN/google-vertex-ai#advanced-credential-configuration) | `gcloud auth application-default login` |

282| `language` | 配置 Claude 的首选响应语言（例如 `"japanese"`、`"spanish"`、`"french"`）。Claude 将默认以此语言响应。也设置[语音听写](/zh-CN/voice-dictation#change-the-dictation-language)语言和自动生成的会话标题。{/* min-version: 2.1.176 */}从 v2.1.176 开始，未设置时，会话标题与您的对话语言匹配 | `"japanese"` |286| `language` | 配置 Claude 的首选响应语言（例如 `"japanese"`、`"spanish"`、`"french"`）。Claude 将默认以此语言响应。也设置[语音听写](/zh-CN/voice-dictation#change-the-dictation-language)语言和自动生成的会话标题。{/* min-version: 2.1.176 */}从 v2.1.176 开始，未设置时，会话标题与您的对话语言匹配 | `"japanese"` |

283| `minimumVersion` | 防止后台自动更新和 `claude update` 安装低于此版本的版本。从 `"latest"` 渠道切换到 `"stable"` 时通过 `/config` 提示您保持在当前版本或允许降级。选择保持设置此值。也在[managed 设置](/zh-CN/permissions#managed-settings)中有用，以固定组织范围的最低版本。对于阻止启动的硬下限，请参阅 `requiredMinimumVersion` | `"2.1.100"` |287| `minimumVersion` | 防止后台自动更新和 `claude update` 安装低于此版本的版本。从 `"latest"` 渠道切换到 `"stable"` 时通过 `/config` 提示您保持在当前版本或允许降级。选择保持设置此值。也在[managed 设置](/zh-CN/permissions#managed-settings)中有用，以固定组织范围的最低版本。对于阻止启动的硬下限，请参阅 `requiredMinimumVersion` | `"2.1.100"` |

285| `modelOverrides` | 将 Anthropic 模型 ID 映射到特定于提供商的模型 ID，例如 Bedrock 推理配置文件 ARN。每个模型选择器条目在调用提供商 API 时使用其映射值。请参阅[按版本覆盖模型 ID](/zh-CN/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |289| `modelOverrides` | 将 Anthropic 模型 ID 映射到特定于提供商的模型 ID，例如 Amazon Bedrock 推理配置文件 ARN。每个模型选择器条目在调用提供商 API 时使用其映射值。请参阅[按版本覆盖模型 ID](/zh-CN/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |

286| `otelHeadersHelper` | 生成动态 OpenTelemetry 标头的脚本。在启动时和定期运行。使用 [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/zh-CN/env-vars) 设置刷新间隔。请参阅[动态标头](/zh-CN/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |290| `otelHeadersHelper` | 生成动态 OpenTelemetry 标头的脚本。在启动时和定期运行。使用 [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/zh-CN/env-vars) 设置刷新间隔。请参阅[动态标头](/zh-CN/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |

288| `parentSettingsBehavior` | {/* min-version: 2.1.133 */}（仅 Managed 设置）**默认**：`"first-wins"`。控制由嵌入主机进程（例如 Agent SDK 或 IDE 扩展）以编程方式提供的 managed 设置在同时存在管理员部署的 managed 层时是否应用。`"first-wins"`：父级提供的设置被丢弃，仅应用管理员层。`"merge"`：父级提供的设置在管理员层下应用，经过筛选以便它们可以收紧策略但不能放松策略。当未部署管理员层时无效。需要 Claude Code v2.1.133 或更高版本 | `"merge"` |292| `parentSettingsBehavior` | {/* min-version: 2.1.133 */}（仅 Managed 设置）**默认**：`"first-wins"`。控制由嵌入主机进程（例如 Agent SDK 或 IDE 扩展）以编程方式提供的 managed 设置在同时存在管理员部署的 managed 层时是否应用。`"first-wins"`：父级提供的设置被丢弃，仅应用管理员层。`"merge"`：父级提供的设置在管理员层下应用，经过筛选以便它们可以收紧策略但不能放松策略。当未部署管理员层时无效。需要 Claude Code v2.1.133 或更高版本 | `"merge"` |

303| `showThinkingSummaries` | **默认**：`false`。在交互式会话中显示[扩展思考](/zh-CN/model-config#extended-thinking)摘要。未设置或 `false` 时，思考块由 API 编辑并显示为折叠的存根。编辑仅改变您看到的内容，而不是模型生成的内容：要减少思考支出，[降低预算或禁用思考](/zh-CN/model-config#extended-thinking)。此设置在非交互模式（`-p`）、Agent SDK 或 IDE 扩展（如 VS Code）中无效 | `true` |307| `showThinkingSummaries` | **默认**：`false`。在交互式会话中显示[扩展思考](/zh-CN/model-config#extended-thinking)摘要。未设置或 `false` 时，思考块由 API 编辑并显示为折叠的存根。编辑仅改变您看到的内容，而不是模型生成的内容：要减少思考支出，[降低预算或禁用思考](/zh-CN/model-config#extended-thinking)。此设置在非交互模式（`-p`）、Agent SDK 或 IDE 扩展（如 VS Code）中无效 | `true` |

305| `skillListingBudgetFraction` | {/* min-version: 2.1.105 */}**默认**：`0.01`（1%）。为[skill 列表](/zh-CN/skills#skill-descriptions-are-cut-short)预留的模型上下文窗口的分数，Claude 每轮看到。当列表超过预算时，最少使用的 skills 的描述被折叠为仅名称，以便 Claude 仍可以调用它们但不会看到原因。提高以保持更多描述可见，代价是每轮更多上下文。`/doctor` 显示当前截断计数和受影响的 skills。需要 Claude Code v2.1.105 或更高版本 | `0.02` |309| `skillListingBudgetFraction` | {/* min-version: 2.1.105 */}**默认**：`0.01`。为[skill 列表](/zh-CN/skills#skill-descriptions-are-cut-short)预留的模型上下文窗口的分数，Claude 每轮看到。当列表超过预算时，最少使用的 skills 的描述被折叠为仅名称，以便 Claude 仍可以调用它们但不会看到原因。提高以保持更多描述可见，代价是每轮更多上下文。`/doctor` 显示当前截断计数和受影响的 skills。需要 Claude Code v2.1.105 或更高版本 | `0.02` |

306| `skillListingMaxDescChars` | {/* min-version: 2.1.105 */}**默认**：`1536`。[skill 列表](/zh-CN/skills#skill-descriptions-are-cut-short)中每个 skill 的 `description` 和 `when_to_use` 文本组合的字符上限。超过此长度的文本被截断。提高以保持长描述完整，代价是每轮更多上下文；降低以在 [`skillListingBudgetFraction`](#available-settings) 下适应更多 skills。需要 Claude Code v2.1.105 或更高版本 | `2048` |310| `skillListingMaxDescChars` | {/* min-version: 2.1.105 */}**默认**：`1536`。[skill 列表](/zh-CN/skills#skill-descriptions-are-cut-short)中每个 skill 的 `description` 和 `when_to_use` 文本组合的字符上限。超过此长度的文本被截断。提高以保持长描述完整，代价是每轮更多上下文；降低以在 [`skillListingBudgetFraction`](#available-settings) 下适应更多 skills。需要 Claude Code v2.1.105 或更高版本 | `2048` |

307| `skillOverrides` | {/* min-version: 2.1.129 */}按 skill 名称键入的每个 skill 可见性覆盖。值为 `"on"`、`"name-only"`、`"user-invocable-only"` 或 `"off"`。让您隐藏或折叠 skill 而无需编辑其 SKILL.md。不适用于插件 skills，这些通过 `/plugin` 管理。`/skills` 菜单将这些写入 `.claude/settings.local.json`。请参阅[从设置覆盖 skill 可见性](/zh-CN/skills#override-skill-visibility-from-settings)。需要 Claude Code v2.1.129 或更高版本 | `{"legacy-context": "name-only", "deploy": "off"}` |311| `skillOverrides` | {/* min-version: 2.1.129 */}按 skill 名称键入的每个 skill 可见性覆盖。值为 `"on"`、`"name-only"`、`"user-invocable-only"` 或 `"off"`。让您隐藏或折叠 skill 而无需编辑其 SKILL.md。不适用于插件 skills，这些通过 `/plugin` 管理。`/skills` 菜单将这些写入 `.claude/settings.local.json`。请参阅[从设置覆盖 skill 可见性](/zh-CN/skills#override-skill-visibility-from-settings)。需要 Claude Code v2.1.129 或更高版本 | `{"legacy-context": "name-only", "deploy": "off"}` |

308| `skipWebFetchPreflight` | 跳过[WebFetch 域安全检查](/zh-CN/data-usage#webfetch-domain-safety-check)，该检查在获取前将每个请求的主机名发送到 `api.anthropic.com`。在阻止到 Anthropic 的流量的环境中设置为 `true`，例如 Bedrock、Vertex AI 或 Foundry 部署，具有限制性出站。跳过时，WebFetch 尝试任何 URL 而不咨询阻止列表 | `true` |312| `skipWebFetchPreflight` | 跳过[WebFetch 域安全检查](/zh-CN/data-usage#webfetch-domain-safety-check)，该检查在获取前将每个请求的主机名发送到 `api.anthropic.com`。在阻止到 Anthropic 的流量的环境中设置为 `true`，例如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 部署，具有限制性出站。跳过时，WebFetch 尝试任何 URL 而不咨询阻止列表 | `true` |

310| `spinnerTipsOverride` | 使用自定义字符串覆盖微调器提示。`tips`：提示字符串数组。`excludeDefault`：如果为 `true`，仅显示自定义提示；如果为 `false` 或不存在，自定义提示与内置提示合并 | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |314| `spinnerTipsOverride` | 使用自定义字符串覆盖微调器提示。`tips`：提示字符串数组。`excludeDefault`：如果为 `true`，仅显示自定义提示；如果为 `false` 或不存在，自定义提示与内置提示合并 | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |

311| `spinnerVerbs` | 自定义在微调器中显示的操作动词。将 `mode` 设置为 `"replace"` 以仅使用您的动词，或 `"append"` 以将它们添加到默认值 | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |315| `spinnerVerbs` | 自定义在微调器中显示的操作动词。将 `mode` 设置为 `"replace"` 以仅使用您的动词，或 `"append"` 以将它们添加到默认值 | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |

319| `theme` | {/* min-version: 2.1.119 */}**默认**：`"dark"`。界面的颜色主题：`"auto"`、`"dark"`、`"light"`、`"dark-daltonized"`、`"light-daltonized"`、`"dark-ansi"`、`"light-ansi"` 或自定义主题参考，如 `"custom:<slug>"` 或 `"custom:<plugin-name>:<slug>"`。请参阅[创建自定义主题](/zh-CN/terminal-config#create-a-custom-theme)。在 `/config` 中显示为**主题** | `"dark"` |323| `theme` | {/* min-version: 2.1.119 */}**默认**：`"dark"`。界面的颜色主题：`"auto"`、`"dark"`、`"light"`、`"dark-daltonized"`、`"light-daltonized"`、`"dark-ansi"`、`"light-ansi"` 或自定义主题参考，如 `"custom:<slug>"` 或 `"custom:<plugin-name>:<slug>"`。请参阅[创建自定义主题](/zh-CN/terminal-config#create-a-custom-theme)。在 `/config` 中显示为**主题** | `"dark"` |

320| `tui` | 终端 UI 渲染器。使用 `"fullscreen"` 获取无闪烁的[替代屏幕渲染器](/zh-CN/fullscreen)，具有虚拟化滚动条。使用 `"default"` 获取经典主屏幕渲染器。通过 `/tui` 设置。您也可以设置 [`CLAUDE_CODE_NO_FLICKER`](/zh-CN/env-vars) 环境变量。后台会话从[代理视图](/zh-CN/agent-view)打开始终使用全屏渲染器，无论此设置如何 | `"fullscreen"` |324| `tui` | 终端 UI 渲染器。使用 `"fullscreen"` 获取无闪烁的[替代屏幕渲染器](/zh-CN/fullscreen)，具有虚拟化滚动条。使用 `"default"` 获取经典主屏幕渲染器。通过 `/tui` 设置。您也可以设置 [`CLAUDE_CODE_NO_FLICKER`](/zh-CN/env-vars) 环境变量。后台会话从[代理视图](/zh-CN/agent-view)打开始终使用全屏渲染器，无论此设置如何 | `"fullscreen"` |

321| `ultracode` | 为会话打开 [ultracode](/zh-CN/workflows#let-claude-decide-with-ultracode)。仅限会话，不从 `settings.json` 读取。通过 `/effort ultracode`、`--settings` 或 Agent SDK 控制请求设置 | `true` |325| `ultracode` | 为会话打开 [ultracode](/zh-CN/workflows#let-claude-decide-with-ultracode)。仅限会话，不从 `settings.json` 读取。通过 `/effort ultracode`、`--settings` 或 Agent SDK 控制请求设置。{/* min-version: 2.1.203 */}要启动已打开 ultracode 的会话，使用 `claude --effort ultracode` 启动，需要 Claude Code v2.1.203 或更高版本 | `true` |

323| `verbose` | {/* min-version: 2.1.119 */}**默认**：`false`。显示完整工具输出而不是截断的摘要。在 `/config` 中显示为**详细输出**。`--verbose` 标志覆盖此用于一个会话 | `true` |327| `verbose` | {/* min-version: 2.1.119 */}**默认**：`false`。显示完整工具输出而不是截断的摘要。在 `/config` 中显示为**详细输出**。`--verbose` 标志覆盖此用于一个会话 | `true` |

339</Note>343</Note>

340 344

341| 键 | 描述 | 示例 |345| 键 | 描述 | 示例 |

342| :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- |346| :------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- |

343| `autoConnectIde` | **默认**：`false`。当 Claude Code 从外部终端启动时自动连接到运行的 IDE。在 VS Code 或 JetBrains 终端外运行时在 `/config` 中显示为**自动连接到 IDE（外部终端）**。[`CLAUDE_CODE_AUTO_CONNECT_IDE`](/zh-CN/env-vars) 环境变量在设置时覆盖此 | `true` |347| `autoConnectIde` | **默认**：`false`。当 Claude Code 从外部终端启动时自动连接到运行的 IDE。在 VS Code 或 JetBrains 终端外运行时在 `/config` 中显示为**自动连接到 IDE（外部终端）**。[`CLAUDE_CODE_AUTO_CONNECT_IDE`](/zh-CN/env-vars) 环境变量在设置时覆盖此 | `true` |

344| `autoInstallIdeExtension` | **默认**：`true`。从 VS Code 终端运行时自动安装 Claude Code IDE 扩展。在 VS Code 或 JetBrains 终端内运行时在 `/config` 中显示为**自动安装 IDE 扩展**。您也可以设置 [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/zh-CN/env-vars) 环境变量 | `false` |348| `autoInstallIdeExtension` | **默认**：`true`。从 VS Code 终端运行时自动安装 Claude Code IDE 扩展。在 VS Code 或 JetBrains 终端内运行时在 `/config` 中显示为**自动安装 IDE 扩展**。您也可以设置 [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/zh-CN/env-vars) 环境变量 | `false` |

346| `teammateDefaultModel` | [agent team](/zh-CN/agent-teams) 队友的默认模型，当生成提示未指定时。设置为模型别名（如 `"sonnet"`），或 `null` 以继承主导的当前 `/model` 选择。在 `/config` 中显示为**默认队友模型** | `"sonnet"` |350| `teammateDefaultModel` | [agent team](/zh-CN/agent-teams) 队友的默认模型，当生成提示未指定时。设置为模型别名（如 `"sonnet"`），或 `null` 以继承主导的当前 `/model` 选择。在 `/config` 中显示为**默认队友模型** | `"sonnet"` |

351| `workflowSizeGuideline` | {/* min-version: 2.1.202 */}**默认**：`unrestricted`，不发送指南。设置[动态工作流](/zh-CN/workflows#set-a-size-guideline)中 Claude 针对的[代理计数](/zh-CN/workflows#set-a-size-guideline)。Claude Code 将值作为建议而不是强制上限发送给 Claude。接受 `unrestricted`、`small`、`medium` 或 `large`。在 `/config` 中显示为**动态工作流大小**。您也可以使用 `/config workflowSizeGuideline=small` 直接设置它。需要 Claude Code v2.1.202 或更高版本。{/* min-version: 2.1.203 */}指南的代理计数也替换[`Large workflow` 警告](/zh-CN/workflows#cost)的默认阈值；该行为需要 Claude Code v2.1.203 或更高版本 | `"small"` |

347 352

348<h3 id="worktree-settings">353<h3 id="worktree-settings">

349 Worktree 设置354 Worktree 设置

352配置 `--worktree` 如何创建和管理 git worktrees。357配置 `--worktree` 如何创建和管理 git worktrees。

353 358

354| 键 | 描述 | 示例 |359| 键 | 描述 | 示例 |

355| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |360| :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |

356| `worktree.baseRef` | 新 worktrees 分支的参考。`"fresh"`（默认）从 `origin/<default-branch>` 分支以获得与远程匹配的干净树。`"head"` 从您当前的本地 `HEAD` 分支，因此未推送的提交和特性分支状态存在于 worktree 中。适用于 `--worktree`、`EnterWorktree` 工具和 subagent 隔离 | `"head"` |361| `worktree.baseRef` | 新 worktrees 分支的参考。`"fresh"`（默认）从 `origin/<default-branch>` 分支以获得与远程匹配的干净树。`"head"` 从您当前的本地 `HEAD` 分支，因此未推送的提交和特性分支状态存在于 worktree 中。适用于 `--worktree`、`EnterWorktree` 工具和 subagent 隔离 | `"head"` |

359| `worktree.bgIsolation` | {/* min-version: 2.1.143 */}[后台会话](/zh-CN/agent-view#how-file-edits-are-isolated)的隔离模式。`"worktree"`（默认）在调用 `EnterWorktree` 之前阻止主检出中的 `Edit`/`Write`。`"none"` 让后台作业直接编辑工作副本。需要 Claude Code v2.1.143 或更高版本 | `"none"` |364| `worktree.bgIsolation` | {/* min-version: 2.1.143 */}[后台会话](/zh-CN/agent-view#how-file-edits-are-isolated)的隔离模式。`"worktree"`（默认）在调用 `EnterWorktree` 之前阻止主检出中的 `Edit`/`Write`。{/* min-version: 2.1.203 */}在 git 存储库外，失败的 [`WorktreeCreate` hook](/zh-CN/worktrees#non-git-version-control) 释放块，以便会话可以就地编辑工作目录；需要 Claude Code v2.1.203 或更高版本。`"none"` 让后台作业直接编辑工作副本。需要 Claude Code v2.1.143 或更高版本 | `"none"` |

360 365

361要将 gitignored 文件（如 `.env`）复制到新的 worktrees，请在项目根目录中使用 [`.worktreeinclude` 文件](/zh-CN/worktrees#copy-gitignored-files-into-worktrees)，而不是设置。366要将 gitignored 文件（如 `.env`）复制到新的 worktrees，请在项目根目录中使用 [`.worktreeinclude` 文件](/zh-CN/worktrees#copy-gitignored-files-into-worktrees)，而不是设置。

362 367

365</h3>370</h3>

366 371

367| 键 | 描述 | 示例 |372| 键 | 描述 | 示例 |

368| :---------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |373| :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |

369| `allow` | 允许工具使用的权限规则数组。工具名称 globs 仅在字面 `mcp__<server>__` 前缀后的工具位置支持，例如 `mcp__github__get_*`；server 段必须无 glob。请参阅下面的[权限规则语法](#permission-rule-syntax)了解模式匹配详情 | `[ "Bash(git diff *)" ]` |374| `allow` | 允许工具使用的权限规则数组。工具名称 globs 仅在字面 `mcp__<server>__` 前缀后的工具位置支持，例如 `mcp__github__get_*`；server 段必须无 glob。请参阅下面的[权限规则语法](#permission-rule-syntax)了解模式匹配详情 | `[ "Bash(git diff *)" ]` |

370| `ask` | 在工具使用时要求确认的权限规则数组。请参阅下面的[权限规则语法](#permission-rule-syntax) | `[ "Bash(git push *)" ]` |375| `ask` | 在工具使用时要求确认的权限规则数组。请参阅下面的[权限规则语法](#permission-rule-syntax) | `[ "Bash(git push *)" ]` |

371| `deny` | 拒绝工具使用的权限规则数组。使用此排除敏感文件不被 Claude Code 访问。工具名称接受 glob 模式：`"*"` 拒绝每个工具，`"mcp__*"` 拒绝所有 MCP 工具。请参阅[权限规则语法](#permission-rule-syntax)和 [Bash 权限限制](/zh-CN/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |376| `deny` | 拒绝工具使用的权限规则数组。使用此排除敏感文件不被 Claude Code 访问。工具名称接受 glob 模式：`"*"` 拒绝每个工具，`"mcp__*"` 拒绝所有 MCP 工具。请参阅[权限规则语法](#permission-rule-syntax)和 [Bash 权限限制](/zh-CN/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |

372| `additionalDirectories` | Claude 有权访问的额外[工作目录](/zh-CN/permissions#working-directories)。大多数 `.claude/` 配置[未从这些目录发现](/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |377| `additionalDirectories` | Claude 有权访问的额外[工作目录](/zh-CN/permissions#working-directories)。大多数 `.claude/` 配置[未从这些目录发现](/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |

373| `defaultMode` | 打开 Claude Code 时的默认[权限模式](/zh-CN/permission-modes)。有效值：`default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions`。{/* min-version: 2.1.142 */}从 Claude Code v2.1.142 开始，当在项目或本地设置（`.claude/settings.json`、`.claude/settings.local.json`）中设置时，`auto` 被忽略，因此存储库无法授予自己自动模式。改为在 `~/.claude/settings.json` 中设置它。`--permission-mode` CLI 标志覆盖此设置用于单个会话 | `"acceptEdits"` |378| `defaultMode` | 打开 Claude Code 时的默认[权限模式](/zh-CN/permission-modes)。有效值：`default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 和 {/* min-version: 2.1.200 */}}`manual` 作为 `default` 的别名，CLI 和 VS Code 和 JetBrains 扩展中标记为 Manual 的模式。`manual` 别名需要 Claude Code v2.1.200 或更高版本。{/* min-version: 2.1.142 */}}从 Claude Code v2.1.142 开始，当在项目或本地设置（`.claude/settings.json`、`.claude/settings.local.json`）中设置时，`auto` 被忽略，因此存储库无法授予自己自动模式。改为在 `~/.claude/settings.json` 中设置它。`--permission-mode` CLI 标志覆盖此设置用于单个会话 | `"acceptEdits"` |

374| `disableBypassPermissionsMode` | 设置为 `"disable"` 以防止激活 `bypassPermissions` 模式。禁用 `--dangerously-skip-permissions` 标志。在[managed 设置](/zh-CN/permissions#managed-settings)中最有用，用户无法覆盖它 | `"disable"` |379| `disableBypassPermissionsMode` | 设置为 `"disable"` 以防止激活 `bypassPermissions` 模式。禁用 `--dangerously-skip-permissions` 标志。在[managed 设置](/zh-CN/permissions#managed-settings)中最有用，用户无法覆盖它 | `"disable"` |

375| `skipDangerousModePermissionPrompt` | 跳过通过 `--dangerously-skip-permissions` 或 `defaultMode: "bypassPermissions"` 进入 bypass permissions 模式前显示的确认提示。在项目设置（`.claude/settings.json`）中设置时被忽略，以防止不受信任的存储库自动绕过提示 | `true` |380| `skipDangerousModePermissionPrompt` | 跳过通过 `--dangerously-skip-permissions` 或 `defaultMode: "bypassPermissions"` 进入 bypass permissions 模式前显示的确认提示。在项目设置（`.claude/settings.json`）中设置时被忽略，以防止不受信任的存储库自动绕过提示 | `true` |

376 381

setup.md +9 −3

Details

188 身份验证188 身份验证

189</h2>189</h2>

190 190

191Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 账户。免费的 Claude.ai 计划不包括 Claude Code 访问权限。您也可以通过第三方 API 提供商（如 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Vertex AI](/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/zh-CN/microsoft-foundry)）使用 Claude Code。191Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 账户。免费的 Claude.ai 计划不包括 Claude Code 访问权限。您也可以通过第三方 API 提供商（如 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud's Agent Platform](/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/zh-CN/microsoft-foundry)）使用 Claude Code。

192 192

193安装后，通过运行 `claude` 并按照浏览器提示登录。有关所有账户类型和团队设置选项，请参阅[身份验证](/zh-CN/authentication)。193安装后，通过运行 `claude` 并按照浏览器提示登录。有关所有账户类型和团队设置选项，请参阅[身份验证](/zh-CN/authentication)。

194 194

376 376

377<Tabs>377<Tabs>

378 <Tab title="apt">378 <Tab title="apt">

379 适用于 Debian 和 Ubuntu。以下命令配置 `stable` 渠道：379 适用于 Debian 和 Ubuntu。以下安装命令使用 `curl` 下载签名密钥，新安装的 Debian 和 Ubuntu 可能不包含此命令。如果下载失败并显示 `sudo: curl: command not found`，请先安装 curl：

380

381 ```bash theme={null}

382 sudo apt install curl

383 ```

384

385 以下命令配置 `stable` 渠道：

380 386

381 ```bash theme={null}387 ```bash theme={null}

382 sudo install -d -m 0755 /etc/apt/keyrings388 sudo install -d -m 0755 /etc/apt/keyrings

526 </Step>532 </Step>

527 533

528 <Step title="根据清单检查二进制文件">534 <Step title="根据清单检查二进制文件">

529 将您下载的二进制文件的 SHA256 校验和与 `manifest.json` 中 `platforms.<platform>.checksum` 下列出的值进行比较。535 将二进制文件的 SHA256 校验和与 `manifest.json` 中 `platforms.<platform>.checksum` 下列出的值进行比较。以下命令假设当前目录中有 `claude` 二进制文件。要验证已安装的原生二进制文件，请针对 `~/.local/share/claude/versions/VERSION` 运行命令，将 VERSION 替换为您在第 2 步中设置的发布。

530 536

531 <Tabs>537 <Tabs>

532 <Tab title="Linux">538 <Tab title="Linux">

skills.md +11 −8

Details

22 捆绑 skills22 捆绑 skills

23</h2>23</h2>

24 24

25Claude Code 包括一组捆绑 skills，在每个会话中都可用，除非通过 [`disableBundledSkills`](/zh-CN/settings#available-settings) 设置禁用，包括 `/code-review`、`/batch`、`/debug`、`/loop` 和 `/claude-api`。与大多数内置命令不同，内置命令直接执行固定逻辑，捆绑 skills 是基于提示的：它们为 Claude 提供详细的说明，让它使用其工具来编排工作。你调用捆绑 skills 的方式与调用任何其他 skill 相同，输入 `/` 后跟 skill 名称。25Claude Code 包括一组捆绑 skills，在每个会话中都可用，除非通过 [`disableBundledSkills`](/zh-CN/settings#available-settings) 设置禁用，包括 `/doctor`、`/code-review`、`/batch`、`/debug`、`/loop` 和 `/claude-api`。与大多数内置命令不同，内置命令直接执行固定逻辑，捆绑 skills 是基于提示的：它们为 Claude 提供详细的说明，让它使用其工具来编排工作。你调用捆绑 skills 的方式与调用任何其他 skill 相同，输入 `/` 后跟 skill 名称。

27[`/doctor`](/zh-CN/commands#all-commands) 设置检查是 Claude Code v2.1.205 及更高版本中 `disableBundledSkills` 的一个例外：当设置打开时，它仍然可以输入。要隐藏它，请设置 `DISABLE_DOCTOR_COMMAND` 环境变量或 [`skillOverrides`](#override-skill-visibility-from-settings) 条目 `"doctor": "off"`。在 v2.1.205 之前，`/doctor` 是一个内置命令而不是捆绑 skill。

26 28

27捆绑 skills 在[命令参考](/zh-CN/commands)中与内置命令一起列出，在"目的"列中标记为 **Skill**。29捆绑 skills 在[命令参考](/zh-CN/commands)中与内置命令一起列出，在"目的"列中标记为 **Skill**。

28 30

129 131

130输入 `/deploy` 运行项目根目录 skill。输入限定名称 `/apps/web:deploy` 来显式运行嵌套变体。132输入 `/deploy` 运行项目根目录 skill。输入限定名称 `/apps/web:deploy` 来显式运行嵌套变体。

131 133

134当你或 Claude 调用非限定名称时，项目根目录 skill 加载，Claude Code 将目录限定变体列表附加到其内容中，并指示也调用任何目录包含 Claude 正在处理的文件的变体。因此，嵌套 skill 在仅调用非限定名称时仍然适用于其目录中的工作。需要 Claude Code v2.1.203 或更高版本。

135

132一个 `<skill-name>` 条目在企业、个人或项目位置可以是指向磁盘上其他位置的目录的符号链接。Claude Code 跟随符号链接并从目标目录读取 `SKILL.md`，如果同一目标可从多个位置访问，Claude Code 只加载一次该 skill。插件 skills 以不同的方式处理符号链接；请参阅[使用符号链接在市场中共享文件](/zh-CN/plugins-reference#share-files-within-a-marketplace-with-symlinks)。136一个 `<skill-name>` 条目在企业、个人或项目位置可以是指向磁盘上其他位置的目录的符号链接。Claude Code 跟随符号链接并从目标目录读取 `SKILL.md`，如果同一目标可从多个位置访问，Claude Code 只加载一次该 skill。插件 skills 以不同的方式处理符号链接；请参阅[使用符号链接在市场中共享文件](/zh-CN/plugins-reference#share-files-within-a-marketplace-with-symlinks)。

133 137

134<Note>138<Note>

181 来自 `--add-dir` 目录的 CLAUDE.md 文件默认不加载。要加载它们，请设置 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`。请参阅[从其他目录加载](/zh-CN/memory#load-from-additional-directories)。185 来自 `--add-dir` 目录的 CLAUDE.md 文件默认不加载。要加载它们，请设置 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`。请参阅[从其他目录加载](/zh-CN/memory#load-from-additional-directories)。

182</Note>186</Note>

183 187

184***

~~185~~

186title: "配置 skills"

187description: "通过 YAML frontmatter 和 markdown 内容配置 skills，包括 frontmatter 参考、字符串替换和工具权限。"

~~188~~

189<h2 id="configure-skills">188<h2 id="configure-skills">

190 配置 skills189 配置 skills

191</h2>190</h2>

396 394

397当你或 Claude 调用一个 skill 时，呈现的 `SKILL.md` 内容作为单个消息进入对话，并在会话的其余部分保持在那里。Claude Code 不会在后续轮次重新读取 skill 文件，因此将应该在整个任务中应用的指导写成常设说明，而不是一次性步骤。395当你或 Claude 调用一个 skill 时，呈现的 `SKILL.md` 内容作为单个消息进入对话，并在会话的其余部分保持在那里。Claude Code 不会在后续轮次重新读取 skill 文件，因此将应该在整个任务中应用的指导写成常设说明，而不是一次性步骤。

398 396

397当 Claude 重新调用一个 skill 且其呈现的内容与已在上下文中的副本相同时，Claude Code 添加一个简短的说明，表示该 skill 已加载，而不是内容的第二份副本。当呈现的内容不同时，因为参数改变或[动态上下文](#inject-dynamic-context)命令产生了新输出，Claude Code 会再次附加完整内容。在 v2.1.202 之前，每次重新调用都会附加 skill 说明的另一份完整副本。

398

399[自动压缩](/zh-CN/how-claude-code-works#when-context-fills-up)在令牌预算内转发调用的 skills。当对话被总结以释放上下文时，Claude Code 在总结后重新附加每个 skill 的最新调用，保留前 5,000 个令牌。重新附加的 skills 共享 25,000 个令牌的组合预算。Claude Code 从最近调用的 skill 开始填充此预算，因此如果你在一个会话中调用了许多 skills，较旧的 skills 可能会在压缩后完全删除。399[自动压缩](/zh-CN/how-claude-code-works#when-context-fills-up)在令牌预算内转发调用的 skills。当对话被总结以释放上下文时，Claude Code 在总结后重新附加每个 skill 的最新调用，保留前 5,000 个令牌。重新附加的 skills 共享 25,000 个令牌的组合预算。Claude Code 从最近调用的 skill 开始填充此预算，因此如果你在一个会话中调用了许多 skills，较旧的 skills 可能会在压缩后完全删除。

400 400

401如果一个 skill 似乎在第一个响应后停止影响行为，内容通常仍然存在，模型正在选择其他工具或方法。加强 skill 的 `description` 和说明，以便模型继续偏好它，或使用 [hooks](/zh-CN/hooks) 来确定性地强制行为。如果 skill 很大或你在它之后调用了其他几个，在压缩后重新调用它以恢复完整内容。401如果一个 skill 似乎在第一个响应后停止影响行为，内容通常仍然存在，模型正在选择其他工具或方法。加强 skill 的 `description` 和说明，以便模型继续偏好它，或使用 [hooks](/zh-CN/hooks) 来确定性地强制行为。如果 skill 很大或你在它之后调用了其他几个，在压缩后重新调用它以恢复完整内容。

914 Skill 描述被截断914 Skill 描述被截断

915</h3>915</h3>

916 916

917Skill 描述被加载到上下文中，以便 Claude 知道什么可用。所有 skill 名称始终包括，但如果你有许多 skills，描述会被缩短以适应字符预算，这可能会删除 Claude 需要匹配你的请求的关键字。预算按模型上下文窗口的 1% 进行扩展。当预算溢出时，你调用最少的 skills 的描述会首先被删除，因此你实际使用的 skills 会保留其完整文本。运行 `/doctor` 以查看有多少 skill 描述被缩短或删除以及哪些 skills 受到影响。917Claude Code 将 skill 名称和描述的列表加载到上下文中，以便 Claude 知道什么可用。列表始终包含每个 skill 名称，但如果你有许多 skills，Claude Code 会缩短描述以适应列表的字符预算，这可能会删除 Claude 需要匹配你的请求的关键字。预算按模型上下文窗口的 1% 进行扩展。当列表超出预算时，Claude Code 会从你调用最少的 skills 开始删除描述，因此你使用最多的 skills 会保留其完整文本。

918

919运行 `/doctor` 以估计列表的上下文成本及其最大贡献者。当列表超出预算时，Claude Code 也会向调试日志写入警告，可通过 [`--debug`](/zh-CN/cli-reference#cli-flags) 查看。

918 920

919从 v2.1.196 开始，`/context` 中的 Skills 行报告应用预算后的列表大小，因此它与模型接收的内容相匹配。早期版本计算每个描述的完整文本，因此该行可能显示的值比预算 `/doctor` 报告的值大几倍。921`/context` 中的 Skills 行报告应用预算后的列表大小，因此它与模型接收的内容相匹配。在 v2.1.196 之前，该行计算每个描述的完整文本，可能显示的值比配置的预算大几倍。

920 922

921要提高预算，设置 [`skillListingBudgetFraction`](/zh-CN/settings#available-settings) 设置（例如 `0.02` = 2%）或 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 环境变量为固定字符数。要为其他 skills 释放预算，在 [`skillOverrides`](#override-skill-visibility-from-settings) 中将低优先级条目设置为 `"name-only"`，以便它们列出而不显示描述。你也可以在源处修剪 `description` 和 `when_to_use` 文本：前置关键用例，因为每个条目的组合文本被限制为 1,536 个字符，无论预算如何。该限制可通过 [`skillListingMaxDescChars`](/zh-CN/settings#available-settings) 进行配置。923要提高预算，设置 [`skillListingBudgetFraction`](/zh-CN/settings#available-settings) 设置（例如 `0.02` = 2%）或 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 环境变量为固定字符数。要为其他 skills 释放预算，在 [`skillOverrides`](#override-skill-visibility-from-settings) 中将低优先级条目设置为 `"name-only"`，以便它们列出而不显示描述。你也可以在源处修剪 `description` 和 `when_to_use` 文本：前置关键用例，因为每个条目的组合文本被限制为 1,536 个字符，无论预算如何。该限制可通过 [`skillListingMaxDescChars`](/zh-CN/settings#available-settings) 进行配置。

922 924

statusline.md +3 −1

Details

1044}1044}

1045```1045```

1046 1046

1047该命令在每个刷新周期运行一次，所有可见的子代理行作为单个 JSON 对象传递到 stdin。输入包括[基本钩子字段](/zh-CN/hooks#common-input-fields)加上 `columns`（可用行宽）和 `tasks` 数组，其中每个任务有 `id`、`name`、`type`、`status`、`description`、`label`、`startTime`、`tokenCount`、`tokenSamples` 和 `cwd`。1047该命令在每个刷新周期运行一次，所有可见的子代理行作为单个 JSON 对象传递到 stdin。输入包括[基本钩子字段](/zh-CN/hooks#common-input-fields)、`columns` 字段（可用行宽）和 `tasks` 数组。每个任务有 `id`、`name`、`type`、`status`、`description`、`label`、`startTime`、`model`、`contextWindowSize`、`tokenCount`、`tokenSamples` 和 `cwd`。

1048

1049每个任务的 `model` 字段是任务运行的已解析模型 ID。`contextWindowSize` 是该模型的上下文窗口（以令牌计），计算方式与主状态行的 `context_window.context_window_size` 相同，因此你可以从 `tokenCount` 呈现每行百分比。这两个字段需要 Claude Code v2.1.205 或更高版本，对于模型尚未解析的任务会被省略。

1048 1050

1049将一个 JSON 行写入 stdout，用于你想覆盖的每一行，形式为 `{"id": "<task id>", "content": "<row body>"}` 。`content` 字符串按原样呈现，包括 ANSI 颜色和 OSC 8 超链接。省略任务的 `id` 以保持该行的默认呈现；发出空 `content` 字符串以隐藏它。1051将一个 JSON 行写入 stdout，用于你想覆盖的每一行，形式为 `{"id": "<task id>", "content": "<row body>"}` 。`content` 字符串按原样呈现，包括 ANSI 颜色和 OSC 8 超链接。省略任务的 `id` 以保持该行的默认呈现；发出空 `content` 字符串以隐藏它。

1050 1052

sub-agents.md +10 −4

Details

183 183

184Claude Code 递归扫描 `.claude/agents/` 和 `~/.claude/agents/`，因此您可以将定义组织到子文件夹中，例如 `agents/review/` 或 `agents/research/`。子目录路径不会影响 subagent 的识别或调用方式，因为身份仅来自 `name` frontmatter 字段。184Claude Code 递归扫描 `.claude/agents/` 和 `~/.claude/agents/`，因此您可以将定义组织到子文件夹中，例如 `agents/review/` 或 `agents/research/`。子目录路径不会影响 subagent 的识别或调用方式，因为身份仅来自 `name` frontmatter 字段。

185 185

186在整个树中保持 `name` 值唯一：如果一个范围内的两个文件声明相同的名称，Claude Code 仅加载其中一个。{/* min-version: 2.1.196 */}从 v2.1.196 开始，运行 `/doctor` 会报告同范围内的重复代理名称，并显示哪个定义是活跃的。186在整个树中保持 `name` 值唯一：如果同一 `.claude/agents/` 目录下的两个文件（包括其子文件夹）声明相同的名称，Claude Code 仅加载其中一个，由文件系统读取顺序选择，而不是有文档记录的优先级。在嵌套项目目录中，最接近工作目录的定义获胜，如上所述。{/* min-version: 2.1.205 */}[`/doctor`](/zh-CN/commands#all-commands) 设置检查报告同一目录中共享名称的文件，并建议重命名或删除除一个之外的所有文件。在 v2.1.205 之前，`/doctor` 打开一个诊断屏幕，列出重复项并显示哪个定义是活跃的。

187 187

188Plugin `agents/` 目录也会被递归扫描。与项目和用户范围不同，plugin 的 `agents/` 目录内的子文件夹成为 [scoped identifier](#invoke-subagents-explicitly) 的一部分：plugin `my-plugin` 中位于 `agents/review/security.md` 的文件注册为 `my-plugin:review:security`。188Plugin `agents/` 目录也会被递归扫描。与项目和用户范围不同，plugin 的 `agents/` 目录内的子文件夹成为 [scoped identifier](#invoke-subagents-explicitly) 的一部分：plugin `my-plugin` 中位于 `agents/review/security.md` 的文件注册为 `my-plugin:review:security`。

189 189

268 268

269Frontmatter 定义了 subagent 的元数据和配置。正文成为指导 subagent 行为的系统提示。Subagents 仅接收此系统提示（加上基本环境详细信息，如工作目录），而不是完整的 Claude Code 系统提示。269Frontmatter 定义了 subagent 的元数据和配置。正文成为指导 subagent 行为的系统提示。Subagents 仅接收此系统提示（加上基本环境详细信息，如工作目录），而不是完整的 Claude Code 系统提示。

270 270

271在 [non-interactive mode](/zh-CN/headless) 中，[`--append-subagent-system-prompt`](/zh-CN/cli-reference#cli-flags) 标志将您提供的文本附加到每个 subagent 的系统提示末尾，包括嵌套 subagents。需要 Claude Code v2.1.205 或更高版本。

272

271一个 subagent 在主对话的当前工作目录中启动。在 subagent 中，`cd` 命令不会在 Bash 或 PowerShell 工具调用之间持续，也不会影响主对话的工作目录。要给 subagent 一个隔离的存储库副本，请改为设置 [`isolation: worktree`](#supported-frontmatter-fields)。273一个 subagent 在主对话的当前工作目录中启动。在 subagent 中，`cd` 命令不会在 Bash 或 PowerShell 工具调用之间持续，也不会影响主对话的工作目录。要给 subagent 一个隔离的存储库副本，请改为设置 [`isolation: worktree`](#supported-frontmatter-fields)。

272 274

275{/* min-version: 2.1.203 */}具有 `isolation: worktree` 的 subagent 在其 worktree 内运行其 Bash 和 PowerShell 命令。一个工作目录解析到您的主检出的命令，例如因为 worktree 目录在 subagent 运行时被删除，会失败并出现错误。在 v2.1.203 之前，这样的命令可能在主检出中运行。

276

273<h4 id="supported-frontmatter-fields">277<h4 id="supported-frontmatter-fields">

274 支持的 frontmatter 字段278 支持的 frontmatter 字段

275</h4>279</h4>

277以下字段可以在 YAML frontmatter 中使用。只有 `name` 和 `description` 是必需的。281以下字段可以在 YAML frontmatter 中使用。只有 `name` 和 `description` 是必需的。

278 282

279| Field | 必需 | Description |283| Field | 必需 | Description |

280| :---------------- | :- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |284| :---------------- | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

281| `name` | 是 | 使用小写字母和连字符的唯一标识符。[Hooks](/zh-CN/hooks#subagentstart) 将此值作为 `agent_type` 接收。文件名不必匹配 |285| `name` | 是 | 使用小写字母和连字符的唯一标识符。[Hooks](/zh-CN/hooks#subagentstart) 将此值作为 `agent_type` 接收。文件名不必匹配 |

282| `description` | 是 | Claude 何时应该委托给此 subagent |286| `description` | 是 | Claude 何时应该委托给此 subagent |

283| `tools` | 否 | [Tools](#available-tools) subagent 可以使用。如果省略，继承所有工具。要将 Skills 预加载到上下文中，请使用 `skills` 字段而不是在此处列出 `Skill` |287| `tools` | 否 | [Tools](#available-tools) subagent 可以使用。如果省略，继承所有工具。要将 Skills 预加载到上下文中，请使用 `skills` 字段而不是在此处列出 `Skill` |

284| `disallowedTools` | 否 | 要拒绝的工具，从继承或指定的列表中删除 |288| `disallowedTools` | 否 | 要拒绝的工具，从继承或指定的列表中删除 |

285| `model` | 否 | [Model](#choose-a-model) 使用：`sonnet`、`opus`、`haiku`、`fable`、完整模型 ID（例如，`claude-opus-4-8`）或 `inherit`。默认为 `inherit` |289| `model` | 否 | [Model](#choose-a-model) 使用：`sonnet`、`opus`、`haiku`、`fable`、完整模型 ID（例如，`claude-opus-4-8`）或 `inherit`。默认为 `inherit` |

286| `permissionMode` | 否 | [Permission mode](#permission-modes)：`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions` 或 `plan`。对于 [plugin subagents](#choose-the-subagent-scope) 被忽略 |290| `permissionMode` | 否 | [Permission mode](#permission-modes)：`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`、`plan` 或 {/* min-version: 2.1.200 */}`manual` 作为 `default` 的别名。`manual` 别名需要 Claude Code v2.1.200 或更高版本。对于 [plugin subagents](#choose-the-subagent-scope) 被忽略 |

287| `maxTurns` | 否 | subagent 停止前的最大代理轮数 |291| `maxTurns` | 否 | subagent 停止前的最大代理轮数 |

288| `skills` | 否 | [Skills](/zh-CN/skills) 在启动时加载到 subagent 的上下文中。注入完整的技能内容，而不仅仅是描述。Subagents 仍然可以通过 Skill 工具调用未列出的项目、用户和 plugin 技能 |292| `skills` | 否 | [Skills](/zh-CN/skills) 在启动时加载到 subagent 的上下文中。注入完整的技能内容，而不仅仅是描述。Subagents 仍然可以通过 Skill 工具调用未列出的项目、用户和 plugin 技能 |

289| `mcpServers` | 否 | [MCP servers](/zh-CN/mcp) 对此 subagent 可用。每个条目要么是引用已配置服务器的服务器名称（例如，`"slack"`），要么是内联定义，其中服务器名称为键，完整的 [MCP server config](/zh-CN/mcp#installing-mcp-servers) 为值。对于 [plugin subagents](#choose-the-subagent-scope) 被忽略 |293| `mcpServers` | 否 | [MCP servers](/zh-CN/mcp) 对此 subagent 可用。每个条目要么是引用已配置服务器的服务器名称（例如，`"slack"`），要么是内联定义，其中服务器名称为键，完整的 [MCP server config](/zh-CN/mcp#installing-mcp-servers) 为值。对于 [plugin subagents](#choose-the-subagent-scope) 被忽略 |

790 794

791{/* min-version: 2.1.199 */}从 v2.1.199 开始，subagent 的运行因 API 错误（例如使用限制或重复的服务器错误）而结束时，会向 Claude 报告该失败，而不是返回错误文本，就像它是 subagent 的发现一样。Claude 接收的内容取决于 subagent 运行的位置：795{/* min-version: 2.1.199 */}从 v2.1.199 开始，subagent 的运行因 API 错误（例如使用限制或重复的服务器错误）而结束时，会向 Claude 报告该失败，而不是返回错误文本，就像它是 subagent 的发现一样。Claude 接收的内容取决于 subagent 运行的位置：

792 796

793* **前台**：如果速率限制、过载或服务器错误切断已经产生输出的 subagent，Agent 工具返回该部分输出，并注明 subagent 被切断且未完成其任务。否则工具调用失败，出现 [`Agent terminated early due to an API error`](/zh-CN/errors#agent-terminated-early-due-to-an-api-error)，后跟错误详情。797* **前台**：如果速率限制、过载或服务器错误切断已经产生输出的 subagent，Agent 工具返回该部分输出，并注明 subagent 被切断且未完成其任务。{/* min-version: 2.1.200 */}未产生任何内容的 subagent，或其唯一输出是工具调用的 subagent，失败并出现 [`Agent terminated early due to an API error`](/zh-CN/errors#agent-terminated-early-due-to-an-api-error)，后跟错误详情。在 v2.1.199 中，切断仅工具调用形状的速率限制、过载或服务器错误返回了仅包含切断注记的空部分结果。

794* **后台**：subagent 被标记为失败，Claude 在其结束时接收的消息命名 API 错误并包括 subagent 的最后输出，所以部分工作不会丢失。798* **后台**：subagent 被标记为失败，Claude 在其结束时接收的消息命名 API 错误并包括 subagent 的最后输出，所以部分工作不会丢失。

795 799

796一旦底层 API 错误清除，要求 Claude 重试任务或 [恢复 subagent](#resume-subagents)。800一旦底层 API 错误清除，要求 Claude 重试任务或 [恢复 subagent](#resume-subagents)。

920 924

921如果停止的 subagent 接收 `SendMessage`，它会在后台自动恢复，无需新的 `Agent` 调用。925如果停止的 subagent 接收 `SendMessage`，它会在后台自动恢复，无需新的 `Agent` 调用。

922 926

927恢复在相同 ID 下启动代理的新运行，所以已经失败或完成的 subagent 在任务列表和 Agent SDK 的任务事件中再次显示为运行。在 v2.1.205 之前，它在恢复的运行工作时保持显示其早期的失败或完成状态。

928

923{/* min-version: 2.1.199 */}从 v2.1.199 开始，`SendMessage` 检查名称是否仍然指向它在对话中早期到达的同一代理。如果较新的代理已经采用了该名称，例如重新生成的后台代理重新使用了它，Claude Code 会拒绝发送，而不是将其传递给错误的代理，错误会报告该名称现在到达的代理，以便 Claude 可以重新定向。要在它仍在运行时到达早期的代理，Claude 通过其生成结果中的代理 ID 来寻址它。检查的范围是当前对话，并在 `/clear` 时重置。929{/* min-version: 2.1.199 */}从 v2.1.199 开始，`SendMessage` 检查名称是否仍然指向它在对话中早期到达的同一代理。如果较新的代理已经采用了该名称，例如重新生成的后台代理重新使用了它，Claude Code 会拒绝发送，而不是将其传递给错误的代理，错误会报告该名称现在到达的代理，以便 Claude 可以重新定向。要在它仍在运行时到达早期的代理，Claude 通过其生成结果中的代理 ID 来寻址它。检查的范围是当前对话，并在 `/clear` 时重置。

924 930

925{/* min-version: 2.1.198 */}从 v2.1.198 开始，subagent 将来自启动它的代理的消息视为正常任务方向，包括中途任务方向更正，并在其自己的权限设置内对其进行操作。无论谁发送消息，两个限制仍然成立：来自任何代理的消息都不计为您对待处理权限提示的批准，任何代理消息都无法改变 subagent 的权限设置、`CLAUDE.md` 或配置。只有权限系统或您自己的消息可以授予批准。931{/* min-version: 2.1.198 */}从 v2.1.198 开始，subagent 将来自启动它的代理的消息视为正常任务方向，包括中途任务方向更正，并在其自己的权限设置内对其进行操作。无论谁发送消息，两个限制仍然成立：来自任何代理的消息都不计为您对待处理权限提示的批准，任何代理消息都无法改变 subagent 的权限设置、`CLAUDE.md` 或配置。只有权限系统或您自己的消息可以授予批准。

third-party-integrations.md +14 −14

Details

102 <th>Anthropic Console</th>102 <th>Anthropic Console</th>

103 <th>Amazon Bedrock</th>103 <th>Amazon Bedrock</th>

104 <th>Claude Platform on AWS</th>104 <th>Claude Platform on AWS</th>

105 <th>Google Vertex AI</th>105 <th>Google Cloud's Agent Platform，原名 Vertex AI</th>

106 <th>Microsoft Foundry</th>106 <th>Microsoft Foundry</th>

107 </tr>107 </tr>

108 </thead>108 </thead>

196 196

197* [Claude for Teams 或 Enterprise](/zh-CN/authentication#claude-for-teams-or-enterprise)197* [Claude for Teams 或 Enterprise](/zh-CN/authentication#claude-for-teams-or-enterprise)

198* [Anthropic Console](/zh-CN/authentication#claude-console-authentication)198* [Anthropic Console](/zh-CN/authentication#claude-console-authentication)

199* [Claude 应用网关](/zh-CN/claude-apps-gateway)，一个自托管网关，在 Amazon Bedrock、Claude Platform on AWS、Google Vertex AI、Microsoft Foundry 或 Anthropic API 前面添加 IdP 登录199* [Claude 应用网关](/zh-CN/claude-apps-gateway)，一个自托管网关，在 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform、Microsoft Foundry 或 Anthropic API 前面添加 IdP 登录

200* [Amazon Bedrock](/zh-CN/amazon-bedrock)200* [Amazon Bedrock](/zh-CN/amazon-bedrock)

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

202* [Google Vertex AI](/zh-CN/google-vertex-ai)202* [Google Cloud's Agent Platform](/zh-CN/google-vertex-ai)

203* [Microsoft Foundry](/zh-CN/microsoft-foundry)203* [Microsoft Foundry](/zh-CN/microsoft-foundry)

204 204

205<h2 id="configure-proxies-and-gateways">205<h2 id="configure-proxies-and-gateways">

219 219

220<Tabs>220<Tabs>

221 <Tab title="企业代理">221 <Tab title="企业代理">

222 通过设置以下[环境变量](/zh-CN/env-vars)，将 Bedrock 流量路由通过您的企业代理：222 通过设置以下[环境变量](/zh-CN/env-vars)，将 Amazon Bedrock 流量路由通过您的企业代理：

223 223

224 ```bash theme={null}224 ```bash theme={null}

225 # 启用 Bedrock225 # 启用 Bedrock

232 </Tab>232 </Tab>

233 233

234 <Tab title="LLM 网关">234 <Tab title="LLM 网关">

235 通过设置以下[环境变量](/zh-CN/env-vars)，将 Bedrock 流量路由通过您的 LLM 网关：235 通过设置以下[环境变量](/zh-CN/env-vars)，将 Amazon Bedrock 流量路由通过您的 LLM 网关：

236 236

237 ```bash theme={null}237 ```bash theme={null}

238 # 启用 Bedrock238 # 启用 Bedrock

251 251

252<Tabs>252<Tabs>

253 <Tab title="企业代理">253 <Tab title="企业代理">

254 通过设置以下[环境变量](/zh-CN/env-vars)，将 Foundry 流量路由通过您的企业代理：254 通过设置以下[环境变量](/zh-CN/env-vars)，将 Microsoft Foundry 流量路由通过您的企业代理：

255 255

256 ```bash theme={null}256 ```bash theme={null}

257 # 启用 Microsoft Foundry257 # 启用 Microsoft Foundry

265 </Tab>265 </Tab>

266 266

267 <Tab title="LLM 网关">267 <Tab title="LLM 网关">

268 通过设置以下[环境变量](/zh-CN/env-vars)，将 Foundry 流量路由通过您的 LLM 网关：268 通过设置以下[环境变量](/zh-CN/env-vars)，将 Microsoft Foundry 流量路由通过您的 LLM 网关：

269 269

270 ```bash theme={null}270 ```bash theme={null}

271 # 启用 Microsoft Foundry271 # 启用 Microsoft Foundry

278 </Tab>278 </Tab>

279</Tabs>279</Tabs>

280 280

281<h3 id="google-vertex-ai">281<h3 id="google-cloud’s-agent-platform">

282 Google Vertex AI282 Google Cloud's Agent Platform

283</h3>283</h3>

284 284

285<Tabs>285<Tabs>

286 <Tab title="企业代理">286 <Tab title="企业代理">

287 通过设置以下[环境变量](/zh-CN/env-vars)，将 Vertex AI 流量路由通过您的企业代理：287 通过设置以下[环境变量](/zh-CN/env-vars)，将 Google Cloud's Agent Platform 流量路由通过您的企业代理：

288 288

289 ```bash theme={null}289 ```bash theme={null}

290 # 启用 Vertex290 # 启用 Agent Platform

291 export CLAUDE_CODE_USE_VERTEX=1291 export CLAUDE_CODE_USE_VERTEX=1

292 export CLOUD_ML_REGION=us-east5292 export CLOUD_ML_REGION=us-east5

293 export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id293 export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

298 </Tab>298 </Tab>

299 299

300 <Tab title="LLM 网关">300 <Tab title="LLM 网关">

301 通过设置以下[环境变量](/zh-CN/env-vars)，将 Vertex AI 流量路由通过您的 LLM 网关：301 通过设置以下[环境变量](/zh-CN/env-vars)，将 Google Cloud's Agent Platform 流量路由通过您的 LLM 网关：

302 302

303 ```bash theme={null}303 ```bash theme={null}

304 # 启用 Vertex304 # 启用 Agent Platform

305 export CLAUDE_CODE_USE_VERTEX=1305 export CLAUDE_CODE_USE_VERTEX=1

306 306

307 # 配置 LLM 网关307 # 配置 LLM 网关

348 为云提供商固定模型版本348 为云提供商固定模型版本

349</h3>349</h3>

350 350

351如果您通过 [Bedrock](/zh-CN/amazon-bedrock)、[Vertex AI](/zh-CN/google-vertex-ai)、[Foundry](/zh-CN/microsoft-foundry) 或 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 部署，请使用 `ANTHROPIC_DEFAULT_FABLE_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 固定特定模型版本。如果不固定，模型别名会解析为 Claude Code 为该提供商内置的默认值，这可能滞后于最新版本，并且可能尚未在您的账户中启用。固定让您可以控制用户何时迁移到新模型。有关每个提供商在默认值不可用时的行为，请参阅[模型配置](/zh-CN/model-config#pin-models-for-third-party-deployments)。351如果您通过 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-CN/google-vertex-ai)、[Microsoft Foundry](/zh-CN/microsoft-foundry) 或 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 部署，请使用 `ANTHROPIC_DEFAULT_FABLE_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 固定特定模型版本。如果不固定，模型别名会解析为 Claude Code 为该提供商内置的默认值，这可能滞后于最新版本，并且可能尚未在您的账户中启用。固定让您可以控制用户何时迁移到新模型。有关每个提供商在默认值不可用时的行为，请参阅[模型配置](/zh-CN/model-config#pin-models-for-third-party-deployments)。

352 352

353<h3 id="configure-security-policies">353<h3 id="configure-security-policies">

354 配置安全策略354 配置安全策略

tools-reference.md +12 −12

Details

11要添加自定义工具，请连接一个 [MCP server](/zh-CN/mcp)。要使用可重用的基于提示的工作流扩展 Claude，请编写一个 [skill](/zh-CN/skills)，它通过现有的 `Skill` 工具运行，而不是添加新的工具条目。11要添加自定义工具，请连接一个 [MCP server](/zh-CN/mcp)。要使用可重用的基于提示的工作流扩展 Claude，请编写一个 [skill](/zh-CN/skills)，它通过现有的 `Skill` 工具运行，而不是添加新的工具条目。

12 12

13| 工具 | 描述 | 需要权限 |13| 工具 | 描述 | 需要权限 |

14| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--- |14| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--- |

15| `Agent` | 生成一个具有自己 context window 的 [subagent](/zh-CN/sub-agents)，用于处理任务。请参阅 [Agent 工具行为](#agent-tool-behavior) | 否 |15| `Agent` | 生成一个具有自己 context window 的 [subagent](/zh-CN/sub-agents)，用于处理任务。请参阅 [Agent 工具行为](#agent-tool-behavior) | 否 |

16| `Artifact` | 将 HTML 或 Markdown 文件发布为 [artifact](/zh-CN/artifacts)：一个私有的、交互式的 claude.ai 页面。在 Team 和 Enterprise 计划上，您可以在组织内共享它。{/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}需要 Pro、Max、Team 或 Enterprise 计划和 `/login` 身份验证；请参阅[可用性](/zh-CN/artifacts#availability) | 是 |16| `Artifact` | 将 HTML 或 Markdown 文件发布为 [artifact](/zh-CN/artifacts)：一个私有的、交互式的 claude.ai 页面。在 Team 和 Enterprise 计划上，您可以在组织内共享它。{/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}需要 Pro、Max、Team 或 Enterprise 计划和 `/login` 身份验证；请参阅[可用性](/zh-CN/artifacts#availability) | 是 |

17| `AskUserQuestion` | 提出多选问题以收集需求或澄清歧义。{/* min-version: 2.1.198 */}从 v2.1.198 起，如果您在 60 秒内没有响应，对话框会自动关闭：它会提交您已选择的任何选项，并告诉 Claude 您可能离开了键盘，因此 Claude 会根据自己的判断继续进行，稍后可以重新提问。最后 20 秒会出现倒计时。任何按键都会保持对话框打开，对于报告焦点的终端上的焦点窗口也是如此。设置 [`CLAUDE_AFK_TIMEOUT_MS`](/zh-CN/env-vars#variables) 环境变量以更改 Claude Code 等待的时间，或设置为大值如 `86400000`（24 小时）以在您离开时保持问题打开。此超时仅适用于 `AskUserQuestion` 的多选问题；权限提示（包括计划批准）在空闲时永远不会自动解决 | 否 |17| `AskUserQuestion` | 提出多选问题以收集需求或澄清歧义。{/* min-version: 2.1.200 */}问题保持打开状态直到您回答：默认情况下没有空闲超时。要让空闲对话框自动继续，请将 [`askUserQuestionTimeout`](/zh-CN/settings#available-settings) 设置设置为 `60s`、`5m` 或 `10m`，可以在您的用户 `settings.json` 中或从 `/config` 中的**问题自动继续超时**行进行设置。一旦经过所选的空闲时间且没有输入，对话框会自动关闭：它会提交您已选择的任何选项，并告诉 Claude 您可能离开了键盘，因此 Claude 会根据自己的判断继续进行，稍后可以重新提问。最后 20 秒会出现倒计时。任何按键都会重启计时器，对于报告焦点的终端上的焦点窗口也是如此。超时仅适用于 `AskUserQuestion` 的多选问题；权限提示（包括计划批准）在空闲时永远不会自动解决。在 v2.1.198 和 v2.1.199 中，对话框默认在 60 秒空闲后自动继续，[`CLAUDE_AFK_TIMEOUT_MS`](/zh-CN/env-vars#variables) 是改变这一点的唯一方式 | 否 |

18| `Bash` | 在您的环境中执行 shell 命令。请参阅 [Bash 工具行为](#bash-tool-behavior) | 是 |18| `Bash` | 在您的环境中执行 shell 命令。请参阅 [Bash 工具行为](#bash-tool-behavior) | 是 |

19| `CronCreate` | 在当前会话中安排定期或一次性提示。任务是会话范围的，在 `--resume` 或 `--continue` 时如果未过期则会恢复。请参阅[计划任务](/zh-CN/scheduled-tasks) | 否 |19| `CronCreate` | 在当前会话中安排定期或一次性提示。任务是会话范围的，在 `--resume` 或 `--continue` 时如果未过期则会恢复。请参阅[计划任务](/zh-CN/scheduled-tasks) | 否 |

20| `CronDelete` | 按 ID 取消计划任务 | 否 |20| `CronDelete` | 按 ID 取消计划任务 | 否 |

21| `CronList` | 列出会话中的所有计划任务 | 否 |21| `CronList` | 列出会话中的所有计划任务 | 否 |

22| `Edit` | 对特定文件进行有针对性的编辑。请参阅 [Edit 工具行为](#edit-tool-behavior) | 是 |22| `Edit` | 对特定文件进行有针对性的编辑。请参阅 [Edit 工具行为](#edit-tool-behavior) | 是 |

23| `EnterPlanMode` | 切换到 Plan Mode 以在编码前设计方法 | 否 |23| `EnterPlanMode` | 切换到 Plan Mode 以在编码前设计方法 | 否 |

24| `EnterWorktree` | 创建一个隔离的 [git worktree](/zh-CN/worktrees) 并切换到它。传递 `path` 以切换到当前存储库的现有 worktree，而不是创建新的。从 worktree 会话内，或从具有固定工作目录的 subagent（例如 [`isolation: worktree`](/zh-CN/sub-agents#supported-frontmatter-fields)）中，仅 `path` 形式可用，目标必须在 `.claude/worktrees/` 下 | 否 |24| `EnterWorktree` | 创建一个隔离的 [git worktree](/zh-CN/worktrees) 并切换到它。传递 `path` 以切换到现有 worktree，而不是创建新的。{/* min-version: 2.1.203 */}首次进入时，目标可能是当前存储库的 worktree，或在多存储库工作区中，是嵌套在其中的存储库的 worktree。在 v2.1.203 之前，嵌套存储库的 worktree 被拒绝。从 worktree 会话内，或从具有固定工作目录的 subagent（例如 [`isolation: worktree`](/zh-CN/sub-agents#supported-frontmatter-fields)）中，仅 `path` 形式可用，目标必须在会话存储库的 `.claude/worktrees/` 下 | 否 |

25| `ExitPlanMode` | 提出计划以供批准并退出 Plan Mode | 是 |25| `ExitPlanMode` | 提出计划以供批准并退出 Plan Mode | 是 |

26| `ExitWorktree` | 退出 worktree 会话并返回到原始目录。不适用于已在自己的工作目录中运行的 subagents，例如使用 [`isolation: worktree`](/zh-CN/sub-agents#supported-frontmatter-fields) | 否 |26| `ExitWorktree` | 退出 worktree 会话并返回到原始目录。不适用于已在自己的工作目录中运行的 subagents，例如使用 [`isolation: worktree`](/zh-CN/sub-agents#supported-frontmatter-fields) | 否 |

27| `Glob` | 基于模式匹配查找文件。请参阅 [Glob 工具行为](#glob-tool-behavior) | 否 |27| `Glob` | 基于模式匹配查找文件。请参阅 [Glob 工具行为](#glob-tool-behavior) | 否 |

31| `Monitor` | 在后台运行命令并将每个输出行反馈给 Claude，以便它可以对日志条目、文件更改或轮询状态做出反应。还可以打开 WebSocket 并将每条传入消息视为事件。请参阅 [Monitor 工具](#monitor-tool) | 是 |31| `Monitor` | 在后台运行命令并将每个输出行反馈给 Claude，以便它可以对日志条目、文件更改或轮询状态做出反应。还可以打开 WebSocket 并将每条传入消息视为事件。请参阅 [Monitor 工具](#monitor-tool) | 是 |

32| `NotebookEdit` | 修改 Jupyter notebook 单元格。请参阅 [NotebookEdit 工具行为](#notebookedit-tool-behavior) | 是 |32| `NotebookEdit` | 修改 Jupyter notebook 单元格。请参阅 [NotebookEdit 工具行为](#notebookedit-tool-behavior) | 是 |

33| `PowerShell` | 本地执行 PowerShell 命令。请参阅 [PowerShell 工具](#powershell-tool)了解可用性 | 是 |33| `PowerShell` | 本地执行 PowerShell 命令。请参阅 [PowerShell 工具](#powershell-tool)了解可用性 | 是 |

34| `PushNotification` | 发送桌面通知，以及当 [Remote Control](/zh-CN/remote-control) 已连接时发送手机推送，以便长时间运行的任务或[计划任务](/zh-CN/scheduled-tasks)可以在您离开时联系您。{/* plan-availability: feature=push-notifications providers=anthropic */}推送传递通过 Anthropic 托管的基础设施运行，该基础设施无法从 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 访问 | 否 |34| `PushNotification` | 发送桌面通知，以及当 [Remote Control](/zh-CN/remote-control) 已连接时发送手机推送，以便长时间运行的任务或[计划任务](/zh-CN/scheduled-tasks)可以在您离开时联系您。{/* plan-availability: feature=push-notifications providers=anthropic */}推送传递通过 Anthropic 托管的基础设施运行，该基础设施无法从 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 访问 | 否 |

35| `Read` | 读取文件内容。请参阅 [Read 工具行为](#read-tool-behavior) | 否 |35| `Read` | 读取文件内容。请参阅 [Read 工具行为](#read-tool-behavior) | 否 |

36| `ReadMcpResourceTool` | 按 URI 读取特定 MCP 资源 | 否 |36| `ReadMcpResourceTool` | 按 URI 读取特定 MCP 资源 | 否 |

37| `RemoteTrigger` | 在 claude.ai 上创建、更新、运行和列出 [Routines](/zh-CN/routines)。支持 `/schedule` 命令。{/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Routines 存在于 claude.ai 上，需要 Pro、Max、Team 或 Enterprise 计划，因此此工具无法从 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 访问 | 否 |37| `RemoteTrigger` | 在 claude.ai 上创建、更新、运行和列出 [Routines](/zh-CN/routines)。支持 `/schedule` 命令。{/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Routines 存在于 claude.ai 上，需要 Pro、Max、Team 或 Enterprise 计划，因此此工具无法从 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 访问 | 否 |

38| `ReportFindings` | 将代码审查发现报告为结构化列表，每个发现包含文件、摘要和失败场景，以便 Claude Code 可以呈现它们而不是将其打印为文本。当活跃的代码审查指令告诉它时，Claude 会调用它。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更高版本。{/* min-version: 2.1.199 */}从 v2.1.199 起，发现还可以携带可选的 `category` 字段，例如 `correctness` 或 `test-coverage`，显示在呈现列表中的文件位置旁边 | 否 |38| `ReportFindings` | 将代码审查发现报告为结构化列表，每个发现包含文件、摘要和失败场景，以便 Claude Code 可以呈现它们而不是将其打印为文本。当活跃的代码审查指令告诉它时，Claude 会调用它。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更高版本。{/* min-version: 2.1.199 */}从 v2.1.199 起，发现还可以携带可选的 `category` slug，例如 `correctness` 或 `test-coverage`，显示在呈现列表中的文件位置旁边 | 否 |

39| `ScheduleWakeup` | 重新安排 [self-paced `/loop`](/zh-CN/scheduled-tasks#let-claude-choose-the-interval) 的下一次迭代。Claude 在每次迭代结束时调用此工具以选择下一次运行的时间，范围在一分钟到一小时之间；您不需要直接调用它。待处理的唤醒显示在 [Stop hook input](/zh-CN/hooks#stop-input) 中的 `session_crons` 中。{/* plan-availability: feature=loop-dynamic providers=anthropic */}在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用，其中没有间隔的 `/loop` 提示按固定时间表运行 | 否 |39| `ScheduleWakeup` | 重新安排 [self-paced `/loop`](/zh-CN/scheduled-tasks#let-claude-choose-the-interval) 的下一次迭代。Claude 在每次迭代结束时调用此工具以选择下一次运行的时间，范围在一分钟到一小时之间；您不需要直接调用它。要结束循环，Claude 会调用它并设置 `stop: true`，这会取消待处理的唤醒。{/* min-version: 2.1.202 */}`stop` 字段需要 Claude Code v2.1.202 或更高版本。待处理的唤醒显示在 [Stop hook input](/zh-CN/hooks#stop-input) 中的 `session_crons` 中。{/* plan-availability: feature=loop-dynamic providers=anthropic */}在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用，其中没有间隔的 `/loop` 提示按固定时间表运行 | 否 |

40| `SendMessage` | 向 [agent team](/zh-CN/agent-teams) 队友发送消息，或按 agent ID 或名称[恢复 subagent](/zh-CN/sub-agents#resume-subagents)。已停止的 subagents 在后台自动恢复。结构化的团队协议消息需要 agent teams。接收者永远不会将来自另一个 agent 的消息视为您的同意或批准。{/* min-version: 2.1.198 */}从 v2.1.198 起，subagent 将来自启动它的 agent 的消息视为正常任务指示，而不是对等请求。{/* min-version: 2.1.199 */}从 v2.1.199 起，发送到现在解析为与对话早期不同的 agent 的名称会被拒绝而不是传递；请参阅[恢复 subagents](/zh-CN/sub-agents#resume-subagents) | 否 |40| `SendMessage` | 向 [agent team](/zh-CN/agent-teams) 队友发送消息，或按 agent ID 或名称[恢复 subagent](/zh-CN/sub-agents#resume-subagents)。已停止的 subagents 在后台自动恢复。结构化的团队协议消息需要 agent teams。接收者永远不会将来自另一个 agent 的消息视为您的同意或批准。{/* min-version: 2.1.198 */}从 v2.1.198 起，subagent 将来自启动它的 agent 的消息视为正常任务指示，而不是对等请求。{/* min-version: 2.1.199 */}从 v2.1.199 起，发送到现在解析为与对话早期不同的 agent 的名称会被拒绝而不是传递；请参阅[恢复 subagents](/zh-CN/sub-agents#resume-subagents) | 否 |

41| `SendUserFile` | 将会话中的文件发送给您，带有可选的标题，以便生成的报告、图表、屏幕截图或构建的工件到达您的设备，而不仅仅是在记录中提及。{/* min-version: 2.1.196 */}从 v2.1.196 起，可选的 `display` 输入控制呈现方式：`render` 在客户端中内联打开文件，`attach` 仅显示下载卡，未设置时客户端按文件类型决定。当连接了 [Remote Control](/zh-CN/remote-control) 客户端或会话在托管云环境（如 [Claude Code on the web](/zh-CN/claude-code-on-the-web)）中运行时可用。传递通过 Anthropic 托管的基础设施运行，因此该工具在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用 | 否 |41| `SendUserFile` | 将会话中的文件发送给您，带有可选的标题，以便生成的报告、图表、屏幕截图或构建的工件到达您的设备，而不仅仅是在记录中提及。{/* min-version: 2.1.196 */}从 v2.1.196 起，可选的 `display` 输入控制呈现方式：`render` 在客户端中内联打开文件，`attach` 仅显示下载卡，未设置时客户端按文件类型决定。当连接了 [Remote Control](/zh-CN/remote-control) 客户端或会话在托管云环境（如 [Claude Code on the web](/zh-CN/claude-code-on-the-web)）中运行时可用。传递通过 Anthropic 托管的基础设施运行，因此该工具在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用 | 否 |

42| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}上传 `ONBOARDING.md` 并返回队友可以在 Claude Code 中打开的共享链接。在编写指南后从 `/team-onboarding` 调用。适用于 Pro、Max、Team 和 Enterprise 计划上的 claude.ai 订阅者 | 是 |42| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}上传 `ONBOARDING.md` 并返回队友可以在 Claude Code 中打开的共享链接。在编写指南后从 `/team-onboarding` 调用。适用于 Pro、Max、Team 和 Enterprise 计划上的 claude.ai 订阅者 | 是 |

43| `Skill` | 在主对话中执行 [skill](/zh-CN/skills#control-who-invokes-a-skill) | 是 |43| `Skill` | 在主对话中执行 [skill](/zh-CN/skills#control-who-invokes-a-skill) | 是 |

44| `TaskCreate` | 在任务列表中创建新任务 | 否 |44| `TaskCreate` | 在任务列表中创建新任务 | 否 |

45| `TaskGet` | 检索特定任务的完整详细信息 | 否 |45| `TaskGet` | 检索特定任务的完整详细信息 | 否 |

46| `TaskList` | 列出所有任务及其当前状态 | 否 |46| `TaskList` | 列出所有任务及其当前状态 | 否 |

47| `TaskOutput` | （已弃用）检索后台任务的输出。优先使用 `Read` 读取任务的输出文件路径 | 否 |47| `TaskOutput` | 检索后台任务的输出。已弃用，改用 `Read` 读取任务的输出文件路径。{/* min-version: 2.1.203 */}当没有任务与 ID 匹配时，错误会按 ID 和描述列出运行中的后台 agents。在 v2.1.203 之前，错误仅命名缺失的 ID | 否 |

48| `TaskStop` | 按 ID 终止运行中的后台任务。{/* min-version: 2.1.198 */}从 v2.1.198 起，还接受 [agent-team 队友](/zh-CN/agent-teams)或按 agent ID 或名称的命名后台 agent | 否 |48| `TaskStop` | 按 ID 停止运行中的后台任务。{/* min-version: 2.1.198 */}它还接受 [agent-team 队友](/zh-CN/agent-teams)或按 agent ID 或名称的命名后台 agent。在 v2.1.198 之前，它仅接受后台任务 ID。{/* min-version: 2.1.203 */}当没有任务与 ID 匹配时，错误会按 ID 和描述列出运行中的后台 agents，包括另一个 agent 生成的 agents。在 v2.1.203 之前，错误列出了运行中的队友和命名 agents，但不包括另一个 agent 生成的后台 agents，因此无法从主对话中识别或停止这些 agents | 否 |

49| `TaskUpdate` | 更新任务状态、依赖项、详细信息或删除任务 | 否 |49| `TaskUpdate` | 更新任务状态、依赖项、详细信息或删除任务 | 否 |

50| `TodoWrite` | {/* min-version: 2.1.142 */}管理会话任务清单。在 v2.1.142 起默认禁用，改用 `TaskCreate`、`TaskGet`、`TaskList` 和 `TaskUpdate`。设置 `CLAUDE_CODE_ENABLE_TASKS=0` 以重新启用 | 否 |50| `TodoWrite` | {/* min-version: 2.1.142 */}管理会话任务清单。在 v2.1.142 起默认禁用，改用 `TaskCreate`、`TaskGet`、`TaskList` 和 `TaskUpdate`。设置 `CLAUDE_CODE_ENABLE_TASKS=0` 以重新启用 | 否 |

51| `ToolSearch` | 当启用 [tool search](/zh-CN/mcp#scale-with-mcp-tool-search) 时搜索并加载延迟工具 | 否 |51| `ToolSearch` | 当启用 [tool search](/zh-CN/mcp#scale-with-mcp-tool-search) 时搜索并加载延迟工具 | 否 |

220 220

221当 Monitor 运行命令时，它使用与 [Bash 相同的权限规则](/zh-CN/permissions#tool-specific-permission-rules)，因此您为 Bash 设置的 `allow` 和 `deny` 模式也适用于此处。[WebSocket 源](#websocket-source)有其自己的批准提示。221当 Monitor 运行命令时，它使用与 [Bash 相同的权限规则](/zh-CN/permissions#tool-specific-permission-rules)，因此您为 Bash 设置的 `allow` 和 `deny` 模式也适用于此处。[WebSocket 源](#websocket-source)有其自己的批准提示。

222 222

223该工具在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用。当设置了 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时，它也不可用。223该工具在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。当设置了 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时，它也不可用。

224 224

225插件可以声明在插件处于活动状态时自动启动的监视，而不是要求 Claude 启动它们。请参阅 [plugin monitors](/zh-CN/plugins-reference#monitors)。225插件可以声明在插件处于活动状态时自动启动的监视，而不是要求 Claude 启动它们。请参阅 [plugin monitors](/zh-CN/plugins-reference#monitors)。

226 226

369WebSearch 权限规则不接受 specifier。`allow` 或 `deny` 中的裸 `WebSearch` 条目是唯一的形式。369WebSearch 权限规则不接受 specifier。`allow` 或 `deny` 中的裸 `WebSearch` 条目是唯一的形式。

370 370

371<Note>371<Note>

372 WebSearch 在 Claude API、[Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 和 Microsoft Foundry 上可用。在 Google Cloud Vertex AI 上，它适用于 Claude 4 及更高版本的模型，包括 Opus、Sonnet 和 Haiku。Amazon Bedrock 不公开服务器端网络搜索工具。372 WebSearch 在 Claude API、[Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 和 Microsoft Foundry 上可用。在 Google Cloud 的 Agent Platform 上，它适用于 Claude 4 及更高版本的模型，包括 Opus、Sonnet 和 Haiku。Amazon Bedrock 不公开服务器端网络搜索工具。

373</Note>373</Note>

374 374

375<h2 id="write-tool-behavior">375<h2 id="write-tool-behavior">

troubleshoot-install.md +17 −14

Details

15将您看到的错误消息或症状与解决方案相匹配：15将您看到的错误消息或症状与解决方案相匹配：

16 16

17| 您看到的内容 | 解决方案 |17| 您看到的内容 | 解决方案 |

~~18| :----------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- |~~18| :----------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |

22| `curl: (23)` 或 `curl: (56) Failure writing output to destination` | [检查连接或使用替代安装程序](#curl-56-failure-writing-output-to-destination) |22| `curl: (23)` 或 `curl: (56) Failure writing output to destination` | [检查连接或使用替代安装程序](#curl-56-failure-writing-output-to-destination) |

~~42| `Could not load the default credentials` 或 `Could not load credentials from any providers` | [Bedrock、Vertex 或 Foundry 凭证](#bedrock-vertex-or-foundry-credentials-not-loading) |~~42| `Could not load the default credentials` 或 `Could not load credentials from any providers` | [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 凭证](#bedrock-agent-platform-or-foundry-credentials-not-loading) |

~~43| `ChainedTokenCredential authentication failed` 或 `CredentialUnavailableError` | [Bedrock、Vertex 或 Foundry 凭证](#bedrock-vertex-or-foundry-credentials-not-loading) |~~43| `ChainedTokenCredential authentication failed` 或 `CredentialUnavailableError` | [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 凭证](#bedrock-agent-platform-or-foundry-credentials-not-loading) |

45 45

46如果您的问题未列出，请按照下面的诊断检查来缩小原因范围。46如果您的问题未列出，请按照下面的诊断检查来缩小原因范围。

538 低内存 Linux 服务器上安装被杀死538 低内存 Linux 服务器上安装被杀死

539</h3>539</h3>

540 540

541如果在 VPS 或云实例上安装期间看到 `Killed`：541在安装期间看到 `Killed` 消息通常意味着 Linux 内存不足 (OOM) 杀手终止了 `claude install` 步骤，因为系统内存不足。这在小型 VPS 和云实例上很常见。安装脚本报告原因并以代码 137 退出：

542 542

543```text theme={null}543```text theme={null}

544Setting up Claude Code...544Setting up Claude Code...

545Installing Claude Code native build latest...

546bash: line 142: 34803 Killed "$binary_path" install ${TARGET:+"$TARGET"}545bash: line 142: 34803 Killed "$binary_path" install ${TARGET:+"$TARGET"}

546Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.

547Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

547```548```

548 549

549Linux OOM 杀手终止了该进程，因为系统内存不足。Claude Code 需要至少 4 GB 的可用 RAM。550在 v2.1.200 之前，脚本仅以 shell 的裸 `Killed` 行退出，没有解释。

551

552安装需要大约 512 MB 的可用内存，运行 Claude Code 需要更多。请参阅 [system requirements](/zh-CN/setup#system-requirements)。

550 553

551**解决方案：**554**解决方案：**

552 555

781`@anthropic-ai/claude-code` npm 包通过每个平台的可选依赖项（如 `@anthropic-ai/claude-code-darwin-arm64`）拉入本机二进制文件。如果在安装后运行 `claude` 打印 `Could not find native binary package "@anthropic-ai/claude-code-<platform>"`，请检查以下原因：784`@anthropic-ai/claude-code` npm 包通过每个平台的可选依赖项（如 `@anthropic-ai/claude-code-darwin-arm64`）拉入本机二进制文件。如果在安装后运行 `claude` 打印 `Could not find native binary package "@anthropic-ai/claude-code-<platform>"`，请检查以下原因：

782 785

783* **可选依赖项被禁用。** 从您的 npm 安装命令中删除 `--omit=optional`，从 pnpm 中删除 `--no-optional`，或从 yarn 中删除 `--ignore-optional`，并检查 `.npmrc` 是否未设置 `optional=false`。然后重新安装。本机二进制文件仅作为可选依赖项提供，因此如果跳过它，就没有 JavaScript 回退。786* **可选依赖项被禁用。** 从您的 npm 安装命令中删除 `--omit=optional`，从 pnpm 中删除 `--no-optional`，或从 yarn 中删除 `--ignore-optional`，并检查 `.npmrc` 是否未设置 `optional=false`。然后重新安装。本机二进制文件仅作为可选依赖项提供，因此如果跳过它，就没有 JavaScript 回退。

784* **不支持的平台。** 预构建的二进制文件为 `darwin-arm64`、`darwin-x64`、`linux-x64`、`linux-arm64`、`linux-x64-musl`、`linux-arm64-musl`、`win32-x64` 和 `win32-arm64` 发布。Claude Code 不为其他平台提供二进制文件；请参阅 [system requirements](/zh-CN/setup#system-requirements)。787* **不支持的平台。** 预构建的二进制文件为 `darwin-arm64`、`darwin-x64`、`linux-x64`、`linux-arm64`、`linux-x64-musl`、`linux-arm64-musl`、`win32-x64` 和 `win32-arm64` 发布。Claude Code 不为其他平台提供二进制文件；请参阅 [system requirements](/zh-CN/setup#system-requirements)。{/* min-version: 2.1.205 */}在 FreeBSD 上，安装程序报告平台不受支持。在 v2.1.205 之前，它将 FreeBSD 视为 Linux 并下载了无法运行的二进制文件。

785* **企业 npm 镜像缺少平台包。** 确保您的注册表除了元包外还镜像所有八个 `@anthropic-ai/claude-code-*` 平台包。788* **企业 npm 镜像缺少平台包。** 确保您的注册表除了元包外还镜像所有八个 `@anthropic-ai/claude-code-*` 平台包。

786 789

787使用 `--ignore-scripts` 安装不会触发此错误。跳过链接二进制文件到位的 postinstall 步骤，因此 Claude Code 回退到在每次启动时定位和生成平台二进制文件的包装器。这有效但启动速度较慢；使用启用的脚本重新安装以进行直接执行。790使用 `--ignore-scripts` 安装不会触发此错误。跳过链接二进制文件到位的 postinstall 步骤，因此 Claude Code 回退到在每次启动时定位和生成平台二进制文件的包装器。这有效但启动速度较慢；使用启用的脚本重新安装以进行直接执行。

876 879

877在 macOS 上，当 Keychain 被锁定或其密码与您的账户密码不同步时，登录也可能失败，这会阻止 Claude Code 保存凭证。运行 `claude doctor` 检查 Keychain 访问。要手动解锁 Keychain，请运行 `security unlock-keychain ~/Library/Keychains/login.keychain-db`。如果解锁无法帮助，打开 Keychain Access，选择 `login` keychain，并选择"Edit > Change Password for Keychain "login""以将其与您的账户密码重新同步。880在 macOS 上，当 Keychain 被锁定或其密码与您的账户密码不同步时，登录也可能失败，这会阻止 Claude Code 保存凭证。运行 `claude doctor` 检查 Keychain 访问。要手动解锁 Keychain，请运行 `security unlock-keychain ~/Library/Keychains/login.keychain-db`。如果解锁无法帮助，打开 Keychain Access，选择 `login` keychain，并选择"Edit > Change Password for Keychain "login""以将其与您的账户密码重新同步。

878 881

879<h3 id="bedrock-vertex-or-foundry-credentials-not-loading">882<h3 id="bedrock-agent-platform-or-foundry-credentials-not-loading">

880 Bedrock、Vertex 或 Foundry 凭证未加载883 Bedrock、Agent Platform 或 Foundry 凭证未加载

881</h3>884</h3>

882 885

883如果您配置了 Claude Code 以使用云提供商，并在 Bedrock 上看到 `Could not load credentials from any providers`、在 Vertex 上看到 `Could not load the default credentials` 或在 Foundry 上看到 `ChainedTokenCredential authentication failed`，您的云提供商 CLI 可能在当前 shell 中未进行身份验证。886如果您配置了 Claude Code 以使用云提供商，并在 Amazon Bedrock 上看到 `Could not load credentials from any providers`、在 Google Cloud 的 Agent Platform 上看到 `Could not load the default credentials` 或在 Microsoft Foundry 上看到 `ChainedTokenCredential authentication failed`，您的云提供商 CLI 可能在当前 shell 中未进行身份验证。

884 887

885对于 Bedrock，确认您的 AWS 凭证有效：888对于 Amazon Bedrock，确认您的 AWS 凭证有效：

886 889

887```bash theme={null}890```bash theme={null}

888aws sts get-caller-identity891aws sts get-caller-identity

889```892```

890 893

891对于 Vertex AI，确认 `ANTHROPIC_VERTEX_PROJECT_ID` 和 `CLOUD_ML_REGION` 在您的 shell 中设置，然后设置应用默认凭证：894对于 Google Cloud 的 Agent Platform，确认 `ANTHROPIC_VERTEX_PROJECT_ID` 和 `CLOUD_ML_REGION` 在您的 shell 中设置，然后设置应用默认凭证：

892 895

893```bash theme={null}896```bash theme={null}

894gcloud auth application-default login897gcloud auth application-default login

902 905

903如果凭证在您的终端中有效但在 VS Code 或 JetBrains 扩展中无效，IDE 进程可能未继承您的 shell 环境。在 IDE 自己的设置中设置提供商环境变量，或从已导出它们的终端启动 IDE。906如果凭证在您的终端中有效但在 VS Code 或 JetBrains 扩展中无效，IDE 进程可能未继承您的 shell 环境。在 IDE 自己的设置中设置提供商环境变量，或从已导出它们的终端启动 IDE。

904 907

905有关完整的提供商设置，请参阅 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Vertex AI](/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/zh-CN/microsoft-foundry)。908有关完整的提供商设置，请参阅 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/zh-CN/microsoft-foundry)。

906 909

907<h2 id="still-stuck">910<h2 id="still-stuck">

908 仍然卡住911 仍然卡住

troubleshooting.md +6 −5

Details

9本页涵盖 Claude Code 运行后的性能、稳定性和搜索问题。对于其他问题，请从与您遇到的问题相匹配的页面开始：9本页涵盖 Claude Code 运行后的性能、稳定性和搜索问题。对于其他问题，请从与您遇到的问题相匹配的页面开始：

10 10

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

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

~~14| 登录循环、OAuth 错误、`403 Forbidden`、"organization disabled"、Bedrock/Vertex/Foundry 凭据 | [故障排除安装和登录](/zh-CN/troubleshoot-install#login-and-authentication) |~~14| 更新或安装下载失败，显示 `The connection dropped while downloading the update` 或 `aborted` | [错误参考](/zh-CN/errors#the-connection-dropped-while-downloading-the-update) |

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

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

17| `model not found` 或 `you may not have access to it` | [错误参考](/zh-CN/errors#there%E2%80%99s-an-issue-with-the-selected-model) |18| `model not found` 或 `you may not have access to it` | [错误参考](/zh-CN/errors#there%E2%80%99s-an-issue-with-the-selected-model) |

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

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

21 22

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

23 24

24<h2 id="performance-and-stability">25<h2 id="performance-and-stability">

25 性能和稳定性26 性能和稳定性

119在 WSL 上[跨文件系统工作](https://learn.microsoft.com/en-us/windows/wsl/filesystems)时的磁盘读取性能损失可能导致使用 Claude Code 在 WSL 上时搜索匹配数少于预期。搜索仍然有效，但返回的结果少于本机文件系统。120在 WSL 上[跨文件系统工作](https://learn.microsoft.com/en-us/windows/wsl/filesystems)时的磁盘读取性能损失可能导致使用 Claude Code 在 WSL 上时搜索匹配数少于预期。搜索仍然有效，但返回的结果少于本机文件系统。

120 121

121<Note>122<Note>

122 在这种情况下，`/doctor` 将显示搜索为正常。123 `claude doctor` 在这种情况下将搜索显示为正常。

123</Note>124</Note>

124 125

125**解决方案：**126**解决方案：**

136 137

137如果您遇到此处未涵盖的问题：138如果您遇到此处未涵盖的问题：

138 139

1391. 运行 `/doctor` 以检查安装健康状况、设置有效性、MCP 配置和上下文使用情况1401. 运行 `/doctor` 进行设置检查，运行 `/mcp` 检查 MCP 服务器状态

1402. 在 Claude Code 中使用 `/feedback` 命令直接向 Anthropic 报告问题1412. 在 Claude Code 中使用 `/feedback` 命令直接向 Anthropic 报告问题

1413. 检查 [GitHub 存储库](https://github.com/anthropics/claude-code) 以了解已知问题1423. 检查 [GitHub 存储库](https://github.com/anthropics/claude-code) 以了解已知问题

1424. 直接向 Claude 询问其功能和特性。Claude 可以内置访问其文档。1434. 直接向 Claude 询问其功能和特性。Claude 可以内置访问其文档。

ultraplan.md +1 −1

Details

18* **无需干预的草拟**：计划在远程生成，所以你的终端可以自由用于其他工作18* **无需干预的草拟**：计划在远程生成，所以你的终端可以自由用于其他工作

19* **灵活的执行**：批准计划在网络上运行并打开拉取请求，或将其发送回终端19* **灵活的执行**：批准计划在网络上运行并打开拉取请求，或将其发送回终端

20 20

21Ultraplan 需要 [网络上的 Claude Code](/zh-CN/claude-code-on-the-web) 账户和 GitHub 仓库。由于它在 Anthropic 的云基础设施上运行，当使用 Amazon Bedrock、Google Cloud Vertex AI 或 Microsoft Foundry 时不可用。云会话在你账户的默认 [云环境](/zh-CN/claude-code-on-the-web#the-cloud-environment) 中运行。如果你还没有云环境，ultraplan 在首次启动时会自动创建一个。21Ultraplan 需要 [网络上的 Claude Code](/zh-CN/claude-code-on-the-web) 账户和 GitHub 仓库。由于它在 Anthropic 的云基础设施上运行，当使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 时不可用。云会话在你账户的默认 [云环境](/zh-CN/claude-code-on-the-web#the-cloud-environment) 中运行。如果你还没有云环境，ultraplan 在首次启动时会自动创建一个。

22 22

23<h2 id="launch-ultraplan-from-the-cli">23<h2 id="launch-ultraplan-from-the-cli">

24 从 CLI 启动 ultraplan24 从 CLI 启动 ultraplan

ultrareview.md +5 −5

Details

15与本地 `/code-review` 或 `/review` 相比，ultrareview 提供：15与本地 `/code-review` 或 `/review` 相比，ultrareview 提供：

16 16

17* **更高的信号质量**：每个报告的发现都经过独立复现和验证，因此结果专注于真实的错误而不是风格建议17* **更高的信号质量**：每个报告的发现都经过独立复现和验证，因此结果专注于真实的错误而不是风格建议

~~18* **更广泛的覆盖范围**：许多审查代理并行探索更改，这会发现中等工作量的本地审查可能遗漏的问题~~18* **更广泛的覆盖范围**：许多审查代理并行探索更改，这会发现本地审查可能遗漏的问题

19* **无本地资源使用**：审查完全在远程沙箱中运行，因此您的终端在运行时保持空闲，可用于其他工作19* **无本地资源使用**：审查完全在远程沙箱中运行，因此您的终端在运行时保持空闲，可用于其他工作

20 20

21Ultrareview 需要使用 Claude.ai 账户进行身份验证，因为它在 Claude Code 网络基础设施上运行。如果您仅使用 API 密钥登录，请先运行 `/login` 并使用 Claude.ai 进行身份验证。当使用 Claude Code 与 Amazon Bedrock、Google Cloud Vertex AI 或 Microsoft Foundry 时，Ultrareview 不可用，对于已启用零数据保留的组织也不可用。21Ultrareview 需要使用 Claude.ai 账户进行身份验证，因为它在 Claude Code 网络基础设施上运行。如果您仅使用 API 密钥登录，请先运行 `/login` 并使用 Claude.ai 进行身份验证。当使用 Claude Code 与 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 时，Ultrareview 不可用，对于已启用零数据保留的组织也不可用。

22 22

23<h2 id="run-ultrareview-from-the-cli">23<h2 id="run-ultrareview-from-the-cli">

24 从 CLI 运行 ultrareview24 从 CLI 运行 ultrareview

104所有三个命令都审查代码，但它们针对工作流的不同阶段。104所有三个命令都审查代码，但它们针对工作流的不同阶段。

105 105

107| ---- | -------------- | -------------------- | ------------------------------- |107| ---- | -------------- | ------------------- | ------------------------------- |

108| 目标 | 您的工作差异 | GitHub pull request | 您的工作差异或 pull request |108| 目标 | 您的工作差异 | GitHub pull request | 您的工作差异或 pull request |

110| 深度 | 随着 effort 参数扩展 | 中等 `/code-review` 引擎 | 具有独立验证的多代理队列 |110| 深度 | 随着 effort 参数扩展 | 会话的 effort 级别的单次审查 | 具有独立验证的多代理队列 |

112| 成本 | 计入正常使用量 | 计入正常使用量 | 免费运行，然后大约 \$5 到 \$20 每次审查作为使用额度 |112| 成本 | 计入正常使用量 | 计入正常使用量 | 免费运行，然后大约 \$5 到 \$20 每次审查作为使用额度 |

113| 最适合 | 迭代时的快速反馈 | 在批准前审查团队成员的 PR | 合并前对重大更改的信心 |113| 最适合 | 迭代时的快速反馈 | 在批准前审查团队成员的 PR | 合并前对重大更改的信心 |

114 114

voice-dictation.md +3 −2

Details

20 20

21语音听写将你录制的音频流传输到 Anthropic 的服务器进行转录。音频不在本地处理。它需要以下所有条件：21语音听写将你录制的音频流传输到 Anthropic 的服务器进行转录。音频不在本地处理。它需要以下所有条件：

22 22

23* **一个 Claude.ai 账户**：语音转文本服务仅在你使用 Claude.ai 账户进行身份验证时可用，当 Claude Code 配置为直接使用 Anthropic API 密钥、Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 时不可用。23* **一个 Claude.ai 账户**：语音转文本服务仅在你使用 Claude.ai 账户进行身份验证时可用，当 Claude Code 配置为直接使用 Anthropic API 密钥、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 时不可用。

24* **一个未启用 HIPAA 合规性的组织**：当此限制适用时，`/voice` 显示 `Voice mode is disabled by your organization's policy`。24* **一个未启用 HIPAA 合规性的组织**：当此限制适用时，`/voice` 显示 `Voice mode is disabled by your organization's policy`。

25* **一个本地麦克风**：语音听写在远程环境中不起作用，例如[网络上的 Claude Code](/zh-CN/claude-code-on-the-web)或 SSH 会话。25* **一个本地麦克风**：语音听写在远程环境中不起作用，例如[网络上的 Claude Code](/zh-CN/claude-code-on-the-web)或 SSH 会话。

26* **如果你在 WSL 中运行 Claude Code，则需要 WSLg**：WSLg 包含在 Windows 10 或 11 上从 Microsoft Store 安装的 WSL2 中。如果 WSLg 不可用，例如在 WSL1 上，改为在本机 Windows 中运行 Claude Code。26* **如果你在 WSL 中运行 Claude Code，则需要 WSLg**：WSLg 包含在 Windows 10 或 11 上从 Microsoft Store 安装的 WSL2 中。如果 WSLg 不可用，例如在 WSL1 上，改为在本机 Windows 中运行 Claude Code。

183* **Linux 上的 `No audio recording tool found`**：本机音频模块无法加载，没有安装回退。使用错误消息中显示的命令安装 SoX，例如 `sudo apt-get install sox`。183* **Linux 上的 `No audio recording tool found`**：本机音频模块无法加载，没有安装回退。使用错误消息中显示的命令安装 SoX，例如 `sudo apt-get install sox`。

184* **`Voice mode requires a microphone, but SoX could not open an audio capture device`**：SoX 已安装，但主机没有音频捕获设备，例如无头服务器或容器。在有麦克风的机器上运行 Claude Code。{/* min-version: 2.1.195 */}从 v2.1.195 开始，Linux 上的 Claude Code 在这种情况下报告此消息；早期版本即使已安装 SoX 也会要求你安装 SoX。184* **`Voice mode requires a microphone, but SoX could not open an audio capture device`**：SoX 已安装，但主机没有音频捕获设备，例如无头服务器或容器。在有麦克风的机器上运行 Claude Code。{/* min-version: 2.1.195 */}从 v2.1.195 开始，Linux 上的 Claude Code 在这种情况下报告此消息；早期版本即使已安装 SoX 也会要求你安装 SoX。

185* **`Voice mode could not find a working audio recorder in WSL`**：WSLg 通过 PulseAudio 而不是 ALSA 设备路由音频，因此 SoX 需要显式安装其 PulseAudio 后端。运行 `sudo apt install sox libsox-fmt-pulse`。单独安装 `sox` 会拉入 ALSA 后端，它无法在 WSL 上录制，因为没有 `/dev/snd` 设备。185* **`Voice mode could not find a working audio recorder in WSL`**：WSLg 通过 PulseAudio 而不是 ALSA 设备路由音频，因此 SoX 需要显式安装其 PulseAudio 后端。运行 `sudo apt install sox libsox-fmt-pulse`。单独安装 `sox` 会拉入 ALSA 后端，它无法在 WSL 上录制，因为没有 `/dev/snd` 设备。

186* **`Voice input is failing repeatedly and has been paused`**：语音听写连续遇到多个启动失败，并停止尝试新会话，直到一个成功。这通常意味着此主机上的麦克风或音频堆栈无法捕获音频，例如无头服务器、没有音频直通的远程 shell 或被拒绝的麦克风权限。确认工作输入设备，从上面的条目中修复根本原因，然后再次触发语音。186* **`Voice input is failing repeatedly and has been paused`**：语音听写连续遇到多个启动失败，并停止尝试新会话，直到一个成功。失败计数无论麦克风无法启动还是录音机启动然后停止而不产生任何音频。这通常意味着此主机上的麦克风或音频堆栈无法捕获音频，例如无头服务器、没有音频直通的远程 shell 或被拒绝的麦克风权限。确认工作输入设备，从上面的条目中修复根本原因，然后再次触发语音。{/* min-version: 2.1.202 */}在 v2.1.202 之前，只有启动失败计入暂停。

187* **在按住模式中按住 `Space` 时没有任何反应**：在按住时观察提示词输入。如果空格不断累积，语音听写可能已关闭；运行 `/voice hold` 启用它。如果只出现一两个空格然后没有任何反应，语音听写已打开但按住检测未触发。按住检测需要你的终端发送按键重复事件，所以如果在操作系统级别禁用了按键重复，它无法检测按住的键。使用 `/voice tap` 切换到点击模式以避免按键重复要求。187* **在按住模式中按住 `Space` 时没有任何反应**：在按住时观察提示词输入。如果空格不断累积，语音听写可能已关闭；运行 `/voice hold` 启用它。如果只出现一两个空格然后没有任何反应，语音听写已打开但按住检测未触发。按住检测需要你的终端发送按键重复事件，所以如果在操作系统级别禁用了按键重复，它无法检测按住的键。使用 `/voice tap` 切换到点击模式以避免按键重复要求。

188* **在点击模式中点击 `Space` 输入空格而不是录制**：第一次点击仅在提示词输入为空时开始录制。先清除输入，或通过运行 `/voice tap` 检查你是否处于点击模式。188* **在点击模式中点击 `Space` 输入空格而不是录制**：第一次点击仅在提示词输入为空时开始录制。先清除输入，或通过运行 `/voice tap` 检查你是否处于点击模式。

189* **`No audio detected from microphone`**：录制开始但捕获了静音。确认正确的输入设备设置为系统默认值，其输入级别未静音或接近零。在 Windows 上，打开设置 → 系统 → 声音 → 输入并选择你的麦克风。在 macOS 上，打开系统设置 → 声音 → 输入。189* **`No audio detected from microphone`**：录制开始但捕获了静音。确认正确的输入设备设置为系统默认值，其输入级别未静音或接近零。在 Windows 上，打开设置 → 系统 → 声音 → 输入并选择你的麦克风。在 macOS 上，打开系统设置 → 声音 → 输入。

190* **`Voice connection failed`**：你的录制从未到达转录服务，因为连接失败。检查你的网络并重试。{/* min-version: 2.1.200 */}捕获无音频的录制报告 `No audio detected from microphone` 而不是此消息。在 v2.1.200 之前，静音麦克风可能报告连接失败，这表示网络问题，而实际问题是输入设备。

190* **`No speech detected`**：音频到达转录服务但未识别任何单词。靠近麦克风说话，减少背景噪音，并确认你的[听写语言](#change-the-dictation-language)与你说话的语言匹配。191* **`No speech detected`**：音频到达转录服务但未识别任何单词。靠近麦克风说话，减少背景噪音，并确认你的[听写语言](#change-the-dictation-language)与你说话的语言匹配。

191* **转录是乱码或使用了错误的语言**：听写默认为英语。如果你用另一种语言听写，请先在 `/config` 中设置它。请参阅[更改听写语言](#change-the-dictation-language)。192* **转录是乱码或使用了错误的语言**：听写默认为英语。如果你用另一种语言听写，请先在 `/config` 中设置它。请参阅[更改听写语言](#change-the-dictation-language)。

192 193

vs-code.md +10 −6

Details

19安装前，请确保您拥有：19安装前，请确保您拥有：

20 20

21* VS Code 1.98.0 或更高版本21* VS Code 1.98.0 或更高版本

22* Anthropic 账户：任何付费 Claude 订阅（Pro、Max、Team 或 Enterprise）或 Claude Console 账户都可以使用，无需 API 密钥。首次打开扩展时，您将[使用此账户登录](/zh-CN/authentication#log-in-to-claude-code)。如果您通过第三方提供商（如 Amazon Bedrock 或 Google Vertex AI）访问 Claude，请参阅[使用第三方提供商](#use-third-party-providers)了解设置说明。22* Anthropic 账户：任何付费 Claude 订阅（Pro、Max、Team 或 Enterprise）或 Claude Console 账户都可以使用，无需 API 密钥。首次打开扩展时，您将[使用此账户登录](/zh-CN/authentication#log-in-to-claude-code)。如果您通过第三方提供商（如 Amazon Bedrock 或 Google Cloud 的 Agent Platform）访问 Claude，请参阅[使用第三方提供商](#use-third-party-providers)了解设置说明。

23 23

24<Tip>24<Tip>

25 该扩展包含其自己的 CLI（命令行界面）副本用于聊天面板。要在 VS Code 的集成终端中运行 `claude`，您还需要[独立 CLI 安装](/zh-CN/setup)。有关详细信息，请参阅 [VS Code 扩展与 Claude Code CLI](#vs-code-extension-vs-claude-code-cli)。25 该扩展包含其自己的 CLI（命令行界面）副本用于聊天面板。要在 VS Code 的集成终端中运行 `claude`，您还需要[独立 CLI 安装](/zh-CN/setup)。有关详细信息，请参阅 [VS Code 扩展与 Claude Code CLI](#vs-code-extension-vs-claude-code-cli)。

102 102

103提示框支持多个功能：103提示框支持多个功能：

104 104

105* **权限模式**：点击提示框底部的模式指示器以切换模式。在正常模式下，Claude 在每个操作前请求许可。在 Plan mode 中，Claude 描述它将做什么，并在进行更改前等待批准。VS Code 会自动将计划作为完整的 markdown 文档打开，您可以添加内联注释以在 Claude 开始前提供反馈。在自动接受模式下，Claude 进行编辑而不询问。在 VS Code 设置中的 `claudeCode.initialPermissionMode` 下设置默认值。105* **权限模式**：点击提示框底部的模式指示器以切换模式，或在 VS Code 设置中的 `claudeCode.initialPermissionMode` 下设置默认值。请参阅[权限模式](/zh-CN/permission-modes#switch-permission-modes)了解指示器提供的每种模式。

106 * **Manual**：Claude 在每个操作前请求许可。

107 * **Plan Mode**：Claude 描述它将做什么，并在进行更改前等待批准。VS Code 会自动将计划作为完整的 Markdown 文档打开，您可以添加内联注释以在 Claude 开始前提供反馈。

108 * **Edit automatically**：Claude 进行编辑而不询问。

106* **命令菜单**：点击 `/` 或输入 `/` 以打开命令菜单。选项包括附加文件、切换模型、切换扩展思考、查看计划使用情况（`/usage`）以及启动 [Remote Control](/zh-CN/remote-control) 会话（`/remote-control`）。自定义部分提供对 MCP servers、hooks、memory、permissions 和 plugins 的访问。带有终端图标的项目在集成终端中打开。109* **命令菜单**：点击 `/` 或输入 `/` 以打开命令菜单。选项包括附加文件、切换模型、切换扩展思考、查看计划使用情况（`/usage`）以及启动 [Remote Control](/zh-CN/remote-control) 会话（`/remote-control`）。自定义部分提供对 MCP servers、hooks、memory、permissions 和 plugins 的访问。带有终端图标的项目在集成终端中打开。

110 * {/* min-version: 2.1.203 */}设置部分包括**为所有会话启用 Remote Control**，它设置 [`remoteControlAtStartup`](/zh-CN/settings#available-settings) 以便[每个新的交互式会话都自动连接到 Remote Control](/zh-CN/remote-control#enable-remote-control-for-all-sessions)。需要 Claude Code v2.1.203 或更高版本。

107* **上下文指示器**：提示框显示您使用了多少 Claude 的 context window。Claude 在需要时自动压缩，或者您可以手动运行 `/compact`。111* **上下文指示器**：提示框显示您使用了多少 Claude 的 context window。Claude 在需要时自动压缩，或者您可以手动运行 `/compact`。

108* **扩展思考**：让 Claude 花更多时间推理复杂问题。通过命令菜单（`/`）切换它。Claude 的推理在对话中显示为折叠块：点击一个块来阅读它，或按 `Ctrl+O` 以展开或折叠会话中的每个思考块。有关详细信息，请参阅[扩展思考](/zh-CN/model-config#extended-thinking)。112* **扩展思考**：让 Claude 花更多时间推理复杂问题。通过命令菜单（`/`）切换它。Claude 的推理在对话中显示为折叠块：点击一个块来阅读它，或按 `Ctrl+O` 以展开或折叠会话中的每个思考块。有关详细信息，请参阅[扩展思考](/zh-CN/model-config#extended-thinking)。

109* **多行输入**：按 `Shift+Enter` 添加新行而不发送。这也适用于问题对话框的"其他"自由文本输入。113* **多行输入**：按 `Shift+Enter` 添加新行而不发送。这也适用于问题对话框的"其他"自由文本输入。

356</h3>360</h3>

357 361

358| 设置 | 默认值 | 描述 |362| 设置 | 默认值 | 描述 |

359| ----------------------------------- | --------- | --------------------------------------------------------------------------------------------------- |363| ----------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

361| `initialPermissionMode` | `default` | 控制新对话的批准提示：`default`、`plan`、`acceptEdits` 或 `bypassPermissions`。请参阅[权限模式](/zh-CN/permission-modes)。 |365| `initialPermissionMode` | `default` | 控制新对话的批准提示：`default`、`plan`、`acceptEdits` 或 `bypassPermissions`。{/* min-version: 2.1.200 */}`manual` 是 `default` 的别名，选择模式指示器中标记为**手动**的模式。需要 Claude Code v2.1.200 或更高版本。请参阅[权限模式](/zh-CN/permission-modes)。 |

479 使用第三方提供商483 使用第三方提供商

480</h2>484</h2>

481 485

482默认情况下，Claude Code 直接连接到 Anthropic 的 API。如果您的组织使用 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 来访问 Claude，请配置扩展以改用您的提供商：486默认情况下，Claude Code 直接连接到 Anthropic 的 API。如果您的组织使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 来访问 Claude，请配置扩展以改用您的提供商：

483 487

484<Steps>488<Steps>

485 <Step title="禁用登录提示">489 <Step title="禁用登录提示">

492 按照您的提供商的设置指南：496 按照您的提供商的设置指南：

493 497

494 * [Amazon Bedrock 上的 Claude Code](/zh-CN/amazon-bedrock)498 * [Amazon Bedrock 上的 Claude Code](/zh-CN/amazon-bedrock)

495 * [Google Vertex AI 上的 Claude Code](/zh-CN/google-vertex-ai)499 * [Google Cloud 的 Agent Platform 上的 Claude Code](/zh-CN/google-vertex-ai)

496 * [Microsoft Foundry 上的 Claude Code](/zh-CN/microsoft-foundry)500 * [Microsoft Foundry 上的 Claude Code](/zh-CN/microsoft-foundry)

497 501

498 这些指南涵盖在 `~/.claude/settings.json` 中配置您的提供商，这确保您的设置在 VS Code 扩展和 CLI 之间共享。502 这些指南涵盖在 `~/.claude/settings.json` 中配置您的提供商，这确保您的设置在 VS Code 扩展和 CLI 之间共享。

web-quickstart.md +7 −7

Details

43Claude Code 在任何地方的行为都相同。改变的是代码执行的位置以及您的本地配置是否可用。Desktop 应用提供本地和云会话，因此其下面的答案取决于您选择的是哪一个：43Claude Code 在任何地方的行为都相同。改变的是代码执行的位置以及您的本地配置是否可用。Desktop 应用提供本地和云会话，因此其下面的答案取决于您选择的是哪一个：

44 44

~~46| :---------------------------------- | :---------------------------------------------------------------------------------------------- | :-------------- | :----------- | :---------- |~~46| :---------------------------------- | :--------------------------------------------------------------------------------------------- | :-------------- | :----------- | :---------- |

49| **使用您的本地配置** | 否，仅限仓库 | 是 | 是 | 本地为是，云为否 |49| **使用您的本地配置** | 否，仅限仓库 | 是 | 是 | 本地为是，云为否 |

50| **需要 GitHub** | 是，或通过 `--remote` [捆绑本地仓库](/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) | 否 | 否 | 仅限云会话 |50| **需要 GitHub** | 是，或通过 `--cloud` [捆绑本地仓库](/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) | 否 | 否 | 仅限云会话 |

51| **断开连接时继续运行** | 是 | 当终端保持打开时 | 否 | 取决于会话类型 |51| **断开连接时继续运行** | 是 | 当终端保持打开时 | 否 | 取决于会话类型 |

54 54

55请参阅[终端快速入门](/zh-CN/quickstart)、[Desktop 应用](/zh-CN/desktop)或 [Remote Control](/zh-CN/remote-control) 文档来设置这些。55请参阅[终端快速入门](/zh-CN/quickstart)、[Desktop 应用](/zh-CN/desktop)或 [Remote Control](/zh-CN/remote-control) 文档来设置这些。

113 /web-setup113 /web-setup

114 ```114 ```

115 115

116 这会将您的 `gh` 令牌同步到您的 Claude 账户。如果您还没有云环境，`/web-setup` 会创建一个具有 Trusted 网络访问和无设置脚本的环境。您可以[稍后编辑环境或添加变量](/zh-CN/claude-code-on-the-web#configure-your-environment)。一旦 `/web-setup` 完成，您可以从您的终端使用 [`--remote`](/zh-CN/claude-code-on-the-web#from-terminal-to-web) 启动云会话，或使用 [`/schedule`](/zh-CN/routines) 设置定期任务。116 这会将您的 `gh` 令牌同步到您的 Claude 账户。如果您还没有云环境，`/web-setup` 会创建一个具有 Trusted 网络访问和无设置脚本的环境。您可以[稍后编辑环境或添加变量](/zh-CN/claude-code-on-the-web#configure-your-environment)。一旦 `/web-setup` 完成，您可以从您的终端使用 [`--cloud`](/zh-CN/claude-code-on-the-web#from-terminal-to-web) 启动云会话，或使用 [`/schedule`](/zh-CN/routines) 设置定期任务。

117 </Step>117 </Step>

118</Steps>118</Steps>

119 119

129 </Step>129 </Step>

130 130

131 <Step title="选择权限模式">131 <Step title="选择权限模式">

132 输入旁边的模式下拉菜单默认为**Accept edits**，其中 Claude 进行更改并推送分支而无需停止以获得批准。如果您希望 Claude 提出方法并在编辑文件前等待您的同意，请切换到**Plan Mode**。云会话不提供 Ask 权限或 Bypass 权限。请参阅[权限模式](/zh-CN/permission-modes)了解完整列表。132 输入旁边的模式下拉菜单默认为**Accept edits**，其中 Claude 进行更改并推送分支而无需停止以获得批准。如果您希望 Claude 提出方法并在编辑文件前等待您的同意，请切换到**Plan Mode**。云会话不提供 Manual 或 Bypass 权限。请参阅[权限模式的完整列表](/zh-CN/permission-modes#available-modes)了解每种权限允许的操作。

133 </Step>133 </Step>

134 134

135 <Step title="描述任务并提交">135 <Step title="描述任务并提交">

216 216

217如果您在 Claude Code 内输入它，命令菜单显示 `No commands match "/web-setup"`，或提交它返回 `Unknown command: /web-setup`，该命令被隐藏是因为未满足要求。原因通常是您的 CLI 版本早于 v2.1.80，或者您使用 API 密钥或第三方提供商而不是 claude.ai 订阅进行身份验证。运行 `claude update`，然后 `/login` 以使用您的 claude.ai 账户登录。217如果您在 Claude Code 内输入它，命令菜单显示 `No commands match "/web-setup"`，或提交它返回 `Unknown command: /web-setup`，该命令被隐藏是因为未满足要求。原因通常是您的 CLI 版本早于 v2.1.80，或者您使用 API 密钥或第三方提供商而不是 claude.ai 订阅进行身份验证。运行 `claude update`，然后 `/login` 以使用您的 claude.ai 账户登录。

218 218

219<h3 id="could-not-create-a-cloud-environment-or-no-cloud-environment-available-when-using-remote-or-ultraplan">219<h3 id="could-not-create-a-cloud-environment-or-no-cloud-environment-available-when-using-cloud-or-ultraplan">

220 使用 `--remote` 或 ultraplan 时出现 "Could not create a cloud environment" 或 "No cloud environment available"220 使用 `--cloud` 或 ultraplan 时出现 "Could not create a cloud environment" 或 "No cloud environment available"

221</h3>221</h3>

222 222

223远程会话功能如果您没有云环境，会自动创建一个默认的云环境。如果您看到 "Could not create a cloud environment"，自动创建失败。{/* max-version: 2.1.100 */}如果您看到 "No cloud environment available"，您的 CLI 早于自动创建。在任何一种情况下，在 Claude Code CLI 中运行 `/web-setup` 以手动创建一个，或访问 [claude.ai/code](https://claude.ai/code) 并按照上面的**Create your environment** 步骤。223远程会话功能如果您没有云环境，会自动创建一个默认的云环境。如果您看到 "Could not create a cloud environment"，自动创建失败。{/* max-version: 2.1.100 */}如果您看到 "No cloud environment available"，您的 CLI 早于自动创建。在任何一种情况下，在 Claude Code CLI 中运行 `/web-setup` 以手动创建一个，或访问 [claude.ai/code](https://claude.ai/code) 并按照上面的**Create your environment** 步骤。

whats-new.md +1 −1

Details

33</Update>33</Update>

34 34

35<Update label="Week 23" description="June 1–5, 2026" tags={["v2.1.158–v2.1.165"]}>35<Update label="Week 23" description="June 1–5, 2026" tags={["v2.1.158–v2.1.165"]}>

~~36 **Bedrock、Vertex 和 Foundry 上的 Auto mode**：auto mode 现在在第三方提供商上可用，支持 Opus 4.7 和 Opus 4.8，用后台安全检查替换权限提示。~~36 **Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的 Auto mode**：auto mode 现在在第三方提供商上可用，支持 Opus 4.7 和 Opus 4.8，用后台安全检查替换权限提示。

37 37

38 本周还有：**更安全的自动编辑**在 `acceptEdits` 模式下写入可以运行代码的文件前提示；**`/plugin list`** 内联打印您安装的插件；**版本要求**让托管部署要求批准的 Claude Code 版本范围。38 本周还有：**更安全的自动编辑**在 `acceptEdits` 模式下写入可以运行代码的文件前提示；**`/plugin list`** 内联打印您安装的插件；**版本要求**让托管部署要求批准的 Claude Code 版本范围。

39 39

whats-new/2026-w15.md +2 −2

Details

102 102

103 <div className="digest-wins-grid">103 <div className="digest-wins-grid">

104 <div>焦点视图：在无闪烁模式下按 <code>Ctrl+O</code> 将视图折叠到您的最后一个提示、单行工具摘要（带有 diffstats）和 Claude 的最终响应</div>104 <div>焦点视图：在无闪烁模式下按 <code>Ctrl+O</code> 将视图折叠到您的最后一个提示、单行工具摘要（带有 diffstats）和 Claude 的最终响应</div>

105 <div>登录屏幕上的引导式 <a href="/zh-CN/docs/amazon-bedrock">Bedrock</a> 和 <a href="/zh-CN/docs/google-vertex-ai">Vertex AI</a> 设置向导：选择"第三方平台"进行分步身份验证、区域、凭证检查和模型固定</div>105 <div>登录屏幕上的引导式 <a href="/zh-CN/docs/amazon-bedrock">Amazon Bedrock</a> 和 <a href="/zh-CN/docs/google-vertex-ai">Google Cloud 的 Agent Platform</a> 设置向导：选择"第三方平台"进行分步身份验证、区域、凭证检查和模型固定</div>

106 <div><code>/agents</code> 获得选项卡式布局：Running 选项卡显示带有 <code>● N running</code> 计数的实时子代理，以及库选项卡中的 Run agent 和 View running instance 操作</div>106 <div><code>/agents</code> 获得选项卡式布局：Running 选项卡显示带有 <code>● N running</code> 计数的实时子代理，以及库选项卡中的 Run agent 和 View running instance 操作</div>

107 <div>默认工作量级别现在对 API 密钥、Bedrock、Vertex、Foundry、Team 和 Enterprise 用户为 <code>high</code>（使用 <code>/effort</code> 控制）</div>107 <div>默认工作量级别现在对 API 密钥、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、Team 和 Enterprise 用户为 <code>high</code>（使用 <code>/effort</code> 控制）</div>

108 <div><code>/cost</code> 为订阅用户显示按模型和缓存命中的分解</div>108 <div><code>/cost</code> 为订阅用户显示按模型和缓存命中的分解</div>

109 <div><code>/release-notes</code> 现在是交互式版本选择器</div>109 <div><code>/release-notes</code> 现在是交互式版本选择器</div>

110 <div>状态行：新的 <code>refreshInterval</code> 设置每 N 秒重新运行命令，JSON 输入中的 <code>workspace.git\_worktree</code></div>110 <div>状态行：新的 <code>refreshInterval</code> 设置每 N 秒重新运行命令，JSON 输入中的 <code>workspace.git\_worktree</code></div>

whats-new/2026-w16.md +1 −1

Details

123 <div><code>/fewer-permission-prompts</code> 扫描您的记录以查找常见的只读 Bash 和 MCP 调用，并为 <code>.claude/settings.json</code> 提议一个允许列表</div>123 <div><code>/fewer-permission-prompts</code> 扫描您的记录以查找常见的只读 Bash 和 MCP 调用，并为 <code>.claude/settings.json</code> 提议一个允许列表</div>

124 <div>Claude 现在可以通过 Skill 工具发现并运行内置命令，如 <code>/init</code>、<code>/review</code> 和 <code>/security-review</code></div>124 <div>Claude 现在可以通过 Skill 工具发现并运行内置命令，如 <code>/init</code>、<code>/review</code> 和 <code>/security-review</code></div>

125 <div><code>PreCompact</code> hooks 可以通过以代码 2 退出或返回 <code>{"{"}"decision":"block"{"}"}</code> 来阻止压缩</div>125 <div><code>PreCompact</code> hooks 可以通过以代码 2 退出或返回 <code>{"{"}"decision":"block"{"}"}</code> 来阻止压缩</div>

126 <div><code>ENABLE\_PROMPT\_CACHING\_1H</code> 选择 API 密钥、Bedrock、Vertex 和 Foundry 用户进入 1 小时提示缓存 TTL</div>126 <div><code>ENABLE\_PROMPT\_CACHING\_1H</code> 选择 API 密钥、Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 用户进入 1 小时提示缓存 TTL</div>

127 <div><code>sandbox.network.deniedDomains</code> 设置从更广泛的 <code>allowedDomains</code> 通配符中分离特定域</div>127 <div><code>sandbox.network.deniedDomains</code> 设置从更广泛的 <code>allowedDomains</code> 通配符中分离特定域</div>

128 <div><code>/undo</code> 现在是 <code>/rewind</code> 的别名，<code>/proactive</code> 是 <code>/loop</code> 的别名</div>128 <div><code>/undo</code> 现在是 <code>/rewind</code> 的别名，<code>/proactive</code> 是 <code>/loop</code> 的别名</div>

129 <div>强化的 Bash 权限：拒绝规则现在通过 <code>env</code>/<code>sudo</code>/<code>watch</code> 包装器匹配，<code>Bash(find:\*)</code> 允许规则不再自动批准 <code>-exec</code> 或 <code>-delete</code></div>129 <div>强化的 Bash 权限：拒绝规则现在通过 <code>env</code>/<code>sudo</code>/<code>watch</code> 包装器匹配，<code>Bash(find:\*)</code> 允许规则不再自动批准 <code>-exec</code> 或 <code>-delete</code></div>

whats-new/2026-w18.md +2 −2

Details

103 <div><code>--dangerously-skip-permissions</code> 现在绕过对 <code>.claude/</code>、<code>.git/</code>、<code>.vscode/</code>、shell 配置文件和其他以前受保护的路径的写入提示，而灾难性删除命令仍然作为安全网提示</div>103 <div><code>--dangerously-skip-permissions</code> 现在绕过对 <code>.claude/</code>、<code>.git/</code>、<code>.vscode/</code>、shell 配置文件和其他以前受保护的路径的写入提示，而灾难性删除命令仍然作为安全网提示</div>

104 <div><code>/model</code> 选择器可以在 <code>ANTHROPIC\_BASE\_URL</code> 指向 Anthropic 兼容网关时列出来自网关的 <code>/v1/models</code> 端点的模型；自 v2.1.129 起使用 <code>CLAUDE\_CODE\_ENABLE\_GATEWAY\_MODEL\_DISCOVERY=1</code> 选择加入</div>104 <div><code>/model</code> 选择器可以在 <code>ANTHROPIC\_BASE\_URL</code> 指向 Anthropic 兼容网关时列出来自网关的 <code>/v1/models</code> 端点的模型；自 v2.1.129 起使用 <code>CLAUDE\_CODE\_ENABLE\_GATEWAY\_MODEL\_DISCOVERY=1</code> 选择加入</div>

105 <div>在启动期间遇到瞬时错误的 MCP 服务器现在自动重试最多 3 次，而不是保持断开连接</div>105 <div>在启动期间遇到瞬时错误的 MCP 服务器现在自动重试最多 3 次，而不是保持断开连接</div>

106 <div><code>ANTHROPIC\_BEDROCK\_SERVICE\_TIER</code> 选择 Bedrock 服务层：<code>default</code>、<code>flex</code> 或 <code>priority</code></div>106 <div><code>ANTHROPIC\_BEDROCK\_SERVICE\_TIER</code> 选择 Amazon Bedrock 服务层：<code>default</code>、<code>flex</code> 或 <code>priority</code></div>

107 <div><code>/terminal-setup</code> 启用 iTerm2 的剪贴板访问设置，以便 <code>/copy</code> 工作，包括来自 tmux</div>107 <div><code>/terminal-setup</code> 启用 iTerm2 的剪贴板访问设置，以便 <code>/copy</code> 工作，包括来自 tmux</div>

108 <div>Vertex AI 现在支持基于 X.509 证书的工作负载身份联合 (mTLS ADC)</div>108 <div>Google Cloud 的 Agent Platform 现在支持基于 X.509 证书的工作负载身份联合 (mTLS ADC)</div>

109 <div>重大内存泄漏修复：图像繁重的会话、大型记录历史上的 <code>/usage</code> 以及没有进度事件的长时间运行工具</div>109 <div>重大内存泄漏修复：图像繁重的会话、大型记录历史上的 <code>/usage</code> 以及没有进度事件的长时间运行工具</div>

110 </div>110 </div>

111</div>111</div>

whats-new/2026-w21.md +1 −1

Details

37 <div>新的 <a href="/zh-CN/code-review"><code>/code-review</code></a> 命令在选定的工作量级别（如 <code>/code-review high</code>）报告正确性错误，<code>--comment</code> 将发现作为内联 GitHub PR 注释发布。<code>/simplify</code> 保留为单独的仅清理审查。</div>37 <div>新的 <a href="/zh-CN/code-review"><code>/code-review</code></a> 命令在选定的工作量级别（如 <code>/code-review high</code>）报告正确性错误，<code>--comment</code> 将发现作为内联 GitHub PR 注释发布。<code>/simplify</code> 保留为单独的仅清理审查。</div>

38 <div>后台会话现在与交互式会话一起出现在 <code>/resume</code> 中，标记为 <code>bg</code>，在 <code>claude agents</code> 中使用 <code>Ctrl+T</code> 固定的会话在空闲时保持活跃</div>38 <div>后台会话现在与交互式会话一起出现在 <code>/resume</code> 中，标记为 <code>bg</code>，在 <code>claude agents</code> 中使用 <code>Ctrl+T</code> 固定的会话在空闲时保持活跃</div>

39 <div><code>claude agents --json</code> 将实时会话列为 JSON 以供脚本编写，例如状态栏和会话选择器</div>39 <div><code>claude agents --json</code> 将实时会话列为 JSON 以供脚本编写，例如状态栏和会话选择器</div>

~~40 <div>PowerShell 工具现在在 Windows 上默认为 Bedrock、Vertex 和 Foundry 用户启用；使用 <code>CLAUDE\_CODE\_USE\_POWERSHELL\_TOOL=0</code> 选择退出</div>~~40 <div>PowerShell 工具现在在 Windows 上默认为 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 用户启用；使用 <code>CLAUDE\_CODE\_USE\_POWERSHELL\_TOOL=0</code> 选择退出</div>

41 <div><code>claude plugin disable</code> 现在在另一个启用的插件依赖于目标时拒绝，<code>claude plugin enable</code> 强制启用传递依赖</div>41 <div><code>claude plugin disable</code> 现在在另一个启用的插件依赖于目标时拒绝，<code>claude plugin enable</code> 强制启用传递依赖</div>

42 <div><code>/plugin</code> marketplace 浏览窗格显示预计的上下文成本，Discover 和 Browse 屏幕在安装前列出插件的命令、agents、skills、hooks 和 MCP/LSP servers</div>42 <div><code>/plugin</code> marketplace 浏览窗格显示预计的上下文成本，Discover 和 Browse 屏幕在安装前列出插件的命令、agents、skills、hooks 和 MCP/LSP servers</div>

43 <div>新的 <code>worktree.bgIsolation: "none"</code> 设置允许后台会话直接编辑工作副本，无需 <code>EnterWorktree</code>，适用于 worktrees 不实用的存储库</div>43 <div>新的 <code>worktree.bgIsolation: "none"</code> 设置允许后台会话直接编辑工作副本，无需 <code>EnterWorktree</code>，适用于 worktrees 不实用的存储库</div>

whats-new/2026-w22.md +2 −2

Details

109 <div>Claude Code 现在在找不到主模型时切换到您配置的 <code>--fallback-model</code> 以继续会话的其余部分，而不是使每个请求都失败</div>109 <div>Claude Code 现在在找不到主模型时切换到您配置的 <code>--fallback-model</code> 以继续会话的其余部分，而不是使每个请求都失败</div>

110 <div>插件可以在 <code>plugin.json</code> 或市场条目中声明 <code>defaultEnabled: false</code>，以便它们安装时不会打开，直到您启用它们</div>110 <div>插件可以在 <code>plugin.json</code> 或市场条目中声明 <code>defaultEnabled: false</code>，以便它们安装时不会打开，直到您启用它们</div>

111 <div>Vim 模式：在 NORMAL 模式下按 <code>/</code> 打开反向历史搜索，与 Bash 和 Zsh vi-mode 匹配</div>111 <div>Vim 模式：在 NORMAL 模式下按 <code>/</code> 打开反向历史搜索，与 Bash 和 Zsh vi-mode 匹配</div>

112 <div>流式工具执行现在始终启用，包括在禁用遥测和在 Bedrock、Vertex 和 Foundry 上</div>112 <div>流式工具执行现在始终启用，包括在禁用遥测和在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上</div>

113 <div><code>←←</code> 打开代理视图现在在 Bedrock、Vertex、Foundry 和禁用遥测时有效</div>113 <div><code>←←</code> 打开代理视图现在在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和禁用遥测时有效</div>

114 <div>Chrome 中的 Claude：通过 <code>/chrome</code> → "选择浏览器…" 选择要使用的连接浏览器，或在浏览器操作运行时在聊天中选择（当有多个连接时）</div>114 <div>Chrome 中的 Claude：通过 <code>/chrome</code> → "选择浏览器…" 选择要使用的连接浏览器，或在浏览器操作运行时在聊天中选择（当有多个连接时）</div>

115 <div><code>claude mcp list</code> 和 <code>claude mcp get</code> 现在将未批准的 <code>.mcp.json</code> 服务器显示为待批准，而不是在输出被管道传输时自动批准和连接</div>115 <div><code>claude mcp list</code> 和 <code>claude mcp get</code> 现在将未批准的 <code>.mcp.json</code> 服务器显示为待批准，而不是在输出被管道传输时自动批准和连接</div>

116 </div>116 </div>

whats-new/2026-w23.md +4 −4

Details

4 4

5# 第 23 周 · 2026 年 6 月 1–5 日5# 第 23 周 · 2026 年 6 月 1–5 日

6 6

7> 在 Bedrock、Vertex 和 Foundry 上运行自动模式，在 acceptEdits 模式下提示写入可运行代码的文件，使用 /plugin list 列出已安装的插件，以及为托管部署要求批准的版本范围。7> 在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上运行自动模式，在 acceptEdits 模式下提示写入可运行代码的文件，使用 /plugin list 列出已安装的插件，以及为托管部署要求批准的版本范围。

8 8

9<div className="digest-meta">9<div className="digest-meta">

10 <span>发布版本 <a href="/zh-CN/docs/changelog#2-1-158">v2.1.158 → v2.1.165</a></span>10 <span>发布版本 <a href="/zh-CN/docs/changelog#2-1-158">v2.1.158 → v2.1.165</a></span>

13 13

14<div className="digest-feature">14<div className="digest-feature">

15 <div className="digest-feature-header">15 <div className="digest-feature-header">

~~16 <span className="digest-feature-title">Bedrock、Vertex 和 Foundry 上的自动模式</span>~~16 <span className="digest-feature-title">Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的自动模式</span>

17 <span className="digest-feature-pill">v2.1.158</span>17 <span className="digest-feature-pill">v2.1.158</span>

18 </div>18 </div>

19 19

20 <p className="digest-feature-lede">自动模式现已在 Bedrock、Vertex 和 Foundry 上可用，支持 Opus 4.7 和 Opus 4.8，用第三方提供商的后台安全检查替代权限提示。通过设置 <code>CLAUDE\_CODE\_ENABLE\_AUTO\_MODE=1</code> 来选择加入。</p>20 <p className="digest-feature-lede">自动模式现已在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上可用，支持 Opus 4.7 和 Opus 4.8，用第三方提供商的后台安全检查替代权限提示。通过设置 <code>CLAUDE\_CODE\_ENABLE\_AUTO\_MODE=1</code> 来选择加入。</p>

21 21

22 <p className="digest-feature-try">在第三方提供商上选择加入，然后使用 Shift+Tab 切换到自动模式：</p>22 <p className="digest-feature-try">在第三方提供商上选择加入，然后使用 Shift+Tab 切换到自动模式：</p>

23 23

25 export CLAUDE_CODE_ENABLE_AUTO_MODE=125 export CLAUDE_CODE_ENABLE_AUTO_MODE=1

26 ```26 ```

27 27

~~28 <a className="digest-feature-link" href="/zh-CN/docs/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry">在第三方提供商上启用自动模式</a>~~28 <a className="digest-feature-link" href="/zh-CN/docs/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry">在第三方提供商上启用自动模式</a>

29</div>29</div>

30 30

31<div className="digest-feature">31<div className="digest-feature">

workflows.md +28 −2

Details

9{/* plan-availability: feature=workflows plans=pro,max,team,enterprise providers=all */}9{/* plan-availability: feature=workflows plans=pro,max,team,enterprise providers=all */}

10 10

11<Note>11<Note>

12 动态工作流需要 Claude Code v2.1.154 或更高版本，在所有付费计划上可用，具有 Anthropic API 访问权限，以及在 Amazon Bedrock、Google Cloud Vertex AI 和 Microsoft Foundry 上可用。在 Pro 上，从 `/config` 中的"Dynamic workflows"行启用它们。12 动态工作流需要 Claude Code v2.1.154 或更高版本，在所有付费计划上可用，具有 Anthropic API 访问权限，以及在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上可用。在 Pro 上，从 `/config` 中的"Dynamic workflows"行启用它们。

13</Note>13</Note>

14 14

15动态工作流是一个 JavaScript 脚本，可大规模编排[子代理](/zh-CN/sub-agents)。Claude 为您描述的任务编写脚本，运行时在后台执行它，同时您的会话保持响应。15动态工作流是一个 JavaScript 脚本，可大规模编排[子代理](/zh-CN/sub-agents)。Claude 为您描述的任务编写脚本，运行时在后台执行它，同时您的会话保持响应。

148/effort ultracode148/effort ultracode

149```149```

150 150

151要启动已启用 ultracode 的会话，请使用 `claude --effort ultracode` 启动。需要 Claude Code v2.1.203 或更高版本。

152

151启用 ultracode 后，Claude 决定任务何时值得工作流。单个请求可以变成一系列工作流：一个理解代码，一个进行更改，一个验证它。这适用于会话中的每个任务，所以每个请求使用更多令牌并花费比较低努力级别更长的时间。153启用 ultracode 后，Claude 决定任务何时值得工作流。单个请求可以变成一系列工作流：一个理解代码，一个进行更改，一个验证它。这适用于会话中的每个任务，所以每个请求使用更多令牌并花费比较低努力级别更长的时间。

152 154

153Ultracode 持续当前会话，当您启动新会话时重置。当您返回日常工作时，使用 `/effort high` 下降。它在支持 `xhigh` [努力](/zh-CN/model-config#adjust-effort-level)的模型上可用；在其他模型上，`/effort` 菜单不提供它。155Ultracode 持续当前会话，当您启动新会话时重置。当您返回日常工作时，使用 `/effort high` 下降。它在支持 `xhigh` [努力](/zh-CN/model-config#adjust-effort-level)的模型上可用；在其他模型上，`/effort` 菜单不提供它。

346 348

347工作流生成许多代理，所以单次运行可以使用比在对话中处理相同任务更多的令牌。运行计入您的计划使用和速率限制，如任何其他会话。349工作流生成许多代理，所以单次运行可以使用比在对话中处理相同任务更多的令牌。运行计入您的计划使用和速率限制，如任何其他会话。

348 350

349要在提交大型任务前评估支出，请先在小范围上运行工作流：一个目录而不是整个仓库，或一个狭窄的问题而不是一个宽泛的问题。`/workflows` 视图显示每个代理的令牌使用情况，随着运行进行，您可以随时在那里停止运行而不会丢失已完成的工作。运行时的[代理上限](#behavior-and-limits)限制单次运行可以生成多少个代理，这限制了失控脚本的成本。351要在提交大型任务前评估支出，请先在小范围上运行工作流：一个目录而不是整个仓库，或一个狭窄的问题而不是一个宽泛的问题。`/workflows` 视图显示每个代理的令牌使用情况，随着运行进行，您可以随时在那里停止运行而不会丢失已完成的工作。运行时的[代理上限](#behavior-and-limits)限制单次运行可以生成多少个代理，这限制了失控脚本的成本。要默认保持每次运行更小，在 `/config` 中[设置大小指南](#set-a-size-guideline)。

352

353Claude Code 还会标记增长异常大的运行。当工作流调度超过 25 个代理，或其预计令牌总数超过 150 万时，输入框下方任务面板中的其进度行显示 `Large workflow` 警告。警告指向您可以停止运行的 [`/workflows`](#watch-the-run)。需要 Claude Code v2.1.203 或更高版本。

354

355警告是建议性的：它不会暂停或限制运行。当您看到它时，两个设置会改变：

356

357* 如果您[设置大小指南](#set-a-size-guideline)，指南的代理计数替换 25 个代理的阈值。

358* 启用[ultracode](#let-claude-decide-with-ultracode)的会话不显示警告，因为打开 ultracode 已经让您选择加入大型运行。

350 359

351工作流中的每个代理使用您的会话模型，除非脚本将阶段路由到不同的模型。要控制模型成本：360工作流中的每个代理使用您的会话模型，除非脚本将阶段路由到不同的模型。要控制模型成本：

352 361

353* 在大型运行前检查 `/model`，如果您通常为日常工作切换到较小的模型362* 在大型运行前检查 `/model`，如果您通常为日常工作切换到较小的模型

354* 当您描述任务时，要求 Claude 为不需要最强模型的阶段使用较小的模型363* 当您描述任务时，要求 Claude 为不需要最强模型的阶段使用较小的模型

355 364

365<h3 id="set-a-size-guideline">

366 设置大小指南

367</h3>

368

369`/config` 中的 Dynamic workflow size 设置使 Claude 编写的工作流默认保持在较小规模。Claude Code 将该设置作为建议发送给 Claude，所以调用不同规模的提示仍然会覆盖它。需要 Claude Code v2.1.202 或更高版本。

370

371每个值设置 Claude 在其编写的脚本中针对的代理计数。

372

373| 值 | 发送给 Claude 的指导 |

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

375| `unrestricted` | 无指南。这是默认值。 |

376| `small` | 目标少于 5 个代理。 |

377| `medium` | 目标少于 15 个代理。 |

378| `large` | 目标少于 50 个代理。 |

379

380更改在下一个提示时生效。[运行时代理上限](#behavior-and-limits)仍然适用，无论设置如何。

381

356<h3 id="turn-workflows-off">382<h3 id="turn-workflows-off">

357 关闭工作流383 关闭工作流

358</h3>384</h3>

worktrees.md +6 −0

Details

40 40

41在首次在目录中使用 `--worktree` 之前，请通过在该目录中运行一次 `claude` 来接受工作区信任对话框。如果尚未接受信任，`--worktree` 将以错误退出并提示您首先在目录中运行 `claude`。使用 `-p` 的非交互式运行会跳过[信任检查](/zh-CN/security)，因此 `claude -p --worktree` 会在没有信任检查的情况下进行。41在首次在目录中使用 `--worktree` 之前，请通过在该目录中运行一次 `claude` 来接受工作区信任对话框。如果尚未接受信任，`--worktree` 将以错误退出并提示您首先在目录中运行 `claude`。使用 `-p` 的非交互式运行会跳过[信任检查](/zh-CN/security)，因此 `claude -p --worktree` 会在没有信任检查的情况下进行。

42 42

43如果 Claude Code 在启动时无法进入 worktree 目录，例如因为 [`WorktreeCreate` hook](/zh-CN/hooks#worktreecreate) 打印了除了它创建的目录之外的其他内容，或者因为目录在设置后被删除，Claude Code 会打印一个错误，命名该路径并以代码 1 退出。在 v2.1.205 之前，这会导致会话崩溃，使用 `-p` 时会在大约 30 秒后停滞，然后以代码 0 退出。

45{/* min-version: 2.1.200 */}从 Claude Code v2.1.200 开始，在主检出处从[项目范围](/zh-CN/plugins-reference#plugin-installation-scopes)安装的插件也会在同一存储库的 worktrees 中加载，因此您无需为每个 worktree 重新安装它们。这适用于您是使用 `--worktree` 还是使用 `git worktree add` 创建 worktree。需要 Claude Code v2.1.200 或更高版本。

43<Tip>47<Tip>

44 将 `.claude/worktrees/` 添加到您的 `.gitignore`，以便 worktree 内容不会在您的主检出中显示为未跟踪的文件。48 将 `.claude/worktrees/` 添加到您的 `.gitignore`，以便 worktree 内容不会在您的主检出中显示为未跟踪的文件。

45</Tip>49</Tip>

106 110

107当代理运行时，Claude 在其 worktree 上运行 `git worktree lock`，以便并发清理无法将其删除。当代理完成时，锁会被释放。要清理扫描保留的 worktree，请运行 `git worktree remove`，如果 worktree 有未提交的更改或未跟踪的文件，请添加 `--force`。111当代理运行时，Claude 在其 worktree 上运行 `git worktree lock`，以便并发清理无法将其删除。当代理完成时，锁会被释放。要清理扫描保留的 worktree，请运行 `git worktree remove`，如果 worktree 有未提交的更改或未跟踪的文件，请添加 `--force`。

108 112

113在 Windows 上，删除 worktree 之前，Claude Code 会将其内部任何深度的 NTFS 接合点或目录符号链接作为链接条目删除，以便删除 worktree 不会删除链接指向的文件。在 v2.1.205 之前，Claude Code 仅将顶级链接作为链接条目删除，删除包含嵌套在子目录中的接合点的 worktree 可能会删除 worktree 外链接指向的目录的内容。

114

109<h2 id="manage-worktrees-manually">115<h2 id="manage-worktrees-manually">

110 手动管理 worktrees116 手动管理 worktrees

111</h2>117</h2>

zero-data-retention.md +1 −1

Details

19* [服务器管理的设置](/zh-CN/server-managed-settings)19* [服务器管理的设置](/zh-CN/server-managed-settings)

20* 审计日志20* 审计日志

21 21

22Claude for Enterprise 上 Claude Code 的 ZDR 仅适用于 Anthropic 的直接平台。对于在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上的 Claude 部署，请参考这些平台的数据保留政策。22Claude for Enterprise 上 Claude Code 的 ZDR 仅适用于 Anthropic 的直接平台。对于在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上的 Claude 部署，请参考这些平台的数据保留政策。

23 23

24<h2 id="zdr-scope">24<h2 id="zdr-scope">

25 ZDR 范围25 ZDR 范围

Documentation 2026-07-09 23:58 UTC to 2026-07-10 17:00 UTC