6 6
7> 查找 Claude Code 运行时错误消息，了解每个错误的含义以及如何修复。7> 查找 Claude Code 运行时错误消息，了解每个错误的含义以及如何修复。
8 8
9本页列出了 Claude Code 显示的运行时错误以及如何从每个错误中恢复，以及当响应似乎有问题但没有错误时要检查的内容。对于安装错误（如 `command not found` 或设置期间的 TLS 故障），请参阅[故障排除安装和登录](/zh-CN/troubleshoot-install)。9本页列出了 Claude Code 显示的运行时错误以及如何从每个错误中恢复，以及当响应似乎有问题但没有错误时要检查的内容。对于安装错误（如 `command not found` 或设置期间的 TLS 故障），请参阅[故障排除安装和登录](/docs/zh-CN/troubleshoot-install)。
10 10
11这些错误和恢复命令适用于 CLI、[桌面应用](/zh-CN/desktop)和[网络上的 Claude Code](/zh-CN/claude-code-on-the-web)，因为这三个都包装了相同的 Claude Code CLI。对于特定于表面的问题，请参阅该表面页面上的故障排除部分。11这些错误和恢复命令适用于 CLI、[桌面应用](/docs/zh-CN/desktop)和[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)，因为这三个都包装了相同的 Claude Code CLI。对于特定于表面的问题，请参阅该表面页面上的故障排除部分。
12 12
13<Note>13<Note>
14 Claude Code 调用 Claude API 获取模型响应，因此大多数运行时错误映射到底层 API 错误代码。本页介绍了每个错误在 Claude Code 中的含义以及如何恢复。有关原始 HTTP 状态代码定义，请参阅 [Claude Platform 错误参考](https://platform.claude.com/docs/en/api/errors)。14 Claude Code 调用 Claude API 获取模型响应，因此大多数运行时错误映射到底层 API 错误代码。本页介绍了每个错误在 Claude Code 中的含义以及如何恢复。有关原始 HTTP 状态代码定义，请参阅 [Claude Platform 错误参考](https://platform.claude.com/docs/en/api/errors)。
97 自动重试97 自动重试
98</h2>98</h2>
99 99
100Claude Code 在向您显示错误之前会重试瞬时故障。服务器错误、过载响应、请求超时、临时 429 限流和断开的连接都会以指数退避方式重试最多 10 次。{/* min-version: 2.1.198 */}从 v2.1.198 开始，这涵盖了在任何可见输出流出之前在响应中途断开的连接：Claude Code 使用相同的退避重新发出请求，轮次继续而不是停止并显示连接错误。{/* min-version: 2.1.199 */}从 v2.1.199 开始，不携带您计划配额标头的临时 429 限流在您使用 claude.ai 订阅登录时也会重试；早期版本仅对 API 密钥和企业登录重试它们。100Claude Code 在向您显示错误之前会重试瞬时故障。服务器错误、过载响应、请求超时、临时 429 限流和断开的连接都会以指数退避方式重试最多 10 次。从 v2.1.198 开始，这涵盖了在任何可见输出流出之前在响应中途断开的连接：Claude Code 使用相同的退避重新发出请求，轮次继续而不是停止并显示连接错误。从 v2.1.199 开始，不携带您计划配额标头的临时 429 限流在您使用 claude.ai 订阅登录时也会重试；早期版本仅对 API 密钥和企业登录重试它们。
101 101
102某些故障类别不会重试，因为重试无法成功：102某些故障类别不会重试，因为重试无法成功：
103 103
104* {/* min-version: 2.1.199 */}从 v2.1.199 开始，TLS 证书验证失败（例如 TLS 检查代理、缺少 `NODE_EXTRA_CA_CERTS` 包或过期证书）在第一次尝试时失败，因此修复立即出现，而不是在完整重试预算之后。请参阅 [SSL 证书错误](#ssl-certificate-errors)。瞬时 TLS 条件（例如握手超时）仍然会重试。104* 从 v2.1.199 开始，TLS 证书验证失败（例如 TLS 检查代理、缺少 `NODE_EXTRA_CA_CERTS` 包或过期证书）在第一次尝试时失败，因此修复立即出现，而不是在完整重试预算之后。请参阅 [SSL 证书错误](#ssl-certificate-errors)。瞬时 TLS 条件（例如握手超时）仍然会重试。
105* {/* min-version: 2.1.199 */}从 v2.1.199 开始，在 Claude 已经流出可见输出后到达的服务器错误会保留部分响应并附加[不完整响应通知](#the-response-above-may-be-incomplete)，而不是重试，因为重新运行请求可能会执行相同的工具两次。早期版本丢弃了部分输出并将轮次报告为错误。105* 从 v2.1.199 开始，在 Claude 已经流出可见输出后到达的服务器错误会保留部分响应并附加[不完整响应通知](#the-response-above-may-be-incomplete)，而不是重试，因为重新运行请求可能会执行相同的工具两次。早期版本丢弃了部分输出并将轮次报告为错误。
106* {/* min-version: 2.1.208 */}[Amazon Bedrock 流式响应具有意外的内容类型](#bedrock-streaming-response-has-an-unexpected-content-type)在第一次尝试时失败，因为网关或代理重写响应会以相同方式重写重试。需要 Claude Code v2.1.208 或更高版本。106* [Amazon Bedrock 流式响应具有意外的内容类型](#bedrock-streaming-response-has-an-unexpected-content-type)在第一次尝试时失败，因为网关或代理重写响应会以相同方式重写重试。需要 Claude Code v2.1.208 或更高版本。
107 107
108重试时，微调器在错误标签后显示 `Retrying in Ns · attempt x/y` 倒计时。标签命名了第一次尝试中您可以立即采取行动的特定原因：网络已关闭、TLS 握手失败或您达到了速率限制。对于其他错误，它最初读作 `API error`。{/* min-version: 2.1.198 */}从 v2.1.198 开始，它切换到第三次尝试中的特定原因，或当 `CLAUDE_CODE_MAX_RETRIES` 允许少于三次时在最后一次尝试；早期版本仅在最后一次尝试时切换。108重试时，微调器在错误标签后显示 `Retrying in Ns · attempt x/y` 倒计时。标签命名了第一次尝试中您可以立即采取行动的特定原因：网络已关闭、TLS 握手失败或您达到了速率限制。对于其他错误，它最初读作 `API error`。从 v2.1.198 开始，它切换到第三次尝试中的特定原因，或当 `CLAUDE_CODE_MAX_RETRIES` 允许少于三次时在最后一次尝试；早期版本仅在最后一次尝试时切换。
109 109
110{/* min-version: 2.1.198 */}从 v2.1.198 开始，重试期间会抑制通常的微调器提示。一旦错误原因被揭示，如果故障是 529 过载，倒计时下方的行也会命名检查服务状态的位置：Anthropic API 上的 `status.claude.com`，或其他配置上的提供商或网关主机。110从 v2.1.198 开始，重试期间会抑制通常的微调器提示。一旦错误原因被揭示，如果故障是 529 过载，倒计时下方的行也会命名检查服务状态的位置：Anthropic API 上的 `status.claude.com`，或其他配置上的提供商或网关主机。
111 111
112{/* min-version: 2.1.185 */}如果在请求仍然待处理时，响应流上 20 秒内没有数据到达，微调器会显示 `Waiting for API response · will retry in … · check your network`，然后再进行任何重试。请求尚未失败：倒计时运行到 Claude Code 中止停滞连接并重试的点，因此一旦数据恢复或重试成功，横幅就会自动清除。从 v2.1.185 开始，阈值为 20 秒；早期版本在 10 秒后显示横幅，措辞不同。如果它在每次尝试时都重新出现，请将其视为[网络问题](#unable-to-connect-to-api)。112如果在请求仍然待处理时，响应流上 20 秒内没有数据到达，微调器会显示 `Waiting for API response · will retry in … · check your network`，然后再进行任何重试。请求尚未失败：倒计时运行到 Claude Code 中止停滞连接并重试的点，因此一旦数据恢复或重试成功，横幅就会自动清除。从 v2.1.185 开始，阈值为 20 秒；早期版本在 10 秒后显示横幅，措辞不同。如果它在每次尝试时都重新出现，请将其视为[网络问题](#unable-to-connect-to-api)。
113 113
114当您看到本页上的错误之一时，这些重试已经用尽，除非它属于不会重试的类别，例如证书验证失败。您可以使用这些环境变量调整行为：114当您看到本页上的错误之一时，这些重试已经用尽，除非它属于不会重试的类别，例如证书验证失败。您可以使用这些环境变量调整行为：
115 115
116| 变量 | 默认值 | 效果 |116| 变量 | 默认值 | 效果 |
117| :---------------------------------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |117| :---------------------------------------------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
118| [`CLAUDE_CODE_MAX_RETRIES`](/zh-CN/env-vars) | 10 | 重试次数。{/* min-version: 2.1.186 */}从 v2.1.186 开始上限为 15；{/* min-version: 2.1.199 */}从 v2.1.199 开始 `CLAUDE_CODE_RETRY_WATCHDOG` 提高默认值并移除上限。降低它以在脚本中更快地显示故障。 |118| [`CLAUDE_CODE_MAX_RETRIES`](/docs/zh-CN/env-vars) | 10 | 重试次数。从 v2.1.186 开始上限为 15；从 v2.1.199 开始 `CLAUDE_CODE_RETRY_WATCHDOG` 提高默认值并移除上限。降低它以在脚本中更快地显示故障。 |
119| [`CLAUDE_CODE_RETRY_WATCHDOG`](/zh-CN/env-vars) | 未设置 | 在 CI 作业等无人值守会话中设置为 `1`，以无限期重试 `429` 和 `529` 容量错误，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次尝试后失败。{/* min-version: 2.1.199 */}从 v2.1.199 开始，它也提高了其他瞬时错误（例如服务器错误、超时和断开的连接）的默认重试计数至 300，大约三小时的退避，如果您显式设置该变量，则移除 `CLAUDE_CODE_MAX_RETRIES` 的 15 上限。 |119| [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/zh-CN/env-vars) | 未设置 | 在 CI 作业等无人值守会话中设置为 `1`，以无限期重试 `429` 和 `529` 容量错误，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次尝试后失败。从 v2.1.199 开始，它也提高了其他瞬时错误（例如服务器错误、超时和断开的连接）的默认重试计数至 300，大约三小时的退避，如果您显式设置该变量，则移除 `CLAUDE_CODE_MAX_RETRIES` 的 15 上限。 |
120| [`API_TIMEOUT_MS`](/zh-CN/env-vars) | 600000 | 每个请求的超时时间（毫秒）。为慢速网络或代理提高它。 |120| [`API_TIMEOUT_MS`](/docs/zh-CN/env-vars) | 600000 | 每个请求的超时时间（毫秒）。为慢速网络或代理提高它。 |
121 121
122<h2 id="server-errors">122<h2 id="server-errors">
123 服务器错误123 服务器错误
196API Error: Response stalled mid-stream. The response above may be incomplete.196API Error: Response stalled mid-stream. The response above may be incomplete.
197```197```
198 198
199* {/* min-version: 2.1.199 */}}`Server error mid-response`：流中的过载或 5xx 服务器错误。此变体需要 Claude Code v2.1.199 或更高版本；在此之前，该情况会丢弃部分输出并将整个轮次报告为错误。199* }`Server error mid-response`：流中的过载或 5xx 服务器错误。此变体需要 Claude Code v2.1.199 或更高版本；在此之前，该情况会丢弃部分输出并将整个轮次报告为错误。
200* `Connection closed mid-response`：连接断开。200* `Connection closed mid-response`：连接断开。
201* `Response stalled mid-stream`：流停止发送数据。201* `Response stalled mid-stream`：流停止发送数据。
202 202
210 自动模式无法确定操作的安全性210 自动模式无法确定操作的安全性
211</h3>211</h3>
212 212
213[自动模式](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)用来分类操作的模型无法做出决定，因此自动模式没有自动批准该操作。您看到的消息取决于分类器失败的原因。213[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)用来分类操作的模型无法做出决定，因此自动模式没有自动批准该操作。您看到的消息取决于分类器失败的原因。
214 214
215在您的工作目录内的读取、搜索和编辑会跳过分类器，因此在所有这些情况下都能继续工作。215在您的工作目录内的读取、搜索和编辑会跳过分类器，因此在所有这些情况下都能继续工作。
216 216
224 224
225* 几秒钟后重试；Claude 会看到相同的消息，通常会自动重试225* 几秒钟后重试；Claude 会看到相同的消息，通常会自动重试
226* 如果重试继续失败，继续执行只读任务，稍后再回到被阻止的操作226* 如果重试继续失败，继续执行只读任务，稍后再回到被阻止的操作
227* 这是暂时的，与[自动模式资格](/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)无关；您不需要更改设置227* 这是暂时的，与[自动模式资格](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)无关；您不需要更改设置
228 228
229当分类器返回无法解析的响应时：229当分类器返回无法解析的响应时：
230 230
247 247
248* 这不是关于您的操作的决定。您对话中已有的内容在自动模式将对话发送给分类器时触发了 API 上的安全过滤器248* 这不是关于您的操作的决定。您对话中已有的内容在自动模式将对话发送给分类器时触发了 API 上的安全过滤器
249* 重试无法帮助；相同的对话内容将再次触发过滤器249* 重试无法帮助；相同的对话内容将再次触发过滤器
250* 切换到不同的[权限模式](/zh-CN/permission-modes)，以便在提示时可以批准该操作，或开始一个没有触发内容的新对话250* 切换到不同的[权限模式](/docs/zh-CN/permission-modes)，以便在提示时可以批准该操作，或开始一个没有触发内容的新对话
251 251
252当对话大小超过分类器的上下文窗口时：252当对话大小超过分类器的上下文窗口时：
253 253
255Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)255Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)
256```256```
257 257
258在交互式会话中，自动模式会为该操作回退到正常权限提示，以便您可以手动批准或拒绝它。在[非交互式模式](/zh-CN/headless)中，运行会中止，因为记录只会增长，重试无法成功。258在交互式会话中，自动模式会为该操作回退到正常权限提示，以便您可以手动批准或拒绝它。在[非交互式模式](/docs/zh-CN/headless)中，运行会中止，因为记录只会增长，重试无法成功。
259 259
260**应该做什么：**260**应该做什么：**
261 261
266 代理因 API 错误而提前终止266 代理因 API 错误而提前终止
267</h3>267</h3>
268 268
269{/* min-version: 2.1.199 */}[子代理](/zh-CN/sub-agents)的 API 请求终止失败，例如因为达到了使用限制或服务器错误的重试用尽，所以子代理在完成其任务之前停止。此消息需要 Claude Code v2.1.199 或更高版本；在此之前，API 错误文本被返回给 Claude，就像它是子代理的结果一样。269[子代理](/docs/zh-CN/sub-agents)的 API 请求终止失败，例如因为达到了使用限制或服务器错误的重试用尽，所以子代理在完成其任务之前停止。此消息需要 Claude Code v2.1.199 或更高版本；在此之前，API 错误文本被返回给 Claude，就像它是子代理的结果一样。
270 270
271```text theme={null}271```text theme={null}
272Agent terminated early due to an API error: <error detail>272Agent terminated early due to an API error: <error detail>
275**应该做什么：**275**应该做什么：**
276 276
277* 将冒号后的错误详情与此页面上的其自己的部分相匹配，例如[使用限制](#usage-limits)或[服务器错误](#server-errors)，并按照该部分的步骤操作277* 将冒号后的错误详情与此页面上的其自己的部分相匹配，例如[使用限制](#usage-limits)或[服务器错误](#server-errors)，并按照该部分的步骤操作
278* 一旦底层错误清除，请要求 Claude 重试任务或[恢复子代理](/zh-CN/sub-agents#resume-subagents)278* 一旦底层错误清除，请要求 Claude 重试任务或[恢复子代理](/docs/zh-CN/sub-agents#resume-subagents)
279 279
280当速率限制、过载或服务器错误中断已经生成文本输出的前台子代理时，Claude 会收到该部分输出标记为不完整，而不是此错误。{/* min-version: 2.1.200 */}仅输出为工具调用的子代理也会收到此错误；在 v2.1.199 中，该形状返回了空的部分结果。请参阅[子代理中的 API 错误](/zh-CN/sub-agents#api-errors-in-subagents)。280当速率限制、过载或服务器错误中断已经生成文本输出的前台子代理时，Claude 会收到该部分输出标记为不完整，而不是此错误。仅输出为工具调用的子代理也会收到此错误；在 v2.1.199 中，该形状返回了空的部分结果。请参阅[子代理中的 API 错误](/docs/zh-CN/sub-agents#api-errors-in-subagents)。
281 281
282<h2 id="usage-limits">282<h2 id="usage-limits">
283 使用限制283 使用限制
309* 运行 `/usage-credits` 在 Pro 和 Max 上购买额外使用量，或在 Team 和 Enterprise 上向您的管理员请求。有关如何计费，请参阅[付费计划的使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。309* 运行 `/usage-credits` 在 Pro 和 Max 上购买额外使用量，或在 Team 和 Enterprise 上向您的管理员请求。有关如何计费，请参阅[付费计划的使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。
310* 要升级您的计划以获得更高的基础限制，请参阅 [claude.com/pricing](https://claude.com/pricing)310* 要升级您的计划以获得更高的基础限制，请参阅 [claude.com/pricing](https://claude.com/pricing)
311 311
312要在达到限制之前监控您的剩余额度，请将 `rate_limits` 字段添加到[自定义状态行](/zh-CN/statusline#rate-limit-usage)，或在桌面应用中单击模型选择器旁边的[使用量环](/zh-CN/desktop#check-usage)。312要在达到限制之前监控您的剩余额度，请将 `rate_limits` 字段添加到[自定义状态行](/docs/zh-CN/statusline#rate-limit-usage)，或在桌面应用中单击模型选择器旁边的[使用量环](/docs/zh-CN/desktop#check-usage)。
313 313
314<h3 id="usage-credits-required-for-1m-context">314<h3 id="usage-credits-required-for-1m-context">
315 1M 上下文需要使用额度315 1M 上下文需要使用额度
321API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context321API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context
322```322```
323 323
324这是一项权利检查，而不是配额耗尽。即使您的会话和每周额度仍有容量，它也会触发。有关哪些计划直接包含 1M 上下文以及哪些需要使用额度，请参阅[扩展上下文](/zh-CN/model-config#extended-context)。324这是一项权利检查，而不是配额耗尽。即使您的会话和每周额度仍有容量，它也会触发。有关哪些计划直接包含 1M 上下文以及哪些需要使用额度，请参阅[扩展上下文](/docs/zh-CN/model-config#extended-context)。
325 325
326{/* min-version: 2.1.172 */}当此错误在对话中期出现，因为上下文增长超过 200K 令牌时，Claude Code 会自动将对话压缩回标准上下文限制以下，并在之后将会话保持在该限制，因此无需采取任何操作。在 v2.1.172 之前的版本上，错误会在每个后续请求（包括 `/compact`）上重复出现；在这些版本上运行 `/clear` 以恢复。以下步骤适用于您明确选择 `[1m]` 模型的情况。326当此错误在对话中期出现，因为上下文增长超过 200K 令牌时，Claude Code 会自动将对话压缩回标准上下文限制以下，并在之后将会话保持在该限制，因此无需采取任何操作。在 v2.1.172 之前的版本上，错误会在每个后续请求（包括 `/compact`）上重复出现；在这些版本上运行 `/clear` 以恢复。以下步骤适用于您明确选择 `[1m]` 模型的情况。
327 327
328**应该怎么做：**328**应该怎么做：**
329 329
330* 运行 `/model` 并选择不带 `[1m]` 后缀的变体以回退到标准上下文窗口330* 运行 `/model` 并选择不带 `[1m]` 后缀的变体以回退到标准上下文窗口
331* 运行 `/usage-credits` 在 Pro 和 Max 上为 1M 变体启用按量计费，或在 Team 和 Enterprise 上向您的管理员请求331* 运行 `/usage-credits` 在 Pro 和 Max 上为 1M 变体启用按量计费，或在 Team 和 Enterprise 上向您的管理员请求
332* 如果 `/model` 后错误仍然存在，1M 模型 ID 可能在其他地方设置。有关要按优先级顺序检查的配置位置，请参阅[所选模型存在问题](#theres-an-issue-with-the-selected-model)。332* 如果 `/model` 后错误仍然存在，1M 模型 ID 可能在其他地方设置。有关要按优先级顺序检查的配置位置，请参阅[所选模型存在问题](#theres-an-issue-with-the-selected-model)。
333* 要从模型选择器中完全删除 1M 变体，请设置 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/zh-CN/env-vars)333* 要从模型选择器中完全删除 1M 变体，请设置 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-CN/env-vars)
334 334
335<h3 id="server-is-temporarily-limiting-requests">335<h3 id="server-is-temporarily-limiting-requests">
336 服务器暂时限制请求336 服务器暂时限制请求
342API Error: Server is temporarily limiting requests (not your usage limit)342API Error: Server is temporarily limiting requests (not your usage limit)
343```343```
344 344
345Claude Code 通过真实限制响应所携带的统一配额标头的缺失来区分这些与您的计划限制。{/* min-version: 2.1.199 */}从 v2.1.199 开始，无论您如何进行身份验证，这都会[自动重试](#automatic-retries)并进行退避，然后才会显示。在早期版本上，使用 claude.ai 订阅登录的会话在第一次出现时失败；只有 API 密钥和 Enterprise 登录会重试。345Claude Code 通过真实限制响应所携带的统一配额标头的缺失来区分这些与您的计划限制。从 v2.1.199 开始，无论您如何进行身份验证，这都会[自动重试](#automatic-retries)并进行退避，然后才会显示。在早期版本上，使用 claude.ai 订阅登录的会话在第一次出现时失败；只有 API 密钥和 Enterprise 登录会重试。
346 346
347**应该怎么做：**347**应该怎么做：**
348 348
366* 运行 `/status` 并确认活跃凭证是您期望的凭证。环境中的杂散 `ANTHROPIC_API_KEY` 可能会通过低级密钥而不是您的订阅来路由请求。366* 运行 `/status` 并确认活跃凭证是您期望的凭证。环境中的杂散 `ANTHROPIC_API_KEY` 可能会通过低级密钥而不是您的订阅来路由请求。
367* 检查您的提供商控制台以了解活跃限制，如果需要，请请求更高的层级367* 检查您的提供商控制台以了解活跃限制，如果需要，请请求更高的层级
368* 对于 Anthropic API 密钥，请参阅[速率限制参考](https://platform.claude.com/docs/en/api/rate-limits)了解层级如何工作以及如何设置每个工作区的上限368* 对于 Anthropic API 密钥，请参阅[速率限制参考](https://platform.claude.com/docs/en/api/rate-limits)了解层级如何工作以及如何设置每个工作区的上限
369* 降低并发：降低 [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/zh-CN/env-vars)，避免运行许多并行子代理，或使用 `/model` 切换到较小的模型以进行大容量脚本运行369* 降低并发：降低 [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/docs/zh-CN/env-vars)，避免运行许多并行子代理，或使用 `/model` 切换到较小的模型以进行大容量脚本运行
370 370
371<h3 id="credit-balance-is-too-low">371<h3 id="credit-balance-is-too-low">
372 信用余额过低372 信用余额过低
382 382
383* 在 [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing) 添加信用，并考虑在那里启用自动重新加载，以便在余额达到零之前进行补充383* 在 [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing) 添加信用，并考虑在那里启用自动重新加载，以便在余额达到零之前进行补充
384* 如果您有 Pro、Max、Team 或 Enterprise 计划，请使用 `/login` 切换到订阅身份验证384* 如果您有 Pro、Max、Team 或 Enterprise 计划，请使用 `/login` 切换到订阅身份验证
385* 在 Console 中设置每个工作区的支出上限，以防止单个项目耗尽组织余额。请参阅[有效管理成本](/zh-CN/costs)。385* 在 Console 中设置每个工作区的支出上限，以防止单个项目耗尽组织余额。请参阅[有效管理成本](/docs/zh-CN/costs)。
386 386
387<h2 id="authentication-errors">387<h2 id="authentication-errors">
388 身份验证错误388 身份验证错误
404 404
405* 运行 `/login` 使用您的 Claude 订阅或 Console 账户进行身份验证405* 运行 `/login` 使用您的 Claude 订阅或 Console 账户进行身份验证
406* 如果您期望使用环境变量进行身份验证，请确认 `ANTHROPIC_API_KEY` 已在启动 `claude` 的 shell 中设置并导出406* 如果您期望使用环境变量进行身份验证，请确认 `ANTHROPIC_API_KEY` 已在启动 `claude` 的 shell 中设置并导出
407* 对于无法进行交互式登录的 CI 或自动化环境，配置一个 [`apiKeyHelper`](/zh-CN/settings#available-settings) 脚本，在启动时获取密钥407* 对于无法进行交互式登录的 CI 或自动化环境，配置一个 [`apiKeyHelper`](/docs/zh-CN/settings#available-settings) 脚本，在启动时获取密钥
408* 查看 [身份验证优先级](/zh-CN/authentication#authentication-precedence) 了解当存在多个凭证时 Claude Code 使用哪个凭证408* 查看 [身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) 了解当存在多个凭证时 Claude Code 使用哪个凭证
409 409
410如果您被反复提示登录，请参阅 [未登录或令牌过期](/zh-CN/troubleshoot-install#not-logged-in-or-token-expired) 了解系统时钟和 macOS Keychain 修复。410如果您被反复提示登录，请参阅 [未登录或令牌过期](/docs/zh-CN/troubleshoot-install#not-logged-in-or-token-expired) 了解系统时钟和 macOS Keychain 修复。
411 411
412<h3 id="could-not-resolve-authentication-method">412<h3 id="could-not-resolve-authentication-method">
413 无法解析身份验证方法413 无法解析身份验证方法
414</h3>414</h3>
415 415
416会话到达 API 客户端时没有任何凭证。这出现在 [后台会话](/zh-CN/agent-view)、云会话和 Agent SDK 上下文中，其中交互式登录检查在第一个请求之前不会运行。416会话到达 API 客户端时没有任何凭证。这出现在 [后台会话](/docs/zh-CN/agent-view)、云会话和 Agent SDK 上下文中，其中交互式登录检查在第一个请求之前不会运行。
417 417
418```text theme={null}418```text theme={null}
419Could 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 omitted419Could 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
420```420```
421 421
422{/* min-version: 2.1.174 */}在 v2.1.174 之前，分配给空闲预初始化工作进程的后台或云会话即使配置了有效凭证也可能以这种方式失败。升级以恢复。在当前版本中，该错误意味着工作进程没有可用的凭证。422在 v2.1.174 之前，分配给空闲预初始化工作进程的后台或云会话即使配置了有效凭证也可能以这种方式失败。升级以恢复。在当前版本中，该错误意味着工作进程没有可用的凭证。
423 423
424**应该做什么：**424**应该做什么：**
425 425
426* 如果这出现在后台或云会话中且您的凭证已配置，请升级到 v2.1.174 或更高版本426* 如果这出现在后台或云会话中且您的凭证已配置，请升级到 v2.1.174 或更高版本
427* 确认 `ANTHROPIC_API_KEY`、`CLAUDE_CODE_OAUTH_TOKEN` 或您的云提供商凭证已在启动工作进程的环境中设置，而不仅仅在您的交互式 shell 中427* 确认 `ANTHROPIC_API_KEY`、`CLAUDE_CODE_OAUTH_TOKEN` 或您的云提供商凭证已在启动工作进程的环境中设置，而不仅仅在您的交互式 shell 中
428* 对于 Agent SDK，请参阅 [身份验证设置](/zh-CN/agent-sdk/overview#get-started)428* 对于 Agent SDK，请参阅 [身份验证设置](/docs/zh-CN/agent-sdk/overview#get-started)
429* 在同一环境中的交互式会话中运行 `/status` 以确认哪个凭证源可以解析429* 在同一环境中的交互式会话中运行 `/status` 以确认哪个凭证源可以解析
430 430
431<h3 id="invalid-api-key">431<h3 id="invalid-api-key">
443* 检查拼写错误并确认密钥未在 [Console](https://platform.claude.com/settings/keys) 中被撤销443* 检查拼写错误并确认密钥未在 [Console](https://platform.claude.com/settings/keys) 中被撤销
444* 在同一 shell 中运行 `env | grep ANTHROPIC`。direnv、dotenv shell 插件和 IDE 终端等工具可以从项目中的 `.env` 文件加载过时的密钥，而无需您显式设置它444* 在同一 shell 中运行 `env | grep ANTHROPIC`。direnv、dotenv shell 插件和 IDE 终端等工具可以从项目中的 `.env` 文件加载过时的密钥，而无需您显式设置它
445* 取消设置 `ANTHROPIC_API_KEY` 并运行 `/login` 改用订阅身份验证445* 取消设置 `ANTHROPIC_API_KEY` 并运行 `/login` 改用订阅身份验证
446* 如果密钥来自 [`apiKeyHelper`](/zh-CN/settings#available-settings) 脚本，直接运行该脚本以确认它在 stdout 上打印有效密钥446* 如果密钥来自 [`apiKeyHelper`](/docs/zh-CN/settings#available-settings) 脚本，直接运行该脚本以确认它在 stdout 上打印有效密钥
447* 运行 `/status` 确认 Claude Code 实际使用的凭证源447* 运行 `/status` 确认 Claude Code 实际使用的凭证源
448 448
449<h3 id="your-apikeyhelper-script-is-failing">449<h3 id="your-apikeyhelper-script-is-failing">
450 您的 apiKeyHelper 脚本失败450 您的 apiKeyHelper 脚本失败
451</h3>451</h3>
452 452
453在 [`apiKeyHelper`](/zh-CN/settings#available-settings) 设置中配置的命令以错误退出、超时或未向 stdout 打印任何内容。没有来自脚本的密钥，请求到达 API 时带有占位符凭证，API 以 `401` 拒绝它。453在 [`apiKeyHelper`](/docs/zh-CN/settings#available-settings) 设置中配置的命令以错误退出、超时或未向 stdout 打印任何内容。没有来自脚本的密钥，请求到达 API 时带有占位符凭证，API 以 `401` 拒绝它。
454 454
455```text theme={null}455```text theme={null}
456Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output456Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output
457```457```
458 458
459Claude Code 重新运行脚本并在显示此消息之前最多重试请求两次，因此故障在三次尝试内浮出。{/* min-version: 2.1.208 */}在 v2.1.208 之前，Claude Code 花费完整的 [重试预算](#automatic-retries) 使用占位符凭证重新发送请求，然后报告通用的 `401` 身份验证错误而不是脚本故障。459Claude Code 重新运行脚本并在显示此消息之前最多重试请求两次，因此故障在三次尝试内浮出。在 v2.1.208 之前，Claude Code 花费完整的 [重试预算](#automatic-retries) 使用占位符凭证重新发送请求，然后报告通用的 `401` 身份验证错误而不是脚本故障。
460 460
461运行 `/login` 在这里无法帮助：只要设置存在，helper 的输出 [优先于](/zh-CN/authentication#authentication-precedence) 保存的登录。461运行 `/login` 在这里无法帮助：只要设置存在，helper 的输出 [优先于](/docs/zh-CN/authentication#authentication-precedence) 保存的登录。
462 462
463**应该做什么：**463**应该做什么：**
464 464
465* 在您的 shell 中直接运行在 `apiKeyHelper` 中配置的命令以重现故障465* 在您的 shell 中直接运行在 `apiKeyHelper` 中配置的命令以重现故障
466* 如果命令报告会话已过期，请使用您的凭证提供商重新身份验证，例如再次登录您的 SSO 或密钥保管库466* 如果命令报告会话已过期，请使用您的凭证提供商重新身份验证，例如再次登录您的 SSO 或密钥保管库
467* 修复命令以便它将密钥打印到 stdout 并以代码 0 退出。有关工作设置，请参阅 [使用 apiKeyHelper 轮换凭证](/zh-CN/llm-gateway-connect#rotate-credentials-with-apikeyhelper)。467* 修复命令以便它将密钥打印到 stdout 并以代码 0 退出。有关工作设置，请参阅 [使用 apiKeyHelper 轮换凭证](/docs/zh-CN/llm-gateway-connect#rotate-credentials-with-apikeyhelper)。
468* 运行 `/status` 确认 `apiKeyHelper` 是活跃凭证源。每次命令失败时，其退出代码和错误输出都会出现在终端中的 `Cloud authentication` 面板中。468* 运行 `/status` 确认 `apiKeyHelper` 是活跃凭证源。每次命令失败时，其退出代码和错误输出都会出现在终端中的 `Cloud authentication` 面板中。
469 469
470<h3 id="this-organization-has-been-disabled">470<h3 id="this-organization-has-been-disabled">
499Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account499Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account
500```500```
501 501
502环境变量和 `apiKeyHelper` 优先于 `/login`，因此仅运行 `/login` 在任一仍在提供密钥时无法帮助。请参阅 [身份验证优先级](/zh-CN/authentication#authentication-precedence)。502环境变量和 `apiKeyHelper` 优先于 `/login`，因此仅运行 `/login` 在任一仍在提供密钥时无法帮助。请参阅 [身份验证优先级](/docs/zh-CN/authentication#authentication-precedence)。
503 503
504**应该做什么：**504**应该做什么：**
505 505
506* 如果消息提到 `ANTHROPIC_API_KEY`，在当前 shell 中取消设置它并从 shell 配置文件或 `.env` 文件中删除它，然后重新启动 `claude`506* 如果消息提到 `ANTHROPIC_API_KEY`，在当前 shell 中取消设置它并从 shell 配置文件或 `.env` 文件中删除它，然后重新启动 `claude`
507* 如果消息提到 `apiKeyHelper`，从您的 `settings.json` 中删除 [`apiKeyHelper`](/zh-CN/settings#available-settings) 设置507* 如果消息提到 `apiKeyHelper`，从您的 `settings.json` 中删除 [`apiKeyHelper`](/docs/zh-CN/settings#available-settings) 设置
508* 运行 `/login` 使用您的 claude.ai 账户登录508* 运行 `/login` 使用您的 claude.ai 账户登录
509* 之后运行 `/status` 确认活跃凭证是您的订阅而不是 API 密钥509* 之后运行 `/status` 确认活跃凭证是您的订阅而不是 API 密钥
510* 如果您需要 API 密钥身份验证用于自动化，请要求您的组织管理员在 Console 中重新启用它510* 如果您需要 API 密钥身份验证用于自动化，请要求您的组织管理员在 Console 中重新启用它
526**应该做什么：**526**应该做什么：**
527 527
528* 要求您的管理员为您的组织启用 Claude Code 访问528* 要求您的管理员为您的组织启用 Claude Code 访问
529* 使用 Console API 密钥而不是您的订阅进行身份验证。有关设置，请参阅 [Claude Console 身份验证](/zh-CN/authentication#claude-console-authentication)。529* 使用 Console API 密钥而不是您的订阅进行身份验证。有关设置，请参阅 [Claude Console 身份验证](/docs/zh-CN/authentication#claude-console-authentication)。
530* 如果您是管理员且看不到启用访问的选项，请联系 [Anthropic 支持](https://support.claude.com)530* 如果您是管理员且看不到启用访问的选项，请联系 [Anthropic 支持](https://support.claude.com)
531 531
532<h3 id="routines-are-disabled-by-your-organizations-policy">532<h3 id="routines-are-disabled-by-your-organizations-policy">
533 例程被您的组织的策略禁用533 例程被您的组织的策略禁用
534</h3>534</h3>
535 535
536您的 Team 或 Enterprise 组织中的所有者已在组织级别关闭例程。当您尝试创建或运行例程时会出现该错误，包括从 `/schedule` 和 claude.ai/code 上的 [Routines](/zh-CN/routines) UI。536您的 Team 或 Enterprise 组织中的所有者已在组织级别关闭例程。当您尝试创建或运行例程时会出现该错误，包括从 `/schedule` 和 claude.ai/code 上的 [Routines](/docs/zh-CN/routines) UI。
537 537
538```text theme={null}538```text theme={null}
539Routines are disabled by your organization's policy.539Routines are disabled by your organization's policy.
544**应该做什么：**544**应该做什么：**
545 545
546* 要求您的组织中的所有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 启用 **Routines** 切换546* 要求您的组织中的所有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 启用 **Routines** 切换
547* 对于不需要组织级例程的一次性计划工作，请参阅 [计划任务](/zh-CN/scheduled-tasks)547* 对于不需要组织级例程的一次性计划工作，请参阅 [计划任务](/docs/zh-CN/scheduled-tasks)
548 548
549<h3 id="remote-control-requires-the-anthropic-api">549<h3 id="remote-control-requires-the-anthropic-api">
550 Remote Control 需要 Anthropic API550 Remote Control 需要 Anthropic API
551</h3>551</h3>
552 552
553会话不是直接与 Anthropic API 通信，因此没有 claude.ai 后端供 [Remote Control](/zh-CN/remote-control) 配对。553会话不是直接与 Anthropic API 通信，因此没有 claude.ai 后端供 [Remote Control](/docs/zh-CN/remote-control) 配对。
554 554
555```text theme={null}555```text theme={null}
556Remote Control is only available when using Claude via api.anthropic.com.556Remote Control is only available when using Claude via api.anthropic.com.
557```557```
558 558
559这出现在 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 登录，它也会出现。559这出现在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上。从 v2.1.196 开始，当 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 指向 `api.anthropic.com` 以外的主机时，例如 [LLM 网关](/docs/zh-CN/llm-gateway) 或代理，即使您使用 claude.ai 登录，它也会出现。
560 560
561**应该做什么：**561**应该做什么：**
562 562
563* 取消设置 `ANTHROPIC_BASE_URL` 并重启会话，或从直接与 Anthropic API 通信的会话启动 Remote Control563* 取消设置 `ANTHROPIC_BASE_URL` 并重启会话，或从直接与 Anthropic API 通信的会话启动 Remote Control
564* 对于此错误和其他 Remote Control 启动消息，请参阅 [Remote Control 故障排除](/zh-CN/remote-control#troubleshooting)564* 对于此错误和其他 Remote Control 启动消息，请参阅 [Remote Control 故障排除](/docs/zh-CN/remote-control#troubleshooting)
565 565
566<h3 id="oauth-token-revoked-or-expired">566<h3 id="oauth-token-revoked-or-expired">
567 OAuth 令牌被撤销或过期567 OAuth 令牌被撤销或过期
581 581
582* 运行 `/login` 重新登录582* 运行 `/login` 重新登录
583* 如果在同一会话中重新身份验证后错误返回，请先运行 `/logout` 完全清除存储的令牌，然后运行 `/login`583* 如果在同一会话中重新身份验证后错误返回，请先运行 `/logout` 完全清除存储的令牌，然后运行 `/login`
584* 对于跨启动的重复登录提示，请参阅 [故障排除](/zh-CN/troubleshoot-install#not-logged-in-or-token-expired) 中的系统时钟和 macOS Keychain 检查584* 对于跨启动的重复登录提示，请参阅 [故障排除](/docs/zh-CN/troubleshoot-install#not-logged-in-or-token-expired) 中的系统时钟和 macOS Keychain 检查
585* 对于其他故障，包括 `403 Forbidden` 和 OAuth 浏览器问题，请参阅 [登录和身份验证](/zh-CN/troubleshoot-install#login-and-authentication)585* 对于其他故障，包括 `403 Forbidden` 和 OAuth 浏览器问题，请参阅 [登录和身份验证](/docs/zh-CN/troubleshoot-install#login-and-authentication)
586 586
587<h3 id="login-expired">587<h3 id="login-expired">
588 登录已过期588 登录已过期
589</h3>589</h3>
590 590
591Claude Code 尝试更新您保存的 claude.ai 或 Claude Console 登录，OAuth 服务拒绝了存储的刷新令牌，因此 Claude Code 清除了保存的凭证。之后，每个请求在到达 API 之前都会在本地停止，因为只有 `/login` 可以创建新凭证。{/* min-version: 2.1.206 */}在 v2.1.206 之前，Claude Code 无论如何都会发送请求，使用环境中剩余的任何凭证，然后每个模型都会失败，显示 [所选模型有问题](#theres-an-issue-with-the-selected-model) 或 401 而不是登录提示。591Claude Code 尝试更新您保存的 claude.ai 或 Claude Console 登录，OAuth 服务拒绝了存储的刷新令牌，因此 Claude Code 清除了保存的凭证。之后，每个请求在到达 API 之前都会在本地停止，因为只有 `/login` 可以创建新凭证。在 v2.1.206 之前，Claude Code 无论如何都会发送请求，使用环境中剩余的任何凭证，然后每个模型都会失败，显示 [所选模型有问题](#theres-an-issue-with-the-selected-model) 或 401 而不是登录提示。
592 592
593```text theme={null}593```text theme={null}
594Login expired · Please run /login594Login expired · Please run /login
595```595```
596 596
597在 [非交互模式](/zh-CN/headless) (`-p`) 和 [Agent SDK](/zh-CN/agent-sdk/overview) 中，消息如下所示，结构化错误代码为 `authentication_failed`：597在 [非交互模式](/docs/zh-CN/headless) (`-p`) 和 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 中，消息如下所示，结构化错误代码为 `authentication_failed`：
598 598
599```text theme={null}599```text theme={null}
600Failed to authenticate: OAuth session expired and could not be refreshed600Failed to authenticate: OAuth session expired and could not be refreshed
602 602
603这与 [OAuth 令牌被撤销或过期](#oauth-token-revoked-or-expired) 的状态不同。这些消息报告 API 返回的 401。Claude Code 本身为已失败刷新的登录生成 `Login expired`，因此它不发送请求。603这与 [OAuth 令牌被撤销或过期](#oauth-token-revoked-or-expired) 的状态不同。这些消息报告 API 返回的 401。Claude Code 本身为已失败刷新的登录生成 `Login expired`，因此它不发送请求。
604 604
605使用 API 密钥、[`CLAUDE_CODE_OAUTH_TOKEN`](/zh-CN/env-vars) 或第三方提供商进行身份验证的会话不使用保存的登录，永远不会看到此消息。605使用 API 密钥、[`CLAUDE_CODE_OAUTH_TOKEN`](/docs/zh-CN/env-vars) 或第三方提供商进行身份验证的会话不使用保存的登录，永远不会看到此消息。
606 606
607**应该做什么：**607**应该做什么：**
608 608
609* 运行 `/login` 重新登录。不登录重试会在每个请求上显示相同的消息。609* 运行 `/login` 重新登录。不登录重试会在每个请求上显示相同的消息。
610* 在非交互模式中，在同一环境中运行 `claude`，完成 `/login`，然后重新运行您的命令。对于无法交互式登录的自动化，使用 `ANTHROPIC_API_KEY` 进行身份验证或 [使用 `claude setup-token` 生成长期令牌](/zh-CN/authentication#generate-a-long-lived-token)。610* 在非交互模式中，在同一环境中运行 `claude`，完成 `/login`，然后重新运行您的命令。对于无法交互式登录的自动化，使用 `ANTHROPIC_API_KEY` 进行身份验证或 [使用 `claude setup-token` 生成长期令牌](/docs/zh-CN/authentication#generate-a-long-lived-token)。
611* 如果登录持续失败，请参阅 [登录和身份验证](/zh-CN/troubleshoot-install#login-and-authentication)611* 如果登录持续失败，请参阅 [登录和身份验证](/docs/zh-CN/troubleshoot-install#login-and-authentication)
612 612
613<h3 id="oauth-scope-requirement">613<h3 id="oauth-scope-requirement">
614 OAuth 范围要求614 OAuth 范围要求
628 AWS 凭证已过期或无效628 AWS 凭证已过期或无效
629</h3>629</h3>
630 630
631{/* 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 上，这是这些提供商报告过期安全令牌的方式。631此消息需要 Claude Code v2.1.198 或更高版本，仅当在您的设置文件中设置了 [`awsAuthRefresh`](/docs/zh-CN/amazon-bedrock#advanced-credential-configuration) 时才会出现。您的 AWS 会话令牌已过期或被拒绝，Claude Code 已运行的自动刷新未产生 API 接受的凭证。它出现在来自 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 或 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint) 的 401 上，这是这些提供商报告过期安全令牌的方式。
632 632
633中间的操作提示命名了您的设置中的 `awsAuthRefresh` 命令，因此它会有所不同。稳定的部分是前导的 `AWS credentials expired or invalid`：633中间的操作提示命名了您的设置中的 `awsAuthRefresh` 命令，因此它会有所不同。稳定的部分是前导的 `AWS credentials expired or invalid`：
634 634
641**应该做什么：**641**应该做什么：**
642 642
643* 在另一个终端中运行消息中命名的 `awsAuthRefresh` 命令，例如 `aws sso login --profile myprofile`，完成浏览器登录，然后重试643* 在另一个终端中运行消息中命名的 `awsAuthRefresh` 命令，例如 `aws sso login --profile myprofile`，完成浏览器登录，然后重试
644* 在交互式会话中，运行 `/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)644* 在交互式会话中，运行 `/login`，选择 **3rd-party platform**，然后在 **Using 3rd-party platforms** 下选择 **Claude Platform on AWS · refresh credentials** 以运行相同的命令而无需重启 Claude Code。请参阅 [配置 AWS 凭证](/docs/zh-CN/claude-platform-on-aws#1-configure-aws-credentials)
645* 如果刷新命令成功后错误重复出现，请在同一 shell 和配置文件中使用 `aws sts get-caller-identity` 确认身份在 Claude Code 外部有效645* 如果刷新命令成功后错误重复出现，请在同一 shell 和配置文件中使用 `aws sts get-caller-identity` 确认身份在 Claude Code 外部有效
646 646
647<h3 id="aws-authentication-failed">647<h3 id="aws-authentication-failed">
648 AWS 身份验证失败648 AWS 身份验证失败
649</h3>649</h3>
650 650
651{/* 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。651此消息需要 Claude Code v2.1.198 或更高版本，仅当在您的设置文件中设置了 [`awsAuthRefresh`](/docs/zh-CN/amazon-bedrock#advanced-credential-configuration) 时才会出现。您的 AWS 提供商返回了 403，或 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 返回了 401。
652 652
653Claude Code 无法判断您遇到了哪个原因。Amazon Bedrock 将过期的安全令牌报告为 403，但 403 也是它报告授权拒绝的方式，例如来自缺失 IAM 权限或未为您的账户启用的模型的 `AccessDeniedException`。653Claude Code 无法判断您遇到了哪个原因。Amazon Bedrock 将过期的安全令牌报告为 403，但 403 也是它报告授权拒绝的方式，例如来自缺失 IAM 权限或未为您的账户启用的模型的 `AccessDeniedException`。
654 654
665**应该做什么：**665**应该做什么：**
666 666
667* 运行消息中命名的 `awsAuthRefresh` 命令或 `aws sso login`，以防过期凭证是原因667* 运行消息中命名的 `awsAuthRefresh` 命令或 `aws sso login`，以防过期凭证是原因
668* 如果您的凭证是最新的，请确认 [IAM 配置](/zh-CN/amazon-bedrock#iam-configuration) 中的 IAM 权限已附加到您使用的身份，并且所选模型已为您的账户和区域启用668* 如果您的凭证是最新的，请确认 [IAM 配置](/docs/zh-CN/amazon-bedrock#iam-configuration) 中的 IAM 权限已附加到您使用的身份，并且所选模型已为您的账户和区域启用
669* 运行 `aws sts get-caller-identity` 确认您的请求使用哪个身份；过时的 `AWS_PROFILE` 或默认配置文件是权限不匹配的常见原因669* 运行 `aws sts get-caller-identity` 确认您的请求使用哪个身份；过时的 `AWS_PROFILE` 或默认配置文件是权限不匹配的常见原因
670 670
671<h3 id="aws-default-chain-credential-resolve-timed-out">671<h3 id="aws-default-chain-credential-resolve-timed-out">
672 AWS 默认链凭证解析超时672 AWS 默认链凭证解析超时
673</h3>673</h3>
674 674
675AWS 默认凭证提供商链在 60 秒内未产生凭证，因此 Claude Code 停止了解析并使请求失败。故障是本地凭证解析：请求从未到达 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 或 [Mantle 端点](/zh-CN/amazon-bedrock#use-the-mantle-endpoint)。Claude Code 在此错误浮出之前清除其 [凭证缓存](/zh-CN/amazon-bedrock#credential-caching-and-resolution-timeout) 并重试，因此到您看到它时链已在重复尝试上停滞。675AWS 默认凭证提供商链在 60 秒内未产生凭证，因此 Claude Code 停止了解析并使请求失败。故障是本地凭证解析：请求从未到达 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 或 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)。Claude Code 在此错误浮出之前清除其 [凭证缓存](/docs/zh-CN/amazon-bedrock#credential-caching-and-resolution-timeout) 并重试，因此到您看到它时链已在重复尝试上停滞。
676 676
677```text theme={null}677```text theme={null}
678API Error: AWS default-chain credential resolve timed out678API Error: AWS default-chain credential resolve timed out
679```679```
680 680
681常见原因是 AWS 配置文件中的 `credential_process` 命令等待它无法接收的输入，以及容器或 VM 的实例元数据服务 (IMDS) 从不回答链的探测。{/* min-version: 2.1.207 */}在 v2.1.207 之前，停滞的链使请求无限期等待而不是以此消息失败。681常见原因是 AWS 配置文件中的 `credential_process` 命令等待它无法接收的输入，以及容器或 VM 的实例元数据服务 (IMDS) 从不回答链的探测。在 v2.1.207 之前，停滞的链使请求无限期等待而不是以此消息失败。
682 682
683**应该做什么：**683**应该做什么：**
684 684
685* 在同一 shell 中使用相同的 `AWS_PROFILE` 运行 `aws sts get-caller-identity`。如果它也挂起，请修复配置文件；提示交互式的 `credential_process` 命令是常见原因。685* 在同一 shell 中使用相同的 `AWS_PROFILE` 运行 `aws sts get-caller-identity`。如果它也挂起，请修复配置文件；提示交互式的 `credential_process` 命令是常见原因。
686* 在启动 Claude Code 之前完成登录步骤，例如 `aws sso login --profile myprofile`，以便链从本地 SSO 缓存解析而不是等待浏览器流686* 在启动 Claude Code 之前完成登录步骤，例如 `aws sso login --profile myprofile`，以便链从本地 SSO 缓存解析而不是等待浏览器流
687* 如果您的链运行合法需要超过 60 秒的交互式登录，例如通过 `aws-vault` 等包装器的带 MFA 的 SSO，请使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/zh-CN/env-vars) 以毫秒为单位提高限制687* 如果您的链运行合法需要超过 60 秒的交互式登录，例如通过 `aws-vault` 等包装器的带 MFA 的 SSO，请使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-CN/env-vars) 以毫秒为单位提高限制
688 688
689<h2 id="network-and-connection-errors">689<h2 id="network-and-connection-errors">
690 网络和连接错误690 网络和连接错误
712**应该做什么：**712**应该做什么：**
713 713
714* 通过在同一 shell 中运行 `curl -I https://api.anthropic.com` 来确认您可以到达 API 主机。在 Windows PowerShell 上使用 `curl.exe -I https://api.anthropic.com`，以便不使用内置的 `Invoke-WebRequest` 别名。714* 通过在同一 shell 中运行 `curl -I https://api.anthropic.com` 来确认您可以到达 API 主机。在 Windows PowerShell 上使用 `curl.exe -I https://api.anthropic.com`，以便不使用内置的 `Invoke-WebRequest` 别名。
715* 如果您在企业代理后面，请在启动 Claude Code 之前设置 `HTTPS_PROXY`，并参阅[网络配置](/zh-CN/network-config)715* 如果您在企业代理后面，请在启动 Claude Code 之前设置 `HTTPS_PROXY`，并参阅[网络配置](/docs/zh-CN/network-config)
716* 如果您通过 LLM 网关或中继路由，请将 [`ANTHROPIC_BASE_URL`](/zh-CN/env-vars) 设置为其地址。有关设置，请参阅[将 Claude Code 连接到 LLM 网关](/zh-CN/llm-gateway-connect)。716* 如果您通过 LLM 网关或中继路由，请将 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 设置为其地址。有关设置，请参阅[将 Claude Code 连接到 LLM 网关](/docs/zh-CN/llm-gateway-connect)。
717* 确保您的防火墙允许[网络访问要求](/zh-CN/network-config#network-access-requirements)中列出的主机717* 确保您的防火墙允许[网络访问要求](/docs/zh-CN/network-config#network-access-requirements)中列出的主机
718* 间歇性故障会[自动重试](#automatic-retries)；持续故障指向本地网络问题718* 间歇性故障会[自动重试](#automatic-retries)；持续故障指向本地网络问题
719 719
720如果 `curl` 成功但 Claude Code 仍然失败，原因通常是运行时和网络之间的某些东西，而不是网络本身：720如果 `curl` 成功但 Claude Code 仍然失败，原因通常是运行时和网络之间的某些东西，而不是网络本身：
727 Bedrock 流式响应具有意外的内容类型727 Bedrock 流式响应具有意外的内容类型
728</h3>728</h3>
729 729
730Claude Code 和 [Amazon Bedrock](/zh-CN/amazon-bedrock) 之间的网关或代理正在转换流式响应体或其 `Content-Type` 标头。Amazon Bedrock 将响应流式传输为 `application/vnd.amazon.eventstream`，Claude Code 拒绝报告不同内容类型的成功流式响应，而不是解码它无法读取的响应体。请求不会重试。730Claude Code 和 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 之间的网关或代理正在转换流式响应体或其 `Content-Type` 标头。Amazon Bedrock 将响应流式传输为 `application/vnd.amazon.eventstream`，Claude Code 拒绝报告不同内容类型的成功流式响应，而不是解码它无法读取的响应体。请求不会重试。
731 731
732```text theme={null}732```text theme={null}
733Bedrock streaming response has content-type "text/event-stream"; expected "application/vnd.amazon.eventstream". A gateway or proxy between Claude Code and Bedrock is likely transforming the response body — Bedrock's binary event-stream format must be passed through unmodified. Set CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 to suppress this check while the gateway is being fixed.733Bedrock streaming response has content-type "text/event-stream"; expected "application/vnd.amazon.eventstream". A gateway or proxy between Claude Code and Bedrock is likely transforming the response body — Bedrock's binary event-stream format must be passed through unmodified. Set CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 to suppress this check while the gateway is being fixed.
734```734```
735 735
736{/* min-version: 2.1.208 */}在 v2.1.208 之前，相同的配置错误表现为 `API Error: Truncated event message received`，在整个响应被缓冲后出现。736在 v2.1.208 之前，相同的配置错误表现为 `API Error: Truncated event message received`，在整个响应被缓冲后出现。
737 737
738**应该做什么：**738**应该做什么：**
739 739
740* 配置网关以不修改地传递 `InvokeModelWithResponseStream` 响应体及其 `Content-Type` 标头。将流重新发出为服务器发送事件的中介是常见原因。740* 配置网关以不修改地传递 `InvokeModelWithResponseStream` 响应体及其 `Content-Type` 标头。将流重新发出为服务器发送事件的中介是常见原因。
741* 如果网关仅重写标头并完整传递二进制体，请设置 [`CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1`](/zh-CN/env-vars) 以跳过检查，直到网关被修复。请参阅[网关或代理后的流式错误](/zh-CN/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。741* 如果网关仅重写标头并完整传递二进制体，请设置 [`CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1`](/docs/zh-CN/env-vars) 以跳过检查，直到网关被修复。请参阅[网关或代理后的流式错误](/docs/zh-CN/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。
742 742
743<h3 id="ssl-certificate-errors">743<h3 id="ssl-certificate-errors">
744 SSL 证书错误744 SSL 证书错误
751Unable to connect to API: Self-signed certificate detected751Unable to connect to API: Self-signed certificate detected
752```752```
753 753
754{/* min-version: 2.1.199 */}从 v2.1.199 开始，证书验证失败不会重试，因此此错误在第一次尝试时出现，而不是在完整[重试预算](#automatic-retries)之后。早期版本在显示它之前花费几分钟重试。瞬时 TLS 条件（例如握手超时）仍然会重试。754从 v2.1.199 开始，证书验证失败不会重试，因此此错误在第一次尝试时出现，而不是在完整[重试预算](#automatic-retries)之后。早期版本在显示它之前花费几分钟重试。瞬时 TLS 条件（例如握手超时）仍然会重试。
755 755
756在 `/login` 和启动连接检查期间，使用 OpenSSL 代码和内联修复报告相同的失败：756在 `/login` 和启动连接检查期间，使用 OpenSSL 代码和内联修复报告相同的失败：
757 757
762**应该做什么：**762**应该做什么：**
763 763
764* 导出您组织的 CA 包，并使用 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` 将 Claude Code 指向它764* 导出您组织的 CA 包，并使用 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` 将 Claude Code 指向它
765* 有关完整设置说明，请参阅[网络配置](/zh-CN/network-config#custom-ca-certificates)765* 有关完整设置说明，请参阅[网络配置](/docs/zh-CN/network-config#custom-ca-certificates)
766* 不要设置 `NODE_TLS_REJECT_UNAUTHORIZED=0`，这会完全禁用证书验证766* 不要设置 `NODE_TLS_REJECT_UNAUTHORIZED=0`，这会完全禁用证书验证
767 767
768<h3 id="host-not-allowed-in-a-cloud-session">768<h3 id="host-not-allowed-in-a-cloud-session">
778 778
779您也可能看到与目的地真实证书不匹配的 TLS 证书。云环境通过代理路由出站流量以强制执行网络策略，因此证书不匹配意味着代理终止了连接，而不是目的地。779您也可能看到与目的地真实证书不匹配的 TLS 证书。云环境通过代理路由出站流量以强制执行网络策略，因此证书不匹配意味着代理终止了连接，而不是目的地。
780 780
781这不是客户端网络问题。云会话和[例程](/zh-CN/routines)在沙箱环境内运行，其出站流量被过滤到环境的允许列表。**默认**环境使用**受信任**访问，允许[默认允许列表](/zh-CN/claude-code-on-the-web#default-allowed-domains)中的包注册表、云提供商 API、容器注册表和常见开发域，但阻止其他所有内容。781这不是客户端网络问题。云会话和[例程](/docs/zh-CN/routines)在沙箱环境内运行，其出站流量被过滤到环境的允许列表。**默认**环境使用**受信任**访问，允许[默认允许列表](/docs/zh-CN/claude-code-on-the-web#default-allowed-domains)中的包注册表、云提供商 API、容器注册表和常见开发域，但阻止其他所有内容。
782 782
783**应该做什么：**783**应该做什么：**
784 784
785* 打开例程进行编辑，或启动云会话。选择显示您的环境名称（例如**默认**）的云图标以打开选择器。将鼠标悬停在您的环境上，然后单击设置图标。785* 打开例程进行编辑，或启动云会话。选择显示您的环境名称（例如**默认**）的云图标以打开选择器。将鼠标悬停在您的环境上，然后单击设置图标。
786* 在**更新云环境**对话框中，将**网络访问**从**受信任**更改为**自定义**，然后将被阻止的域添加到**允许的域**。每行输入一个域。选中**也包括常见包管理器的默认列表**以在自定义域旁边保留[默认允许列表](/zh-CN/claude-code-on-the-web#default-allowed-domains)。如果您想要不受限制的访问，请改为选择**完全**。786* 在**更新云环境**对话框中，将**网络访问**从**受信任**更改为**自定义**，然后将被阻止的域添加到**允许的域**。每行输入一个域。选中**也包括常见包管理器的默认列表**以在自定义域旁边保留[默认允许列表](/docs/zh-CN/claude-code-on-the-web#default-allowed-domains)。如果您想要不受限制的访问，请改为选择**完全**。
787* 单击**保存更改**。下一次运行使用更新的允许列表。787* 单击**保存更改**。下一次运行使用更新的允许列表。
788 788
789有关访问级别和默认允许列表，请参阅[网络访问](/zh-CN/claude-code-on-the-web#network-access)。本地 CLI 会话不受此策略影响。789有关访问级别和默认允许列表，请参阅[网络访问](/docs/zh-CN/claude-code-on-the-web#network-access)。本地 CLI 会话不受此策略影响。
790 790
791<h3 id="couldnt-reconnect-to-your-remote-control-session">791<h3 id="couldnt-reconnect-to-your-remote-control-session">
792 无法重新连接到您的 Remote Control 会话792 无法重新连接到您的 Remote Control 会话
796Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.796Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.
797```797```
798 798
799使用 `claude --resume` 或 `claude --continue` 恢复会重新连接到该对话中记录的 [Remote Control](/zh-CN/remote-control) 会话。此消息意味着重新连接因可能是临时的原因（例如网络中断或服务器错误）而失败，因此 Claude Code 无法确认远程会话是否仍然存在。您的本地会话继续运行而不使用 Remote Control。799使用 `claude --resume` 或 `claude --continue` 恢复会重新连接到该对话中记录的 [Remote Control](/docs/zh-CN/remote-control) 会话。此消息意味着重新连接因可能是临时的原因（例如网络中断或服务器错误）而失败，因此 Claude Code 无法确认远程会话是否仍然存在。您的本地会话继续运行而不使用 Remote Control。
800 800
801**应该做什么：**801**应该做什么：**
802 802
803* 运行 `/remote-control` 以重试连接803* 运行 `/remote-control` 以重试连接
804* 启动 Claude Code 而不使用 `--resume` 以创建新的 Remote Control 会话804* 启动 Claude Code 而不使用 `--resume` 以创建新的 Remote Control 会话
805* 有关其他 Remote Control 启动消息，请参阅[排查 Remote Control 故障](/zh-CN/remote-control#troubleshooting)805* 有关其他 Remote Control 启动消息，请参阅[排查 Remote Control 故障](/docs/zh-CN/remote-control#troubleshooting)
806 806
807当服务器确认前一个会话不再存在时，您不会看到此消息；Claude Code 在这种情况下会创建一个新的会话。{/* min-version: 2.1.200 */}在 v2.1.200 之前，任何重新连接失败都会创建一个新的 Remote Control 会话，这在 claude.ai/code 的会话列表中留下了额外的会话。807当服务器确认前一个会话不再存在时，您不会看到此消息；Claude Code 在这种情况下会创建一个新的会话。在 v2.1.200 之前，任何重新连接失败都会创建一个新的 Remote Control 会话，这在 claude.ai/code 的会话列表中留下了额外的会话。
808 808
809<h2 id="request-errors">809<h2 id="request-errors">
810 请求错误810 请求错误
827* 运行 `/compact` 来总结早期的回合并释放空间，或运行 `/clear` 来重新开始827* 运行 `/compact` 来总结早期的回合并释放空间，或运行 `/clear` 来重新开始
828* 运行 `/context` 来查看消耗窗口的内容分解：系统提示、工具、内存文件和消息828* 运行 `/context` 来查看消耗窗口的内容分解：系统提示、工具、内存文件和消息
829* 使用 `/mcp disable <name>` 禁用您未使用的 MCP 服务器，以从上下文中移除其工具定义829* 使用 `/mcp disable <name>` 禁用您未使用的 MCP 服务器，以从上下文中移除其工具定义
830* 修剪大型 `CLAUDE.md` 内存文件，或将说明移到[路径范围规则](/zh-CN/memory#path-specific-rules)中，这些规则仅在相关时加载830* 修剪大型 `CLAUDE.md` 内存文件，或将说明移到[路径范围规则](/docs/zh-CN/memory#path-specific-rules)中，这些规则仅在相关时加载
831* 子代理从父会话继承每个 MCP 工具定义，这可能会在第一个回合之前填满它们的上下文窗口。在生成子代理之前禁用您未使用的 MCP 服务器。831* 子代理从父会话继承每个 MCP 工具定义，这可能会在第一个回合之前填满它们的上下文窗口。在生成子代理之前禁用您未使用的 MCP 服务器。
832* 自动压缩默认启用，通常可以防止此错误。如果您设置了 [`DISABLE_AUTO_COMPACT`](/zh-CN/env-vars)，请重新启用它或在窗口填满之前手动运行 `/compact`。832* 自动压缩默认启用，通常可以防止此错误。如果您设置了 [`DISABLE_AUTO_COMPACT`](/docs/zh-CN/env-vars)，请重新启用它或在窗口填满之前手动运行 `/compact`。
833 833
834请参阅[探索上下文窗口](/zh-CN/context-window)以获得上下文如何填充的交互式视图。834请参阅[探索上下文窗口](/docs/zh-CN/context-window)以获得上下文如何填充的交互式视图。
835 835
836<h3 id="error-during-compaction-conversation-too-long">836<h3 id="error-during-compaction-conversation-too-long">
837 Error during compaction: Conversation too long837 Error during compaction: Conversation too long
879API Error: 400 ... image dimensions exceed max allowed size879API Error: 400 ... image dimensions exceed max allowed size
880```880```
881 881
882{/* min-version: 2.1.142 */}Claude Code 将无法处理的图像替换为文本占位符并重试，因此后续消息成功。在 2.1.142 之前的版本中，粘贴的图像可能会保留在对话中，并在后续的每条消息上重复相同的错误。要在这些版本上恢复，请按 Esc 两次并回退到添加图像的回合之前。882Claude Code 将无法处理的图像替换为文本占位符并重试，因此后续消息成功。在 2.1.142 之前的版本中，粘贴的图像可能会保留在对话中，并在后续的每条消息上重复相同的错误。要在这些版本上恢复，请按 Esc 两次并回退到添加图像的回合之前。
883 883
884**应该做什么：**884**应该做什么：**
885 885
939 939
940**应该做什么：**940**应该做什么：**
941 941
942* 配置您的网关以转发 `anthropic-beta` 头。请参阅[功能传递](/zh-CN/llm-gateway-protocol#feature-pass-through)了解网关必须转发的内容。942* 配置您的网关以转发 `anthropic-beta` 头。请参阅[功能传递](/docs/zh-CN/llm-gateway-protocol#feature-pass-through)了解网关必须转发的内容。
943* 作为备选方案，在启动前设置 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/zh-CN/env-vars)。这会禁用需要测试版头的功能，以便请求通过无法转发它的网关成功。943* 作为备选方案，在启动前设置 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/zh-CN/env-vars)。这会禁用需要测试版头的功能，以便请求通过无法转发它的网关成功。
944 944
945<h3 id="theres-an-issue-with-the-selected-model">945<h3 id="theres-an-issue-with-the-selected-model">
946 There's an issue with the selected model946 There's an issue with the selected model
955**应该做什么：**955**应该做什么：**
956 956
957* **交互式 CLI**：运行 `/model` 从您账户可用的模型中选择。957* **交互式 CLI**：运行 `/model` 从您账户可用的模型中选择。
958* **非交互模式 (`-p`)**：使用有效的别名或 ID 传递 `--model`，或设置 [`ANTHROPIC_MODEL`](/zh-CN/env-vars)。错误文本在此表面上显示 `Run --model`。958* **非交互模式 (`-p`)**：使用有效的别名或 ID 传递 `--model`，或设置 [`ANTHROPIC_MODEL`](/docs/zh-CN/env-vars)。错误文本在此表面上显示 `Run --model`。
959* **Agent SDK**：错误文本省略提示，因为模型是以编程方式设置的。在 TypeScript 中设置 [`Options` 上的 `model`](/zh-CN/agent-sdk/typescript#options) 或在 Python 中设置 [`ClaudeAgentOptions(model=...)`](/zh-CN/agent-sdk/python#claudeagentoptions)，并处理结构化的 `model_not_found` 错误以显示您自己的重试或模型选择器。959* **Agent SDK**：错误文本省略提示，因为模型是以编程方式设置的。在 TypeScript 中设置 [`Options` 上的 `model`](/docs/zh-CN/agent-sdk/typescript#options) 或在 Python 中设置 [`ClaudeAgentOptions(model=...)`](/docs/zh-CN/agent-sdk/python#claudeagentoptions)，并处理结构化的 `model_not_found` 错误以显示您自己的重试或模型选择器。
960* 使用别名（如 `sonnet` 或 `opus`）而不是完整的版本化 ID。别名解析为维护的默认值，因此不会过时。请参阅[模型配置](/zh-CN/model-config)。960* 使用别名（如 `sonnet` 或 `opus`）而不是完整的版本化 ID。别名解析为维护的默认值，因此不会过时。请参阅[模型配置](/docs/zh-CN/model-config)。
961* 如果 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 会回退到您的账户默认值。961* 如果 CLI 中一直返回错误的模型，则某处设置了过时的 ID。按[优先级顺序](/docs/zh-CN/model-config#setting-your-model)检查：`--model` 标志、`ANTHROPIC_MODEL` 环境变量，然后是 `.claude/settings.local.json` 中的 `model` 字段、您项目的 `.claude/settings.json` 和 `~/.claude/settings.json`。删除过时的值，Claude Code 会回退到您的账户默认值。
962* {/* min-version: 2.1.206 */}Claude Code 将过期的 claude.ai 登录报告为[登录已过期](#login-expired)，而不是此错误。在 v2.1.206 之前，无法再刷新的过期登录在每个模型上都失败，出现此错误；如果您在较旧版本上看到这个，请运行 `/login`。962* Claude Code 将过期的 claude.ai 登录报告为[登录已过期](#login-expired)，而不是此错误。在 v2.1.206 之前，无法再刷新的过期登录在每个模型上都失败，出现此错误；如果您在较旧版本上看到这个，请运行 `/login`。
963* 对于 Google Cloud 的 Agent Platform 部署，请参阅 [Google Cloud 的 Agent Platform 故障排除](/zh-CN/google-vertex-ai#troubleshooting)。963* 对于 Google Cloud 的 Agent Platform 部署，请参阅 [Google Cloud 的 Agent Platform 故障排除](/docs/zh-CN/google-vertex-ai#troubleshooting)。
964 964
965<h3 id="model-is-not-a-recognized-model-id">965<h3 id="model-is-not-a-recognized-model-id">
966 Model is not a recognized model id966 Model is not a recognized model id
974 974
975尾部提示命名最接近的匹配别名或模型 ID。当没有足够接近的内容时，它读作 `Run /model to see available models.`。975尾部提示命名最接近的匹配别名或模型 ID。当没有足够接近的内容时，它读作 `Run /model to see available models.`。
976 976
977Claude Code 在请求切换时在本地生成此错误，在发出任何 API 请求之前。它适用于通过 [Agent SDK](/zh-CN/agent-sdk/typescript) `setModel()` 方法或为您运行 Claude Code CLI 的应用程序（如 [Desktop app](/zh-CN/desktop)）设置模型的情况。977Claude Code 在请求切换时在本地生成此错误，在发出任何 API 请求之前。它适用于通过 [Agent SDK](/docs/zh-CN/agent-sdk/typescript) `setModel()` 方法或为您运行 Claude Code CLI 的应用程序（如 [Desktop app](/docs/zh-CN/desktop)）设置模型的情况。
978 978
979**应该做什么：**979**应该做什么：**
980 980
981* 运行不带参数的 `/model` 来打开选择器并从您账户可用的模型中选择，然后传递那里显示的别名或 ID981* 运行不带参数的 `/model` 来打开选择器并从您账户可用的模型中选择，然后传递那里显示的别名或 ID
982* 如果您使用了较新 Claude Code 版本支持的别名，运行 `claude update`。以 `claude-` 开头的完整 ID 即使模型比您的 Claude Code 版本更新，也会通过此检查，因此不需要升级。982* 如果您使用了较新 Claude Code 版本支持的别名，运行 `claude update`。以 `claude-` 开头的完整 ID 即使模型比您的 Claude Code 版本更新，也会通过此检查，因此不需要升级。
983* v2.1.200 之前保存的模型不会被此检查修复。如果过时的值一直出现，请从[所选模型有问题](#theres-an-issue-with-the-selected-model)下列出的位置中删除它。983* v2.1.200 之前保存的模型不会被此检查修复。如果过时的值一直出现，请从[所选模型有问题](#theres-an-issue-with-the-selected-model)下列出的位置中删除它。
984* 检查仅在 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 接受任何字符串并将其传递。984* 检查仅在 Anthropic API 上运行。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和 [LLM 网关](/docs/zh-CN/llm-gateway)后面或自定义 `ANTHROPIC_BASE_URL`，您的提供商或网关定义模型名称，因此 Claude Code 接受任何字符串并将其传递。
985 985
986<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">986<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">
987 Claude Opus is not available with the Claude Pro plan987 Claude Opus is not available with the Claude Pro plan
1003 Model is restricted by your organization's settings1003 Model is restricted by your organization's settings
1004</h3>1004</h3>
1005 1005
1006您的组织管理员在 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.`，会话保持其当前模型。1006您的组织管理员在 claude.ai 管理控制台中禁用了此模型，或者它被托管设置中的 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 允许列表排除。当受限模型使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 设置设置时，Claude Code 替换允许的模型并继续。为受限模型键入 `/model <name>` 会被拒绝，显示 `Run /model to choose a different model.`，会话保持其当前模型。
1007 1007
1008```text theme={null}1008```text theme={null}
1009Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.1009Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.
1010```1010```
1011 1011
1012Claude 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 之前，族别名基于其最新版本单独替换或拒绝，即使同一族的较旧版本被允许。1012Claude Code 将模型族别名（`opus`、`sonnet`、`haiku` 或 `fable` 之一）视为对该族的请求，而不是对其最新版本的请求。在 Anthropic API 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 上，受限的族别名解析为您的组织和 `availableModels` 允许列表允许的族的最新版本，替换通知命名该版本。Claude Code 仅当族的每个版本都受限时才拒绝 `/model <alias>`。在 v2.1.205 之前，族别名基于其最新版本单独替换或拒绝，即使同一族的较旧版本被允许。
1013 1013
1014**应该做什么：**1014**应该做什么：**
1015 1015
1016* 运行 `/model` 从您的组织允许的模型中选择。受限模型从选择器中隐藏。1016* 运行 `/model` 从您的组织允许的模型中选择。受限模型从选择器中隐藏。
1017* 如果受限模型在 `--model`、`ANTHROPIC_MODEL` 或设置文件的 `model` 字段中设置，删除或更新该值，以便通知不会在每次启动时重复出现1017* 如果受限模型在 `--model`、`ANTHROPIC_MODEL` 或设置文件的 `model` 字段中设置，删除或更新该值，以便通知不会在每次启动时重复出现
1018* 如果您需要访问受限模型，请要求您的组织管理员启用它。请参阅[组织模型限制](/zh-CN/model-config#organization-model-restrictions)。1018* 如果您需要访问受限模型，请要求您的组织管理员启用它。请参阅[组织模型限制](/docs/zh-CN/model-config#organization-model-restrictions)。
1019 1019
1020<h3 id="thinking-type-enabled-is-not-supported-for-this-model">1020<h3 id="thinking-type-enabled-is-not-supported-for-this-model">
1021 thinking.type.enabled is not supported for this model1021 thinking.type.enabled is not supported for this model
1031 1031
1032* 运行 `claude update` 并重启 Claude Code。Opus 4.7 需要 v2.1.111 或更高版本。Opus 4.8 需要 v2.1.154 或更高版本。Sonnet 5 需要 v2.1.197 或更高版本1032* 运行 `claude update` 并重启 Claude Code。Opus 4.7 需要 v2.1.111 或更高版本。Opus 4.8 需要 v2.1.154 或更高版本。Sonnet 5 需要 v2.1.197 或更高版本
1033* 如果您无法升级，运行 `/model` 并改为选择 Opus 4.6 或 Sonnet 4.61033* 如果您无法升级，运行 `/model` 并改为选择 Opus 4.6 或 Sonnet 4.6
1034* {/* 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 或更高版本1034* 如果您在 [Agent SDK](/docs/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 或更高版本
1035 1035
1036<h3 id="thinking-budget-exceeds-output-limit">1036<h3 id="thinking-budget-exceeds-output-limit">
1037 Thinking budget exceeds output limit1037 Thinking budget exceeds output limit
1043API Error: 400 ... max_tokens must be greater than thinking.budget_tokens1043API Error: 400 ... max_tokens must be greater than thinking.budget_tokens
1044```1044```
1045 1045
1046Claude Code 在 Anthropic API 上自动调整这些值。您通常在 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上看到此错误，当 [`MAX_THINKING_TOKENS`](/zh-CN/env-vars) 设置高于提供商的输出限制时，或当计划模式提高思考预算时。1046Claude Code 在 Anthropic API 上自动调整这些值。您通常在 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上看到此错误，当 [`MAX_THINKING_TOKENS`](/docs/zh-CN/env-vars) 设置高于提供商的输出限制时，或当计划模式提高思考预算时。
1047 1047
1048**应该做什么：**1048**应该做什么：**
1049 1049
1050* 降低 `MAX_THINKING_TOKENS`，或将 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/zh-CN/env-vars) 提高到思考预算之上1050* 降低 `MAX_THINKING_TOKENS`，或将 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/zh-CN/env-vars) 提高到思考预算之上
1051* 请参阅[扩展思考](/zh-CN/model-config#extended-thinking)了解预算如何与输出长度相互作用1051* 请参阅[扩展思考](/docs/zh-CN/model-config#extended-thinking)了解预算如何与输出长度相互作用
1052 1052
1053<h3 id="tool-use-or-thinking-block-mismatch">1053<h3 id="tool-use-or-thinking-block-mismatch">
1054 Tool use or thinking block mismatch1054 Tool use or thinking block mismatch
1066 1066
1067**应该做什么：**1067**应该做什么：**
1068 1068
1069* {/* max-version: 2.1.155 */}如果您使用的是 Opus 4.7 或 Opus 4.8，请先运行 `claude update`。v2.1.156 之前的版本可能在正常工具使用期间触发此错误，`/rewind` 不会清除它。1069* 如果您使用的是 Opus 4.7 或 Opus 4.8，请先运行 `claude update`。v2.1.156 之前的版本可能在正常工具使用期间触发此错误，`/rewind` 不会清除它。
1070* 运行 `/rewind` 或按 Esc 两次，回退到损坏回合之前的检查点并从那里继续。请参阅[检查点](/zh-CN/checkpointing)了解如何创建和恢复检查点。1070* 运行 `/rewind` 或按 Esc 两次，回退到损坏回合之前的检查点并从那里继续。请参阅[检查点](/docs/zh-CN/checkpointing)了解如何创建和恢复检查点。
1071 1071
1072<h3 id="usage-policy-refusal">1072<h3 id="usage-policy-refusal">
1073 Usage Policy refusal1073 Usage Policy refusal
1079API 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.1079API 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.
1080```1080```
1081 1081
1082检查评估完整对话，而不仅仅是您的最新提示，因此在同一会话中发送新消息通常会重新触发相同的拒绝。在使用 `--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)。1082检查评估完整对话，而不仅仅是您的最新提示，因此在同一会话中发送新消息通常会重新触发相同的拒绝。在使用 `--continue` 或 `--resume` 退出并重新打开会话后也是如此，因为磁盘上的记录仍然包含触发内容。在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上，此消息也涵盖模型的安全措施标记为网络安全主题的请求。请参阅[安全措施标记了网络安全主题](#safety-measures-flagged-a-cybersecurity-topic)。
1083 1083
1084**应该做什么：**1084**应该做什么：**
1085 1085
1086* 按 Esc 两次或运行 `/rewind` 回退到触发拒绝的回合之前的检查点，然后重新表述或采取不同的方法。请参阅[检查点](/zh-CN/checkpointing)。1086* 按 Esc 两次或运行 `/rewind` 回退到触发拒绝的回合之前的检查点，然后重新表述或采取不同的方法。请参阅[检查点](/docs/zh-CN/checkpointing)。
1087* 如果您无法识别哪个回合导致了它，运行 `/clear` 在同一项目中启动新对话。您之前的对话保留在磁盘上，在 `/resume` 中仍然可用。1087* 如果您无法识别哪个回合导致了它，运行 `/clear` 在同一项目中启动新对话。您之前的对话保留在磁盘上，在 `/resume` 中仍然可用。
1088* 在[非交互模式](/zh-CN/headless)(`-p`) 中，其中 rewind 不可用，在没有 `--continue` 的新会话中使用重新表述的提示重试。政策检查因模型而异，因此使用 `--model` 切换到不同的模型也可能在某些情况下解决拒绝。1088* 在[非交互模式](/docs/zh-CN/headless)(`-p`) 中，其中 rewind 不可用，在没有 `--continue` 的新会话中使用重新表述的提示重试。政策检查因模型而异，因此使用 `--model` 切换到不同的模型也可能在某些情况下解决拒绝。
1089 1089
1090<h3 id="safety-measures-flagged-a-cybersecurity-topic">1090<h3 id="safety-measures-flagged-a-cybersecurity-topic">
1091 Safety measures flagged a cybersecurity topic1091 Safety measures flagged a cybersecurity topic
1103 1103
1104您看到的内容取决于您的提供商和模式：1104您看到的内容取决于您的提供商和模式：
1105 1105
1106* 在 [Amazon Bedrock](/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/zh-CN/microsoft-foundry) 上，网络安全标志会产生[使用政策拒绝](#usage-policy-refusal)消息。1106* 在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上，网络安全标志会产生[使用政策拒绝](#usage-policy-refusal)消息。
1107* [非交互模式](/zh-CN/headless)省略 `/feedback` 句子。1107* [非交互模式](/docs/zh-CN/headless)省略 `/feedback` 句子。
1108 1108
1109{/* 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:` 后跟豁免表单链接。1109在 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:` 后跟豁免表单链接。
1110 1110
1111**应该做什么：**1111**应该做什么：**
1112 1112
1113* 如果您的工作需要此内容，请通过[网络验证计划](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)申请访问权限1113* 如果您的工作需要此内容，请通过[网络验证计划](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)申请访问权限
1114* 如果您的请求不是关于网络安全主题，运行 `/feedback` 来报告误报1114* 如果您的请求不是关于网络安全主题，运行 `/feedback` 来报告误报
1115* 要在同一会话中继续工作，按 Esc 两次或运行 `/rewind` 回退到触发标志的回合之前的检查点，然后采取不同的方法。请参阅[检查点](/zh-CN/checkpointing)。1115* 要在同一会话中继续工作，按 Esc 两次或运行 `/rewind` 回退到触发标志的回合之前的检查点，然后采取不同的方法。请参阅[检查点](/docs/zh-CN/checkpointing)。
1116 1116
1117<h2 id="installation-errors">1117<h2 id="installation-errors">
1118 安装错误1118 安装错误
1119</h2>1119</h2>
1120 1120
1121这些错误在安装或更新 Claude Code 时出现，来自[安装脚本](/zh-CN/setup#install-claude-code)、`claude install` 或 `claude update`。对于设置期间的 `command not found`、PATH、权限和 TLS 问题，请参阅[排查安装和登录问题](/zh-CN/troubleshoot-install)。1121这些错误在安装或更新 Claude Code 时出现，来自[安装脚本](/docs/zh-CN/setup#install-claude-code)、`claude install` 或 `claude update`。对于设置期间的 `command not found`、PATH、权限和 TLS 问题，请参阅[排查安装和登录问题](/docs/zh-CN/troubleshoot-install)。
1122 1122
1123<h3 id="installation-was-killed-before-it-could-finish">1123<h3 id="installation-was-killed-before-it-could-finish">
1124 安装在完成前被中止1124 安装在完成前被中止
1136**应该做什么：**1136**应该做什么：**
1137 1137
1138* 停止其他进程以释放内存，然后重新运行安装程序1138* 停止其他进程以释放内存，然后重新运行安装程序
1139* 添加交换空间或移至更大的实例。有关交换文件命令，请参阅[在低内存 Linux 服务器上安装被中止](/zh-CN/troubleshoot-install#install-killed-on-low-memory-linux-servers)。1139* 添加交换空间或移至更大的实例。有关交换文件命令，请参阅[在低内存 Linux 服务器上安装被中止](/docs/zh-CN/troubleshoot-install#install-killed-on-low-memory-linux-servers)。
1140 1140
1141<h3 id="the-connection-dropped-while-downloading-the-update">1141<h3 id="the-connection-dropped-while-downloading-the-update">
1142 下载更新时连接断开1142 下载更新时连接断开
1143</h3>1143</h3>
1144 1144
1145在 `claude install`、`claude update` 或[自动更新程序](/zh-CN/setup#auto-updates)获取 Claude Code 二进制文件时，与下载服务器的连接关闭，重试未能恢复。当连接断开、传输停滞或下载的文件未通过校验和时，Claude Code 会重试下载，总共最多尝试三次。已完成的 HTTP 错误（例如 404）不会重试，因为服务器已经响应。{/* min-version: 2.1.202 */}在 v2.1.202 之前，单个断开的连接会立即导致下载失败，显示裸错误 `aborted`，而不是重试。1145在 `claude install`、`claude update` 或[自动更新程序](/docs/zh-CN/setup#auto-updates)获取 Claude Code 二进制文件时，与下载服务器的连接关闭，重试未能恢复。当连接断开、传输停滞或下载的文件未通过校验和时，Claude Code 会重试下载，总共最多尝试三次。已完成的 HTTP 错误（例如 404）不会重试，因为服务器已经响应。在 v2.1.202 之前，单个断开的连接会立即导致下载失败，显示裸错误 `aborted`，而不是重试。
1146 1146
1147```text theme={null}1147```text theme={null}
1148The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.1148The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.
1157**应该做什么：**1157**应该做什么：**
1158 1158
1159* 再次运行 `claude update`。在网络状况良好的情况下，下载通常在下次运行时成功。对于超时消息，从更快或限制较少的网络再次运行它。1159* 再次运行 `claude update`。在网络状况良好的情况下，下载通常在下次运行时成功。对于超时消息，从更快或限制较少的网络再次运行它。
1160* 如果您的网络需要代理，请在运行安装程序或 `claude update` 之前设置 `HTTPS_PROXY`。请参阅[检查网络连接](/zh-CN/troubleshoot-install#check-network-connectivity)。1160* 如果您的网络需要代理，请在运行安装程序或 `claude update` 之前设置 `HTTPS_PROXY`。请参阅[检查网络连接](/docs/zh-CN/troubleshoot-install#check-network-connectivity)。
1161* 如果公司代理持续关闭传输，请要求您的网络团队允许从 `downloads.claude.ai` 进行完整下载。请参阅[网络访问要求](/zh-CN/network-config#network-access-requirements)。1161* 如果公司代理持续关闭传输，请要求您的网络团队允许从 `downloads.claude.ai` 进行完整下载。请参阅[网络访问要求](/docs/zh-CN/network-config#network-access-requirements)。
1162* 从您的 shell 运行 `claude doctor` 以进行安装诊断1162* 从您的 shell 运行 `claude doctor` 以进行安装诊断
1163 1163
1164<h2 id="command-line-errors">1164<h2 id="command-line-errors">
1171 \--bg 和 --print 之间的冲突1171 \--bg 和 --print 之间的冲突
1172</h3>1172</h3>
1173 1173
1174此消息需要 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 之前，此组合会静默创建一个永远无法附加的后台作业。1174此消息需要 Claude Code v2.1.198 或更高版本。您在同一个 `claude` 调用中将 `--bg` 与 `-p` 或 `--print` 结合使用。`--bg` 启动一个[后台会话](/docs/zh-CN/agent-view#from-your-shell)，您稍后可以使用 `claude agents` 附加到该会话，而 `--print` 以[非交互方式](/docs/zh-CN/headless)运行，永远不会启动 `claude agents` 附加到的交互会话。在 v2.1.198 之前，此组合会静默创建一个永远无法附加的后台作业。
1175 1175
1176```text theme={null}1176```text theme={null}
1177--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.1177--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.
1179 1179
1180**应该怎么做：**1180**应该怎么做：**
1181 1181
1182* 删除 `-p` 或 `--print`。`--bg` 将提示作为其位置参数，所以 `claude --bg "<task>"` 是完整的命令。请参阅[从您的 shell 分派新代理](/zh-CN/agent-view#from-your-shell)。1182* 删除 `-p` 或 `--print`。`--bg` 将提示作为其位置参数，所以 `claude --bg "<task>"` 是完整的命令。请参阅[从您的 shell 分派新代理](/docs/zh-CN/agent-view#from-your-shell)。
1183* 要以非交互方式运行提示并打印结果而不是创建后台会话，请删除 `--bg` 并运行 `claude -p "<task>"`1183* 要以非交互方式运行提示并打印结果而不是创建后台会话，请删除 `--bg` 并运行 `claude -p "<task>"`
1184 1184
1185<h3 id="the-json-schema-value-is-not-a-valid-json-schema">1185<h3 id="the-json-schema-value-is-not-a-valid-json-schema">
1186 \--json-schema 值不是有效的 JSON Schema1186 \--json-schema 值不是有效的 JSON Schema
1187</h3>1187</h3>
1188 1188
1189您在[非交互模式](/zh-CN/headless#get-structured-output)中传递给 [`--json-schema`](/zh-CN/cli-reference#cli-flags) 的架构未能通过 JSON Schema 编译，因此 `claude` 以代码 1 退出，而不是运行提示。在 v2.1.205 之前，无效的架构会产生无结构的输出且没有错误，任何使用 `format` 关键字的架构都被视为无效。1189您在[非交互模式](/docs/zh-CN/headless#get-structured-output)中传递给 [`--json-schema`](/docs/zh-CN/cli-reference#cli-flags) 的架构未能通过 JSON Schema 编译，因此 `claude` 以代码 1 退出，而不是运行提示。在 v2.1.205 之前，无效的架构会产生无结构的输出且没有错误，任何使用 `format` 关键字的架构都被视为无效。
1190 1190
1191```text theme={null}1191```text theme={null}
1192Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values1192Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values
1200 1200
1201* 修复诊断命名的架构部分，然后重新运行命令1201* 修复诊断命名的架构部分，然后重新运行命令
1202* 如果诊断是 `schema too large`，请减少架构的嵌套和 `$ref` 重用1202* 如果诊断是 `schema too large`，请减少架构的嵌套和 `$ref` 重用
1203* 请参阅[获取结构化输出](/zh-CN/headless#get-structured-output)以获取有效的架构和命令1203* 请参阅[获取结构化输出](/docs/zh-CN/headless#get-structured-output)以获取有效的架构和命令
1204 1204
1205<h3 id="could-not-import-a-server-from-claude-desktop">1205<h3 id="could-not-import-a-server-from-claude-desktop">
1206 无法从 Claude Desktop 导入服务器1206 无法从 Claude Desktop 导入服务器
1212Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.1212Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.
1213```1213```
1214 1214
1215服务器名称后面的文本是原因。最常见的是名称检查：Claude Desktop 允许服务器名称中的字符（例如空格和句号），而 `claude mcp` 仅限于字母、数字、连字符和下划线。其他原因包括未通过验证的服务器配置和被您组织的 [MCP 策略](/zh-CN/managed-mcp)阻止的服务器。1215服务器名称后面的文本是原因。最常见的是名称检查：Claude Desktop 允许服务器名称中的字符（例如空格和句号），而 `claude mcp` 仅限于字母、数字、连字符和下划线。其他原因包括未通过验证的服务器配置和被您组织的 [MCP 策略](/docs/zh-CN/managed-mcp)阻止的服务器。
1216 1216
1217**应该怎么做：**1217**应该怎么做：**
1218 1218
1219* 在 `claude_desktop_config.json` 中重命名服务器，仅使用字母、数字、连字符和下划线，然后再次运行 `claude mcp add-from-claude-desktop`1219* 在 `claude_desktop_config.json` 中重命名服务器，仅使用字母、数字、连字符和下划线，然后再次运行 `claude mcp add-from-claude-desktop`
1220* 使用 `claude mcp add` 或 `claude mcp add-json` 在有效名称下直接添加该服务器。请参阅[从 Claude Desktop 导入 MCP 服务器](/zh-CN/mcp#import-mcp-servers-from-claude-desktop)。1220* 使用 `claude mcp add` 或 `claude mcp add-json` 在有效名称下直接添加该服务器。请参阅[从 Claude Desktop 导入 MCP 服务器](/docs/zh-CN/mcp#import-mcp-servers-from-claude-desktop)。
1221 1221
1222<h3 id="mcp-permission-prompt-tool-not-found">1222<h3 id="mcp-permission-prompt-tool-not-found">
1223 找不到 MCP 权限提示工具1223 找不到 MCP 权限提示工具
1224</h3>1224</h3>
1225 1225
1226您传递给 [`--permission-prompt-tool`](/zh-CN/cli-reference#cli-flags) 的工具在运行首次需要权限决定时不在连接的 MCP 工具中，原因可能是其服务器从未连接，或者没有连接的服务器公开该名称的工具。Claude Code 仍然发送您的提示：[非交互](/zh-CN/headless)运行在第一个需要批准的工具调用时以此错误和退出代码 1 退出，因此即使请求已发出，它也不会产生答案。在第一个提示之前，Claude Code 会等待最多由 [`MCP_TIMEOUT`](/zh-CN/env-vars) 设置的每个服务器连接超时 30 秒，以便该服务器连接。{/* min-version: 2.1.206 */}在 v2.1.206 之前，启动不会等待服务器完成连接，因此启动缓慢但健康的服务器也会产生此错误。1226您传递给 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 的工具在运行首次需要权限决定时不在连接的 MCP 工具中，原因可能是其服务器从未连接，或者没有连接的服务器公开该名称的工具。Claude Code 仍然发送您的提示：[非交互](/docs/zh-CN/headless)运行在第一个需要批准的工具调用时以此错误和退出代码 1 退出，因此即使请求已发出，它也不会产生答案。在第一个提示之前，Claude Code 会等待最多由 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars) 设置的每个服务器连接超时 30 秒，以便该服务器连接。在 v2.1.206 之前，启动不会等待服务器完成连接，因此启动缓慢但健康的服务器也会产生此错误。
1227 1227
1228```text theme={null}1228```text theme={null}
1229Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none1229Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none
1235 1235
1236* 检查服务器是否启动并保持连接：在同一目录中运行 `claude mcp list`，并确认服务器列为已连接1236* 检查服务器是否启动并保持连接：在同一目录中运行 `claude mcp list`，并确认服务器列为已连接
1237* 确认工具名称与服务器公开的 `mcp__<server>__<tool>` 名称匹配1237* 确认工具名称与服务器公开的 `mcp__<server>__<tool>` 名称匹配
1238* 如果服务器需要超过 30 秒才能启动，请提高 [`MCP_TIMEOUT`](/zh-CN/env-vars)1238* 如果服务器需要超过 30 秒才能启动，请提高 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars)
1239 1239
1240<h2 id="plugin-errors">1240<h2 id="plugin-errors">
1241 插件错误1241 插件错误
1242</h2>1242</h2>
1243 1243
1244这些错误来自[插件](/zh-CN/plugins)和[marketplace](/zh-CN/plugin-marketplaces)配置。对于不会产生本页面上的消息之一的插件问题，例如无法加载的 marketplace URL 或已安装但不显示的插件，请参阅[插件故障排除](/zh-CN/discover-plugins#troubleshooting)。1244这些错误来自[插件](/docs/zh-CN/plugins)和[marketplace](/docs/zh-CN/plugin-marketplaces)配置。对于不会产生本页面上的消息之一的插件问题，例如无法加载的 marketplace URL 或已安装但不显示的插件，请参阅[插件故障排除](/docs/zh-CN/discover-plugins#troubleshooting)。
1245 1245
1246<h3 id="marketplace-is-registered-from-an-untrusted-source">1246<h3 id="marketplace-is-registered-from-an-untrusted-source">
1247 Marketplace 从不受信任的源注册1247 Marketplace 从不受信任的源注册
1248</h3>1248</h3>
1249 1249
1250marketplace 以[为官方 Anthropic marketplace 保留的名称](/zh-CN/plugin-marketplaces#marketplace-schema)注册，但其注册源不是 `anthropics` GitHub 存储库。Claude Code 每次加载或刷新 marketplace 时都会重新检查保留的名称，因此 marketplace 和从中安装的插件停止加载。在 v2.1.205 之前，仅在添加 marketplace 时检查名称，因此在其名称被保留之前注册的条目继续加载。1250marketplace 以[为官方 Anthropic marketplace 保留的名称](/docs/zh-CN/plugin-marketplaces#marketplace-schema)注册，但其注册源不是 `anthropics` GitHub 存储库。Claude Code 每次加载或刷新 marketplace 时都会重新检查保留的名称，因此 marketplace 和从中安装的插件停止加载。在 v2.1.205 之前，仅在添加 marketplace 时检查名称，因此在其名称被保留之前注册的条目继续加载。
1251 1251
1252```text theme={null}1252```text theme={null}
1253Marketplace "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.1253Marketplace "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.
1257 1257
1258* 运行 `claude plugin marketplace remove <name>`，然后从官方 `github.com/anthropics` 存储库重新添加 marketplace1258* 运行 `claude plugin marketplace remove <name>`，然后从官方 `github.com/anthropics` 存储库重新添加 marketplace
1259* 如果您发布了在名称被保留之前使用该名称的第三方 marketplace，请重命名它并要求用户从您的源重新添加它1259* 如果您发布了在名称被保留之前使用该名称的第三方 marketplace，请重命名它并要求用户从您的源重新添加它
1260* 请参阅[Marketplace schema](/zh-CN/plugin-marketplaces#marketplace-schema)下的保留名称列表1260* 请参阅[Marketplace schema](/docs/zh-CN/plugin-marketplaces#marketplace-schema)下的保留名称列表
1261 1261
1262<h3 id="plugin-command-references-user-config">1262<h3 id="plugin-command-references-user-config">
1263 插件命令在 shell 命令中引用 user\_config1263 插件命令在 shell 命令中引用 user\_config
1264</h3>1264</h3>
1265 1265
1266插件 hook、[monitor](/zh-CN/plugins-reference#monitors)或 MCP [`headersHelper`](/zh-CN/mcp#use-dynamic-headers-for-custom-authentication)命令引用 `${user_config.KEY}` [插件选项](/zh-CN/plugins-reference#user-configuration)，替换后的字符串将被传递到 shell。配置的值包含 `$(...)` 、反引号或 `;` 会在那里作为代码运行，因此 Claude Code 拒绝启动该组件而不是替换该值。检查在命令模板上运行，因此即使尚未配置任何值，错误也会出现。在 v2.1.207 之前，该值被替换到 shell 命令中。1266插件 hook、[monitor](/docs/zh-CN/plugins-reference#monitors)或 MCP [`headersHelper`](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication)命令引用 `${user_config.KEY}` [插件选项](/docs/zh-CN/plugins-reference#user-configuration)，替换后的字符串将被传递到 shell。配置的值包含 `$(...)` 、反引号或 `;` 会在那里作为代码运行，因此 Claude Code 拒绝启动该组件而不是替换该值。检查在命令模板上运行，因此即使尚未配置任何值，错误也会出现。在 v2.1.207 之前，该值被替换到 shell 命令中。
1267 1267
1268措辞取决于哪个表面引用了该选项。shell 形式的 hook 报告：1268措辞取决于哪个表面引用了该选项。shell 形式的 hook 报告：
1269 1269
1285 1285
1286**应该怎么做：**1286**应该怎么做：**
1287 1287
1288* 对于 hook，添加 `args` 数组以便它在[exec 形式](/zh-CN/hooks#exec-form-and-shell-form)中运行，其中每个 `${user_config.KEY}` 成为一个参数，中间没有 shell。或删除引用并在脚本内读取 `$CLAUDE_PLUGIN_OPTION_<KEY>` 环境变量1288* 对于 hook，添加 `args` 数组以便它在[exec 形式](/docs/zh-CN/hooks#exec-form-and-shell-form)中运行，其中每个 `${user_config.KEY}` 成为一个参数，中间没有 shell。或删除引用并在脚本内读取 `$CLAUDE_PLUGIN_OPTION_<KEY>` 环境变量
1289* 对于 monitor，删除引用并让 monitor 脚本从配置文件读取该值1289* 对于 monitor，删除引用并让 monitor 脚本从配置文件读取该值
1290* 对于 `headersHelper`，将 `${user_config.KEY}` 移到服务器的 `headers` 字段中，该字段不会被 shell 解析，或在 helper 脚本内读取该值1290* 对于 `headersHelper`，将 `${user_config.KEY}` 移到服务器的 `headers` 字段中，该字段不会被 shell 解析，或在 helper 脚本内读取该值
1291 1291
1299 Agent would be spawned with zero tools1299 Agent would be spawned with zero tools
1300</h3>1300</h3>
1301 1301
1302[子代理的 `tools` 列表](/zh-CN/sub-agents#supported-frontmatter-fields)中没有任何内容解析为工具，因此 Claude Code 拒绝启动子代理，而不是启动一个无法执行操作的代理。该消息按它们未解析的原因对条目进行分组：不是公认的工具、子代理不可用的工具，或已识别但与当前会话中的任何工具都不匹配。省略 `tools` 字段永远不会触发此拒绝。MCP 服务器模式（如 `mcp__github__*`）不例外：当没有来自该服务器的连接工具时，启动会被拒绝，该模式在匹配失败组中。在 v2.1.208 之前，子代理启动时没有工具，并返回空结果或令人困惑的结果。1302[子代理的 `tools` 列表](/docs/zh-CN/sub-agents#supported-frontmatter-fields)中没有任何内容解析为工具，因此 Claude Code 拒绝启动子代理，而不是启动一个无法执行操作的代理。该消息按它们未解析的原因对条目进行分组：不是公认的工具、子代理不可用的工具，或已识别但与当前会话中的任何工具都不匹配。省略 `tools` 字段永远不会触发此拒绝。MCP 服务器模式（如 `mcp__github__*`）不例外：当没有来自该服务器的连接工具时，启动会被拒绝，该模式在匹配失败组中。在 v2.1.208 之前，子代理启动时没有工具，并返回空结果或令人困惑的结果。
1303 1303
1304```text theme={null}1304```text theme={null}
1305Agent 'code-reviewer' would be spawned with zero tools — refusing. Its tools list resolved to nothing: unrecognized [Grpe]. Fix the agent's tools frontmatter or pass a different subagent_type.1305Agent 'code-reviewer' would be spawned with zero tools — refusing. Its tools list resolved to nothing: unrecognized [Grpe]. Fix the agent's tools frontmatter or pass a different subagent_type.
1307 1307
1308**应该做什么：**1308**应该做什么：**
1309 1309
1310* 针对[子代理可用的工具](/zh-CN/sub-agents#available-tools)纠正错误命名的每个条目1310* 针对[子代理可用的工具](/docs/zh-CN/sub-agents#available-tools)纠正错误命名的每个条目
1311* 删除会话没有的工具条目，例如来自未连接的服务器的 MCP 工具1311* 删除会话没有的工具条目，例如来自未连接的服务器的 MCP 工具
1312* 要给子代理提供父代理拥有的每个工具，请删除 `tools` 字段而不是列出工具1312* 要给子代理提供父代理拥有的每个工具，请删除 `tools` 字段而不是列出工具
1313 1313
1315 File is covered by a Read deny rule1315 File is covered by a Read deny rule
1316</h3>1316</h3>
1317 1317
1318Edit 工具在与 [`Read` 拒绝规则](/zh-CN/permissions#read-and-edit)匹配的路径上被调用，包括在该路径创建新文件。编辑会重写 Claude 必须能够读回的内容，因此在任何文件访问之前调用被拒绝。该规则仅阻止 Edit 工具：Write 和 NotebookEdit 不受 `Read` 拒绝规则的覆盖。在 v2.1.208 之前，只有 `Edit` 拒绝规则阻止编辑，而 `Read` 拒绝规则单独不会。1318Edit 工具在与 [`Read` 拒绝规则](/docs/zh-CN/permissions#read-and-edit)匹配的路径上被调用，包括在该路径创建新文件。编辑会重写 Claude 必须能够读回的内容，因此在任何文件访问之前调用被拒绝。该规则仅阻止 Edit 工具：Write 和 NotebookEdit 不受 `Read` 拒绝规则的覆盖。在 v2.1.208 之前，只有 `Edit` 拒绝规则阻止编辑，而 `Read` 拒绝规则单独不会。
1319 1319
1320```text theme={null}1320```text theme={null}
1321File is covered by a Read deny rule in your permission settings and cannot be edited.1321File is covered by a Read deny rule in your permission settings and cannot be edited.
1323 1323
1324**应该做什么：**1324**应该做什么：**
1325 1325
1326* 如果 Claude 应该能够编辑该文件，请在 `/permissions` 或[设置](/zh-CN/settings#permission-settings)中删除或缩小 `Read` 拒绝规则1326* 如果 Claude 应该能够编辑该文件，请在 `/permissions` 或[设置](/docs/zh-CN/settings#permission-settings)中删除或缩小 `Read` 拒绝规则
1327* 如果文件必须保持不变，请保留该规则并为相同路径添加 `Edit` 拒绝规则，以便 Write 和 NotebookEdit 工具也被阻止1327* 如果文件必须保持不变，请保留该规则并为相同路径添加 `Edit` 拒绝规则，以便 Write 和 NotebookEdit 工具也被阻止
1328 1328
1329<h2 id="background-session-errors">1329<h2 id="background-session-errors">
1330 后台会话错误1330 后台会话错误
1331</h2>1331</h2>
1332 1332
1333[后台会话](/zh-CN/agent-view)在没有交互式终端的情况下运行，因此需要终端的命令在那里的行为会有所不同。这些消息出现在后台会话的记录中，在代理视图中或附加后。1333[后台会话](/docs/zh-CN/agent-view)在没有交互式终端的情况下运行，因此需要终端的命令在那里的行为会有所不同。这些消息出现在后台会话的记录中，在代理视图中或附加后。
1334 1334
1335<h3 id="commands-refused-in-a-background-session">1335<h3 id="commands-refused-in-a-background-session">
1336 后台会话中被拒绝的命令1336 后台会话中被拒绝的命令
1337</h3>1337</h3>
1338 1338
1339打开交互式对话框的命令在后台会话中被拒绝，并显示一条消息，该消息要么命名一个在那里有效的表单，要么告诉您从常规终端运行该命令。`/install-github-app`、`/mcp` 设置列表和 MCP 服务器菜单中的身份验证操作都以这种方式被拒绝。在 v2.1.208 之前，它们在后台会话内打开其对话框。1339打开交互式对话框的命令在后台会话中被拒绝，并显示一条消息，该消息要么命名一个在那里有效的表单，要么告诉您从常规终端运行该命令。`/install-github-app`、`/mcp` 设置列表和 MCP 服务器菜单中的身份验证操作都以这种方式被拒绝。在 v2.1.208 之前，它们在后台会话内打开其对话框。
1340{/* max-version: 2.1.208 */}在 v2.1.208 中，`/model` 选择器也在后台会话中被拒绝，`/upgrade` 打印升级 URL 而不是打开浏览器。1340在 v2.1.208 中，`/model` 选择器也在后台会话中被拒绝，`/upgrade` 打印升级 URL 而不是打开浏览器。
1341 1341
1342措辞会命名被拒绝的命令。`/mcp` 设置列表报告：1342措辞会命名被拒绝的命令。`/mcp` 设置列表报告：
1343 1343
1354 CLAUDE\_CODE\_PROCESS\_WRAPPER 启动器错误1354 CLAUDE\_CODE\_PROCESS\_WRAPPER 启动器错误
1355</h3>1355</h3>
1356 1356
1357[`CLAUDE_CODE_PROCESS_WRAPPER`](/zh-CN/corporate-launcher) 已设置，其值无法使用，因此 Claude Code 拒绝启动受影响的进程，而不是在没有启动器的情况下运行它。配置问题会报告一条以变量名开头并说明原因的消息，例如：1357[`CLAUDE_CODE_PROCESS_WRAPPER`](/docs/zh-CN/corporate-launcher) 已设置，其值无法使用，因此 Claude Code 拒绝启动受影响的进程，而不是在没有启动器的情况下运行它。配置问题会报告一条以变量名开头并说明原因的消息，例如：
1358 1358
1359```text theme={null}1359```text theme={null}
1360CLAUDE_CODE_PROCESS_WRAPPER: launcher `/opt/corp/launcher` is not an executable regular file1360CLAUDE_CODE_PROCESS_WRAPPER: launcher `/opt/corp/launcher` is not an executable regular file
1364 1364
1365**应该怎么做：**1365**应该怎么做：**
1366 1366
1367* 将变量设置为可执行文件的绝对路径，该文件以调用 `exec "$@"` 结尾。有关完整合同，请参阅[启动器合同](/zh-CN/corporate-launcher#the-launcher-contract)1367* 将变量设置为可执行文件的绝对路径，该文件以调用 `exec "$@"` 结尾。有关完整合同，请参阅[启动器合同](/docs/zh-CN/corporate-launcher#the-launcher-contract)
1368* 检查 `/status`，它在其 Self-exec 条目中显示已解析的启动命令，并在运行的后台服务与其不匹配时发出警告，或从 shell 运行 `claude daemon status`1368* 检查 `/status`，它在其 Self-exec 条目中显示已解析的启动命令，并在运行的后台服务与其不匹配时发出警告，或从 shell 运行 `claude daemon status`
1369* 在[设置](/zh-CN/corporate-launcher#set-up-the-launcher)的 `env` 块中修复值后，使用 `claude daemon stop --any` 重启后台服务，以便下一次调度启动一个包装的服务1369* 在[设置](/docs/zh-CN/corporate-launcher#set-up-the-launcher)的 `env` 块中修复值后，使用 `claude daemon stop --any` 重启后台服务，以便下一次调度启动一个包装的服务
1370 1370
1371<h2 id="configuration-warnings">1371<h2 id="configuration-warnings">
1372 配置警告1372 配置警告
1378 工作区尚未被信任1378 工作区尚未被信任
1379</h3>1379</h3>
1380 1380
1381Claude Code 在项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中找到了 `permissions.allow` 规则或 `permissions.additionalDirectories` 条目，但未应用它们，因为[项目设置中的允许规则需要工作区信任](/zh-CN/permissions#project-allow-rules-and-workspace-trust)。消息中的计数、设置名称和文件名会根据您的配置而变化。`deny` 和 `ask` 规则不受影响。1381Claude Code 在项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中找到了 `permissions.allow` 规则或 `permissions.additionalDirectories` 条目，但未应用它们，因为[项目设置中的允许规则需要工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)。消息中的计数、设置名称和文件名会根据您的配置而变化。`deny` 和 `ask` 规则不受影响。
1382 1382
1383```text theme={null}1383```text theme={null}
1384Ignoring 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.1384Ignoring 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.
1386 1386
1387**应该做什么：**1387**应该做什么：**
1388 1388
1389* 在目录中运行 `claude` 并接受信任对话框。{/* min-version: 2.1.200 */}即使父目录已被信任，对话框也会出现，列出被保留的规则，并让您可以拒绝并继续工作而不应用这些规则。在 v2.1.200 之前，在这种情况下不会出现对话框，因此无法在那里完成此步骤。1389* 在目录中运行 `claude` 并接受信任对话框。即使父目录已被信任，对话框也会出现，列出被保留的规则，并让您可以拒绝并继续工作而不应用这些规则。在 v2.1.200 之前，在这种情况下不会出现对话框，因此无法在那里完成此步骤。
1390* 在[非交互模式](/zh-CN/headless)中使用 `-p` 不会显示对话框。使用消息打印的确切 `projects` 密钥在 `~/.claude.json` 中设置 `hasTrustDialogAccepted` 条目。1390* 在[非交互模式](/docs/zh-CN/headless)中使用 `-p` 不会显示对话框。使用消息打印的确切 `projects` 密钥在 `~/.claude.json` 中设置 `hasTrustDialogAccepted` 条目。
1391* {/* 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` 视为存储库提供的。{/* min-version: 2.1.207 */}在 v2.1.207 及更高版本上，如果您尚未信任该文件夹，在 git 存储库外部更新是不够的：确定文件夹不在存储库内会运行 git，Claude Code 仅在您接受信任对话框后才运行该检查，因此请使用第一步。您的主目录和任何其他[配置主目录](/zh-CN/permissions#project-allow-rules-and-workspace-trust)是豁免的，不需要等待对话框。请参阅[项目允许规则和工作区信任](/zh-CN/permissions#project-allow-rules-and-workspace-trust)。1391* 如果消息命名 `.claude/settings.local.json` 并且您在 git 存储库外部或在主目录中启动了 Claude Code，请更新到 v2.1.200 或更高版本。版本 2.1.196 至 2.1.199 在这些工作区中将您自己的 `.claude/settings.local.json` 视为存储库提供的。在 v2.1.207 及更高版本上，如果您尚未信任该文件夹，在 git 存储库外部更新是不够的：确定文件夹不在存储库内会运行 git，Claude Code 仅在您接受信任对话框后才运行该检查，因此请使用第一步。您的主目录和任何其他[配置主目录](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)是豁免的，不需要等待对话框。请参阅[项目允许规则和工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)。
1392 1392
1393<h2 id="responses-seem-lower-quality-than-usual">1393<h2 id="responses-seem-lower-quality-than-usual">
1394 回复质量似乎低于预期1394 回复质量似乎低于预期
1396 1396
1397如果 Claude 的回答似乎不如你预期的那样有能力，但没有显示错误，原因通常是对话状态而不是模型本身。Claude Code 不会无声地更改模型版本。它只能在三种特定情况下切换到备用模型：1397如果 Claude 的回答似乎不如你预期的那样有能力，但没有显示错误，原因通常是对话状态而不是模型本身。Claude Code 不会无声地更改模型版本。它只能在三种特定情况下切换到备用模型：
1398 1398
1399* 配置的 [`--fallback-model`](/zh-CN/cli-reference#cli-flags) 在可用性错误后接管该轮，并在记录中显示通知1399* 配置的 [`--fallback-model`](/docs/zh-CN/cli-reference#cli-flags) 在可用性错误后接管该轮，并在记录中显示通知
1400* Amazon Bedrock 或 Google Cloud 的 Agent Platform 启动检查发现你的默认模型不可用1400* Amazon Bedrock 或 Google Cloud 的 Agent Platform 启动检查发现你的默认模型不可用
1401* [自动模型备用](/zh-CN/model-config#automatic-model-fallback)在 Fable 5 上将会话移至默认 Opus 模型，并在记录中显示通知1401* [自动模型备用](/docs/zh-CN/model-config#automatic-model-fallback)在 Fable 5 上将会话移至默认 Opus 模型，并在记录中显示通知
1402 1402
1403下面的模型选择检查捕获第二和第三种情况；第一种情况显示为记录通知而不是 `/model` 更改。[模型配置](/zh-CN/model-config)解释了每个备用何时适用。1403下面的模型选择检查捕获第二和第三种情况；第一种情况显示为记录通知而不是 `/model` 更改。[模型配置](/docs/zh-CN/model-config)解释了每个备用何时适用。
1404 1404
1405首先检查这些：1405首先检查这些：
1406 1406
1407* **模型选择**：运行 `/model` 以确认你在预期的模型上。之前的 `/model` 选择或 `ANTHROPIC_MODEL` 环境变量可能使你在比预期更小的模型上。1407* **模型选择**：运行 `/model` 以确认你在预期的模型上。之前的 `/model` 选择或 `ANTHROPIC_MODEL` 环境变量可能使你在比预期更小的模型上。
1408* **努力级别**：运行 `/effort` 以检查当前推理级别，并为困难的调试或设计工作提高它。默认值因模型而异，所以在假设你低于最大值之前请检查。有关每个模型的默认值和 `ultrathink` 快捷方式，请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level)。1408* **努力级别**：运行 `/effort` 以检查当前推理级别，并为困难的调试或设计工作提高它。默认值因模型而异，所以在假设你低于最大值之前请检查。有关每个模型的默认值和 `ultrathink` 快捷方式，请参阅[调整努力级别](/docs/zh-CN/model-config#adjust-effort-level)。
1409* **上下文压力**：运行 `/context` 以查看窗口有多满。如果接近容量，在自然断点处运行 `/compact` 或运行 `/clear` 以重新开始。有关自动压缩如何影响早期轮次的信息，请参阅[探索上下文窗口](/zh-CN/context-window)。1409* **上下文压力**：运行 `/context` 以查看窗口有多满。如果接近容量，在自然断点处运行 `/compact` 或运行 `/clear` 以重新开始。有关自动压缩如何影响早期轮次的信息，请参阅[探索上下文窗口](/docs/zh-CN/context-window)。
1410* **过时的指令**：大型或过时的 `CLAUDE.md` 文件和 MCP 工具定义会消耗上下文并可能引导回复。{/* min-version: 2.1.205 */}`/doctor` 检查会标记超大内存文件和未使用的扩展，`/context` 显示 MCP 工具令牌使用情况。在 v2.1.205 之前，`/doctor` 打开一个诊断屏幕，标记超大内存文件和子代理定义。1410* **过时的指令**：大型或过时的 `CLAUDE.md` 文件和 MCP 工具定义会消耗上下文并可能引导回复。`/doctor` 检查会标记超大内存文件和未使用的扩展，`/context` 显示 MCP 工具令牌使用情况。在 v2.1.205 之前，`/doctor` 打开一个诊断屏幕，标记超大内存文件和子代理定义。
1411 1411
1412当回复出错时，回退通常比用更正回复效果更好。按 Esc 两次或运行 `/rewind` 以回到坏轮之前，然后用更具体的内容重新表述提示。在线程中更正会将错误的尝试保留在上下文中，这可能会将后来的答案锚定到它。请参阅[检查点](/zh-CN/checkpointing)。1412当回复出错时，回退通常比用更正回复效果更好。按 Esc 两次或运行 `/rewind` 以回到坏轮之前，然后用更具体的内容重新表述提示。在线程中更正会将错误的尝试保留在上下文中，这可能会将后来的答案锚定到它。请参阅[检查点](/docs/zh-CN/checkpointing)。
1413 1413
1414如果在检查上述内容后质量仍然似乎有问题，运行 `/feedback` 并描述你期望的内容与你得到的内容。以这种方式提交的反馈包括对话记录，这是 Anthropic 诊断真实回归的最快方式。如果 `/feedback` 在你的环境中不可用，请参阅[报告错误](#report-an-error)。1414如果在检查上述内容后质量仍然似乎有问题，运行 `/feedback` 并描述你期望的内容与你得到的内容。以这种方式提交的反馈包括对话记录，这是 Anthropic 诊断真实回归的最快方式。如果 `/feedback` 在你的环境中不可用，请参阅[报告错误](#report-an-error)。
1415 1415
1416如果 Claude 警告可疑的提示注入，或因可疑注入而拒绝请求，并且警告命名的文本是 Claude Code 自动添加到对话中的上下文而不是文件或网络内容，运行 `claude update` 并重试。如果更新后警告重复出现，[报告它](#report-an-error)而不是将标记的内容粘贴回提示中。{/* min-version: 2.1.201 */}在 v2.1.201 之前，Sonnet 5 以相同的方式拒绝了一些请求。1416如果 Claude 警告可疑的提示注入，或因可疑注入而拒绝请求，并且警告命名的文本是 Claude Code 自动添加到对话中的上下文而不是文件或网络内容，运行 `claude update` 并重试。如果更新后警告重复出现，[报告它](#report-an-error)而不是将标记的内容粘贴回提示中。在 v2.1.201 之前，Sonnet 5 以相同的方式拒绝了一些请求。
1417 1417
1418<h2 id="report-an-error">1418<h2 id="report-an-error">
1419 报告错误1419 报告错误
1421 1421
1422对于此页面未涵盖的组件错误，请参阅相关指南：1422对于此页面未涵盖的组件错误，请参阅相关指南：
1423 1423
1424* MCP 服务器连接或身份验证失败：[MCP](/zh-CN/mcp)1424* MCP 服务器连接或身份验证失败：[MCP](/docs/zh-CN/mcp)
1425* Hook 脚本失败或阻止了工具：[调试 hooks](/zh-CN/hooks#debug-hooks)1425* Hook 脚本失败或阻止了工具：[调试 hooks](/docs/zh-CN/hooks#debug-hooks)
1426* 安装期间权限被拒绝或文件系统错误：[排查安装和登录问题](/zh-CN/troubleshoot-install)1426* 安装期间权限被拒绝或文件系统错误：[排查安装和登录问题](/docs/zh-CN/troubleshoot-install)
1427 1427
1428如果此处未列出错误或建议的修复方法无法帮助：1428如果此处未列出错误或建议的修复方法无法帮助：
1429 1429
1430* 在 Claude Code 中运行 `/feedback` 将记录和描述发送给 Anthropic。该命令还提供打开预填充的 GitHub issue 的选项。发送到 Anthropic 需要[身份验证](/zh-CN/authentication)。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和其他第三方提供商上，或者当未配置 Anthropic 凭证时，`/feedback` 会保存一个本地存档，您可以将其发送给您的 Anthropic 账户代表。1430* 在 Claude Code 中运行 `/feedback` 将记录和描述发送给 Anthropic。该命令还提供打开预填充的 GitHub issue 的选项。发送到 Anthropic 需要[身份验证](/docs/zh-CN/authentication)。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和其他第三方提供商上，或者当未配置 Anthropic 凭证时，`/feedback` 会保存一个本地存档，您可以将其发送给您的 Anthropic 账户代表。
1431* 从您的 shell 中运行 `claude doctor` 以获取安装的只读诊断，或在 Claude Code 中运行 `/doctor` 检查以查找和修复设置问题1431* 从您的 shell 中运行 `claude doctor` 以获取安装的只读诊断，或在 Claude Code 中运行 `/doctor` 检查以查找和修复设置问题
1432* 检查 [status.claude.com](https://status.claude.com) 以了解活跃的事件1432* 检查 [status.claude.com](https://status.claude.com) 以了解活跃的事件
1433* 在 GitHub 上搜索[现有问题](https://github.com/anthropics/claude-code/issues)1433* 在 GitHub 上搜索[现有问题](https://github.com/anthropics/claude-code/issues)
