21将您在终端中看到的消息与下面的部分相匹配。21将您在终端中看到的消息与下面的部分相匹配。
22 22
23| 消息 | 部分 |23| 消息 | 部分 |
24| :-------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- |24| :------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- |
25| `API Error: 500 Internal server error` | [服务器错误](#api-error-500-internal-server-error) |25| `API Error: 500 Internal server error` | [服务器错误](#api-error-500-internal-server-error) |
26| `API Error: Repeated 529 Overloaded errors` | [服务器错误](#api-error-repeated-529-overloaded-errors) |26| `API Error: Repeated 529 Overloaded errors` | [服务器错误](#api-error-repeated-529-overloaded-errors) |
27| `Request timed out` | [服务器错误](#request-timed-out)，或[网络](#unable-to-connect-to-api)（如果消息提到您的互联网连接） |27| `Request timed out` | [服务器错误](#request-timed-out)，或[网络](#unable-to-connect-to-api)（如果消息提到您的互联网连接） |
39| `Not logged in · Please run /login` | [身份验证](#not-logged-in) |39| `Not logged in · Please run /login` | [身份验证](#not-logged-in) |
40| `Could not resolve authentication method` | [身份验证](#could-not-resolve-authentication-method) |40| `Could not resolve authentication method` | [身份验证](#could-not-resolve-authentication-method) |
41| `Invalid API key` | [身份验证](#invalid-api-key) |41| `Invalid API key` | [身份验证](#invalid-api-key) |
42| `Your apiKeyHelper script is failing` | [身份验证](#your-apikeyhelper-script-is-failing) |
42| `This organization has been disabled` | [身份验证](#this-organization-has-been-disabled) |43| `This organization has been disabled` | [身份验证](#this-organization-has-been-disabled) |
43| `Your organization has disabled API key authentication` | [身份验证](#your-organization-has-disabled-api-key-authentication) |44| `Your organization has disabled API key authentication` | [身份验证](#your-organization-has-disabled-api-key-authentication) |
44| `Your organization has disabled Claude subscription access` | [身份验证](#your-organization-has-disabled-claude-subscription-access) |45| `Your organization has disabled Claude subscription access` | [身份验证](#your-organization-has-disabled-claude-subscription-access) |
45| `Routines are disabled by your organization's policy` | [身份验证](#routines-are-disabled-by-your-organizations-policy) |46| `Routines are disabled by your organization's policy` | [身份验证](#routines-are-disabled-by-your-organizations-policy) |
46| `Remote Control is only available when using Claude via api.anthropic.com` | [身份验证](#remote-control-requires-the-anthropic-api) |47| `Remote Control is only available when using Claude via api.anthropic.com` | [身份验证](#remote-control-requires-the-anthropic-api) |
47| `OAuth token revoked` / `OAuth token has expired` | [身份验证](#oauth-token-revoked-or-expired) |48| `OAuth token revoked` / `OAuth token has expired` | [身份验证](#oauth-token-revoked-or-expired) |
49| `Login expired · Please run /login` | [身份验证](#login-expired) |
50| `Failed to authenticate: OAuth session expired and could not be refreshed` | [身份验证](#login-expired) |
48| `does not meet scope requirement user:profile` | [身份验证](#oauth-scope-requirement) |51| `does not meet scope requirement user:profile` | [身份验证](#oauth-scope-requirement) |
49| `AWS credentials expired or invalid` | [身份验证](#aws-credentials-expired-or-invalid) |52| `AWS credentials expired or invalid` | [身份验证](#aws-credentials-expired-or-invalid) |
50| `AWS authentication failed` | [身份验证](#aws-authentication-failed) |53| `AWS authentication failed` | [身份验证](#aws-authentication-failed) |
54| `AWS default-chain credential resolve timed out` | [身份验证](#aws-default-chain-credential-resolve-timed-out) |
51| `Unable to connect to API` | [网络](#unable-to-connect-to-api) |55| `Unable to connect to API` | [网络](#unable-to-connect-to-api) |
52| `Waiting for API response · will retry in` | [自动重试](#automatic-retries)，或[网络](#unable-to-connect-to-api)（如果问题持续） |56| `Waiting for API response · will retry in` | [自动重试](#automatic-retries)，或[网络](#unable-to-connect-to-api)（如果问题持续） |
57| `Bedrock streaming response has content-type "..."; expected "application/vnd.amazon.eventstream"` | [网络](#bedrock-streaming-response-has-an-unexpected-content-type) |
53| `SSL certificate verification failed` | [网络](#ssl-certificate-errors) |58| `SSL certificate verification failed` | [网络](#ssl-certificate-errors) |
54| `SSL certificate error (...)` during login or startup | [网络](#ssl-certificate-errors) |59| `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) |60| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [网络](#host-not-allowed-in-a-cloud-session) |
76| `--bg and --print conflict` | [命令行错误](#command-line-errors) |81| `--bg and --print conflict` | [命令行错误](#command-line-errors) |
77| `Error: --json-schema is not a valid JSON Schema` | [命令行错误](#command-line-errors) |82| `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) |83| `Could not import <server>: <reason>` | [命令行错误](#could-not-import-a-server-from-claude-desktop) |
84| `Error: MCP tool <name> (passed via --permission-prompt-tool) not found` | [命令行错误](#mcp-permission-prompt-tool-not-found) |
79| `Marketplace "<name>" is registered from an untrusted source` | [插件错误](#marketplace-is-registered-from-an-untrusted-source) |85| `Marketplace "<name>" is registered from an untrusted source` | [插件错误](#marketplace-is-registered-from-an-untrusted-source) |
86| `references ${user_config.*} in a shell-form command` | [插件错误](#plugin-command-references-user-config) |
87| `Monitor "<name>" from plugin <plugin> references ${user_config.*} in its command` | [插件错误](#plugin-command-references-user-config) |
88| `headersHelper for MCP server '<name>' references ${user_config.*}` | [插件错误](#plugin-command-references-user-config) |
89| `would be spawned with zero tools — refusing` | [工具错误](#agent-would-be-spawned-with-zero-tools) |
90| `File is covered by a Read deny rule in your permission settings` | [工具错误](#file-is-covered-by-a-read-deny-rule) |
91| `Can't open MCP settings in a background session` | [后台会话错误](#commands-refused-in-a-background-session) |
92| `CLAUDE_CODE_PROCESS_WRAPPER: launcher ...` | [后台会话错误](#claude_code_process_wrapper-launcher-errors) |
80| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [配置警告](#workspace-has-not-been-trusted) |93| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [配置警告](#workspace-has-not-been-trusted) |
81| 响应质量似乎低于平常 | [响应质量](#responses-seem-lower-quality-than-usual) |94| 响应质量似乎低于平常 | [响应质量](#responses-seem-lower-quality-than-usual) |
82 95
86 99
87Claude 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 次。{/* min-version: 2.1.198 */}从 v2.1.198 开始，这涵盖了在任何可见输出流出之前在响应中途断开的连接：Claude Code 使用相同的退避重新发出请求，轮次继续而不是停止并显示连接错误。{/* min-version: 2.1.199 */}从 v2.1.199 开始，不携带您计划配额标头的临时 429 限流在您使用 claude.ai 订阅登录时也会重试；早期版本仅对 API 密钥和企业登录重试它们。
88 101
89两个故障类别不会重试，因为重试无法成功：102某些故障类别不会重试，因为重试无法成功：
90 103
91* {/* min-version: 2.1.199 */}从 v2.1.199 开始，TLS 证书验证失败（例如 TLS 检查代理、缺少 `NODE_EXTRA_CA_CERTS` 包或过期证书）在第一次尝试时失败，因此修复立即出现，而不是在完整重试预算之后。请参阅 [SSL 证书错误](#ssl-certificate-errors)。瞬时 TLS 条件（例如握手超时）仍然会重试。104* {/* min-version: 2.1.199 */}从 v2.1.199 开始，TLS 证书验证失败（例如 TLS 检查代理、缺少 `NODE_EXTRA_CA_CERTS` 包或过期证书）在第一次尝试时失败，因此修复立即出现，而不是在完整重试预算之后。请参阅 [SSL 证书错误](#ssl-certificate-errors)。瞬时 TLS 条件（例如握手超时）仍然会重试。
92* {/* min-version: 2.1.199 */}从 v2.1.199 开始，在 Claude 已经流出可见输出后到达的服务器错误会保留部分响应并附加[不完整响应通知](#the-response-above-may-be-incomplete)，而不是重试，因为重新运行请求可能会执行相同的工具两次。早期版本丢弃了部分输出并将轮次报告为错误。105* {/* min-version: 2.1.199 */}从 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 或更高版本。
93 107
94重试时，微调器在错误标签后显示 `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`。{/* min-version: 2.1.198 */}从 v2.1.198 开始，它切换到第三次尝试中的特定原因，或当 `CLAUDE_CODE_MAX_RETRIES` 允许少于三次时在最后一次尝试；早期版本仅在最后一次尝试时切换。
95 109
285 299
286Claude Code 会阻止进一步的请求，直到消息中显示的重置时间。会话和每周限制在所有模型中共享，因此切换模型不会恢复访问权限。Opus 限制仅适用于 Opus 请求，因此使用 `/model` 切换到另一个模型可以继续工作。300Claude Code 会阻止进一步的请求，直到消息中显示的重置时间。会话和每周限制在所有模型中共享，因此切换模型不会恢复访问权限。Opus 限制仅适用于 Opus 请求，因此使用 `/model` 切换到另一个模型可以继续工作。
287 301
302使用量同时计入会话和每周额度。单次大量活动突发（例如大型工作流扇出）可能会在会话窗口重置之前耗尽每周额度。
303
288**应该怎么做：**304**应该怎么做：**
289 305
290* 等待错误消息中显示的重置时间306* 等待错误消息中显示的重置时间
430* 如果密钥来自 [`apiKeyHelper`](/zh-CN/settings#available-settings) 脚本，直接运行该脚本以确认它在 stdout 上打印有效密钥446* 如果密钥来自 [`apiKeyHelper`](/zh-CN/settings#available-settings) 脚本，直接运行该脚本以确认它在 stdout 上打印有效密钥
431* 运行 `/status` 确认 Claude Code 实际使用的凭证源447* 运行 `/status` 确认 Claude Code 实际使用的凭证源
432 448
449<h3 id="your-apikeyhelper-script-is-failing">
450 您的 apiKeyHelper 脚本失败
451</h3>
452
453在 [`apiKeyHelper`](/zh-CN/settings#available-settings) 设置中配置的命令以错误退出、超时或未向 stdout 打印任何内容。没有来自脚本的密钥，请求到达 API 时带有占位符凭证，API 以 `401` 拒绝它。
454
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 output
457```
458
459Claude Code 重新运行脚本并在显示此消息之前最多重试请求两次，因此故障在三次尝试内浮出。{/* min-version: 2.1.208 */}在 v2.1.208 之前，Claude Code 花费完整的 [重试预算](#automatic-retries) 使用占位符凭证重新发送请求，然后报告通用的 `401` 身份验证错误而不是脚本故障。
460
461运行 `/login` 在这里无法帮助：只要设置存在，helper 的输出 [优先于](/zh-CN/authentication#authentication-precedence) 保存的登录。
462
463**应该做什么：**
464
465* 在您的 shell 中直接运行在 `apiKeyHelper` 中配置的命令以重现故障
466* 如果命令报告会话已过期，请使用您的凭证提供商重新身份验证，例如再次登录您的 SSO 或密钥保管库
467* 修复命令以便它将密钥打印到 stdout 并以代码 0 退出。有关工作设置，请参阅 [使用 apiKeyHelper 轮换凭证](/zh-CN/llm-gateway-connect#rotate-credentials-with-apikeyhelper)。
468* 运行 `/status` 确认 `apiKeyHelper` 是活跃凭证源。每次命令失败时，其退出代码和错误输出都会出现在终端中的 `Cloud authentication` 面板中。
469
433<h3 id="this-organization-has-been-disabled">470<h3 id="this-organization-has-been-disabled">
434 此组织已被禁用471 此组织已被禁用
435</h3>472</h3>
532 569
533您保存的登录不再有效。撤销的令牌意味着您在任何地方都已登出或管理员删除了访问权限；过期的令牌意味着自动刷新在会话中途失败。570您保存的登录不再有效。撤销的令牌意味着您在任何地方都已登出或管理员删除了访问权限；过期的令牌意味着自动刷新在会话中途失败。
534 571
572两条消息都报告 Claude Code 发送的请求 API 返回的拒绝。当保存的登录在失败的刷新后已被清除时，您会看到 [登录已过期](#login-expired) 代替。
573
535```text theme={null}574```text theme={null}
536OAuth token revoked · Please run /login575OAuth token revoked · Please run /login
537OAuth token has expired · Please run /login576OAuth token has expired · Please run /login
545* 对于跨启动的重复登录提示，请参阅 [故障排除](/zh-CN/troubleshoot-install#not-logged-in-or-token-expired) 中的系统时钟和 macOS Keychain 检查584* 对于跨启动的重复登录提示，请参阅 [故障排除](/zh-CN/troubleshoot-install#not-logged-in-or-token-expired) 中的系统时钟和 macOS Keychain 检查
546* 对于其他故障，包括 `403 Forbidden` 和 OAuth 浏览器问题，请参阅 [登录和身份验证](/zh-CN/troubleshoot-install#login-and-authentication)585* 对于其他故障，包括 `403 Forbidden` 和 OAuth 浏览器问题，请参阅 [登录和身份验证](/zh-CN/troubleshoot-install#login-and-authentication)
547 586
587<h3 id="login-expired">
588 登录已过期
589</h3>
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 而不是登录提示。
592
593```text theme={null}
594Login expired · Please run /login
595```
596
597在 [非交互模式](/zh-CN/headless) (`-p`) 和 [Agent SDK](/zh-CN/agent-sdk/overview) 中，消息如下所示，结构化错误代码为 `authentication_failed`：
598
599```text theme={null}
600Failed to authenticate: OAuth session expired and could not be refreshed
601```
602
603这与 [OAuth 令牌被撤销或过期](#oauth-token-revoked-or-expired) 的状态不同。这些消息报告 API 返回的 401。Claude Code 本身为已失败刷新的登录生成 `Login expired`，因此它不发送请求。
604
605使用 API 密钥、[`CLAUDE_CODE_OAUTH_TOKEN`](/zh-CN/env-vars) 或第三方提供商进行身份验证的会话不使用保存的登录，永远不会看到此消息。
606
607**应该做什么：**
608
609* 运行 `/login` 重新登录。不登录重试会在每个请求上显示相同的消息。
610* 在非交互模式中，在同一环境中运行 `claude`，完成 `/login`，然后重新运行您的命令。对于无法交互式登录的自动化，使用 `ANTHROPIC_API_KEY` 进行身份验证或 [使用 `claude setup-token` 生成长期令牌](/zh-CN/authentication#generate-a-long-lived-token)。
611* 如果登录持续失败，请参阅 [登录和身份验证](/zh-CN/troubleshoot-install#login-and-authentication)
612
548<h3 id="oauth-scope-requirement">613<h3 id="oauth-scope-requirement">
549 OAuth 范围要求614 OAuth 范围要求
550</h3>615</h3>
603* 如果您的凭证是最新的，请确认 [IAM 配置](/zh-CN/amazon-bedrock#iam-configuration) 中的 IAM 权限已附加到您使用的身份，并且所选模型已为您的账户和区域启用668* 如果您的凭证是最新的，请确认 [IAM 配置](/zh-CN/amazon-bedrock#iam-configuration) 中的 IAM 权限已附加到您使用的身份，并且所选模型已为您的账户和区域启用
604* 运行 `aws sts get-caller-identity` 确认您的请求使用哪个身份；过时的 `AWS_PROFILE` 或默认配置文件是权限不匹配的常见原因669* 运行 `aws sts get-caller-identity` 确认您的请求使用哪个身份；过时的 `AWS_PROFILE` 或默认配置文件是权限不匹配的常见原因
605 670
671<h3 id="aws-default-chain-credential-resolve-timed-out">
672 AWS 默认链凭证解析超时
673</h3>
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) 并重试，因此到您看到它时链已在重复尝试上停滞。
676
677```text theme={null}
678API Error: AWS default-chain credential resolve timed out
679```
680
681常见原因是 AWS 配置文件中的 `credential_process` 命令等待它无法接收的输入，以及容器或 VM 的实例元数据服务 (IMDS) 从不回答链的探测。{/* min-version: 2.1.207 */}在 v2.1.207 之前，停滞的链使请求无限期等待而不是以此消息失败。
682
683**应该做什么：**
684
685* 在同一 shell 中使用相同的 `AWS_PROFILE` 运行 `aws sts get-caller-identity`。如果它也挂起，请修复配置文件；提示交互式的 `credential_process` 命令是常见原因。
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) 以毫秒为单位提高限制
688
606<h2 id="network-and-connection-errors">689<h2 id="network-and-connection-errors">
607 网络和连接错误690 网络和连接错误
608</h2>691</h2>
609 692
610这些错误表示来自 Claude Code 的网络请求未能到达其目的地。它们通常源于您的本地网络、代理或防火墙，或云环境的网络策略。693这些错误表示来自 Claude Code 的网络请求未能到达其目的地，或 Claude Code 和 API 之间的某些东西在返回途中改变了响应。它们通常源于您的本地网络、代理或防火墙，或云环境的网络策略。
611 694
612<h3 id="unable-to-connect-to-api">695<h3 id="unable-to-connect-to-api">
613 无法连接到 API696 无法连接到 API
640* 在 macOS 上，已断开连接或卸载的 VPN 客户端可能会留下隧道接口或路由规则。检查 `ifconfig` 是否有过时的 `utun` 接口，并在系统设置中删除 VPN 的网络扩展。723* 在 macOS 上，已断开连接或卸载的 VPN 客户端可能会留下隧道接口或路由规则。检查 `ifconfig` 是否有过时的 `utun` 接口，并在系统设置中删除 VPN 的网络扩展。
641* Docker Desktop 和类似的容器运行时可能会拦截出站流量。退出它们并重试以排除这种可能性。724* Docker Desktop 和类似的容器运行时可能会拦截出站流量。退出它们并重试以排除这种可能性。
642 725
726<h3 id="bedrock-streaming-response-has-an-unexpected-content-type">
727 Bedrock 流式响应具有意外的内容类型
728</h3>
729
730Claude Code 和 [Amazon Bedrock](/zh-CN/amazon-bedrock) 之间的网关或代理正在转换流式响应体或其 `Content-Type` 标头。Amazon Bedrock 将响应流式传输为 `application/vnd.amazon.eventstream`，Claude Code 拒绝报告不同内容类型的成功流式响应，而不是解码它无法读取的响应体。请求不会重试。
731
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.
734```
735
736{/* min-version: 2.1.208 */}在 v2.1.208 之前，相同的配置错误表现为 `API Error: Truncated event message received`，在整个响应被缓冲后出现。
737
738**应该做什么：**
739
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)。
742
643<h3 id="ssl-certificate-errors">743<h3 id="ssl-certificate-errors">
644 SSL 证书错误744 SSL 证书错误
645</h3>745</h3>
859* **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`](/zh-CN/agent-sdk/typescript#options) 或在 Python 中设置 [`ClaudeAgentOptions(model=...)`](/zh-CN/agent-sdk/python#claudeagentoptions)，并处理结构化的 `model_not_found` 错误以显示您自己的重试或模型选择器。
860* 使用别名（如 `sonnet` 或 `opus`）而不是完整的版本化 ID。别名解析为维护的默认值，因此不会过时。请参阅[模型配置](/zh-CN/model-config)。960* 使用别名（如 `sonnet` 或 `opus`）而不是完整的版本化 ID。别名解析为维护的默认值，因此不会过时。请参阅[模型配置](/zh-CN/model-config)。
861* 如果 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。按[优先级顺序](/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`。
862* 对于 Google Cloud 的 Agent Platform 部署，请参阅 [Google Cloud 的 Agent Platform 故障排除](/zh-CN/google-vertex-ai#troubleshooting)。963* 对于 Google Cloud 的 Agent Platform 部署，请参阅 [Google Cloud 的 Agent Platform 故障排除](/zh-CN/google-vertex-ai#troubleshooting)。
863 964
864<h3 id="model-is-not-a-recognized-model-id">965<h3 id="model-is-not-a-recognized-model-id">
1070 \--bg 和 --print 之间的冲突1171 \--bg 和 --print 之间的冲突
1071</h3>1172</h3>
1072 1173
1073此消息需要 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` 启动一个[后台会话](/zh-CN/agent-view#from-your-shell)，您稍后可以使用 `claude agents` 附加到该会话，而 `--print` 以[非交互方式](/zh-CN/headless)运行，永远不会启动 `claude agents` 附加到的交互会话。在 v2.1.198 之前，此组合会静默创建一个永远无法附加的后台作业。
1074 1175
1075```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>'`.
1076```1178```
1077 1179
1078**应该怎么做：**1180**应该怎么做：**
1079 1181
1080* 删除 `-p` 或 `--print`。`--bg` 将提示作为其位置参数，因此 `claude --bg "<task>"` 是完整命令。请参阅[从您的 shell 分派新代理](/zh-CN/agent-view#from-your-shell)。1182* 删除 `-p` 或 `--print`。`--bg` 将提示作为其位置参数，所以 `claude --bg "<task>"` 是完整的命令。请参阅[从您的 shell 分派新代理](/zh-CN/agent-view#from-your-shell)。
1081* 要以非交互方式运行提示并打印结果而不是创建后台会话，请删除 `--bg` 并运行 `claude -p "<task>"`1183* 要以非交互方式运行提示并打印结果而不是创建后台会话，请删除 `--bg` 并运行 `claude -p "<task>"`
1082 1184
1083<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">
1093 1194
1094第二个冒号后面的文本是验证器的诊断，并命名了失败的关键字或位置。使用 `format` 关键字的架构（例如 `"format": "email"`）是有效的：Claude Code 接受 `format` 作为注释，不强制执行它。1195第二个冒号后面的文本是验证器的诊断，并命名了失败的关键字或位置。使用 `format` 关键字的架构（例如 `"format": "email"`）是有效的：Claude Code 接受 `format` 作为注释，不强制执行它。
1095 1196
1096Claude Code 在架构编译之前运行两项检查：它拒绝不可解析的 JSON 值，并显示 `Error: --json-schema is not valid JSON`，以及不是对象的有效 JSON，并显示 `Error: --json-schema must be a JSON object`。1197Claude Code 在架构编译之前运行两项检查：它拒绝不可解析的 JSON 值，并显示 `Error: --json-schema is not valid JSON`，以及拒绝不是对象的有效 JSON，并显示 `Error: --json-schema must be a JSON object`。
1097 1198
1098**应该怎么做：**1199**应该怎么做：**
1099 1200
1105 无法从 Claude Desktop 导入服务器1206 无法从 Claude Desktop 导入服务器
1106</h3>1207</h3>
1107 1208
1108Claude Code 无法添加您在 `claude mcp add-from-claude-desktop` 中选择的其中一个服务器。该命令仍会导入其他选定的服务器，并为每个无法添加的服务器打印一行。在 v2.1.205 之前，第一个失败的服务器会停止导入，所有选定的服务器都不会被添加。1209Claude Code 无法添加您在 `claude mcp add-from-claude-desktop` 中选择的其中一个服务器。该命令仍然导入其他选定的服务器，并为每个无法添加的服务器打印一行。在 v2.1.205 之前，第一个失败的服务器会停止导入，并且不会添加任何选定的服务器。
1109 1210
1110```text theme={null}1211```text theme={null}
1111Could 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.
1112```1213```
1113 1214
1114服务器名称后面的文本是原因。最常见的是名称检查：Claude Desktop 允许服务器名称中的字符（例如空格和句号），而 `claude mcp` 限制为字母、数字、连字符和下划线。其他原因包括未通过验证的服务器配置以及被您组织的 [MCP 策略](/zh-CN/managed-mcp)阻止的服务器。1215服务器名称后面的文本是原因。最常见的是名称检查：Claude Desktop 允许服务器名称中的字符（例如空格和句号），而 `claude mcp` 仅限于字母、数字、连字符和下划线。其他原因包括未通过验证的服务器配置和被您组织的 [MCP 策略](/zh-CN/managed-mcp)阻止的服务器。
1115 1216
1116**应该怎么做：**1217**应该怎么做：**
1117 1218
1118* 在 `claude_desktop_config.json` 中重命名服务器，仅使用字母、数字、连字符和下划线，然后再次运行 `claude mcp add-from-claude-desktop`1219* 在 `claude_desktop_config.json` 中重命名服务器，仅使用字母、数字、连字符和下划线，然后再次运行 `claude mcp add-from-claude-desktop`
1119* 使用 `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 服务器](/zh-CN/mcp#import-mcp-servers-from-claude-desktop)。
1120 1221
1222<h3 id="mcp-permission-prompt-tool-not-found">
1223 找不到 MCP 权限提示工具
1224</h3>
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 之前，启动不会等待服务器完成连接，因此启动缓慢但健康的服务器也会产生此错误。
1227
1228```text theme={null}
1229Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none
1230```
1231
1232`Available MCP tools:` 后面的列表命名了在等待结束时连接的 MCP 工具。
1233
1234**应该怎么做：**
1235
1236* 检查服务器是否启动并保持连接：在同一目录中运行 `claude mcp list`，并确认服务器列为已连接
1237* 确认工具名称与服务器公开的 `mcp__<server>__<tool>` 名称匹配
1238* 如果服务器需要超过 30 秒才能启动，请提高 [`MCP_TIMEOUT`](/zh-CN/env-vars)
1239
1121<h2 id="plugin-errors">1240<h2 id="plugin-errors">
1122 Plugin 错误1241 插件错误
1123</h2>1242</h2>
1124 1243
1125这些错误来自 [plugin](/zh-CN/plugins) 和 [marketplace](/zh-CN/plugin-marketplaces) 配置。对于不会产生此页面上的消息之一的 plugin 问题，例如无法加载的 marketplace URL 或已安装但不显示的 plugin，请参阅 [Plugin troubleshooting](/zh-CN/discover-plugins#troubleshooting)。1244这些错误来自[插件](/zh-CN/plugins)和[marketplace](/zh-CN/plugin-marketplaces)配置。对于不会产生本页面上的消息之一的插件问题，例如无法加载的 marketplace URL 或已安装但不显示的插件，请参阅[插件故障排除](/zh-CN/discover-plugins#troubleshooting)。
1126 1245
1127<h3 id="marketplace-is-registered-from-an-untrusted-source">1246<h3 id="marketplace-is-registered-from-an-untrusted-source">
1128 Marketplace 从不受信任的源注册1247 Marketplace 从不受信任的源注册
1129</h3>1248</h3>
1130 1249
1131marketplace 以 [为官方 Anthropic marketplace 保留的名称](/zh-CN/plugin-marketplaces#marketplace-schema) 注册，但其注册源不是 `anthropics` GitHub 存储库。Claude Code 每次加载或刷新 marketplace 时都会重新检查保留的名称，因此 marketplace 和从中安装的 plugin 停止加载。在 v2.1.205 之前，仅在添加 marketplace 时检查名称，因此在其名称被保留之前注册的条目继续加载。1250marketplace 以[为官方 Anthropic marketplace 保留的名称](/zh-CN/plugin-marketplaces#marketplace-schema)注册，但其注册源不是 `anthropics` GitHub 存储库。Claude Code 每次加载或刷新 marketplace 时都会重新检查保留的名称，因此 marketplace 和从中安装的插件停止加载。在 v2.1.205 之前，仅在添加 marketplace 时检查名称，因此在其名称被保留之前注册的条目继续加载。
1132 1251
1133```text theme={null}1252```text theme={null}
1134Marketplace "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.
1135```1254```
1136 1255
1137**应该做什么：**1256**应该怎么做：**
1138 1257
1139* 运行 `claude plugin marketplace remove <name>`，然后从官方 `github.com/anthropics` 存储库重新添加 marketplace1258* 运行 `claude plugin marketplace remove <name>`，然后从官方 `github.com/anthropics` 存储库重新添加 marketplace
1140* 如果您发布了在名称被保留之前使用该名称的第三方 marketplace，请重命名它并要求用户从您的源重新添加它1259* 如果您发布了在名称被保留之前使用该名称的第三方 marketplace，请重命名它并要求用户从您的源重新添加它
1141* 查看 [Marketplace schema](/zh-CN/plugin-marketplaces#marketplace-schema) 下的保留名称列表1260* 请参阅[Marketplace schema](/zh-CN/plugin-marketplaces#marketplace-schema)下的保留名称列表
1261
1262<h3 id="plugin-command-references-user-config">
1263 插件命令在 shell 命令中引用 user\_config
1264</h3>
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 命令中。
1267
1268措辞取决于哪个表面引用了该选项。shell 形式的 hook 报告：
1269
1270```text theme={null}
1271Hook from plugin formatter@acme-tools references ${user_config.*} in a shell-form command. The substituted value would be re-parsed by the shell. Use exec form instead — {"command": "<executable>", "args": ["${user_config.KEY}", ...]} — or read $CLAUDE_PLUGIN_OPTION_<KEY> from the hook's environment. Command: ./scripts/notify.sh ${user_config.webhook_url}
1272```
1273
1274monitor 报告：
1275
1276```text theme={null}
1277Monitor "deploy-status" from plugin deploy-tools references ${user_config.*} in its command. The substituted value would be passed to a shell. Monitor commands cannot safely reference ${user_config.*}; have the monitor script read the value from a config file or prompt instead.
1278```
1279
1280MCP `headersHelper` 报告：
1281
1282```text theme={null}
1283headersHelper for MCP server 'internal-api' references ${user_config.*}. The substituted value would be passed to a shell; read the value inside the helper script instead (e.g. from an env var set in the server's "env" block).
1284```
1285
1286**应该怎么做：**
1287
1288* 对于 hook，添加 `args` 数组以便它在[exec 形式](/zh-CN/hooks#exec-form-and-shell-form)中运行，其中每个 `${user_config.KEY}` 成为一个参数，中间没有 shell。或删除引用并在脚本内读取 `$CLAUDE_PLUGIN_OPTION_<KEY>` 环境变量
1289* 对于 monitor，删除引用并让 monitor 脚本从配置文件读取该值
1290* 对于 `headersHelper`，将 `${user_config.KEY}` 移到服务器的 `headers` 字段中，该字段不会被 shell 解析，或在 helper 脚本内读取该值
1291
1292<h2 id="tool-errors">
1293 工具错误
1294</h2>
1295
1296这些错误来自 Claude 的内置工具拒绝输入。Claude 会自动纠正大多数工具错误；下面两个错误需要你进行更改，因为它们来自你控制的子代理定义或权限规则。
1297
1298<h3 id="agent-would-be-spawned-with-zero-tools">
1299 Agent would be spawned with zero tools
1300</h3>
1301
1302[子代理的 `tools` 列表](/zh-CN/sub-agents#supported-frontmatter-fields)中没有任何内容解析为工具，因此 Claude Code 拒绝启动子代理，而不是启动一个无法执行操作的代理。该消息按它们未解析的原因对条目进行分组：不是公认的工具、子代理不可用的工具，或已识别但与当前会话中的任何工具都不匹配。省略 `tools` 字段永远不会触发此拒绝。MCP 服务器模式（如 `mcp__github__*`）不例外：当没有来自该服务器的连接工具时，启动会被拒绝，该模式在匹配失败组中。在 v2.1.208 之前，子代理启动时没有工具，并返回空结果或令人困惑的结果。
1303
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.
1306```
1307
1308**应该做什么：**
1309
1310* 针对[子代理可用的工具](/zh-CN/sub-agents#available-tools)纠正错误命名的每个条目
1311* 删除会话没有的工具条目，例如来自未连接的服务器的 MCP 工具
1312* 要给子代理提供父代理拥有的每个工具，请删除 `tools` 字段而不是列出工具
1313
1314<h3 id="file-is-covered-by-a-read-deny-rule">
1315 File is covered by a Read deny rule
1316</h3>
1317
1318Edit 工具在与 [`Read` 拒绝规则](/zh-CN/permissions#read-and-edit)匹配的路径上被调用，包括在该路径创建新文件。编辑会重写 Claude 必须能够读回的内容，因此在任何文件访问之前调用被拒绝。该规则仅阻止 Edit 工具：Write 和 NotebookEdit 不受 `Read` 拒绝规则的覆盖。在 v2.1.208 之前，只有 `Edit` 拒绝规则阻止编辑，而 `Read` 拒绝规则单独不会。
1319
1320```text theme={null}
1321File is covered by a Read deny rule in your permission settings and cannot be edited.
1322```
1323
1324**应该做什么：**
1325
1326* 如果 Claude 应该能够编辑该文件，请在 `/permissions` 或[设置](/zh-CN/settings#permission-settings)中删除或缩小 `Read` 拒绝规则
1327* 如果文件必须保持不变，请保留该规则并为相同路径添加 `Edit` 拒绝规则，以便 Write 和 NotebookEdit 工具也被阻止
1328
1329<h2 id="background-session-errors">
1330 后台会话错误
1331</h2>
1332
1333[后台会话](/zh-CN/agent-view)在没有交互式终端的情况下运行，因此需要终端的命令在那里的行为会有所不同。这些消息出现在后台会话的记录中，在代理视图中或附加后。
1334
1335<h3 id="commands-refused-in-a-background-session">
1336 后台会话中被拒绝的命令
1337</h3>
1338
1339打开交互式对话框的命令在后台会话中被拒绝，并显示一条消息，该消息要么命名一个在那里有效的表单，要么告诉您从常规终端运行该命令。`/install-github-app`、`/mcp` 设置列表和 MCP 服务器菜单中的身份验证操作都以这种方式被拒绝。在 v2.1.208 之前，它们在后台会话内打开其对话框。
1340{/* max-version: 2.1.208 */}在 v2.1.208 中，`/model` 选择器也在后台会话中被拒绝，`/upgrade` 打印升级 URL 而不是打开浏览器。
1341
1342措辞会命名被拒绝的命令。`/mcp` 设置列表报告：
1343
1344```text theme={null}
1345Can't open MCP settings in a background session — use `/mcp enable|disable|reconnect <server>` to steer, or run /mcp from an interactive terminal to authenticate.
1346```
1347
1348**应该怎么做：**
1349
1350* 使用消息命名的表单，例如 `/mcp reconnect <server>`、`/mcp enable` 或 `/mcp disable`
1351* 对于登录和授权流程，从终端中的常规 `claude` 会话运行该命令
1352
1353<h3 id="claude_code_process_wrapper-launcher-errors">
1354 CLAUDE\_CODE\_PROCESS\_WRAPPER 启动器错误
1355</h3>
1356
1357[`CLAUDE_CODE_PROCESS_WRAPPER`](/zh-CN/corporate-launcher) 已设置，其值无法使用，因此 Claude Code 拒绝启动受影响的进程，而不是在没有启动器的情况下运行它。配置问题会报告一条以变量名开头并说明原因的消息，例如：
1358
1359```text theme={null}
1360CLAUDE_CODE_PROCESS_WRAPPER: launcher `/opt/corp/launcher` is not an executable regular file
1361```
1362
1363启动但退出而不用 Claude Code 替换自身的启动器会导致它启动的会话失败，该会话在代理视图中的行报告启动器 `must exec, not daemonize`，后跟启动器打印的任何内容。由于启动器而无法启动或到达后台服务的会话会将启动器问题报告为 `Couldn't reach the background service (...)` 内的原因。
1364
1365**应该怎么做：**
1366
1367* 将变量设置为可执行文件的绝对路径，该文件以调用 `exec "$@"` 结尾。有关完整合同，请参阅[启动器合同](/zh-CN/corporate-launcher#the-launcher-contract)
1368* 检查 `/status`，它在其 Self-exec 条目中显示已解析的启动命令，并在运行的后台服务与其不匹配时发出警告，或从 shell 运行 `claude daemon status`
1369* 在[设置](/zh-CN/corporate-launcher#set-up-the-launcher)的 `env` 块中修复值后，使用 `claude daemon stop --any` 重启后台服务，以便下一次调度启动一个包装的服务
1142 1370
1143<h2 id="configuration-warnings">1371<h2 id="configuration-warnings">
1144 配置警告1372 配置警告
1150 工作区尚未被信任1378 工作区尚未被信任
1151</h3>1379</h3>
1152 1380
1153Claude 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` 条目，但未应用它们，因为[项目设置中的允许规则需要工作区信任](/zh-CN/permissions#project-allow-rules-and-workspace-trust)。消息中的计数、设置名称和文件名会根据您的配置而变化。`deny` 和 `ask` 规则不受影响。
1154 1382
1155```text theme={null}1383```text theme={null}
1156Ignoring 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.
1157```1385```
1158 1386
1159**应该怎么做：**1387**应该做什么：**
1160 1388
1161* 在目录中运行 `claude` 并接受信任对话框。{/* min-version: 2.1.200 */}即使父目录已被信任，对话框也会出现，列出被保留的规则，并让您可以拒绝并继续工作而不应用这些规则。在 v2.1.200 之前，在这种情况下不会出现对话框，因此无法在那里完成此步骤。1389* 在目录中运行 `claude` 并接受信任对话框。{/* min-version: 2.1.200 */}即使父目录已被信任，对话框也会出现，列出被保留的规则，并让您可以拒绝并继续工作而不应用这些规则。在 v2.1.200 之前，在这种情况下不会出现对话框，因此无法在那里完成此步骤。
1162* 在[非交互模式](/zh-CN/headless)中使用 `-p` 不会显示对话框。使用消息打印的确切 `projects` 键在 `~/.claude.json` 中设置 `hasTrustDialogAccepted` 条目。1390* 在[非交互模式](/zh-CN/headless)中使用 `-p` 不会显示对话框。使用消息打印的确切 `projects` 密钥在 `~/.claude.json` 中设置 `hasTrustDialogAccepted` 条目。
1163* {/* 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)。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)。
1164 1392
1165<h2 id="responses-seem-lower-quality-than-usual">1393<h2 id="responses-seem-lower-quality-than-usual">
1166 响应质量似乎低于预期1394 回复质量似乎低于预期
1167</h2>1395</h2>
1168 1396
1169如果 Claude 的回答似乎不如你预期的那样有能力，但没有显示错误，原因通常是对话状态而不是模型本身。Claude Code 不会无声地更改模型版本。它只能在三种特定情况下切换到备用模型：1397如果 Claude 的回答似乎不如你预期的那样有能力，但没有显示错误，原因通常是对话状态而不是模型本身。Claude Code 不会无声地更改模型版本。它只能在三种特定情况下切换到备用模型：
1170 1398
1171* 配置的 [`--fallback-model`](/zh-CN/cli-reference#cli-flags) 在可用性错误后接管该轮次，并在记录中显示通知1399* 配置的 [`--fallback-model`](/zh-CN/cli-reference#cli-flags) 在可用性错误后接管该轮，并在记录中显示通知
1172* Amazon Bedrock 或 Google Cloud 的 Agent Platform 启动检查发现你的默认模型不可用1400* Amazon Bedrock 或 Google Cloud 的 Agent Platform 启动检查发现你的默认模型不可用
1173* [自动模型备用](/zh-CN/model-config#automatic-model-fallback)在 Fable 5 上将会话移至默认 Opus 模型，并在记录中显示通知1401* [自动模型备用](/zh-CN/model-config#automatic-model-fallback)在 Fable 5 上将会话移至默认 Opus 模型，并在记录中显示通知
1174 1402
1175下面的模型选择检查捕获第二和第三种情况；第一种情况显示为记录通知而不是 `/model` 更改。[模型配置](/zh-CN/model-config)解释了每种备用何时适用。1403下面的模型选择检查捕获第二和第三种情况；第一种情况显示为记录通知而不是 `/model` 更改。[模型配置](/zh-CN/model-config)解释了每个备用何时适用。
1176 1404
1177首先检查这些：1405首先检查这些：
1178 1406
1179* **模型选择**：运行 `/model` 以确认你在预期的模型上。之前的 `/model` 选择或 `ANTHROPIC_MODEL` 环境变量可能使你在比预期更小的模型上。1407* **模型选择**：运行 `/model` 以确认你在预期的模型上。之前的 `/model` 选择或 `ANTHROPIC_MODEL` 环境变量可能使你在比预期更小的模型上。
1180* **努力级别**：运行 `/effort` 以检查当前推理级别，并为困难的调试或设计工作提高它。默认值因模型而异，所以在假设你低于最大值之前请检查。有关每个模型的默认值和 `ultrathink` 快捷方式，请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level)。1408* **努力级别**：运行 `/effort` 以检查当前推理级别，并为困难的调试或设计工作提高它。默认值因模型而异，所以在假设你低于最大值之前请检查。有关每个模型的默认值和 `ultrathink` 快捷方式，请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level)。
1181* **上下文压力**：运行 `/context` 以查看窗口有多满。如果接近容量，在自然断点处运行 `/compact` 或运行 `/clear` 以重新开始。有关自动压缩如何影响早期轮次的信息，请参阅[探索上下文窗口](/zh-CN/context-window)。1409* **上下文压力**：运行 `/context` 以查看窗口有多满。如果接近容量，在自然断点处运行 `/compact` 或运行 `/clear` 以重新开始。有关自动压缩如何影响早期轮次的信息，请参阅[探索上下文窗口](/zh-CN/context-window)。
1182* **过时的指令**：大型或过时的 `CLAUDE.md` 文件和 MCP 工具定义会消耗上下文并可能引导响应。{/* min-version: 2.1.205 */}`/doctor` 检查会标记超大内存文件和未使用的扩展，`/context` 显示 MCP 工具令牌使用情况。在 v2.1.205 之前，`/doctor` 打开一个诊断屏幕，标记超大内存文件和子代理定义。1410* **过时的指令**：大型或过时的 `CLAUDE.md` 文件和 MCP 工具定义会消耗上下文并可能引导回复。{/* min-version: 2.1.205 */}`/doctor` 检查会标记超大内存文件和未使用的扩展，`/context` 显示 MCP 工具令牌使用情况。在 v2.1.205 之前，`/doctor` 打开一个诊断屏幕，标记超大内存文件和子代理定义。
1183 1411
1184当响应出错时，回退通常比用更正进行回复效果更好。按两次 Esc 或运行 `/rewind` 以回到错误轮次之前，然后用更具体的内容重新表述提示。在线程中更正会将错误的尝试保留在上下文中，这可能会将后来的答案锚定到它。请参阅[检查点](/zh-CN/checkpointing)。1412当回复出错时，回退通常比用更正回复效果更好。按 Esc 两次或运行 `/rewind` 以回到坏轮之前，然后用更具体的内容重新表述提示。在线程中更正会将错误的尝试保留在上下文中，这可能会将后来的答案锚定到它。请参阅[检查点](/zh-CN/checkpointing)。
1185 1413
1186如果在检查上述内容后质量仍然似乎不对，请运行 `/feedback` 并描述你期望的内容与你得到的内容。以这种方式提交的反馈包括对话记录，这是 Anthropic 诊断真实回归的最快方式。如果 `/feedback` 在你的环境中不可用，请参阅[报告错误](#report-an-error)。1414如果在检查上述内容后质量仍然似乎有问题，运行 `/feedback` 并描述你期望的内容与你得到的内容。以这种方式提交的反馈包括对话记录，这是 Anthropic 诊断真实回归的最快方式。如果 `/feedback` 在你的环境中不可用，请参阅[报告错误](#report-an-error)。
1187 1415
1188{/* min-version: 2.1.201 */}如果 Sonnet 5 拒绝请求并在 Claude Code v2.1.200 或更早版本上引用可疑的提示注入，请运行 `claude update` 以获取 v2.1.201 修复。1416如果 Claude 警告可疑的提示注入，或因可疑注入而拒绝请求，并且警告命名的文本是 Claude Code 自动添加到对话中的上下文而不是文件或网络内容，运行 `claude update` 并重试。如果更新后警告重复出现，[报告它](#report-an-error)而不是将标记的内容粘贴回提示中。{/* min-version: 2.1.201 */}在 v2.1.201 之前，Sonnet 5 以相同的方式拒绝了一些请求。
1189 1417
1190<h2 id="report-an-error">1418<h2 id="report-an-error">
1191 报告错误1419 报告错误
1199 1427
1200如果此处未列出错误或建议的修复方法无法帮助：1428如果此处未列出错误或建议的修复方法无法帮助：
1201 1429
1202* 在 Claude Code 中运行 `/feedback` 将记录和描述发送给 Anthropic。该命令还提供打开预填充的 GitHub issue 的选项。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和其他第三方提供商上，`/feedback` 保存本地存档，您可以将其发送给您的 Anthropic 账户代表。1430* 在 Claude Code 中运行 `/feedback` 将记录和描述发送给 Anthropic。该命令还提供打开预填充的 GitHub issue 的选项。发送到 Anthropic 需要[身份验证](/zh-CN/authentication)。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和其他第三方提供商上，或者当未配置 Anthropic 凭证时，`/feedback` 会保存一个本地存档，您可以将其发送给您的 Anthropic 账户代表。
1203* 从您的 shell 运行 `claude doctor` 以获取安装的只读诊断，或在 Claude Code 中运行 `/doctor` 检查以查找和修复设置问题1431* 从您的 shell 中运行 `claude doctor` 以获取安装的只读诊断，或在 Claude Code 中运行 `/doctor` 检查以查找和修复设置问题
1204* 检查 [status.claude.com](https://status.claude.com) 以了解活跃事件1432* 检查 [status.claude.com](https://status.claude.com) 以了解活跃的事件
1205* 在 GitHub 上搜索[现有 issue](https://github.com/anthropics/claude-code/issues)1433* 在 GitHub 上搜索[现有问题](https://github.com/anthropics/claude-code/issues)
