Skip to main content
遇到报错，先运行自诊断命令： 
/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 | sh

​
PATH 未配置（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

​
登录后仍提示未认证

# 删除本地凭证，重新走授权
rm -rf ~/.claude/credentials.json
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。 通常是文件内容包含了工具调用格式的特殊字符，或目标路径没有写权限： 
# 检查文件权限
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 路径）
安装成功后的国内网络配置见 Claude Code 国内使用指南。Claude Code 功能完整说明见 Claude Code 使用指南。 本文最后更新于 2026-04。