create: 2026-07-08

update: 2026-07-31

author: thinkycx

title: 【译】安装排错

description: 修复安装或登录 Claude Code 时的 command not found、PATH、权限、网络和认证错误。包含各平台的诊断步骤和常见问题解决方案。

category: translation

tags: claude-code, translation

refs: https://code.claude.com/docs/en/troubleshoot-install.md en-source/troubleshoot-install.md

安装和登录排错¶

修复安装或登录 Claude Code 时的 command not found、PATH、权限、网络和认证错误。

安装失败或无法登录时，在下面找到你的错误。 运行时问题参见故障排除。配置问题参见调试配置。

错误速查表¶

你看到的	解决方案
`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`	检查连通性或使用替代安装方式
`Killed` / 退出码 137	释放内存或添加 swap
`TLS connect error` / `SSL/TLS secure channel`	更新 CA 证书
`Failed to fetch version` 或无法访问下载服务器	检查网络和代理设置
`irm is not recognized` / `&& is not valid`	使用正确的安装命令
`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`	打开正确的 PowerShell
`The process cannot access the file ... because it is being used by another process`	清除下载文件夹并重试
`Error loading shared library`	二进制变体不匹配
`Illegal instruction`	架构或 CPU 指令集不匹配
`cannot execute binary file: Exec format error`（WSL 中）	WSL1 原生二进制回归
PowerShell 安装完成但 `claude` 未找到或显示旧版本	将安装目录添加到 PATH，然后打开新终端
`dyld: cannot load`、`dyld: Symbol not found` 或 macOS 上 `Abort trap`	二进制不兼容
`claude update` 在 `Checking for updates` 后挂起，或 `claude doctor` 无输出挂起	移动 shell 配置路径下的目录
`Invoke-Expression`/`iex` 解析错误引用 HTML/CSS，或 `ParserError`/`ParseException`	安装脚本返回 HTML
`running scripts is disabled on this system` 或 `PSSecurityException`	允许 npm shim 运行
`Error: claude native binary not installed`	完成 npm 安装
`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/Agent Platform/Foundry 凭据
`ChainedTokenCredential authentication failed` 或 `CredentialUnavailableError`	Bedrock/Agent Platform/Foundry 凭据
`API Error: 500`、`529 Overloaded`、`429` 或其他 4xx/5xx 错误	参见错误参考

如果你的问题不在列表中，按下面的诊断步骤缩小范围。

[!TIP]
如果想跳过终端，Claude Code Desktop 应用提供图形界面安装和使用。macOS 下载这里，Windows 下载这里。Linux 按 Linux 安装指南通过 apt 安装。

运行诊断检查¶

检查网络连通性¶

安装程序从 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 表示到达服务器。其他结果指向原因：

403：通常是代理或网络过滤器阻止了主机，或 Claude Code 在你的地区不可用
5xx：通常是临时服务问题，等几分钟重试

无输出、Could not resolve host 或连接超时表示网络阻止了连接。常见原因：

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

如果在企业代理后面，在安装前设置 HTTPS_PROXY 和 HTTP_PROXY：

macOS/Linux：

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

Windows PowerShell：

$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 时，安装目录不在 PATH 中。 Shell 在 PATH 列出的目录中搜索程序，安装器将 claude 放在 macOS/Linux 的 ~/.local/bin/claude 或 Windows 的 %USERPROFILE%\.local\bin\claude.exe。

[!NOTE]
VS Code 扩展不会将 claude 放在此位置。它在扩展目录内捆绑私有 CLI 副本用于自己的聊天面板，不会添加到 PATH。如果你只安装了扩展，~/.local/bin/claude 不会存在。运行独立安装以便从终端使用 claude。

检查安装目录是否在 PATH 中：

macOS/Linux：

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

如果输出 /Users/you/.local/bin 或 /home/you/.local/bin，目录已在 PATH 中，跳到检查冲突安装。如果无输出，添加到 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

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

Windows PowerShell：

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

如果无输出，添加安装目录到用户 PATH：

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

Windows CMD：

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

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

验证修复：

claude --version

检查冲突安装¶

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

macOS/Linux：

which -a claude

如果无输出，PATH 中没有 claude。回到验证 PATH。

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

ls -la ~/.local/bin/claude

原生安装显示为指向 ~/.local/share/claude/versions/ 的符号链接。

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

Windows PowerShell：

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

保留一个（推荐原生安装 ~/.local/bin/claude），移除其他：

npm uninstall -g @anthropic-ai/claude-code   # 移除 npm 全局安装
rm -rf ~/.claude/local                         # 移除旧版本地安装
brew uninstall --cask claude-code              # macOS 移除 Homebrew 安装

Windows 上移除 WinGet 安装：

winget uninstall Anthropic.ClaudeCode

检查目录权限¶

安装器需要 ~/.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。

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

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

Windows：

Get-Command claude | Select-Object Source

Linux 上检查缺失的共享库：

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

确认二进制可执行：

claude --version

常见安装问题¶

安装脚本返回 HTML¶

运行安装命令时看到以下错误之一：

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

PowerShell 上，同一问题表现为解析错误，iex 尝试将 HTML 和 CSS 作为 PowerShell 运行：

iex : At line:1 char:2310
+ ... igin="anonymous"/><script type="text/javascript">!function(o,c){var n ...
Missing argument in parameter list.

措辞因 PowerShell 版本和系统语言而异：可能看到 Missing expression after unary operator '--' 或 ParserError + ParseException。引用文本中出现 HTML 标签或 CSS 即可识别此故障。

你也可能看到无 HTML 正文的 403：

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

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

无正文的 403 通常同因，但也可能是企业代理或防火墙阻止下载。如果你在支持的国家仍看到 403，先按检查网络连通性排查再尝试替代安装方式。

解决：

使用替代安装方式：

macOS：
bash brew install --cask claude-code

Windows：
powershell winget install Anthropic.ClaudeCode

然后运行 claude --version 确认：应输出版本号如 2.1.211 (Claude Code)。如果 shell 报未找到 claude，打开新终端窗口重试。

等几分钟重试：问题通常是临时的。

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)）表示 Bash 未收到完整脚本。退出码 56 表示下载被中断，退出码 23 表示 curl 无法将接收的内容写入管道（通常因为 Bash 提前退出）。

解决：

检查网络稳定性：Claude Code 二进制托管在 downloads.claude.ai。测试可达性：
bash curl -sI https://downloads.claude.ai/claude-code-releases/latest
HTTP/2 200 表示到达服务器，原始失败可能是间歇性的，重试安装命令。
尝试替代安装方式：

macOS：
bash brew install --cask claude-code

Windows：
powershell winget install Anthropic.ClaudeCode

Homebrew cask 不可用或过时¶

Homebrew 报告 Error: Cask 'claude-code' is unavailable 时，你的本地 cask 索引早于 cask 发布。刷新索引并重试：

brew update
brew install --cask claude-code

如果 Homebrew 安装的版本比预期旧，同样是索引过时。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 证书：
bash sudo apt-get update && sudo apt-get install ca-certificates
macOS 上系统 curl 使用 Keychain 信任存储；更新 macOS 本身即更新根证书。
Windows 上启用 TLS 1.2：
powershell [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 指向企业 CA 包：
bash curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash
安装后设置 NODE_EXTRA_CA_CERTS：
bash export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
Windows 网络阻止撤销检查时（CRYPT_E_NO_REVOCATION_CHECK、CRYPT_E_REVOCATION_OFFLINE），使用 PowerShell 安装器（通过 .NET 下载，不会在撤销服务器不可达时失败）：
powershell irm https://claude.ai/install.ps1 | iex
也可使用 winget install Anthropic.ClaudeCode。

Failed to fetch version from downloads.claude.ai¶

安装器无法到达下载服务器，通常表示 downloads.claude.ai 在你的网络上被阻止。

解决：

直接测试连通性：curl -sI https://downloads.claude.ai/claude-code-releases/latest
如果在代理后面，设置 HTTPS_PROXY。参见代理配置。
如果在受限网络上，尝试其他网络或 VPN，或使用替代安装方式（macOS 用 brew install --cask claude-code，Windows 用 winget install Anthropic.ClaudeCode）。

Windows 上使用错误安装命令¶

irm not recognized → 你在 CMD 而非 PowerShell。打开 PowerShell 运行：
powershell irm https://claude.ai/install.ps1 | iex
或留在 CMD 使用 CMD 安装器：
batch curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
&& not valid → 你在 PowerShell 但用了 CMD 命令。用 PowerShell 安装器。
-fsSL 参数错误 → 你在 Windows PowerShell 中用了 macOS/Linux 命令（PowerShell 的 curl 是 Invoke-WebRequest 别名）。用 PowerShell 安装器。
bash not recognized → 你在 Windows 上用了 macOS/Linux 安装器。用 PowerShell 安装器。

running scripts is disabled on this system¶

通过 npm 安装或运行 Claude Code 时 PowerShell 可能报 SecurityError：

npm : File C:\Program Files\nodejs\npm.ps1 cannot be loaded because running scripts is disabled on this system.

PowerShell 的执行策略阻止了 npm 创建的 .ps1 启动脚本。

解决：

为用户允许本地创建的脚本：
powershell Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
改用 .cmd 启动器：npm.cmd 和 claude.cmd 做同样的事，策略不涵盖它们。
使用 PowerShell 安装器 代替 npm。它安装二进制而非 .ps1 脚本。

Windows 安装时文件被占用¶

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 消息通常表示 OOM killer 终止了进程。 安装脚本报告原因并以退出码 137 退出：

Setting up Claude Code...
bash: line 183: 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 空闲内存，运行需要更多。参见系统要求。

解决： 添加 swap 空间：

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
curl -fsSL https://claude.ai/install.sh | bash

Docker 中安装挂起¶

以 root 在 / 安装时可能挂起。

解决： 设置工作目录。从 / 运行时安装器扫描整个文件系统导致内存过高。设置 WORKDIR 限制扫描范围：

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

增加 Docker 内存限制：

docker build --memory=4g .

claude update 或 claude doctor 挂起¶

claude update 和 claude doctor 扫描 shell 配置文件中是否有过时的 claude 别名：~/.zshrc、~/.bashrc、~/.config/fish/config.fish，macOS 上还检查第一个存在的 ~/.bash_profile、~/.bash_login 或 ~/.profile。v2.1.214 起，如果某个路径是目录，Claude Code 跳过它正常完成。v2.1.214 之前，某路径为目录时两个命令都会挂起。

如果在早期版本遇到挂起，找到该目录：

ls -ld ~/.zshrc ~/.bashrc ~/.bash_profile ~/.bash_login ~/.profile ~/.config/fish/config.fish

输出中以 d 开头的行标识为目录。将该目录移走，或更新到 v2.1.214+。由于 claude update 在受影响版本上挂起，通过重新运行安装脚本来更新。

Claude Desktop 覆盖 Windows 上的 claude 命令¶

如果安装了旧版 Claude Desktop，它可能在 WindowsApps 目录注册了 Claude.exe，在 PATH 中优先于 Claude Code CLI。运行 claude 打开桌面应用而非 CLI。

将 Claude Desktop 更新到最新版本即可修复。

Windows 需要 Git for Windows 或 PowerShell¶

Git for Windows 是可选的。Claude Code 在 Git Bash 不存在时使用 PowerShell 工具，所以此错误表示两个 shell 都未找到。

如果 PowerShell 不在 PATH 中，默认位置是 C:\Windows\System32\WindowsPowerShell\v1.0\。将该目录加入 PATH，或安装 PowerShell 7。

要安装 Git for Windows，从 git-scm.com/downloads/win 下载。安装时选择 "Add to PATH"。安装后重启终端。

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

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

如果路径正确且文件存在 但 Claude Code 仍不使用它，先检查文件名。Claude Code 只接受名为 bash.exe、sh.exe、bash 或 sh 的文件；其他名称（如 git-bash.exe）会被忽略。v2.1.219 之前 Claude Code 使用任何存在的文件作为 shell。

如果文件名正确，端点安全软件（如 AppLocker、组策略软件限制或 EDR 代理）可能在干扰。Claude Code v2.1.116+ 直接检查文件系统，先更新。如果错误持续，让 IT 团队在端点保护策略中允许 claude.exe 及其子进程。

不支持 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），安装器可能下载了错误的二进制变体。

解决：

检查系统使用哪个 libc：
bash ldd --version 2>&1 | head -1
输出包含 GNU libc 或 GLIBC 表示 glibc；包含 musl 表示 musl。
如果在 glibc 系统但得到了 musl 二进制，删除安装并重装。提交 GitHub issue 附上 ldd --version 和 ls /lib/libc.musl* 输出。
如果确实在 musl 上（如 Alpine），安装依赖：
bash apk add libgcc libstdc++ ripgrep

Illegal instruction¶

运行 claude 或安装器时输出 Illegal instruction，原生二进制使用你的处理器不支持的 CPU 指令。两种原因：

架构不匹配。 安装器下载了错误二进制（如 ARM 上的 x86）。用 uname -m 检查。

缺少 AVX 指令集。 架构正确但仍报错，你的 CPU 可能缺少 AVX（影响约 2013 年前的 Intel/AMD 处理器，以及不传递 AVX 的虚拟机）。

在 VPS/VM 上运行 grep -m1 -ow avx /proc/cpuinfo；空结果表示 AVX 不可用。

无原生二进制解决方案；跟踪 issue #50384。替代安装方式下载相同二进制，不能解决问题。

macOS 上的 dyld: cannot load¶

dyld: cannot load、dyld: Symbol not found 或 Abort trap: 6 表示二进制与你的 macOS 版本或硬件不兼容。

引用 libicucore 的 Symbol not found 错误也表示 macOS 版本比二进制支持的更旧。

解决： Claude Code 需要 macOS 13.0 或更高版本。打开 Apple 菜单 → About This Mac 检查版本。如果版本较旧需要更新 macOS。替代安装方式（如 Homebrew）下载相同二进制，无法解决此错误。

WSL1 上的 Exec format error¶

在 WSL 中运行 claude 输出 cannot execute binary file: Exec format error，你在 WSL1 上遇到已知的原生二进制回归（issue #38788）。

最干净的修复是转为 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 重试。

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。

exec: node: not found。 WSL 环境可能使用了 Windows 的 Node.js。用 which npm 和 which node 确认：/mnt/c/ 开头是 Windows 二进制。通过 Linux 包管理器或 nvm 安装 Node。

nvm 版本冲突。 WSL 默认导入 Windows PATH，Windows nvm 可能优先。在 ~/.bashrc 或 ~/.zshrc 中添加 nvm 加载器：

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

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

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

[!WARNING]
避免通过 appendWindowsPath = false 禁用 Windows PATH 导入，这会破坏从 WSL 调用 Windows 可执行文件的能力。

npm 安装后原生二进制未找到¶

@anthropic-ai/claude-code npm 包将原生二进制作为平台可选依赖下载（如 @anthropic-ai/claude-code-darwin-arm64）。npm 然后运行包的 postinstall 脚本将二进制复制到位作为 claude 命令；在此之前 claude 是占位脚本。如果下载或 postinstall 步骤被跳过，运行 claude 会输出：

Error: claude native binary not installed.

Either postinstall did not run (--ignore-scripts, some pnpm configs)
or the platform-native optional dependency was not downloaded
(--omit=optional).

Run the postinstall manually (adjust path for local vs global install):
  node node_modules/@anthropic-ai/claude-code/install.cjs

Or reinstall without --ignore-scripts / --omit=optional.

检查以下原因：

可选依赖被禁用。 移除 --omit=optional、--no-optional、--ignore-optional，检查 .npmrc 中的 optional=false。重装。
安装脚本被禁用。 --ignore-scripts 跳过 postinstall 但仍下载平台包。运行 node node_modules/@anthropic-ai/claude-code/install.cjs，或重装不带该标志。
不支持的平台。 预构建二进制发布于 darwin-arm64、darwin-x64、linux-x64、linux-arm64、linux-x64-musl、linux-arm64-musl、win32-x64 和 win32-arm64。
企业 npm 镜像缺少平台包。 确保镜像包含全部 8 个 @anthropic-ai/claude-code-* 平台包。

权限错误¶

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

如果之前用 npm 安装遇到 npm 权限错误，切换到原生安装器：

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

登录和认证¶

重置登录¶

登录失败时，干净的重新认证可解决大多数情况：

运行 /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 在本地浏览器中打开。

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

This organization has been disabled¶

尽管有活跃订阅但看到此错误，一个 ANTHROPIC_API_KEY 环境变量覆盖了你的订阅。 当 ANTHROPIC_API_KEY 存在且你已批准时，Claude Code 使用该 key 而非订阅的 OAuth 凭据。

要使用订阅，取消设置环境变量：

unset ANTHROPIC_API_KEY
claude

检查 ~/.zshrc、~/.bashrc 或 ~/.profile 中的 export ANTHROPIC_API_KEY=... 行并移除。Windows 上检查 PowerShell profile（$PROFILE）和用户环境变量。运行 /status 确认活跃的认证方式。

WSL2/SSH/容器中 OAuth 登录失败¶

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

如果浏览器不从 WSL2 打开，设置 BROWSER 环境变量：

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

或在交互式登录提示处按 c 复制 OAuth URL，在本地浏览器中打开。

如果粘贴码到交互式提示无反应，你终端的粘贴绑定可能未到达输入字段。尝试终端的备用粘贴快捷键（Windows Terminal 中常为右键或 Shift+Insert），或使用 claude auth login（从标准输入读取粘贴的码）：

claude auth login

Not logged in or token expired¶

如果 Claude Code 在会话后提示重新登录，OAuth token 可能已过期。 运行 /login 重新认证。

频繁发生时，检查系统时钟准确性（token 验证依赖正确时间戳）。

一台机器上的并行会话共享保存的登录并协调续期，只有一个进程刷新 token。v2.1.211 之前，从休眠唤醒可能导致两个会话用相同 token 续期，从而撤销保存的登录并提示所有打开的会话同时重新登录。

macOS 上，当 Keychain 锁定或密码与账户不同步时登录也可能失败。运行 claude doctor 检查 Keychain 访问。手动解锁 Keychain：security unlock-keychain ~/Library/Keychains/login.keychain-db。如果解锁无效，打开 Keychain Access，选择 login 钥匙串，选择 Edit > Change Password for Keychain "login" 将其与账户密码同步。

Bedrock、Agent Platform 或 Foundry 凭据未加载¶

配置 Claude Code 使用云提供商后看到凭据加载错误，云提供商 CLI 可能未在当前 shell 中认证。

Amazon Bedrock：

aws sts get-caller-identity

Google Cloud Agent Platform：确认 ANTHROPIC_VERTEX_PROJECT_ID 和 CLOUD_ML_REGION 已设置，然后：

gcloud auth application-default login

Microsoft Foundry：确认 ANTHROPIC_FOUNDRY_API_KEY 已设置，或：

az login

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

完整设置参见 Amazon Bedrock、Google Cloud Agent Platform 或 Microsoft Foundry。

仍然卡住¶

检查 GitHub 仓库的已知问题，或附上操作系统、安装命令和完整错误输出提交新 issue
如果 claude --version 有效但有其他问题，运行 claude doctor 获取自动诊断报告
如果能启动会话，使用 /feedback 报告问题
如果问题与账户相关（登录循环、订阅未识别、组织被禁用），联系 Anthropic 支持：在 claude.ai（Console 用户：platform.claude.com）登录，点击左下角头像，选择 Get help。参见 How to get support

安装和登录排错¶

错误速查表¶

运行诊断检查¶

检查网络连通性¶

验证 PATH¶

检查冲突安装¶

检查目录权限¶

验证二进制工作正常¶

常见安装问题¶

安装脚本返回 HTML¶

command not found: claude¶

curl: (56) Failure writing output to destination¶

Homebrew cask 不可用或过时¶

TLS 或 SSL 连接错误¶

Failed to fetch version from downloads.claude.ai¶

Windows 上使用错误安装命令¶

running scripts is disabled on this system¶

Windows 安装时文件被占用¶

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

Docker 中安装挂起¶

claude update 或 claude doctor 挂起¶

Claude Desktop 覆盖 Windows 上的 claude 命令¶

Windows 需要 Git for Windows 或 PowerShell¶

不支持 32 位 Windows¶

Linux musl 或 glibc 二进制不匹配¶

Illegal instruction¶

macOS 上的 dyld: cannot load¶

WSL1 上的 Exec format error¶

WSL 中 npm 安装错误¶

npm 安装后原生二进制未找到¶

权限错误¶

登录和认证¶

重置登录¶

OAuth error: Invalid code¶

403 Forbidden after login¶

This organization has been disabled¶

WSL2/SSH/容器中 OAuth 登录失败¶

Not logged in or token expired¶

Bedrock、Agent Platform 或 Foundry 凭据未加载¶

仍然卡住¶