常见报错速查
按错误信息快速查找解决方案
常见报错速查¶
按
Ctrl+F搜索你看到的错误关键词，快速定位解决方案。
安装相关¶
command not found: claude¶
Claude Code 未安装或未加入 PATH：
npm install -g @anthropic-ai/claude-code
export PATH="$(npm config get prefix)/bin:$PATH"
npm ERR! EACCES permission denied¶
# 方法 1：sudo
sudo npm install -g @anthropic-ai/claude-code
# 方法 2：修改 npm 目录（推荐）
mkdir -p ~/.npm-global && npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
npm install -g @anthropic-ai/claude-code
Node.js version not supported¶
需要 Node.js 18+，推荐 22 LTS：
node --version
# 升级：macOS: brew install node | Linux: nodesource | Windows: nodejs.org
运行相关¶
401 Unauthorized / Invalid API key¶
详见 认证错误排查
429 Too Many Requests¶
等待 30-60 秒重试，或升级套餐。详见 认证错误排查
connect ETIMEDOUT¶
网络问题。详见 连接问题排查
ANTHROPIC_BASE_URL is not set¶
# 国内用户推荐深圳直连（最低延迟）
export ANTHROPIC_BASE_URL="http://103.236.53.153/api"
# 海外用户使用国际入口
# export ANTHROPIC_BASE_URL="https://api.qcode.cc/"
Could not connect to MCP server¶
检查 MCP 配置：cat ~/.claude/settings.json | grep -A5 mcp
Context window exceeded¶
在 Claude Code 中运行 /compact 压缩上下文，或 /clear 开启新对话。
Model not found¶
使用 QCode 支持的默认模型即可，无需手动指定。
IDE 相关¶
VS Code 中扩展不工作¶
- 确认 CLI 已安装：
claude --version - 确认 VS Code 终端中环境变量生效
- 重启 VS Code
Cursor 中无法使用¶
在 Cursor 内置终端运行 claude，而非使用 Cursor 自带的 AI。