目录
你正在用 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。若反复出现，检查系统时钟和 Keychain 是否被锁 |
| Invalid API key | 残留了过期的 ANTHROPIC_API_KEY | env | grep ANTHROPIC → unset ANTHROPIC_API_KEY → /login |
| OAuth token revoked / expired | 在别处登出了 / 管理员禁用了 | /logout → /login。也要怀疑时钟偏差 |
| This organization has been disabled | 来自已禁用组织的 API key 覆盖了凭证 | 从 shell 配置文件（.zshrc 等）中移除该 key → /login → 用 /status 确认 |
| 403 Forbidden (after login) | 订阅过期 / 缺少角色 / 代理干扰 | 检查订阅和 Console 角色。代理场景设置 HTTPS_PROXY |
经验法则：环境变量里的 API key 优先于订阅登录。如果你为某个 CI 任务设了 ANTHROPIC_API_KEY 又忘了，你个人的 Pro/Max 套餐就会被忽略。先用 /status 确认"当前生效的是哪个凭证"才是正解。
3. 用量与速率限制（最常见）
Claude Code 最常见的抱怨。Claude Code 消耗的 token 是聊天的 10-100 倍（多轮对话、巨大的上下文、工具往返），所以你比感觉中更快地撞上限制。
"撞上限制"时的 3 步
/usage 看额度和重置时间，/status 看凭证/model 换更轻的模型，/compact 压缩历史，禁用没用的 MCP
注意："Server is temporarily limiting requests"是短暂的服务器侧限流，不是你的套餐额度。等一下再重试即可。
别和套餐额度（会话/每周）搞混。
更多："429 / Request rejected"是你的 API key 或工作区上的速率超限。"Credit balance is too low"是 Console 预付余额耗尽（在账单页充值或改用订阅）。要注意的是，2026 年 3 月前后，有 Max 用户在科技媒体和官方仓库的 issue 中报告其 5 小时窗口异常地快速耗尽（疑似 bug）。若反复出现，请更新到最新版本，用 /usage 测量，必要时 /feedback 反馈。系统性地省 token，参见 AI 省 token 和 Claude Code 省 token。
4. 上下文与 token
处理冗长的会话或巨大的文件时会出现。
| 症状 | 原因 | 对策 |
|---|---|---|
| Prompt is too long | 对话 + 文件超出了上下文窗口 | /compact（汇总）、/clear（重置）、/context 看明细，用 /mcp 禁用没用的 MCP |
| Error during compaction: Conversation too long | 压缩输出的剩余空间不足 | 按两次 Esc 回退几轮，再 /compact。仍卡住就 /clear |
| Auto-compact is thrashing | 压缩刚结束，一个巨大的输出又把上下文填满 | 按行范围读大文件 / /compact keep only <focus> / 移交给子 agent |
诀窍是绝不整文件读取大文件。日志和数据要按小的行范围分块传入。理解 上下文窗口 的概念，能让这一类错误大幅减少。
5. 服务器与模型
| 症状 | 原因 | 对策 |
|---|---|---|
| 500 Internal server error | Anthropic 侧的临时故障 | 查看 status.claude.com → 1 分钟后重试 |
| 529 Overloaded (repeated) | API 临时满载 | 等几分钟。用 /model 换模型以分散负载 |
| Request timed out | 在 10 分钟默认时限内无响应 | 拆分任务。线路慢就调高 API_TIMEOUT_MS |
| model not found / no access | 模型名错误或不在你的套餐内 | /model 重新选择。检查残留的 ANTHROPIC_MODEL 环境变量 |
| Opus is not available with Pro plan | 所选模型不在你的套餐内 | /model 换一个可用的。变更套餐后，/logout→/login |
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 |
| Multiple claude installations found | npm/Homebrew/native 重复安装 | 只保留一个，例如 npm uninstall -g @anthropic-ai/claude-code |
| Bugs from an old version | 没更新 | claude update（能解决许多 bug 的首选对策） |
7. 网络与代理
在企业网络和 VPN 上常见。先用 curl -I https://api.anthropic.com 确认可达性。
| 症状 | 原因 | 对策 |
|---|---|---|
| Unable to connect / ECONNREFUSED / ETIMEDOUT | 离线 / 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 并放行目标域名 |
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 | 启动 >5 秒等 | MCP_TIMEOUT=10000 claude（毫秒）。按服务器：.mcp.json 里的 "timeout" |
9. 权限与工具
这类是"连 bypass 模式下都来问权限"的家族。要点：deny 规则优先于 allow 和 bypass。
| 症状 | 原因 | 对策 |
|---|---|---|
| Asked for permission even in bypass mode | deny 规则胜出；危险操作总会询问（断路器） | 在 /permissions 中检查并调整 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 错误。 - Could not check the pull request status：GitHub 连接问题（常见是
gh认证）。先从gh auth status开始。详情：PR 状态错误。 - Image was too large / PDF too large：长边超过 8000px 的图片、超过 100 页 / 32 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 检查 deny 规则 |
| 只想把它修好 | claude update（最新版能解决很多问题） |
总结
Claude Code 的错误很多，但第一步是用三个命令切分原因：claude doctor / /status / /context——这能让大多数问题重新动起来。常见的是四大类——用量/速率限制、上下文溢出、认证过期、MCP 连接失败——而 /usage、/compact、/login、/mcp 是第一线的对策。
而最容易被忽视的最强一招，是用 claude update 保持最新。Claude Code 更新很快，过去的 bug（比如 thinking-blocks 400）常常只要升一下版本就消失了。"卡住时先来三个诊断命令；若没修好，就更新到最新版。"守住这个套路，你就不会再把时间耗在错误里。
延伸阅读：thinking blocks 400 错误、PR 状态检查错误、Claude Code 省 token、为何 bypass 模式下仍会询问权限，以及 什么是 MCP。
FAQ
Q. 出现了错误——我先做什么？
A. 先跑 claude doctor。它一次性检查安装、设置、MCP 和上下文。然后看 /status（当前认证）和 /context（什么在吃上下文），通常就能判断是认证、上下文还是连接问题。
Q. 我很快就撞上速率限制。有什么帮助？
A. Claude Code 消耗的 token 是聊天的 10-100 倍，所以你比预期更早撞上。用 /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 反馈。
