排查安装和登录问题

如果安装失败或无法登录，请在下面找到您的错误。有关 Claude Code 正常工作后的运行时问题，请参阅 Troubleshooting。有关配置问题（例如设置未应用或 hooks 未触发），请参阅 Debug your configuration。

查找您的错误

将您看到的错误消息或症状与解决方案相匹配：

您看到的内容	解决方案
`command not found: claude` 或 `'claude' is not recognized`	修复您的 PATH
`syntax error near unexpected token '<'`	安装脚本返回 HTML
`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 git-bash`	安装或配置 Git Bash
`Claude Code does not support 32-bit Windows`	打开 Windows PowerShell，而不是 x86 条目
`Error loading shared library`	您的系统的二进制变体错误
`Illegal instruction`	架构或 CPU 指令集不匹配
WSL 中 `cannot execute binary file: Exec format error`	WSL1 上的 Exec 格式错误
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 在您的国家/地区不可用。请参阅 supported countries。
`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 错误	请参阅 Error reference

如果您的问题未列出，请按照下面的诊断检查来缩小原因范围。

如果您宁愿完全跳过终端，Claude Code Desktop 应用可让您通过图形界面安装和使用 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 团队询问，或检查您的浏览器代理设置。此示例设置两个代理变量，然后通过您的代理运行安装程序：

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

$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 中列出的目录中搜索程序，安装程序在 macOS/Linux 上将 claude 放在 ~/.local/bin/claude，或在 Windows 上放在 %USERPROFILE%\.local\bin\claude.exe。通过列出您的 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 中，您可以跳到 Check for conflicting installations。如果没有输出，请将其添加到您的 shell 配置。对于 Zsh（macOS 上的默认值）：

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

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

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

或者，关闭并重新打开您的终端。验证修复是否有效：

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 安装可能导致版本不匹配或意外行为。检查已安装的内容：

macOS/Linux
Windows PowerShell

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

which -a claude

如果这不打印任何内容，您的 PATH 上还没有 claude。返回到 Verify your 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 说命令未找到，请先转到 Verify your PATH；下面的命令假设 claude 在您的 PATH 上。确认二进制文件存在且可执行：

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

在 Windows 上，使用 PowerShell：

Get-Command claude | Select-Object Source

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

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.

这意味着安装 URL 返回了 HTML 页面而不是安装脚本。如果 HTML 页面显示”App unavailable in region”，Claude Code 在您的国家/地区不可用。请参阅 supported countries。否则，这可能由于网络问题、区域路由或临时服务中断而发生。 解决方案：

使用替代安装方法：在 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 搜索路径中。请参阅 Verify your PATH 以获取每个平台上的修复。

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

curl ... | bash 命令下载脚本并将其传送到 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 使用 Keychain 信任存储；更新 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 以便安装程序可以通过它路由。有关详细信息，请参阅 proxy configuration。
```
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
```

低内存 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 杀手终止了该进程，因为系统内存不足。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 会打开 Desktop 应用而不是 CLI。更新 Claude Desktop 到最新版本以修复此问题。

Windows 上的 Claude Code 需要 Git Bash

Windows 上的 Claude Code 需要 Git for Windows，它提供 Git Bash 来运行 shell 命令。 如果未安装 Git，从 git-scm.com/downloads/win 下载它。在设置期间，选择”Add to PATH”。安装后重启您的终端。 如果已安装 Git 但 Claude Code 找不到它，请在您的 settings.json file 中设置路径：

{
  "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 位操作系统。请参阅 system requirements。

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。如果结果与您收到的二进制文件不匹配，请 file a GitHub issue 并提供输出。 较旧 CPU 上缺失指令集。 如果您的架构正确但仍然看到 Illegal instruction，您的 CPU 可能缺少二进制文件需要的 AVX 或其他指令。这影响大约 2013 年之前的英特尔和 AMD 处理器。目前没有本机二进制文件解决方法；跟踪 issue #50384 以获取状态，并在报告时包括您的 CPU 型号（来自 Linux 上的 cat /proc/cpuinfo | grep "model name" | head -1 或 macOS 上的 sysctl -n machdep.cpu.brand_string）。替代安装方法下载相同的本机二进制文件，不会解决任一原因。

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 安装错误

如果您在 WSL 内使用 npm install -g 安装了 Claude Code，这些问题适用。如果您使用了 native installer，请跳过此部分。 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 环境可能使用 Node.js 的 Windows 安装。使用 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 卸载它。

安装期间的权限错误

如果本机安装程序因权限错误而失败，目标目录可能不可写。请参阅 Check directory permissions。如果您之前使用 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 安装命令中删除 --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 不为其他平台提供二进制文件；请参阅 system requirements。
企业 npm 镜像缺少平台包。 确保您的注册表除了元包外还镜像所有八个 @anthropic-ai/claude-code-* 平台包。

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

登录和身份验证

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

重置您的登录

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

运行 /logout 完全注销
关闭 Claude Code
使用 claude 重启并再次完成身份验证过程

如果浏览器在登录期间不会自动打开，按 c 将 OAuth URL 复制到您的剪贴板，然后手动将其粘贴到浏览器中。当 URL 在狭窄或 SSH 终端中跨行换行且无法直接点击时，这也有效。

OAuth 错误：无效代码

如果您看到 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 请求。有关代理设置，请参阅 network configuration。

此组织已被禁用，但有活跃订阅

如果您看到 API Error: 400 ... "This organization has been disabled"，尽管有活跃的 Claude 订阅，ANTHROPIC_API_KEY 环境变量正在覆盖您的订阅。这通常发生在来自前一个雇主或项目的旧 API 密钥仍在您的 shell 配置文件中设置时。当 ANTHROPIC_API_KEY 存在且您已批准它时，Claude Code 使用该密钥而不是您的订阅的 OAuth 凭证。在使用 -p 标志的非交互模式下，当存在时始终使用该密钥。有关完整的解决顺序，请参阅 authentication precedence。要改用您的订阅，请取消设置环境变量并从您的 shell 配置文件中删除它：

unset ANTHROPIC_API_KEY
claude

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

OAuth 登录在 WSL2 中失败

WSL2 中基于浏览器的登录可能以两种方式失败：WSL 无法打开您的 Windows 浏览器，或终端不会接受粘贴的授权代码。如果浏览器不打开，将 BROWSER 环境变量设置为您的 Windows 浏览器路径：

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

或在登录提示处按 c 复制 OAuth URL 并自己将其粘贴到您的 Windows 浏览器中。如果浏览器打开但将代码粘贴回终端不起作用，您的终端的粘贴绑定可能无法到达提示。尝试您的终端的替代粘贴快捷键，通常在 Windows Terminal 中是右键单击或 Shift+Insert，或在交互式 UI 外运行登录：

claude auth login

此回退也适用于本机 Windows 或任何将代码粘贴到交互式提示中失败的终端。

未登录或令牌已过期

如果 Claude Code 在会话后提示您再次登录，您的 OAuth 令牌可能已过期。运行 /login 重新身份验证。如果这经常发生，检查您的系统时钟是否准确，因为令牌验证取决于正确的时间戳。在 macOS 上，当 Keychain 被锁定或其密码与您的账户密码不同步时，登录也可能失败，这会阻止 Claude Code 保存凭证。运行 claude doctor 检查 Keychain 访问。要手动解锁 Keychain，请运行 security unlock-keychain ~/Library/Keychains/login.keychain-db。如果解锁无法帮助，打开 Keychain Access，选择 login keychain，并选择”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 repository 以了解已知问题，或使用您的操作系统、您运行的安装命令和完整错误输出打开新问题
如果 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 上的错误安装命令

低内存 Linux 服务器上安装被杀死

Docker 中安装挂起

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

Windows 上的 Claude Code 需要 Git Bash

Claude Code 不支持 32 位 Windows

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

`Illegal instruction`

macOS 上的 `dyld: cannot load`

WSL1 上的 `Exec format error`

WSL 中的 npm 安装错误

安装期间的权限错误

npm 安装后未找到本机二进制文件

登录和身份验证

重置您的登录

OAuth 错误：无效代码

登录后 403 Forbidden

此组织已被禁用，但有活跃订阅

OAuth 登录在 WSL2 中失败

未登录或令牌已过期

Bedrock、Vertex 或 Foundry 凭证未加载

仍然卡住

代理

工具和插件

自动化

故障排除

Documentation Index

​查找您的错误

​运行诊断检查

​检查网络连接

​验证您的 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 上的错误安装命令

​低内存 Linux 服务器上安装被杀死

​Docker 中安装挂起

​Claude Desktop 在 Windows 上覆盖 claude 命令

​Windows 上的 Claude Code 需要 Git Bash

​Claude Code 不支持 32 位 Windows

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

​Illegal instruction

​macOS 上的 dyld: cannot load

​WSL1 上的 Exec format error

​WSL 中的 npm 安装错误

​安装期间的权限错误

​npm 安装后未找到本机二进制文件

​登录和身份验证

​重置您的登录

​OAuth 错误：无效代码

​登录后 403 Forbidden

​此组织已被禁用，但有活跃订阅

​OAuth 登录在 WSL2 中失败

​未登录或令牌已过期

​Bedrock、Vertex 或 Foundry 凭证未加载

​仍然卡住

查找您的错误

运行诊断检查

检查网络连接

验证您的 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 上的错误安装命令

低内存 Linux 服务器上安装被杀死

Docker 中安装挂起

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

Windows 上的 Claude Code 需要 Git Bash

Claude Code 不支持 32 位 Windows

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

`Illegal instruction`

macOS 上的 `dyld: cannot load`

WSL1 上的 `Exec format error`

WSL 中的 npm 安装错误

安装期间的权限错误

npm 安装后未找到本机二进制文件

登录和身份验证

重置您的登录

OAuth 错误：无效代码

登录后 403 Forbidden

此组织已被禁用，但有活跃订阅

OAuth 登录在 WSL2 中失败

未登录或令牌已过期

Bedrock、Vertex 或 Foundry 凭证未加载

仍然卡住