Claude Code 运行时错误包括服务器错误、使用限制、认证错误、网络连接错误、请求错误等。每个错误都附有解决方法，可通过运行 /status、/context、/model 等命令验证状态，并通过环境变量 CLAUDE_CODE_MAX_RETRIES 和 API_TIMEOUT_MS 调整自动重试行为。先查错误速查表定位你的问题。

Claude Code 运行时错误排查与解决方法 #

本页列出 Claude Code 显示的运行时错误以及如何修复，以及当响应异常但没有报错时该检查什么。安装时遇到 command not found 或 TLS 失败等安装错误，请参见安装与登录故障排查。

以下错误和恢复命令适用于 CLI、桌面应用和 Web 版 Claude Code，三者都基于同一 CLI。针对特定界面的问题，请查看对应界面的故障排查章节。

Claude Code 调用 Claude API 获取模型响应，因此大多数运行时错误对应底层 API 错误码。本页说明每个错误在 Claude Code 中的含义及恢复方法。原始 HTTP 状态码定义见 Claude Platform 错误参考。

错误速查表 #

根据终端显示的提示信息，匹配到对应章节。

自动重试 #

Claude Code 在显示错误之前会重试临时性故障。服务器错误、过载响应、请求超时、临时 429 限速以及中断连接都会以指数退避方式重试最多 10 次。重试时，旋转指示器会显示 Retrying in Ns · attempt x/y 倒计时。

当你看到本页列出的错误时，说明重试已全部耗尽。你可以通过两个环境变量调整行为：

服务器错误 #

这些错误来自推理提供方（而非你的账户或请求）。Anthropic API 指 Anthropic 基础设施；Bedrock、Vertex AI、Foundry 或自定义网关指对应提供方的基础设施。

API Error: 500 Internal server error #

Claude Code 为任何 5xx 响应显示状态码和 API 的错误信息。以下示例为 Anthropic API 上的 500 响应：

API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check status.claude.com.

末尾的句子会根据提供方不同而指示服务健康状况查询地址。Bedrock、Vertex AI 和 Foundry 配置会显示对应提供方的服务状态；自定义 ANTHROPIC_BASE_URL 会显示网关主机。

这表明 API 内部发生了意外故障，与你的提示词、设置或账户无关。

处理方法：

• 查看 status.claude.com 或消息中提到的提供方状态页面，确认是否存在正在处理的事件
• 等待一分钟，然后重新发送你的消息。你的原始消息仍在对话中，对于较长的提示，可直接输入 try again 而无需重新粘贴。
• 如果错误持续出现且未公布事件，运行 /feedback 以便 Anthropic 根据你的请求详情进行调查。如果环境中无法使用 /feedback，参考报告错误。

API Error: Repeated 529 Overloaded errors #

API 暂时对所有用户达到容量上限。Claude Code 已多次重试后显示此消息：

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check status.claude.com.

末尾的句子与 500 错误类似，因提供方而异。529 错误不是你的使用限制，也不抵扣配额。

处理方法：

• 查看 status.claude.com 或消息中提到的提供方状态页面，确认容量通知
• 几分钟后重试
• 运行 /model 切换到不同模型（容量按模型统计）。当某个模型负载特别高时，Claude Code 会提示你切换，例如 Opus is experiencing high load, please use /model to switch to Sonnet。

Request timed out #

API 在连接截止前未响应。

Request timed out

可能发生在高负载时期或生成非常大的响应时。默认请求超时为 10 分钟。

处理方法：

• 重试请求
• 对于长时间运行的任务，将工作拆分为多个小提示
• 如果原因是慢速网络或代理，按自动重试中的描述调高 API_TIMEOUT_MS
• 如果超时频繁且网络正常，参见下方的网络连接错误

Auto mode 无法判断操作安全性 #

auto mode 用于分类操作的模型无法产生决策，因此 auto mode 未自动批准该操作。根据分类器失败原因，你会看到不同消息。

对工作目录内的读取、搜索和编辑操作会跳过分类器，因此这些操作在所有情况下都能继续工作。

分类器模型过载时：

<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait briefly and then try this action again.

处理方法：

• 几秒后重试；Claude 看到相同消息后通常会自行重试
• 如果持续失败，先处理只读任务，稍后再回来处理被阻止的操作
• 这是临时性问题，与 auto mode 资格无关，无需更改设置

分类器返回无法解析的响应时：

Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details

处理方法：

• 重试该操作；通常下一次会成功
• 运行 claude --debug 并重复该操作，查看调试日志中的底层分类器响应

对话超出分类器上下文窗口时：

Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)

在交互式会话中，auto mode 会退化为正常权限提示，由你手动批准或拒绝该操作。在非交互模式下运行会中止，因为对话只会增长，重试无法成功。

处理方法：

• 在出现的提示中批准或拒绝该操作
• 运行 /compact 减小对话大小，使后续操作重新适配分类器窗口

使用限制 #

这些错误表示已达到与账户或计划相关的配额。它们不同于影响所有人的服务器错误。

You’ve hit your session limit #

订阅计划包含滚动使用额度。用完后你会看到以下消息之一：

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm

在消息显示的恢复时间之前，Claude Code 会阻止进一步请求。

处理方法：

• 等待错误中显示的恢复时间
• 运行 /usage 查看你的计划限制和恢复时间
• 运行 /usage-credits 购买 Pro 和 Max 的额外使用量，或向 Team 和 Enterprise 管理员申请。关于计费方式，参见付费计划的额外使用量
• 要升级计划以获得更高基础限额，参见 claude.com/pricing

要在达到限制前监控剩余额度，可将 rate_limits 字段添加到自定义状态行，或在桌面应用中点击模型选择器旁的使用量环。

Server is temporarily limiting requests #

API 应用了短时限制，与你的计划配额无关。

API Error: Server is temporarily limiting requests (not your usage limit)

此情况在显示前会经过自动重试。

处理方法：

• 稍等片刻后重试
• 如果持续，查看 status.claude.com

Request rejected (429) #

已达到 API 密钥、Amazon Bedrock 项目或 Google Vertex AI 项目的速率限制。

API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check status.claude.com.

末尾的句子因提供方而异。Bedrock、Vertex AI 和 Foundry 配置会显示对应提供方的服务状态页面，而非 Anthropic 状态页面。自定义 ANTHROPIC_BASE_URL 会显示网关主机。

处理方法：

• 运行 /status 确认当前使用的凭证是否为预期凭证。环境中残留的 ANTHROPIC_API_KEY 可能将请求路由到低层级密钥，而非你的订阅。
• 在提供方控制台查看当前限制，需要时申请更高层级
• 对于 Anthropic API 密钥，参见速率限制参考了解层级工作方式以及如何设置工作空间上限
• 降低并发：调低 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY，避免运行多个并行子代理，或通过 /model 切换到较小的模型用于高并发脚本执行

Credit balance is too low #

你的控制台组织预付费余额已用尽。

Credit balance is too low

处理方法：

• 在 platform.claude.com/settings/billing 添加余额，并考虑启用自动充值，以便在余额归零前补充
• 如果你有 Pro、Max、Team 或 Enterprise 计划，使用 /login 切换到订阅认证
• 在控制台中为每个工作空间设置支出上限，防止单个项目耗尽组织余额。参见有效管理成本

认证错误 #

这些错误表示 Claude Code 无法向 API 证明你的身份。随时运行 /status 可查看当前使用的凭证。

Not logged in #

当前会话没有有效凭证。

Not logged in · Please run /login

处理方法：

• 运行 /login 使用你的 Claude 订阅或控制台账户进行认证
• 如果你期望环境变量进行认证，确认 ANTHROPIC_API_KEY 已在启动 claude 的 shell 中设置并导出
• 对于 CI 或自动化环境（无法交互登录），配置一个 apiKeyHelper 脚本，在启动时获取密钥
• 参见认证优先级了解多个凭证并存时的优先级规则

如果反复提示登录，参见未登录或令牌过期进行系统时钟和 macOS 钥匙串修复。

Invalid API key #

ANTHROPIC_API_KEY 环境变量或 apiKeyHelper 脚本返回的密钥被 API 拒绝。

Invalid API key · Fix external API key

处理方法：

• 检查拼写，确认密钥未在控制台中被吊销
• 在相同 shell 中运行 env | grep ANTHROPIC。direnv、dotenv shell 插件和 IDE 终端可能从项目的 .env 文件中加载了过期密钥，而你可能并未显式设置它。
• 取消设置 ANTHROPIC_API_KEY 并运行 /login 改用订阅认证
• 如果密钥来自 apiKeyHelper 脚本，直接运行该脚本确认它在 stdout 上打印有效密钥
• 运行 /status 确认 Claude Code 实际使用的凭证源

This organization has been disabled #

来自已禁用的控制台组织的过期 ANTHROPIC_API_KEY 覆盖了你的订阅登录。

Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your other credentials
API Error: 400 ... This organization has been disabled.

环境变量优先级高于 /login，因此即使你有可用的 Pro 或 Max 订阅，shell 配置文件或 .env 文件中导出的密钥也会被使用。在非交互模式（-p）下，密钥存在时总是被使用。

处理方法：

• 在当前 shell 中取消设置 ANTHROPIC_API_KEY，并从 shell 配置文件中移除，然后重新启动 claude
• 之后运行 /status 确认当前凭证是你的订阅
• 如果未设置环境变量但错误仍然存在，说明被禁用的组织与你的 /login 关联。联系支持或使用不同账户登录。

Your organization has disabled Claude subscription access #

你的 Claude 组织不允许使用订阅登录方式访问 Claude Code。使用相同账户再次运行 /login 将返回相同错误。

Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access

这是服务端组织设置，无法从本地设置、环境变量或 CLI 标志覆盖。Agent SDK 和 -p 非交互模式将此错误代码显示为 oauth_org_not_allowed。

处理方法：

• 请管理员为你的组织启用 Claude Code 访问
• 使用控制台 API 密钥认证，而非订阅。设置方法参见 Claude Console 认证
• 如果你是管理员，但未看到启用选项，请联系 Anthropic 支持

Routines are disabled by your organization’s policy #

你的团队或企业管理员已在组织层面关闭了 routines。当你尝试创建或运行 routine 时会出现此错误，包括从 /schedule 和 claude.ai/code 上的 Routines UI 操作。

Routines are disabled by your organization's policy.

这是服务端设置，无法从本地设置、环境变量或 CLI 标志覆盖。

处理方法：

• 请管理员在 claude.ai/admin-settings/claude-code 启用 Routines 开关
• 对于不需要组织级 routines 的一次性计划任务，参见定时任务

OAuth token 被撤销或过期 #

你保存的登录信息不再有效。被撤销的令牌表示你已在所有设备上登出，或管理员移除了访问权限；过期的令牌表示会话期间自动刷新失败。

OAuth token revoked · Please run /login
OAuth token has expired · Please run /login
API Error: 401 ... authentication_error

处理方法：

• 运行 /login 重新登录
• 如果重新认证后同一会话中又出现错误，先运行 /logout 完全清除存储的令牌，再运行 /login
• 如果跨启动反复提示登录，参见故障排查中的系统时钟和 macOS 钥匙串检查
• 对于其他失败（包括 403 Forbidden 和 OAuth 浏览器问题），参见登录与认证

OAuth scope requirement #

存储的令牌缺少新功能所需的权限作用域。最常见的情况来自 /usage 和状态行使用量指示器：

OAuth token does not meet scope requirement: user:profile

处理方法：

• 运行 /login 生成一个包含当前作用域的新令牌。不需要先登出。

网络连接错误 #

这些错误表示 Claude Code 的网络请求未能到达目标。通常源于本地网络、代理、防火墙，或云环境的网络策略。

Unable to connect to API #

TCP 连接 API 失败或从未完成。

Unable to connect to API. Check your internet connection
Unable to connect to API (ECONNREFUSED)
Unable to connect to API (ECONNRESET)
Unable to connect to API (ETIMEDOUT)
fetch failed
Request timed out. Check your internet connection and proxy settings

常见原因包括无网络访问、VPN 屏蔽 api.anthropic.com，或未配置必需的代理。

处理方法：

• 在同一 shell 中运行 curl -I https://api.anthropic.com 确认能否访问 API 主机。Windows PowerShell 使用 curl.exe -I https://api.anthropic.com 以避免触发内置的 Invoke-WebRequest 别名。
• 如果位于企业代理后，在启动 Claude Code 前设置 HTTPS_PROXY，参见网络配置
• 如果通过 LLM 网关或中继路由，设置 ANTHROPIC_BASE_URL 为其地址。设置方法参见 LLM 网关配置
• 确保防火墙允许网络访问要求中列出的主机
• 间歇性故障会自动重试；持续性故障指向本地网络问题

如果 curl 成功但 Claude Code 仍失败，原因通常是运行时与网络之间的问题而非网络本身：

• Linux 和 WSL：检查 /etc/resolv.conf 中是否存在不可达的域名服务器。WSL 可能从主机继承损坏的解析器。
• macOS：已断开或卸载的 VPN 客户端可能留下隧道接口或路由规则。检查 ifconfig 中是否存在过时的 utun 接口，并在系统设置中移除 VPN 的网络扩展。
• Docker Desktop 及类似容器运行时可能拦截出站流量。退出并重试以排除此原因。

SSL 证书错误 #

你网络中的代理或安全设备正使用自己的证书拦截 TLS 流量，而 Claude Code 不信任该证书。

Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates
Unable to connect to API: Self-signed certificate detected

处理方法：

• 导出你组织的 CA 捆绑包，并通过 NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem 指向 Claude Code。完整设置参见网络配置
• 不要设置 NODE_TLS_REJECT_UNAUTHORIZED=0，这会完全禁用证书验证

Host not allowed in a cloud session #

云会话或 routine 中的出站 HTTP 请求被环境网络策略阻止。

HTTP 403
x-deny-reason: host_not_allowed

你可能会看到与目标实际证书不匹配的 TLS 证书。云环境通过执行网络策略的代理路由出站流量，因此证书不匹配意味着代理终止了连接，而非目标。

这不是客户端网络问题。云会话和 routines 运行在沙箱环境中，出站流量被过滤为环境的允许列表。Default 环境使用 Trusted 访问，允许默认允许列表中的包注册表、云提供方 API、容器注册表和常见开发域名，但阻止所有其他内容。

处理方法：

• 打开 routine 编辑，或启动一个云会话。点击显示环境名称（如 Default）的云图标，打开选择器。悬停到你的环境并点击设置图标。
• 在 Update cloud environment 对话框中，将 Network access 从 Trusted 改为 Custom，然后将被阻止的域名添加到 Allowed domains。每行一个域名。勾选 Also include default list of common package managers 以在自定义域名旁保留默认允许列表。如果你希望无限制访问，选择 Full。
• 点击 Save changes。下次运行时将使用更新后的允许列表。

参见网络访问了解访问级别和默认允许列表。本地 CLI 会话不受此策略影响。

请求错误 #

这些错误表示 API 已收到你的请求但拒绝了其内容。

Prompt is too long #

对话加上附件内容超过了模型的上下文窗口。

Prompt is too long

处理方法：

• 运行 /compact 总结早期对话并释放空间，或 /clear 重新开始
• 运行 /context 查看哪些部分占用了窗口：系统提示、工具、记忆文件、消息
• 使用 /mcp disable <name> 禁用未使用的 MCP 服务器，从上下文中移除其工具定义
• 缩减大型 CLAUDE.md 记忆文件，或将指令移至路径限定规则，使其只在相关时加载
• 子代理会继承父会话的所有 MCP 工具定义，这可能在第一个回合前就填满其上下文窗口。生成子代理前禁用未使用的 MCP 服务器。
• 自动压缩默认开启，通常可防止此错误。如果你设置了 DISABLE_AUTO_COMPACT，需重新启用，或在窗口填满前手动运行 /compact

参见探索上下文窗口了解上下文是如何填满的。

Error during compaction: Conversation too long #

/compact 本身失败，因为没有足够的空闲上下文来容纳它生成的摘要。

Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.

这可能在自动压缩触发时窗口已满，或你在看到 Prompt is too long 后运行 /compact 时发生。

处理方法：

• 按两次 Esc 打开消息列表，后退几个回合。这会从上下文中丢弃最近的消息。然后再次运行 /compact。
• 如果后退不足以释放足够空间，运行 /clear 开始新会话。之前的对话会保留，可通过 /resume 重新打开。

Request too large #

原始请求体超过了 API 的字节限制，通常由粘贴的大文件或附件导致。

Request too large (max 30 MB). Double press esc to go back and remove or shrink the attached content.

这是 HTTP 请求的大小限制，与上下文窗口限制不同。

处理方法：

• 按两次 Esc，后退到添加了过大内容的回合之前
• 通过路径引用大文件而非粘贴其内容，以便 Claude 分块读取
• 对于图片，参见下方的Image was too large

Image was too large #

粘贴或附加的图片超过了 API 的大小或尺寸限制。

Image was too large. Double press esc to go back and try again with a smaller image.
API Error: 400 ... image dimensions exceed max allowed size

错误发生后图片仍会保留在对话历史中，因此后续每条消息都会因相同错误失败，直到你移除该图片。

处理方法：

• 按两次 Esc，后退到添加图片的回合之前
• 粘贴前调整图片大小。API 对单张图片最长边接受最多 8000 像素，当上下文中有多张图片时最长边为 2000 像素。
• 截取相关区域的更小截图，而非全屏

Unable to resize image #

Claude Code 无法在发送给 API 前缩小附加的图片。

Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.
Unable to resize image — dimensions exceed the 2000x2000px limit and image processing failed. Please resize the image to reduce its pixel dimensions.
Unable to resize image (… raw, … base64). The image exceeds the … API limit and compression failed. Please resize the image manually or use a smaller image.
Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.

Claude Code 通常会自动缩小大图片。这些错误意味着原生图片处理器未能加载或返回错误，因此无法将图片缩放到 API 限制内。

处理方法：

• 如果消息要求你转换图片，将其转换为 PNG、JPEG、GIF 或 WebP 并重新附加。Claude Code 无需图片处理器即可验证这些格式的尺寸。
• 如果消息报告维度或大小限制，在附加前将图片缩放或压缩到该限制以下。

PDF errors #

你附加的 PDF 无法处理。

PDF too large (max 100 pages, 32 MB). Try splitting it or extracting text first.
PDF is password protected. Try removing protection or extracting text first.
The PDF file was not valid. Try converting to a different format first.

处理方法：

• 对于过大的 PDF，要求 Claude 使用 Read 工具读取特定页面范围（而非附加整个文件），或使用 pdftotext 等工具提取文本并通过路径引用输出文件
• 对于受保护或无效的 PDF：移除密码或从其源应用中重新导出文件，然后重试

Extra inputs are not permitted #

Claude Code 与 API 之间的代理或 LLM 网关剥离了 anthropic-beta 请求头，导致 API 拒绝了依赖该头的字段。

API Error: 400 ... Extra inputs are not permitted ... context_management
API Error: 400 ... Extra inputs are not permitted ... tools.0.custom.input_examples
API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header

Claude Code 发送 beta 专属字段（如 context_management、effort、工具 input_examples），同时附带启用这些字段的 anthropic-beta 头。当网关转发请求体但丢弃头时，API 看到无法识别的字段。

处理方法：

• 配置你的网关转发 anthropic-beta 头。参见 LLM 网关配置
• 作为后备，在启动前设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。这会禁用需要 beta 头的功能，使请求能够通过无法转发该头的网关。

There’s an issue with the selected model #

配置的模型名称无法识别，或你的账户没有访问权限。

There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to select a different one.

处理方法：

• 运行 /model 从你的账户可用的模型中选择
• 使用别名（如 sonnet 或 opus）而非完整的版本 ID。别名会跟踪最新版本，不会过期。参见模型配置
• 如果错误的模型持续出现，说明某个地方设置了过时的 ID。按优先级顺序检查：--model 标志、ANTHROPIC_MODEL 环境变量、model 字段（在 .claude/settings.local.json、项目的 .claude/settings.json、~/.claude/settings.json 中）。移除过时值后，Claude Code 会回退到账户默认模型。
• 对于 Vertex AI 部署，参见 Vertex AI 故障排查

Claude Opus is not available with the Claude Pro plan #

你的活跃订阅计划不包含选择的模型。

Claude Opus is not available with the Claude Pro plan · Select a different model in /model

处理方法：

• 运行 /model 选择计划中包含的模型
• 如果你最近升级了计划但仍看到此错误，运行 /logout 然后 /login。存储的令牌反映的是登录时的计划，因此在网站上升级后，需重新认证才会生效。
• 参见 claude.com/pricing 查看各计划包含的模型

thinking.type.enabled is not supported for this model #

你的 Claude Code 版本低于 Opus 4.7 的最低要求。CLI 发送了模型不再接受的思考配置。

API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

处理方法：

• 运行 claude update 升级到 v2.1.111 或更高版本，然后重启 Claude Code
• 如果无法升级，运行 /model 选择 Opus 4.6 或 Sonnet
• 如果在 Agent SDK 中遇到此问题，参见 SDK 故障排查

Thinking budget exceeds output limit #

配置的扩展思考预算超过了最大响应长度，导致没有空间留给实际答案。

API Error: 400 ... max_tokens must be greater than thinking.budget_tokens

在 Anthropic API 上，Claude Code 会自动调整这些值。你通常在 Amazon Bedrock 或 Google Vertex AI 上看到此错误，当 MAX_THINKING_TOKENS 设置高于提供方的输出限制时，或计划模式提高思考预算时。

处理方法：

• 降低 MAX_THINKING_TOKENS，或将 CLAUDE_CODE_MAX_OUTPUT_TOKENS 提升到思考预算以上
• 参见扩展思考了解如何平衡预算与输出长度

Tool use or thinking block mismatch #

对话历史以不一致的状态到达 API，通常是因为工具调用被中断或回合在过程中被编辑。

API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.
API Error: 400 ... unexpected `tool_use_id` found in `tool_result` blocks
API Error: 400 ... thinking blocks ... cannot be modified

三种变体含义相同：历史中的 tool_use、tool_result 和 thinking 块序列不再匹配 API 的期望。

处理方法：

• 运行 /rewind 或按两次 Esc，后退到损坏回合之前的检查点并继续。参见检查点了解如何创建和恢复检查点。

Usage Policy refusal #

API 拒绝响应，因为对话中的内容触发了使用政策检查。消息包含一个 Request ID，如果你认为拒绝有误，可向支持团队提供该 ID。

API 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.

检查评估的是整个对话，而不仅仅是你的最新提示，因此在同一会话中发送新消息通常会再次触发相同拒绝。退出后使用 --continue 或 --resume 重新打开会话也是如此，因为磁盘上的转录仍然包含触发内容。

处理方法：

• 按两次 Esc 或运行 /rewind，后退到触发拒绝的回合之前的检查点，然后重新措辞或采取其他方法。参见检查点
• 如果你无法确定是哪个回合导致的，运行 /clear 在相同项目中开始新对话。之前的对话会保留在磁盘上，可通过 /resume 恢复。
• 在非交互模式（-p）下，无法使用 rewind，请重试并换用更安全的提示，或在不带 --continue 的情况下启动新会话。

响应质量低于预期 #

如果 Claude 的答案不如预期但不显示错误，原因通常是对话状态而非模型本身。Claude Code 不会静默更改模型版本。在特定情况下（如 Opus 配额用尽、Bedrock 或 Vertex AI 区域缺少模型）可能会切换到回退模型；下面的模型选择检查可覆盖两种情况，模型配置说明了何时应用回退。

首先检查以下项：

• 模型选择：运行 /model 确认你使用的是期望的模型。之前通过 /model 选择的模型或 ANTHROPIC_MODEL 环境变量可能让你用上了较小的模型。
• 努力级别：运行 /effort 查看当前的推理级别，进行困难调试或设计工作时可调高。默认值因模型而异，因此在假设未达到最大值前先检查。参见调整努力级别了解每模型默认值和 ultrathink 快捷方式。
• 上下文压力：运行 /context 查看窗口剩余空间。如果接近容量，在自然断点处运行 /compact 或 /clear 重新开始。参见探索上下文窗口了解自动压缩如何影响早期回合。
• 指令过期：过大的或过时的 CLAUDE.md 文件以及 MCP 工具定义会消耗上下文并可能干扰回答。/doctor 会标记过大的记忆文件和子代理定义；/context 显示 MCP 工具的令牌使用量。

当响应出现问题时，后退通常比在问题后回复修正更有效。按两次 Esc 或运行 /rewind，后退到错误回合之前，然后用更多细节重新措辞提示。在对话线程中直接纠正会使错误尝试留在上下文中，可能影响后续回答。参见检查点。

如果检查上述项目后质量仍然异常，运行 /feedback 并描述你期望的结果与实际结果。以此方式提交的反馈包含对话转录，是 Anthropic 诊断真实回退最快的方式。如果环境中无法使用 /feedback，参见下方的报告错误。

报告错误 #

本页涵盖来自 Claude API 的错误。对于其他 Claude Code 组件的错误，请参见相应指南：

• MCP 服务器连接或认证失败：MCP
• Hook 脚本失败或阻止工具：调试 Hooks
• 安装时权限被拒绝或文件系统错误：安装与登录故障排查

如果此处未列出某个错误，或建议的修复无效：

• 在 Claude Code 中运行 /feedback，将转录和描述发送给 Anthropic。该命令还可以打开预填的 GitHub Issue。在 Bedrock、Vertex AI、Foundry 及其他第三方提供方上，/feedback 会保存本地存档，你可以将其发送给你的 Anthropic 客户代表。
• 运行 /doctor 检查本地配置问题
• 查看 status.claude.com 了解已报告的事件
• 在 GitHub 上搜索已有 Issue

常见问题 #

Claude Code 报错 “API Error: 500” 怎么办？ #

这是 API 内部临时故障，与你无关。先查看 status.claude.com 确认是否有事件，等待一分钟后重试。如果持续且无公告，运行 /feedback 向 Anthropic 提交详情。

Claude Code 提示 “Not logged in” 如何解决？ #

运行 /login 使用你的 Claude 订阅或控制台账户登录。如果期望 API 密钥认证，确认 ANTHROPIC_API_KEY 已在启动 shell 中设置并导出。反复提示登录时，检查系统时钟和 macOS 钥匙串（参见安装与登录故障排查）。

Claude Code 上下文窗口太大导致 “Prompt is too long” 怎么处理？ #

运行 /compact 压缩对话，或 /clear 清空后重新开始。使用 /context 查看哪些部分占用最大（系统提示、工具定义、记忆文件、消息），禁用不必要的 MCP 服务器（/mcp disable <name>）并缩减 CLAUDE.md 文件。自动压缩默认开启，不要关闭 DISABLE_AUTO_COMPACT。