展开本页目录
开始前准备什么
- 记录原始错误、系统、终端种类和采用的安装方式。
- 以下检查不需要 API Key，也不需要模型请求；不粘贴密钥和完整环境变量。
- 修改 PATH 前备份对应 Shell 配置；保留项目、会话与用户设置。
- 找到二进制
- 检查 PATH
- 排除多版本
- 修复启动环境
- 再配置模型
先下载样例，再完成自己的首次调用
示例不含密钥。API 按实际用量计费；下载和点击不代表调用成功。
用同一台机器复现并修复 command not found
Claude Code 2.1.177；本地命令核验。没有模型请求。
使用 zsh -fc 在子进程执行 PATH=/usr/bin:/bin command -v claude；这个设置只在该进程有效。
对照使用正常 PATH 的子进程，先 command -v claude，再运行 claude --version。
把定位出的实际安装目录加回正确 Shell 的 PATH 后，开新终端验证；不要把二进制复制到系统目录。
样例测试的是 PATH 问题。如果已经找到命令但运行失败，继续按版本或系统架构分支排查。
- 通过：最小PATH无法找到
- 通过：恢复当前PATH可找到
本地样例复跑
python3 lab.py --output ./result c04
真实客户端或本地脚本执行记录；测试响应来自本机样例服务。
先看错误属于哪一层
| 现象 | 优先判断 | 下一步 |
|---|---|---|
| command not found / 不识别命令 | 本地命令搜索失败 | 检查二进制和 PATH，不换 API Key。 |
| 文件存在，完整路径能输出版本 | Shell 的 PATH 未读取 | 添加路径，新开同一类终端。 |
| claude 打开桌面应用 | PATH 指向其他同名程序 | 检查全部路径，更新或处理冲突安装。 |
| 能输出版本，但请求 401 / 429 | 已经越过安装阶段 | 按 API 认证、额度和限流排查。 |
- 现象
- command not found / 不识别命令
- 优先判断
- 本地命令搜索失败
- 下一步
- 检查二进制和 PATH，不换 API Key。
- 现象
- 文件存在，完整路径能输出版本
- 优先判断
- Shell 的 PATH 未读取
- 下一步
- 添加路径，新开同一类终端。
- 现象
- claude 打开桌面应用
- 优先判断
- PATH 指向其他同名程序
- 下一步
- 检查全部路径，更新或处理冲突安装。
- 现象
- 能输出版本，但请求 401 / 429
- 优先判断
- 已经越过安装阶段
- 下一步
- 按 API 认证、额度和限流排查。
macOS / Linux：先测试完整路径
下面仅查看路径并尝试读取本机版本。若完整路径也不存在，PATH 修改不能凭空创建程序；回安装教程确认独立 CLI 是否安装成功。npm 或 Homebrew 路径可能不同，用实际安装方式判断。
只读检查
command -v claude
which -a claude
ls -l "$HOME/.local/bin/claude"
"$HOME/.local/bin/claude" --version
本站绘制的内容说明图：这些命令定位 Unix shell 的命令实体；仅 PATH 缺失时才进入 PATH 修复，不反复重装。
文件存在时，给当前 Shell 加入 PATH
先在当前终端临时加入路径。如果随后能输出版本，再把同一行添加一次到你实际使用的启动文件。不要覆盖整个 PATH，也不需要更改 HOME。
Zsh 通常读取 ~/.zshrc；Linux Bash 交互终端通常读取 ~/.bashrc；macOS 的 Bash 登录终端通常读取现有 ~/.bash_profile、~/.bash_login 或 ~/.profile。先备份，再编辑实际使用的那个文件，最后新开终端验证。
- 若只是旧终端未刷新，新开终端即可，无需多次追加同一行。
- 桌面启动的编辑器、SSH、容器各有启动环境；在出错的原环境再次检查。
- 其他 Shell 使用其自身 PATH 配置语法，不直接粘贴 Bash 语法。
当前终端验证
export PATH="$HOME/.local/bin:$PATH"
claude --version
claude doctor
本站绘制的内容说明图：仅适用于实体存在但不在 PATH 的分支；按实际 shell 写入启动文件，不照搬到其他系统。
Windows：检查 exe，再测试当前进程 PATH
在 64 位 PowerShell 中运行。代码只为当前窗口临时加目录，并验证版本；关闭窗口后这个临时修改失效。它不修改整个系统 PATH。
如果临时验证通过，在 Windows 的“环境变量”设置中，将 %USERPROFILE%\.local\bin 添加到当前用户的 Path 列表，然后重新打开终端。保留其他列表项。若路径已存在，优先检查旧窗口、重复版本或不同用户。
Windows PowerShell
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
Get-Command claude -All -ErrorAction SilentlyContinue | Select-Object Source, CommandType
where.exe claude
$claudeDir = Join-Path $env:USERPROFILE '.local\bin'
$env:PATH = $claudeDir + ';' + $env:PATH
claude --version
claude doctor不要把扩展、npm 与 WSL 的安装混在一起
只卸载确认不要的程序，不删除整个 .claude、.codex 或 .cc-switch 目录。更新中断、杀毒占用和 32 位终端属于不同原因，保留实际报错后对照官方专门章节。
| 情况 | 检查方式 | 处理 |
|---|---|---|
| 只装 VS Code 扩展 | 独立二进制是否存在 | 需要终端命令时安装独立 CLI。 |
| 原生和 npm 同时存在 | which -a / Get-Command -All | 选定一套，用对应安装器管理旧版本。 |
| Windows 有命令，WSL 没有 | 在 WSL 内检查 command -v | 按 Linux 安装；不调用 Windows 安装路径。 |
| 命令指向 WindowsApps | where.exe claude 的第一条路径 | 核对旧 Claude Desktop 的同名程序冲突。 |
| 更新后 exe 缺失 | 本地 bin 内是否有 claude.exe.old.* | 按官方恢复备份步骤处理，无法恢复再重装。 |
- 情况
- 只装 VS Code 扩展
- 检查方式
- 独立二进制是否存在
- 处理
- 需要终端命令时安装独立 CLI。
- 情况
- 原生和 npm 同时存在
- 检查方式
- which -a / Get-Command -All
- 处理
- 选定一套，用对应安装器管理旧版本。
- 情况
- Windows 有命令，WSL 没有
- 检查方式
- 在 WSL 内检查 command -v
- 处理
- 按 Linux 安装；不调用 Windows 安装路径。
- 情况
- 命令指向 WindowsApps
- 检查方式
- where.exe claude 的第一条路径
- 处理
- 核对旧 Claude Desktop 的同名程序冲突。
- 情况
- 更新后 exe 缺失
- 检查方式
- 本地 bin 内是否有 claude.exe.old.*
- 处理
- 按官方恢复备份步骤处理，无法恢复再重装。
修复完成的标志：回到原终端重新启动
- 新开最初出错的同类终端，claude --version 正常且路径符合预期。
- 运行 claude doctor 检查设置，保存不含凭据的诊断结果。
- 安装通过以后，再处理官方登录或 apizt API 配置。
- 能启动并不意味着某个模型已经可用；最后用小任务与调用记录验收。
怎样确认已经完成
- 独立二进制存在，完整路径能输出版本。
- 新的原终端能够找到同一个预期版本。
- 没有为解决 PATH 问题删除用户会话或改动 API 凭据。
- 请求失败转到对应 API 错误页，不重复重装。
常见问题
更换 API Key 能解决 command not found 吗？
不能。此错误发生在启动可执行程序之前，模型请求尚未发出，先检查安装与 PATH。
需要 sudo 或管理员权限修改 PATH 吗？
通常可以在当前用户范围添加安装目录。企业受管设备遵守管理员配置，不为修复命令搜索而扩大整个系统权限。
为什么加入 PATH 后仍没生效？
旧进程可能仍保留原环境，也可能修改了未读取的启动文件。新开同类终端，比较完整路径和命令路径，再检查重复安装。
claude 能打开桌面应用，算安装成功吗？
要看你需要哪个程序。若需要 CLI，检查 Get-Command 或 where.exe 返回的路径；同名桌面程序不是 CLI 的版本验证。
卸载重装会删除历史会话吗？
程序卸载与配置目录删除是不同操作。不要使用删除整个用户配置目录的步骤；先备份并按原安装方式处理程序。