Claude Code 的报错种类不少, 但高频撞见的集中在这五类: 账单类的 402、OAuth 登录循环、context 超限压缩失败、MCP 服务器连不上、Windows 下找不到命令。下面按现象、原因、解决命令逐个理清, 内容基于 Anthropic 官方错误参考文档整理。
402 账单错误
现象: 请求返回 API Error: 402, 或提示需要更多积分/更少 max_tokens。
原因: 官方文档把它明确归类为 billing_error, 就是支付方式或积分出了问题, 不是权限或网络故障。免费额度或有限积分用户, 也可能是积分已耗尽。
解决:
- 打开 Claude Console (
platform.claude.com/settings/billing) 检查支付方式是否有效 - 用 Amazon Bedrock 的话查 AWS Marketplace 账户设置
- 跑
/usage看当前额度和重置时间 - 需要立即用的话跑
/usage-credits购买额外使用量, 或去控制台组织页面直接加积分
OAuth 登录循环
现象: 浏览器打开授权页, 点 Authorize 后又跳回登录页, 反复循环出不去。
原因: 多是浏览器缓存/Cookie 冲突, 或者 SSH/远程/容器环境里浏览器没法正常跳转回终端。
解决:
- 先在隐身/无痕窗口里试登录, 如果能成功说明是缓存 Cookie 问题, 清掉 Claude 相关站点数据后重启浏览器
- 远程或 SSH 会话里正常现象是浏览器只显示一个登录码, 不会自动跳回, 把这个码粘贴进终端的
Paste code here提示里完成登录 - 浏览器没自动打开的话, 按
c复制 OAuth 链接, 手动粘到浏览器打开 - 反复失败可以运行
/logout再/login强制重新走一遍认证流程
context 超限, /compact 也失败
现象: 提示 Prompt is too long, 手动跑 /compact 却报 Error during compaction: Error: Conversation too long。
原因: 官方文档承认这是已知问题: 当 context 窗口已经写满时, 压缩流程本身也需要占用一部分上下文空间来运行, 而这部分预留目前还不存在, 导致「最需要压缩的时候恰好压缩不了」。
解决:
- 按两次 Esc 回退几条消息再重试
/compact(给压缩流程腾出空间) - 如果窗口已经完全写满导致
/compact直接拒绝执行, 只能/clear开一个新会话, 这会清空上下文, 提前压缩比等到写满再压缩更稳妥 - 长期规避办法: 单个任务跑到一半就主动
/compact一次, 不要等到系统提示才处理 - 也可以用
/context先看当前上下文占用情况, 提前判断还有多少空间
MCP 服务器连接失败
现象: MCP 相关工具提示 Failed to connect, 或者配置文件看着没问题但服务器就是连不上。
原因: 常见几种: 配置文件改动后没重启 Claude Code、Node.js 版本过低、项目路径含空格或特殊字符、本地 stdio 类型的 MCP 服务器依赖的应用 (比如 Figma、Chrome) 没打开、远程 http/sse 类型的服务器认证过期或 URL 错误。
解决:
- 先跑
claude doctor, 官方文档说这一步能自动排查出约 80% 的配置问题 - 如果还是不行, 把 MCP 配置里的完整命令和参数直接复制到终端手动跑一遍, 看真实报错是什么
- 改了
~/.claude.json后必须完全关闭并重新打开 Claude Code, 配置改动在运行期间不会热生效 - 检查 Node.js 版本是否低于 v18, 低于的话升级
- 检查项目路径是否包含空格或特殊字符, 有的话挪到干净路径下
- 本地 stdio 类型服务器要确认它依赖的应用程序 (Figma、Chrome 等) 已经打开
- 远程 http/sse 类型服务器: 401/403 说明认证过期需要重新登录, 404/405 说明 URL 配错, 5xx 或超时通常是临时性的可以重试
- Windows 上用 npx 启动的 MCP 服务器, 官方建议用
cmd /c包一层再执行
Windows 找不到 claude 命令 / 路径问题
现象: 终端提示 claude 不是内部或外部命令, 或者文件读写操作报路径相关错误。
原因: 绝大多数是 PATH 没有正确指向 claude 安装目录, 少数是装过 Claude Desktop 后它的 claude.exe 抢占了 PATH 优先级, 或者是文件路径格式不对 (用了正斜杠、相对路径、没带盘符)。
解决:
- 关闭所有已打开的终端窗口, 重新开一个新的 (PATH 改动只对新开的窗口生效)
- 跑
claude --version测试, 失败就用where.exe claude看能不能定位到安装目录 - 定位到安装目录后手动把该目录加进系统 PATH 环境变量
- 如果之前装过 Claude Desktop, 检查它是否注册了同名的
Claude.exe占了 PATH 优先级, 更新 Claude Desktop 到最新版通常能解决冲突 - 文件读写类操作报错时, 确认路径都带盘符 (如
C:\Users\...)、用反斜杠\而不是正斜杠, 且是绝对路径而非相对路径 - 安装本身损坏的话, 用官方安装器重装比手动修 PATH 更快
我的判断
这五类报错里, 402 和 Windows 路径问题最容易自己排查清楚, 照着官方给的步骤走基本能解决。context 超限那个 bug 目前官方也没修完, 只能靠「提前压缩」这个习惯规避, 别等系统弹提示才处理。MCP 连接问题最费时间, 但 claude doctor 这一步基本能省掉大半排查时间, 遇到问题先跑这个, 不要一上来就重装。