# Claude Code 安装与登录排错

> Claude Code 安装、PATH、冲突安装、权限、TLS/代理、Windows/WSL、Docker、登录和 OAuth 常见问题。

URL: https://docs.passion8.cc/docs/claude-code/install-troubleshooting
Language: zh-CN
Publisher: Passion8

这页处理 `claude` 命令还没正常跑起来之前的问题。已经能启动 Claude Code,但 settings、Hooks、MCP 或记忆不生效,看 [配置调试与 .claude 目录](https://docs.passion8.cc/docs/claude-code/configuration-debugging)。运行中 API 报错看 [错误参考](https://docs.passion8.cc/docs/claude-code/error-reference)。

## 先跑诊断

```bash
claude doctor
claude --version
which -a claude
```

Windows PowerShell:

```powershell
claude doctor
claude --version
where.exe claude
```




官方原生安装位置通常是 `~/.local/bin/claude` 或 Windows 的 `%USERPROFILE%\.local\bin\claude.exe`。VS Code 扩展内置的 CLI 不等于终端里的 `claude` 命令。




## 错误速查

| 现象 | 优先处理 |
| --- | --- |
| `command not found: claude` | 修 PATH,确认安装目录在 PATH |
| Windows 提示 not recognized | 新开终端,检查 `%USERPROFILE%\.local\bin` |
| 安装脚本返回 HTML | 下载地址被代理、登录页或防火墙替换 |
| `curl: (56)` | 网络中断或输出目录不可写 |
| TLS/SSL 错误 | 公司 CA、代理、证书链 |
| Homebrew cask 不存在 | 更新 Homebrew 或改用官方安装脚本 |
| Linux 安装时 `Killed` | 内存不足,加 swap 或换机器 |
| Docker 安装卡住 | 用非交互安装、固定版本、预装依赖 |
| Windows shell 命令报错 | PowerShell、CMD、Git Bash 命令不要混用 |
| WSL npm 安装异常 | 用 Linux 环境内的 Node/npm,避免 Windows 路径混用 |
| OAuth invalid code | 重新登录,确保浏览器和 CLI 在同一环境 |
| 403 after login | 账号、组织、地区或企业策略问题 |

## 网络和下载

安装器需要访问官方下载域名:

```bash
/usr/bin/curl -sI https://downloads.claude.ai/claude-code-releases/latest
```

PowerShell 里用 `curl.exe`,不要用被 alias 的 `curl`:

```powershell
curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest
```

如果公司网络需要代理:

```bash
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
```

TLS 报错时,优先让系统信任公司根证书。Node 进程需要额外 CA 时:

```bash
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca.pem"
```

## PATH

macOS / Linux:

```bash
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
claude --version
```

Bash 用户把 `~/.zshrc` 换成 `~/.bashrc`。

Windows PowerShell:

```powershell
$env:PATH -split ';' | Select-String '\.local\\bin'
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
```

改完 PATH 后要新开终端。

## 冲突安装

多个 `claude` 会导致版本不一致、命令跑到旧二进制、Desktop 覆盖路径等问题。

macOS / Linux:

```bash
which -a claude
ls -la ~/.local/bin/claude
ls -la ~/.claude/local/
npm -g ls @anthropic-ai/claude-code 2>/dev/null
```

清理旧 npm 全局安装:

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

如果用过 Homebrew:

```bash
brew uninstall --cask claude-code
```

Windows PowerShell:

```powershell
where.exe claude
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"
```

## 权限和目录

| 现象 | 处理 |
| --- | --- |
| 写入 `~/.local/bin` 失败 | 确认目录属于当前用户 |
| npm 全局权限错误 | 不建议 `sudo npm install -g`,优先原生安装 |
| `curl` 写输出失败 | 检查磁盘、目录权限和临时目录 |
| macOS quarantine 或 `dyld` | 重新安装官方二进制,确认架构匹配 |
| Linux musl/glibc 不匹配 | Alpine 和 glibc 发行版用对应二进制 |
| `Illegal instruction` | CPU 或架构不支持当前二进制 |
| WSL1 `Exec format error` | 升级 WSL2 或用兼容安装方式 |

## Windows 和 WSL

| 环境 | 建议 |
| --- | --- |
| Windows PowerShell | 使用官方 PowerShell 安装命令,不要粘贴 Bash 的 `curl -fsSL ... | bash` |
| CMD | PATH 改完后重开 CMD |
| Git Bash | 确认 `bash` 可用,路径不要混用 Windows 和 WSL |
| WSL2 | 在 WSL 内安装 Linux 版 Node 和 Claude Code |
| 32-bit Windows | 不支持,打开普通 64-bit PowerShell |
| Docker | 预装依赖和 CA,不要依赖交互式登录流程 |

Claude Code on Windows 需要可用 shell。若提示需要 Git for Windows 或 PowerShell,先安装对应 shell,再重试。

## 登录和 OAuth

官方登录问题常见处理:

```bash
claude /login
claude doctor
```

如果登录状态混乱,可以重置后重新登录。具体删除哪些文件取决于平台和安装方式,先用 `claude doctor` 看诊断,不要盲删整个 `~/.claude`。

| 现象 | 可能原因 |
| --- | --- |
| OAuth invalid code | 浏览器跳转被代理、复制了旧 code、CLI 和浏览器环境不一致 |
| 403 after login | 账号地区、组织禁用、套餐或企业策略 |
| WSL/SSH/容器登录失败 | 浏览器回调无法回到远程 shell,改用 API Key 或在本机登录 |
| token expired | 重新 `/login` |
| Bedrock/Vertex/Foundry 凭据缺失 | 检查云 provider 环境变量、profile 和权限 |

## 接入 Passion8 的登录选择

接 Passion8 通常不需要官方 OAuth 登录,只需要环境变量:

```bash
ANTHROPIC_BASE_URL="https://passion8.cc" \
ANTHROPIC_AUTH_TOKEN="sk-你的 Passion8 API Key" \
claude -p "只回答 ok"
```

如果这条能通,但交互模式不能通,说明 shell 配置、settings 或项目配置没有把变量带进去。继续看 [配置调试与 .claude 目录](https://docs.passion8.cc/docs/claude-code/configuration-debugging)。

## 官方参考

- [Troubleshoot installation and login](https://code.claude.com/docs/en/troubleshoot-install.md)
- [Setup Claude Code](https://code.claude.com/docs/en/setup.md)
- [Debug your configuration](https://code.claude.com/docs/en/debug-your-config.md)
- [Error reference](https://code.claude.com/docs/en/errors.md)