Claude Code 报错解决手册：安装失败、登录异常、context too long 等常见问题全覆盖

Claude Code 报错了？这篇手册覆盖从安装到日常使用最常见的问题，每个附上可直接执行的解决步骤。

安装类#

command not found: claude#

PATH 没有更新。

source ~/.zshrc     # zsh（macOS 默认）
source ~/.bashrc    # bash

还不行？

which claude         # 找实际路径
echo 'export PATH="~/.claude/bin:PATH"' >> ~/.zshrc
source ~/.zshrc

安装脚本返回 HTML#

请求被拦截，返回了网页。

解决：挂代理，或改用 Homebrew：

brew install --cask claude-code

TLS / SSL 错误#

unset https_proxy
curl -fsSL https://claude.ai/install.sh | bash

Windows && 不识别#

你在 PowerShell 里：

irm https://claude.ai/install.ps1 | iex

Windows：requires git-bash#

先装 Git for Windows：https://git-scm.com/downloads/win（勾选 Git Bash）

低内存 Linux 安装被 kill#

sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile
# 再次安装

登录 / 认证类#

OAuth error: Invalid code#

claude /logout
claude /login

还不行，清除缓存：

rm -f ~/.claude/.credentials.json
claude /login

403 Forbidden#

账号没权限或订阅过期。确认有 Pro/Max/Team/Enterprise 订阅或 Console 余额。

Model not found#

当前订阅等级无法使用选中的模型，切换：

/model
# 选 claude-sonnet-4-6

WSL2 OAuth 失败#

Claude Code 会输出 URL，复制到 Windows 浏览器手动打开。

使用中的性能 / 上下文问题#

Context window full / 上下文太长#

/compact   # 压缩对话，释放空间

或开新会话：/clear

预防：

• 每完成一个任务就 /compact
• 精确引用文件（@src/auth.ts）减少探索
• 大型任务拆成多个子任务

Auto-compaction thrashing#

上下文满了，压缩后又立刻填满，循环卡住。

/clear   # 彻底清除，重新开始

下次在 60-70% 时就主动 /compact。

响应很慢#

1. 检查网络代理（Claude API 需要代理）
2. 切换到 Sonnet（比 Opus 快很多）：/model
3. 开 Fast Mode：/fast（Opus 提速 2.5x，更贵）
4. 先 /compact 减少上下文

命令卡住不动#

Ctrl+C   # 中断
Ctrl+D   # 强制退出
claude -c  # 重启并继续上次对话

MCP 相关#

MCP 连接失败#

claude mcp list              # 查看状态
claude mcp remove <name>    # 删除
claude mcp add ...           # 重新添加

MCP 工具不出现#

/mcp → 找到对应服务器 → Enable

配置文件位置#

重置配置（奇怪问题时）：

rm -rf ~/.claude/
claude   # 重新初始化

还是解决不了？#

• 开启详细日志：claude --debug
• 官方文档：https://code.claude.com/docs/en/troubleshooting
• Discord 社区：https://www.anthropic.com/discord
• 提交 bug：/bug

来源：Claude Code 官方 Troubleshooting 文档 | 整理：ClaudeEagle