Claude Code 错误码排查

先分清错误发生在哪一层

INSTALL

安装 / 运行时

command not found、Node 版本、npm 权限、WSL 路径和原生安装器问题。

AUTH

登录 / 认证

OAuth 回调、API key、Console 组织、SSO 和本地 auth 状态问题。

NETWORK

网络 / 代理

企业代理、防火墙、证书、超时、403/429 和必需域名不可达。

常见错误与处理

claude: command not found

常见原因: 安装目录没有加入 PATH, 或当前 shell 还没重新加载配置。

处理: 打开新终端, 或把 Claude Code 安装目录加入 PATH 后重新加载 shell 配置。

export PATH="$PATH:$HOME/.local/bin"
source ~/.zshrc

Node version not supported / silent crash

常见原因: Node 版本低于官方要求, 或 WSL 调用了 Windows 侧 Node。

处理: 升级 Node, 或使用官方 native installer。WSL 下用 which node / which npm 确认路径来自 Linux 环境。

node -v
which node
which npm

EACCES / permission denied

常见原因: 全局 npm 目录归 root 所有, 或之前用 sudo 安装导致权限混乱。

处理: 不要用 sudo 安装 Claude Code。改 npm prefix 到用户目录, 或使用 native installer。

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

Waiting for authentication...

常见原因: 浏览器 OAuth 回调没有回到本机 CLI, 常见于 remote SSH、devcontainer、严格防火墙或 localhost 回调被拦。

处理: 确认浏览器和 CLI 在同一台机器可互通。必要时退出登录、重启 Claude Code, 再重新完成认证。

/logout
# 关闭 Claude Code 后重新运行
claude

SELF_SIGNED_CERT_IN_CHAIN / certificate error

常见原因: 公司代理或安全网关注入了自签 CA, Node 默认不信任该证书链。

处理: 让 IT 提供公司 CA bundle, 并通过 NODE_EXTRA_CA_CERTS 指定。

export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

proxy connection failed / timeout

常见原因: 代理变量写错、代理协议不支持、NO_PROXY 覆盖了目标域名, 或企业防火墙阻断。

处理: Claude Code 使用标准 HTTP/HTTPS proxy 环境变量; 官方说明不支持 SOCKS 代理。先用 HTTPS_PROXY 复测。

export HTTPS_PROXY=http://proxy.example.com:8080
echo $HTTPS_PROXY
echo $NO_PROXY

403 Forbidden

常见原因: 组织未启用 Claude Code、企业 allowlist 未包含当前出口、账号/地区/策略限制或代理被拒绝。

处理: 个人账号先确认支持地区和账号状态; 企业账号让管理员检查 Claude Code 权限、SSO、IP allowlist 和防火墙。

429 / rate limit

常见原因: 请求过密、并发过高、账号计划限制或组织级限流。

处理: 降低外层并发, 停止循环重试, 等待恢复。不要用多 worker 包 Claude Code 做强行加速。

API key not recognized / SSO mismatch

常见原因: API key 来自另一个 shell、Console key 与 OAuth 会话冲突, 或组织要求 SSO 登录。

处理: 检查 ANTHROPIC_API_KEY 是否来自当前 shell。组织账号按管理员要求走 Console/SSO 登录。

echo $ANTHROPIC_API_KEY

代理和企业网络基线

官方文档说明 Claude Code 支持标准 HTTPS_PROXY / HTTP_PROXY / NO_PROXY 环境变量, 但不支持 SOCKS 代理。企业自签证书需要通过 NODE_EXTRA_CA_CERTS 指定 CA bundle。

export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY="localhost,127.0.0.1"
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

最小复现流程

确认 `node -v` 满足官方要求, 或使用 Claude Code native installer。
关闭外层脚本和 worker, 只在一个终端窗口运行 `claude`。
用 `echo $HTTPS_PROXY`、`echo $NO_PROXY` 确认代理变量没有写错。
访问 api.anthropic.com、claude.ai、statsig.anthropic.com、sentry.io 是否被防火墙允许。
如果是登录卡住, 运行 `/logout` 后重启 Claude Code, 必要时清理本地 auth 文件再重新登录。

官方依据

Claude Code 企业网络配置

代理、CA、mTLS 和必需访问 URL。

Claude Code 安装与认证排障

官方列出的安装、Node、权限、代理和登录常见问题。

Claude Code 数据与遥测

Statsig、Sentry、/bug 和禁用非必要流量的环境变量。

Claude Code FAQ

企业代理、Console 组织和常见权限问题。