OpenClaw安装后提示command not found？5种场景修复方案
## 快速诊断：30 秒锁定根因
运行两条命令，根据输出直接跳到对应修复方案：
```bash
# 第一步：定位 npm 全局包的安装目录
npm prefix -g
# 示例输出：/Users/你的用户名/.nvm/versions/node/v22.3.0
# 或 /usr/local
# 或 C:Users你的用户名AppDataRoamingnpm
# 第二步：检查该路径是否在系统 PATH 中
echo $PATH
# 在输出字符串中查找第一步获得的路径，未找到则需添加
```
**如果 `npm prefix -g` 报错**：说明 Node.js 安装异常或版本过低（低于 22），请先按 OpenClaw Node.js 版本升级指南处理，再回来配置 PATH。
---
## 场景一：macOS（zsh，最常见）
macOS Catalina 及以上版本默认使用 zsh，配置文件是 `~/.zshrc`。
```bash
# 第一步：获取 npm 全局 bin 路径
npm prefix -g
# 假设输出：/Users/yourname/.nvm/versions/node/v22.3.0
# 第二步：将该路径追加到 ~/.zshrc
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
# 第三步：立即生效，无需重启终端
source ~/.zshrc
# 第四步：验证
openclaw --version
```
若仍找不到命令，执行 `rehash` 刷新 zsh 的命令缓存：
```bash
rehash
openclaw --version
```
---
## 场景二：macOS（bash）/ Linux
bash 的配置文件为 `~/.bashrc`（Linux）或 `~/.bash_profile`（macOS 旧版）。
```bash
# 写入配置文件
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
# 立即生效
source ~/.bashrc
# 验证
openclaw --version
```
**Linux 用户留意**：部分发行版的 `~/.bashrc` 在非交互式登录 shell 中不会自动加载。若修改后仍无效，同步写入 `~/.profile`：
```bash
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.profile
source ~/.profile
```
---
## 场景三：Windows（PowerShell）
Windows 的 PATH 可通过图形界面或命令行设置。
### 方法 A：图形界面（持久生效）
1. 按 `Win + S` 搜索“环境变量”，打开“编辑系统环境变量”。
2. 点击“环境变量”→ 在“用户变量”里找到 `Path` → 点击“编辑”。
3. 点“新建”，粘贴 `npm prefix -g` 输出的路径（通常是 `C:Users你的用户名AppDataRoamingnpm`）。
4. 确定保存，**重新打开 PowerShell**。
### 方法 B：PowerShell 命令（当前会话立即生效 + 永久写入）
```powershell
# 获取 npm 全局路径
$npmBin = npm prefix -g
# 添加到当前会话 PATH
$env:Path += ";$npmBin"
# 写入用户级 PATH（永久）
[Environment]::SetEnvironmentVariable(
"Path",
"$([Environment]::GetEnvironmentVariable('Path', 'User'));$npmBin",
"User"
)
# 验证
openclaw --version
```
**强调**：修改系统 PATH 后必须重新打开终端窗口才能生效，VS Code 内置终端也不例外。
---
## 场景四：WSL2（Linux 子系统）
WSL2 是独立的 Linux 环境，与 Windows 本机 PATH 互不影响。在 WSL2 中安装的 OpenClaw 仅能在 WSL2 终端内使用，处理方式与 Linux 一致：
```bash
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
openclaw --version
```
若在 WSL2 内执行 `npm prefix -g` 输出 Windows 路径（如 `/mnt/c/...`），说明你使用的是 Windows 安装的 Node.js，而非 WSL2 内的。需在 WSL2 中单独安装 Node.js 22：
```bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g openclaw@latest
```
---
## 场景五：nvm 用户（特殊情况）
nvm 会自动管理 PATH，但有两个常见陷阱。
### 情况 A：nvm 初始化代码未写入 shell 配置文件
```bash
# 检查 ~/.zshrc 或 ~/.bashrc 中是否包含 nvm 相关行
grep -n "nvm" ~/.zshrc # 或 ~/.bashrc
# 若缺失，手动追加
cat >> ~/.zshrc << 'EOF'
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
EOF
source ~/.zshrc
```
### 情况 B：nvm 已加载，但未设置默认版本
```bash
# 查看当前默认版本
nvm alias default
# 若输出 N/A 或旧版本，重新设置
nvm alias default 22
nvm use 22
# 在当前版本下重装 openclaw
npm install -g openclaw@latest
# 验证
openclaw --version
```
### 情况 C：OpenClaw 安装在了旧版本的 Node 下
```bash
# 切换到 Node 22
nvm use 22
# 确认当前 node 版本
node -v # 应为 v22.x.x
# 在当前版本下重新安装
npm install -g openclaw@latest
openclaw --version
```
**nvm 关键路径**：全局包位于 `$NVM_DIR/versions/node/v22.x.x/bin/`，每个 Node 版本拥有独立的全局包目录。在 v18 下安装的 OpenClaw，切换到 v22 后自然不可见，必须重装。
---
## 场景六：用 sudo 安装导致路径不一致
若当初执行 `sudo npm install -g openclaw@latest`（Linux/macOS），全局包会被安装到 root 用户的 npm prefix 路径，普通用户 PATH 中自然找不到。
**如何判断？**
```bash
# 查看 root 的 npm prefix
sudo npm prefix -g
# 比如输出：/usr/local
# 再看当前用户的 npm prefix
npm prefix -g
# 比如输出：/home/yourname/.nvm/...（两者不一致，说明装错用户）
```
**解决方案**：不要使用 sudo 安装，换当前用户重装：
```bash
# 先卸载 root 下的版本
sudo npm uninstall -g openclaw
# 用普通用户重装
npm install -g openclaw@latest
```
---
## 验证修复成功
```bash
# 测试命令能否正常执行
openclaw --version # 输出版本号即成功
# 运行完整诊断
openclaw doctor
```
`openclaw doctor` 正常输出示例：
```
✔ Node.js version: v22.x.x (ok)
✔ npm global bin in PATH
✔ Gateway daemon: running
```
若 `npm global bin in PATH` 显示 `✘`，说明 PATH 修改尚未生效，请重新打开终端窗口再试。
---
## 快速排查索引
| 情况 | 跳转 |
|------|------|
| macOS zsh 终端 | 场景一 |
| macOS bash / Linux | 场景二 |
| Windows PowerShell | 场景三 |
| WSL2 子系统 | 场景四 |
| 使用 nvm 管理 Node | 场景五 |
| 之前用了 sudo 安装 | 场景六 |
---
## 常见问题
**Q：每次打开新终端都要重新执行 `export PATH=...` 才能用？**
说明你仅修改了临时会话，未写入配置文件。确认修改已写入 `~/.zshrc`（zsh）或 `~/.bashrc`（bash），而非仅在终端内输入了 `export`。执行 `grep openclaw ~/.zshrc` 检查内容是否存在，然后重新打开终端验证。
**Q：`npm prefix -g` 输出了路径，但该目录下根本没有 openclaw 文件？**
OpenClaw 可能安装到了不同 Node.js 版本的目录。检查是否使用 nvm 并切换过版本（见场景五），在正确版本下重装：`npm install -g openclaw@latest`。
**Q：Windows 上添加了 PATH 但 VS Code 终端仍找不到命令？**
VS Code 终端启动时读取 PATH，修改系统 PATH 后必须**完全关闭并重启 VS Code**，而非仅关闭终端面板。
**Q：PATH 中已有 npm 路径，但仍找不到 openclaw？**
执行 `ls $(npm prefix -g)/bin/ | grep openclaw` 确认可执行文件是否存在。若不存在，说明安装失败或安装到了其他路径，重新执行 `npm install -g openclaw@latest`。
---
## 总结
OpenClaw 安装后 `command not found`，根因是 npm 全局 bin 路径未加入 PATH。修复流程极为简单：**`npm prefix -g` 定位路径 → 写入 shell 配置文件 → `source` 生效 → `openclaw --version` 验证**。nvm 用户额外确认 shell 初始化代码存在、OpenClaw 安装在当前激活的 Node.js 版本下。
*本文基于 OpenClaw 2026 年 3 月版本，nvm v0.40.4，npm v10.x。*