Claude Code

安装与登录排错

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

这页处理 claude 命令还没正常跑起来之前的问题。已经能启动 Claude Code,但 settings、Hooks、MCP 或记忆不生效,看配置调试与 .claude 目录。运行中 API 报错看错误参考。

#先跑诊断

claude doctor
claude --version
which -a claude

Windows 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	账号、组织、地区或企业策略问题

#网络和下载

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

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

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

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

如果公司网络需要代理:

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

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

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

#PATH

macOS / Linux:

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:

$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:

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

清理旧 npm 全局安装:

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

如果用过 Homebrew:

brew uninstall --cask claude-code

Windows 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

官方登录问题常见处理:

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 登录,只需要环境变量:

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

如果这条能通,但交互模式不能通,说明 shell 配置、settings 或项目配置没有把变量带进去。继续看配置调试与 .claude 目录。

#官方参考

上一页工作原理与扩展地图下一页配置调试与 .claude 目录

Support / 支持

Need help? / 需要帮助？

接入、计费与模型异常可邮件联系；服务可用性以状态页为准。
For setup, billing, or model issues, email us. Check the status page for uptime.

Support Email[email protected]Service Statusstatus.passion8.cc

也可使用右下角微信 / QQ 客服 · WeChat / QQ support is available at the bottom right