目录
你正在用 Claude Code 干活，它突然报错停下——“重新登录”“速率限制”“prompt 太长”“MCP 连不上”。错误种类繁多，每遇到一个都去搜一次实在麻烦。本文是一份把 Claude Code 中常见的错误连同原因和“该敲的命令”一起整理出来的实用参考手册。
先说结论：对大多数错误，先敲 claude doctor（全面诊断）、/status（当前认证状态）、/context（上下文明细）这三个，就能把原因范围缩小。而最常见的错误聚成四大类：① 用量/速率限制、② 上下文溢出、③ 认证过期、④ MCP 连接失败。下面按类别以“症状 → 原因 → 对策命令”的方式整理。把它收藏起来，卡住时直接跳到相应小节。
拿不准时，就这 3 个命令
— 大多数错误都从切分原因开始
四大类：① 用量/速率限制 ② 上下文溢出 ③ 认证过期 ④ MCP 连接失败。
还有不起眼的一招，“更新到最新版” claude update 能解决不少 bug。
* 本文的命令与对策基于 Claude Code 官方文档（截至 2026 年）。Claude Code 更新很快，命令名和提示文案可能会变。请用 claude doctor 和官方文档确认最新情况。
1. 卡住时最先敲的“诊断命令”
在钻进具体错误之前，先了解能帮你切分原因的诊断命令，多数问题都能快速定位。
| 命令 | 显示/作用 |
|---|---|
claude doctor | 全面检查安装、设置、MCP 服务器、上下文使用情况 |
/status | 当前生效的认证方式（Pro / Max / Team / API key） |
/context | 上下文明细（system prompt、历史记录、文件、MCP 工具） |
/usage | 当前套餐的额度和重置时间 |
/permissions | 权限规则列表（allow/deny）及其来源 |
/mcp | MCP 服务器连接状态和暴露的工具数量 |
/feedback | 连同对话日志向 Anthropic 报告 bug |
2. 认证与登录
这类是“本来好好的，突然要我登录”的家族。经典陷阱是环境变量里的 API key 覆盖了你的订阅。
| 症状 | 原因 | 对策 |
|---|---|---|
| Not logged in · Please run /login | 本会话没有可用的凭证（保存的登录无法续期时，显示的是 Login expired · Please run /login） | /login。若反复出现，检查系统时钟和 Keychain 是否被锁 |
| Invalid API key · Fix external API key | 来自 ANTHROPIC_API_KEY 或 apiKeyHelper 的密钥被 API 拒绝（常见于残留的旧密钥） | env | grep ANTHROPIC → unset ANTHROPIC_API_KEY → /login |
| OAuth token revoked · Please run /login Please run /login · API Error: 401 OAuth token has expired ... | 在所有设备上登出 / 管理员移除了访问权限（revoked）、自动刷新失败（expired） | /login。同一会话内再次出现就 /logout → /login。每次启动都出现则怀疑时钟偏差 |
| Your ANTHROPIC_API_KEY belongs to a disabled organization · … API Error: 400 ... This organization has been disabled. | 正在使用已停用组织的旧 ANTHROPIC_API_KEY。没有设置环境变量也出现时，被停用的是 /login 那一侧的组织 | 从 shell 配置文件（.zshrc 等）中移除该 key → /login → 用 /status 确认。没有环境变量时，联系支持团队或改用其他账号登录 |
| 403 Forbidden (after login) | 订阅过期 / 缺少角色 / 代理干扰 | 检查订阅和 Console 角色。代理场景设置 HTTPS_PROXY |
经验法则：环境变量里的 API key 优先于订阅登录。如果你为某个 CI 任务设了 ANTHROPIC_API_KEY 又忘了，你个人的 Pro/Max 套餐就会被忽略。先用 /status 确认“当前生效的是哪个凭证”才是正解。想深入了解认证与登录的修复（ANTHROPIC_API_KEY 覆盖、令牌失效、Keychain 等），请看 认证与登录错误的原因与对策。
3. 用量与速率限制（最常见）
Claude Code 最常见的抱怨。根据官方成本管理文档（Manage costs effectively），Claude Code 的每一轮都会带上文件内容、工具调用和多步推理，所以一次调试就可能超过一整天聊天的用量。因此你会比感觉中更快撞上限制。
“撞上限制”时的 3 步
/usage 看额度和重置时间，/status 看凭证/model 换更轻的模型，/compact 压缩历史，禁用没用的 MCP
注意：“Server is temporarily limiting requests”是短暂的服务器侧限流，不是你的套餐额度。等一下再重试即可。
别和套餐额度（会话/每周）搞混。
更多：“API Error: Request rejected (429)”表示触及了你的 API key（或 Amazon Bedrock/Google Cloud 项目）设定的速率限制；如果你本想用订阅，请用 /status 检查是否混入了 ANTHROPIC_API_KEY。“Credit balance is too low”表示 Console 预付余额耗尽，或本想用订阅、请求却走了 Console 的 API key（充值，或在 /status 中确认该 key 并移除）。要注意的是，2026 年 3 月，Pro 和 Max 用户纷纷抱怨 Claude Code 的额度耗尽得比预期快得多，Anthropic 也承认正在将其作为最优先事项调查（The Register，2026 年 3 月 31 日）。若反复出现，请更新到最新版本，用 /usage 测量，必要时 /feedback 反馈。系统性地省 token，参见 AI 省 token 和 Claude Code 省 token。关于 “usage limit reached” 的机制（5 小时窗口与每周窗口）以及触顶后的应对，详见 usage limit reached 原因与对策专文。
4. 上下文与 token
处理冗长的会话或巨大的文件时会出现。
| 症状 | 原因 | 对策 |
|---|---|---|
| Prompt is too long | 对话 + 文件超出了上下文窗口 | /compact（汇总）、/clear（重置）、/context 看明细，用 /mcp 禁用没用的 MCP |
| Error during compaction: Conversation too long | 压缩输出的剩余空间不足 | 按两次 Esc 回退几轮，再 /compact。仍卡住就 /clear |
| Autocompact is thrashing | 压缩刚结束，一个巨大的输出又把上下文填满 | 按行范围读大文件 / /compact keep only <focus> / 移交给子 agent |
诀窍是绝不整文件读取大文件。日志和数据要按小的行范围分块传入。理解 上下文窗口 的概念，能让这一类错误大幅减少。关于 Prompt is too long 报错 的详细成因与对策（200K 与 1M 窗口、善用子智能体），请看专门的文章。
5. 服务器与模型
| 症状 | 原因 | 对策 |
|---|---|---|
| 500 Internal server error | Anthropic 侧的临时故障 | 查看 status.claude.com → 1 分钟后重试 |
| 529 Overloaded (repeated) | API 临时满载 | 等几分钟。用 /model 换模型以分散负载 |
| Request timed out | 在 10 分钟默认时限内无响应 | 拆分任务。线路慢就调高 API_TIMEOUT_MS |
| There's an issue with the selected model / Model '…' not found | 模型名错误或不在你的套餐内 | /model 重新选择。检查残留的 ANTHROPIC_MODEL 环境变量 |
| Claude Opus is not available with the Claude Pro plan | 所选模型不在你的套餐内 | /model 换一个可用的。变更套餐后，/logout→/login |
关于 529 Overloaded / 500 为何属于服务器侧问题、不会消耗你的额度，以及自动重试（最多 10 次）的机制和与 429 的区别，详见 529 Overloaded / 500 的原因与对策。
6. 安装、PATH 与更新
| 症状 | 原因 | 对策 |
|---|---|---|
| command not found: claude | 安装目录不在 PATH 上 | 把 ~/.local/bin（Win：%USERPROFILE%\.local\bin）加入 PATH |
| Install fails (HTML error, etc.) | 代理 / 地区封锁 | Homebrew brew install --cask claude-code / WinGet winget install Anthropic.ClaudeCode |
| TLS / SSL certificate verification failed | 企业代理的 TLS 检查 / 缺少 CA | 指向 NODE_EXTRA_CA_CERTS=/path/ca.pem。绝不要设置 NODE_TLS_REJECT_UNAUTHORIZED=0 |
| 装了多个 Claude Code（版本不一致、行为异常） | native、npm、Homebrew、WinGet 等重复安装 | 用 which -a claude（Windows 用 where.exe claude）检查后只保留一个，推荐 native 安装的 ~/.local/bin/claude。例如 npm uninstall -g @anthropic-ai/claude-code |
| Bugs from an old version | 没更新 | claude update（能解决许多 bug 的首选对策） |
| 桌面版提示“无法打开这个应用” | 更新时 MSIX 包只注册了一半（Windows） | 先结束后台进程，再到设置里执行“修复”。详解 |
command not found: claude 的成因（PATH、多重安装冲突、npm 权限、Windows 用错 shell 的陷阱）与解决办法，详见 “command not found” 安装与 PATH 错误的排查与修复。
7. 网络与代理
在企业网络和 VPN 上常见。先用 curl -I https://api.anthropic.com 确认可达性。
| 症状 | 原因 | 对策 |
|---|---|---|
| Unable to connect to API / Connection refused … (ECONNREFUSED) | 离线 / VPN 封锁 / 未设代理 | 设置 HTTPS_PROXY=http://proxy:8080。请 IT 放行 api.anthropic.com |
| SSL certificate verification failed (corporate) | 自签名的拦截证书 | 从 IT 拿到 CA 包并设置 NODE_EXTRA_CA_CERTS |
| 403 host_not_allowed (cloud runs) | 在云环境的白名单之外 | 把网络访问设为 Custom 并放行目标域名 |
| Connection lost mid-response（v2.1.227 之前显示为 Connection closed mid-response） | 已连上、流也开始传输之后连接才被切断 | 已输出内容会保留，回复 continue 即可。反复出现就查 claude --version 并升级 |
关于 proxy 配置、TLS 证书（NODE_EXTRA_CA_CERTS）、allowlist 域名，以及 NODE_TLS_REJECT_UNAUTHORIZED=0 为何危险的深入讲解，详见 连接与代理错误的成因与排查。 Connection lost mid-response（旧称 Connection closed mid-response） 则是“已经送达之后”的另一类问题，回答中途被切断的原因与对策 一文整理了排查步骤与各版本的修复情况。
8. MCP（连接的服务器）
当你开始使用 MCP 服务器后就会遇到这些。先用 /mcp 查看状态。
| 症状 | 原因 | 对策 |
|---|---|---|
| Server failed to connect / Pending approval | 服务器崩溃 / 不可达 / 需要认证 | /mcp 看状态。stdio：检查命令是否存在且可执行；HTTP：检查 URL/认证头 |
| Tool not found | 已连接但没暴露工具 / 名称错误 | /mcp 确认工具数量，claude mcp get <name> 查健康状态 |
| Reconnection attempts exhausted | HTTP/SSE 服务器在 5 次重试后仍宕机 | 确认服务器在运行，在 /mcp 中手动重连。stdio 则重启 claude |
| MCP server timeout | 启动未能在 MCP_TIMEOUT（默认 30 秒）内完成 | 用毫秒调大，例如 MCP_TIMEOUT=60000 claude。.mcp.json 里的 "timeout" 是每次工具执行的上限，不是启动等待时间 |
关于 MCP 连接按 failed、needs authentication、pending 各状态的详细排查（包括在 Windows 上用 cmd /c 包裹 npx 等），请参阅 如何修复 MCP 连接错误。
9. 权限与工具
这类是“连 bypass 模式下都来问权限”的家族。要点有两个：官方文档列出了在 bypass 模式下仍会询问的操作，以及deny 规则在包括 bypass 在内的所有模式下都会阻止执行（allow 规则在 bypass 下不起作用；见官方文档 Choose a permission mode）。
| 症状 | 原因 | 对策 |
|---|---|---|
| Asked for permission even in bypass mode | 明确的 ask 规则、AskUserQuestion 等需要用户操作的工具，以及对根目录、主目录、工作目录等关键路径执行的 rm/rmdir（官方称之为 circuit breaker 的安全装置），在 bypass 下仍会询问。写入 .git、.claude 等受保护路径在 bypass 下不会询问 | 在 /permissions 中检查并调整 ask 规则。deny 规则会直接阻止，不会询问 |
| Tool execution denied by PreToolUse hook | 某个 hook 以退出码 2 阻止了它 | 检查 .claude/settings.json 里的 hook。用 claude --debug 看输出 |
关于为何 bypass 仍会停下，参见 为何 bypass 模式下仍会询问权限；关于安全的权限设计，参见 权限模式与安全。
10. 其他（thinking / 图片-PDF / IDE）
- thinking blocks cannot be modified (400)：一个已知 bug，扩展思考块在历史中损坏。按两次 Esc → /rewind，否则开新会话，并
claude update。详情：thinking blocks 400 错误。 - court / 显示原始 <invoke> 标签且工具不执行：一个已知 bug，工具调用的控制标签生成时损坏。失败两次就开新会话(/clear)。详情：court / invoke 标签泄漏错误解析。
- Could not check the pull request status：GitHub 连接问题（常见是
gh认证）。先从gh auth status开始。详情：PR 状态错误。 - Image was too large / PDF too large：长边超过 8000px（上下文中图片很多时为 2000px）的图片、超过 100 页 / 20 MB 的 PDF 会被拒。按两次 Esc 移除附件；缩放或按行范围读取。大文件用路径引用，而不是粘贴。
- VS Code extension won't connect：确认在 VS Code 终端里
claude --version能跑。检查 PATH、重启 VS Code、重装扩展。
11. 错误 → 对策速查表
| 当出现这种情况 | 先试这个 |
|---|---|
| 原因不明 / 通用 | claude doctor → /status → /context |
| 突然被要求登录 | /status →（若有残留 key）unset ANTHROPIC_API_KEY → /login |
| 撞上速率限制 | /usage → /model 换轻的 → /compact → 等待 |
| Prompt is too long | /compact → /clear → 按行范围读大文件 |
| 500/529/超时 | 查看 status.claude.com → 稍等 → /model |
| command not found: claude | 把 ~/.local/bin 加入 PATH |
| 连不上（企业网络） | curl -I https://api.anthropic.com → HTTPS_PROXY/NODE_EXTRA_CA_CERTS |
| MCP 连不上 | /mcp → 检查 URL/权限/命令 → MCP_TIMEOUT |
| 连 bypass 下也被询问 | /permissions 检查 ask 规则（删除关键路径在 bypass 下也会询问） |
| 只想把它修好 | claude update（最新版能解决很多问题） |
总结
Claude Code 的错误很多，但第一步是用三个命令切分原因：claude doctor / /status / /context——这能让大多数问题重新动起来。常见的是四大类——用量/速率限制、上下文溢出、认证过期、MCP 连接失败——而 /usage、/compact、/login、/mcp 是第一线的对策。
而最容易被忽视的最强一招，是用 claude update 保持最新。Claude Code 更新很快，过去的 bug（比如 thinking-blocks 400）常常只要升一下版本就消失了。“卡住时先来三个诊断命令；若没修好，就更新到最新版。”守住这个套路，你就不会再把时间耗在错误里。
如果困扰你的不是报错，而是它的行为太“重”或太慢，那么重新审视 Claude Code 的工数（effort）设置 可以帮你调节思考深度与 token 消耗之间的平衡。延伸阅读：thinking blocks 400 错误、PR 状态检查错误、Claude Code 省 token、为何 bypass 模式下仍会询问权限、什么是 MCP，以及 The model returned no content 的原因与对策。
FAQ
Q. 出现了错误——我先做什么？
A. 先跑 claude doctor。它一次性检查安装、设置、MCP 和上下文。然后看 /status（当前认证）和 /context（什么在吃上下文），通常就能判断是认证、上下文还是连接问题。
Q. 我很快就撞上速率限制。有什么帮助？
A. Claude Code 的每一轮都会带上文件内容和工具调用，官方文档也指出一次调试就可能超过一整天聊天的用量，所以你比预期更早撞上。用 /usage 查额度和重置时间，用 /model 换更轻的模型，用 /compact 压缩历史，并禁用没用的 MCP。若还不够，考虑更高套餐（如 Max）或额外充值额度。
Q. 它说 “Invalid API key”，但我的 key 应该是对的。
A. 经典原因是残留的 ANTHROPIC_API_KEY 环境变量覆盖了你的订阅。用 env | grep ANTHROPIC 检查，unset ANTHROPIC_API_KEY（也从 shell 配置文件里移除），然后 /login 并用 /status 确认。
Q. 我在公司网络上连不上。
A. 先用 curl -I https://api.anthropic.com 确认可达性。代理场景设置 HTTPS_PROXY；TLS 检查场景把 NODE_EXTRA_CA_CERTS 指向 CA 证书。别用 NODE_TLS_REJECT_UNAUTHORIZED=0——很危险。正道是请 IT 放行 api.anthropic.com。
Q. 怎么试都不行——最后一招？
A. 用 claude update 更新到最新版。Claude Code 更新很快，已知 bug 常常只要升版本就消失。若仍失败，用 /feedback（包含对话日志）向 Anthropic 反馈。
