Claude Code 深度学习手册

主题

安装与登录排错 ​

按错误信息定位安装失败与登录失败的具体修法，覆盖 PATH、网络、权限、二进制、OAuth。

是什么 ​

专门针对安装 Claude Code 和首次登录阶段出现的故障，区别于安装成功后的运行期 Troubleshooting 与配置类 Debug your configuration。核心做法是把你看到的报错信息或症状对照官方表格，跳转到对应修复段落。

如果报错不在表中，则依次执行诊断检查（网络连通性、PATH、冲突安装、目录权限、二进制可执行性）来缩小原因。还可改用 Claude Code Desktop app 通过图形界面安装，绕开终端。

怎么工作 ​

  • 安装器从 downloads.claude.ai 下载二进制，并把 claude 放到 macOS/Linux 的 ~/.local/bin/claude 或 Windows 的 %USERPROFILE%.local\bin\claude.exe
  • 先用错误对照表（command not found、HTML/403、curl 23/56、Killed、TLS/SSL、Illegal instruction、Exec format error、dyld、OAuth error 等）直接定位修法
  • 对照表无命中时按顺序跑诊断：检查网络 → 验证 PATH → 检查冲突安装 → 检查目录权限 → 验证二进制可运行
  • 存在多个安装时只保留一个，推荐保留 native 安装；npm 全局、~/.claude/local 旧版、Homebrew、WinGet 安装分别用各自命令卸载
  • 登录失败优先做一次干净重新认证：/logout → 关闭 → 重启 claude；浏览器没自动打开时按 c 复制 OAuth URL
  • 云厂商（Bedrock/Vertex/Foundry）凭据问题源自当前 shell 未认证对应 CLI，需在同一终端登录或在 IDE 设置里注入环境变量
  • 仍无法解决时查 GitHub issues，或运行 claude doctor 自动诊断，或在会话内用 /feedback 反馈

怎么配置 / 用法 ​

bash
# 验证网络连通性（HTTP/2 200 表示可达）
curl -sI https://downloads.claude.ai/claude-code-releases/latest

# 验证并修复 PATH（macOS Zsh 示例）
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
claude --version

# 检查冲突安装并清理多余安装
which -a claude
npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude/local

# 检查目录权限
test -w ~/.local/bin && echo writable || echo "not writable"
sudo mkdir -p ~/.local/bin && sudo chown -R $(whoami) ~/.local

# 代理环境下安装
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

# 低内存 Linux：加 swap
sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile
sudo mkswap /swapfile && sudo swapon /swapfile
powershell
# Windows PowerShell 安装命令（CMD 里 irm 不可用）
irm https://claude.ai/install.ps1 | iex

API key 顶掉了订阅时改回订阅：unset ANTHROPIC_API_KEY 后重启 claude。

什么时候用 ​

  • 运行 claude 报 command not found / 'claude' is not recognized，或安装后版本不对
  • curl/install 报 HTML、403、TLS/SSL、curl 23/56、Failed to fetch version 等下载或网络错误
  • 二进制起不来：Illegal instruction、Error loading shared library、dyld cannot load、WSL 的 Exec format error
  • 登录或鉴权失败：OAuth error、403 Forbidden、token 过期、Bedrock/Vertex/Foundry 凭据加载失败

限制 / 坑 ​

  • 仅覆盖安装与登录阶段；安装成功后的运行期问题见 Troubleshooting，配置不生效/hook 不触发见 Debug your configuration
  • Claude Code 在部分国家/地区不可用（报 App unavailable in region），需查 supported countries
  • 缺少 AVX 指令集（约 2013 年前 CPU 或未透传 AVX 的虚拟机）无 native 二进制解法，仅能跟踪 issue #50384
  • API Error 500/529/429 等未列出的 4xx/5xx 见 Error reference

硬事实速查（22 条） ​

  • command not found: claude / 'claude' is not recognized：安装目录不在 PATH，把 ~/.local/bin（Win 为 %USERPROFILE%.local\bin）加入 PATH 后重启终端
  • syntax error near unexpected token '<' 或 curl (22) 403：安装 URL 返回了 HTML/错误页，改用 brew install --cask claude-code 或 winget install Anthropic.ClaudeCode，或稍后重试
  • curl (23) / (56) Failure writing output：下载被中断，先 curl -sI 测连通性，再重试或换 brew/winget 安装
  • Killed during install（Linux）：OOM 杀进程，需至少 4GB RAM，加 2G swapfile 后重装
  • TLS / SSL connect error、unable to get local issuer certificate：更新 CA 证书（apt install ca-certificates）；Windows 启用 TLS 1.2；企业代理用 --cacert 与 NODE_EXTRA_CA_CERTS 指向公司 CA
  • Failed to fetch version from downloads.claude.ai：该域被网络拦截，设 HTTPS_PROXY 或换网络/VPN/替代安装方式
  • irm is not recognized：当前是 CMD 不是 PowerShell，改用 install.cmd 或开 PowerShell 跑 irm | iex
  • 'bash' is not recognized：在 Windows 跑了 mac/Linux 安装命令，改用 PowerShell 安装器
  • Windows requires Git for Windows or PowerShell：两种 shell 都没找到，加 PowerShell 路径或装 PowerShell 7 / Git for Windows，或在 settings.json 设 CLAUDE_CODE_GIT_BASH_PATH
  • Error loading shared library libstdc++.so.6：musl/glibc 二进制不匹配，用 ldd --version 判断 libc；glibc 误装 musl 则重装，真 musl（Alpine）则 apk add libgcc libstdc++ ripgrep
  • Illegal instruction：架构不符（用 uname -m 核对并报 issue），或 CPU 缺 AVX（grep avx /proc/cpuinfo 为空，无解法，跟踪 issue #50384）
  • cannot execute binary file: Exec format error（WSL）：WSL1 已知回归，wsl --set-version <Distro> 2 升级到 WSL2
  • dyld: cannot load / Symbol not found / Abort trap（macOS）：二进制与系统不兼容，需 macOS 13.0+，升级系统
  • npm 装在 WSL 报平台不符：npm config set os linux 后 npm install -g @anthropic-ai/claude-code --force，不要用 sudo
  • Could not find native binary package：未禁用 optional 依赖后重装，确认平台受支持且企业镜像含全部 8 个平台包
  • 登录失败通用修法：/logout → 关闭 → 重启 claude；浏览器没开按 c 复制 OAuth URL
  • OAuth error: Invalid code：登录码过期或被截断，重试并尽快完成，远程/SSH 时把终端里的 URL 复制到本地浏览器打开
  • 403 Forbidden after login：Pro/Max 查订阅是否有效，Console 用户确认有 Claude Code/Developer 角色，代理环境查网络配置
  • This organization has been disabled（仍有订阅）：ANTHROPIC_API_KEY 顶掉了订阅，unset ANTHROPIC_API_KEY 并从 shell profile 删除该行，/status 确认
  • OAuth login fails in WSL2/SSH/容器：浏览器在别的主机，粘贴登录码到提示处；WSL2 浏览器不开则设 BROWSER 指向 Windows 浏览器，或用 claude auth login 从 stdin 读码
  • Not logged in or token expired：/login 重新认证；频繁掉线检查系统时钟；macOS Keychain 锁定用 claude doctor 检查、security unlock-keychain 解锁
  • Bedrock/Vertex/Foundry credentials not loading：当前 shell 未认证云 CLI，分别用 aws sts get-caller-identity、gcloud auth application-default login、az login；IDE 内失败则在 IDE 设置注入环境变量

官方出处：https://code.claude.com/docs/en/troubleshoot-install