错误参考

查找 Claude Code 运行时错误消息，了解每个错误的含义以及如何修复。

本页列出 Claude Code 显示的运行时错误以及如何从每个错误中恢复，以及当响应似乎有问题但没有错误时要检查的内容。对于安装错误（如 command not found 或设置期间的 TLS 失败），请参阅排查安装和登录问题。

除了包装器和 IDE 错误（由启动程序打印而不是 Claude Code 本身打印）外，这些错误和恢复命令适用于 CLI、桌面应用和云会话，因为这三个都包装相同的 Claude Code CLI。对于其他表面特定的问题，请参阅该表面页面上的故障排除部分。

查找您的错误

将您看到的消息与下面的部分相匹配。

自动重试

Claude Code 在显示错误之前，会以指数退避方式重试瞬时故障最多 10 次。它并不总是重试在 Claude 响应过程中途出现的故障。当您看到本页面上的错误之一时，Claude Code 已经对该故障进行了适用的重试；下面的列表说明哪些故障获得完整预算、哪些获得较小预算，以及哪些不获得预算。

Claude Code 重试这些故障：

• 在 Claude 响应开始流式传输之前到达的服务器错误、过载响应和请求超时。
• 连接断开。当连接在请求过程中途断开，且 Claude 尚未完成其响应的任何部分（包括其思考过程）时，Claude Code 会使用相同的退避重新发送请求，转换继续进行，即使某些文本已经开始流式传输。当连接在 Claude 完成思考之后但在开始任何文本或工具调用之前断开时，Claude Code 改为快速连续重新发送请求最多两次，如果连接在该点继续断开，则以 Connection lost before a response was produced 结束转换。
• Claude Code 检测到的连接在您的计算机进入睡眠状态时在请求过程中途被破坏。Claude Code 将其计为上述规则下的断开连接；一旦重试标签命名了具体原因，它会读作 Connection lost while your computer was asleep，如果转换在 Claude 完成思考之后但在任何文本或工具调用之前结束，消息会读作 Your computer went to sleep before a response was produced。
• 停滞的响应流，当响应头已到达但 Claude 响应的任何部分都未到达，或当 Claude 完成思考但尚未开始任何文本或工具调用时：Claude Code 中止停滞连接并最多重新发送一次请求，不在上述 10 次尝试预算之外。如果响应在 Claude 完成思考之后但在任何文本或工具调用之前第二次停滞，Claude Code 以 The response stalled before a response was produced 结束转换。
• 流式请求 API 从未用响应头回答，在 first-byte deadline runs 的连接上：Claude Code 在截止时间中止它，并在重试预算内每个模型请求最多重新发送一次，然后如果该尝试也未得到回答，则以 No response from API 结束转换。在其他连接上，请求等待 API_TIMEOUT_MS。当您设置 CLAUDE_CODE_RETRY_WATCHDOG 时，一次重试上限不适用。
• 临时 429 节流，但不是网关的支出限制 429，这不是节流；请参阅 Spend limit reached。
  • 当您使用 claude.ai 订阅登录时，这包括不携带您计划配额头的 429 节流。在 v2.1.199 之前，Claude Code 仅对 API 密钥和企业登录重试这些节流。
• 因为输入加上 max_tokens 超过上下文限制而被拒绝的请求。以相同方式重新发送它会以相同方式失败，所以 Claude Code 使用减少的 max_tokens 重试，并在两种情况下停止重试并改为压缩：
  • 当没有减少可以适应时，例如当对话本身几乎填满上下文窗口时。
  • 当重试无法进一步缩小 max_tokens 时。在 v2.1.218 之前，Claude Code 可以重新发送仍然不适应的减少请求，例如当扩展思考预算超过剩余上下文时，直到重试预算用尽。
• Google Cloud 的 Agent Platform 上过期或缺失的 Google Cloud 凭证，或在您的机器上加载失败的 AWS 凭证。Claude Code 丢弃其缓存的凭证并重试最多两次，然后报告错误以便您可以立即重新身份验证，如 Could not load AWS or Google Cloud credentials 下所述。在 v2.1.228 之前，Claude Code 通过完整重试预算重试失败的 Google Cloud 凭证，然后显示错误。
• 来自 Anthropic API 的 401 或 403，直接或通过 LLM gateway，而 apiKeyHelper 脚本提供凭证。Claude Code 重新运行脚本并使用其新输出重试，在完整重试预算内。当脚本本身在重新运行时失败时，Claude Code 改为显示 Your apiKeyHelper script is failing。

在 v2.1.227 之前，Connection lost before a response was produced 读作 Connection closed while thinking, before producing a response，The response stalled before a response was produced 读作 Response stalled while thinking, before producing a response。

Claude Code 不重试这些故障：

• TLS 证书验证失败，例如 TLS 检查代理、缺失的 NODE_EXTRA_CA_CERTS 包或过期的证书。Claude Code 在第一次尝试时报告错误，以便您可以立即修复证书设置；请参阅 SSL certificate errors。Claude Code 仍然重试瞬时 TLS 条件，例如握手超时。在 v2.1.199 之前，Claude Code 通过完整重试预算重试证书失败，然后显示错误。
• 服务器错误、断开连接或停滞流在 Claude 完成文本块或工具调用之后到达，或在完成思考之后开始一个但在完成响应之前。Claude Code 不重新运行请求，因为这可能会执行相同的工具调用两次。它保留 Claude 完成的内容，运行 Claude 完成的任何工具调用，并从其结果继续转换。对于您在交互式会话和非交互式会话中看到的内容，请阅读 The response above may be incomplete。在 v2.1.199 之前，当服务器错误在流中途到达时，Claude Code 丢弃部分输出并将整个转换报告为错误。
• 在 Claude 完成响应之后到达的故障：无需重试任何内容，所以 Claude Code 保留完整响应并正常结束转换。
• Amazon Bedrock 流式响应具有意外的 content-type，因为重写响应的网关或代理会以相同方式重写重试。需要 Claude Code v2.1.208 或更高版本。
• 失败的流式请求的非流式重试获得成功状态但 body 中没有 Claude API 消息。Claude Code 以该错误结束转换。
• 您的组织的策略检查拒绝的请求，其表现为携带拒绝消息的 API Error: 行。您的组织管理员使用 Inference hooks（Claude Enterprise 功能）设置检查，消息以他们配置的说明结尾，或默认告诉您联系他们。Claude Code 不会将拒绝的请求重新发送到相同模型或 fallback model，因为拒绝涉及请求的内容而不是模型。在 v2.1.239 之前，Claude Code 可以重新发送拒绝的请求，不流式传输或在配置的备用模型上，然后向您显示拒绝。

Claude Code 重试或等待时您看到的内容

重试时，微调器在错误标签后显示 Retrying in Ns · attempt x/y 倒计时。标签命名第一次尝试的具体原因，用于您可以立即采取行动的故障：网络已关闭、TLS 握手失败或您达到速率限制。对于其他错误，它最初读作 API error。从 v2.1.198 开始，它切换到第三次尝试的具体原因，或当 CLAUDE_CODE_MAX_RETRIES 允许少于三次时在最后一次尝试；较早版本仅在最后一次尝试时切换。

从 v2.1.198 开始，通常的微调器提示在重试期间被抑制。一旦错误原因被揭示，如果故障是 529 过载，倒计时下方的行也命名了检查服务状态的位置：Anthropic API 上的 status.claude.com，或其他配置上的提供商或网关主机。

如果在请求仍然待处理时响应流上 20 秒内没有数据到达，微调器显示 Waiting for API response · will retry in … · check your network，然后任何重试都尚未开始。请求尚未失败：倒计时运行到 Claude Code 中止停滞连接的点。中止后，您看到的内容取决于响应已进行的距离：

• 在 Claude 完成文本块或工具调用之前，或在完成思考之后开始一个，Claude Code 重试请求或以错误结束转换。Automatic retries 说明它重试哪些停滞以及多少次。
• 在 Claude 完成文本块或工具调用之后，或在完成思考之后开始一个，但在 Claude 完成响应之前，Claude Code 保留 Claude 完成的内容，从 Claude 完成的任何工具调用继续转换，并显示 The response above may be incomplete。在非交互式会话中，以及对于任何会话中的子代理响应，Claude Code 可能首先提示 Claude 继续响应；该条目说明何时执行以及何时您仍然在那里看到通知。
• 在 Claude 完成响应之后，Claude Code 正常结束转换。

一旦数据恢复或重试成功，横幅会自动清除。如果它在每次尝试时重新出现，将其视为 network issue。在 v2.1.185 之前，横幅在 10 秒后出现，措辞不同。

当 Claude 咨询 advisor 时，横幅在 90 秒无数据后出现，而不是 20 秒，因为长时间的顾问审查可以发送超过 20 秒的任何内容。在 v2.1.214 之前，20 秒阈值也适用于顾问调用，所以横幅在顾问审查期间出现，即使没有任何问题。

调整重试行为

您可以使用这些环境变量调整重试行为：

服务器错误

这些错误中的大多数来自推理提供商：Anthropic API 上的 Anthropic 服务，以及 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自定义网关上该提供商端点后面的服务。Auto mode 无法确定操作的安全性和Agent 因 API 错误而提前终止也涵盖了您这一方的原因，例如无法调用分类器模型的 Amazon Bedrock 账户或达到使用限制的子代理。

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 https://status.claude.com.

尾部句子指出了检查服务健康状况的位置，因提供商而异。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft 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 https://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
• 如果超时频繁且您的网络状况良好，请参阅下面的网络和连接错误

No response from API

Claude Code 发送了流式请求，API 在第一个字节的截止时间内没有返回响应头，因此 Claude Code 中止了请求，而不是等待完整的 API_TIMEOUT_MS 请求超时（默认为 10 分钟）。Claude Code 最多再发送一次请求，如果重试预算允许的话。当重试也没有得到回复时，该轮次以此消息结束，该消息显示每次尝试等待了多长时间。当您设置 CLAUDE_CODE_RETRY_WATCHDOG 时，一次重试的上限不适用，Claude Code 在调整重试行为中描述的预算下重试。

API Error: No response from API (waited 3m, then 10m on the retry). If a proxy or gateway on your network holds responses until they complete, raise API_TIMEOUT_MS or CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS to wait longer.

Claude Code 分别为第一次尝试的等待响应头和重试的等待设置：

• 第一次尝试：当您将其设置为 1 或更多时使用 CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS，限制在 10 秒到 30 分钟之间。否则 Claude Code 使用流式空闲监视程序中列出的字节级监视程序超时，因此改变该超时的变量也会改变此等待。无论哪种方式，Claude Code 为请求体的每 32KB 添加一秒。
• 重试：比 API_TIMEOUT_MS 少一秒，默认略低于 10 分钟，以便重试可以超过保持响应直到生成完成的代理或网关。在 Amazon Bedrock 上，重试使用与第一次尝试相同的截止时间，消息显示一个持续时间而不是两个。

两个等待都不超过正 API_TIMEOUT_MS 少一秒，正 API_TIMEOUT_MS 低于 11 秒会关闭截止时间。字节级监视程序仅在响应头到达后才开始，因此在此之后停止发送字节的响应遵循停滞流规则而不是此截止时间。

应该做什么：

• 再次发送您的消息。您的原始消息仍在对话中，因此对于较长的提示，您可以输入 try again 而不是粘贴整个内容。
• 如果重复出现，将其视为网络或代理问题。接受连接但从不转发请求的代理会在每次尝试时产生此错误。
• 如果您网络上的代理或网关保持响应直到完成，请提高 API_TIMEOUT_MS 以便重试等待更长时间。在 Amazon Bedrock 上，也提高 CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS。
• 如果第一次尝试持续超时，然后重试成功，请提高 CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS 以便第一次尝试也等待足够长的时间。

在 v2.1.242 之前，Claude Code 在未回复的流式请求失败之前等待完整的 API_TIMEOUT_MS 请求超时（默认为 10 分钟）。在 v2.1.261 之前，重试等待与第一次尝试相同的截止时间，消息没有显示持续时间。

The response above may be incomplete

流式请求在响应仍在进行中时失败，在 Claude 完成了一个文本块或工具调用之后，或在完成思考后开始了一个。重新发送请求可能会运行相同的工具调用两次，因此 Claude Code 保留 Claude 完成的输出并附加此通知，而不是丢弃该轮次。您看到的变体指出了原因：

API Error: Server error mid-response. The response above may be incomplete.
API Error: Connection lost mid-response. The response above may be incomplete.
API Error: Your computer went to sleep mid-response. The response above may be incomplete.
API Error: The response stopped arriving. The response above may be incomplete.

• Server error mid-response：中流过载或 5xx 服务器错误。此变体需要 Claude Code v2.1.199 或更高版本；在此之前，该情况会丢弃部分输出并将整个轮次报告为错误。
• Connection lost mid-response：连接断开。
• Your computer went to sleep mid-response：Claude Code 检测到您的计算机在响应流式传输时进入睡眠状态。一旦您的计算机唤醒，Claude Code 会将连接视为断开并停止从中读取。
• The response stopped arriving：连接保持打开但停止传递数据，因此流式空闲监视程序中止了它。在 v2.1.222 之前，Claude Code 也可能在通过 ANTHROPIC_BASE_URL 或 ANTHROPIC_AWS_BASE_URL 到达的网关连接上报告此故障，同时服务器的保活 ping 仍在到达，因为它只在那里计算已解析的响应事件；升级会停止这些虚假超时。通过提供商基础 URL（如 ANTHROPIC_BEDROCK_BASE_URL）到达的网关不被字节监视程序包装；请参阅流式空闲监视程序。

在 v2.1.227 之前，Connection lost mid-response 读作 Connection closed mid-response，The response stopped arriving 读作 Response stalled mid-stream。

在四种情况下，Claude Code 处理故障而不立即显示此通知：

• 在响应的早期，Claude Code 要么重试故障，要么以不同的错误结束轮次。请参阅自动重试。
• 当这些故障之一在 Claude 完成响应后到达时，Claude Code 保留完整响应并正常结束轮次，没有此通知。在 v2.1.222 之前，当连接在响应完成后断开或停滞时，Claude Code 显示此通知，并将轮次报告为错误，即使响应是完整的。
• 在非交互式会话中，例如 -p 运行、Agent SDK 运行或云会话，当截断响应在主对话中且包含文本但没有工具调用时，您不必自己发送 continue：Claude Code 保留部分输出并提示 Claude 从停止的地方继续，最多连续三次。您只有在 Claude Code 用完这些继续后才会看到此通知。在 v2.1.246 之前，Claude Code 在第一次截断时以此通知结束非交互式轮次。
• 在子代理中，无论会话是否交互式：当其截断响应包含文本但没有工具调用时，Claude Code 提示子代理继续。通知仅在这些继续用完后才成为子代理的最后一条消息。在 v2.1.257 之前，子代理在第一次截断时显示此通知。

应该做什么：

• 在交互式会话中，阅读屏幕上剩余的响应：Claude Code 保留 Claude 在错误前完成的每个块，但当轮次结束时丢弃中断的最后块，因此最后的句子或工具调用可能会丢失。回复 continue 以让 Claude 从其最后完成的块继续。
• 在非交互式模式（-p）中：
  • 使用默认文本输出，Claude Code 打印它仍然从轮次早期保留的最后完成的文本块，然后是此消息。当它不保留任何内容时，Claude Code 仅打印此消息，例如因为 Claude Code 在轮次中间压缩了对话并清除了该文本。在 v2.1.219 之前，Claude Code 仅在 -p 文本输出中打印此消息并丢弃它已经生成的响应。
  • 使用 --output-format json 或 stream-json，Claude Code 在 result 字段中报告此消息。
  • 一旦连接稳定，要继续该轮次，请恢复会话并按照继续对话中的说明发送 continue。

Auto mode cannot determine the safety of an action

auto mode 使用的模型无法对操作进行分类，因此 auto mode 没有自动批准该操作。您看到的消息取决于分类器如何失败。

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

当分类器模型不可用时：

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

当 Claude Code 可以确定故障类别时，它在 temporarily unavailable 后的括号中指出该类别，例如 <model> is temporarily unavailable (rate-limited), so auto mode cannot determine the safety of <tool> right now。类别为 (rate-limited)、(overloaded)、(server error)、(timed out) 和 (connection failed)。速率限制、过载和服务器错误是暂时的，重试有效。如果 (timed out) 或 (connection failed) 重复出现，请检查您的连接；请参阅无法连接到 API。在 v2.1.229 之前，消息从不指出类别，读作 Wait briefly and then try this action again。

当没有类别适用时，消息出现时括号中没有类别；多个故障会产生该形式。在 Amazon Bedrock 上，包括 Mantle 端点，当您的 AWS 账户无法调用消息中指出的模型时，它也会出现，该故障在每次重试时重复，直到您的账户被授予访问该模型的权限。

应该做什么：

• 几秒后重试；Claude 看到相同的消息，通常会自动重试。暂时故障与 auto mode 资格无关；您不需要更改设置
• 如果重试持续失败，继续进行只读任务，稍后回到被阻止的操作
• 在 Amazon Bedrock 上，如果消息在每次重试时返回，请检查您的账户是否可以调用它指出的模型：对于标准 Amazon Bedrock 模型，确认您的 IAM 策略允许调用它；对于 Mantle 模型 ID，联系您的 AWS 账户团队

当分类器请求失败是因为您的 OAuth 令牌过期或被另一个会话轮换时，Claude Code 刷新令牌并重试请求一次，因此例行令牌过期不会显示为此消息。在 v2.1.216 之前，过期或轮换的令牌会导致每个分类器请求失败，auto mode 会拒绝每个检查的操作，直到令牌被刷新。

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

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

应该做什么：

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

当单独的 API 安全检查因早期对话内容而阻止分类器请求时：

Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details

Claude Code 拒绝该操作，但告诉 Claude 这不是对该操作不安全的判断，并继续进行其他任务而不是重试。这些拒绝不计入 auto mode 的暂停阈值。在非交互式 -p 运行中，Claude Code 不会停止运行。Claude 接收的内容取决于它请求操作的位置：

• 对于 -p 运行中没有 --input-format stream-json 的后台子代理，Claude Code 返回包含 Agent aborted: auto mode classifier request refused by the safety safeguard in headless mode 的错误结果
• 在其他地方，包括交互式会话和 -p 运行的主对话，Claude Code 将该拒绝返回给 Claude

在 v2.1.225 之前，Claude Code 将这些拒绝计入暂停阈值，并返回与真正分类器块相同的拒绝消息。

应该做什么：

• 这不是对您的操作的决定。您对话中已有的内容在 auto mode 将对话发送给分类器时触发了 API 上的安全过滤器
• 重试无法帮助；相同的对话内容将再次触发过滤器
• 在交互式会话中，切换到不同的权限模式，以便您可以在提示时批准该操作
• 开始一个新对话，不包含触发内容

当对话增长到超过分类器的上下文窗口时：

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

操作发生的情况取决于 Claude 请求它的位置：

• 在交互式会话中，auto mode 回退到该操作的正常权限提示，以便您可以手动批准或拒绝它
• 对于非交互式 -p 运行中没有 --input-format stream-json 的后台子代理，Claude Code 返回包含 Agent aborted: auto mode classifier transcript exceeded context window in headless mode 的错误结果，运行继续
• 在 -p 运行中的其他地方，没有 --permission-prompt-tool，没有提示可以回退到，因此操作不运行，运行继续

应该做什么：

• 在交互式会话中，在出现的提示中批准或拒绝该操作
• 在交互式会话中，运行 /compact 以减少对话大小，以便后续操作再次适应分类器窗口

The server returned no safety verdict

在服务器端分类器审查下，当服务器对操作没有给出判决时，auto mode 拒绝该操作。当 Claude Code 可以确定一个类别时，拒绝会在括号中指出一个类别，例如 (timed out)：

The server-side auto mode classifier gave no verdict (timed out), so auto mode cannot determine the safety of <tool>.

消息的其余部分告诉 Claude 一次重试是否可以帮助。在某些这些拒绝之前，Claude Code 会等待，以便 Claude 的下一次尝试不会立即跟随。在交互式会话中等待期间，微调器显示 Auto mode check unavailable 和倒计时，按 Esc 会中断轮次。

在连续十个响应都没有判决后，auto mode 停止轮次：

Auto mode is unavailable — the server returned no safety verdict for the last 10 responses, so Claude stopped. Send a message to try again, or switch out of auto mode.

停止消息在每种会话中出现在不同的位置：

• 在交互式会话中，消息作为警告出现在记录中，轮次结束
• 在非交互式 -p 运行中，运行结束并报告执行错误。使用默认文本输出，消息在 stderr 上打印。
• 当子代理达到限制时，子代理在完成之前停止，Claude 接收它生成的任何内容，并附带 auto mode 停止它的说明

应该做什么：

• 发送另一条消息以让 Claude 重试。响应计数重新开始。
• 如果停止重复且您的请求通过LLM 网关或代理，检查它是否截断流式响应或重写它们。服务器端分类器审查说明哪种网关行为会导致拒绝，网关兼容性指南列出了要保持不变的内容。
• 在启动 Claude Code 之前设置 CLAUDE_CODE_AUTO_MODE_SERVER=0 以改用其自己的分类器请求。在 v2.1.281 之前，Claude Code 在直接连接到 Anthropic API 时不读取该变量。
• 要自己批准操作，请改为切换出 auto mode

在 v2.1.280 之前，Claude Code 立即拒绝来自没有判决的响应的每个操作，从不停止轮次。

Agent terminated early due to an API error

子代理的 API 请求终止失败，例如因为达到了使用限制或服务器错误的重试用尽，因此子代理在完成其任务之前停止。此消息需要 Claude Code v2.1.199 或更高版本；在此之前，API 错误文本被返回给 Claude，就像它是子代理的结果一样。

Agent terminated early due to an API error: <error detail>

应该做什么：

• 将冒号后的错误详情与此页面上的其自己的部分匹配，例如使用限制或服务器错误，并按照该部分的步骤操作
• 一旦底层错误清除，请要求 Claude 重试任务或恢复子代理

当速率限制、过载或服务器错误中断已经生成文本输出的前台子代理时，Claude 接收该部分输出标记为不完整，而不是此错误。仅输出为工具调用的子代理也会收到此错误；在 v2.1.199 中，该形状返回了空的部分结果。请参阅子代理中的 API 错误。

使用限制

本部分中的大多数错误意味着与您的账户或计划相关的配额已达到。其中三个的工作方式不同：Server is temporarily limiting requests 是与您的计划配额无关的服务器端限流，Usage credits required for 1M context 是权限检查而非配额耗尽，The prompt to confirm went unanswered 表示使用额度同意提示未被回答而关闭，无论是否达到配额。

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
You've hit your Sonnet limit · resets 3:45pm

Claude Code 会阻止进一步的请求，直到消息中显示的重置时间。会话和周限制在所有模型中共享，因此切换模型不会恢复访问权限。Opus 和 Sonnet 限制各自仅适用于对该模型系列的请求，因此使用 /model 切换到该系列之外的模型可以继续工作。

在使用 claude.ai 订阅登录的交互式会话中，Claude Code 也可以在打开的会话中等待，并在重置后不久继续中断的任务。等待时，会话底部的一行显示 Usage limit reached · continuing automatically at 3:45pm · esc to cancel。在空提示处按 Esc 可取消等待。有关您看到的内容、如何开始或取消等待以及如何关闭自动继续的信息，请参阅 Wait for a usage limit to reset。在 v2.1.234 之前，Claude Code 不提供此等待功能。

使用量同时计入会话和周额度。单次大量活动突发（例如大型工作流扇出）可能会在会话窗口重置之前耗尽周额度。

要做什么：

• 等待错误中显示的重置时间
• 在 Desktop app 的 Code 选项卡中，会话限制卡提供 Auto-continue when limits reset 复选框。周限制卡没有。选中后，Desktop app 会在重置后重试中断的轮次，并在卡上显示重试时间。Desktop 复选框和 CLI 中 /config 中的 Continue automatically at usage limit 设置是分开的，因此需要分别关闭每一个。
• 对于 Opus 或 Sonnet 限制，运行 /model 并切换到该系列之外的模型以继续工作。每个模型都有自己的提示缓存，因此下一个请求会重新读取整个对话，没有缓存命中；请参阅 Switching models
• 运行 /usage 查看您的计划限制以及何时重置
• 运行 /usage-credits 在 Pro 和 Max 上购买额外使用，或在 Team 和 Enterprise 上向您的管理员请求。有关如何计费的信息，请参阅 usage credits for paid plans。
• 要升级您的计划以获得更高的基础限制，请参阅 claude.com/pricing

在窗口用完之前，Claude Code 可以警告您已使用了大部分额度，显示类似 You've used 85% of your session limit · resets 3:45pm 的消息。要持续监视您的剩余额度，请将 rate_limits 字段添加到 custom status line，或在 Desktop app 中单击模型选择器旁边的 usage ring。

Usage credits required for 1M context

所选模型使用 1M 令牌扩展上下文窗口，您的计划仅通过使用额度包含它。

API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context

这是权限检查，而非配额耗尽。即使您的会话和周额度有剩余容量，它也会触发。有关哪些计划直接包含 1M 上下文以及哪些需要使用额度的信息，请参阅 Extended context。Claude Code 在您使用 /model 选择模型时运行此检查，仅在直接连接到 Anthropic API 时；如果您将 ANTHROPIC_BASE_URL 指向 LLM gateway，/model 允许 [1m] 选择，网关决定请求是否成功。

当此错误在对话中期出现，因为上下文增长超过 200K 令牌时，Claude Code 会自动将对话压缩回标准上下文限制以下，并之后将会话保持在该限制，因此无需采取任何操作。在 v2.1.172 之前的版本中，错误会在每个后续请求（包括 /compact）上重复；在这些版本上运行 /clear 以恢复。以下步骤适用于您明确选择 [1m] 模型的情况。

要做什么：

• 运行 /model 并选择不带 [1m] 后缀的变体以回退到标准上下文窗口
• 在消息命名 /usage-credits 的地方，运行它以在 Pro 和 Max 上为 1M 变体启用按量计费，或在 Team 和 Enterprise 上向您的管理员请求使用额度。启用使用额度后，重启 Claude Code 或启动新会话，按消息所说的进行。在此之前，会话保持在标准上下文限制。
• 如果在 /model 后错误仍然存在，1M 模型 ID 可能在其他地方设置。有关要按优先级检查的配置位置，请参阅 Setting your model。
• 要从模型选择器中完全删除 1M 变体，请设置 CLAUDE_CODE_DISABLE_1M_CONTEXT=1

在 v2.1.268 之前，消息以 run /usage-credits to turn them on, or /model to switch to standard context 结尾，没有提及重启。

The prompt to confirm went unanswered

如果您的账户需要 Fable usage-credits consent，Claude Code 会在 Fable 请求计费使用额度之前要求您确认。当在可能没有人在其终端的会话中没有人回答该同意提示时，Claude Code 会关闭提示并以以下消息之一结束轮次：

Fable limit reached · continuing on Fable 5.1 uses usage credits, and the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change
Fable 5.1 now uses usage credits · the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change

消息命名会话的 Fable 模型，因此在 Fable 5 上它们读作 continuing on Fable 5 和 Fable 5 now uses usage credits。在 v2.1.257 之前，第一条消息以 Fable 5 limit reached 开头。

这发生在 Remote Control 会话、background sessions 和 agent team 队友会话中。Claude Code 仅在会话自己的交互式视图中显示同意提示：运行它的终端，或对于后台会话，一旦您附加，agents view。Remote Control 客户端无法显示它。Claude Code 在 dialogExpiry 截止时间关闭提示，默认为五分钟，或一旦新提示到达而没有人在该终端输入时立即关闭，例如从 Remote Control 客户端发送的提示。在会话运行的终端输入会取消截止时间，Claude Code 等待您的答案。在附加的后台会话视图中，输入不会取消截止时间，新提示仍会关闭同意提示，因此在任何一个发生之前回答。Claude Code 不发送任何内容并保持您的模型，因此当您发送下一个提示时，Claude Code 会再次显示同意提示。

要做什么：

• 在会话运行的终端，发送另一个提示并在它重新出现时回答同意提示。对于后台会话，首先从 agents view 附加到它。从 Remote Control 客户端重新发送会再次显示此消息，因为客户端无法显示提示。
• 运行 /model 切换到不计费使用额度的模型
• 要给自己更多时间到达该终端，请将 dialogExpiry 设置为更长的值或 "never"

在 v2.1.236 之前，此消息没有出现：当 Remote Control 客户端连接时，Claude Code 等待 60 秒以获得答案，然后在您的默认模型上继续轮次。

Server is temporarily limiting requests

API 应用了与您的计划配额无关的短期限流。

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

Claude Code 通过真实限制响应所携带的统一配额标头的缺失来区分这些。从 v2.1.199 开始，这是 retried automatically 带有退避，无论您如何进行身份验证。在早期版本中，使用 claude.ai 订阅登录的会话在第一次出现时失败轮次；只有 API 密钥和 Enterprise 登录重试了它。

要做什么：

• 稍等片刻后重试
• 如果问题仍然存在，请检查 status.claude.com

Request rejected (429)

您已达到为您的 API 密钥、Amazon Bedrock 项目或 Google Cloud 项目配置的速率限制。

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

尾部句子命名检查服务健康的位置，并因提供商而异。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 配置命名该提供商的服务状态，而不是 Anthropic 状态页面。自定义 ANTHROPIC_BASE_URL 命名网关主机。

要做什么：

• 运行 /status 并确认活跃凭证是您期望的。环境中的流浪 ANTHROPIC_API_KEY 可能会通过低层密钥而不是您的订阅路由请求。
• 检查您的提供商控制台以了解活跃限制，如果需要请求更高的层级
• 对于 Anthropic API 密钥，请参阅 rate limits reference 了解层级如何工作以及如何设置每个工作区的上限
• 降低并发：降低 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY，避免运行许多并行子代理，或使用 /model 为高容量脚本运行切换到更小的模型

You've hit your monthly spend limit

您的计划包含的使用量无法覆盖此请求，而本应为其付款的 usage credits 已达到支出限制。这发生在您的计划的使用窗口之一用完时，或当请求是仅由使用额度支付的请求时，例如对 bills to usage credits 的模型的请求。消息命名其限制阻止了您。· 后的文本说明如何增加该限制，并因您的计划和您是否管理计费而异：

You've hit your monthly spend limit · raise it at claude.ai/settings/usage
You've hit your individual spend limit · ask your admin for a higher limit
You've hit your org's monthly spend limit · visit claude.ai/admin-settings/usage to raise it
You've hit your team's shared budget · ask your admin to raise it at claude.ai/admin-settings/usage
You've hit your channel's monthly spend limit · an org owner or channel manager can raise it in the channel's Claude settings

team's shared budget 是管理员分配给您所属的组的汇总预算；消息不命名该组。channel's monthly spend limit 是会话运行的一个 Slack 频道的预算，因此您的组织可能在其外部仍有预算。

当您的计划的窗口之一用完时，消息也会说该窗口何时重置，例如 · your session limit resets 3:45pm，访问权限会在那时返回，无需任何人提高限制。在使用基于使用量的计费的组织中，消息说 usage limit 代替 spend limit，如 You've hit your individual usage limit。

在 v2.1.239 之前，消息没有命名计划窗口的重置时间。在 v2.1.268 之前，组的汇总预算产生 individual spend limit 消息而不是 team's shared budget。

如果您通过 Claude apps gateway 连接并看到小写 spend limit reached，那是您的网关操作员的上限；请参阅 Spend limit reached。

要做什么：

• 在 Pro 和 Max 上，在 claude.ai 的 Settings > Usage 中增加您的月度支出限制，或运行 /usage-credits
• 在 Team 和 Enterprise 上，如果您管理计费，在 Admin settings > Usage 中增加限制，或要求管理员这样做。/usage-credits 为您向您的管理员发送该请求
• 对于频道的限制，要求组织所有者或频道的管理员在 claude.ai 上提高它。请参阅 Claude Tag 文档中的 Per-channel limits
• 如果消息命名您的计划窗口的重置时间，您可以改为等待它
• 运行 /usage 查看您的计划窗口以及每个何时重置

Spend limit reached

您通过 Claude apps gateway 连接，并已超过您的网关操作员设置的 spend cap。网关阻止您的请求，直到命名的期间重置或操作员提高上限。它将每个被阻止的 429 响应标记为 x-should-retry: false，因此 Claude Code 显示此消息而不重试。

spend limit reached (daily; resets 2026-08-09 00:00 UTC)

消息命名上限的期间和重置时间，当操作员配置了 blocked_message 时，他们的说明跟在它后面。在 v2.1.225 之前，消息仅读作 spend limit reached；较旧版本上的网关仍然发送该较短的形式。

要做什么：

• 等待消息命名的重置时间，或如果消息包含说明，请遵循操作员的说明
• 如果您经常达到上限，要求您的网关操作员提高上限

一条相关消息 spend limit unavailable 意味着网关无法读取其支出记录，并作为预防措施而不是超过您的上限而阻止了请求。它通常会自行清除；如果它持续存在，请告诉您的网关操作员。

Credit balance is too low

您的 Console 组织已用完预付额度，或 Claude Code 使用 Console API 密钥发送您的请求，而您打算使用您的订阅。

Credit balance is too low

要做什么：

• 如果您有 Pro、Max、Team 或 Enterprise 计划并看到这个，运行 /status 并检查 API key 行。环境中已批准的 ANTHROPIC_API_KEY 通过该密钥而不是您的订阅路由请求。在当前 shell 中取消设置它并从您的 shell 配置文件中删除它，然后重新启动 claude。如果您还没有使用您的订阅登录，运行 /login。
• 在 platform.claude.com/settings/billing 添加额度，并考虑在那里启用自动重新加载，以便余额在达到零之前重新填充
• 在 Console 中设置每个工作区的支出上限，以防止单个项目耗尽组织余额。请参阅 Manage costs effectively。

Could not update your spend limit

服务器拒绝了您在达到支出限制时出现的提示中所做的支出限制更改。

Could not update your spend limit: <reason from the server>

当服务器解释拒绝时，消息以该原因结尾，重试相同的值会再次失败。当失败没有服务器提供的原因时，例如连接断开，消息读作 Could not update your spend limit. Press Enter to retry. 并且重试可能成功。在 v2.1.216 之前，Claude Code 为每个失败显示通用形式。

要做什么：

• 如果消息包含原因，选择满足它的限制，例如较低的金额
• 如果消息仅显示通用形式，重试；失败可能是暂时的
• 如果更改持续失败，改为从浏览器中的 claude.ai billing settings 进行

身份验证错误

这些错误意味着 Claude Code 无法向 API 证明您的身份。随时运行 /status 查看当前活跃的凭证。

未登录

此会话没有可用的有效凭证。

Not logged in · Please run /login

应该做什么：

• 运行 /login 以使用您的 Claude 订阅或 Console 账户进行身份验证
• 如果您期望使用环境变量进行身份验证，请确认 ANTHROPIC_API_KEY 已在启动 claude 的 shell 中设置并导出
• 对于无法进行交互式登录的 CI 或自动化，配置一个 apiKeyHelper 脚本，在启动时获取密钥
• 查看 身份验证优先级 以了解当存在多个凭证时 Claude Code 使用哪个凭证

如果您被重复提示登录，请参阅 未登录或令牌过期 了解系统时钟检查和 macOS 凭证存储恢复步骤。

无法解析身份验证方法

会话到达 API 客户端时没有任何凭证。后台会话 和云会话在 worker 启动时没有凭证时显示此消息。交互式、-p 和 Agent SDK 运行报告与 未登录 相同的条件，并仅将此字符串写入其调试日志，因此如果您在那里找到它，请改为遵循该条目。

Could 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

在当前版本上，该错误意味着 worker 进程没有可用的凭证。在 v2.1.174 之前，分配给空闲预初始化 worker 的后台会话即使配置了有效凭证也可能以这种方式失败。在 v2.1.176 之前，在被声明之前处于空闲状态的云会话也可能失败。升级以恢复。

应该做什么：

• 如果这出现在后台或云会话中且您的凭证已配置，请升级到 v2.1.176 或更高版本
• 确认 ANTHROPIC_API_KEY、CLAUDE_CODE_OAUTH_TOKEN 或您的云提供商凭证已在启动 worker 的环境中设置，而不仅仅在您的交互式 shell 中
• 对于 Agent SDK，请参阅 快速入门中的身份验证设置
• 在同一环境中的交互式会话中运行 /status 以确认哪个凭证源可解析

无效的 API 密钥

ANTHROPIC_API_KEY 环境变量或 apiKeyHelper 脚本返回了 API 拒绝的密钥，或 Claude Code 在发送前阻止了来自 ANTHROPIC_API_KEY 的密钥。

Invalid API key · Fix external API key

当消息在 Fix external API key 之后继续，并带有描述如 Invalid X-Api-Key header value from ANTHROPIC_API_KEY: it contains a line break at character 41 (120 characters on 2 lines). 时，API 从未看到该密钥。Claude Code 发现了 HTTP 标头无法传输的字符，并在发送前停止了请求。请参阅 无效的请求标头值 了解如何读取描述并修复该值。

应该做什么：

• 检查拼写错误并确认密钥未在 Console 中被撤销
• 在同一 shell 中，运行 env | grep ANTHROPIC，或在 PowerShell 中运行 Get-ChildItem Env:ANTHROPIC*。direnv、dotenv shell 插件和 IDE 终端等工具可以从项目中的 .env 文件加载过时的密钥，而无需您显式设置它
• 取消设置 ANTHROPIC_API_KEY 并运行 /login 以改用订阅身份验证
• 如果密钥来自 apiKeyHelper 脚本，请直接运行该脚本以确认它在 stdout 上打印有效密钥
• 运行 /status 以确认 Claude Code 实际使用的凭证源

您的 apiKeyHelper 脚本失败

Claude Code 运行了您的 apiKeyHelper 设置中的命令，但没有获得密钥。没有密钥，请求会到达 API，并带有占位符凭证，API 会以 401 拒绝它。终端中的 Authentication 面板显示发生了以下哪种情况：

• 命令以错误退出或超时
• 命令未向 stdout 打印任何内容
• 命令打印了除密钥之外的内容，例如登录横幅或日志行。该面板显示 returned output that cannot be used as an API key 并说明了问题所在，而不重复输出。在 v2.1.227 之前，Claude Code 发送命令打印的任何内容，在修剪周围空格后。

Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output

在 非交互式模式 中，stderr 也带有具体原因，前缀为 apiKeyHelper failed:。

Claude Code 重新运行脚本并在显示此消息之前最多重试请求两次，因此故障在三次尝试内出现。在 v2.1.208 之前，Claude Code 花费完整的 重试预算 使用占位符凭证重新发送请求，然后报告通用 401 身份验证错误而不是脚本故障。

运行 /login 在这里没有帮助：只要设置存在，helper 的输出 优先于 保存的登录。

应该做什么：

• 直接在您的 shell 中运行在 apiKeyHelper 中配置的命令以重现故障
• 如果命令报告会话过期，请使用您的凭证提供商重新身份验证，例如再次登录您的 SSO 或密钥保管库
• 修复命令，使其仅将密钥打印到 stdout，作为单个可打印 ASCII 令牌，最多 16,384 个字符，并以代码 0 退出。请参阅 使用 apiKeyHelper 轮换凭证 了解工作设置。
• 运行 /status 查看故障并确认 apiKeyHelper 是活跃凭证源。apiKeyHelper 行显示 Failing 以及最后一次故障的详细信息，例如退出代码和命令的错误输出，并在下一次成功运行后消失。在 v2.1.274 之前，/status 仅显示凭证源，而不是故障。
• 每次命令失败时，其退出代码和错误输出也会出现在终端中的 Authentication 面板中。在 v2.1.212 之前，该面板的标题为 Cloud authentication。

无效的请求标头值

Claude Code 即将作为请求标头发送的值包含 HTTP 标头无法传输的字符：换行符、NUL 字节或 U+00FF 以上的字符，例如弯引号或零宽空格。Claude Code 在发送任何内容之前停止请求，并命名要修复的变量或设置。通常的原因是从文档或聊天粘贴的凭证，其中包含不可见字符或杂散换行符。

Claude Code 在直接向 Claude API 或通过 LLM 网关 发送请求时运行此检查。在第三方云提供商（如 Amazon Bedrock）上，Claude Code 在发送前不运行它。

Invalid auth token · Fix external auth token
Invalid ANTHROPIC_CUSTOM_HEADERS · Fix the environment variable
Invalid request header from the environment · Fix the environment variable

消息的第一部分取决于坏值来自何处：

• Invalid auth token：来自 ANTHROPIC_AUTH_TOKEN 或 CLAUDE_CODE_OAUTH_TOKEN 的持有者令牌
• Invalid ANTHROPIC_CUSTOM_HEADERS：您在 ANTHROPIC_CUSTOM_HEADERS 中设置的标头名称或值。描述计算哪个 Name: Value 对有问题，例如 distinct header 2 of 3 parsed from ANTHROPIC_CUSTOM_HEADERS，而不重复名称或值，因为您选择了两者。
• Invalid request header from the environment：Claude Code 从另一个环境变量（如 CLAUDE_AGENT_SDK_CLIENT_APP）复制到请求标头中的值。描述命名要修复的变量。

Claude Code 将此检查捕获的坏 ANTHROPIC_API_KEY 报告为 无效的 API 密钥，具有相同的尾部描述。它将坏的保存 /login 凭证报告为 未登录；运行 /login 以保存新凭证。apiKeyHelper 脚本的输出永远不会到达此检查：Claude Code 在脚本运行时验证它，并且输出 HTTP 标头无法传输的失败会导致 您的 apiKeyHelper 脚本失败。

在第二个 · 之后，消息描述问题，如以下完整示例：

Invalid auth token · Fix external auth token · Invalid Authorization header value from ANTHROPIC_AUTH_TOKEN: it contains a line break at character 41 (120 characters on 2 lines).

位置从 1 开始计算字符。描述由固定短语和字符计数构建，因此它永远不包括值本身。它仅在字符是众所周知的不可见或排版字符（如字节顺序标记、零宽空格或弯引号）时命名该字符，并将其他任何内容报告为 a non-ASCII character。

应该做什么：

• 重新设置消息命名的变量或设置，重新输入报告位置周围的字符，而不是从同一来源再次粘贴
• 对于 ANTHROPIC_CUSTOM_HEADERS，每行保留一个 Name: Value 对，并重写消息计数的对
• 运行 /status 以确认哪个凭证源处于活跃状态

此组织已被禁用

Claude Code 正在使用来自已禁用 Console 组织的过时 ANTHROPIC_API_KEY。当您有保存的订阅登录时，密钥会覆盖它。

Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your subscription instead
Your ANTHROPIC_API_KEY belongs to a disabled organization · Update or unset the environment variable
API Error: 400 ... This organization has been disabled.

· 之后的提示取决于您保存的凭证：当存储的 /login 可以在您取消设置密钥后接管时出现第一种形式，当密钥是您唯一的凭证时出现第二种形式。

环境变量优先于 /login，因此在您的 shell 配置文件中导出或从 .env 文件加载的密钥即使您有有效的 Pro 或 Max 订阅也会被使用。在非交互式模式 (-p) 中，当存在密钥时始终使用该密钥。

应该做什么：

• 在当前 shell 中取消设置 ANTHROPIC_API_KEY 并从您的 shell 配置文件中删除它，然后重新启动 claude
• 如果消息说 Update or unset，您没有保存的登录可以回退。取消设置密钥并运行 /login，或将密钥替换为来自活跃 Console 组织的密钥。
• 之后运行 /status 以确认活跃凭证是您的订阅
• 如果未设置环境变量且错误仍然存在，则禁用的组织是与您的 /login 关联的组织。联系支持或使用不同账户登录。

您的组织已禁用 API 密钥身份验证

此消息需要 Claude Code v2.1.169 或更高版本。您的 Console 组织的管理员已关闭 API 密钥身份验证，因此 API 拒绝 Claude Code 正在发送的密钥。· 之后的恢复提示因密钥来自何处而异：

Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account
Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY to use your claude.ai account instead
Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY and run /login to sign in with your claude.ai account
Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account

环境变量和 apiKeyHelper 优先于 /login，因此仅运行 /login 在任一仍在提供密钥时没有帮助。请参阅 身份验证优先级。

应该做什么：

• 如果消息命名 ANTHROPIC_API_KEY，在当前 shell 中取消设置它并从您的 shell 配置文件或 .env 文件中删除它，然后重新启动 claude
• 如果消息命名 apiKeyHelper，从您的 settings.json 中删除 apiKeyHelper 设置
• 运行 /login 以使用您的 claude.ai 账户登录
• 之后运行 /status 以确认活跃凭证是您的订阅而不是 API 密钥
• 如果您需要 API 密钥身份验证用于自动化，请要求您的组织管理员在 Console 中重新启用它

您的组织已禁用 Claude 订阅访问

您的 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 访问
• 使用 Console API 密钥而不是您的订阅进行身份验证。请参阅 Claude Console 身份验证 了解设置。
• 如果您是管理员且看不到启用访问的选项，请联系 Anthropic 支持

例程被您的组织的策略禁用

您的 Team 或 Enterprise 组织中的所有者已在组织级别关闭例程。当您尝试创建或运行例程时会出现错误，例如从 claude.ai/code 上的 例程 UI。在 Claude Code v2.1.227 或更高版本上，相同的设置也 隐藏 CLI 中的 /schedule。

Routines are disabled by your organization's policy.

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

应该做什么：

• 要求您的组织中的所有者在 claude.ai/admin-settings/claude-code 启用 Routines 切换
• 对于不需要组织级例程的一次性计划工作，请参阅 计划任务

Remote Control 需要 Anthropic API

会话不是直接与 Anthropic API 通信，因此没有 claude.ai 后端供 Remote Control 配对。

Remote Control is only available when using Claude via api.anthropic.com. CLAUDE_CODE_USE_BEDROCK is set, so this session is using Amazon Bedrock — unset it (or run in a shell without it) to use Remote Control.

第二句解释了什么将会话路由离开 Anthropic API；在 v2.1.219 之前，消息仅为第一句。根据原因，消息命名：

• CLAUDE_CODE_USE_* 提供商变量，例如 Amazon Bedrock 的 CLAUDE_CODE_USE_BEDROCK 或 Google Cloud 的 Agent Platform 的 CLAUDE_CODE_USE_VERTEX
• ANTHROPIC_BASE_URL 指向 api.anthropic.com 以外的主机，例如 LLM 网关 或代理，即使您使用 claude.ai 登录；在 v2.1.196 之前，自定义基础 URL 不会阻止 Remote Control
• ANTHROPIC_UNIX_SOCKET 已设置，因此会话通过本地套接字而不是 api.anthropic.com 发送其请求
• 企业 云网关 通过 /login 登录，不支持 Remote Control，没有变量可取消设置

应该做什么：

• 取消设置消息命名的变量，例如 CLAUDE_CODE_USE_BEDROCK 或 ANTHROPIC_BASE_URL，并重新启动会话，或从直接与 Anthropic API 通信的会话启动 Remote Control
• 如果变量未在您的 shell 中设置，请检查您的 设置文件 中的 env 键，该键将环境变量应用于每个会话
• 对于此和其他 Remote Control 启动消息，请参阅 Remote Control 故障排除

Remote Control 无法刷新您的登录

Claude Code 在短期凭证上运行实时 Remote Control 连接，它使用您保存的 claude.ai 登录获取和更新这些凭证。当 claude.ai 停止接受该登录或 Claude Code 没有保存的登录时，Claude Code 停止 Remote Control 并需要您再次登录。任一故障都可能在 Claude Code 仍在连接时或稍后在更新凭证时发生。

当 Claude Code 要求登录服务刷新您保存的登录并且没有得到答复时，它会保持 Remote Control 运行并在连接的当前凭证仍然有效时再次尝试刷新。当 Claude Code 无法到达登录服务、请求超时或服务在不拒绝您的登录的情况下失败时，刷新会得不到答复。如果当该凭证过期时登录服务仍然没有答复，Claude Code 会停止 Remote Control 并报告 OAuth token refresh failed。

当 Claude Code 停止 Remote Control 时，它在警告和以 Remote Control disconnected 开头的成绩单行中显示原因。您的本地会话继续运行而没有 Remote Control。本部分涵盖这些行：

Remote Control disconnected — Claude.ai login expired — run /login to restore Remote Control
Remote Control disconnected — Claude.ai login expired — run /login, then /remote-control
Remote Control disconnected — Claude.ai login was rejected — run /login, then /remote-control
Remote Control disconnected — OAuth token unavailable — run /login to restore Remote Control
Remote Control disconnected — OAuth token refresh failed — run /login to re-authenticate
Remote Control disconnected — JWT refresh failed: no OAuth token — run /login
Remote Control disconnected — Signed out of Claude — run /login, then /remote-control

Claude Code 在消息中间命名原因：

• Claude.ai login expired 和 Claude.ai login was rejected：claude.ai 不再接受您保存的登录令牌，因为它已过期或被撤销
• OAuth token unavailable：当连接的凭证到期需要更新时，Claude Code 没有保存的登录令牌
• OAuth token refresh failed：claude.ai 在 Claude Code 重新连接时拒绝了您保存的登录令牌，刷新令牌没有产生新令牌
• JWT refresh failed: no OAuth token：Claude Code 找不到保存的登录令牌来更新
• Signed out of Claude：您在此机器上登出，例如在另一个终端中运行 /logout，因此 Claude Code 没有保存的登录来更新连接

应该做什么：

• 运行 /login 再次登录
• 运行 /remote-control 重新连接会话。以 run /login to restore Remote Control 结尾的消息不需要此步骤：Claude Code 在您登录后自动重新连接。

在 v2.1.224 之前，OAuth token refresh failed — run /login to re-authenticate 读作 OAuth token refresh failed — re-authenticate, then re-enable Remote Control，JWT refresh failed: no OAuth token — run /login 读作 no OAuth token available for recovery (code <N>)。 Claude.ai login expired、Claude.ai login was rejected 和 OAuth token unavailable 消息在 v2.1.225 中添加。

在 v2.1.238 之前，Claude Code 将现在说 Signed out of Claude 的情况报告为 JWT refresh failed: no OAuth token — run /login，并在一次登录刷新没有得到答复后立即停止 Remote Control，显示 Claude.ai login expired — run /login to restore Remote Control。

Remote Control 停止，因为登录账户已更改

Claude Code 在 Remote Control 会话期间显示此行，当您在此机器上登录到不同的 claude.ai 账户或组织时。您在 Claude Code 会话外进行了切换，例如在另一个终端中运行 /login。

您在通过 /login 登录时启动的 Remote Control 会话属于当时登录的 claude.ai 账户和组织。

Remote Control disconnected — signed-in claude.ai account or organization changed on this machine — run /remote-control to start a session for the current account, or /login to switch back, then /remote-control

Claude Code 在 claude.ai 确认账户或组织已更改后立即停止 Remote Control 会话。您的本地会话继续运行而没有 Remote Control。

应该做什么：

• 运行 /remote-control 在当前账户或组织下启动新的 Remote Control 会话
• 要切换回去，运行 /login 并再次登录到之前的账户或组织。然后运行 /remote-control。

在 v2.1.234 之前，Claude Code 在您在 Claude Code 会话外切换到不同账户或组织时没有注意到。Claude Code 保持 Remote Control 会话连接，直到稍后对 Remote Control 服务器的请求失败，显示 Remote Control server rejected the request (HTTP 404)。该故障可能在切换后数小时发生。

Remote Control 停止，因为运行会话的应用登出或切换了账户

当 Claude 桌面应用或 IDE 托管您的会话时，Claude Code 从该应用而不是从 /login 获取其登录令牌。当 claude.ai 拒绝该令牌时，Claude Code 要求应用提供新令牌。如果应用回答说它已登出或现在登录到不同的 Claude 账户，Claude Code 结束 Remote Control 会话并向应用发送以下行之一：

Remote Control stopped — the app running this session is now signed in to a different Claude account
Remote Control stopped — the app running this session is signed out of Claude. Sign in there, then turn Remote Control back on

您的本地会话继续运行而没有 Remote Control。

应该做什么：

• 如果应用已登出，再次登录，然后在应用中重新打开 Remote Control
• 如果应用切换了账户，Claude Code 无法在新账户下继续已结束的会话。在该账户下启动新的 Remote Control 会话。

在 v2.1.238 之前，Claude Code 在两种情况下都向应用发送了 Remote Control 无法刷新您的登录 下列出的 run /login 消息。

OAuth 令牌被撤销或过期

您保存的登录不再有效。被撤销的令牌意味着您在任何地方登出或管理员删除了访问权限；过期的令牌意味着自动刷新在会话中失败。

两条消息都报告 API 为 Claude Code 发送的请求返回的拒绝。当保存的登录在失败的刷新后已被清除时，您会看到 登录过期。如果您使用 CLAUDE_CODE_OAUTH_TOKEN 中的长期令牌进行身份验证，当该令牌过期或被撤销时，您会看到相同的消息。

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

应该做什么：

• 运行 /login 再次登录
• 如果重新身份验证后错误在同一会话中返回，首先运行 /logout 以完全清除存储的令牌，然后运行 /login
• 如果您使用 CLAUDE_CODE_OAUTH_TOKEN 环境变量进行身份验证，Claude Code 在请求失败并显示 401 后会继续发送您设置的值，而不是切换到保存的登录的令牌。/status 将此凭证显示为读取 CLAUDE_CODE_OAUTH_TOKEN 的 Auth token 行。使用 claude setup-token 生成新令牌并使用它重新启动，或取消设置变量并运行 /login。在 v2.1.225 之前，Claude Code 可以在会话中用保存的登录的短期访问令牌替换变量的值，一旦该令牌过期，会话再次失败并显示 401 错误。
• 对于跨启动的重复登录提示，请参阅 故障排除 中的系统时钟检查和 macOS 凭证存储恢复步骤
• 对于其他故障，包括 403 Forbidden 和 OAuth 浏览器问题，请参阅 登录和身份验证

API 错误：401 无效的身份验证凭证

API 识别了您凭证的格式，但拒绝了其背后的账户或组织。当凭证最近被撤销、组织被禁用或删除了您的访问权限或账户本身被停用时，Anthropic 返回此消息，因此过期的令牌不是原因。凭证可以是您保存的登录或批准的 ANTHROPIC_API_KEY，修复方式不同，因此首先运行 /status 查看哪个处于活跃状态。

Please run /login · API Error: 401 Invalid authentication credentials

应该做什么：

• 如果 /status 显示未标记为未使用的 API key 行，则批准的 ANTHROPIC_API_KEY 是活跃凭证并优先于您的登录，因此 /login 不会替换它。在 Claude Console 中轮换密钥，或通过运行 unset ANTHROPIC_API_KEY 回退到您的订阅，或在 PowerShell 中运行 Remove-Item Env:ANTHROPIC_API_KEY。
• 如果 /status 仅显示您的登录，运行 /login 一次。如果凭证被撤销，新登录会替换它。
• 如果相同的消息对相同的登录账户返回，则该账户或组织不再活跃。检查 /status 报告的账户和组织，并要求您的组织管理员恢复访问。
• 如果 ANTHROPIC_BASE_URL 指向 LLM 网关，401 之后的文本是您网关的消息而不是 Anthropic 的，/login 不会改变它。改为修复您的网关期望的凭证。

登录过期

Claude Code 尝试更新您保存的 claude.ai 或 Claude Console 登录，OAuth 服务拒绝了存储的刷新令牌，因此 Claude Code 清除了保存的凭证。之后，每个模型请求在到达 API 之前都会在本地停止，显示此消息，因为只有 /login 可以创建新凭证。

在 v2.1.206 之前，Claude Code 无论如何都会发送模型请求，使用环境中剩余的任何凭证，每个模型都会失败，显示 所选模型有问题 或 401，而不是登录提示。

Login expired · Please run /login

在 非交互式模式 (-p) 和 Agent SDK 中，消息如下所示，结构化错误代码为 authentication_failed：

Failed to authenticate: OAuth session expired and could not be refreshed

这与 OAuth 令牌被撤销或过期 的状态不同。这些消息报告 API 返回的拒绝。Claude Code 本身为已失败更新的登录生成 Login expired，因此它不发送请求。当更新失败是因为账户本身被暂停而不是登录过时时，Claude Code 改为显示 您的账户被冻结。

使用 API 密钥、CLAUDE_CODE_OAUTH_TOKEN 或第三方提供商进行身份验证的会话不使用保存的登录，永远不会看到此消息。

您可以在请求失败之前检查此状态：/status 显示读取 Expired — log in again 的 Login 行，加上它为过期登录保存的组织和电子邮件。该行仅在保存的登录是您的活跃凭证且无法再刷新时出现。以其他方式进行身份验证的会话不显示该行，即使过期的登录仍然保存。在 v2.1.210 之前，/status 在此状态下没有指示登录曾经存在过，因为清除的凭证使其无法报告。

应该做什么：

• 运行 /login 再次登录。在不登录的情况下重试会在每个请求上显示相同的消息。
• 在非交互式模式中，在同一环境中运行 claude，完成 /login，然后重新运行您的命令。对于无法交互式登录的自动化，使用 ANTHROPIC_API_KEY 进行身份验证或 使用 claude setup-token 生成长期令牌。
• 如果登录持续失败，请参阅 登录和身份验证

Claude 登录未被接受

您尝试启动 云会话，服务器拒绝使用 401 创建它：它不接受此机器发送的 Claude 登录，通常是因为登录过期或被撤销。

当服务器给出自己的原因时，行的第一部分是该原因。否则该行读作：

Claude login not accepted · Run /login, then try again

应该做什么：

• 运行 /login，完成登录，然后再次启动会话

工件需要 claude.ai 登录

Claude Code 拒绝了 工件 发布或读取，因为会话没有可用于工件的 claude.ai 登录。

消息的每种形式都以相同的词开头，然后是取决于您的会话如何进行身份验证的补救措施。没有竞争凭证时，它读作：

Artifacts need a claude.ai login. Run /login and select "Claude account with subscription", then retry — the "Anthropic Console account" option does not provide claude.ai credentials.

应该做什么：

• 运行 /login 并选择 Claude account with subscription。Anthropic Console account 选项不提供 claude.ai 凭证。
• 当消息命名优先的凭证（如 ANTHROPIC_API_KEY、apiKeyHelper 设置或之前 /login 保存的 Console 密钥）时，按消息说的方式删除它，然后运行 /login
• 当消息说此远程会话通过启动它的机器进行身份验证时，在该机器上登录到 claude.ai，然后重新连接会话
• 当消息说凭证由会话的主机环境注入时，您无法在该会话中更改它；启动登录到 claude.ai 的会话
• 请参阅 可用性 了解工件具有的其他要求，例如计划、模型提供商和组织策略

管理员策略需要 Cloud gateway 登录

管理员在此机器上的 托管设置 将 forceLoginMethod 设置为 "gateway" 或设置 forceLoginGatewayUrl。除非您通过 CLAUDE_CODE_USE_BEDROCK 等变量选择云提供商，Claude Code 仅接受 Claude apps gateway 登录。您会看到两条消息之一：

Not signed in to the Cloud gateway — run /login.

当会话没有网关登录时，模型请求失败，显示此消息，例如因为您自策略到达机器后未运行 /login。

如果您还配置了 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或 apiKeyHelper 凭证，且托管设置设置了 forceLoginMethod，Claude Code 在启动时改为以以下消息退出：

Administrator policy requires a Cloud gateway sign-in on this machine; the
Anthropic-issued credential configured here (ANTHROPIC_API_KEY,
ANTHROPIC_AUTH_TOKEN, or apiKeyHelper) is not used.

应该做什么：

• 运行 /login 并在 Cloud gateway 屏幕上完成登录
• 对于启动消息，删除您配置的 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或 apiKeyHelper 设置，然后启动 claude 并运行 /login
• 如果您认为机器不应该需要网关，请要求管理该机器的管理员从其托管设置中删除 forceLoginMethod 和 forceLoginGatewayUrl

在 v2.1.265 上，回归也在某些 LLM 网关和代理配置中显示第一条消息，这些配置使用 API 密钥、apiKeyHelper 或自定义标头进行身份验证，即使机器上没有管理员要求。更新到 v2.1.266 或更高版本。您不需要更改您的配置。

在 v2.1.261 之前，在将 forceLoginMethod 设置为 "gateway" 的机器上，Claude Code 使用剩余的保存登录而不是失败模型请求，并使用 This machine's managed settings require a first-party login 而不是启动消息报告配置的环境凭证。在 v2.1.265 之前，其托管设置仅设置 forceLoginGatewayUrl 的机器不需要网关登录，Claude Code 在那里使用剩余凭证。

您的账户被冻结

您的 Claude 账户背后的登录已被暂停。Claude Code 在尝试更新您保存的登录并了解冻结时显示第一条消息，在您在浏览器中完成的登录报告时显示第二条消息：

Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted
Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted

使用同一账户再次登录不会清除消息，因为冻结是在账户上而不是登录上。在 非交互式模式 (-p) 和 Agent SDK 中，结构化错误代码为 account_on_hold。在 v2.1.235 之前，Claude Code 将被冻结的账户报告为 登录过期 · 请运行 /login，其恢复步骤无法清除冻结。

应该做什么：

• 打开消息中的链接以查看冻结的详细信息或对其提出上诉
• 如果您有另一个 Claude 账户或不受冻结影响的 API 密钥，您可以在冻结解决期间继续工作：使用该账户运行 /login，或使用 ANTHROPIC_API_KEY 设置密钥

Anthropic 配置文件登录过期

Claude Code 通过 Anthropic 凭证配置文件进行身份验证，其保存的登录凭证已过期，且配置文件不包含 Claude Code 可用于更新它的刷新凭证。Claude Code 在本地停止每个请求而不重试，因为重试会读取相同的过期凭证。

Anthropic profile login expired · Re-authenticate your Anthropic profile
Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile

这仅在活跃凭证来自 Anthropic 凭证配置文件时出现，您使用 ANTHROPIC_PROFILE 环境变量选择该文件，Claude Code 从您的 Anthropic 配置目录中发现为活跃配置文件，或 Claude Code 在您 不使用 API 密钥登录 时写入。使用 /login 的 claude.ai 选项、API 密钥、持有者令牌（如 ANTHROPIC_AUTH_TOKEN）或第三方提供商进行身份验证的会话永远不会看到此消息。

在 提供无密钥登录 的机器上，运行 /login，选择 Anthropic Console 账户，并再次登录以更新无密钥 Console 登录或 Claude Platform CLI 的 ant auth login 写入的配置文件。Claude Code 替换该配置文件中的过期凭证。对于联合配置文件或另一个工具创建的配置文件，/login 不会更新凭证。您看到的形式取决于您是否显式选择了配置文件或 Claude Code 发现了它：

• 当您显式设置 ANTHROPIC_PROFILE 时，消息以 Re-authenticate your Anthropic profile 结尾。
• 当 Claude Code 从您的配置目录发现配置文件时，消息提供 /login，因为 Claude Code 给予工作的 /login 优先于发现的配置文件，然后改为使用您的 claude.ai 或 Console 账户进行身份验证。在 v2.1.234 之前，Claude Code 在这种情况下也显示 Re-authenticate your Anthropic profile 形式。

应该做什么：

• 再次登录到配置文件，然后重试：在 提供无密钥登录 的机器上，运行 /login 并为无密钥 Console 登录或 Claude Platform CLI 的 ant auth login 写入的配置文件选择 Anthropic Console 账户；对于其他配置文件，使用创建它们的工具
• 如果管理员配置了配置文件的凭证，请要求他们颁发新凭证
• 运行 /status 以确认活跃凭证源和配置文件名称
• 要停止使用配置文件，如果您设置了 ANTHROPIC_PROFILE，则取消设置它，然后以其他方式进行身份验证，例如 /login 或 ANTHROPIC_API_KEY

OAuth 范围要求

存储的令牌早于较新功能需要的权限范围。您最常从 /usage 和状态行使用指示器看到这种情况：

OAuth token does not meet scope requirement: user:profile

应该做什么：

• 运行 /login 以获取具有当前范围的新令牌。您不需要先登出。

claude.ai 拒绝了会话令牌

claude.ai 连接器 请求失败，因为 claude.ai 拒绝了您的 Claude Code 登录中的令牌，通常是已过期且无法刷新的登录。被拒绝的令牌是您的登录，而不是连接器在 claude.ai 中的自己的授权，因此再次授权连接器不会解决它。在 /mcp 中，连接器显示为 connected · session token rejected，其详细视图读作：

claude.ai rejected the session token. Run /login, then reconnect.

应该做什么：

• 运行 /login 再次登录
• 从 /mcp 重新连接连接器，或运行 /mcp reconnect <server>。在您再次登录之前重新连接会使连接器处于相同状态。/mcp 面板的 Reconnect 选项报告 your claude.ai session token was rejected；输入的 /mcp reconnect <server> 形式报告成功重新连接，即使令牌仍然被拒绝。

在 v2.1.222 之前，Claude Code 改为将连接器标记为需要身份验证，这指向您连接器的授权流程，即使完成它也不会解决状态。

MCP 服务器需要您再次登录

远程 MCP 服务器 在会话中期拒绝了工具调用上的凭证，通常是因为登录或令牌过期或令牌缺少工具需要的权限。工具调用失败，/mcp 将服务器标记为 需要身份验证。

对于您从 Claude Code 登录的服务器，包括 claude.ai 连接器，登录已过期或被撤销：

MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)

运行 /mcp，选择服务器，并从其菜单再次登录。

对于使用 headersHelper 脚本配置的服务器，Claude Code 已在显示此之前重新运行 helper 并重试调用一次：

MCP server "<name>" rejected the credential from its headersHelper (check the helper and run /mcp to reconnect, or to authenticate if the server also uses OAuth)

检查 helper 返回服务器接受的凭证，然后从 /mcp 重新连接，这会再次运行 helper。

对于在其配置中具有静态 Authorization 标头的服务器：

MCP server "<name>" rejected the Authorization header in its config (update it, then run /mcp to reconnect)

在配置服务器的位置更新标头值，然后从 /mcp 重新连接。

在 v2.1.273 之前，过期的登录、headersHelper 和 Authorization 标头情况都显示 MCP server "<name>" requires re-authorization (token expired)。

服务器也可以使用 HTTP 403 insufficient_scope 拒绝工具调用，以要求您授权范围，有时是您的令牌已列出的范围。消息命名该范围：

MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate

运行 /mcp，选择服务器，并从其菜单再次进行身份验证。

当服务器的配置既不设置 oauth.scopes 也不设置 authServerMetadataUrl 时，Claude Code 请求服务器命名的范围。使用任一设置，Claude Code 改为请求该设置的范围。如果您固定了 oauth.scopes，在再次进行身份验证之前将缺失的范围添加到该列表。

在 v2.1.274 之前，这种情况显示 needs you to sign in again 消息，在 v2.1.273 之前它显示 requires re-authorization (token expired)，如其他情况。

授权响应中的发行者不匹配

在 MCP OAuth 登录 期间，授权服务器重定向回 Claude Code，其中 iss 参数不命名 Claude Code 从服务器的 OAuth 元数据期望的发行者。此步骤中的错误发行者是授权服务器混合攻击的样子，因此 Claude Code 失败登录而不是交换授权代码。Claude Code 在浏览器登录后在 /mcp 服务器菜单中显示错误：

Issuer mismatch in authorization response (RFC 9207): expected "https://auth.example.com", received "https://other.example.com"

expected 是来自服务器的 OAuth 元数据的发行者，received 是重定向携带的 iss 值。其重定向不携带 iss 参数的登录通过检查，除非服务器的元数据设置 authorization_response_iss_parameter_supported，在这种情况下 Claude Code 失败登录。

应该做什么：

• 从 /mcp 再次尝试登录
• 如果错误重复，将其报告给服务器操作员。修复是服务器端的：授权服务器必须在 iss 参数中返回与在其元数据中宣传的相同发行者
• 要在修复服务器时连接，使用 MCP_SDK_GENERATION=v1 启动 Claude Code，其 运行时 不运行此检查。这消除了对混合攻击的保护，因此更喜欢服务器端修复

在 v2.1.232 之前，Claude Code 仅在逐步推出中或当您设置 MCP_SDK_GENERATION=v2 时使用 v2 运行时。

AWS 凭证已过期或无效

您的 AWS 会话令牌已过期或被拒绝。此消息出现在来自 Claude Platform on AWS 或 Mantle 端点 的 401，这是这些提供商报告过期安全令牌的方式。

中间的操作提示因您的设置而异。稳定部分是前导 AWS credentials expired or invalid：

AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...

在 v2.1.273 之前，仅当配置了 awsAuthRefresh 时才出现此消息。

应该做什么：

• 如果提示说凭证由此环境管理，启动 Claude Code 的应用拥有凭证，此处的其他步骤不适用：重试或联系您的管理员
• 如果设置了 awsAuthRefresh，在另一个终端中运行消息中命名的命令，例如 aws sso login --profile myprofile，并完成浏览器登录，然后重试。否则自己刷新您使用的 AWS 凭证：您的 SSO 登录、访问密钥、API 密钥或代理令牌
• 在交互式会话中设置 awsAuthRefresh，您可以改为运行 /login，选择 3rd-party platform，然后在 Using 3rd-party platforms 下选择 Claude Platform on AWS · refresh credentials 以运行相同的命令而不重新启动 Claude Code。请参阅 配置 AWS 凭证
• 如果刷新命令成功后错误重复，通过在同一 shell 和配置文件中使用 aws sts get-caller-identity 在 Claude Code 外确认身份有效

AWS 身份验证失败

您的 AWS 提供商返回了 403，或 Amazon Bedrock 返回了 401。

Amazon Bedrock 将过期的安全令牌报告为 403，但 403 也是它报告授权拒绝的方式，例如来自缺失 IAM 权限的 AccessDeniedException。Claude Code 无法区分这两个原因。

来自 Amazon Bedrock 的 401 也在这里而不是在 AWS 凭证已过期或无效 下，因为 Amazon Bedrock 不将过期令牌报告为 401。来自该端点的 401 通常来自请求路径中的其他内容，例如公司代理。

凭证刷新修复过期令牌，无法修复其他原因，因此消息提供两者：

AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...

中间的操作提示因您的设置而异。稳定部分是前导 AWS authentication failed。

当 403 是 Amazon Bedrock 的答案，说您无权访问具有指定模型 ID 的模型时，提示改为告诉您在 Amazon Bedrock 控制台中为您的账户和区域启用模型。

在 v2.1.273 之前，仅当配置了 awsAuthRefresh 时才出现此消息。

应该做什么：

• 如果提示说凭证由此环境管理，启动 Claude Code 的应用拥有凭证，此处的其他步骤不适用：重试或联系您的管理员
• 刷新您的 AWS 凭证以防过期凭证是原因：运行消息中命名的 awsAuthRefresh 命令（当设置时），或自己刷新您的 SSO 登录、访问密钥、API 密钥或代理令牌
• 如果您的凭证是最新的，确认 IAM 配置 中的 IAM 权限已附加到您使用的身份，并且所选模型已为您的账户和区域启用
• 运行 aws sts get-caller-identity 以确认您的请求使用哪个身份；过时的 AWS_PROFILE 或默认配置文件是权限不匹配的常见原因

Google Cloud 凭证已过期或无效

您的 Google Cloud 的 Agent Platform Google Cloud 凭证已过期或被拒绝：请求返回了 401，这是 Agent Platform 报告凭证过期的方式。

中间的操作提示因您的设置而异。稳定部分是前导 Google Cloud credentials expired or invalid：

Google Cloud credentials expired or invalid · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · API Error: 401 ...

应该做什么：

• 如果提示说凭证由此环境管理，启动 Claude Code 的应用拥有凭证，此处的其他步骤不适用：重试或联系您的管理员
• 如果您使用应用默认凭证进行身份验证，运行消息中命名的 gcpAuthRefresh 命令或 gcloud auth application-default login，并完成登录，然后重试
• 如果您通过设置了 CLAUDE_CODE_SKIP_VERTEX_AUTH 的 LLM 网关 路由，刷新 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_CUSTOM_HEADERS 中的网关令牌，然后重试
• 如果您使用服务账户密钥文件进行身份验证，确认 GOOGLE_APPLICATION_CREDENTIALS 指向有效密钥。请参阅 配置 GCP 凭证
• 如果刷新后错误重复，通过在同一 shell 中使用 gcloud auth application-default print-access-token 在 Claude Code 外确认身份有效

在 v2.1.273 之前，来自 Agent Platform 的 401 显示通用 Please run /login 或 Failed to authenticate 消息，无法刷新 Google Cloud 凭证。

Google Cloud 身份验证失败

Google Cloud 的 Agent Platform 返回了 403，它用于授权拒绝而不是过期凭证。通常您进行身份验证的身份缺少 IAM 权限，或模型未为您的项目启用。

中间的操作提示因您的设置而异。稳定部分是前导 Google Cloud authentication failed：

Google Cloud authentication failed · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · if credentials are current, check GCP IAM permissions and Vertex AI model access · API Error: 403 ...

应该做什么：

• 如果提示说凭证由此环境管理，启动 Claude Code 的应用拥有凭证，此处的其他步骤不适用：重试或联系您的管理员
• 确认 IAM 配置 中的角色已授予您进行身份验证的身份
• 确认模型已为您的项目启用。请参阅 请求模型访问

在 v2.1.273 之前，来自 Agent Platform 的 403 显示通用 Please run /login 或 Failed to authenticate 消息，无法刷新 Google Cloud 凭证。

Microsoft Foundry 身份验证失败

Microsoft Foundry 返回了 401 或 403：请求上的 Azure 凭证被拒绝，或其背后的身份无权访问 Foundry 资源。/login 无法铸造 Azure 凭证。中间的操作提示因您的设置而异。稳定部分是前导 Microsoft Foundry authentication failed：

Microsoft Foundry authentication failed · refresh your Foundry credential (ANTHROPIC_FOUNDRY_AUTH_TOKEN, ANTHROPIC_FOUNDRY_API_KEY, Azure sign-in for Entra, or your proxy token) and retry · if credentials are current, check access to the Foundry resource · API Error: 401 ...

应该做什么：

• 如果提示说凭证由此环境管理，启动 Claude Code 的应用拥有凭证，此处的其他步骤不适用：重试或联系您的管理员
• 刷新您在 配置 Azure 凭证 中配置的凭证：轮换 ANTHROPIC_FOUNDRY_API_KEY、铸造新的 ANTHROPIC_FOUNDRY_AUTH_TOKEN 或运行 az login 以便默认 Microsoft Entra 凭证链可以再次登录
• 如果凭证是最新的，确认身份有权访问 Foundry 资源。请参阅 Azure RBAC 配置

在 v2.1.273 之前，来自 Microsoft Foundry 的 401 或 403 显示通用 Please run /login 或 Failed to authenticate 消息，无法刷新 Azure 凭证。

无法加载 AWS 或 Google Cloud 凭证

Claude Code 无法从 AWS 凭证提供商链或从它运行的机器上的 Google 应用默认凭证获取可用凭证，因此没有请求到达您的云提供商。Claude Code 清除其缓存凭证并在显示此消息之前重试两次。· 之后的详细信息命名具体原因，例如过期的 SSO 会话、缺失的应用默认凭证报告为 Could not load the default credentials 或被撤销的登录报告为 invalid_grant：

API Error: Could not load AWS credentials · Could not load credentials from any providers. Check or refresh your AWS credentials and try again.
API Error: Could not load Google Cloud credentials · invalid_grant. Check or refresh your Google Cloud credentials and try again.

在 非交互式模式 中使用 -p 和在 Agent SDK 中，结构化错误代码为 cloud_credential_error。在 v2.1.267 之前，消息仅显示 API Error: 之后的详细信息文本，结构化代码为 server_error 或 unknown。

应该做什么：

• 运行您的提供商的登录命令，例如 aws sso login --profile myprofile 或 gcloud auth application-default login，然后重试。Bedrock、Agent Platform 或 Foundry 凭证未加载 显示如何在 Claude Code 外确认凭证
• 如果详细信息读作 AWS default-chain credential resolve timed out，链挂起而不是失败，因此改为遵循 AWS default-chain credential resolve timed out

AWS default-chain credential resolve 超时

AWS 默认凭证提供商链在 60 秒内未生成凭证，因此 Claude Code 停止了解析并失败了请求。此超时是 无法加载 AWS 或 Google Cloud 凭证 的一个原因。故障是本地凭证解析：请求从未到达 Amazon Bedrock、Claude Platform on AWS 或 Mantle 端点。Claude Code 在此错误出现之前清除其 凭证缓存 并重试，因此当您看到它时链已在重复尝试中停滞。

API Error: Could not load AWS credentials · AWS default-chain credential resolve timed out. Check or refresh your AWS credentials and try again.

常见原因是您的 AWS 配置文件中的 credential_process 命令等待它无法接收的输入，以及其实例元数据服务 (IMDS) 从不回答链探针的容器或 VM。

在 v2.1.267 之前，消息读作 API Error: AWS default-chain credential resolve timed out。 在 v2.1.207 之前，停滞的链使请求无限期等待而不是失败。

应该做什么：

• 在同一 shell 中使用相同的 AWS_PROFILE 运行 aws sts get-caller-identity。如果它也挂起，修复配置文件；提示交互式的 credential_process 命令是常见原因。
• 在启动 Claude Code 之前完成登录步骤，例如 aws sso login --profile myprofile，以便链从本地 SSO 缓存而不是等待浏览器流解析
• 如果您的链运行合法需要超过 60 秒的交互式登录，例如通过 aws-vault 等包装器的 SSO 与 MFA，使用 CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS 以毫秒为单位提高限制

Bedrock 设置验证超时等待 AWS

在 Bedrock 设置向导 的凭证验证期间对 AWS 的调用，例如凭证查找或身份检查，未在 60 秒限制内完成。向导停止等待并失败验证步骤：

Timed out after 60s waiting for AWS. Check your network and proxy settings; if a credential helper needs longer to prompt you, raise CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.

该数字反映您的限制：默认 60 秒，或您在 CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS 中设置的值。

常见原因是停滞对 AWS 的请求的网络或代理，包括 SSO 令牌刷新，以及仍在等待您看不到的输入的凭证 helper。仅当 helper 合法需要更多时间时才提高限制。

对 AWS 的单个停滞请求也可能在其自己的每请求超时上失败，这在同一步骤上显示较短的消息：

A request to AWS timed out. Check your network and proxy settings, then try again.

当相同的超时在模型固定步骤上发生时，向导将模型标记为 unreachable 而不是显示任一消息。

应该做什么：

• 在同一 shell 中运行 aws sts get-caller-identity。如果它也挂起，停滞在 Claude Code 外，在您的网络、您的代理或您的 AWS 配置文件中的凭证 helper 中；首先修复它。
• 在打开向导之前完成任何交互式登录，例如 aws sso login --profile myprofile
• 如果您的 AWS 配置文件中的凭证 helper 合法需要超过 60 秒来提示您，使用 CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS 以毫秒为单位提高限制

Cloud gateway 会话已过期

您通过 Claude apps gateway 登录，此机器上保存的网关会话已过期且无法更新，或网关不再接受它，例如在网关的 JWT 密钥被替换 后。如果您在交互式启动 claude 时看到此行，会话已打开且未登录网关：

Cloud gateway session expired — run /login to reconnect.

相同的行可能在会话中期出现，当网关凭证过期且 Claude Code 无法更新它时。

在 非交互式 运行、后台或其他无人值守会话或 claude 子命令（除 claude auth 外）中，Claude Code 改为在网关不再接受会话时以此消息退出：

Cloud gateway <url> no longer accepts this session. Start `claude` and sign in again with /login.

应该做什么：

• 在会话中运行 /login 并完成浏览器登录
• 对于非交互式启动，在同一环境中启动 claude，运行 /login，然后重新运行您的命令

登录超时，等待您继续

在 Claude apps gateway 登录期间，网关命名了登录的账户，Claude Code 要求您在保存凭证之前确认它。您将确认保持打开状态超过登录自己的过期，网关未颁发可更新它的刷新令牌，因此当您继续时 Claude Code 未存储任何内容：

Sign-in timed out while waiting for you to continue. Try again.

应该做什么：

• 再次运行 /login 并在登录过期之前确认账户

Gateway 拒绝了请求

您通过 Claude apps gateway 登录，请求返回了 403：网关或其背后的上游拒绝了它。再次登录不会改变拒绝，因此消息指向您的网关管理员：

Gateway refused the request · signing in again won't change this — check with your gateway administrator · API Error: 403 ...

应该做什么：

• 要求您的网关管理员查找请求。API Error: 尾部携带网关返回的拒绝
• 对于管理员：网关上的 访问控制规则 返回 403，审计日志 记录其原因，上游的授权拒绝按 上游错误消息 传递

在 v2.1.273 之前，网关会话上的 403 显示通用 Please run /login 或 Failed to authenticate 消息，再次登录不会清除拒绝。

网络和连接错误

大多数这些错误意味着来自 Claude Code 的网络请求未能到达其目的地，或者 Claude Code 和 API 之间的某些东西在返回时改变了响应；如果条目还有本地原因（例如存档写入失败），其正文会说明这一点。它们通常源于您的本地网络、代理或防火墙，或云环境的网络策略。

无法连接到 API

到 API 的 TCP 连接失败或从未完成。对于常见的连接错误代码，消息名称指出失败的类型并在括号中保留代码：

Unable to connect to API. Check your internet connection
Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)
Can't reach the API server — check your internet or DNS (ENOTFOUND)
No internet route — check your connection or VPN (EHOSTUNREACH)
Couldn't connect through your proxy (ERR_PROXY_TUNNEL) — the proxy refused the tunnel: check its credentials and that it allows this host
Connection dropped (ECONNRESET)
fetch failed
Request timed out. Check your internet connection and proxy settings

Claude Code 不识别的代码显示为 Unable to connect to API 后跟括号中的代码。某些这些消息可以显示多个代码：Connection refused 可以显示 ConnectionRefused 或 ECONNREFUSED，例如，Can't reach the API server 可以显示 ENOTFOUND 或 FailedToOpenSocket。

在 v2.1.227 之前，这些编码消息中的每一个都读作 Unable to connect to API 后跟代码，例如 Unable to connect to API (ECONNREFUSED)。

常见原因包括没有互联网访问、阻止 api.anthropic.com 的 VPN，或未配置的必需企业代理。

要做什么：

• 通过从同一 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 设置为其地址。有关设置，请参阅将 Claude Code 连接到 LLM 网关。
• 确保您的防火墙允许网络访问要求中列出的主机
• 间歇性故障会自动重试；持续故障指向本地网络问题

如果 curl 成功但 Claude Code 仍然失败，原因通常是运行时和网络之间的某些东西，而不是网络本身：

• 在 Linux 和 WSL 上，检查 /etc/resolv.conf 是否有无法到达的名称服务器。WSL 特别可以从主机继承损坏的解析器。
• 在 macOS 上，已断开连接或卸载的 VPN 客户端可能会留下隧道接口或路由规则。检查 ifconfig 是否有陈旧的 utun 接口，并在系统设置中删除 VPN 的网络扩展。
• Docker Desktop 和类似的容器运行时可以拦截出站流量。退出它们并重试以排除这种可能性。

无法连接到 Anthropic 服务

在首次运行设置期间，Claude Code 检查它是否可以到达 api.anthropic.com 和 platform.claude.com，然后再显示登录步骤。当任一检查失败时，Claude Code 打印原因并退出。

Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ECONNREFUSED
Connection to api.anthropic.com timed out after 10 seconds
A proxy is configured via HTTPS_PROXY. Check that it allows connections to the host above.

Claude Code 通过与 API 请求相同的代理配置发送检查，并给每个探针 10 秒。当失败的探针通过代理时，消息名称配置它的环境变量，例如 HTTPS_PROXY。在 v2.1.222 之前，检查使用不同的代理传输，没有超时：在具有 https:// 方案的代理 URL 后面，它可能会在 Checking connectivity... 上无限期停滞，然后即使通过同一代理的 API 请求成功也会失败。

当托管设置文件、MDM 策略或策略助手将 forceLoginMethod 设置为 "gateway" 或设置 forceLoginGatewayUrl 而不设置 forceLoginMethod 时，Claude Code 会跳过此检查。使用任一配置，Claude Code 在云网关屏幕上打开登录步骤，而不是 Anthropic 登录方法。当机器上存在托管设置源但无法读取时，Claude Code 也会跳过检查，因为该源可能包含网关配置。在 v2.1.247 之前，Claude Code 在此配置下也运行检查，当 Anthropic 的端点无法到达时以此错误退出。

要做什么：

• 如果消息名称代理变量，检查其值是否指向正确的代理，并要求您的网络团队允许通过它进行 HTTPS 连接到消息中的主机。请参阅网络配置。
• 完成无法连接到 API 中的检查。那里的 curl 测试和防火墙指导也适用于此检查。
• 如果您的组织通过云网关登录，并且此错误出现在首次运行时，请更新到 Claude Code v2.1.247 或更高版本。
• 如果您的网络是开放的，故障仍然存在，Claude Code 可能在您的国家不可用

Socket 已关闭

Socket is closed 意味着承载流式响应的连接在响应仍在到达时被关闭。最常见的原因是 Windows 上的企业代理在响应中途丢弃已建立的隧道。

根据响应的进度，Claude Code 重试请求、保留 Claude 生成的内容或结束轮次。请参阅自动重试。

在 v2.1.214 之前，Claude Code 不会重试此故障，轮次停止并显示包含 Socket is closed 的错误。

要做什么：

• 如果您看到此错误，使用 claude update 更新到 v2.1.214 或更高版本，然后再次发送您的消息
• 如果在更新后轮次在同一代理后面继续失败，请完成无法连接到 API 并检查网络配置中的代理设置

API 返回了空的或格式错误的响应

Claude Code 在失败的流式请求的非流式重试获得 HTTP 成功状态但正文不是 Claude API 消息时显示此错误：通常是 HTML 错误或登录页面、空正文或其他格式的 JSON。代理、网关或网络登录页面代替 API 回答是常见的来源。Claude Code 不会重试请求，轮次以此错误结束。

API returned an empty or malformed response (HTTP 200) — check for a proxy or gateway intercepting the request.

在该开头之后，消息报告返回的内容和哪个请求失败：

• 一个 Response: 子句，包含内容类型、正文类型（例如 body is an HTML page 或 empty body）、其大小（以字节为单位）以及响应是否携带 Anthropic 请求 id。当响应名称可识别的服务器（例如 nginx 或 cloudflare）或携带中介标头（例如 cf-ray 或 via）时，子句也会列出这些。
• 一个句子，名称失败的流式请求的 id 和触发重试的故障。当流在故障之前打开时，它也报告有多少流事件到达，如果有的话，当尝试失败时流已沉默多长时间。

在 v2.1.234 之前，消息在 intercepting the request 之后结束。

在 v2.1.271 之前，在非 JSON 内容类型（例如 text/plain）下携带有效 API 消息的回复也以此错误结束轮次。某些 LLM 网关对非流式回复使用该内容类型。

要做什么：

• 阅读 Response: 子句以查看哪个系统回答。HTML 正文、没有 Anthropic 请求 id 或名称服务器（例如 nginx 或 cloudflare）意味着 Claude Code 和 API 之间的某些东西代替回答
• 如果您通过LLM 网关路由，使用直接请求测试路由，并修复返回非 API 响应的跳跃
• 在具有登录页面的网络上（例如访客 Wi-Fi），在浏览器中完成登录，然后重试
• 如果只有通过您的网关的非流式路由被破坏，设置 CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 以便在流中失败的请求转到正常重试路径而不是此回退，除非流式端点本身返回 404，Claude Code 仍然会回退

流式响应在接收任何完整数据之前结束

来自您的模型提供商的流式响应完成而没有传递任何可用数据，因此 Claude Code 重新发送了没有流式的请求以完成轮次。Claude Code 在交互式会话中每个会话显示一次警告。在 v2.1.239 之前，Claude Code 无声地重试而不流式。

Streaming response ended before any complete data was received. Retrying without streaming. If this keeps happening, check any proxy or gateway between Claude Code and your model provider.

Claude Code 发送每个受影响的请求两次：空流式尝试和重试。常见原因是在返回时消耗或转换流式响应正文的代理或网关。

要做什么：

• 配置 Claude Code 和您的模型提供商之间的任何代理或网关，以通过未修改的流式响应正文和其标头
• 在Amazon Bedrock 上，请参阅网关或代理后面的流式错误了解标头和正文要求

Bedrock 流式响应具有意外的 content-type

Claude Code 和Amazon Bedrock 之间的网关或代理正在转换流式响应正文或其 Content-Type 标头。Amazon Bedrock 将响应流式传输为 application/vnd.amazon.eventstream。Claude Code 不会解码它无法读取的正文，而是拒绝报告不同 content-type 的成功流式响应。Claude Code 不会重试请求。

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

在 v2.1.208 之前，相同的配置错误显示为 API Error: Truncated event message received，在整个响应被缓冲后。

要做什么：

• 配置网关以通过未修改的 InvokeModelWithResponseStream 响应正文及其 Content-Type 标头。将流重新发出为服务器发送事件的中介是常见原因。
• 设置 CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 隐藏此错误，但 Claude Code 不会在重写的标头下解码二进制正文，因此这些请求回退到较慢的非流式路径。请参阅网关或代理后面的流式错误。

SSL 证书错误

您网络上的代理或安全设备正在用其自己的证书拦截 TLS 流量，Claude Code 不信任它。

Unable to connect to API: SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store · see https://code.claude.com/docs/en/network-config
Unable to connect to API: Self-signed certificate detected (SELF_SIGNED_CERT_IN_CHAIN). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store · see https://code.claude.com/docs/en/network-config

在 v2.1.273 之前，两条消息都在 Check your proxy or corporate SSL certificates 处结束，没有 OpenSSL 代码或 NODE_EXTRA_CA_CERTS 提示。

从 v2.1.199 开始，证书验证失败不会重试，因此此错误出现在第一次尝试而不是完整重试预算之后。早期版本在显示它之前花费几分钟重试。瞬时 TLS 条件（例如握手超时）仍然重试。

在 /login 和启动连接检查期间，相同的故障产生不同的消息：

SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run `claude doctor` for details.

在Amazon Bedrock 上，Claude Code 本身发送给 AWS 的请求，例如 STS 和 SSO 角色凭证调用、模型发现和设置向导的检查，取决于相同的证书配置。请参阅TLS 检查代理后面的证书错误。

要做什么：

• 导出您组织的 CA 包并使用 NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem 指向 Claude Code
• 有关完整设置说明，请参阅网络配置
• 不要设置 NODE_TLS_REJECT_UNAUTHORIZED=0，这会完全禁用证书验证

云会话中不允许的主机

来自云会话或例程的出站 HTTP 请求被环境的网络策略阻止。

HTTP 403
x-deny-reason: host_not_allowed

您也可能看到与目标的真实证书不匹配的 TLS 证书。云会话通过代理路由出站流量以强制执行网络策略，因此不匹配的证书意味着代理终止了连接，而不是目标。

这不是客户端网络问题。云会话和例程在沙箱 VM 内运行，其通过会话网络的出站流量被过滤到云环境的允许列表；GitHub 操作和 MCP 连接器流量使用单独的通道，这就是为什么当其他主机被阻止时它们可以继续工作。默认环境使用受信任访问，允许默认允许列表的包注册表、云提供商 API、容器注册表和常见开发域，并阻止该路径上的其他域。

要做什么：

这些步骤更改您自己的环境之一。组织共享环境在选择器中以只读方式打开，因此请要求所有者从管理设置中的云环境页面更改其网络访问。

• 打开例程进行编辑，或启动云会话。选择显示您的环境名称（例如默认）的云图标以打开选择器。将鼠标悬停在您的环境上，然后单击设置图标。
• 在更新云环境对话框中，将网络访问从受信任更改为自定义，然后将被阻止的域添加到允许的域。每行输入一个域。检查也包括常见包管理器的默认列表以将默认允许列表与您的自定义域保持在一起。如果您想要不受限制的访问，请改为选择完全。
• 单击保存更改。下一次运行使用更新的允许列表。

有关访问级别和默认允许列表，请参阅网络访问。本地 CLI 会话不受此策略影响。

代理拒绝了连接

当 Claude 通过您在 HTTPS_PROXY 中设置的代理或相关代理变量读取工件时，您会看到此消息。工件内容来自 *.frame.claudeusercontent.com，因此 Claude Code 首先向代理发送 CONNECT 请求，要求它打开到该主机的隧道。当代理拒绝时，没有任何东西到达主机，消息携带代理的 HTTP 状态：

artifact content fetch failed (proxy refused the connection: HTTP 407)
artifact content fetch failed (proxy refused the connection: HTTP 403)
the proxy refused the connection to the artifact's content host (HTTP 502)

状态是代理对 CONNECT 的答案。主机从未回答，因此每个状态指向不同的修复：

• HTTP 407：代理需要它没有获得的凭证。将它们放在代理 URL 中，如基本身份验证所示。
• HTTP 403：代理拒绝隧道到 *.frame.claudeusercontent.com。要求运行代理的人允许该主机，网络访问要求列出了该主机。
• 任何其他状态，例如 HTTP 502：代理由于其自己的原因没有打开隧道，例如无法到达主机。在代理的日志中查找状态。
• unreadable reply 代替状态：代理地址处的任何东西都没有用 HTTP 状态行回答。检查地址是否是 HTTP 代理。

要做什么：

• 检查代理变量中的地址和凭证，如代理配置所述，然后从启动 Claude Code 的 shell 运行 curl -x http://proxy.example.com:8080 -I https://api.anthropic.com，使用您自己的代理 URL。在 Windows PowerShell 上，运行 curl.exe。如果此探针以相同方式失败，首先修复代理设置。如果成功，拒绝特定于工件主机。
• 如果您的网络让 Claude Code 直接到达工件主机，将 .frame.claudeusercontent.com 添加到 NO_PROXY。保持条目狭窄：更广泛的 .claudeusercontent.com 条目也会绕过 bridge.claudeusercontent.com 的代理，具有IP 允许列表的组织需要将其保留在代理上。

在 v2.1.238 之前，Claude Code 将拒绝的隧道报告为通用网络错误。

云环境服务返回了空的或意外的响应

Claude Code 在多个点请求您的云环境列表，例如当您从 CLI 创建云会话或运行 /remote-env 时。当它无法读取服务器的答案时，它显示以下消息之一：

The cloud environments service returned an empty response (HTTP 200 with no body). This is usually temporary — try again in a moment.
The cloud environments service returned a response in an unexpected format (HTTP 200 with a non-JSON body). This is usually temporary — try again in a moment.
The cloud environments service returned a response in an unexpected format (HTTP 200 without a usable environments list). This is usually temporary — try again in a moment.

服务器接受了请求但用不是环境列表的正文回答：空、不是 JSON 或没有列表的 JSON。这通常伴随服务端中断，并自行清除。根据请求列表的表面，Claude Code 可能会添加前缀，例如 /remote-env 对话框中的 couldn't list environments:。

要做什么：

• 重试操作。Claude Code 每次都再次请求列表
• 如果消息继续出现，检查 status.claude.com 是否有活跃事件

在 v2.1.236 之前，Claude Code 显示原始 JavaScript TypeError 而不是这些消息。

无法重新连接到您的 Remote Control 会话

Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.

使用 claude --resume 或 claude --continue 恢复会重新连接到该对话中记录的Remote Control 会话。此消息意味着重新连接因可能是临时的原因（例如网络中断或服务器错误）而失败，因此 Claude Code 无法确认远程会话是否仍然存在。您的本地会话继续运行而不使用 Remote Control。

要做什么：

• 运行 /remote-control 重试连接
• 使用 claude --remote-control 启动新会话以创建新的 Remote Control 会话
• 对于其他 Remote Control 启动消息，请参阅Remote Control 故障排除

如果服务器报告之前的会话已消失，您不会看到此消息。Claude Code 在其位置启动新会话或显示 Previous session is unavailable — run /remote-control to start a new one，取决于对话的重新连接记录。从 v2.1.227 到 v2.1.231，Claude Code 显示了以 Remote Control could not resume the previous session under the current login 开头的消息，早期版本的行为也不同。

此机器离线时会话已结束

Claude Code 在运行 claude remote-control 的终端中显示此消息，在您的机器离线足够长的时间后，服务器清理了您的机器正在服务的 Remote Control 环境。该环境中的会话已结束，您无法恢复它们。计数是已结束的会话数。

2 sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.

要做什么：

• 当 Claude Code 在此消息下列出保留的 worktrees 时，从它们中拾取任何未提交的工作
• 运行 claude remote-control 启动新环境

无法共享成绩单

在您同意从调查提示（例如会话质量调查）共享您的会话成绩单后，Claude Code 将其上传到 Anthropic，或在第三方提供商上、Claude apps gateway 会话上以及当没有 Anthropic 凭证可用时保存本地存档。此消息意味着共享未完成。

Couldn't share the transcript.

上传必须符合 8 MiB 限制。在长会话上，Claude Code 逐步删除共享的部分，最后一个请求的模型设置首先，然后是结构化对话和子代理成绩单，仅当没有减少的版本可以发送或网络或服务器错误停止上传时才显示此消息。当 Claude Code 保存本地存档时，消息意味着它无法写入存档。

要做什么：

• 运行 /feedback 发送成绩单并描述发生了什么。如果 /feedback 在您的环境中不可用，请参阅报告错误
• 如果其他请求也失败，检查您的网络连接并查看无法连接到 API

请求错误

这些错误与您的请求内容有关。大多数来自 API 拒绝请求后的返回；少数是由 Claude Code 在发送任何请求之前在本地生成的。

提示词过长

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

Prompt is too long

在交互式会话中，Claude Code 将此错误显示为：

Context limit reached · /compact or /clear to continue

当设置了 DISABLE_COMPACT 时，该行仅显示 /clear。较长形式的错误，例如下面的压缩失败形式，保留 Prompt is too long · 的措辞。在 -p 输出和记录中，文本保持为 Prompt is too long。

当您在用户设置中关闭自动压缩时，该行也会显示：

Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on

/config 中的自动压缩切换将 autoCompactEnabled 写入用户设置。该提示仅在 /config 更改会生效时出现。例如，当 DISABLE_AUTO_COMPACT 或 DISABLE_COMPACT 关闭自动压缩时，它不会出现。当更高优先级的范围（如项目或托管设置）将 autoCompactEnabled 设置为 false 时，它也不会出现。在 v2.1.235 之前，该行没有自动压缩提示。

Amazon Bedrock 将此条件报告为 Input is too long for requested model.，Claude Code 以相同方式处理。在 v2.1.217 之前，Claude Code 不识别 Bedrock 的措辞，因此自动压缩从不在其上触发，/compact 失败并显示相同错误。

Claude apps gateway 在云上游以提供商自己的错误形状拒绝请求时，将此条件报告为 capability_rejected: prompt_too_long。Claude Code 将该令牌视为与 Prompt is too long 相同。在 v2.1.228 之前，Claude Code 不识别该令牌，因此自动压缩不会在其上触发。

当自动压缩在此轮上运行并因底层错误（如不可用的模型或身份验证失败）而失败时，该消息在分隔符后命名该错误：

Prompt is too long · automatic compaction failed: <the underlying error>

首先解决命名的错误；在您这样做之前，/compact 会因相同错误而失败。在 v2.1.229 之前，失败的自动压缩显示 Prompt is too long 而不显示原因。

当自动压缩在此错误上运行时，它通常会总结您最早的交换并保留最新的。作为最后的手段，Claude Code 会以不同的方式总结：

• 当它无法总结任何完整交换时，Claude Code 会逐字保留您最新的提示，并总结其前面的所有内容。
• 在这种情况下，当对话不以您的提示结尾时，Claude Code 会改为总结整个对话。

当它将转发的内容不包含模型回复且您自己的文本少于约 1,000 个令牌（如在超大粘贴后发送的短重试）时，Claude Code 会跳过此恢复。运行 /clear 以重新开始。在 v2.1.269 之前，每当压缩无法总结完整交换时就会失败，因此处于该状态的会话在每一轮都会再次遇到此错误。

单交换对话没有更早的轮次可总结。当自动压缩会在其上运行时，Claude Code 会跳过尝试并解释请求中填充的内容。当 API 在其错误中不报告令牌计数时，消息读取：

Prompt is too long · this conversation is a single exchange and cannot be compacted — the request size comes mostly from system prompt, tool definitions, or attachments.

当 API 在其错误中报告令牌计数时，Claude Code 将其与对话大小的自己估计进行比较，以判断请求的大部分是什么：对话自己的内容，还是 Claude Code 与其一起发送的系统提示、工具定义和附件内容。当对话自己的内容是请求的大部分时，消息读取：

Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) and this conversation's own content is most of it. A single-exchange conversation cannot be compacted; start with less content (smaller files or pasted text).

当请求的大部分在对话之外时，消息读取：

Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) but this conversation is only ~<conversation tokens> tokens — the rest is system prompt, tool definitions, and attachment content. A single-exchange conversation cannot be compacted; reduce attached files/tools or start with less context.

在 v2.1.162 之前，Claude Code 尝试了压缩，并在失败时显示裸露的 Prompt is too long。

要做什么：

• 运行 /compact 以总结较早的轮次并释放空间，或运行 /clear 以重新开始。如果 /compact 回答 Not enough messages to compact.，则对话是单个交换，没有更早的内容可总结，因此空间由该单个提示和 Claude Code 与每个请求一起发送的内容占用：运行 /clear 并使用较少的粘贴文本或较小的附件重新发送，或使用下面的步骤减少工具定义和内存文件
• 运行 /context 以查看窗口消耗内容的分解：系统提示、工具、内存文件和消息
• 使用 /mcp disable <name> 禁用您未使用的 MCP 服务器，以从上下文中删除其工具定义
• 修剪大型 CLAUDE.md 内存文件，或将说明移到仅在相关时加载的路径范围规则中
• 子代理从父会话继承每个 MCP 工具定义，这可能在第一轮之前填满其上下文窗口。在生成子代理之前，禁用您未使用的 MCP 服务器。
• 自动压缩默认开启，通常可防止此错误。如果您在 /config 中或使用 DISABLE_AUTO_COMPACT 关闭了它，请将其重新打开。如果您保持关闭，请在窗口填满之前自己运行 /compact。

有关上下文如何填满的交互式视图，请参阅探索上下文窗口。

上下文超过令牌限制

当对话超过模型的上下文窗口时，/context 在其输出顶部显示此警告。请求失败，显示 Prompt is too long，直到您释放空间。交互式会话将该错误显示为 Context limit reached 行。

Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.

当您超过的限制是压缩窗口（如 1M 上下文模型上的 200K 边界）时，警告的读取方式不同。压缩窗口可以位于模型的上下文窗口下方，因此超过它的请求仍然可以成功。

Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.

当您设置了 DISABLE_COMPACT 时，两种形式都命名 /clear 而不是 /compact。

要做什么：

• 在多轮对话中，运行 /compact 以总结较早的轮次并释放空间。要重新开始，请运行 /clear
• 有关减少使用的更多方法，请参阅 Prompt is too long

在 v2.1.216 之前，/context 显示超过 100% 的使用情况，没有警告行解释这意味着什么或如何恢复。

压缩期间出错：对话过长

/compact 本身失败，因为没有足够的可用上下文来保存它生成的摘要。

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

当窗口在自动压缩触发时已满，或当您在看到 Prompt is too long 后运行 /compact 时，可能会发生这种情况。在交互式会话中，该错误是 Context limit reached 行。

要做什么：

• 按 Esc 两次打开消息列表并回退几轮。这会从上下文中删除最近的消息。然后再次运行 /compact。
• 如果回退没有释放足够的空间，运行 /clear 以启动新的会话。您之前的对话被保留，可以使用 /resume 重新打开。

此消息和其他 /compact 失败以错误样式显示。在 v2.1.216 之前，它们以与成功命令输出相同的暗淡样式呈现，因此您可能会将失败的压缩读取为成功。

请求过大

原始请求体在令牌化之前超过了 API 的 32MB 限制，通常是由于大型粘贴内容、工具结果或附件。此限制与上下文窗口分开。

Request too large (max 32MB). Accumulated images and attachments in the conversation pushed the request over the limit. Run /compact, or double press esc to go back and remove attachments.

当请求直接进入 Claude API 且 API 本身拒绝了它时，Claude Code 会测量对话并根据恢复是否可行来表述消息。通过代理、网关或云提供商，您会获得一般消息。测量的形式：

• Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).：图像或文档将请求推过了限制。Claude Code 会在去除它们后重试。
• Request too large for the API's 32MB request limit：消息本身超过了限制，因此消息说 compacting cannot make it fit，Claude Code 不会重试。在非交互模式中，消息告诉您减少输入或启动新会话。

在 v2.1.212 之前，具有足够累积图像的对话在每一轮都失败，显示 Request too large (max 32MB). Double press esc to go back and try with a smaller file. 在 v2.1.229 之前，Claude Code 为每次拒绝显示附件建议，即使压缩无法帮助。

要做什么：

• 如果消息说 compacting cannot make it fit，按 Esc 两次回退到添加大型内容的轮次之前，或运行 /clear 以重新开始
• 否则，运行 /compact，它会删除累积的图像和附件
• 按路径引用大型文件而不是粘贴其内容，以便 Claude 可以分块读取它们
• 对于图像，请参阅下面的图像过大

图像过大

粘贴或附加的图像超过了 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

Claude Code 用文本占位符替换无法处理的图像并重试，因此后续消息成功。在 2.1.142 之前的版本上，粘贴的图像可能保留在对话中，并在每个后续消息上重复相同的错误。要在这些版本上恢复，按 Esc 两次并回退到添加图像的轮次之前。

要做什么：

• 在粘贴之前调整图像大小。API 接受单个图像最长边最多 8000 像素的图像，或当许多图像在上下文中时最多 2000 像素。
• 拍摄相关区域的更紧密屏幕截图，而不是整个屏幕

无法调整图像大小

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.
Unable to resize image — it is a CMYK JPEG, which Claude Code cannot decode, and at …px it is over the 2000x2000px limit, so it cannot be sent. Re-save it as an RGB PNG or JPEG and try again.
Unable to resize image — it is an animated WebP whose first frame Claude Code cannot decode, and at …px it is over the 2000x2000px limit, so it cannot be sent. Save its first frame as a PNG or JPEG and try again.
Unable to resize image — its pixels could not be decoded (the file may be damaged, or use an encoding Claude Code cannot read), and it is over the … API limit (… raw, … base64), so it cannot be sent. Re-save it as a PNG or JPEG and try again.

Claude Code 通常会自动调整大型图像的大小。这些错误意味着无法解码或调整图像大小以适应 API 限制。

要做什么：

• 如果消息要求您转换图像，请将其转换为 PNG、JPEG、GIF 或 WebP，然后再次附加。Claude Code 可以从文件头为这些格式验证尺寸，而无需解码图像。
• 如果消息报告尺寸或大小限制，请在附加之前将图像调整或重新压缩到该限制以下。
• 如果消息命名原因，例如 CMYK JPEG、动画 WebP 或可能损坏的文件，请以消息建议的格式重新保存图像并再次附加。

PDF 错误

您附加的 PDF 无法处理。消息在此处以非交互形式显示；在交互式会话中，它们会提示您按 Esc 两次并重试。

PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).
PDF is password protected. Try using a CLI tool to extract or convert the PDF.
The PDF file was not valid. Try converting it to text first (e.g., pdftotext).

要做什么：

• 对于超大 PDF，要求 Claude 使用 Read 工具读取页面范围，而不是附加整个文件，或使用 pdftotext 等工具提取文本并按路径引用输出文件
• 对于受保护或无效的 PDF，删除密码或从其源应用程序重新导出文件，然后重试

不允许额外输入

Claude Code 和 API 之间的代理或 LLM 网关删除了 anthropic-beta 请求头，因此 API 拒绝了依赖它的字段。

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

Claude Code 发送 context_management 和 effort 等仅限测试版的字段，以及启用它们的 anthropic-beta 头。当网关转发正文但删除头时，API 会看到它不识别的字段。

要做什么：

• 配置您的网关以转发 anthropic-beta 头。有关网关必须转发的内容，请参阅功能传递。
• 作为后备，在启动前设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。禁用预发布功能涵盖确切范围。

工具输入架构无效

请求中的工具声明了 input_schema，该架构未通过 API 的 JSON Schema 验证，因此 API 拒绝了整个请求。tools. 后的数字是失败工具在请求的工具列表中的位置，而不是您可以查找的名称。

API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid
API Error: 400 ... tools.N.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$'

第一种形式意味着架构不是有效的 JSON Schema draft 2020-12。第二种意味着顶级属性名称与消息引用的模式不匹配。

Claude Code 在加载服务器的工具时排除其输入架构会失败此验证的 MCP 工具，因此请求通常永远不会包含一个。

在禁用标志获取的部署上，或在标志从未到达的机器上，Claude Code 在服务器的日志中记录哪个工具会被拒绝，但仍然发送它，因此此错误仍然可能发生。

该错误也可能发生在其架构在 $schema 中声明 JSON Schema 方言（而不是 draft 2020-12）的工具上。Claude Code 不会根据 JSON Schema 元架构检查这些架构，尽管顶级属性名称检查仍然适用。

在 v2.1.216 之前，没有部署运行排除检查。

要做什么：

• 如果您的 Claude Code 版本早于 v2.1.216，运行 claude update。
• 删除或禁用声明无效架构的 MCP 服务器。该错误仅按位置命名工具。在 v2.1.216 或更高版本上，检查每个服务器的日志，查找命名其输入架构会被拒绝的工具的行。如果没有日志命名一个，一次禁用一个服务器。
• 如果您维护服务器，请修复工具的 input_schema。架构必须是有效的 JSON Schema，顶级属性名称必须为 1 到 64 个字符长，并仅使用 ASCII 字母和数字、_、. 和 -。请参阅具有无效输入架构的工具。

所选模型存在问题

配置的模型名称未被识别，或您的帐户无权访问它。从 v2.1.160 开始，尾部提示（此处以其交互形式显示）因表面而异。

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

要做什么：

• 交互式 CLI：运行 /model 从您帐户可用的模型中选择。
• 非交互模式 (-p)：使用有效的别名或 ID 传递 --model，或设置 ANTHROPIC_MODEL。错误文本在此表面上显示 Run --model。
• Agent SDK：错误文本省略提示，因为模型是以编程方式设置的。在 TypeScript 中的 Options 上设置 model，或在 Python 中设置 ClaudeAgentOptions(model=...)，并处理结构化的 model_not_found 错误以显示您自己的重试或模型选择器。
• 使用别名（如 sonnet 或 opus）而不是完整的版本化 ID。别名解析为维护的默认值，因此它们不会过时。请参阅模型配置。
• 如果错误的模型在 CLI 中不断返回，则某处设置了过时的 ID。按优先级顺序检查您可以设置模型的位置，并删除过时的值。
• 新推出的模型可能在 Anthropic API 上可用，但在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上可用之前。如果您在这些提供商之一上固定了新模型 ID 并看到此错误，请检查您提供商的模型目录以了解您所在地区的可用性，并保持固定前一个版本，直到新版本出现。
• Claude Code 将过期的 claude.ai 登录报告为登录过期，而不是此错误。在 v2.1.206 之前，无法再刷新的过期登录对每个模型都失败，显示此错误；如果您在较旧版本上看到这种情况，请运行 /login。
• 对于 Google Cloud 的 Agent Platform 部署，请参阅 Google Cloud 的 Agent Platform 故障排除。

模型不是公认的模型 ID

您传递给模型切换的模型字符串不是模型别名、此 Claude Code 版本知道的模型 ID，也不是以 claude- 开头的 ID。常见原因是 ID 中的拼写错误、显示名称（如 Sonnet 5，其中需要 ID claude-sonnet-5）或仅较新 Claude Code 版本识别的别名。Claude Code 立即拒绝切换。在 v2.1.200 之前，Claude Code 保存字符串并在下一个请求时失败，显示所选模型存在问题。

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

尾部提示命名最接近的匹配别名或模型 ID。当没有足够接近的内容时，它读取 Run /model to see available models.。

Claude Code 在请求切换时在本地生成此错误，在发送任何 API 请求之前。它适用于通过 Agent SDK setModel() 方法设置模型的情况，通过运行 Claude Code CLI 的应用程序（如 Desktop app），或当您从通过 Remote Control 连接的设备选择模型时。在 v2.1.260 之前，检查不涵盖 Remote Control 选择，因此 Claude Code 应用了选择，下一个请求失败，显示所选模型存在问题。

要做什么：

• 运行 /model 不带参数以打开选择器并从您帐户可用的模型中选择，然后传递那里显示的别名或 ID
• 如果您使用了较新 Claude Code 版本支持的别名，运行 claude update。以 claude- 开头的完整 ID 通过此本地检查，即使模型比您的 Claude Code 版本更新。服务器仍然可能需要该模型的最低版本；请参阅 Claude Code 不支持此模型。
• v2.1.200 之前保存的模型不会被此检查修复。如果过时的值不断返回，请从设置您的模型下列出的位置删除它。
• 检查仅在 Anthropic API 上运行。在任何其他提供商或网关上，包括自定义 ANTHROPIC_BASE_URL，提供商定义模型名称，因此 Claude Code 接受任何字符串并将其传递。Claude Code 仍然可以在请求时写入无法识别的模型诊断行，在每个提供商上。

模型未找到

您使用 /model <name> 选择了模型，Claude Code 无法确认存在具有该名称的模型。当名称不是 model alias 或 Claude Code 在本地接受的另一种拼写时，/model 使用最小 API 请求验证它，此错误通常是您的 API 端点的答案。无法成为模型 ID 的名称（如包含空格的名称）会获得相同的消息。

Model 'claude-opus-9' not found

在具有提供商特定模型 ID 的提供商上，消息可能会添加 Try '...' instead 建议，该建议命名您提供商的后备模型 ID。

要做什么：

• 运行 /model 不带参数并从您帐户可用的模型中选择，或使用 model alias（如 sonnet），它解析为维护的默认值
• 如果您输入了完整 ID，请根据您提供商的模型目录检查它。新推出的模型可能在 Anthropic API 上可用，但您的提供商或地区尚未提供。
• 在 v2.1.265 之前，/model 也以此错误拒绝了 opusplan[1m] 别名拼写。在这些版本上，更新 Claude Code，或在设置中或使用 --model 设置模型。

Claude Opus 在 Claude Pro 计划中不可用

您的活跃订阅计划不包括您选择的模型。

Claude Opus is not available with the Claude Pro plan. If you have updated your subscription plan recently, run /logout and /login for the plan to take effect.

要做什么：

• 运行 /model 并选择您的计划包括的模型
• 如果您最近升级了计划但仍然看到这个，运行 /logout 然后 /login。存储的令牌反映您登录时的计划，因此在现有会话中升级 claude.ai 不会生效，直到您重新进行身份验证。
• 有关每个计划包括哪些模型，请参阅 claude.com/pricing

Claude Code 不支持此模型

API 因您的 Claude Code 版本低于所需最低版本而拒绝了请求，返回 400。要么您选择的模型需要较新版本（服务器按模型检查），要么您的组织政策需要一个。400 携带错误代码 claude_code_version_too_old，消息说明适用的最低版本。

API Error: 400 Claude Code 2.1.219 does not support this model; version 2.1.255 or newer is required. Run 'claude update', or update the Claude desktop app, then try again.

组织政策措辞读取：

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

要做什么：

• 运行 claude update，或更新 Claude 桌面应用，然后启动新会话
• 对于按模型措辞，您可以通过使用 /model 切换到另一个模型来继续在当前会话中工作
• 对于组织政策措辞，在继续之前更新

模型受您的组织设置限制

您的组织管理员在 claude.ai 管理控制台中禁用了此模型，或它被托管设置中的 availableModels 允许列表排除。当受限制的模型使用 --model、ANTHROPIC_MODEL 或 model 设置设置时，Claude Code 替换允许的模型并继续。为受限制的模型键入 /model <name> 被拒绝，显示 Run /model to choose a different model.，会话保持其当前模型。替换通知也可能在会话中期出现，在组织管理员在 claude.ai 管理控制台中禁用会话正在运行的模型之后。

Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.

以代理、技能或命令名称为前缀的通知意味着限制适用于该子代理的请求模型：子代理在替换模型上运行，您的会话模型保持不变。在 v2.1.223 之前，Claude Code 仅为使用 Agent 工具启动的子代理显示通知。

Claude Code 将模型族别名（opus、sonnet、haiku 或 fable 之一）视为对该族的请求，而不是对其最新版本的请求。在 Anthropic API 和 Claude Platform on AWS 上，受限制的族别名解析为您的组织和 availableModels 允许列表允许的族的最新版本，替换通知命名该版本。Claude Code 仅当族的每个版本都受限制时才拒绝 /model <alias>。在 v2.1.205 之前，族别名基于其最新版本单独被替换或拒绝，即使同一族的较旧版本被允许。

要做什么：

• 运行 /model 从您的组织允许的模型中选择。受限制的模型从选择器中隐藏。
• 如果受限制的模型在 --model、ANTHROPIC_MODEL、设置文件的 model 字段或子代理、技能或命令的 model frontmatter 中设置，删除或更新该值，以便通知不会再次出现
• 如果您需要访问受限制的模型，请要求您的组织管理员启用它。请参阅组织模型限制。

模型切换被 PreModelSwitch hook 阻止

PreModelSwitch hook 没有批准您或客户端请求的模型切换，因此会话保持其当前模型。当切换来自 Agent SDK 主机或 Remote Control 而不是您键入的命令时，消息读取 Model switch blocked by a PreModelSwitch hook 而不命名目标模型。

Model switch to Opus 4.6 was blocked by a PreModelSwitch hook: Opus 4.6 is retired for this project. Use a newer model.

冒号后的原因说明拒绝切换的原因：

• hook 写入的原因：PreModelSwitch hook 在拒绝切换或要求确认时提供了该原因。解决它要求的内容，或选择您的 hook 允许的模型。
• PreModelSwitch hook <name> did not respond before its timeout：在其超时之前不回答的 hook 阻止切换。修复挂起的命令或提高该 hook 的 timeout，然后再次切换。
• confirmation required, and this session cannot ask：hook 回答 ask 而没有原因，控制请求无法显示确认提示。-p 运行中的 /model 命令以原因后的 (run /model interactively to confirm) 报告相同条件。从交互式会话进行切换，或更改 hook 对此模型的决定。
• so organization-managed PreModelSwitch hooks could not be checked：Claude Code 无法判断您的组织的托管插件提供哪些 PreModelSwitch hook，例如因为托管插件加载失败。这些 hook 之一可能阻止切换，因此 Claude Code 拒绝而不是应用未检查的切换。原因的开始命名失败的内容。Claude Code 在每次切换尝试时重新检查，因此已清除的失败停止阻止；如果它继续失败，运行 claude --debug 并再次切换以捕获详细信息，然后修复插件或要求您的管理员修复它。
• a PreModelSwitch hook failed before answering 或 PreModelSwitch hooks were cancelled (the control stream closed) before answering：hook 运行在没有判决的情况下结束，Claude Code 不将其视为批准。运行 claude --debug 以查看失败的内容，然后再次切换。

在 v2.1.260 之前，托管插件拒绝读取 plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log。Claude Code 重试了一次插件加载，然后在会话中拒绝了后来的切换，即使您的组织没有管理任何插件。在这些版本上重启会话以再次运行插件加载。

无法将其保存为您的默认值

您选择了一个模型以保存为您的默认值，例如使用 /model <name> 或 /model 选择器中的 Enter，Claude Code 无法将选择写入您的用户设置文件 ~/.claude/settings.json。切换本身已应用，因此当前会话在您选择的模型上运行，但您的默认值保持不变，下一个会话在旧值上启动。

Set model to Fable 5.1 for this session only · couldn't save it as your default: ~/.claude/settings.json can't be written (EROFS)

文件路径后的原因说明失败的内容：

• can't be written (<code>)：写入失败，显示括号中的操作系统错误代码，如 EROFS（当文件或其链接到的文件位于拒绝写入的文件系统上时）。使文件可写并再次切换。如果另一个工具生成文件，请在该工具中设置 model 键；请参阅您在 Claude Code 中所做的更改在新会话中丢失。
• isn't valid JSON：磁盘上的文件不解析，Claude Code 保持不动而不是覆盖它无法读回的内容。修复语法错误，然后再次切换；请参阅修复损坏的设置文件。

以 couldn't confirm it was saved as your default (~/.claude/settings.json is still being written) 结尾的通知意味着写入在三秒后未完成。它在后台继续，因此默认值可能仍然被保存；检查您的下一个会话启动的模型，或再次运行 /model <name>。

在 v2.1.265 之前，通知说模型被保存为您的新会话默认值，即使写入失败。

thinking.type.enabled 此模型不支持

您的 Claude Code 版本早于所选模型的最低版本。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 并重启 Claude Code。Opus 4.7 需要 v2.1.111 或更高版本。Opus 4.8 需要 v2.1.154 或更高版本。Sonnet 5 需要 v2.1.197 或更高版本。Opus 5 需要 v2.1.219 或更高版本。Opus 5.5 需要 v2.1.280 或更高版本
• 如果您无法升级，运行 /model 并选择 Opus 4.6 或 Sonnet 4.6
• 如果您在 Agent SDK 中遇到这个，升级 SDK 包。Opus 4.8 需要 TypeScript SDK v0.3.154 或更高版本和 Python SDK v0.2.88 或更高版本。Sonnet 5 需要 TypeScript SDK v0.3.197 或更高版本。Opus 5 需要 TypeScript SDK v0.3.219 或更高版本。Opus 5.5 需要 TypeScript SDK v0.3.280 或更高版本

关闭思考时努力不可用

您关闭了扩展思考并以努力级别高于 high 运行。模型不接受该组合，因此 API 拒绝了请求。

API Error: Effort 'xhigh' isn't available with thinking turned off on this model · run /effort high to continue, or turn thinking back on (unset MAX_THINKING_TOKENS=0)

要做什么：

• 降低努力级别到 high 或以下。
• 打开思考，例如通过取消设置 MAX_THINKING_TOKENS 或从您的设置中删除 "alwaysThinkingEnabled": false。

在 v2.1.242 之前，Claude Code 显示了 API 自己的消息：API Error: 400 output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking. 在 v2.1.251 之前，Claude Code 以您设置的努力级别发送请求，因此 Opus 5 拒绝了关闭思考时高于 high 的每个请求。Claude Code 现在向它知道拒绝该组合的模型（如 Opus 5）发送努力 high，因此在 v2.1.251 或更高版本上，此错误仅从 Claude Code 不知道拒绝它的模型到达您。

思考预算超过输出限制

配置的扩展思考预算超过最大响应长度，因此实际答案没有剩余空间。

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

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

要做什么：

• 降低 MAX_THINKING_TOKENS，或提高 CLAUDE_CODE_MAX_OUTPUT_TOKENS 高于思考预算
• 请参阅扩展思考以了解预算如何与输出长度交互

工具使用或思考块不匹配

对话历史以不一致的状态到达 API，通常在工具调用被中断或轮次在流中期被编辑后。

API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.
API Error: 400 orphaned tool_result in conversation history. Run /rewind to recover the conversation.
API Error: 400 duplicate tool_use ID in conversation history. 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 期望的匹配。

要做什么：

• 如果您使用 Opus 4.7 或 Opus 4.8，首先运行 claude update。v2.1.156 之前的版本可以在正常工具使用期间触发此错误，/rewind 不会清除它。
• 运行 /rewind，或按 Esc 两次，回退到损坏轮次之前的检查点并从那里继续。请参阅检查点以了解如何创建和恢复检查点。

删除了不支持的工具内容

当 Claude Code 直接连接到 Anthropic API 并加载或预览保存的会话时，它删除 Anthropic API 不接受的工具内容，并在两个思考块之间删除的内容所在的位置留下此行：

[Unsupported tool content removed]

当 Anthropic API 以外的东西以 API 的格式回答时，这样的内容到达会话文件，通常是通过 ANTHROPIC_BASE_URL 设置的第三方代理，它转换另一个提供商的工具调用。Claude Code 仅在会话直接连接到 Anthropic API 时删除它，并在会话通过代理或在另一个提供商上运行时按原样加载保存的历史。在 v2.1.246 之前，Claude Code 将工具使用及其结果发送回 API，恢复会话的每一轮都失败，显示 400 错误，如 messages.1.content.0.server_tool_use.name: Input should be 'web_search', 'web_fetch', ...。

要做什么：

• 当您看到占位符行时，无需任何操作。会话继续而不删除的内容。
• 如果恢复会话的每一轮都失败，显示 400 错误，运行 claude update 并再次恢复会话。v2.1.246 之前的版本不删除内容。

role 'system' 必须在 'assistant' 消息之前

API 拒绝了请求，返回 400，因为系统消息位于对话中它不接受的位置：

API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...

Claude Code 将其一些提醒和附件文本作为系统消息发送到对话中。当 API 拒绝一个的位置时，Claude Code 重试请求一次，将该文本作为普通用户消息发送。API 的兄弟位置措辞，如 use the top-level 'system' parameter for the initial system prompt，获得相同的恢复。

当错误确实出现时，被拒绝的系统消息不是 Claude Code 可以删除的。这通常意味着 Claude Code 和 API 之间的代理或 LLM gateway 添加了自己的系统消息或重新排序了对话。

要做什么：

• 运行 /clear 以启动新对话。如果错误也在那里返回，原因在请求路径上，而不在保存的对话中。
• 如果错误在通过 ANTHROPIC_BASE_URL 配置的代理或网关后的每一轮上重复，连接而不使用代理以确认源，并向操作它的人报告错误

在 v2.1.280 之前，Claude Code 不识别此措辞，因此当被拒绝的系统消息是 Claude Code 本身发送的时，错误也出现，对话的每个后来轮次都以相同方式失败。

search\_result 块中的 encrypted\_content 无效

API 拒绝了请求，返回 400，因为对话历史包含它无法解密的托管网络搜索内容。措辞命名它无法读取的字段：

API Error: 400 messages.21.content.0: Invalid `encrypted_content` in `search_result` block
API Error: 400 messages.21.content.3.citations.0: Invalid `encrypted_index` in `text` block
API Error: 400 Failed to decrypt web search result content

来自 API 的托管网络搜索工具的结果携带只有 API 可以读取的加密字段。API 拒绝重放它无法解密的内容的请求，如为不同组织生成的内容。

Claude Code 自己的 WebSearch 工具将搜索结果记录为纯文本，因此这些块通常通过代理或 LLM gateway 到达对话，该网关自己运行了托管网络搜索。

被拒绝的块保留在对话历史中，因此每个后来的轮次和 /compact 都以相同方式失败。

要做什么：

• 运行 /clear 或启动新会话；新对话不携带被拒绝的块
• 如果您在代理或网关后运行 Claude Code，向操作它的人报告错误

使用政策拒绝

API 拒绝了响应，因为对话中的内容触发了使用政策检查。消息包括您可以引用给支持的请求 ID，如果您认为拒绝不正确。

API Error: Opus 4.6 can't help with this. Start a new session to continue.

Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup

消息命名拒绝的模型，或当没有记录模型时命名 Claude。

检查评估完整对话，而不仅仅是您的最新提示，因此在同一会话中发送新消息通常会重新触发相同的拒绝。使用 --continue 或 --resume 退出并重新打开会话后也是如此，因为磁盘上的记录仍然包含触发内容。在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，此消息也涵盖模型的安全措施标记为网络安全主题的请求。请参阅安全措施标记了网络安全主题。

在 v2.1.219 之前，消息读取 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.

要做什么：

• 按 Esc 两次或运行 /rewind 回退到触发拒绝的轮次之前的检查点，然后重新表述或采取不同的方法。请参阅检查点。
• 如果您无法识别哪个轮次导致了它，运行 /clear 在同一项目中启动新对话。您之前的对话保留在磁盘上，并在 /resume 中保持可用。
• 在非交互模式(-p) 中，其中回退不可用，在没有 --continue 的新会话中使用重新表述的提示重试。政策检查因模型而异，因此使用 --model 切换到不同的模型也可能在某些情况下解决拒绝。

安全措施标记了网络安全主题

模型的安全措施将对话中的内容标记为网络安全主题。消息命名标记请求的模型：

API Error: Opus 4.8's safeguards flagged this message. Our intentionally broad safeguards allow us to deliver more capabilities faster, but can sometimes flag legitimate cybersecurity work. Apply to the Cyber Verification Program to reduce these interruptions. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude

消息链接到网络安全验证计划，该计划为合法网络安全工作授予访问权限。在 Opus 5.5 上（需要 v2.1.280 或更高版本），消息以 Opus 5.5's safeguards flagged this session 开头。当标记的类别有可用的后备模型时，Claude Code 切换模型 而不是显示此错误。

在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，网络安全标记会产生使用政策拒绝消息。

保护措施本身是服务器端的，早于 v2.1.203；自那以后的客户端版本仅更改了消息的措辞。 从 v2.1.203 到 v2.1.218，消息读取 <model> has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center: 后跟相同的帮助中心链接，交互式会话附加 If you were not engaging in a cybersecurity topic, please send feedback via /feedback. 在 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: 后跟豁免表单链接。

要做什么：

• 如果您的工作需要此内容，通过网络安全验证计划申请访问权限
• 如果您的请求不是关于网络安全主题，运行 /feedback 报告误报
• 要继续在同一会话中工作，按 Esc 两次或运行 /rewind 回退到触发标记的轮次之前的检查点，然后采取不同的方法。请参阅检查点。

安装错误

这些错误在安装或更新 Claude Code 时出现，来自 安装脚本、claude install 或 claude update。对于安装过程中的 command not found、PATH、权限和 TLS 问题，请参阅 排查安装和登录问题。

安装在完成前被中止

当 claude install 步骤被信号终止时，安装脚本会报告。在 Linux 上，退出代码 137 表示进程收到了 SIGKILL，在低内存主机上通常是内核内存不足 (OOM) 杀手。脚本打印此说明并以代码 137 退出：

Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.
Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

对于任何其他致命信号，以及 macOS 上的退出代码 137，脚本打印 Installation was killed before it could finish (exit code <N>)，其中包含实际的退出代码，并省略内存不足的说明。该消息来自 macOS 和 Linux 使用的安装脚本，该脚本也涵盖 WSL 内的安装；本机 Windows 安装脚本永远不会打印它。在 v2.1.200 之前，脚本仅以 shell 的裸 Killed 行退出。

应该做什么：

• 停止其他进程以释放内存，然后重新运行安装程序
• 添加交换空间或移至更大的实例。有关交换文件命令，请参阅 在低内存 Linux 服务器上安装被中止。

下载更新时连接断开

在 claude install、claude update 或 自动更新程序 获取 Claude Code 二进制文件时，与下载服务器的连接关闭，重试也没有恢复。当连接断开、传输停滞或下载的文件校验和失败时，Claude Code 会重试下载，总共最多尝试三次。已完成的 HTTP 错误（例如 404）不会重试，因为服务器已经响应。在 v2.1.202 之前，单个断开的连接会立即导致下载失败，并显示裸错误 aborted，而不是重试。

The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

括号中的文本命名失败的尝试和底层网络错误。claude update 在 stderr 上以 Error: Failed to install native update 开头的消息。

保持连接但在 10 分钟内未完成的下载失败，显示 Download timed out: exceeded the total deadline。Claude Code 不会重试超时的下载，因为连接速度太慢而无法在截止时间内完成，在立即重试时也不会完成。以下步骤适用于两条消息。

通常的原因是代理或网关在长传输完成前关闭它。Claude Code 二进制文件是一个大型下载，因此永远不会影响正常 API 流量的代理连接限制仍然可能中断它。

应该做什么：

• 再次运行 claude update。在网络状况良好的情况下，下载通常在下一次运行时成功。对于超时消息，从更快或限制较少的网络再次运行它。
• 如果您的网络需要代理，请在运行安装程序或 claude update 之前设置 HTTPS_PROXY。请参阅 检查网络连接。
• 如果公司代理持续关闭传输，请要求您的网络团队允许从 downloads.claude.ai 进行完整下载。请参阅 网络访问要求。
• 从您的 shell 运行 claude doctor 以进行安装诊断

命令行错误

这些错误来自 claude 命令行及其子命令、您在提示符处提交的命令名称，以及诸如 /security-review 之类的命令，这些命令通过运行 shell 命令来收集上下文，然后再运行其提示。它们也来自 /tui，它会重新启动 CLI。

\--bg 和 --print 之间的冲突

此消息需要 Claude Code v2.1.198 或更高版本。您在同一个 claude 调用中将 --bg 与 -p 或 --print 结合使用。--bg 启动一个后台会话，您稍后可以使用 claude agents 附加到该会话，而 --print 以非交互方式运行，永远不会启动 claude agents 附加到的交互会话。在 v2.1.198 之前，此组合会以静默方式创建一个永远无法附加的后台作业。

--bg 和 --print 冲突：--print 永远不会启动 `claude agents` 附加到的交互会话，因此该作业将无法附加。提示是位置参数 — 删除 --print：`claude --bg '<task>'`。

要做什么：

• 删除 -p 或 --print。--bg 将提示作为其位置参数，因此 claude --bg "<task>" 是完整命令。请参阅从您的 shell 分派新代理。
• 要以非交互方式运行提示并打印结果而不是创建后台会话，请删除 --bg 并运行 claude -p "<task>"

无效的 --agents 配置

您传递给 --agents 的值无效，因此 claude 以代码 1 退出，而不是启动会话。当您传递 --safe-mode、--resume 或 --continue，或设置 CLAUDE_CODE_SAFE_MODE 时，Claude Code 不会检查该值并启动会话。在 v2.1.242 之前，Claude Code 无论如何都会启动会话，并遗漏它无法加载的定义。

Error: Invalid --agents configuration:
<what failed>

第一行之后的内容取决于值如何失败。Claude Code 按顺序运行这些检查，并在第一个失败的检查处停止。如果您的值有两种问题，您只有在修复第一个问题后才会看到第二个问题：

1. 当值不能解析为 JSON 时，Claude Code 打印一行 invalid JSON: 行，其中包含 JSON 解析器自己的消息
2. 当它解析但代理定义与 CLI 定义的子代理 的架构不匹配时，Claude Code 为每个问题打印一行
3. 当代理名称以 - 开头时，Claude Code 打印 <name>: agent names must not start with '-'

当有超过 20 个问题行时，Claude Code 打印前 20 个，并用 …and N more 替换其余的。

要做什么：

• 修复消息列出的每个问题，然后再次运行命令。请参阅 CLI 定义的子代理采用的字段。

无法从 --restricted 会话创建云会话

当您使用 --restricted 启动会话时，Claude Code 拒绝从它创建云会话，因为新会话将在受限进程之外运行，不会强制执行受限模式。Claude Code 在客户端拒绝，在联系服务器之前，因此不会创建云会话：

Cloud sessions cannot be created from a --restricted session: they would not enforce it.

要做什么：

• 在受限会话中本地运行任务
• 如果您控制会话的启动方式，请启动一个没有 --restricted 的新 claude 会话，并从那里创建云会话

在 v2.1.248 之前，Claude Code 没有 --restricted 标志；较早的版本会以未知选项错误拒绝该标志本身。

云会话被您的组织的策略禁用

您的组织的 allow_remote_sessions 策略已关闭，因此云会话和使用它们的命令不可用：

Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.

当您从终端创建云会话时，消息会出现，当您提交需要云会话的命令时，例如 /teleport、/remote-env 或 /web-setup。在 v2.1.268 之前，提交其中一个命令会返回 Unknown command。

这是一个服务器端组织策略，因此无法从本地设置、环境变量或 CLI 标志覆盖。

如果 Claude Code 尚未加载您的组织的策略或无法获取它，这些命令会回答 Couldn't verify your organization's policy for cloud sessions. Check your network connection, then restart Claude Code and try again.。

要做什么：

• 要求您的组织中的所有者在 claude.ai/admin-settings/claude-code 的 Claude Code 管理员设置中启用云会话
• 如果消息说它无法验证策略，请检查您的网络连接，然后重新启动 Claude Code 并重试

\--json-schema 值不是有效的 JSON Schema

您传递给 --json-schema 的架构在非交互模式中未能通过 JSON Schema 编译，因此 claude 以代码 1 退出，而不是运行提示。在 v2.1.205 之前，无效的架构会产生无结构的输出，没有错误，任何使用 format 关键字的架构都被视为无效。

Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values

第二个冒号后的文本是验证器的诊断，并命名失败的关键字或位置。使用 format 关键字的架构，例如 "format": "email"，是有效的：Claude Code 接受 format 作为注释，不强制执行它。

Claude Code 在架构编译之前运行两个检查：它拒绝不可解析的 JSON 值，错误为 Error: --json-schema is not valid JSON，以及有效的 JSON 但不是对象的值，错误为 Error: --json-schema must be a JSON object。

要做什么：

• 修复诊断命名的架构部分，然后重新运行命令
• 如果诊断是 schema too large，请减少架构的嵌套和 $ref 重用
• 请参阅获取结构化输出以获取工作架构和命令

设置文件超过 2MiB 限制

您传递给 --settings 的文件大于 2 MiB，因此 claude 在启动时以代码 1 退出，而不是加载它。设置文件是一个小的 JSON 文档，所以这么大的文件通常意味着路径指向错误的文件。在 v2.1.214 之前，Claude Code 读取文件时没有大小检查，多 GB 的文件或诸如 /dev/zero 之类的设备文件会无限增长内存。

Error: Settings file exceeds the 2MiB limit: /path/to/settings.json

Claude Code 以相同的方式拒绝不是常规文件的 --settings 路径：设备、FIFO 或套接字报告 Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))，后跟路径，目录报告 EISDIR 原因。

要做什么：

• 将 --settings 指向 2 MiB 以下的常规 JSON 设置文件。请参阅设置以了解格式。

当前目录不再存在

您从一个在您的 shell 进入后被删除或移动的目录启动了 claude，例如 worktree 或另一个 shell 删除的临时目录。Claude Code 无法读取其工作目录，因此它在启动会话之前以代码 1 退出，在交互和非交互模式中都是如此。在 v2.1.239 之前，Claude Code 会因缩小的捆绑源和原始 ENOENT ... uv_cwd 堆栈在 stderr 上崩溃，而不是显示此消息。

The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.
error: The current working directory was deleted, so that command didn't work. Please cd into a different directory and try again.

原因和修复对两种形式都是相同的。

当 Claude Code 因其他原因（例如权限更改）无法读取工作目录时，消息会命名错误代码：Can't read the current directory (EACCES). Start Claude Code from a different directory.

在 macOS 上，~/Desktop、~/Documents、~/Downloads 或 iCloud Drive 中目录的 EPERM 通常意味着 macOS 阻止您的终端应用访问该文件夹。读取该文件夹的其他命令也会以相同的方式失败：即使使用 sudo，ls 也会报告 Operation not permitted。

要做什么：

• 更改为存在的目录，例如您的主目录或项目目录，然后再次运行 claude
• 如果目录在同一路径处被重新创建，您的 shell 仍然持有已删除的目录。运行 cd "$PWD" 或离开并重新进入目录，然后再次运行 claude
• 对于 macOS 上的 EPERM，使用 Cmd+Q 退出您的终端应用，重新打开它，返回该文件夹，然后运行 claude。如果该文件夹中的 ls 仍然失败，请打开系统设置 > 隐私和安全 > 文件和文件夹，为您的终端应用打开该文件夹，然后重新打开终端

临时目录被拒绝或无法创建

在 macOS 和 Linux 上，Claude Code 在启动时创建一个私有临时目录 claude-<uid>，位于系统临时目录或 CLAUDE_CODE_TMPDIR 覆盖下。当无法创建目录或该路径处的现有条目未通过安全检查时，Claude Code 将失败打印到 stderr 并以代码 1 退出，而不是启动会话：

ENOSPC: no space left on device, mkdir '/tmp/claude-501'

Temp directory /tmp/claude-501 is not a directory (may be an attacker-planted symlink). Refusing to use it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.

Temp directory /tmp/claude-501 is owned by uid 502, expected 501. Refusing to use it — another user may have pre-created it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.

Temp directory /tmp/claude-501 is not readable (its mode may have been altered, or a path component denies search). Refusing to use it — restore its permissions (chmod 0700) or remove it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.

要做什么：

• 对于 ENOSPC，释放保存临时目录的卷上的磁盘空间
• 对于 Refusing to use it 形式，删除命名的条目本身，而不是链接指向的内容，然后再次启动 Claude Code；对于 owned by uid 形式，只有管理员或该用户可以删除它
• 对于 is not readable，在命名目录上运行 chmod 0700，或删除它并重新启动
• 在任何这些情况下，将 CLAUDE_CODE_TMPDIR 设置为您控制的目录并启动 Claude Code，保持拒绝的路径不变

目录无法解析为真实位置

您为工作目录的子目录运行了 /add-dir，Claude Code 无法将目录解析为其真实位置。

您已经有对工作目录的子目录的文件访问权限，因此 /add-dir 仅加载其 skills、命令和代理。在加载它们之前，Claude Code 检查目录的真实位置（解析任何符号链接）是否在工作目录内。当 Claude Code 无法解析该位置时，它不加载任何内容并显示此消息：

packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.

要做什么：

• 检查路径是否命名工作目录内的真实目录，然后再次运行 /add-dir
• 消息不会改变您的文件访问；它仅报告目录的 .claude/ 内容未被加载

在 v2.1.261 之前，当工作目录在 /net/<host> 自动挂载上时，此消息也会为每个 /add-dir <subdirectory> 出现，Claude Code 根据设计拒绝解析路径；目录很好，重试无法帮助。

启动远程控制时工作区不受信任

您在未信任的目录中使用 claude remote-control 或其 claude rc 别名启动了远程控制服务器模式。该命令本身不显示工作区信任对话框，因此它以代码 1 退出并命名修复：

Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.

在您的主目录中，消息是不同的，因为工作区信任对话框永远不会保存主目录的信任，因此在那里接受它无法满足此检查。在 v2.1.214 之前，主目录显示上述消息，其建议无法在那里成功。

Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).

要做什么：

• 在目录中运行 claude，接受工作区信任对话框，然后再次运行 claude remote-control
• 在您的主目录中，更改为项目目录并在那里启动远程控制

未被远程控制启动的会话继承

您使用全局 claude 标志在 remote-control 动词之前启动了远程控制，该标志会限制或配置远程控制启动的会话，例如 --settings、--setting-sources、--permission-mode、--disallowed-tools 或 --mcp-config。放在动词之前的标志永远不会到达这些会话。Claude Code 拒绝启动，而是命名标志：

Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).

Claude Code 不拒绝无害的全局标志，例如 --verbose、--model 或包装器注入的 --session-id 或 --plugin-dir：它忽略它们，远程控制启动。

Claude Code 也拒绝启动一个它尚未识别为无害的全局标志，因此在较新版本中添加的标志可能会出现在此消息中，直到稍后的版本将其标记为无害。

要做什么：

• 从动词之前删除标志，并在其后传递远程控制自己的选项；claude remote-control --help 列出它们
• 当拒绝的标志是 --permission-mode 时，运行 claude remote-control --permission-mode <mode> 为远程控制启动的会话设置权限模式

在 v2.1.248 之前，当全局标志首先出现时，claude remote-control 不接受自己的标志，命令失败并出现 unknown option 错误。

claude import 在此构建中尚不可用

您运行了 claude import，Claude Code 发现导入流已关闭，因此命令以代码 1 退出，而不是启动导入。在 v2.1.222 之前，导入流关闭的构建将 import 视为提示并启动交互会话，而不是打印此消息。

`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.

Claude Code 通过从 Anthropic 获取的功能标志打开 claude import，并在磁盘上缓存。此消息意味着缓存的值已关闭。原因通常是以下之一：

• 您自安装以来尚未启动会话，因此 Claude Code 尚未获取标志。第一个 claude import 即使在功能对您可用时也可能打印此消息。
• 您通过 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform，或通过Claude 应用网关使用 Claude Code。Claude Code 在这些会话中不获取功能标志，因此 claude import 保持不可用。
• 您设置了 DISABLE_TELEMETRY、DO_NOT_TRACK、DISABLE_GROWTHBOOK 或 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC，这会关闭功能标志获取，因此 claude import 保持不可用。

要做什么：

• 在全新安装上，启动 claude，等待会话加载，退出，然后再次运行 claude import
• 在功能标志获取保持关闭的地方，自己设置配置：使用 claude mcp add 添加 MCP 服务器，并创建您想要继承的 CLAUDE.md 文件、skills 和命令以及子代理。消息也命名 ~/.claude/settings.json。在 claude import 继承的配置中，该文件仅保存权限模式；Claude Code 不从它读取 MCP 服务器。

无法读取 Claude Code 配置

您运行了 claude import，而 Claude Code 无法解析 ~/.claude.json，这是它存储您的登录和每个项目状态的文件。子命令读取该文件以检查可用性，但不显示交互会话显示的恢复对话框，因此它以代码 1 退出。在 v2.1.222 之前，带有不可读配置文件的 claude import 启动了交互会话，其恢复对话框处理了该文件。

Could not read Claude Code config — run `claude` with no arguments to recover it.

要做什么：

• 运行 claude 不带参数。Claude Code 检测无效文件并提供重置它。然后再次运行 claude import。
• 要保留您所做的手动编辑，请在编辑器中修复 ~/.claude.json 中的 JSON 语法，然后重新运行 claude import

无法从 Claude Desktop 导入服务器

Claude Code 无法添加您在 claude mcp add-from-claude-desktop 中选择的其中一个服务器。该命令仍然导入其他选定的服务器，并为每个无法添加的服务器打印一行。在 v2.1.205 之前，第一个失败的服务器会停止导入，所有选定的服务器都不会被添加。

Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.

服务器名称后的文本是原因。最常见的是名称检查：Claude Desktop 允许服务器名称中的字符，例如空格和句号，而 claude mcp 限制为字母、数字、连字符和下划线。其他原因包括未通过验证的服务器配置和被您的组织的 MCP 策略阻止的服务器。

要做什么：

• 在 claude_desktop_config.json 中重命名服务器以仅使用字母、数字、连字符和下划线，然后再次运行 claude mcp add-from-claude-desktop
• 使用有效名称直接使用 claude mcp add 或 claude mcp add-json 添加该服务器。请参阅从 Claude Desktop 导入 MCP 服务器。

无法将 MCP 服务器添加到托管范围

您使用 --scope managed 运行了 claude mcp add 或 claude mcp add-json。该范围保存您的组织通过 managedMcpServers 托管设置提供的服务器。Claude Code 仅从托管设置读取它们，因此命令无法向该范围写入服务器。

Cannot add MCP server to scope: managed

要做什么：

• 将服务器添加到您可以写入的范围：local、user 或 project。不带 --scope，命令使用 local。请参阅 MCP 安装范围
• 要为您的组织中的每个用户提供服务器，请将其添加到您部署的托管设置中的 managedMcpServers

无法读取 .mcp.json

读取项目的 .mcp.json 的命令，例如 claude mcp add 或 claude mcp add-json 带 --scope project，或 claude mcp remove，发现您当前目录中的文件不是常规文件或大于 2 MiB，因此它以此错误退出，而不是读取文件。

Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.

在 v2.1.257 之前，.mcp.json 处的 FIFO 会使命令无限期等待，没有输出，到设备文件（如 /dev/zero）的符号链接会增长内存，直到进程被杀死。

要做什么：

• 检查您当前目录中 .mcp.json 处的内容。将其替换为项目范围格式中的普通 JSON 文件，或删除它，然后再次运行命令。

服务器是 Anthropic 托管的，不支持本地 OAuth

您为 URL 指向通过第三方身份提供商进行身份验证的 Anthropic 托管连接器主机的 MCP 服务器启动了登录。这些主机包括 microsoft365.mcp.claude.com、gmail.mcp.claude.com 和 gcal.mcp.claude.com。Claude Code 拒绝从 /mcp 面板和 claude mcp login 为这些主机启动其本地 OAuth 流，因为它们的登录仅通过 claude.ai 工作。

"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.

Claude Code 按 URL 匹配这些主机，因此当您使用 claude mcp add 或在 .mcp.json 中添加的服务器指向其中之一时，消息会出现。

要做什么：

• 使用 claude mcp remove <name> 删除您的条目，以便它无法隐藏同一 URL 处的 claude.ai 连接器
• 删除后，在 claude.ai/customize/connectors 连接服务，同时登录到您在 Claude Code 中使用的帐户。连接后，如果您的活跃身份验证方法是 claude.ai 订阅登录，连接器会自动出现在 Claude Code 中

服务器拒绝了由配置的 headersHelper 生成的 Authorization 标头

其 headersHelper 提供 Authorization 标头的 MCP 服务器以 HTTP 401 或 403 回答连接，因此 Claude Code 将连接报告为失败。因为助手提供 Authorization 标头，Claude Code 不会回退到 OAuth 对于服务器：

Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.

Claude Code 在每次连接尝试时重新运行助手，因此在暂时拒绝后重试（例如令牌轮换竞争）可以使用新凭证成功。

要做什么：

• 按照 Claude Code 运行它的方式自己运行 headersHelper 命令：从 Claude Code 运行它的目录，使用 Claude Code 为其设置的环境变量，以及不使用 Claude Code 为来自项目 .mcp.json、插件或项目代理文件的服务器删除的凭证变量。检查它打印的 Authorization 值是否被服务器的端点接受
• 修复助手或其凭证源后，在 /mcp 中选择服务器并选择重新连接

在 v2.1.248 之前，Claude Code 为其助手提供 Authorization 标头的服务器运行 OAuth 发现。该发现可能失败，错误为 Incompatible auth server: does not support dynamic client registration，而不是报告被拒绝的凭证。

找不到 MCP 权限提示工具

您传递给 --permission-prompt-tool 的工具在运行首次需要权限决定时不在连接的 MCP 工具中，要么因为其服务器从未连接，要么因为没有连接的服务器公开该名称的工具。Claude Code 仍然发送您的提示：非交互运行在第一个需要批准的工具调用时以此错误和代码 1 退出，因此即使请求已发出，它也不会产生答案。在第一个提示之前，Claude Code 等待最多由 MCP_TIMEOUT 设置的每个服务器连接超时 30 秒，以便该服务器连接。在 v2.1.206 之前，启动不等待服务器完成连接，因此启动缓慢但健康的服务器也会产生此错误。

Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none

等待结束时连接的 MCP 工具之后的列表命名了 MCP 工具。

要做什么：

• 检查服务器启动并保持连接：在同一目录中运行 claude mcp list 并确认服务器列为已连接
• 确认工具名称与服务器公开的 mcp__<server>__<tool> 名称匹配
• 如果服务器需要超过 30 秒才能启动，请提高 MCP_TIMEOUT

OAuth 回调端口已在使用中

当您使用 OAuth 登录远程 MCP 服务器时，Claude Code 启动本地侦听器以接收登录回调。如果该侦听器需要的端口被另一个进程持有，登录会失败并显示此消息。这主要发生在通过 MCP_OAUTH_CALLBACK_PORT 变量或 --callback-port 设置的固定回调端口上，因为没有一个 Claude Code 会选择可用端口。

OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.

在 Windows 上，建议的命令是 netstat -ano | findstr :<port>。

要做什么：

• 运行消息中的命令以找到持有端口的进程，并停止它或等待它完成
• 如果另一个程序永久需要该端口，请向服务器注册不同的重定向 URI，并使用 MCP_OAUTH_CALLBACK_PORT 或 --callback-port 设置其端口，以及您使用的任何一个
• 然后再次启动登录，例如通过在 /mcp 中选择服务器

没有可用的 OAuth 重定向端口

当您使用OAuth 登录远程 MCP 服务器时，Claude Code 启动本地侦听器以接收登录回调。当 Claude Code 无法为其绑定本地端口时，登录会失败并显示此消息。机器上的某些内容阻止它在 127.0.0.1 上侦听，例如安全软件或拒绝本地侦听器的沙箱策略。

No available ports for OAuth redirect

在 v2.1.268 之前，Claude Code 没有回退到操作系统分配的端口，因此消息也出现在只有其自选端口无法绑定时。这可能发生在 Hyper-V 保留覆盖 Claude Code 选择的端口的端口范围的 Windows 主机上。

要做什么：

• 检查安全软件或沙箱策略是否阻止进程在 127.0.0.1 上侦听，并允许 Claude Code 绑定本地端口
• 然后再次启动登录，例如通过在 /mcp 中选择服务器

/security-review 在没有 origin/HEAD 的情况下失败

/security-review 通过将您的分支与 origin/HEAD 进行比较来构建其审查上下文，这是记录您的 origin 远程上哪个分支是默认分支的本地 ref。当该 ref 不存在时，收集差异的 git 命令会失败，审查在启动前停止。

Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr]
fatal: ambiguous argument 'origin/HEAD...': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'

消息可能引用 git log 或不同的 git diff。Git 仅在远程通告默认分支且您的获取 refspec 覆盖它时创建 origin/HEAD，这是完整 git clone 的远程提交所做的。该 ref 在这些设置中缺失：

• 单分支或 CI 检出，它获取太窄的 refspec
• 远程的服务器端 HEAD 指向没有人推送的分支
• 没有 origin 远程的存储库，或您从未获取的存储库

Claude Code 为任何注入动态上下文的 skill 显示相同的错误，失败的注入命令会中止该 skill 的调用。两个同级字符串在命令运行之前就会触发：

• Shell command permission check failed for pattern "..."：命令的权限检查不允许它。注入命令的权限检查涵盖在每个权限模式中哪些结果中止以及如何使用 allowed-tools 预批准命令
• Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found：skill 的 frontmatter 在没有它的机器上要求 bash。安装 Git for Windows 或将 frontmatter 更改为 shell: powershell。请参阅注入命令如何运行

要做什么：

• 通过命名您的远程的默认分支创建 ref：git remote set-head origin <default-branch>。只要本地跟踪 ref origin/<default-branch> 存在，这就有效。如果不存在，如在单分支克隆中，首先获取分支：运行 git remote set-branches --add origin <branch>，然后 git fetch origin，然后重新运行 set-head 命令。重新运行 /security-review。
• 如果您不想命名分支，运行 git fetch origin 然后 git remote set-head origin --auto，它询问远程哪个分支是其默认分支。当远程不通告默认分支时它失败，错误为 error: Cannot determine remote HEAD，因为它是空的或其 HEAD 指向没有人推送的分支；改为显式命名分支。当您的克隆不获取该分支时它失败，错误为 error: Not a valid ref；首先按上述方式扩大 refspec。
• 如果存储库没有远程，使用 git remote add origin <url> 添加一个并在创建 ref 之前获取。如果远程是空的，首先使用 git push -u origin HEAD 推送您的分支，并在 set-head 命令中命名该分支；origin/HEAD 然后指向您刚推送的分支，因此 /security-review 看到空差异，直到分支与它分歧。

使用 --print 时必须提供输入

裸 claude 需要 stdout 是终端才能启动交互 UI。当 stdout 被重定向或控制台不是真实终端时，例如 PowerShell ISE 和某些 IDE 输出窗格，claude 改为以非交互方式运行。这与 claude -p 相同，它需要提示，因此消息命名 --print，即使您没有传递标志。在任何地方传递 -p/--print 不带提示且 stdin 上没有任何内容会产生相同的错误。

Error: Input must be provided either through stdin or as a prompt argument when using --print

要做什么：

• 对于交互使用，在真实终端中运行 claude：Windows Terminal 或 PowerShell 控制台而不是 ISE，以及您的 IDE 的集成终端而不是输出窗格
• 对于一次性使用，传递提示：claude -p "your question"，或使用 echo "your question" | claude -p 管道它

输入仅包含空格

在非交互模式中，Claude Code 拒绝完全由空格、制表符或换行符组成的提示，而不是发送它，因为 API 拒绝没有可见文本的消息。您看到的消息取决于空白提示来自何处：

• claude -p 的提示参数或管道 stdin：claude 以 Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print 退出
• 提交给运行的 --input-format stream-json 或Agent SDK 会话的消息：Claude Code 在没有调用模型的情况下结束轮次，会话保持可用。拒绝作为信息消息和轮次的结果文本到达：Blank prompt — the message was only whitespace, so nothing was sent to the model.

在 v2.1.229 之前，Claude Code 将仅空格的消息发送到 API，API 以 400 错误拒绝请求。

要做什么：

• 在提示中包含可见文本。如果脚本从变量或文件构建提示，请在调用 Claude Code 之前检查源是否不为空。

stream-json 输入在没有换行符的情况下超过 256M 个字符

您的程序在 stdin 上发送了超过 268,435,456 个字符，没有换行符到 claude -p --input-format stream-json 运行，因此 Claude Code 将此错误打印到 stderr 并以代码 1 退出，而不是缓冲更多输入。消息将该预算表示为 256M。在 v2.1.257 之前，Claude Code 无限制地缓冲此类输入，增长内存直到进程崩溃或被杀死。

Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.

这么长的输入没有换行符通常意味着生产者根本不是 stream-json 生产者，例如二进制文件或意外管道的纯日志输出。超过预算的单个消息会失败相同的检查。

要做什么：

• 检查什么被管道到 stdin。使用 --input-format stream-json，每条消息必须是一个换行符终止的 JSON 行
• 要改为发送纯文本，请删除 --input-format stream-json；claude -p 默认从 stdin 读取纯文本提示

未知命令

在交互式终端会话中，您提交了一个 / 名称，它与此会话中的任何命令都不匹配，因此 Claude Code 报告该名称而不是运行任何内容：

Unknown command: /hepl. Did you mean /help?

Claude Code 建议此会话中菜单列出的最接近的命令名称或别名。当没有接近的时候，消息在名称后结束。原因通常是以下之一：

• 打字错误，例如 /hepl 代替 /help。命令菜单如何匹配您键入的内容涵盖在提交前选择接近匹配
• 存在但在此会话中不可用的命令，因为不满足要求，例如您的平台、计划或身份验证方法。/web-setup 和 /schedule 的故障排除条目演示了两个常见情况。某些命令在您的组织的策略禁用它们时用自己的消息回答，例如Cloud sessions are disabled by your organization's policy
• 来自此会话中未安装或未连接的插件或 MCP 服务器的命令

Claude Code 仅在交互式终端会话中以这种方式回答不匹配的 / 名称。在所有其他会话中，它将提示作为普通消息发送给 Claude，并注意命令未运行以及 Claude 可以在会话中运行的命令列表。这些会话包括：

• -p 运行
• Agent SDK 应用程序
• Desktop 应用的代码选项卡
• VS Code 扩展的聊天面板
• 云会话和例程

对于无法在这些会话之一中运行的内置命令，Claude Code 仍然回答该命令不可用，而不是将其发送给 Claude。在 v2.1.274 之前，只有云会话和例程将不匹配的名称发送给 Claude。在 v2.1.273 之前，他们也回答 Unknown command。

Claude Code 不将每个以 / 开头的提示视为命令。当 / 后的第一个单词以标点符号开头时，它将提示作为普通消息发送给 Claude，例如打开 Lean 文档注释的 /--，或是路径，例如 /var/log/syslog。

在 v2.1.236 之前，如果您在命令菜单列出您键入的名称的接近匹配时按 Enter，Claude Code 会运行该匹配，因此 /hepl 之类的打字错误会运行 /help 而不是产生此消息。

要做什么：

• 运行建议的名称，或键入 / 后跟名称的一部分以查看此会话中可用的内容
• 如果 Claude Code 将记录的命令报告为未知，请检查命令参考中其行以了解它命名的要求

Diff 对于 ultrareview 来说太大

您的分支与基础分支之间的差异，包括未提交和暂存的更改，超过了 ultrareview 的大小限制，因此 /code-review ultra 和 claude ultrareview 子命令在云会话启动前拒绝审查。被拒绝的审查不使用免费运行，也不计费使用信用。消息命名生效的限制、您的差异大小以及贡献最多更改行的文件。在 v2.1.216 之前，消息仅显示原始差异统计。

Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.

审查拉取请求应用相同的限制；该形式的消息以 PR #<N> is too large for ultrareview 开头，并命名 PR 的文件和行数。

要做什么：

• 传递更接近您的工作的基础分支，例如 /code-review ultra develop，以便审查仅涵盖与该分支的差异
• 将更改分成较小的分支并审查每一个。消息命名的文件贡献最多更改行，因此首先将这些移到它们自己的分支。

无法找到与基础分支的合并基础

/code-review ultra 和 claude ultrareview 子命令审查您的分支与基础分支之间的差异，这需要两者共享的提交。当 git merge-base 找不到时，Claude Code 在云会话启动前拒绝审查。在 Claude Code 可以验证完整的克隆上，至少有一个分支，它改为回退到审查每个跟踪文件而不是拒绝。您在基础分支根本找不到、Claude Code 无法验证您的克隆完整或在罕见的存储库中看到此拒绝，其中整个树差异不可能，例如 SHA-256 对象格式。

Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.

第一句后的提示取决于 Claude Code 观察到的内容：

• 您没有传递基础分支：Claude Code 与存储库的默认分支进行了比较，并建议显式传递您的基础，如上例所示
• 您传递了已在克隆中的基础分支：提示读取 Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)
• 您传递了不在克隆中的基础分支：Claude Code 在比较前从 origin 获取了它。提示读取 <branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)；当 Claude Code 无法判断您的克隆是否浅时，它改为建议 git fetch --unshallow origin。在 v2.1.221 之前，提示为每个获取的基础分支建议 git fetch --unshallow origin，在完整克隆上该命令失败，错误为 fatal: --unshallow on a complete repository does not make sense。

要做什么：

• 如果另一个分支是您的真实基础，显式传递它：/code-review ultra <branch>
• 如果您的克隆可能没有完整历史，运行 git fetch --unshallow origin 并重新运行审查

您的检出没有分支

检出可以有提交但没有分支：如果您运行 git init 后跟 git fetch <url> 和 git checkout FETCH_HEAD，您会得到一个分离的 HEAD，没有 refs。Claude Code 将您的存储库打包为 git 包以上传以进行 ultrareview，它无法打包没有分支或其他 refs 的存储库，因此 /code-review ultra 和 claude ultrareview 子命令在云会话启动前拒绝审查。

Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.

在 v2.1.221 之前，Claude Code 尝试审查此检出中的每个跟踪文件，上传失败。

要做什么：

• 使用 git checkout -b <name> 在您当前的提交处创建分支，然后重新运行审查

没有 GitHub 帐户连接到您的 Claude 帐户

您运行了 /code-review ultra <PR#> 或 claude ultrareview <PR#>，在创建云会话之前，Claude Code 询问服务器连接到您的 Claude 帐户的 GitHub 帐户是否可以到达 PR 的存储库。没有帐户连接，或连接已过期，因此云克隆会失败，Claude Code 拒绝启动。Claude Code 不为被拒绝的启动花费免费运行或计费使用信用。

Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).

当 /web-setup 在您的会话中不可用时，消息仅命名 claude.ai 链接。

要做什么：

• 运行 /web-setup 将您的 GitHub CLI 登录连接到您的 Claude 帐户，或在 claude.ai/connect-github 连接帐户
• 连接后一分钟重新运行审查

在 v2.1.248 之前，Claude Code 在启动前不检查这个。

您连接的 GitHub 帐户看不到存储库

您运行了 /code-review ultra <PR#> 或 claude ultrareview <PR#>，连接到您的 Claude 帐户的 GitHub 帐户无法读取 PR 的存储库，因此云克隆会失败，Claude Code 拒绝启动。Claude Code 不为被拒绝的启动花费免费运行或计费使用信用。

Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.

当 /web-setup 在您的会话中不可用时，消息仅命名应用安装。

要做什么：

• 如果您的本地 gh CLI 可以读取存储库，运行 /web-setup 将该登录连接到您的 Claude 帐户
• 更改后重新运行审查

在 v2.1.248 之前，Claude Code 在启动前不检查这个。

GitHub 应用预检失败暂时

您从本地存储库启动了云会话，两个步骤一起失败。Claude Code 无法构建或上传您的存储库包。在上传之前，它检查了云服务是否可以从 GitHub 克隆存储库，而不是明确的答案，该检查以重试可能清除的错误结束，例如网络错误、超时或临时服务器错误。完整消息以停止包的内容开头，例如 Could not upload repo bundle (<error>)，并以预检句子结尾：

Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead

要做什么：

• 片刻后重新运行命令。当 GitHub 检查通过时，Claude Code 可以从 GitHub 克隆启动会话，因此失败的上传不再阻止启动
• 如果重试继续失败，消息的开头命名了停止上传的内容。当该原因是您可以修复的内容时，修复它以便会话可以从您的本地存储库启动。

在 v2.1.251 之前，Claude Code 以 Please set up GitHub on https://claude.ai/code 结束消息，即使 GitHub 检查仅暂时失败，设置建议也无法清除暂时失败。

GitHub 未连接到您的 Claude 帐户

您从本地存储库启动了云会话，例如使用 /autofix-pr。没有 GitHub 帐户连接到您的 Claude 帐户，或连接已过期，因此 Claude Code 拒绝启动：

GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github

当您使用 /schedule 创建例程时，相同的消息作为命名存储库的设置注释出现；注释不会阻止创建例程。

要做什么：

• 运行 /web-setup 将您的 GitHub CLI 登录连接到您的 Claude 帐户，或在 claude.ai/connect-github 连接帐户。请参阅 GitHub 身份验证选项以了解两者的区别。
• 连接后一分钟重新运行命令

在 v2.1.268 之前，Claude Code 将此报告为 Claude GitHub 应用检查的临时失败，并建议重试或安装应用；两者都不连接 GitHub 帐户。

需要单点登录授权

您运行了 /install-github-app 并选择了其组织强制执行 SAML 单点登录的存储库。在设置之前，Claude Code 使用 GitHub CLI 检查您对存储库的访问权限，GitHub 拒绝了该检查，因为您的 gh 令牌尚未为组织授权。向导显示警告和授权步骤：

Single sign-on authorization needed
<owner>/<repo> belongs to an organization that enforces SAML single sign-on, and your GitHub CLI token isn't authorized for it yet.

要做什么：

• 通过运行 gh auth refresh -h github.com -s repo,workflow 使用 repo 和 workflow 范围重新授权您的 GitHub CLI 登录，并在 GitHub 提示单点登录时授权组织
• 如果您在 GH_TOKEN 中使用个人访问令牌进行身份验证，请打开 github.com/settings/tokens，在令牌上选择配置 SSO，并授权组织
• 再次运行 /install-github-app

在 v2.1.273 之前，Claude Code 为此条件显示 Admin permissions required 警告。

无法恢复对话

Claude Code 无法读取或处理您从 claude --resume 选择器选择的会话的保存成绩单，因此它结束进程而不是在部分加载状态下继续。消息包括重试的命令：

Failed to resume the conversation.
Run claude --resume <session-id> to retry, or claude to start a new session.

Claude Code 在显示消息后以代码 1 退出。运行会话内的 /resume 选择器报告对话中的 Failed to resume conversation，您当前的会话保持运行。在 v2.1.216 之前，来自 claude --resume 选择器的失败恢复在 Resuming conversation… 微调器上无限期停留，而不是显示此消息。

要做什么：

• 运行 claude --resume <session-id>，其中 session-id 来自消息以重试
• 如果每次重试都以相同的方式失败，运行 claude update 并再次恢复。v2.1.275 之前的版本在保存的成绩单包含它们无法读取的条目时恢复失败。
• 如果重试再次失败，运行 claude 启动新会话

找不到具有会话 ID 的对话

您将会话 ID 传递给 claude --resume <session-id>，没有保存的成绩单与之匹配：

No conversation found with session ID: <session-id>

Claude Code 在显示消息后以代码 1 退出。Claude Code 首先搜索当前项目，然后搜索此机器上的所有其他项目以查找 ID。在 v2.1.223 之前，查找在当前项目目录及其 git worktrees 处停止，因此从会话最后工作的目录恢复。

常见原因：

• 打字错误的 ID：对于非交互式运行，ID 是 --output-format json 输出的 session_id 字段
• 删除的成绩单：Claude Code 在保留期后删除成绩单，默认 30 天，遵循保留扫描规则
• 不同的机器：Claude Code 在本地存储成绩单，因此在运行会话的机器上恢复会话
• 重复副本：如果您在 ~/.claude/projects 下复制了项目目录，以便两个成绩单携带相同的 ID，Claude Code 报告此消息而不是任意恢复一个副本

要做什么：

• 对于交互式会话，使用 claude --resume 打开会话选择器，按 Ctrl+A 将其扩展到此机器上的每个项目，然后选择会话
• 使用 claude -p 或 Agent SDK 创建的会话不会出现在选择器中，因此重新检查 ID 与您的原始运行打印的 session_id

无法在此会话中切换渲染器

当您切换渲染器时，Claude Code 重新启动其进程。您在 Claude Code 拒绝重新启动的会话中运行了 /tui，因此它不切换并保存任何内容。您看到的消息告诉您原因：

• Cannot switch renderers while work is running in the background：您有在后台运行的工作，重新启动会放弃，例如后台 shell 或子代理。等待工作完成或使用 /tasks 停止它，然后再次运行 /tui fullscreen 或 /tui default
• Cannot switch renderers in this session：会话有 Claude Code 无法传递给重新启动的进程的限制。在 v2.1.234 之前，Claude Code 无论如何都会重新启动，重新启动的会话运行时没有它们

在限制消息中，括号中的部分命名 Claude Code 找到的限制：

Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too.

消息可以在括号中显示的每个原因：

• launch flags: a custom system prompt, a tool allowlist, or restricted settings：您使用 Claude Code 不传递回重新启动的进程的标志启动了会话。这些标志包括 --system-prompt、--system-prompt-file、--append-system-prompt-file、--tools 允许列表、--setting-sources 和 --permission-prompt-tool
• permission rules set for this session only：来自钩子或 SDK 调用者的权限更新添加了带有 session 目标的拒绝或询问规则。会话范围的允许规则不会触发拒绝。重新启动会删除它们，Claude Code 改为再次提示
• ask-before-running rules with no command-line form：来自钩子或 SDK 调用者的权限更新添加了询问规则以及 Claude Code 作为 --allowed-tools 和 --disallowed-tools 传递回的规则。不存在询问规则的标志
• permission rules a command line cannot carry intact 和 added directories a command line cannot carry intact：权限更新在会话中期添加了规则或目录路径。重新启动的进程的命令行无法将其文本作为相同值继承

要做什么：

• 在没有这些限制的会话中，运行 /tui fullscreen 或 /tui default 切换回。Claude Code 在那里保存 tui 设置

无法打开 Claude Desktop

您运行了 /desktop 或其别名 /app，Claude Code 用来打开 Claude Desktop 的系统命令失败。会话保持在终端中。

Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and run /desktop again.

要做什么：

• 自己打开 Claude Desktop，然后再次运行 /desktop
• 要读取该命令的完整错误输出，使用 /debug 打开调试日志，再次运行 /desktop，并检查调试日志

在 v2.1.275 之前，消息是 Failed to open Claude Desktop. Please try opening it manually.，没有说什么失败。

/terminal-setup 保持您的 Zed 快捷键不变

您在 Zed 中运行了 /terminal-setup，Claude Code 无法完成对您的 Zed keymap.json 的更新，因此它保持文件不变。

每条消息命名您的快捷键的路径，并以您自己添加的快捷键块结尾：

Couldn't update your Zed keymap, so it was left unchanged.
To add the binding yourself, add this block to the keymap array in <path to keymap.json>:
{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }

消息的第一行命名原因：

• Couldn't read your Zed keymap, so it was left unchanged.：Claude Code 无法读取文件，例如由于文件权限
• Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.：文件读取良好，但不解析为快捷键块数组，即使允许 // 注释和尾随逗号
• Couldn't back up your Zed keymap; not modifying it.：Claude Code 无法将文件复制到其旁边的 .bak 备份，因此它没有更改任何内容
• Couldn't update your Zed keymap, so it was left unchanged.：合并的结果未验证为有效的快捷键，携带绑定，因此 Claude Code 丢弃它而不是写入。具有重复键的快捷键块可能导致这种情况

要做什么：

• 将消息中的块复制到您的 keymap.json 中消息命名的路径处的顶级数组中
• 对于 isn't a readable list of keybindings，修复语法错误，或使文件的顶级值成为数组，然后再次运行 /terminal-setup

在 v2.1.247 之前，/terminal-setup 无法解析使用 // 注释或尾随逗号的 Zed 快捷键，它用仅自己的绑定替换整个文件，同时报告绑定已安装。要恢复较早版本替换的快捷键，请使用输入多行提示下描述的 .bak 备份文件。

此连接上不提供 Skill 使用报告

您在远程控制上运行了 /skill-doctor，从您的手机或浏览器。Claude Code 不通过远程控制发送 skill 使用报告，而是用此消息回复：

Skill usage reports are not available on this connection.

要做什么：

• 在会话运行的机器上的终端中运行 /skill-doctor，或在那里运行 claude -p "/skill-doctor"

无法通过远程控制选择自定义输出样式

您从移动应用或网络通过远程控制运行了 /output-style，或命令在中继到会话的消息中到达。因为这样的轮次可能不来自帐户所有者，Claude Code 仅在其上列出和选择内置样式，并在命令列出样式或不识别您给出的名称时添加此通知。自定义样式名称获得与不存在的名称相同的回复：

Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here.

要做什么：

• 选择内置样式，例如 /output-style concise
• 要使用自定义样式，在项目的 .claude/settings.local.json 中设置 outputStyle，或在会话自己的终端中运行 /output-style <style>（如果它有的话）

输出样式保存到此会话不加载的本地设置

您尝试在设置源排除 local 的会话中使用 /output-style <style> 或 /config outputStyle=<style> 切换输出样式。示例是 settingSources 遗漏 "local" 的 Agent SDK 会话和使用遗漏 local 的 --setting-sources 值启动的 CLI 会话。两个命令都将样式保存到 .claude/settings.local.json，这样的会话永远不会读回，因此 Claude Code 拒绝而不是写入没有效果的设置：

Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load, so the style can't be changed here.

要做什么：

• 将 local 添加到会话的设置源并再次切换
• 在会话确实加载的设置文件中设置 outputStyle 键，例如项目中的 .claude/settings.json 或 ~/.claude/settings.json。在 TypeScript SDK 中，改为在内联 settings 对象内设置 outputStyle；请参阅激活输出样式

Plugin 错误

这些错误来自 plugin 和 marketplace 配置。对于不产生此页面上任何消息的 plugin 问题，例如无法加载的 marketplace URL 或已安装但不显示的 plugin，请参阅 Plugin 故障排除。

plugin eval 目前处于早期访问阶段

您运行了 claude plugin eval 或 claude plugin eval init，它在执行任何操作之前以退出代码 1 和以下消息之一退出：

`plugin eval` is currently in early access

`plugin eval` is currently unavailable

第一条消息表示您的构建版本早于 v2.1.269，这是该命令正式发布的第一个版本。第二条消息表示 Anthropic 已在服务器端关闭该命令；您的机器上没有任何东西可以将其重新打开。

要做什么：

• 运行 claude --version，然后运行 claude update，并在新会话中再次运行该命令。请参阅 plugin evals 的要求
• 如果您在当前构建上看到第二条消息，请在另一次 claude update 后稍后重试

Marketplace 从不受信任的源注册

marketplace 注册的名称是 为官方 Anthropic marketplaces 保留的，但其注册源不是 anthropics GitHub 存储库。Claude Code 每次加载或刷新 marketplace 时都会重新检查保留的名称，因此 marketplace 和从中安装的 plugin 停止加载。在 v2.1.205 之前，仅在添加 marketplace 时检查名称，因此在其名称被保留之前注册的条目继续加载。

Marketplace "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.

对于源不是 GitHub 存储库或 Git URL（例如本地目录）的 marketplace，中间句子改为 can only be used with GitHub sources from the 'anthropics' organization。claude plugin marketplace add 运行相同的检查，并以 Failed to add marketplace: 后跟相同的保留名称句子拒绝保留的名称。

要做什么：

• 如果 marketplace 已注册，运行 claude plugin marketplace remove <name>，然后从官方 github.com/anthropics 存储库重新添加它
• 如果您发布了在名称被保留之前使用该名称的第三方 marketplace，请重命名它并要求用户从您的源重新添加它
• 请参阅 Marketplace schema 下的保留名称列表

Marketplace 名称是保留名称的另一种拼写

marketplace 的名称本身不是保留名称，但 Claude Code 将其视为另一种拼写。保留的 marketplace 名称 列出了哪些拼写算作保留名称。Claude Code 在您添加 marketplace 时拒绝这样的名称：

Failed to add marketplace: "claude.code.plugins" is another spelling of "claude-code-plugins", a reserved marketplace name.

当 marketplace 已在这样的名称下注册时，其条目停止加载，/plugin、claude plugin install 和 claude plugin update 警告：

known_marketplaces.json has an entry named "claude.code.plugins", another spelling of the reserved marketplace name "claude-code-plugins", so it is ignored. Remove it with: claude plugin marketplace remove claude.code.plugins

当名称需要 shell 引用时，添加时的拒绝读作 This marketplace's name is another spelling of "<reserved>", a reserved marketplace name. It is not exactly the reserved name it appears to be.

要做什么：

• 将 marketplace 重命名为不拼写保留名称的名称并重新添加它
• 对于被忽略的条目警告，运行它给出的 claude plugin marketplace remove 命令，或从 ~/.claude/plugins/known_marketplaces.json 中删除该条目

Marketplace 已从不同的源添加

您通过 /plugin install <plugin> --marketplace <source> 确认添加了 marketplace，而 Claude Code 从该源获取的目录将自身命名为与您已从不同源添加的 marketplace 相同的名称。Claude Code 保留现有的 marketplace 而不是替换它，plugin 未被安装。

Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.

要做什么：

• 如果您已添加的 marketplace 是您想要的，请按名称从中安装：/plugin install <plugin>@<name>
• 要切换到新源，运行 /plugin marketplace remove <name>，然后重试安装

Plugin 命令在 shell 命令中引用 user\_config

一个 plugin hook、monitor 或 MCP headersHelper 命令引用了 ${user_config.KEY} plugin 选项，而替换后的字符串将被传递到 shell。配置的值包含 $(...) 、反引号或 ; 会在那里作为代码运行，因此 Claude Code 拒绝启动该组件而不是替换该值。检查在命令模板上运行，因此即使尚未配置任何值，错误也会出现。在 v2.1.207 之前，该值被替换到 shell 命令中。

措辞取决于哪个表面引用了该选项。shell 形式的 hook 报告：

Hook 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}

monitor 报告：

Monitor "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.

MCP headersHelper 报告：

headersHelper 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).

要做什么：

• 对于 hook，添加 args 数组以便它在 exec 形式 中运行，其中每个 ${user_config.KEY} 成为一个参数，中间没有 shell。或删除引用并读取脚本内的 $CLAUDE_PLUGIN_OPTION_<KEY> 环境变量
• 对于 monitor，删除引用并让 monitor 脚本从配置文件读取该值
• 对于 headersHelper，将 ${user_config.KEY} 移到服务器的 headers 字段中，该字段不会被 shell 解析，或在 helper 脚本内读取该值

Plugin 存档完整性检查失败

plugin 的 marketplace 条目使用带有 sha256 pin 的 archive 源，而下载文件的摘要与 pin 不匹配。Claude Code 拒绝安装，因此 plugin 缓存中没有任何更改。不匹配有三个可能的原因：

• 作者计算 pin 后，URL 处的文件已更改
• 作者在 marketplace 条目中输入了错误的摘要
• URL 提供的文件与作者 pin 的文件不同

Plugin archive integrity check failed for https://artifacts.example.com/claude-plugins/my-plugin.zip: expected sha256 6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1, got ac52220c0914ef8ca6a602e4a7362f88d30fb021110f72a6d15b68c3fe7df2b7. The archive was not installed. Verify the sha256 in the marketplace entry, or that the URL serves the intended file.

要做什么：

• 如果您发布 plugin，使用 shasum -a 256 my-plugin.zip 或 PowerShell 中的 Get-FileHash -Algorithm SHA256 my-plugin.zip 重新计算 URL 提供的确切文件的摘要，并更新 marketplace 条目中的 sha256
• 如果您安装 plugin，运行 /plugin marketplace update <name> 以刷新目录以防条目已更正，然后重试安装
• 如果刷新后摘要仍然不一致，请在安装前询问 marketplace 所有者他们 pin 了哪个文件

路径逃逸 plugin 目录

plugin 组件路径在 plugin 的 plugin.json 或其 marketplace 条目 中声明，解析到 plugin 自己的目录之外。Claude Code 删除该路径并加载 plugin 的其余部分。消息中的组件名称（例如 commands 或 hooks）命名声明路径的字段。

commands path escapes plugin directory: ./../shared.md

在 claude plugin 命令输出中，相同的错误读作 Path escapes plugin directory: ./../shared.md (commands)。

Claude Code 拒绝指向 plugin 外部的路径（如 ../shared-utils）和导致 plugin 外部的符号链接，以及 marketplace 符号链接规则 不允许的符号链接。对于符号链接，消息还说明路径解析的位置：

commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory

在 macOS 和 Linux 上，Claude Code 还拒绝包含反斜杠的组件路径，即使路径保留在 plugin 内。其组件路径使用 Windows 风格分隔符的 plugin 在 Windows 上加载，并在其他平台上触发此拒绝：

commands path escapes plugin directory: ./commands\deploy.md — its path contains a backslash, which is not resolved reliably on this platform

在 v2.1.251 之前，Claude Code 加载在 marketplace 条目中声明的 commands 路径，即使它指向 plugin 目录之外。Claude Code 已经拒绝在 plugin.json 中声明的路径和 marketplace 条目中的其他组件路径。

在 v2.1.257 之前，检查仅查看路径的拼写，而不是符号链接导向的位置。

要做什么：

• 将引用的文件移到 plugin 目录内，并使用 ./ 相对路径指向它
• 如果路径是指向 plugin 外部文件的符号链接，请用文件副本替换符号链接
• 如果消息说路径包含反斜杠，请使用正斜杠写入路径，例如 ./commands/deploy.md
• 要与同一 marketplace 中的其他 plugin 共享文件，请使用 plugin 目录内的符号链接链接它们，遵循 符号链接规则

路径无法检查

Claude Code 询问操作系统 plugin 路径是否存在，并收到除"未找到"之外的错误，因此它不加载路径命名的内容。plugin 的加载量取决于哪个路径失败：

• plugin 的 默认组件位置 之一，例如 skills/ 文件夹、monitors/monitors.json 文件或 plugin 根目录的 SKILL.md：plugin 的其他组件仍然加载
• plugin 自己的目录：该 plugin 中没有任何内容加载

对于根本不存在的路径，您看不到此错误。在 /plugin 中，错误出现在 plugin 下方，并命名路径和操作系统返回的代码：

skills path could not be checked: /home/user/my-plugin/skills (ELOOP)

在 claude plugin list 中，相同的错误读作 Path not found: /home/user/my-plugin/skills (skills, ELOOP)。

产生此错误的原因包括：

• ELOOP：路径中的符号链接指向自身或形成循环
• EIO 或 ESTALE：路径在损坏或陈旧的网络挂载上
• EACCES：路径上方的目录之一拒绝您遍历它的权限

要做什么：

• 用真实文件夹替换指向自身的符号链接，或删除它
• 如果路径在网络挂载上，重新挂载共享
• 如果代码是 EACCES，恢复您对路径上方目录的执行权限
• 修复路径后运行 /reload-plugins，或重启 Claude Code，以加载 plugin 或组件

在 v2.1.265 之前，Claude Code 将无法检查的默认组件文件夹视为不存在，并加载 plugin 而不使用该组件，没有错误。

Marketplace 条目路径不保留在 marketplace 目录内

plugin 的 marketplace 条目 声明了一个源路径，Claude Code 无法将其解析到 marketplace 自己的目录内的位置，因此 plugin 不会安装或加载。拒绝涵盖：

• 绝对的条目路径、使用 .. 爬出 marketplace 的路径或拼写为网络路径的路径
• 在 macOS 和 Linux 上，在前导 ./ 之后的任何地方包含反斜杠的条目路径
• 从远程源（例如 git 或 URL）获取的 marketplace 中的条目，通过解析到 marketplace 目录外的符号链接到达其目标
• 从直接 URL 添加到其 marketplace.json 的 marketplace 中的相对条目：Claude Code 仅下载该文件，因此不存在本地 plugin 文件供路径命名。请参阅 相对路径的 Plugins 在基于 URL 的 marketplaces 中失败

claude plugin install 报告拒绝如下：

Cannot install my-plugin@my-marketplace: its marketplace entry path does not stay inside the marketplace directory (an absolute, climbing, network-shaped, backslash-containing or link-traversing entry, an entry of a fetched marketplace that resolves or opens outside its tree — or a relative entry in a url-catalog marketplace, which has no local directory)

当已安装的 plugin 的条目失败相同的检查时，claude plugin list 显示 plugin 为 failed to load，带有：

Plugin source path refused: ./my-plugin does not stay inside its marketplace directory. Check that the marketplace entry has a plain relative path.

要做什么：

• 如果您维护 marketplace，将条目的 source 写为带有正斜杠的纯相对路径，例如 ./plugins/my-plugin，并保持它穿过的任何符号链接指向 marketplace 目录内
• 如果您从直接 URL 添加了 marketplace，相对条目无法解析。要求 marketplace 作者使用 另一个 plugin 源，或改为从其 git 存储库添加 marketplace

无法加载 marketplace 配置

Claude Code 将您添加的 plugin marketplaces 保存在 ~/.claude/plugins/known_marketplaces.json 的注册表文件中。当 Claude Code 无法使用该文件时，需要注册表的 plugin 命令（例如 claude plugin install）会失败，并显示以下两条消息之一：

• Failed to load marketplace configuration：文件不是有效的 JSON，或无法读取。空文件也会以这种方式失败。
• Marketplace configuration file is corrupted：文件是有效的 JSON，但其内容与注册表架构不匹配。

缺少的文件不是失败：Claude Code 将其视为没有 marketplaces 的注册表。

对于空文件，claude plugin install 报告：

✘ Failed to install plugin "my-plugin": Failed to load marketplace configuration: JSON Parse error: Unexpected EOF

在 v2.1.246 之前，claude plugin install 没有报告此失败。

要做什么：

• 打开 ~/.claude/plugins/known_marketplaces.json 并修复 JSON，或修复消息命名为与注册表架构不匹配的条目
• 如果您无法修复它，删除文件或用 {} 替换其内容，然后使用 claude plugin marketplace add <source> 重新添加每个 marketplace。Claude Code 在您下次在您信任的文件夹中启动它时重新注册您的用户或托管设置在 extraKnownMarketplaces 中声明的 marketplaces。

Plugin 由您的组织要求

您运行了 claude plugin disable，或使用 /plugin Installed 选项卡关闭了从 claude.ai 同步的 plugin，您的组织将其标记为必需：

Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.

Claude Code 不保存任何内容，plugin 保持启用。

当您尝试禁用必需 plugin 依赖的 plugin 时，Claude Code 以相同的方式拒绝，消息命名需要它的必需 plugin。

要做什么：

• 要求您的 claude.ai 组织的管理员在 claude.ai 上更改 plugin 的必需状态

工具错误

这些错误来自 Claude 的内置工具。Claude 通常会自动纠正大多数工具错误。当需要你进行更改时，该错误的应该做什么列表会说明需要更改的内容。

Agent 将以零个工具生成

子代理的 tools 列表中的每个条目都无法匹配可用工具，因此 Claude Code 拒绝启动子代理：没有工具，它无法行动。该消息按出错原因对你的条目进行分组：

• 无法识别：该条目与任何工具名称都不匹配，通常是拼写错误，例如 Grpe 代替 Grep。
• 子代理不可用：该条目命名了一个真实工具，但子代理无法使用。后台子代理保持较小的内置工具集，因此当子代理在后台运行时（这是默认设置），只有前台子代理才能使用的条目会出现在这里。如果你列出 Agent，该消息会改为在下一组中报告它。
• 在此会话中未匹配任何工具：该条目有效，但当前会话中没有工具与其匹配，例如没有连接 GitHub MCP 服务器的 mcp__github__*，或子代理处于深度限制的 Agent。

省略 tools 字段永远不会触发此拒绝。如果你将 tools 列表留空，或 disallowedTools 删除其中的每个条目，Claude Code 也会跳过拒绝并启动没有工具的子代理。

在 v2.1.208 之前，子代理以零个工具启动，可能返回空结果或令人困惑的结果。

Agent '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.

应该做什么：

• 根据子代理可用的工具纠正错误命名的每个条目
• 删除会话没有的工具条目，例如来自未连接的服务器的 MCP 工具
• 对于后台子代理删除的工具（例如 CronCreate），删除该条目。要保留该工具，关闭 fork 模式并要求 Claude 在前台运行子代理
• 删除 tools 字段而不是列出工具，以给子代理每个子代理可用的工具
• 对于仅包含 Agent 的 tools 列表，提高深度限制或给代理至少一个其他工具：Claude Code 在该限制处保留 Agent，因此列表中没有其他内容会解析为零个工具

文件被 Read 拒绝规则覆盖

Edit 或 Write 工具在与 Read 拒绝规则匹配的路径上被调用，包括在该路径创建新文件。两个工具都会更改 Claude 必须能够读回的内容，因此 Claude Code 在任何文件访问之前拒绝该调用。NotebookEdit 不受 Read 拒绝规则覆盖。在 v2.1.228 之前，该规则仅阻止 Edit 工具，在 v2.1.208 之前，仅 Edit 拒绝规则阻止编辑。

File is covered by a Read deny rule in your permission settings and cannot be edited.

当 Claude Code 拒绝 Write 工具时，消息以 and cannot be written 结尾。

应该做什么：

• 如果 Claude 应该能够更改文件，请在 /permissions 或设置中删除或缩小 Read 拒绝规则
• 如果文件必须保持不变，请保留该规则并为相同路径添加 Edit 拒绝规则以同时阻止 NotebookEdit 工具

subagent\_type 是必需的

subagent_type is required: the general-purpose agent is not available in this session. Available agents: ...

Claude 调用了 Agent 工具而没有 subagent_type，此会话没有通用子代理可回退。这种情况出现在两种设置中：

• CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1在非交互模式下设置，这会删除每个内置子代理
• 会话的主线程代理有一个 tools: Agent(...) 允许列表，其中不包括 general-purpose

应该做什么：

• 通常不需要做任何事：该消息列出了会话确实拥有的子代理，因此 Claude 可以使用其中一个重试
• 如果 Claude 继续失败，请将 general-purpose 添加到 tools: Agent(...) 允许列表，或取消设置 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS

在 v2.1.235 之前，相同的调用失败并显示 Agent type 'general-purpose' not found。

内存索引超过其读取限制

Claude 写入了自动内存索引 MEMORY.md 并将其留在其读取限制之一上：200 行或 25KB。写入成功，但仅加载前 200 行或 25KB（以先到者为准），因此每次读取索引时，超过限制的所有内容都会被丢弃。在 v2.1.210 之前，超限索引在下次加载时被静默截断，没有写入时信号。

Error: this write left the memory index at MEMORY.md at 214 lines, over its 200-line read limit. The write succeeded, but everything past the limit is silently dropped each time the index is loaded — entries at the end are already invisible to readers. Rewrite it to under 140 lines now: keep one line per entry, move detail into topic files, and merge or drop stale entries.

仅加载的内容计入限制。YAML frontmatter 和块级 HTML 注释在加载索引前被删除，因此它们被排除在测量之外。在 v2.1.211 之前，Claude Code 测量原始文件，frontmatter 或注释即使在加载的内容符合时也可能触发此错误。

Claude Code 在写入后将错误传递给 Claude，而不是在你的终端中打印为横幅，因此你可能仅在记录中注意到它。

当 Claude 的写入使文件接近限制但未超过时，Claude Code 返回更温和的提醒以压缩索引，而不是此错误。

应该做什么：

• 让 Claude 重写 MEMORY.md，或要求它：每个条目保留一行，将详细信息移到主题文件中，并合并或删除过时条目
• 要自己修剪索引，请参阅审计和编辑你的内存

pkill 模式匹配 Claude Code 进程

Bash 工具调用中的 pkill 命令使用了一个模式（通常带有 -f），该模式与 Claude Code 进程本身匹配，因此 Claude Code 拒绝该命令而不是让它结束会话。Claude Code 在运行 pkill 之前使用 pgrep 测试该模式，并在其自己的进程 ID 在结果中时拒绝。该检查仅在 Linux 上运行；在 macOS 上，pkill 不经修改地运行。在 v2.1.214 之前，该命令运行，匹配的模式在中途杀死了 Claude Code 会话。

pkill: refusing to run — this pattern matches the Claude CLI process (PID 12345). Narrow the pattern, or target your own children with `pkill -P $$ ...`.

拒绝出现在 Bash 工具结果中，而不是作为你终端中的横幅，Claude 通常会自动调整该命令。

应该做什么：

• 缩小模式，使其仅匹配预期的进程，例如目标二进制文件的完整路径而不是短子字符串
• 要停止由当前 shell 启动的进程，请使用 pkill -P $$ 和该模式，这将匹配限制为 shell 自己的子进程

无法写入队友的收件箱

Claude Code 无法将消息写入 ~/.claude/teams/{team-name}/inboxes/ 下的队友邮箱文件，因此收件人没有收到任何内容。当 Claude Code 无法创建或更新文件时写入失败，例如因为磁盘已满、目录不可写或另一个代理长时间持有收件箱锁。在 v2.1.224 之前，Claude Code 即使在写入失败时也报告消息已发送。

该错误出现在发送代理的工具结果中，而不是作为你终端中的横幅，其文本告诉 Claude 重试：

Failed to write to researcher's inbox — nothing was sent. Try again, or message the lead.

结构化代理团队协议消息以相同方式失败，错误命名未送达的消息：当 Claude Code 无法写入计划批准、计划拒绝、关闭请求或关闭拒绝时，错误读取 Failed to write the <message> to <name>'s inbox — nothing was sent。该列表中的 plan approval 是领导批准队友计划的决定；队友的计划提交是单独的 plan approval request 消息。该消息和另外两个协议消息携带自己的消息文本和后果：

• Failed to write the plan approval request to the lead's inbox — plan not submitted; try again：队友的计划从未到达领导，队友保持计划模式直到重新提交成功
• The permission request could not be delivered to the team lead (mailbox write failed)：队友的权限请求从未到达领导，因此没有人批准工具调用
• The confirmation could not be written to team-lead's inbox.：关闭批准本身生效，队友退出；仅缺少对领导的确认

当你自己给队友发消息时，在领导会话中输入 @name 后跟消息，相同的失败显示为通知 Couldn't write to @name's inbox — message not sent. Try again.，Claude Code 将你的文本保留在提示框中，以便你可以再次发送。

应该做什么：

• 要求发送者重新发送消息；收件箱锁的争用是暂时的，重试时会清除
• 检查可用磁盘空间，并检查 ~/.claude/teams 及其下的文件是否可由你的用户写入

队友的代理定义未被恢复

Claude 给停止的代理团队队友发消息，Claude Code 将其恢复而没有重新应用它生成时的子代理定义，因为其定义文件来自没有保存信任的文件夹。该通知跟随发送代理的工具结果中的恢复报告：

Its agent definition was not restored: the folder its definition file came from is not trusted (source: projectSettings), so the teammate is running with the team-essential tools and no custom instructions. To restore it, the user needs to run Claude Code in that folder once and accept the trust dialog (the --debug log names the folder); do not change trust settings on the user's behalf.

该检查适用于项目的 .claude/agents/ 目录或 --add-dir 目录中的定义，接受父文件夹的信任对话不满足它。

应该做什么：

• 在调试日志命名的文件夹中运行 claude 并接受信任对话。下次 Claude Code 恢复队友时重新应用定义；你不需要重启领导会话
• 或在 ~/.claude.json 中将 hasTrustDialogAccepted 条目设置为 true，使用调试日志打印的确切 projects["<path>"] 键

跨会话传递消息过大

Claude 的跨会话消息到此机器上你的另一个会话太长而无法发送。Claude Code 拒绝了它，接收会话什么都没有收到。拒绝出现在发送会话的工具结果中，而不是作为你终端中的横幅。它命名两个大小以及如何使消息符合：

Failed to send to api-worker: Message too large for cross-session delivery: the serialized message is 1,203,844 characters and the limit is 1,048,576. Shorten the message text — put bulk content in a file the recipient can read rather than in the message — or split it into smaller messages.

重新发送相同的文本以相同方式失败。

应该做什么：

• 要求 Claude 总结消息，或将大量内容放在收件人可以读取的文件中而不是消息中
• 要求 Claude 将内容分成几条较短的消息

在 v2.1.235 之前，Claude Code 报告超大消息已发送。接收会话未读地丢弃了它。

此会话刚刚收到太多消息

Claude 向此机器上你的一个会话发送了快速的跨会话消息突发，突发达到了该会话的收件箱接受的内容。Claude Code 拒绝了下一次发送，接收会话什么都没有收到。拒绝出现在发送会话的工具结果中，而不是作为你终端中的横幅：

Failed to send to api-worker: Too many messages to this session just now: 30 were sent recently and more would be dropped by its rate limit, so this one was not sent. Batch what remains into one message, or wait a little before sending more.

应该做什么：

• 通常不需要做任何事：Claude 将剩余内容批处理为一条消息，或在发送更多内容前等待
• 如果你自己提示了突发，要求 Claude 将剩余内容合并为单条消息

在 v2.1.236 之前，Claude Code 报告这些发送已发送。接收会话未读地丢弃了它们。

拒绝发送跨会话消息

在 Claude Code 将跨会话消息写入此机器上你的另一个会话之前，它检查目标会话的收件箱套接字是消息寻址到的端点。当检查失败时，Claude Code 拒绝发送，目标会话什么都没有收到。对于 Claude 发送的消息，拒绝出现在发送会话的工具结果中：

Failed to send to api-worker: Refusing to send: reply target is a symlink

Refusing to send: 后的文本命名失败的检查：

• reply target is a symlink：符号链接位于目标会话的套接字路径。Claude Code 不通过它传递，因为那里的链接可能会将消息重定向到目标会话未创建的端点。
• cannot vet reply target：Claude Code 根本无法检查目标路径，例如因为读取失败并出现权限错误。
• connected endpoint is not the expected process：持有套接字的进程不是消息寻址到的会话，因此地址已过时或另一个进程替换了套接字。
• connected endpoint identity could not be read：Claude Code 已连接但无法读取哪个进程持有另一端，因此无法确认目标。这可能是暂时的。
• connected endpoint is not owned by this user：持有套接字的进程以不同的用户帐户运行，因此它不是你的会话之一。
• connected endpoint owner could not be read：Claude Code 已连接但无法读取哪个用户帐户拥有另一端，因此无法确认端点是你的。
• connected endpoint is a different process with the expected pid：进程 id 与消息寻址到的进程 id 匹配，但 Claude Code 无法确认它是同一进程。通常该会话已退出，操作系统重用了其进程 id，因此地址已过时。

应该做什么：

• 通常不需要做任何事：检查防止消息到达除了它寻址到的会话之外的端点，什么都没有发送
• 要求 Claude 再次列出你的会话并重新发送；由过时地址引起的拒绝在 Claude 发送到当前会话后清除
• 如果 reply target is a symlink 对一个会话重复，检查在该会话的套接字路径处创建了什么链接，显示在其 /status 下的 Peer address
• 对于 connected endpoint identity could not be read，重新发送；该条件可能是暂时的
• 如果 connected endpoint is not owned by this user 出现在共享机器上，该地址处的会话以另一个用户的帐户运行，因此 Claude 无法从你的帐户给它发消息

在 v2.1.248 之前，Claude Code 没有检查端点的拥有用户或进程启动时间，因此命名这些检查的拒绝不会出现在早期版本上。

拒绝读取、写入或搜索路径

Claude Code 检查文件路径的权限规则，然后在工具打开文件或启动搜索时再次确认该解析。当它无法确认路径仍然导向检查批准的位置时，Claude Code 拒绝操作而不是跟随它。拒绝出现在工具结果中：

Refusing to read /path/to/file: its symlink resolution changed after permission was checked (a link on the way now leads somewhere the check did not see). If a link in the working directory is being rewritten concurrently, stop that and retry.

每个拒绝命名其原因：

• its symlink resolution changed after permission was checked：路径上的符号链接或 Grep 或 Glob 搜索根在权限检查和操作之间被替换。在读取拒绝中，括号中的短语命名哪个比较失败。
• its parent-directory symlink resolution changed after permission was checked：写入路径通过的目录不再解析到批准的位置
• it is a symbolic link. Write to the link's target path instead：符号链接位于批准的写入位置本身，例如 CLAUDE.md 是 AGENTS.md 的符号链接；消息指导 Claude 到链接的目标
• Refusing to write through symlink: <path>. Resolve the symlink and pass the real target path explicitly.：当另一个写入器打开文件时捕获的相同条件，例如写入符号链接的 .mcp.json
• Refusing to write into symlinked directory: <path>：持有文件的目录本身是符号链接，例如项目的 .claude/ 目录链接到另一个位置
• a path one of its Read deny rules is written through changed while the search was being prepared. Retry.：搜索的 Read 拒绝规则命名通过符号链接的路径，该链接在 Claude Code 准备搜索时更改
• it could not be opened (EACCES) — it is unreadable, or is being replaced concurrently.：搜索根存在但无法打开；括号中的代码是操作系统错误
• its permission check expired before it ran (too many concurrent file operations). Retry.：Claude Code 在许多同时文件操作下驱逐了批准记录，然后工具使用了它；重试运行新的权限检查
• ripgrep was found only by name on PATH, and a search outside the working directory cannot apply your Read deny rules in that configuration：Claude Code 无法将 rg 二进制文件解析为绝对路径，因此它拒绝工作目录外的搜索，而不是运行你的拒绝规则不覆盖的搜索

应该做什么：

• 通常不需要做任何事：拒绝到达 Claude 作为工具结果，拒绝的操作不运行
• 如果符号链接拒绝在一个路径上重复，找到什么保持在那里重写链接，例如构建工具或文件监视程序，或要求 Claude 使用文件的解析路径而不是链接的路径
• 如果此拒绝对 Windows 上 AppContainer 或受限令牌沙箱内运行的每个文件出现，升级到 v2.1.265 或更高版本
• 如果读取拒绝在 macOS 上出现，针对没有任何东西重写的文件，例如拖入提示的屏幕截图，升级到 v2.1.273 或更高版本
• 对于 ripgrep 拒绝，使用你的包管理器安装 ripgrep，以便 rg 在 PATH 上解析为绝对路径，或将搜索保持在工作目录下

在 v2.1.251 之前，Claude Code 仅对文件写入重新检查路径的解析，因此在权限检查后替换的链接可能会将读取或搜索重定向到不同的位置而没有消息。其中，仅父目录、通过符号链接和符号链接目录写入拒绝出现在早期版本上。

任务输出交换被拒绝

Claude Code 将每个 Bash 命令的输出保存到其临时目录下的文件。每次打开其中一个文件时，它检查路径仍然导向它创建的文件，没有符号链接、额外硬链接或移动目录重定向它。此消息意味着该检查失败，因此 Claude Code 拒绝操作而不是通过该路径写入或读取输出。消息出现在 Bash 工具结果中：

task output swap refused (tasks dir moved or linked): /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks/b7k2f9m3q.output. To recover: restart Claude Code with CLAUDE_CODE_TMPDIR set to a fresh directory; or, if /private/tmp/claude-501/-Users-you-my-project is a stray directory or a symbolic link that should not be there, remove that entry itself (not what it points to) and restart.

括号中的文本命名失败的检查。诸如 output symlink was re-pointed、output file identity changed 和 not a regular file 之类的原因都报告相同的条件：输出路径上或沿着的某些东西不再是 Claude Code 创建的文件。仅某些原因携带 To recover: 句子。

如果在命令仍在运行时检查失败，Claude Code 停止该命令，其结果报告：

Command killed: its output file was replaced or could no longer be verified

应该做什么：

• 升级到 v2.1.260 或更高版本。早期版本有时在没有链接或移动目录存在时显示此消息
• 使用设置为新目录的 CLAUDE_CODE_TMPDIR重启 Claude Code
• 或检查你的项目在 Claude Code 临时目录下的目录，示例消息中的 /private/tmp/claude-501/-Users-you-my-project。如果该路径是符号链接或不应该存在的目录，删除链接或目录本身而不是链接的目标，然后重启 Claude Code
• 如果拒绝重复，进程在会话运行时替换、链接或删除 Claude Code 临时目录下的条目。将 CLAUDE_CODE_TMPDIR 设置为没有其他东西管理的目录并重启

源文件不是有效的 UTF-8 文本

Claude 尝试从字节不解码为文本的文件发布工件，或其文本已包含替换字符 U+FFFD，因此 Claude Code 拒绝发布，然后上传任何内容。消息出现在 Artifact 工具结果中并命名第一个要修复的位置：

file_path: the source file is not valid UTF-8 text (first invalid byte at line 12, column 40). It may be saved in another encoding or contain binary data. Rewrite it as UTF-8, then publish again. Nothing was published.

file_path: the source file has the replacement character U+FFFD at line 12, column 40, usually left where an earlier edit or paste lost a character. Replace it with the intended text (in HTML, write an intended U+FFFD as �), then publish again. Nothing was published.

Claude Code 将文件解码为 UTF-8，或当它以小端 UTF-16 字节顺序标记开始时解码为 UTF-16。当这样的 UTF-16 文件不解码时，第一条消息命名 UTF-16 并仍然告诉你将文件重写为 UTF-8。当更多位置跟随命名的位置时，消息在位置后添加计数，例如 (+2 more)。

应该做什么：

• 通常不需要做任何事：Claude 重写文件并再次发布
• 如果文件是你写或导出的，再次将其保存为 UTF-8，并将每个 U+FFFD 替换为早期编辑、粘贴或转换丢失的字符
• 要在页面上显示有意的 U+FFFD，在 HTML 中将其写为 � 而不是文字字符

在 v2.1.267 之前，Claude Code 上传这样的文件而不检查它，服务器拒绝发布。

在 Cowork 会话中从连接的文件夹外读取本地文件

在 Claude Desktop 应用中在你的机器上运行的 Cowork 会话中，Claude 为工件命名了本地文件。Claude Code 无法确认文件是会话连接的文件夹内的纯文件：路径位于这些文件夹外、通过符号链接或以可能命名不同文件的方式拼写。读取这样的文件需要你的批准，在无法向你显示批准卡的会话中，例如设置为跳过所有批准的会话，Claude Code 拒绝读取。

拒绝出现在 Artifact 工具结果中；当文件根本无法检查时，它改为命名该失败：

Reading a local file from outside this session's connected folders, or through a link, needs the approval card, and no one can answer it in this Cowork session. Use a plain file inside the connected folders; do not retry this file in this session.

cannot read file_path (ENOENT) — the file could not be examined, and no one can answer the approval card in this Cowork session. Check that the file exists as a plain file inside the connected folders, then retry with that path.

应该做什么：

• 通常不需要做任何事：消息告诉 Claude 改为使用连接的文件夹内的纯文件
• 要将该确切文件放在工件中，将其复制到会话的连接文件夹之一中作为常规文件（不是符号链接），然后再次询问

WebFetch 无法获取 localhost

Claude 调用了 WebFetch，其 URL 的主机名没有点，例如 http://localhost:3000 或裸 intranet 名称如 http://wiki/。WebFetch 在进行任何请求之前拒绝这些 URL：

WebFetch cannot fetch localhost or other hostnames without a dot. To reach a local server, use Bash with curl instead.

应该做什么：

• 通常不需要做任何事：消息指向 Claude 通过 Bash 工具使用 curl，它可以到达本地和 intranet 服务器

在 v2.1.268 之前，WebFetch 用通用 Invalid URL 错误报告这些 URL。

后台会话错误

后台会话在没有自己的交互式终端的情况下运行，因此需要终端的命令在那里的行为会有所不同。这些消息出现在后台会话的记录中、附加到后台会话的终端中、您分派的会话或 shell 中，或者对于下面的worktree-guard 条目，出现在任何在 worktree 中隔离的会话或运行 worktree 隔离子代理中；当消息特定于一个表面时，其条目会说明这一点。

后台会话中拒绝的命令

打开交互式对话框的命令在没有终端附加到后台会话时无法执行。/install-github-app、/mcp 设置列表和 MCP 服务器菜单中的身份验证操作会响应一条消息，该会话在代理视图中的需要输入下显示，以便您可以找到它、附加并再次运行该命令。附加终端时，这些命令正常工作。

在 v2.1.216 之前，会话在其中一次拒绝后不会在需要输入下显示。在 v2.1.213 到 v2.1.215 中，附加终端时命令仍然有效，拒绝消息告诉您附加并再次运行该命令。从 v2.1.208 到 v2.1.212，Claude Code 即使附加了终端也拒绝了它们，消息如 Can't open MCP settings in a background session；在这些版本上，从常规 claude 会话运行该命令，或升级。在 v2.1.208 之前，它们在后台会话内打开了对话框。在仅 v2.1.208 中，Claude Code 也拒绝了后台会话中的 /model 选择器，/upgrade 打印了升级 URL 而不是打开浏览器。

措辞命名该命令。/mcp 设置列表报告：

Can't open MCP settings while no terminal is attached to this background session. This session now shows "needs input" in agent view — open it and run /mcp to manage servers, or use `/mcp enable|disable|reconnect <server>` to steer without the panel.

要做什么：

• 从代理视图附加到会话，其中它在需要输入下列出，然后再次运行该命令
• 或使用消息命名的形式，例如 /mcp reconnect <server>、/mcp enable 或 /mcp disable，这些不需要附加即可工作

写入或命令被阻止，因为路径无法安全解析

Claude 通过 worktree 隔离保护无法解析为一个可验证位置的拼写来寻址文件或工作目录。保护检查任何在 worktree 中隔离的会话中的写入和命令工作目录，交互式或后台，以及worktree 隔离的子代理中的写入和命令工作目录。它在检查操作不会到达共享检出之前解析符号链接，当解析失败时，它会阻止操作而不是让它落在那里。消息命名它拒绝的路径形式以及如何重试：

This write was blocked because the path is spelled in a form that cannot be safely resolved (for example through a symlink storing a raw dot segment, a network-share or device-namespace shape, or an unreadable ancestor directory). If the file is inside the worktree /path/to/worktree, address it by its direct symlink-free path instead.

被阻止的命令为其工作目录报告相同的原因，并以 re-run the command from its direct symlink-free path 结尾。在 v2.1.217 之前，保护在不解析符号链接的情况下比较路径拼写，因此这些拼写未被阻止，通过符号链接路由的写入可能会落在共享检出中。

要做什么：

• 通常什么都不做：完整消息作为工具错误发送给 Claude，Claude 使用它命名的直接路径重试。对于被阻止的文件编辑，对话视图仅显示简短的 Error editing file 行；完整消息出现在您使用 Ctrl+O 打开的记录视图中。被阻止的命令在其命令输出中打印它。
• 如果同一文件上的块重复，路径可能通过包含 .. 的已提交符号链接运行，例如 docs/current -> ../README.md；要求 Claude 通过其真实路径而不是通过链接编辑目标文件

写入或命令被阻止，因为路径命名网络位置

Claude 通过命名不在您机器上的驱动器、UNC 共享（如 \\server\share\file）或 /net 自动挂载路径的路径来寻址文件或工作目录，而会话的检出在本地磁盘上。相同的 worktree 隔离保护无法验证这样的路径保持在共享检出之外，因此它会阻止操作。在 worktree 中隔离会话不会解除阻止。消息命名要使用的路径形式：

This write was blocked because the path is network-shaped (a UNC share or /net automount spelling) while this session's checkout is local. Isolating cannot unblock it. If the file is genuinely inside the worktree /path/to/worktree, address it by its local, plainly-spelled path instead.

被阻止的命令为其工作目录报告相同的原因，并以 re-run the command from its local, plainly-spelled path 结尾。在 v2.1.217 之前，保护仅比较路径文本，因此通过 UNC 或 /net 路径寻址检出内的文件未被阻止。

要做什么：

• 通常什么都不做：Claude 使用消息要求的本地拼写重试
• 如果文件在网络共享上而不是用网络路径拼写的本地文件，它在会话的本地工作区之外；改为从常规交互式会话编辑它

命令被 worktree 隔离检查阻止

Claude 在在 worktree 中隔离的会话中运行了 Bash 或 Monitor 命令，Claude Code 因以下两个原因之一拒绝了它：

• 该命令将 git 指向主检出。
• Claude Code 无法从命令文本验证该命令运行的任何 git 都保留在 worktree 内。从不命名 git 的命令仍然可能因此原因被拒绝，因为展开变量间接寻址（如 ${!name}）或运行 Bash 函数替换（如 ${ command; }）会产生在运行时本身可能是命令的值。

消息的中间命名无法验证的内容：

This session is isolated in the worktree /path/to/worktree, but this command evaluates ${!x@P} arithmetically inside a construct too complex to verify, which can run a command hidden in a variable's value. Refusing to run it — a worktree-isolated session's git operations must target its own worktree. Split it into plain, separate commands and run them from /path/to/worktree.

要做什么：

• 通常什么都不做：Claude 读取消息并按照其最后一句要求的方式重写命令
• 如果您要求的命令继续被拒绝，按字面拼写标记的值：用其值替换间接寻址或替换，并从 worktree 内作为其自己的纯命令运行 git
• 要有意对主检出采取行动，在会话外的终端中自己运行该命令

此会话没有保存的记录

您附加到一个停止的后台会话，该会话从另一个对话中用 ← 或 /background 后台化，并在其第一个响应完成之前停止。在该第一个响应完成之前，对话仍然仅存在于后台化它的会话中，因此 claude attach 拒绝启动停止的会话，而不是在相同的会话 ID 下开始空白对话。消息以此会话的 claude respawn 命令结尾：

This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.

在代理视图中打开相同会话的行显示 Press enter again to restart this session fresh 在列表下方，在该行上第二次 Enter 使用空对话重启会话。在 v2.1.212 之前，打开该行显示拒绝消息，无法从代理视图重启。在 v2.1.211 之前，打开停止的会话无声地启动了该空白对话，并可能重新运行会话的原始提示。

要做什么：

• 您后台化的对话是完整的：使用 claude --resume 恢复它或继续在其中工作
• 要无论如何启动停止的会话，请使用消息中的 ID 运行 claude respawn <id>，或在代理视图中的其行上按 Enter 两次
• 如果会话确实完成了响应，您仍然在 v2.1.214 之前的版本上看到此拒绝，~/.claude/projects 中的不可读文件夹可能会使记录扫描错过保存的对话；更新到 v2.1.214 或更高版本，它在扫描期间容忍不可读的文件夹

此会话在另一个终端中运行

您在代理视图中打开了停止的会话的行，其保存的对话已在此机器上的另一个实时 Claude Code 进程中打开，因此 Claude Code 拒绝启动将写入相同记录的第二个进程。您看到的消息取决于什么持有对话：

Can't open — this session is running in another terminal
This conversation is already open in another running Claude session — use that one, or close it and try again

• running in another terminal：终端持有对话，例如您使用 claude --resume 或 /resume 恢复它的终端。该行也显示 Open in a terminal。
• already open in another running Claude session：另一个非交互式 Claude Code 进程持有它，例如相同对话的后台会话进程尚未退出。

Claude Code 保存您在打开行时键入的回复，并在会话下次启动时将其作为会话的下一个提示发送。

要做什么：

• 在持有它的进程中继续对话，或退出该进程并再次打开该行

在 v2.1.248 之前，仅存在 already open in another running Claude session 拒绝：在终端中恢复的对话不计为打开，打开该行启动了第二个 Claude Code 进程写入相同的对话。

此会话的保存对话不再在磁盘上

您打开了一个后台会话，该会话在后台服务关闭时结束，记录清理随后删除了其保存的对话，例如在机器关闭数周后。通常打开这样的行会恢复其保存的对话。没有什么可恢复的，Claude Code 拒绝而不是在不询问的情况下重新运行会话的原始提示：

This session's saved conversation is no longer on disk (it ended while the background service was off, and old transcripts are cleaned up), so there is nothing to resume. `claude rm 7c5dcf5d` deletes the row; `claude respawn 7c5dcf5d` runs its original prompt again instead.

claude attach <id> 打印此文本。在代理视图中，页脚更短，以 ctrl+x deletes the row 结尾。

要做什么：

• 运行 claude rm <id> 删除该行。当保留的情况之一适用时，claude rm 保留该行和 worktree，并命名原因
• 要再次运行会话的原始提示作为新对话，请运行 claude respawn <id>

在 v2.1.248 之前，打开这样的行会重新运行会话的原始提示，而不是拒绝，将数周前的任务拉回前景。

Worktree 有未推送到任何地方的提交

您尝试删除一个后台会话，其 worktree 持有 Claude Code 无法确认保存在其他地方的提交。Claude Code 保留 worktree 和会话行，而不是销毁提交。claude rm 命名分支和未推送的提交，并说明如何继续：

kept 7c5dcf5d — its worktree is still at "/home/you/project/.claude/worktrees/fix-login"
  2 unpushed commits on "claude/fix-login": a1b2c3d "Fix login flow" and 1 more. They exist on no remote, so deleting the worktree would lose them.
  push them and run 'claude rm 7c5dcf5d' again, or discard the worktree and its commits: claude rm 7c5dcf5d --discard-unpushed a1b2c3d000000000000000000000000000000000@0123456789abcdef0123456789abcdef

当 Claude Code 无法总结提交时，详细行读取 The worktree has unpushed commits。在代理视图中，会话的行显示 not deleted 和相同的原因。

远程上的提交不会阻止删除。本地副本中您的 origin 远程的默认分支上的提交也不会，只要该分支在您的主检出中检出，即存储库目录本身而不是 worktree。

要做什么：

• 要保留提交，推送 worktree 的分支，或将其合并到在主检出中检出的默认分支，然后再次删除会话
• 要丢弃提交，运行消息打印的 claude rm <id> --discard-unpushed 命令，或在代理视图中的会话行上再次按 Ctrl+X。这会删除会话和 worktree 以及其分支、未推送的提交和任何未提交的更改。如果 worktree 自拒绝以来获得了提交，Claude Code 再次保留它并显示更新的状态
• 当消息说 worktree 也由另一个完成的会话记录时，再次删除不会丢弃它：推送提交，然后再次删除会话

在 v2.1.268 之前，claude rm 将提交摘要放在 kept 行本身上。当 claude rm 无法总结提交时，kept 行读取 worktree has commits that are not pushed anywhere 代替摘要。

在 v2.1.260 之前，消息没有命名分支或提交，再次删除被拒绝的方式相同：删除会话而不推送意味着使用 git worktree remove --force <path> 自己删除 worktree，然后再次运行 claude rm <id>。

在 v2.1.248 之前，在主检出中检出的默认分支不计数：您已经合并到那里的分支仍然触发此拒绝，直到其提交到达远程。

终端主机进程已死亡

每个后台会话的终端在后台服务下的主机进程中运行，该进程在服务仍然持有其连接时死亡，因此无法到达会话。

在 Linux 和 WSL 上，后台服务每隔几秒检查每个主机进程，当进程已退出但其与服务的连接从未关闭时标记会话失败，并在代理视图中的其行上显示原因：

terminal host process died — press Enter to restart

如果您在检查运行之前打开该行，页脚显示 This session's terminal host process died (the conversation is saved) — press Enter to restart it，该行变为失败。

从 shell，claude attach <id> 重启已标记为死主机失败的会话，否则打印原因并退出：

Couldn't attach to <id> — This session's terminal host process died (the conversation is saved) — run `claude attach <id>` again to restart it on a fresh host.

对话无论如何都被保存。

运行shell 命令的行显示 terminal host process died — its output is gone; the command was not run again，claude attach 打印 This command's terminal host process died — its output is gone and the command was not run again。Claude Code 从不为您重新运行该命令。

要做什么：

• 在代理视图中，在失败的行上按 Enter；会话在新的主机进程上重启，对话恢复
• 从 shell，再次运行 claude attach <id>。Claude Code 打印 Session <id>'s terminal host died — restarting it on a fresh one… 并重新打开会话
• 您无法以这种方式重启 shell 命令行；再次分派命令以重新运行它

在 v2.1.247 之前，死主机进程可能通过后台服务运行的每个活跃性检查，因此打开会话无限期地显示 opening… · esc to cancel，claude attach <id> 等待而不报告错误。

会话没有响应

您打开了一个后台会话，后台服务接受了打开，但大约十秒钟内没有输出到达，因此 Claude Code 得出结论，中继会话终端的进程无法传递输出，并结束尝试而不是等待。

在代理视图中，Claude Code 在页脚中提供重启：

Press enter again to restart this session — it isn't responding (its conversation is saved and resumes).

从 shell，claude attach <id> 打印原因并退出：

Couldn't attach to <id> — Session isn't responding — `claude stop <id>`, then `claude attach <id>` restarts it (the conversation is saved).

Claude Code 从不为您重启运行shell 命令的行，因为重启会再次运行该命令。

要做什么：

• 在代理视图中，在同一行上再次按 Enter。Claude Code 停止无响应的进程并重启会话，对话恢复。没有第二次按下就不会停止任何东西
• 从 shell，运行 claude stop <id>，然后 claude attach <id>
• 对于 shell 命令行，在代理视图中按 Ctrl+X 或运行 claude stop <id> 停止它；再次分派命令以重新运行它

会话在 respawn 进行中时被停止

您打开了一个后台会话，其进程未运行，当 Claude Code 重启它时，另一个 Claude Code 进程停止了它，例如在另一个终端中 claude stop。Claude Code 保持会话停止：

Session <id> was stopped while the respawn was in flight

打开您刚刚分派的会话，当其进程仍在启动时，等待进程。在 v2.1.246 之前，在那一刻打开它可能会停止它并显示此消息。

要做什么：

• 如果您没有停止会话，在代理视图中再次打开其行或运行 claude respawn <id> 重启它
• 如果您自己停止了它，没有什么剩下要做的：会话保持停止

会话代理不再可用

您恢复了一个正在运行自定义代理的会话，使用 --agent 或 agent 设置启动，Claude Code 没有找到具有该名称的代理。它首先搜索会话的原始目录，当您信任该工作区时，然后搜索您恢复的目录。会话仍然恢复，但使用默认工具，因此代理的工具限制不再适用：

This session was running agent 'code-reviewer', which is no longer available (no agent by that name in /home/you/project). Continuing with the default tools and system prompt — the agent's tool restrictions no longer apply. To restore it, re-create the agent, or resume with an explicit --agent <name>.

警告仅命名 Claude Code 搜索的目录，它出现在恢复的对话中，无论您唤醒后台会话、运行 /resume 或 claude --resume，还是在非交互式模式中恢复，它也发送到 stderr。使用 --input-format stream-json 的会话不显示它，因为 Agent SDK 在启动后提供代理。

Claude Code 不保存回退到会话，因此警告在每次恢复时重复，直到您采取行动。内置 claude 代理不触发警告，因为回退到默认工具集对它没有改变。在 v2.1.216 之前，Claude Code 无声地继续作为默认代理，查找仅覆盖您恢复的目录，因此项目范围的代理在从另一个目录恢复时丢失。

要做什么：

• 在会话的项目中的 .claude/agents/<name>.md 或个人代理的 ~/.claude/agents/<name>.md 重新创建代理文件，然后再次恢复
• 或使用 --agent <name> 恢复，命名确实存在的代理，以改为作为该代理运行会话
• 如果代理是项目范围的，您还没有信任会话的原始目录，在那里运行一次 Claude Code，接受信任对话，然后再次恢复

CLAUDE\_CODE\_PROCESS\_WRAPPER 启动器错误

CLAUDE_CODE_PROCESS_WRAPPER 已设置，其值无法使用，因此 Claude Code 拒绝启动受影响的进程，而不是在没有启动器的情况下运行它。配置问题报告为以变量名开头并说明原因的消息，例如：

CLAUDE_CODE_PROCESS_WRAPPER: launcher `/opt/corp/launcher` is not an executable regular file

启动但在用 Claude Code 替换自己之前退出的启动器会使其启动的会话失败，会话在代理视图中的行报告启动器 must exec, not daemonize，后跟启动器打印的任何内容。无法启动或到达后台服务的会话因启动器报告启动器问题作为 Couldn't reach the background service (...) 内的原因。

要做什么：

• 将变量设置为以调用 exec "$@" 结尾的可执行文件的绝对路径。有关完整合同，请参阅启动器合同
• 检查 /status，它在其 Self-exec 条目中显示解析的启动命令，并在运行的后台服务不匹配时警告，或从 shell 运行 claude daemon status
• 在设置的 env 块中修复值后，使用 claude daemon stop --any 重启后台服务，以便下一次分派启动一个包装的

启动后台会话时 EUNKNOWN

Windows 拒绝使用没有标准名称的错误代码启动程序，因此失败显示为 EUNKNOWN。通常的触发器是软件限制策略，例如组策略或 AppLocker，阻止启动的程序。当您使用 /background 或 claude --bg 启动后台会话时，错误出现：

Couldn't reach the background service (spawn background service: EUNKNOWN: unknown error, uv_spawn) — run 'claude daemon status'

在某些帐户上，消息说 daemon 代替 background service。

在 npm 安装上，在 npm install -g @anthropic-ai/claude-code 替换二进制文件时出现的 EUNKNOWN 与重新安装期间的 EACCES 有相同的原因，并在您在安装完成后重试时清除。

Claude Code 通过 PowerShell 启动后台服务，以便服务在关闭终端后存活，在安装时使用 PowerShell 7，否则使用 Windows PowerShell 5.1。当两个 PowerShell 都无法运行时，Claude Code 直接启动服务，因此仅阻止 PowerShell 的策略不会导致此错误。如果您在没有 npm 安装运行时看到它，策略正在阻止 Claude Code 可执行文件本身。

在 v2.1.212 之前，Claude Code 仅使用 Windows PowerShell 5.1 启动服务，因此任何组策略阻止 PowerShell 5.1 的机器失败，出现 Couldn't start the session — EUNKNOWN: unknown error, uv_spawn，即使安装了 PowerShell 7。

要做什么：

• 如果消息读取 Couldn't start the session，升级到 v2.1.212 或更高版本。在早期版本上，您也可以在单独的终端中首先运行 claude daemon run，然后再次启动后台会话。该命令在终端的前景中运行后台服务，因此服务仅在该终端保持打开时持续。
• 如果 npm 安装正在替换二进制文件，等待它完成，然后再次启动后台会话
• 如果错误在 v2.1.212 或更高版本上出现，而没有 npm 安装运行，请要求您的 Windows 管理员在限制策略中允许 Claude Code 可执行文件
• 如果关闭终端时后台服务停止，Claude Code 在没有 PowerShell 的情况下启动了它。安装 PowerShell 7，或要求您的管理员解除对 PowerShell 的阻止，以便服务可以超越终端。

启动后台会话时 EACCES

Claude Code 无法运行其自己的二进制文件来启动后台服务，该服务托管后台会话。在 npm 安装上，这通常意味着 npm install -g @anthropic-ai/claude-code 在那一刻替换二进制文件，无论您运行它还是自动更新程序运行。当您从代理视图打开会话时，错误出现：

Couldn't start the background service — spawn background service: EACCES: permission denied, posix_spawn '/usr/local/lib/node_modules/@anthropic-ai/claude-code/bin/claude'

当您使用 /background 或 claude --bg 启动会话时，相同的原因出现在 Couldn't reach the background service (...) 内。在相同的重新安装窗口期间，错误可能命名另一个代码，例如 ENOENT 或 ENOEXEC，或在 Windows 上 EUNKNOWN 或 EPERM；跨重试持续的 EUNKNOWN 有不同的原因。

在 npm 安装上，Claude Code 等待重新安装完成并自动重试：最多十秒，以及在 npm 安装 Claude Code 在机器上仍然可见运行时最多两分钟，这涵盖了另一个 Claude Code 进程下载更新。当安装超过该等待时，失败命名更新而不是裸错误代码：

Claude Code is being updated by npm on this machine (still not runnable after 2 min, EACCES) — try again when the update finishes

在 v2.1.257 之前，等待在每种情况下都在十秒处停止，因此此错误在另一个 Claude Code 进程仍在下载更新时出现。在 v2.1.246 之前，Claude Code 立即失败，没有等待。

要做什么：

• 等待几秒钟，然后打开会话或再次分派。当消息说 Claude Code 正在更新时，在更新完成后重试。
• 如果错误在没有 npm 安装运行时持续，您的用户无法运行已安装的二进制文件。检查其权限及其目录的，或重新安装 Claude Code。

后台服务在变得可达之前退出

Claude Code 启动的进程作为后台服务在变得可达之前退出，因此 Claude Code 无法打开您的会话。当服务在退出前打印错误时，括号中的原因给出退出代码或信号以及服务打印的第一行，它命名停止它的内容：

Couldn't reach the background service (background service exited before it became reachable (exit code N): <the service's first error line>) — run 'claude daemon status'

当您从代理视图打开会话时，相同的原因跟随 Couldn't start the background service —。当服务在退出前没有打印任何内容时，消息说 nothing on stderr。

Claude Code 使用服务的错误行报告失败。在 v2.1.246 之前，失败仅在 45 秒等待后显示，作为 background service did not become reachable within 45s，没有服务的错误行。

两个引用的原因有已知的原因：

• Error: claude native binary not installed.：npm 安装在那一刻替换 Claude Code 二进制文件，因此服务运行了 npm 的占位符。在安装完成后重试；如果没有安装运行的行持续，完成 npm 安装。在 v2.1.257 之前，macOS npm 自更新在安装窗口期间的每次启动时产生此失败。
• 在 Windows 上，nothing on stderr 和退出代码 1，每次启动：daemon.lock 命名一个 Claude Code 既无法发信号也无法证明已消失的进程，因此每个新服务得出结论另一个持有锁并退出。Claude Code 可以证明其编写者已消失的锁会自动替换，不会产生此失败。当失败在每次启动时重复时，删除 ~/.claude/daemon.lock，然后打开会话或再次分派。在 v2.1.257 之前，这样的锁阻止了每次启动，直到您删除了文件。

要做什么：

• 如果消息引用一行，修复它命名的内容，然后打开会话或再次分派。下一次尝试再次启动服务
• 运行 claude daemon status 检查现在是否有服务运行

启动后台会话时工作目录不再存在

您尝试在不再存在的目录中启动后台会话。当您从代理视图分派或在删除或移动您正在工作的目录后运行 /background 时，会发生这种情况。当您附加到或重启一个进程已退出且目录已消失的会话时，也会发生这种情况，因为新进程会在相同的目录中启动。Claude Code 不启动会话，消息命名缺失的目录：

Couldn't start a background session (working directory no longer exists or is not accessible: /tmp/demo)

在 v2.1.257 之前，会话似乎启动，然后在代理视图中显示为具有相同原因的失败行。

要做什么：

• 重新创建消息命名的目录，或从存在的目录分派，然后重试

包装器和 IDE 错误

这些错误来自启动 Claude Code 的程序，例如 IDE 扩展或 Agent SDK 应用程序，而不是来自 Claude Code 本身。

Claude Code 进程以代码 N 退出

底层 claude 进程以非零代码退出。仅凭退出代码无法说明失败的原因：真正的错误在于进程自身的输出，包装器会在捕获时附加该输出，否则将其保留在日志中。

Error: Claude Code process exited with code 1

在 Windows 上，本机构建可能在回合完成后立即以代码 4294967295 退出。当该退出发生在回合边界处，没有等待的消息且没有后台任务运行时，VS Code 扩展会静默关闭会话而不显示此错误。您的下一条消息将恢复对话。

在 v2.1.273 之前，扩展在每个回合边界处显示该退出的错误，即使没有任何内容丢失。

应该怎么做：

• 在 VS Code 中，点击错误显示的查看输出日志链接以查看底层故障
• 在 Agent SDK 应用程序中，在消息循环周围捕获错误。CLI 进程退出下的条目涵盖了您的代码在每种 SDK 语言中接收的内容。
• 在终端中的同一项目中运行 claude。故障通常会在那里重现，并显示其真实错误消息，您可以在此页面上查找。
• 在终端中运行 claude doctor 以检查安装和配置

无法在 PATH 上找到 Claude CLI

当您在集成终端中打开 Claude Code、终端的 shell 是 PowerShell 且扩展无法在 PATH 上找到已安装的 claude 可执行文件时，VS Code 扩展在 Windows 上显示此错误。扩展拒绝启动 Claude Code，直到它在 PATH 上找到已安装的 claude。

Failed to run Claude Code: Error: Could not locate the Claude CLI on PATH. Launching by name in a PowerShell terminal would run a 'claude' from the open folder instead of the installed CLI, so the launch was blocked. Make sure the Claude CLI's install directory is on your system PATH (not only your PowerShell profile), then restart VS Code and try again. VS Code reads PATH when it starts, so PATH changes take effect only after a restart.

应该怎么做：

• 在 VS Code 外打开新的 PowerShell 窗口并运行 where.exe claude。如果它没有打印路径，则 CLI 不在您的 PATH 上：按照验证您的 PATH添加其安装目录。如果它打印了路径，该条目来自您的 PowerShell 配置文件或 VS Code 尚未获取的 PATH 更改；接下来的两个步骤涵盖这些情况。
• 将 PATH 条目设置为用户或系统环境变量，而不是在您的 PowerShell 配置文件中。扩展不运行您的配置文件，因此仅存在于那里的 PATH 编辑永远无法到达它。
• 更改 PATH 后重启 VS Code。扩展检查 VS Code 在启动时捕获的 PATH，因此 PATH 更改仅在重启后生效。

Claude Code 的连接在此消息完成前结束

VS Code 扩展将您的消息发送到 claude 进程，连接在进程确认或完成之前无错误地结束。扩展无法判断消息是否已处理，因此它要求您再次发送：

The connection to Claude Code ended before this message completed — it may not have been processed, so please send it again.

应该怎么做：

• 再次发送消息。下一条消息启动一个新的 claude 进程，该进程恢复对话。
• 如果重复发生，在同一项目的终端中运行 claude。持续结束进程的故障通常会在那里重现，并显示其真实错误消息。

Rewind 警告和错误

这些消息来自 /rewind 代码恢复。Restored the code, but skipped N files 是一个警告，表示 Claude Code 跳过了某些路径。No files were restored 是一个错误，表示它没有恢复任何内容。

Restored the code, but skipped files

一个 /rewind 代码恢复跳过了一个或多个跟踪的路径，而不是通过它们进行写入或删除。Claude Code 在以下情况下会跳过一个路径：

• 它是或变成了符号链接、硬链接或其他非常规文件
• 自检查点以来其目录已更改
• 其备份无法安全读取

跳过的路径保持其当前内容。在 v2.1.216 之前，/rewind 通过跟踪路径上的链接进行写入和删除，并且不报告部分恢复。

Restored the code, but skipped 2 files: the tracked path is (or became) a link or other non-regular file, its directory changed since the checkpoint, or its backup could not be safely read. Skipped files were left untouched — run with --debug for the paths.

应该怎么做：

• 确定哪些文件被跳过，以便您可以使用下面的步骤处理每个文件。该消息仅给出计数；~/.claude/debug/<session-id>.txt 中的调试日志在恢复运行时命名每个跳过的路径，因此在下次恢复之前使用 /debug 打开调试日志。在 macOS 或 Linux 上，您可以直接找到链接：find . -type l 用于符号链接，find . -type f -links +1 用于硬链接文件。
• 如果跳过的文件是您有意创建的链接，例如由点文件管理器管理的配置文件或由 pnpm 等工具硬链接的文件，rewind 保持其内容不变。要撤销会话对其所做的更改，请要求 Claude 反转编辑或自己编辑文件
• 如果您没有创建该链接，请在信任其内容之前检查该路径：某些内容在检查点后替换了该文件

No files were restored

当您使用 /rewind 恢复代码且无法恢复该检查点中的任何文件时，Claude Code 会显示此消息。对于每个文件，要么 Claude Code 在编辑前保存的备份丢失，要么 Claude Code 无法写入或删除该文件。

Failed to restore the code:
No files were restored: 1 file failed (backup missing, or the file could not be updated)

Claude Code 在 retention sweep 中删除会话的备份，默认情况下在会话最后一次保存后约 30 天。如果您在之后恢复会话，/rewind 仍会列出其检查点，但恢复到其中一个可能会因此错误而失败。如果消息还说 N paths were skipped for link safety，请参阅 Restored the code, but skipped files 了解这些路径。

当您分叉会话时，例如使用 --fork-session 或 /branch，Claude Code 会将原始会话的备份复制到分叉中。当 Claude Code 无法复制备份时，例如因为磁盘已满，该备份在分叉中丢失。恢复到需要它的检查点可能会因此错误而失败。

应该怎么做：

• 以另一种方式撤销更改：要求 Claude 反转其编辑，或从版本控制恢复文件。当备份消失时，再次运行 /rewind 会以相同方式失败。
• 如果 Claude Code 无法写入或删除文件，请修复阻止写入的内容，例如文件权限，然后再次运行 /rewind。
• 要在将来的会话中保留更长时间的备份，请提高 cleanupPeriodDays。

在 v2.1.260 之前，Claude Code 无声地跳过备份丢失的文件，恢复似乎成功了。

会话保存警告

当 Claude Code 未保存您的会话记录时，它会在输入框下方的持久行上显示这些警告。无论哪种方式，会话都会继续工作；这些警告告诉您该会话稍后可能在 --resume 中丢失。

记录写入失败

Claude Code 在您工作时将记录保存到磁盘，其对记录文件的写入失败。该消息会说明原因并显示底层错误代码，例如磁盘已满：

Transcript writes are failing (disk full — ENOSPC) · recent messages may not be saved for resume

警告在不同的时间点出现，具体取决于错误：

• 对于不会自行清除的条件，在首次失败时出现：磁盘已满、超过磁盘配额、文件系统为只读、路径超过文件系统长度限制，或在 macOS 和 Linux 上出现权限错误
• 对于所有其他情况，在至少跨越一分钟的重复失败后出现，包括 Windows 上的权限错误，其中防病毒扫描可能会导致单次写入失败，然后在重试时成功

在 v2.1.217 之前，Claude Code 会在没有警告的情况下丢弃失败的写入，稍后 --resume 缺少最近的消息是第一个迹象。

应该怎么做：

• 修复错误代码指出的条件：对于 ENOSPC 释放磁盘空间；对于 EDQUOT 提高或清除配额；对于 EACCES、EPERM 或 EROFS 恢复对记录位置的写入访问
• 警告会在下一次成功写入时自动清除；无需重启
• 在警告显示期间发送的消息稍后恢复会话时可能仍然丢失

因为设置了 CLAUDE\_CODE\_SKIP\_PROMPT\_HISTORY 所以记录保存已关闭

此会话启动时设置了 CLAUDE_CODE_SKIP_PROMPT_HISTORY，因此 Claude Code 不会为其写入任何记录或提示历史记录：

Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set · --resume will not find this session; if unintended, unset it and restart

该变量是针对临时脚本会话的有意选择退出，但它也可以通过 shell 配置文件、包装脚本或导出它的父进程到达会话。

应该怎么做：

• 如果您有意设置了该变量，无需采取任何操作；该通知确认该会话不会出现在 --resume、--continue 或向上箭头历史记录中
• 如果您没有，请从启动 claude 的 shell 或脚本中删除该变量，然后启动新会话。当前会话中的消息不会被追溯保存。

因为继承了 CLAUDE\_CODE\_CHILD\_SESSION 标记所以记录保存已关闭

Claude Code 在它生成的子进程中设置 CLAUDE_CODE_CHILD_SESSION，并将继承它的交互式会话视为嵌套的：Claude Code 不会为其保存任何记录，因此 Claude 本身启动的会话不会填充您的 --resume 列表。此通知意味着您的当前会话继承了该标记：

Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker · restart with CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 to keep future transcripts

当您从另一个 Claude Code 会话内部运行 claude 时，该通知是预期的；当标记通过长期存在的中介（例如终端、screen 会话或 Claude Code 会话最初启动的启动器）泄露时，它会发出误分类信号。

在 tmux 内，Claude Code 检测到通过 tmux 服务器全局环境到达的标记，并继续保存，因此在这种情况下不会出现此通知。

应该怎么做：

• 如果您有意从另一个 Claude Code 会话内部启动了此会话，无需采取任何操作
• 如果这是顶级会话，请退出并使用设置的 CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 重新启动。保存从重新启动时开始应用，因此在此之前发送的消息不会被保存。
• 要修复从同一终端或启动器的未来启动，请从其环境中删除 CLAUDE_CODE_CHILD_SESSION

配置警告

Claude Code 将大多数这些消息写入 stderr，而不是写入对话中，并在启动时写入大多数消息。当消息出现在其他地方（例如在调试日志中或作为对话视图中的启动通知）或在其他时间（例如请求时的无法识别的模型诊断行）时，条目会说明这一点。

全屏渲染器未能完成启动

此计算机上的上一个全屏会话在完成启动前退出，因此 Claude Code 在经典渲染器上启动此会话并打印以下通知之一：

Claude Code's fullscreen renderer didn't finish starting last time on this machine, so this launch is using the classic renderer. It will try fullscreen again next launch; /tui default keeps the classic renderer.

Claude Code's fullscreen renderer has repeatedly failed to start on this machine, so it has been turned off here. Run /tui fullscreen to try it again (this also resets after an update).

要做什么：

• 按照全屏渲染进行操作。它说明您获得哪个通知、Claude Code 在后续会话中执行的操作，以及如何再次尝试全屏或保持经典渲染器。
• 如果已退出的会话打印了退出消息，请参阅 Claude Code 在无法恢复的界面错误后退出了解其名称。

在 v2.1.236 之前，Claude Code 在启动失败后不打印通知，并继续在全屏渲染中启动会话。

Claude Code 在无法恢复的界面错误后退出

当 Claude Code 退出时会打印此消息，因为其终端界面遇到了无法恢复的错误，在任一渲染器中都可能发生。第二句仅在全屏渲染器启动时发生错误时出现：

Claude Code exited after an unrecoverable interface error (<error>). It happened while the fullscreen renderer was starting, so the next launch will use the classic renderer (CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 forces that any time).

要做什么：

• 再次启动 Claude Code。要继续该对话，请在同一目录中运行 claude --resume。
• 如果消息提到全屏渲染器，全屏渲染说明下一次启动执行的操作，这取决于您如何打开全屏，以及如何再次尝试全屏或保持经典渲染器。

在 v2.1.236 之前，Claude Code 在此类错误后退出而不打印消息。

Agent 描述超过 15.0k 令牌限制

Claude Code 将此警告显示为对话视图中的启动通知，而不是在 stderr 上。您的子代理（除了内置代理）的组合描述超过 15,000 个令牌，按 Claude Code 的估计。每个代理计算其名称加上其 description frontmatter。Claude Code 加载每个代理，无论总数是否超过限制，因此警告不会改变加载的内容。

Agent descriptions are over the 15.0k-token limit (~16.2k tokens) · ask Claude to trim agent descriptions in .claude/agents/

要做什么：

• 缩短您的代理文件的 description frontmatter，或要求 Claude 为您修剪它们。
• 删除您不再使用的代理文件。

工作区尚未被信任

Claude Code 在项目的 .claude/settings.json 或 .claude/settings.local.json 中找到了 permissions.allow 规则或 permissions.additionalDirectories 条目，但没有应用它们，因为项目设置中的允许规则需要工作区信任。计数、设置名称和消息中命名的文件因您的配置而异。deny 和 ask 规则不受影响。

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

要做什么：

• 在目录中运行 claude 并接受信任对话框。项目允许规则和工作区信任说明该接受涵盖哪个文件夹。
• 在非交互模式中使用 -p 时不显示对话框。使用消息打印的确切 projects 键在 ~/.claude.json 中设置 hasTrustDialogAccepted 条目。
• 如果消息提到 .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 仅在您接受信任对话框后才运行该检查，因此请使用第一步。您的主目录和任何其他配置主目录是豁免的，不需要等待对话框。请参阅项目允许规则和工作区信任。

工作目录是网络路径

Claude Code 不会将网络路径添加为工作目录。查找网络路径可能会联系它命名的主机，在 Windows 上该联系可能会向主机发送您的凭据，因此 Claude Code 拒绝该路径而不查找它。当您使用此类路径运行 /add-dir 时，或作为启动时的警告，您会看到此消息。当它在启动时出现时，Claude Code 启动时不包含该目录。

\\server\share is a network path, which cannot be added as a working directory. On Windows, map the share to a drive letter and pass it at launch with --add-dir (a drive letter added mid-session does not yet carry remote-read trust).

Claude Code 以这种方式拒绝的路径包括：

• UNC 共享，例如 \\server\share
• 自动挂载路径，例如 /net/<host>，除非您从该主机的自动挂载下的目录启动了 Claude Code
• 通过符号链接或连接到达网络位置的本地路径

映射的驱动器号和 \\wsl$ 路径不计为网络路径。

要做什么：

• 在 Windows 上，将共享映射到驱动器号，例如使用 net use Z: \\server\share，并在启动时使用 claude --add-dir Z:\ 传递驱动器。
• 在 macOS 或 Linux 上，将共享挂载到本地路径并改为添加该路径。
• 如果路径在 permissions.additionalDirectories 中，请从列出它的设置文件中删除它。

在 v2.1.257 之前，Claude Code 接受可达的网络路径作为工作目录。

远程托管设置加载失败

您的会话符合服务器托管设置的条件，但 Claude Code 无法获取它们，因此在交互式会话中显示此警告。括号中的原因命名失败的内容，例如 network error、request timed out 或 authentication rejected (401)，行的其余部分说明会话运行的策略：

• 从较早的成功获取缓存的设置：Claude Code 在该缓存策略上运行会话，除了扣留的环境变量，该行读作 using cached policy。
• 无缓存：Claude Code 在没有服务器托管设置的情况下运行会话，该行读作 no remote policy applied。

要做什么：

• 对消息命名的原因采取行动：对于网络原因，检查此计算机是否可以到达 api.anthropic.com；对于身份验证原因，使用 /status 检查您的登录
• 运行 /status 或 claude doctor 以获取完整诊断

在 v2.1.248 之前，Claude Code 仅在调试日志中报告失败的设置获取。

托管设置未被批准

您的组织的服务器托管设置包括需要您批准的设置，而您拒绝了安全批准对话框，因此 Claude Code 退出而不应用它们：

Managed settings were not approved; exiting without applying them.

要做什么：

• 再次启动 Claude Code 并批准对话框以在您的组织设置下继续。拒绝的对话框不被记住，因此在下一次启动时再次出现。
• 如果您对对话框列出的设置不确定，在批准前询问维护您的组织托管设置的人

MCP 服务器被企业托管策略阻止

您在 /mcp 中的服务器上选择了重新连接，或在那里重新打开了禁用的服务器，而限制 MCP 服务器的设置阻止了该服务器。Claude Code 拒绝连接它并显示：

MCP server <name> is blocked by enterprise managed policy

以下任何设置都可能产生该消息：

• 与服务器匹配的 deniedMcpServers 条目，包括您自己的 ~/.claude/settings.json 或项目的 .claude/settings.json 中的条目
• 服务器不匹配的 allowedMcpServers 列表
• strictPluginOnlyCustomization 且 mcp 被锁定，这阻止了在 ~/.claude.json 和 .mcp.json 中配置的服务器
• disableClaudeAiConnectors，当服务器是 claude.ai 连接器时

要做什么：

• 检查您自己的用户和项目设置文件中的这些设置之一，并更改或删除它
• 如果您自己的设置都不能解释该阻止，请询问您的管理员哪个托管设置阻止了该服务器

在 v2.1.257 之前，/mcp 中的重新连接和重新启用可能会连接一个中途策略更新阻止的服务器。

托管设置文档无法解析

您的组织部署了托管设置，其中一个部署的文档存在但无法解析为 JSON 对象，因此 Claude Code 在启动时以代码 1 退出，而不是在没有文档携带的策略的情况下运行。该行在消息前命名失败的源：

/Library/Application Support/ClaudeCode/managed-settings.json: Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.

源是以下之一：

• managed-settings.json 文件的路径或 managed-settings.d 下的放入文件
• macOS 托管首选项配置文件、per-user managed preferences 或 device-level managed preferences
• Windows 注册表值、Registry: HKLM\SOFTWARE\Policies\ClaudeCode\Settings

查找 Claude Code 删除的条目列出了使每个源无法解析的原因。

Claude Code 拒绝启动，即使另一个管理员源提供了有效的策略。您在交互式会话、claude -p、Agent SDK 会话、后台会话和大多数子命令（包括 claude doctor）中看到此错误。拒绝故意失败关闭：Claude Code 无法解析的文档中的设置无法被强制执行，启动时不应用组织的控制会运行会话。

可解析文档中的架构问题不会产生此错误。查找 Claude Code 删除的条目涵盖 Claude Code 对其所做的操作。

当 managed-settings.d/ 目录存在但无法列出时，Claude Code 报告 Managed settings drop-in directory could not be read: 后跟基础错误。查找 Claude Code 删除的条目涵盖读取失败在启动时退出的情况。

要做什么：

• 如果您管理计算机，修复命名的文档使其解析为 JSON 对象，或删除文件、配置文件或注册表值。空的 managed-settings.json 计为 {} 并不阻止启动。
• 如果您不管理，请要求您的管理员修复部署的文档。您自己的设置文件中的任何内容都不会导致或清除此错误。

otelHeadersHelper 失败

当 otelHeadersHelper 脚本失败或打印不符合脚本要求的输出时，Claude Code 在交互式会话中显示此警告作为终端界面中的通知，每个会话一次。

当脚本继续失败时，导出失败，您的遥测后端从会话中接收不到任何内容。

See /status: 后的文本说明失败的内容，例如脚本的退出代码后跟其错误输出：

otelHeadersHelper failed; telemetry is not being exported. See /status: exited 1: token service unreachable

要做什么：

• 运行 /status 以读取失败详情。
• 修复脚本使其在 30 秒内退出 0 并在 stdout 上打印字符串标头值的 JSON 对象。请参阅脚本要求。
• 如果您的组织通过托管设置部署脚本，请要求维护它们的人修复它。

在非交互模式中使用 -p 时，相同的失败在 stderr 上显示为 otelHeadersHelper failed (OpenTelemetry export headers unavailable): <error>。

headersHelper 未运行

Claude Code 仅使用 MCP 服务器的静态 headers 连接了它，并跳过了服务器的 headersHelper，因为助手是 shell 命令，文件夹没有保存的信任。当您手动在 ~/.claude.json 中设置其条目时，或在主目录外，当您在交互式会话中为其接受信任对话框时，文件夹获得保存的信任。请参阅在 headersHelper 运行前信任文件夹了解此检查适用于哪些服务器。

Claude Code 仅在非交互模式中写入此行，每个服务器一次。在交互式会话中，它将相同的拒绝写入调试日志。

MCP server 'internal-api': headersHelper not run — this workspace has no persisted trust; accept the trust dialog here once interactively, or set projects["/Users/you/project"].hasTrustDialogAccepted in /Users/you/.claude.json.

消息打印的 projects 键是文件夹项目允许规则和工作区信任说明 Claude Code 在其上键入信任的。为父文件夹接受信任对话框不满足检查，-p 或 SDK 会话也不满足。

要做什么：

• 在消息命名的文件夹中运行 claude，接受信任对话框，然后再次运行您的 -p 或 SDK 命令
• 自己在 ~/.claude.json 中设置 hasTrustDialogAccepted 条目，使用消息打印的确切 projects 键
• 如果您在主目录中启动了会话，请从您已信任的项目目录工作。当您在主目录中接受信任对话框时，Claude Code 仅为当前会话保持该信任。

格式错误的 Tool(content) 规则

您的一个设置文件中的权限规则没有 Tool 或 Tool(content) 的形状，例如因为文本跟在右括号后或其中一个括号缺失。Claude Code 跳过该规则，并在交互式会话启动时在无效设置对话框中列出它，以及在 claude doctor 输出中：

Invalid permission rule "Bash(ls) x" was skipped: Malformed Tool(content) rule. Rules take the form Tool or Tool(content) and must end at the closing ")"; parentheses inside the content are literal

要做什么：

• 在消息列出的设置文件中，重写规则使其在其右括号处结束，例如用 Bash(ls *) 代替 Bash(ls) x
• 将内容内的括号保留原样。它们是字面的，因此诸如 Edit(./Finance (2024)/**) 之类的规则在不转义的情况下是有效的

在 v2.1.260 之前，Claude Code 将具有不匹配括号的规则报告为 Mismatched parentheses。

不被文件权限检查匹配

Claude Code 在您的设置文件、托管设置或 --allowedTools、--disallowedTools 或 --settings 标志值中找到了带有路径的 Write、NotebookEdit、MultiEdit 或 Glob权限规则。它仅针对 Edit 和 Read 规则检查文件权限，因此它从不查询命名其他文件工具之一的路径规则。它保留规则并不改变其他任何内容；警告命名规则、其在括号中的源和要写入的替换：

Permission deny rule (.claude/settings.json): Write(docs/**) is not matched by file permission checks — only Edit(path) rules are. Use Edit(docs/**) instead (Edit rules cover all file-editing tools).

要做什么：

• 将 Write(path)、NotebookEdit(path) 和旧版 MultiEdit(path) 规则替换为 Edit(path)。Edit 规则涵盖所有文件编辑工具。
• 除了在 --allowedTools 中，Claude Code 接受 Glob 规则而不警告，将 Glob(path) 规则替换为 Read(path)。
• 在警告在括号中命名的源处修复规则：设置文件路径，或 --allowed-tools 和 --disallowed-tools 的标志本身。不存在于磁盘上的 claude-settings-<hash>.json 路径代表内联 --settings 值。修复您传递给该标志的 JSON。
• 将裸工具名称规则（例如 Write 或 Glob）保留原样。Claude Code 在工具级别匹配它们，不对它们警告。
• 如果源读作 managed policy settings，将警告转发给维护您的托管设置的人，因为您无法自己清除它。

在后台会话中或使用 --output-format json 或 stream-json 时，Claude Code 将警告写入调试日志而不是 stderr，因此机器读取的输出保持干净。使用 --debug 运行以在 ~/.claude/debug/<session-id>.txt 处捕获它。在 v2.1.210 之前，Claude Code 接受这些规则而不警告。

在命令的其余部分之前有通配符

Claude Code 在您的设置文件、托管设置或 --allowedTools 或 --settings 标志值中找到了一个 Bash 允许规则，其 * 在确定它是哪个命令的后续单词之前，例如 Bash(git * main) 或 Bash(git -C * status *)。* 匹配任何文本，包括在该位置插入的选项：Bash(git * main) 也批准 git -c core.fsmonitor=<script> diff main，其中 -c 使 git 运行命令命名的程序。通配符模式显示匹配规则。

警告存在是为了让您可以缩小通配符比您打算的更宽的规则。Claude Code 保留规则并不改变它的匹配方式；警告命名规则及其在括号中的源：

Permission allow rule (.claude/settings.json): Bash(git -C * status *) has a wildcard before the rest of the command, so it also matches any options inserted at that position and approves them without a prompt. For git, options such as -c and --exec-path can run arbitrary commands. Replace that * with the exact value you mean, or only use * after the subcommand (for example Bash(git status *)).

要做什么：

• 将子命令前的 * 替换为您的确切值：用 Bash(git checkout main) 代替 Bash(git * main)。
• 将每个 * 移到子命令后：用 Bash(git status *) 代替 Bash(git -C * status *)。为您想允许的每个子命令写一个规则。
• 在警告在括号中命名的源处修复规则：设置文件路径或 --allowed-tools 标志本身。不存在于磁盘上的 claude-settings-<hash>.json 路径代表内联 --settings 值。修复您传递给该标志的 JSON。
• 如果源读作 managed policy settings，将警告转发给维护您的托管设置的人，因为您无法自己清除它。

Claude Code 不对具有相同形状的拒绝和询问规则警告：它拒绝或提示它们匹配的额外命令，而不是批准它们。它也不对子命令在第一个 * 之前的规则警告，例如 Bash(git commit *)，或规则中除了选项外没有其他单词跟在 * 后的规则，例如 Bash(git *)，或关于 :* 前缀规则，例如 Bash(git:*)。

在后台会话中或使用 --output-format json 或 stream-json 时，Claude Code 将警告写入调试日志而不是 stderr，因此机器读取的输出保持干净。使用 --debug 运行以在 ~/.claude/debug/<session-id>.txt 处捕获它。在 v2.1.246 之前，Claude Code 接受这些规则而不警告。

crossSessionInbound 必须是 accept、hold、refuse 之一

设置文件将 crossSessionInbound 设置为 Claude Code 不识别的值，例如拼写错误 "reject"。警告的第二句取决于哪个文件保存该值；在用户、项目、本地或 --settings 文件中，它读作：

"crossSessionInbound" must be one of "accept", "hold", "refuse"; received "reject". This value was ignored; while it is present, cross-session messages are held for your approval instead of being delivered. Set it to one of the values above.

在托管设置中，Claude Code 将无法识别的值视为 refuse（最严格的值），警告说跨会话消息被拒绝，直到管理员修复它。有关保留如何与您的其他设置文件中的值结合，请参阅 crossSessionInbound。

要做什么：

• 将键设置为 "accept"、"hold" 或 "refuse"，或删除它
• 当警告命名托管设置时，要求管理员修复该值

在 v2.1.248 之前，Claude Code 忽略无法识别的值而不警告。

200K 限制未被强制执行

您设置了 CLAUDE_CODE_DISABLE_1M_CONTEXT=1，这通常使自动压缩将 1M 上下文模型上的会话保持在 200K 窗口，但没有压缩阈值将此会话限制在或低于 200K，因此对话可以超过它。

CLAUDE_CODE_DISABLE_1M_CONTEXT is set, but the 200K limit isn't enforced for <model>, so this session can grow past it. To enforce it, set CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 (or the autoCompactWindow setting).

Claude Code 为它识别为具有本地 1M 窗口的每个模型自己强制执行 200K 限制，对于它不识别的模型 ID，它在它假设的窗口处压缩。当其他配置击败该强制执行时出现警告：

• 模型 ID 不是 Claude Code 识别的，例如LLM 网关别名，并且您设置了 CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 或使用 CLAUDE_CODE_MAX_CONTEXT_TOKENS 将假设的窗口提高到 200K 以上。在这种情况下，消息也提供 or update to a Claude Code version that recognizes <model> 作为补救。
• 通过 ANTHROPIC_BETAS 或 --betas 标志请求的 context-1m 测试版仍然在接受该测试版的模型上向 API 请求 1M 窗口，而没有任何东西在 200K 处压缩会话

要做什么：

• 设置 CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 或 autoCompactWindow 设置为 200000，以便自动压缩在 200K 边界处压缩
• 如果消息命名此版本不识别的模型 ID，运行 claude update。识别 ID 为 1M 上下文模型的版本在没有进一步配置的情况下强制执行限制。
• 如果您希望会话使用模型的完整窗口，请取消设置 CLAUDE_CODE_DISABLE_1M_CONTEXT；警告仅报告 200K 限制未被强制执行

在后台会话中或使用 --output-format json 或 stream-json 时，Claude Code 将警告写入调试日志而不是 stderr。

请求上无法识别的模型 ID

Claude Code 为您的 Claude Code 版本不识别的模型 ID 发送了请求，并找不到将该 ID 映射到它识别的模型的 modelOverrides 条目。Claude Code 仍然使用您配置的 ID 发送请求，不退出或切换模型。

[claude-code:unrecognized_model] {"model":"my-proxy-model","query_source":"sdk"}

在读取 stderr 的脚本或工具中，匹配 [claude-code:unrecognized_model] 前缀。在前缀和一个空格之后，Claude Code 写入一行 JSON 对象。Claude Code 可能在后续版本中向其添加字段，因此忽略您不期望的任何字段。它至少写入这两个：

• model：您配置的模型字符串
• query_source：使用模型的请求路径。Claude Code 为 -p 运行报告 sdk，为子代理报告以 agent: 开头的值。

Claude Code 根据您运行它的方式将行写入两个位置之一：

• 在非交互模式中使用 -p 时，Claude Code 在每个 --output-format 下将其写入 stderr，因此您可以解析 stdout 而不过滤该行
• 在交互式会话或后台会话中，Claude Code 将其写入调试日志；使用 --debug 运行以在 ~/.claude/debug/<session-id>.txt 处捕获它

Claude Code 每个模型字符串每个进程写入该行一次。它为每个进一步的无法识别的 ID 写入单独的行，例如子代理或后台功能使用的 ID。

Claude Code 不为它解析为它识别的模型的提供商 ID 写入该行，例如 Amazon Bedrock us.anthropic.claude-... ID、Google Cloud 的 Agent Platform ID 带有 @ 版本后缀，以及包含 Claude 模型 ID 的 Microsoft Foundry 部署名称。Claude Code 检查 Amazon Bedrock 应用推理配置文件 ARN 后面的模型，而不是 ARN 本身。它为无法解析的 ARN（例如拼写错误的 ARN）不写入行。

要做什么：

• 如果您故意设置了 ID，例如LLM 网关别名，请向您的设置文件添加 modelOverrides 条目，以 ID 作为其值。使用 Anthropic 模型 ID 作为键，而不是家族别名，例如 opus。对于示例行中的 my-proxy-model，添加此条目：

  {
    "modelOverrides": {
      "claude-opus-4-6": "my-proxy-model"
    }
  }
  

  Claude Code 然后将 my-proxy-model 视为 claude-opus-4-6 并停止写入该行。

• 如果 ID 命名比您的 Claude Code 版本更新的模型，运行 claude update

• 如果 ID 是拼写错误，在您可以设置模型或别名变量的地方之一修复它。如果 query_source 以 agent: 开头，改为在您设置子代理模型的地方修复它。

在 v2.1.233 之前，Claude Code 在为它不识别的模型 ID 发送请求时不写入行。

被杀死的会话留下的陈旧沙箱掩码文件

claude doctor 在其诊断中打印此警告，/status 列出相同的行。当沙箱在文件系统隔离打开的情况下启用时，它在 Linux 和 WSL2 上出现。

当沙箱命令运行时，沙箱通过在那里创建 0 字节只读占位符来保持对尚不存在的文件的写入拒绝，并在之后删除它。在该清理运行前被杀死的会话（例如通过 SIGKILL）留下占位符。后续会话在每次启动时再次只读绑定它们，因此设置写入（例如保存"是，不要再问"）在其中一个所在的地方失败。

- Stale sandbox mask files left by a killed session: /home/you/project/.claude/settings.local.json
  Fix: Remove each with `rm <path>` while no other Claude Code session is running in that project — a 0-byte read-only file where a settings file belongs makes "Yes, and don't ask again" fail to save, and the sandbox binds it read-only again on every start

要做什么：

• 退出在该项目中运行的任何其他 Claude Code 会话，然后使用 rm 删除每个列出的文件。警告列出最多三个文件并计数其余的，因此在删除后重新运行 claude doctor 直到警告不再出现。另一个会话的沙箱仍在使用的占位符是该会话写入保护的活跃部分
• 如果您使用"是，不要再问"保存的权限选择没有坚持，在删除占位符后再次保存它

在 v2.1.257 之前，claude doctor 没有标记这些文件；早期版本在会话被杀死时留下相同的占位符。

回复质量似乎低于预期

如果 Claude 的回答似乎不如你预期的那样有能力，但没有显示错误，原因通常是对话状态而不是模型本身。Claude Code 不会无声地更改模型版本。它只能在三种特定情况下切换到备用模型：

• 配置的 --fallback-model 在可用性错误后接管该轮，并在记录中显示通知
• Amazon Bedrock 或 Google Cloud 的 Agent Platform 启动检查发现你的默认模型不可用
• 自动模型备用 在 Fable 5.1、Fable 5、Opus 5.5 和 Opus 5 上，当该类别有备用模型时，将会话移动到标记类别的备用模型，并在记录中显示通知

下面的模型选择检查捕获第二和第三种情况；第一种情况显示为记录通知而不是 /model 更改。模型配置 解释了每个备用何时适用。

首先检查这些：

• 模型选择：运行 /model 以确认你在预期的模型上。之前的 /model 选择或 ANTHROPIC_MODEL 环境变量可能使你在比预期更小的模型上。
• 努力级别：运行 /effort 以检查当前推理级别，并为困难的调试或设计工作提高它。默认值因模型而异，所以在假设你低于最大值之前请检查。有关每个模型的默认值和 ultrathink 快捷方式，请参阅调整努力级别。
• 上下文压力：运行 /context 以查看窗口有多满。如果接近容量，在自然断点处运行 /compact 或运行 /clear 以重新开始。有关 auto-compact 如何影响早期轮次的信息，请参阅探索上下文窗口。
• 过时的指令：大型或过时的 CLAUDE.md 文件和 MCP 工具定义会消耗上下文并可能引导回复。/doctor 检查会标记超大内存文件和未使用的扩展，/context 显示 MCP 工具令牌使用情况。在 v2.1.205 之前，/doctor 打开一个诊断屏幕，标记超大内存文件和子代理定义。

当回复出错时，回退通常比用更正回复效果更好。按 Esc 两次或运行 /rewind 以回到坏轮之前，然后用更多细节重新表述提示。在线程中更正会将错误的尝试保留在上下文中，这可能会将后来的答案锚定到它。请参阅检查点。

如果在检查上述内容后质量仍然似乎有问题，运行 /feedback 并描述你期望的内容与你得到的内容。以这种方式提交的反馈包括对话记录，这是 Anthropic 诊断真实回归的最快方式。如果 /feedback 在你的环境中不可用，请参阅报告错误。

如果 Claude 警告可疑的提示注入，或因可疑注入而拒绝请求，并且警告命名的文本是 Claude Code 自动添加到对话中的上下文而不是文件或网络内容，运行 claude update 并重试。如果更新后警告重复出现，报告它而不是将标记的内容粘贴回提示中。在 v2.1.201 之前，Sonnet 5 以相同的方式拒绝了一些请求。

报告错误

对于此页面未涵盖的组件错误，请参阅相关指南：

• MCP 服务器连接或身份验证失败：MCP
• Hook 脚本失败或阻止了工具：调试 hooks
• 安装期间权限被拒绝或文件系统错误：排查安装和登录问题

如果此处未列出错误或建议的修复方法无法帮助：

• 在 Claude Code 中运行 /feedback 将记录和描述发送给 Anthropic。该命令还提供打开预填充的 GitHub issue 的选项。发送到 Anthropic 需要身份验证。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和其他第三方提供商上，或者当未配置 Anthropic 凭证时，/feedback 会保存一个本地存档，您可以将其发送给您的 Anthropic 账户代表。
• 从您的 shell 中运行 claude doctor 以获取安装的只读诊断，或在 Claude Code 中运行 /doctor 检查以查找和修复设置问题
• 检查 status.claude.com 以了解活跃的事件
• 在 GitHub 上搜索现有问题