Claude Code 报错速查手册：安装、认证、运行时问题全覆盖

npm 安装超时或失败#

现象：npm install -g @anthropic-ai/claude-code 长时间无响应或报 ETIMEDOUT。

npm 安装方式已被官方标注为废弃，建议改用原生安装方式（Native Installer），下载速度更快，且不依赖 Node.js 版本：

1
# macOS / Linux
2
curl -fsSL https://claude.ai/install.sh | sh

如果原生安装也超时（安装包从 storage.googleapis.com 下载），需要先配置代理：

1
export HTTPS_PROXY=http://127.0.0.1:7890
2
curl -fsSL https://claude.ai/install.sh | sh

PATH 未配置（command not found）#

现象：安装完成，但运行 claude 提示 command not found。

1
# 查找 claude 实际安装位置
2
which claude || find ~/.local ~/.npm -name "claude" 2>/dev/null | head -5

把安装目录加入 PATH：

1
# npm 全局安装的情况
2
export PATH="$(npm bin -g):$PATH"
3

4
# 原生安装默认路径
5
export PATH="$HOME/.local/bin:$PATH"

将以上行写入 ~/.zshrc 或 ~/.bashrc，然后 source 使配置生效。

内存不足（安装中途失败）#

现象：Linux 系统上安装进程被终止，无明确报错。

Claude Code 安装需要至少 4 GB 可用内存。内存不足时 Linux OOM Killer 会直接结束进程。

1
# 检查可用内存
2
free -h
3

4
# 临时增加 swap（2GB）
5
sudo fallocate -l 2G /swapfile
6
sudo chmod 600 /swapfile
7
sudo mkswap /swapfile
8
sudo swapon /swapfile

OAuth error: Invalid code#

现象：登录时浏览器完成授权，终端报 OAuth error: Invalid code。

登录码有效期很短（约 30 秒）。复制 URL 后需要立即在浏览器完成授权，不能等待。重新运行 claude 走完整登录流程。

如果终端无法自动打开浏览器（如 WSL）：

1
claude
2
# 终端会输出类似：
3
# Open this URL to authenticate: https://claude.ai/auth?code=xxxx
4
# 手动复制该 URL，粘贴到 Windows 浏览器打开

OAuth 不支持 SOCKS5#

现象：配置了代理但登录还是失败。

Claude Code 认证只支持 HTTP/HTTPS 代理，不支持 SOCKS5。确认代理环境变量格式正确：

1
# 正确
2
export HTTPS_PROXY=http://127.0.0.1:7890
3

4
# 错误（不支持）
5
export HTTPS_PROXY=socks5://127.0.0.1:7891

登录后仍提示未认证#

1
# 删除本地凭证，重新走授权
2
rm -rf ~/.claude/credentials.json
3
claude

地区限制提示#

现象：安装时弹出 Claude Code might not be available in your country。

这是安装包的地区检测，不影响 API 层的实际调用。配置 API 代理或中转站后即可正常使用，参考 Claude Code 国内使用指南。

overloaded_error（服务器过载）#

现象：API Error: overloaded_error - Overloaded。

Anthropic 服务器繁忙，非本地问题。稍等几分钟后重试，或在非高峰时段（UTC 白天）使用。

Write failed: InputValidationError#

现象：Claude Code 写文件时报 Write failed due to the following issues。

通常是文件内容包含了工具调用格式的特殊字符，或目标路径没有写权限：

1
# 检查文件权限
2
ls -la 目标文件路径
3

4
# 修复权限
5
chmod 644 目标文件路径

如果权限正常仍报错，在对话里告知 Claude Code 报错内容，要求它换一种写法重试。

tool_call_error#

现象：Error: tool_call_error - Tool invocation failed。

工具调用参数格式错误，通常在复杂任务中出现。在对话里说”上一步出现了 tool_call_error，请重新执行”，Claude Code 会调整参数重试。

request timeout#

现象：请求长时间等待后超时。

1
# 确认代理稳定性
2
curl -x http://127.0.0.1:7890 -o /dev/null -s -w "%{time_total}" https://api.anthropic.com
3
# 响应时间应在 2 秒内

超时也可能是任务过大导致推理时间长，可以尝试把任务拆小。