遇到报错，先运行自诊断命令：
/doctor/doctor 会检查安装版本、配置文件语法、MCP 服务器状态，并给出修复建议。如果 claude 命令本身打不开，按下表定位问题再跳转对应章节。
| 症状 | 类别 | 跳转 |
|---|---|---|
npm install 超时或失败 | 安装 | 安装类问题 |
command not found: claude | 安装 | PATH 未配置 |
| 安装中途进程被终止 | 安装 | 内存不足 |
OAuth error: Invalid code | 认证 | 认证类问题 |
| 授权后仍提示未登录 | 认证 | 登录后仍提示未认证 |
App unavailable in region | 认证 | 地区限制 |
overloaded_error | 运行时 | 运行时报错 |
Write failed: InputValidationError | 运行时 | Write failed |
| WSL 无法完成登录 | 特殊场景 | WSL 场景 |
安装类问题
npm 安装超时或失败
现象：npm install -g @anthropic-ai/claude-code 长时间无响应或报 ETIMEDOUT。
npm 安装方式已被官方标注为废弃，建议改用原生安装方式（Native Installer），下载速度更快，且不依赖 Node.js 版本：
# macOS / Linux
curl -fsSL https://claude.ai/install.sh | sh如果原生安装也超时（安装包从 storage.googleapis.com 下载），需要先配置代理：
export HTTPS_PROXY=http://127.0.0.1:7890
curl -fsSL https://claude.ai/install.sh | shPATH 未配置（command not found）
现象：安装完成，但运行 claude 提示 command not found。
# 查找 claude 实际安装位置
which claude || find ~/.local ~/.npm -name "claude" 2>/dev/null | head -5把安装目录加入 PATH：
# npm 全局安装的情况
export PATH="$(npm bin -g):$PATH"
# 原生安装默认路径
export PATH="$HOME/.local/bin:$PATH"将以上行写入 ~/.zshrc 或 ~/.bashrc，然后 source 使配置生效。
内存不足（安装中途失败）
现象：Linux 系统上安装进程被终止，无明确报错。
Claude Code 安装需要至少 4 GB 可用内存。内存不足时 Linux OOM Killer 会直接结束进程。
# 检查可用内存
free -h
# 临时增加 swap（2GB）
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile认证类问题
OAuth error: Invalid code
现象：登录时浏览器完成授权，终端报 OAuth error: Invalid code。
登录码有效期很短（约 30 秒）。复制 URL 后需要立即在浏览器完成授权，不能等待。重新运行 claude 走完整登录流程。
如果终端无法自动打开浏览器（如 WSL）：
claude
# 终端会输出类似：
# Open this URL to authenticate: https://claude.ai/auth?code=xxxx
# 手动复制该 URL，粘贴到 Windows 浏览器打开
OAuth 不支持 SOCKS5
现象：配置了代理但登录还是失败。
Claude Code 认证只支持 HTTP/HTTPS 代理，不支持 SOCKS5。确认代理环境变量格式正确：
# 正确
export HTTPS_PROXY=http://127.0.0.1:7890
# 错误（不支持）
export HTTPS_PROXY=socks5://127.0.0.1:7891
如果你手里只有 SOCKS5 节点，或者浏览器能登、CLI 还是不稳，建议换用支持 HTTP 协议的代理出口，或联系代理服务商确认是否支持 HTTP 转发。
登录后仍提示未认证
# 删除本地凭证，重新走授权
rm -rf ~/.claude/credentials.json
claude地区限制提示
现象：安装时弹出 Claude Code might not be available in your country。
这是安装包的地区检测，不影响 API 层的实际调用。配置 HTTP 代理（HTTPS_PROXY 环境变量）或 API 中转站后即可正常使用。
如果你不是单次安装，而是想长期稳定使用 Claude Code，建议使用质量可靠的商业 ISP 代理，确保出口 IP 干净稳定。
运行时报错
overloaded_error（服务器过载）
现象：API Error: overloaded_error - Overloaded。
Anthropic 服务器繁忙，非本地问题。稍等几分钟后重试，或在非高峰时段（UTC 白天）使用。
Write failed: InputValidationError
现象：Claude Code 写文件时报 Write failed due to the following issues。
通常是文件内容包含了工具调用格式的特殊字符，或目标路径没有写权限：
# 检查文件权限
ls -la 目标文件路径
# 修复权限
chmod 644 目标文件路径如果权限正常仍报错，在对话里告知 Claude Code 报错内容，要求它换一种写法重试。
tool_call_error
现象：Error: tool_call_error - Tool invocation failed。
工具调用参数格式错误，通常在复杂任务中出现。在对话里说”上一步出现了 tool_call_error，请重新执行”，Claude Code 会调整参数重试。
request timeout
现象：请求长时间等待后超时。
# 确认代理稳定性
curl -x http://127.0.0.1:7890 -o /dev/null -s -w "%{time_total}" https://api.anthropic.com
# 响应时间应在 2 秒内超时也可能是任务过大导致推理时间长，可以尝试把任务拆小。
WSL 特殊场景
现象：WSL 终端里 claude 无法自动打开浏览器完成 OAuth。
claude
# 复制终端输出的授权 URL
# 在 Windows 浏览器（Edge/Chrome）里打开，完成授权
# 授权后回到 WSL 终端，登录自动完成如果 WSL 里 claude 找不到，确认使用的是 Linux 路径下的 Node.js，而不是 Windows 路径：
which node
# 应输出 /usr/bin/node 或 /home/用户名/.nvm/...
# 不应输出 /mnt/c/...（Windows 路径）安装成功后如遇到 API 连通性问题，确认 HTTPS_PROXY 环境变量已正确设置，且代理支持 HTTP/HTTPS 协议（不支持 SOCKS5）。
本文最后更新于 2026-04。