Claude学院

Claude Code 报错不工作？常见问题排查清单

Claude Code 报错不工作，九成集中在四类原因：API Key 认证失败、网络代理或超时、Node 运行环境不兼容、MCP 服务器配置错误。按下面的清单从「认证 → 网络 → 环境 → 配置」逐层排查，绝大多数故障都能在几分钟内定位。先记住一个万能起点：在出问题的目录运行 claude --version 和 claude doctor，前者确认 CLI 本身能跑，后者会自动体检环境并提示明显问题。

第一步：确认 Claude Code 本身能启动

如果连版本号都打不出来，问题在安装层，而不是模型或网络。

  • 提示 command not found: claude：npm 全局 bin 目录没进 PATH。运行 npm config get prefix 看到前缀（如 /usr/local 或 ~/.npm-global），把对应的 bin 目录加进 ~/.zshrc 或 ~/.bashrc 的 PATH，重开终端。Windows 用户重装后需重启终端让 PATH 生效。
  • 启动即崩溃、报 SyntaxError 或 Unexpected token：Node 版本过低。Claude Code 要求 Node 18 及以上，运行 node -v 检查；低于 18 用 nvm 升级到 LTS（nvm install --lts）。
  • 权限报错 EACCES：别用 sudo npm install -g，那会留下 root 属主的文件。改用 nvm 管理的 Node，或把 npm 前缀指向用户目录后重装。

全新装机的同学可以先看完整流程：Claude Code 怎么安装？Windows 完整安装教程（2026） 和 Claude Code Mac 安装教程：从零配置到首次运行。

第二步：认证与 API 报错

能启动但一发请求就报错，重点查认证。Claude Code 底层走 Messages API（POST /v1/messages），认证用 x-api-key 头配合 anthropic-version，所以 API Key 一旦失效，任何对话都会失败。

报错含义处理
401 authentication_errorKey 缺失、拼错或已吊销检查 ANTHROPIC_API_KEY 是否设置且无多余空格；重新 /login 或换新 Key
403 permission_errorKey 没有该模型/功能权限到 Console 确认工作区权限，或更换有权限的 Key
429 rate_limit_error触发限流看响应头 retry-after 退避重试，或降低并发
529 overloaded_error服务端临时过载指数退避重试即可，非你的配置问题

一个高频坑：同时设置了 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN，SDK 会把两个头都发出去，API 直接拒绝并返回 401。请只保留一个。401 的完整排查见 Claude API 报错 401 怎么解决？认证失败排查指南，限流的重试方案见 Claude API 429 限流报错怎么办？3 种重试方案。如果是登录态本身出问题（浏览器回调失败、token 过期），参考 Claude Code 登录失败怎么办？认证问题完整解决。

第三步：网络、代理与超时

国内环境最常见的「转圈半天然后报错」，根因往往是网络无法稳定连到 api.anthropic.com。诊断顺序：

  1. 先排除模型问题——直接 curl 一次最小请求： 
    curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-opus-4-8","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'
    能正常返回 JSON，说明网络和 Key 都没问题，故障在 Claude Code 配置侧；如果 curl 也卡住或超时，就是网络/代理问题。
  2. 代理没生效：给终端设置 HTTPS_PROXY（如 export HTTPS_PROXY=http://127.0.0.1:7890），Claude Code 会读取标准代理环境变量。注意区分 http:// 端口和 socks 端口写错会一直连不上。
  3. SSE 流式中断：Claude Code 用流式输出（SSE）实时显示回答，公司网关或某些代理会缓冲/切断长连接，表现为「输出到一半卡死」。换直连或换支持长连接的代理。

第四步：MCP 服务器连不上

配了 MCP（模型上下文协议）服务器后报错，多半是配置或依赖问题。用 claude mcp list 查看各服务器状态，显示 failed 的逐个排查：

  • 命令路径错误：MCP 配置里的启动命令（如 npx、uvx 或本地脚本）在当前 PATH 下找不到。用绝对路径，或确认对应工具已安装。
  • 环境变量缺失：很多 MCP 服务器需要自己的 API token，没传就连接失败。在配置的 env 字段补齐。
  • 受限网络下被拦截：如果给 MCP 配了主机白名单，缺哪个域名都会静默失败。

配置细节和模板见 Claude Code 配置 MCP 服务器完整步骤，想理解 MCP 是什么先读 MCP 是什么？一篇讲清 Claude 模型上下文协议。

第五步：上下文超限与会话异常

长会话里突然报 model_context_window_exceeded 或回答被截断，是上下文/输出超限。Claude Opus 4.8、Sonnet 4.6 提供 1M 上下文窗口，但单次对话堆积过多文件和历史仍可能撑爆。处理办法：用 /clear 开新会话，或用 /compact 让 Claude Code 压缩历史。如果是输出被截断（命中 max_tokens），说明任务太大，拆成多步。上下文管理技巧见 Claude 上下文窗口多大？长文档处理实用技巧。

第六步：配置文件与命令本身

如果某个特定命令行为反常，先怀疑项目里的 CLAUDE.md——它会被当作指令注入，写错会让模型「不听话」。改完保存即可生效，模板参考 Claude Code CLAUDE.md 配置文件怎么写？完整模板。日常命令对不上号时，查 Claude Code 常用命令大全（附使用场景） 核对用法。模型选错（比如简单任务用了最贵的）也会让你觉得「又慢又贵像出问题」，选型见 Claude 模型怎么选？Opus / Sonnet / Haiku 选型指南。

常见问题

Claude Code 一直转圈不出结果，是卡死了吗？

多数不是卡死，而是网络连不上或流式连接被中断。先按第三步用 curl 直测 API，确认是网络问题后设置代理环境变量或换直连。若 curl 正常而 Claude Code 仍卡，重启 CLI 并用 claude doctor 体检。

报 401 但我的 Key 明明是对的，为什么？

常见三种情况：一是 Key 复制时带了首尾空格或换行；二是同时设置了 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN，两者冲突被拒；三是 Key 已在 Console 被吊销。逐一排除后重新 /login 即可。

升级 Claude Code 后原来能用的功能报错了，怎么办？

先确认 Node 版本仍满足要求（node -v ≥ 18），再用 npm install -g @anthropic-ai/claude-code@latest 重装到最新版，最后检查 MCP 配置和 CLAUDE.md 是否引用了已变更的字段。涉及价格或配额的限制，具体以 Anthropic 官网为准。

← Claude Code