Wiki AI

Troubleshoot Installation and Login 安装与登录排查

4分钟阅读

Claude Code 安装和登录阶段的错误排查。运行时问题见 troubleshooting，API 错误见 errors。

快速定位

症状解决方向
command not found: claudePATH 未配置
安装脚本返回 HTML网络代理拦截或地区限制
Killed 安装时（Linux）内存不足，需要 4GB+ RAM 或添加 swap
TLS/SSL 错误更新 CA 证书或配置企业代理证书
OAuth error / 403 Forbidden认证问题
Bedrock/Vertex/Foundry 凭证不加载云平台 CLI 未认证

诊断步骤

1. 检查网络：curl -sI https://downloads.claude.ai/claude-code-releases/latest，HTTP/2 200 表示可达。

2. 验证 PATH（安装目录：macOS/Linux ~/.local/bin/claude，Windows %USERPROFILE%\.local\bin\claude.exe）：

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
# 没有输出则添加：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

3. 检查冲突安装：which -a claude，多个安装时保留 ~/.local/bin/claude：

npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude/local

常见安装问题

安装脚本返回 HTML：地区不支持或网络问题，尝试备用安装：

brew install --cask claude-code   # macOS
winget install Anthropic.ClaudeCode  # Windows

Linux 内存不足（Killed）：

sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile
sudo mkswap /swapfile && sudo swapon /swapfile

Docker 安装挂起：必须设置 WORKDIR /tmp，避免扫描整个文件系统。

TLS/SSL 错误（企业代理）：

export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

不要用 NODE_TLS_REJECT_UNAUTHORIZED=0。

Linux musl/glibc 不匹配：ldd --version 检查 libc 类型；Alpine 需要 apk add libgcc libstdc++ ripgrep。

登录问题

重置登录（万能方法）：/logout → 关闭 Claude Code → 重新启动并认证。

WSL2/SSH/容器中 OAuth 登录：浏览器在不同主机打开时，将终端显示的 OAuth code 粘贴到提示处：

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude  # WSL2 中指定浏览器

403 Forbidden：Pro/Max 用户确认订阅有效；Console 用户确认账号有 “Claude Code” 或 “Developer” 角色。

组织被禁用（有效订阅但报错）：旧 ANTHROPIC_API_KEY 覆盖了订阅认证：

unset ANTHROPIC_API_KEY  # 并从 ~/.zshrc 中删除对应行

Bedrock/Vertex/Foundry 凭证不加载：

aws sts get-caller-identity          # Bedrock
gcloud auth application-default login  # Vertex AI
az login                              # Foundry

IDE 中不加载时，从终端启动 IDE（继承 shell 环境变量）。

与其他概念的关联

  • troubleshooting — 运行时性能和稳定性问题
  • errors — API 运行时错误
  • env-vars — ANTHROPIC_API_KEY、HTTPS_PROXY 等影响安装和认证

实践要点

  • ANTHROPIC_API_KEY 残留在 shell profile 是最常见的认证问题根源，用 /status 确认当前凭证
  • macOS Keychain 锁定会导致反复要求登录：security unlock-keychain ~/Library/Keychains/login.keychain-db
  • 企业环境中 TLS 代理拦截需要配置 NODE_EXTRA_CA_CERTS
  • 多个 Claude Code 安装会导致版本混乱，保留一个（推荐原生安装）

关系图谱

反向链接