文档索引

在此获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

安装和登录故障排除

修复安装或登录 Claude Code 时的命令未找到、PATH、权限、网络和认证错误。

如果安装失败或你无法登录，在下方查找你的错误。对于 Claude Code 运行后的运行时问题，参见故障排除。对于配置问题如设置未生效或钩子未触发，参见调试你的配置。

查找你的错误

将你看到的错误消息或症状与修复方法匹配：

你看到的内容	解决方案
`command not found: claude` 或 `'claude' is not recognized`	修复你的 PATH
`syntax error near unexpected token '<'`	安装脚本返回 HTML
`curl: (22) The requested URL returned error: 403`	安装脚本返回 403
`curl: (23)` 或 `curl: (56) Failure writing output to destination`	检查连接或使用替代安装器
Linux 安装期间 `Killed`	为低内存服务器添加交换空间
`TLS connect error` 或 `SSL/TLS secure channel`	更新 CA 证书
`Failed to fetch version` 或无法访问下载服务器	检查网络和代理设置
`irm is not recognized` 或 `&& is not valid`	为你的 shell 使用正确的命令
`'bash' is not recognized as the name of a cmdlet`	使用 Windows 安装器命令
`Claude Code on Windows requires either Git for Windows (for bash) or PowerShell`	安装 shell
`Claude Code does not support 32-bit Windows`	打开 Windows PowerShell，而不是 x86 条目
`The process cannot access the file ... because it is being used by another process`	清除下载文件夹并重试
`Error loading shared library`	系统使用了错误的二进制变体
`Illegal instruction`	架构或 CPU 指令集不匹配
WSL 中 `cannot execute binary file: Exec format error`	WSL1 原生二进制回归
PowerShell 安装器完成但未找到 `claude` 或显示旧版本	重启终端并验证 PATH
macOS 上 `dyld: cannot load`、`dyld: Symbol not found` 或 `Abort trap`	二进制不兼容
`Invoke-Expression: Missing argument in parameter list`	安装脚本返回 HTML
`App unavailable in region`	Claude Code 在你的国家/地区不可用。参见支持的国家/地区。
`unable to get local issuer certificate`	配置企业 CA 证书
`OAuth error` 或 `403 Forbidden`	修复认证
`Could not load the default credentials` 或 `Could not load credentials from any providers`	Bedrock、Vertex 或 Foundry 凭证
`ChainedTokenCredential authentication failed` 或 `CredentialUnavailableError`	Bedrock、Vertex 或 Foundry 凭证
`API Error: 500`、`529 Overloaded`、`429` 或其他未列出的 4xx 和 5xx 错误	参见错误参考

如果你的问题未列出，请进行下面的诊断检查以缩小原因范围。

Tip

如果你想完全跳过终端，Claude Code 桌面应用让你通过图形界面安装和使用 Claude Code。为 macOS 或 Windows 下载，无需任何命令行设置即可开始编码。

运行诊断检查

检查网络连接

安装器从 downloads.claude.ai 下载。验证你可以访问它：

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

HTTP/2 200 行意味着你已到达服务器。如果没有输出、Could not resolve host 或连接超时，你的网络正在阻止连接。常见原因：

企业防火墙或代理阻止 downloads.claude.ai
区域网络限制：尝试 VPN 或替代网络
TLS/SSL 问题：更新系统的 CA 证书，或检查是否配置了 HTTPS_PROXY

如果你在企业代理后面，在安装前将 HTTPS_PROXY 和 HTTP_PROXY 设置为代理地址。如果不知道代理 URL，询问你的 IT 团队，或检查浏览器的代理设置。

此示例设置两个代理变量，然后通过代理运行安装器：

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

验证你的 PATH

如果安装成功但运行 claude 时出现 command not found 或 not recognized 错误，说明安装目录不在你的 PATH 中。你的 shell 在 PATH 中列出的目录中搜索程序，安装器将 claude 放在 macOS/Linux 上的 ~/.local/bin/claude 或 Windows 上的 %USERPROFILE%\.local\bin\claude.exe。

通过列出你的 PATH 条目并过滤 local/bin 来检查安装目录是否在你的 PATH 中：

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

如果打印出 /Users/you/.local/bin 或 /home/you/.local/bin，说明目录在你的 PATH 中，可以跳到检查冲突的安装。如果没有输出，将其添加到你的 shell 配置中。

对于 macOS 上默认的 Zsh：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

对于大多数 Linux 发行版上默认的 Bash：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

或者，关闭并重新打开你的终端。

对于其他 shell 如 fish 或 Nushell，使用 shell 自己的配置语法将 ~/.local/bin 添加到你的 PATH，然后重启终端。

验证修复是否生效：

claude --version

$env:PATH -split ';' | Select-String '\.local\\bin'

如果没有输出，将安装目录添加到你的用户 PATH：

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

重启终端以使更改生效。

验证修复是否生效：

claude --version

echo %PATH% | findstr /i "local\bin"

如果没有输出，打开系统设置，转到环境变量，将 %USERPROFILE%\.local\bin 添加到你的用户 PATH 变量。重启终端。

验证修复是否生效：

claude --version

检查冲突的安装

多个 Claude Code 安装可能导致版本不匹配或意外行为。检查已安装的内容：

列出在你的 PATH 中找到的所有 claude 二进制文件：

which -a claude

如果没有打印任何内容，说明你的 PATH 中还没有 claude。回到验证你的 PATH。

检查 claude 二进制文件可能来自的三个位置。~/.local/bin/claude 是原生安装器，~/.claude/local/ 是旧版本 Claude Code 创建的遗留本地 npm 安装，npm 全局列表显示 -g 安装：

ls -la ~/.local/bin/claude

ls -la ~/.claude/local/

npm -g ls @anthropic-ai/claude-code 2>/dev/null

列出在你的 PATH 中找到的所有 claude 二进制文件：

where.exe claude

检查原生安装器是否放置了二进制文件：

Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

如果发现多个安装，只保留一个。推荐 macOS/Linux 上的 ~/.local/bin/claude 或 Windows 上的 %USERPROFILE%\.local\bin\claude.exe 原生安装。移除多余的：

卸载 npm 全局安装：

npm uninstall -g @anthropic-ai/claude-code

移除遗留的本地 npm 安装：

rm -rf ~/.claude/local

在 Windows 上，使用 PowerShell：

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"

移除 macOS 上的 Homebrew 安装。如果你安装了 claude-code@latest cask，替换该名称：

brew uninstall --cask claude-code

移除 Windows 上的 WinGet 安装：

winget uninstall Anthropic.ClaudeCode

检查目录权限

安装器需要对 macOS 和 Linux 上的 ~/.local/bin/ 和 ~/.claude/ 的写入权限。在 Windows 上，安装位置在 %USERPROFILE% 下，该目录默认可被你的用户写入，因此此部分很少适用。

检查目录是否可写：

test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"

如果任一目录不可写，创建安装目录并将你的用户设为所有者：

sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local

验证二进制文件是否工作

如果 claude --version 打印版本但 claude 在启动时崩溃或挂起，运行这些检查以缩小原因范围。如果 claude --version 显示命令未找到，先去验证你的 PATH；下面的命令假设 claude 在你的 PATH 中。

确认二进制文件存在且可执行：

ls -la "$(command -v claude)"

在 Windows 上，使用 PowerShell：

Get-Command claude | Select-Object Source

在 Linux 上，检查缺失的共享库。如果 ldd 显示缺失的库，你可能需要安装系统包。在 Alpine Linux 和其他基于 musl 的发行版上，参见 Alpine Linux 设置。

ldd "$(command -v claude)" | grep "not found"

确认二进制文件可以执行：

claude --version

常见安装问题

这些是最常遇到的安装问题及其解决方案。

安装脚本返回 HTML 而不是 shell 脚本

运行安装命令时，你可能会看到以下错误之一：

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'

在 PowerShell 上，同样的问题表现为：

Invoke-Expression: Missing argument in parameter list.

根据请求的路由方式，你可能会看到没有 HTML 正文的 403：

curl: (22) The requested URL returned error: 403

这些都意味着安装 URL 返回了 HTML 页面或错误状态而不是安装脚本。如果 HTML 页面显示"App unavailable in region"，说明 Claude Code 在你的国家/地区不可用。参见支持的国家/地区。

没有正文的裸 403 通常有相同的原因，但也可能来自企业代理或防火墙阻止下载。如果你在支持的国家/地区仍然看到 403，在尝试下面的替代安装器之前先进行检查网络连接，因为那些访问相同的主机。

否则，这可能是由于网络问题、区域路由或临时服务中断。

解决方案：

使用替代安装方法：

在 macOS 上，通过 Homebrew 安装：
```
brew install --cask claude-code
```
在 Windows 上，通过 WinGet 安装：
```
winget install Anthropic.ClaudeCode
```
几分钟后重试：问题通常是临时的。等待并再次尝试原始命令。

安装后 `command not found: claude`

安装完成但 claude 不工作。确切的错误因平台而异：

平台	错误消息
macOS	`zsh: command not found: claude`
Linux	`bash: claude: command not found`
Windows CMD	`'claude' is not recognized as an internal or external command`
PowerShell	`claude : The term 'claude' is not recognized as the name of a cmdlet`

这意味着安装目录不在你的 shell 搜索路径中。参见验证你的 PATH 了解各平台的修复方法。

`curl: (56) Failure writing output to destination`

curl ... | bash 命令下载脚本并将其管道传输到 Bash 执行。此错误以及相关的 curl: (23) Failure writing output to destination 意味着 Bash 没有接收到完整的脚本。退出代码 56 表示下载本身被中断，退出代码 23 表示 curl 无法将其接收到的内容写入管道，通常是因为 Bash 提前退出。

解决方案：

检查网络稳定性：Claude Code 二进制文件托管在 downloads.claude.ai。测试你是否可以访问它：
```
curl -sI https://downloads.claude.ai/claude-code-releases/latest
```
HTTP/2 200 行意味着你已到达服务器，原始故障可能是间歇性的；重试安装命令。如果看到 Could not resolve host 或连接超时，说明你的网络正在阻止下载。

尝试替代安装方法：

在 macOS 上：

brew install --cask claude-code

在 Windows 上：

winget install Anthropic.ClaudeCode

TLS 或 SSL 连接错误

类似 curl: (35) TLS connect error、schannel: next InitializeSecurityContext failed 或 PowerShell 的 Could not establish trust relationship for the SSL/TLS secure channel 的错误表示 TLS 握手失败。

解决方案：

更新系统 CA 证书：

在 Ubuntu/Debian 上：
```
sudo apt-get update && sudo apt-get install ca-certificates
```
在 macOS 上，系统 curl 使用钥匙串信任存储；更新 macOS 本身会更新根证书。

在 Windows 上，在运行安装器之前启用 TLS 1.2：

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex

检查代理或防火墙干扰：执行 TLS 检查的企业代理可能导致这些错误，包括 unable to get local issuer certificate 和 SELF_SIGNED_CERT_IN_CHAIN。对于安装步骤，使用 --cacert 将 curl 指向你的企业 CA 包：
```
curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash
```
对于安装后的 Claude Code 本身，设置 NODE_EXTRA_CA_CERTS 使 API 请求信任相同的包：
```
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
```
如果没有证书文件，请向你的 IT 团队索取。你也可以尝试直接连接以确认代理是原因。
在 Windows 上，绕过证书吊销检查（如果看到 CRYPT_E_NO_REVOCATION_CHECK (0x80092012) 或 CRYPT_E_REVOCATION_OFFLINE (0x80092013)）。这些意味着 curl 到达了服务器但你的网络阻止了证书吊销查找，这在企业防火墙后面很常见。在安装命令中添加 --ssl-revoke-best-effort：
```
curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```
或者，使用 winget install Anthropic.ClaudeCode 安装，完全避免 curl。

`Failed to fetch version from downloads.claude.ai`

安装器无法访问下载服务器。这通常意味着 downloads.claude.ai 在你的网络上被阻止。

解决方案：

直接测试连接：

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

如果在代理后面，设置 HTTPS_PROXY 以便安装器可以通过它路由。参见代理配置了解详情。
```
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash
```
如果在受限网络上，尝试不同的网络或 VPN，或使用替代安装方法：

在 macOS 上：
```
brew install --cask claude-code
```
在 Windows 上：
```
winget install Anthropic.ClaudeCode
```

Windows 上的错误安装命令

如果看到 'irm' is not recognized、The token '&&' is not valid 或 'bash' is not recognized as the name of a cmdlet，说明你复制了适用于不同 shell 或操作系统的安装命令。

irm 未识别：你在 CMD 中，而不是 PowerShell。你有两个选项：

在开始菜单中搜索"PowerShell"打开 PowerShell，然后运行原始安装命令：
```
irm https://claude.ai/install.ps1 | iex
```
或者留在 CMD 中使用 CMD 安装器：
```
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```
&& 无效：你在 PowerShell 中但运行了 CMD 安装器命令。使用 PowerShell 安装器：
```
irm https://claude.ai/install.ps1 | iex
```
bash 未识别：你在 Windows 上运行了 macOS/Linux 安装器。改用 PowerShell 安装器：
```
irm https://claude.ai/install.ps1 | iex
```

Windows 安装期间 `The process cannot access the file`

如果 PowerShell 安装器报错 Failed to download binary: The process cannot access the file ... because it is being used by another process，说明安装器无法写入 %USERPROFILE%\.claude\downloads。这通常意味着之前的安装尝试仍在运行，或者杀毒软件正在扫描该文件夹中部分下载的二进制文件。

关闭任何运行安装器的其他 PowerShell 窗口，等待杀毒扫描释放文件。然后删除下载文件夹并重新运行安装器：

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

低内存 Linux 服务器上安装被终止

如果在 VPS 或云实例上安装时看到 Killed：

Setting up Claude Code...
Installing Claude Code native build latest...
bash: line 142: 34803 Killed    "$binary_path" install ${TARGET:+"$TARGET"}

Linux OOM killer 终止了进程，因为系统内存不足。Claude Code 至少需要 4 GB 可用 RAM。

解决方案：

添加交换空间（如果你的服务器 RAM 有限）。交换空间使用磁盘空间作为溢出内存，即使物理 RAM 较低也能完成安装。

创建 2 GB 交换文件并启用它：
```
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
```
然后重试安装：
```
curl -fsSL https://claude.ai/install.sh | bash
```
关闭其他进程以在安装前释放内存。
使用更大的实例（如果可能）。Claude Code 至少需要 4 GB RAM。

Docker 中安装挂起

在 Docker 容器中安装 Claude Code 时，以 root 身份安装到 / 可能导致挂起。

解决方案：

在运行安装器之前设置工作目录。从 / 运行时，安装器会扫描整个文件系统，导致过多的内存使用。设置 WORKDIR 将扫描限制在小目录中：
```
WORKDIR /tmp
RUN curl -fsSL https://claude.ai/install.sh | bash
```
增加 Docker 内存限制（如果使用 Docker Desktop）：
```
docker build --memory=4g .
```

Claude Desktop 在 Windows 上覆盖 `claude` 命令

如果你安装了旧版本的 Claude Desktop，它可能在 WindowsApps 目录中注册了一个 Claude.exe，该文件在 PATH 优先级上高于 Claude Code CLI。运行 claude 会打开桌面应用而不是 CLI。

更新 Claude Desktop 到最新版本以修复此问题。

Windows 上的 Claude Code 需要 Git for Windows（用于 bash）或 PowerShell

Git for Windows 是可选的。当 Git Bash 缺失时，Claude Code 使用 PowerShell 工具，因此此错误意味着两个 shell 都未找到。

如果 PowerShell 不在你的 PATH 中，其默认位置是 C:\Windows\System32\WindowsPowerShell\v1.0\。将该目录添加到你的 PATH，或安装提供 pwsh 的 PowerShell 7。

要安装 Git for Windows，从 git-scm.com/downloads/win 下载。安装期间选择"Add to PATH"。安装后重启终端。安装它可以启用 Bash 工具，在使用基于 Bash 的脚本和工具时很有用。

如果 Git 已安装但 Claude Code 找不到它，在你的 settings.json 文件中设置路径：

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

如果你的 Git 安装在其他位置，通过在 PowerShell 中运行 where.exe git 找到路径，并使用该目录中的 bin\bash.exe 路径。

Claude Code 不支持 32 位 Windows

Windows 在开始菜单中有两个 PowerShell 条目：Windows PowerShell 和 Windows PowerShell (x86)。x86 条目以 32 位进程运行，即使在 64 位机器上也会触发此错误。要检查你的情况，在产生错误的同一窗口中运行：

[Environment]::Is64BitOperatingSystem

如果打印 True，你的操作系统没问题。关闭窗口，打开不带 x86 后缀的 Windows PowerShell，然后再次运行安装命令。

如果打印 False，你使用的是 32 位版本的 Windows。Claude Code 需要 64 位操作系统。参见系统要求。

Linux musl 或 glibc 二进制不匹配

如果安装后看到关于缺失共享库如 libstdc++.so.6 或 libgcc_s.so.1 的错误，安装器可能下载了错误的系统二进制变体。

Error loading shared library libstdc++.so.6: No such file or directory

这可能发生在安装了 musl 交叉编译包的基于 glibc 的系统上，导致安装器错误地将系统检测为 musl。

解决方案：

检查你的系统使用哪个 libc：
```
ldd --version 2>&1 | head -1
```
输出提到 GNU libc 或 GLIBC 表示 glibc。输出提到 musl 表示 musl。
如果你在 glibc 上但得到了 musl 二进制文件，移除安装并重新安装。你也可以使用 https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json 处的清单手动下载正确的二进制文件。提交 GitHub issue，附上 ldd --version 和 ls /lib/libc.musl* 的输出。
如果你实际上在 musl 上，如 Alpine Linux，安装所需的包：
```
apk add libgcc libstdc++ ripgrep
```

`Illegal instruction`

如果运行 claude 或安装器打印 Illegal instruction，说明原生二进制文件使用了你的处理器不支持的 CPU 指令。有两种不同的原因。

架构不匹配。 安装器下载了错误的二进制文件，例如在 ARM 服务器上的 x86。在 macOS 或 Linux 上使用 uname -m，或在 PowerShell 中使用 $env:PROCESSOR_ARCHITECTURE 检查。如果结果与你收到的二进制文件不匹配，提交 GitHub issue并附上输出。

缺失 AVX 指令集。 如果你的架构正确但仍然看到 Illegal instruction，你的 CPU 可能缺少 AVX 或二进制文件需要的其他指令。这影响大约 2013 年之前的 Intel 和 AMD 处理器，以及虚拟机管理程序不向客户机传递 AVX 的虚拟机。

在 VPS 或 VM 上，运行 grep -m1 -ow avx /proc/cpuinfo；空结果意味着 AVX 对客户机不可用。

没有原生二进制文件的解决方法；跟踪 issue #50384 了解状态，报告时在 Linux 上附上 grep -m1 "model name" /proc/cpuinfo 或在 macOS 上附上 sysctl -n machdep.cpu.brand_string 的 CPU 型号。

替代安装方法下载相同的原生二进制文件，无法解决任一原因。

macOS 上 `dyld: cannot load`

如果在安装期间看到 dyld: cannot load、dyld: Symbol not found 或 Abort trap: 6，说明二进制文件与你的 macOS 版本或硬件不兼容。

dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)
Abort trap: 6

引用 libicucore 的 Symbol not found 错误也表明你的 macOS 版本早于二进制文件支持的版本：

dyld: Symbol not found: _ubrk_clone
  Referenced from: claude-darwin-x64 (which was built for Mac OS X 13.0)
  Expected in: /usr/lib/libicucore.A.dylib

解决方案：

检查你的 macOS 版本：Claude Code 需要 macOS 13.0 或更高版本。打开 Apple 菜单并选择"关于本机"检查你的版本。
更新 macOS（如果你使用的是旧版本）。二进制文件使用了旧版 macOS 不支持的加载命令和系统库。Homebrew 等替代安装方法下载相同的二进制文件，无法解决此错误。

WSL1 上 `Exec format error`

如果在 WSL 中运行 claude 打印 cannot execute binary file: Exec format error，你在 WSL1 上遇到了 issue #38788 跟踪的已知原生二进制回归。二进制文件的程序头以 WSL1 加载器无法处理的方式更改了。

最干净的修复方法是从 PowerShell 将你的发行版转换为 WSL2：

wsl --set-version <DistroName> 2

如果你需要留在 WSL1 上，通过动态链接器调用二进制文件。将此函数添加到 WSL 内的 ~/.bashrc，如果你的主目录不同则替换路径：

claude() {
  /lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}

然后运行 source ~/.bashrc 并重试 claude。

WSL 中的 npm 安装错误

如果你在 WSL 内使用 npm install -g 安装了 Claude Code，这些问题适用。如果你使用了原生安装器，跳过此部分。

OS 或平台检测问题。 如果 npm 在安装期间报告平台不匹配，WSL 可能正在使用 Windows 的 npm。先运行 npm config set os linux，然后使用 npm install -g @anthropic-ai/claude-code --force 安装。不要使用 sudo。

运行 claude 时 exec: node: not found。 你的 WSL 环境可能正在使用 Windows 的 Node.js 安装。使用 which npm 和 which node 确认：以 /mnt/c/ 开头的路径是 Windows 二进制文件，而 Linux 路径以 /usr/ 开头。要修复此问题，通过 Linux 发行版的包管理器或通过 nvm 安装 Node。

nvm 版本冲突。 如果你在 WSL 和 Windows 中都安装了 nvm，在 WSL 中切换 Node 版本可能会失败，因为 WSL 默认导入 Windows PATH 且 Windows nvm 优先。最常见的原因是 nvm 未在你的 shell 中加载。将 nvm 加载器添加到 ~/.bashrc 或 ~/.zshrc：

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

或在当前会话中加载它：

source ~/.nvm/nvm.sh

如果 nvm 已加载但 Windows 路径仍优先，显式前置你的 Linux Node 路径：

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

Warning

避免通过 appendWindowsPath = false 禁用 Windows PATH 导入，因为这会破坏从 WSL 调用 Windows 可执行文件的能力。同样，如果你将 Node.js 用于 Windows 开发，避免从 Windows 卸载它。

安装期间的权限错误

如果原生安装器因权限错误失败，目标目录可能不可写。参见检查目录权限。

如果你之前使用 npm 安装并遇到 npm 特定的权限错误，切换到原生安装器：

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

npm 安装后找不到原生二进制文件

@anthropic-ai/claude-code npm 包通过每平台可选依赖（如 @anthropic-ai/claude-code-darwin-arm64）引入原生二进制文件。如果安装后运行 claude 打印 Could not find native binary package "@anthropic-ai/claude-code-<platform>"，检查以下原因：

可选依赖被禁用。 从你的 npm install 命令中移除 --omit=optional，从 pnpm 中移除 --no-optional，从 yarn 中移除 --ignore-optional，并检查 .npmrc 未设置 optional=false。然后重新安装。原生二进制文件仅作为可选依赖提供，因此如果被跳过则没有 JavaScript 回退。
不支持的平台。 预构建的二进制文件为 darwin-arm64、darwin-x64、linux-x64、linux-arm64、linux-x64-musl、linux-arm64-musl、win32-x64 和 win32-arm64 发布。Claude Code 不为其他平台提供二进制文件；参见系统要求。
企业 npm 镜像缺少平台包。 确保你的注册表除了元包外还镜像了所有八个 @anthropic-ai/claude-code-* 平台包。

使用 --ignore-scripts 安装不会触发此错误。将二进制文件链接到位的 postinstall 步骤被跳过，因此 Claude Code 回退到每次启动时定位和生成平台二进制文件的包装器。这可以工作但启动更慢；启用脚本重新安装以直接执行。

登录和认证

这些部分涉及登录失败、OAuth 错误和令牌问题。

重置你的登录

当登录失败且原因不明显时，干净的重新认证可以解决大多数情况：

运行 /logout 完全登出
关闭 Claude Code
使用 claude 重启并重新完成认证过程

如果登录期间浏览器没有自动打开，按 c 将 OAuth URL 复制到剪贴板，然后手动粘贴到浏览器中。当 URL 在窄终端或 SSH 终端中跨行包装且无法直接点击时，这也适用。

OAuth error: Invalid code

如果看到 OAuth error: Invalid code. Please make sure the full code was copied，说明登录代码已过期或在复制粘贴时被截断。

解决方案：

按 Enter 重试并在浏览器打开后快速完成登录
如果浏览器没有自动打开，输入 c 复制完整 URL
如果使用远程/SSH 会话，浏览器可能在错误的机器上打开。复制终端中显示的 URL 并在本地浏览器中打开。

登录后 403 Forbidden

如果登录后看到 API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}：

Claude Pro/Max 用户：在 claude.ai/settings 验证你的订阅是否有效
Anthropic Console 用户：确认你的账户具有"Claude Code"或"Developer"角色。管理员在 Anthropic Console 的 Settings → Members 中分配此角色。
在代理后面：企业代理可能干扰 API 请求。参见网络配置了解代理设置。

此组织已被禁用（有活跃订阅）

如果你有活跃的 Claude 订阅但仍看到 API Error: 400 ... "This organization has been disabled"，说明 ANTHROPIC_API_KEY 环境变量覆盖了你的订阅。这通常发生在旧雇主或项目的旧 API 密钥仍在你的 shell 配置文件中设置时。

当 ANTHROPIC_API_KEY 存在且你已批准时，Claude Code 使用该密钥而不是你订阅的 OAuth 凭证。在带 -p 标志的非交互模式下，密钥在存在时始终使用。参见认证优先级了解完整的解析顺序。

要改用你的订阅，取消设置环境变量并从你的 shell 配置文件中移除它：

unset ANTHROPIC_API_KEY
claude

检查 ~/.zshrc、~/.bashrc 或 ~/.profile 中的 export ANTHROPIC_API_KEY=... 行并移除它们以使更改永久生效。在 Windows 上，检查你的 PowerShell 配置文件 $PROFILE 和用户环境变量中的 ANTHROPIC_API_KEY。在 Claude Code 内运行 /status 以确认哪个认证方法处于活跃状态。

WSL2、SSH 或容器中的 OAuth 登录失败

当 Claude Code 在 WSL2 中、通过 SSH 在远程机器上或在容器内运行时，浏览器通常在不同的主机上打开，其重定向无法到达 Claude Code 的本地回调服务器。登录后，浏览器显示登录代码而不是自动重定向回来。在终端的 Paste code here if prompted 提示处粘贴该代码以完成登录。

如果浏览器根本没有从 WSL2 打开，将 BROWSER 环境变量设置为你的 Windows 浏览器路径：

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

或者，在交互式登录提示处按 c 复制 OAuth URL，或复制 claude auth login 打印的 URL，并在本地机器上的浏览器中打开。

如果将代码粘贴到交互式提示中没有效果，你的终端的粘贴绑定可能没有到达输入字段。尝试终端的替代粘贴快捷键，通常是 Windows Terminal 中的右键单击或 Shift+Insert，或改用 claude auth login，它从标准输入读取粘贴的代码：

claude auth login

此回退也适用于原生 Windows 或任何粘贴到交互式提示失败的终端。

未登录或令牌过期

如果 Claude Code 在会话后提示你重新登录，你的 OAuth 令牌可能已过期。

运行 /login 重新认证。如果这经常发生，检查你的系统时钟是否准确，因为令牌验证依赖于正确的时间戳。

在 macOS 上，登录也可能在钥匙串被锁定或其密码与你的账户密码不同步时失败，这阻止 Claude Code 保存凭证。运行 claude doctor 检查钥匙串访问。要手动解锁钥匙串，运行 security unlock-keychain ~/Library/Keychains/login.keychain-db。如果解锁没有帮助，打开钥匙串访问，选择 login 钥匙串，然后选择 Edit > Change Password for Keychain "login" 以与你的账户密码重新同步。

Bedrock、Vertex 或 Foundry 凭证未加载

如果你配置 Claude Code 使用云提供商并在 Bedrock 上看到 Could not load credentials from any providers，在 Vertex 上看到 Could not load the default credentials，或在 Foundry 上看到 ChainedTokenCredential authentication failed，说明你的云提供商 CLI 可能在当前 shell 中未认证。

对于 Bedrock，确认你的 AWS 凭证有效：

aws sts get-caller-identity

对于 Vertex AI，确认 ANTHROPIC_VERTEX_PROJECT_ID 和 CLOUD_ML_REGION 在你的 shell 中已设置，然后设置应用默认凭证：

gcloud auth application-default login

对于 Microsoft Foundry，确认 ANTHROPIC_FOUNDRY_API_KEY 已设置，或使用 Azure CLI 登录以便默认凭证链可以找到你的账户：

az login

如果凭证在你的终端中有效但在 VS Code 或 JetBrains 扩展中无效，IDE 进程可能没有继承你的 shell 环境。在 IDE 自己的设置中设置提供商环境变量，或从已导出它们的终端启动 IDE。

参见 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 了解完整的提供商设置。

仍然卡住

如果以上都没有解决你的问题：

检查 GitHub 仓库了解已知问题，或提交新 issue 附上你的操作系统、运行的安装命令和完整的错误输出
如果 claude --version 有效但其他地方有问题，运行 claude doctor 获取自动诊断报告
如果你可以启动会话，在 Claude Code 内使用 /feedback 报告问题

文档索引

安装和登录故障排除

查找你的错误

运行诊断检查

检查网络连接

验证你的 PATH

检查冲突的安装

检查目录权限

验证二进制文件是否工作

常见安装问题

安装脚本返回 HTML 而不是 shell 脚本

安装后 command not found: claude

curl: (56) Failure writing output to destination

TLS 或 SSL 连接错误

Failed to fetch version from downloads.claude.ai

Windows 上的错误安装命令

Windows 安装期间 The process cannot access the file

低内存 Linux 服务器上安装被终止

Docker 中安装挂起

Claude Desktop 在 Windows 上覆盖 claude 命令

Windows 上的 Claude Code 需要 Git for Windows（用于 bash）或 PowerShell

Claude Code 不支持 32 位 Windows

Linux musl 或 glibc 二进制不匹配

Illegal instruction

macOS 上 dyld: cannot load

WSL1 上 Exec format error

WSL 中的 npm 安装错误

安装期间的权限错误

npm 安装后找不到原生二进制文件

登录和认证

重置你的登录

OAuth error: Invalid code

登录后 403 Forbidden

此组织已被禁用（有活跃订阅）

WSL2、SSH 或容器中的 OAuth 登录失败

未登录或令牌过期

Bedrock、Vertex 或 Foundry 凭证未加载

仍然卡住

安装后 `command not found: claude`

`curl: (56) Failure writing output to destination`

`Failed to fetch version from downloads.claude.ai`

Windows 安装期间 `The process cannot access the file`

Claude Desktop 在 Windows 上覆盖 `claude` 命令

`Illegal instruction`

macOS 上 `dyld: cannot load`

WSL1 上 `Exec format error`