Claude Code 自动化与排错

安装与登录问题排查

1 分钟阅读

故障排查安装与登录

修复安装或登录 Claude Code 时出现的 command not found、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`，或 `Installation was killed before it could finish (exit code 137)`	释放内存或添加交换空间
`TLS connect error` 或 `SSL/TLS secure channel`	更新 CA 证书
`Failed to fetch version` 或无法访问下载服务器	检查网络和代理设置
`irm is not recognized` 或 `&& is not valid`	为你的 shell 使用正确的命令
`Cask 'claude-code' is unavailable: No Cask with this name exists`	更新 Homebrew
`'bash' is not recognized as the name of a cmdlet`	使用 Windows 安装命令
`A parameter cannot be found that matches parameter name 'fsSL'`	使用 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`	Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 凭据
`ChainedTokenCredential authentication failed` 或 `CredentialUnavailableError`	Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 凭据
上面未列出的 `API Error: 500`、`529 Overloaded`、`429`，或其他 4xx 和 5xx 错误	请参阅错误参考

如果你的问题没有列在这里，请按照下面的诊断检查逐步排查原因。

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

运行诊断检查

检查网络连接

安装程序从 downloads.claude.ai 下载。确认你能访问它：

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

在 PowerShell 中，请改为运行 curl.exe -sI。PowerShell 把 curl 别名为 Invoke-WebRequest，它会拒绝 -sI 标志。

一行 HTTP/2 200 意味着你已经访问到了服务器。如果没有任何输出，或出现 Could not resolve host，或连接超时，说明你的网络正在阻止这个连接。常见原因：

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

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

以下示例设置了这两个代理变量，然后通过你的代理运行安装程序：

macOS/Linux
Windows PowerShell

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

检查你的 PATH

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

VS Code 扩展不会把 claude 放在这个位置。它在扩展目录内为自己的聊天面板打包了一份私有的 CLI 副本，不会把它添加到 PATH 中。如果你只安装了这个扩展，~/.local/bin/claude 将不存在。运行独立安装以便能从终端使用 claude，然后继续阅读下文。

通过列出你的 PATH 条目并筛选 local/bin，检查该安装目录是否在你的 PATH 中：

macOS/Linux
Windows PowerShell
Windows CMD

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

如果这打印出 /Users/you/.local/bin 或 /home/you/.local/bin，说明该目录已经在你的 PATH 中，你可以跳到检查是否存在冲突的安装。如果没有任何输出，请把它添加到你的 shell 配置中。

对于 Zsh（macOS 上的默认 shell）：

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

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

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"

如果没有任何输出，打开系统设置，进入 Environment Variables，把 %USERPROFILE%\.local\bin 添加到你的用户 PATH 变量中。重启你的终端。

确认修复是否成功：

claude --version

检查是否存在冲突的安装

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

macOS/Linux
Windows PowerShell

列出你 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 命令打印 No such file or directory，这不是一个错误。它意味着该位置没有安装任何内容，因此继续下一项检查。

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 提示 command not found，请先前往检查你的 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

这些都意味着该安装网址返回的是一个 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
```

Homebrew cask 不可用或已过时

当你本地 Homebrew cask 索引的副本早于该 cask 的发布时间时，Homebrew 会报告 Error: Cask 'claude-code' is unavailable: No Cask with this name exists。刷新索引并重试：

brew update
brew install --cask claude-code

如果 Homebrew 安装的 Claude Code 版本比你预期的更旧，通常也是同一个过时索引导致的。claude-code 这个 cask 跟踪的是稳定渠道，通常比最新发布版本落后约一周；要获取最新版本，请改为运行 brew install --cask claude-code@latest。关于这两个 cask 的区别，请参阅配置发布渠道。

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 上，在运行安装程序之前，在 PowerShell 中启用 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、A parameter cannot be found that matches parameter name 'fsSL'，或 'bash' is not recognized as the name of a cmdlet，说明你复制的安装命令对应的是另一种 shell 或操作系统。

irm 未被识别：你所在的是 CMD，不是 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
```
A parameter cannot be found that matches parameter name 'fsSL'：你在 Windows PowerShell 中运行了 macOS/Linux 的 curl -fsSL ... | bash 安装程序，而在 PowerShell 中 curl 是 Invoke-WebRequest 的别名，会拒绝 -fsSL 标志。请改用 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 服务器上安装被终止

安装期间出现 Killed 信息，通常意味着 Linux 的内存溢出（OOM）杀手因为系统内存不足而终止了 claude install 这一步。这在小型 VPS 和云实例上很常见。安装脚本会报告原因，并以代码 137 退出：

Setting up Claude Code...
bash: line 142: 34803 Killed    "$binary_path" install ${TARGET:+"$TARGET"}
Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.
Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

在 v2.1.200 之前，该脚本只会以 shell 自身裸露的 Killed 那一行退出，没有任何说明。

安装大约需要 512 MB 的空闲内存，运行 Claude Code 则需要更多。请参阅系统要求。

解决方法：

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

创建一个 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 内存。

在 Docker 中安装卡死

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

解决方法：

在运行安装程序之前设置一个工作目录。从 / 运行时，安装程序会扫描整个文件系统，导致内存用量过高。设置 WORKDIR 可以把扫描范围限制在一个小目录内：
```
WORKDIR /tmp
RUN curl -fsSL https://claude.ai/install.sh | bash
```
如果使用 Docker Desktop，提高 Docker 内存限制：
```
docker build --memory=4g .
```

Claude Desktop 覆盖了 Windows 上的 `claude` 命令

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

将 Claude Desktop 更新到最新版本即可修复这个问题。

Claude Code on Windows requires either Git for Windows (for bash) or 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 仍然报告找不到它，可能是端点安全软件（例如 AppLocker、组策略软件限制策略或 EDR 代理）在干扰。在 v2.1.116 之前的版本上，Claude Code 会生成一个子进程（cmd.exe）来验证该路径，而这些策略可能会阻止它——一个常见的信号是：直接在 PowerShell 中运行 cmd.exe /c dir "C:\Program Files\Git\bin\bash.exe" 能正常工作，但由 claude.exe 启动时却静默失败。

Claude Code v2.1.116 及更高版本会直接检查文件系统，因此请先更新。如果在当前版本上错误仍然存在，请让你的 IT 团队在你的端点保护策略中，将 claude.exe 及其生成的进程（包括 cmd.exe 和 bash.exe）加入允许列表。

Claude Code does not support 32-bit 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 处的清单手动下载正确的二进制文件。附上 ldd --version 和 ls /lib/libc.musl* 的输出，提交一个GitHub issue。
如果你确实使用的是 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 或虚拟机上，运行 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 菜单，选择 About This Mac 以检查你的版本。
如果你使用的是较旧版本，请更新 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 install 错误

如果你是在 WSL 内用 npm install -g 安装 Claude Code 的，以下问题适用于你。如果你使用的是原生安装程序，请跳过本节。

操作系统或平台检测问题。 如果 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"

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

安装期间的权限错误

如果原生安装程序因权限错误而失败，目标目录可能不可写。请参阅检查目录权限。

如果你之前用 npm 安装过，正在遇到 npm 特有的权限错误，请切换到原生安装程序：

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

npm install 之后找不到原生二进制文件

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

可选依赖被关闭了。 从你的 npm 安装命令中移除 --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 不为其他平台提供二进制文件；请参阅系统要求。在 FreeBSD 上，安装程序会报告该平台不受支持。在 v2.1.205 之前，它会把 FreeBSD 当作 Linux 处理，下载一个无法运行的二进制文件。
企业 npm 镜像缺少平台软件包。 请确保你的注册表在元软件包之外，还镜像了全部八个 @anthropic-ai/claude-code-* 平台软件包。

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

以下小节说明登录失败、OAuth 错误和令牌问题。

当登录失败、且原因不明显时，一次干净的重新身份验证能解决大多数情况：

运行 /logout 完全退出登录
关闭 Claude Code
用 claude 重新启动，再次完成身份验证流程

如果登录期间浏览器没有自动打开，按 c 把 OAuth 网址复制到剪贴板，然后手动粘贴到浏览器中。当该网址在一个较窄的终端或 SSH 终端中跨行显示、无法直接点击时，这个方法同样适用。

OAuth error: Invalid code

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

解决方法：

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

如果登录后你看到 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 请求。关于代理搭建，请参阅网络配置。

拥有有效订阅时出现 This organization has been disabled

如果你在拥有一个有效 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 上，检查你 $PROFILE 处的 PowerShell 配置文件，以及你用户环境变量中的 ANTHROPIC_API_KEY。在 Claude Code 内运行 /status，确认当前生效的身份验证方式。

当 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 网址，或复制 claude auth login 打印的网址，在你本地机器的浏览器中打开它。

如果把代码粘贴到交互式提示中没有任何反应，可能是你终端的粘贴绑定没有到达输入框。请尝试你终端的备用粘贴快捷键（在 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。如果解锁没有帮助，打开 Keychain Access，选择 login 密钥链，选择 Edit > Change Password for Keychain "login"，将其与你的账号密码重新同步。

Bedrock、Agent Platform 或 Foundry 凭据未加载

如果你配置了 Claude Code 使用一个云服务商，并在 Amazon Bedrock 上看到 Could not load credentials from any providers，在 Google Cloud 的 Agent Platform 上看到 Could not load the default credentials，或在 Microsoft Foundry 上看到 ChainedTokenCredential authentication failed，很可能是你的云服务商 CLI 在当前 shell 中没有完成身份验证。

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

aws sts get-caller-identity

对于 Google Cloud 的 Agent Platform，确认你 shell 中已设置 ANTHROPIC_VERTEX_PROJECT_ID 和 CLOUD_ML_REGION，然后设置应用默认凭据：

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 Cloud 的 Agent Platform，或 Microsoft Foundry。

仍然卡住了

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

查看 GitHub 仓库中的已知问题，或附上你的操作系统、你运行的安装命令，以及完整的错误输出，提交一个新的 issue
如果 claude --version 能正常工作，但其他方面出了问题，运行 claude doctor 获取自动化的诊断报告
如果你能启动一个会话，在 Claude Code 内使用 /feedback 报告这个问题

上一页单体仓库与大型代码库下一页性能与稳定性排查

On this page

故障排查安装与登录

查找你的错误

运行诊断检查

检查网络连接

检查你的 PATH

检查是否存在冲突的安装

检查目录权限

验证该二进制文件能正常工作

常见安装问题

安装脚本返回了 HTML，而不是一个 shell 脚本

安装完成后出现 command not found: claude

curl: (56) Failure writing output to destination

Homebrew cask 不可用或已过时

TLS 或 SSL 连接错误

Failed to fetch version from downloads.claude.ai

Windows 上错误的安装命令

Windows 安装期间出现 The process cannot access the file

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

在 Docker 中安装卡死

Claude Desktop 覆盖了 Windows 上的 claude 命令

Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

Claude Code does not support 32-bit Windows

Linux musl 或 glibc 二进制文件不匹配

Illegal instruction

macOS 上出现 dyld: cannot load

WSL1 上出现 Exec format error

WSL 中的 npm install 错误

安装期间的权限错误

npm install 之后找不到原生二进制文件

登录与身份验证

重置你的登录

OAuth error: Invalid code

登录后出现 403 Forbidden

拥有有效订阅时出现 This organization has been disabled

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

未登录或令牌过期

Bedrock、Agent Platform 或 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`