OpenClaw 安装后 command not found：5 种场景逐一修复

安装 OpenClaw 后执行 openclaw 报 command not found，原因几乎都是 npm 全局 bin 目录不在系统 PATH 中。本文覆盖 macOS（zsh/bash）、Linux、Windows、WSL2 四个平台，以及 nvm 用户和 sudo 安装两类特殊场景，含完整命令，5 分钟内可定位并修复。

快速诊断：30 秒确认根因

依次执行以下两条命令，根据输出结果直接跳转对应修复步骤：

# 第一步：查看 npm 全局包安装路径
npm prefix -g
# 示例输出：/Users/你的用户名/.nvm/versions/node/v22.3.0
#           或 /usr/local
#           或 C:\Users\你的用户名\AppData\Roaming\npm

# 第二步：检查该路径是否在 PATH 中
echo $PATH
# 在输出中搜索第一步的路径，若不存在则需要添加

如果 npm prefix -g 本身报错：Node.js 未安装或版本低于 22，先参考 OpenClaw Node.js 版本升级指南解决版本问题，再回来处理 PATH。

场景一：macOS（zsh，最常见）

macOS Catalina 起默认 shell 为 zsh，配置文件为 ~/.zshrc。

# 第一步：获取 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 的命令缓存：

rehash
openclaw --version

场景二：macOS（bash）/ Linux

bash 的配置文件为 ~/.bashrc（Linux）或 ~/.bash_profile（macOS 旧版）。

# 写入配置文件
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc

# 立即生效
source ~/.bashrc

# 验证
openclaw --version

Linux 系统提示：部分 Linux 发行版的 ~/.bashrc 在非交互式登录 shell 中不会自动加载，若修改后仍无效，同步写入 ~/.profile：

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.profile
source ~/.profile

场景三：Windows（PowerShell）

Windows 的 PATH 可通过两种方式修改：

方法 A：图形界面（持久生效）

按 Win + S 搜索"环境变量"，打开"编辑系统环境变量"
点击"环境变量"→ 在"用户变量"中找到 Path → 点击"编辑"
点击"新建"，添加 npm prefix -g 输出的路径（通常为 C:\Users\你的用户名\AppData\Roaming\npm）
确定保存，重新打开 PowerShell

方法 B：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 相同：

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
openclaw --version

若在 WSL2 中执行 npm prefix -g 输出的是 Windows 路径（如 /mnt/c/...），说明当前用的是 Windows 安装的 Node.js，而非 WSL2 内的 Node.js。需在 WSL2 内单独安装 Node.js 22：

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 管理 Node.js 时，PATH 由 nvm 自动管理，但有两种情况会导致 command not found：

情况 A：nvm 初始化代码未写入 shell 配置文件

# 检查 ~/.zshrc 或 ~/.bashrc 是否包含以下内容
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 已加载但没有设置默认版本

# 查看当前默认版本
nvm alias default

# 若输出为 N/A 或旧版本，重新设置
nvm alias default 22
nvm use 22

# 重装 openclaw（当前版本下重装）
npm install -g openclaw@latest

# 验证
openclaw --version

情况 C：nvm 下 OpenClaw 装在了旧版本的 Node 下

# 切换到 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.js 版本各有独立的全局包目录。在 v18 下安装的 OpenClaw 切换到 v22 后不可见，需重装。

场景六：用 sudo 安装导致路径不一致

若执行的是 sudo npm install -g openclaw@latest（Linux/macOS），全局包会安装到 root 用户的 npm prefix 路径，而普通用户的 PATH 中没有这个路径。

检查方法：

# 查看 root 的 npm prefix（有 sudo）
sudo npm prefix -g
# 示例：/usr/local

# 查看当前用户的 npm prefix（无 sudo）
npm prefix -g
# 示例：/home/yourname/.nvm/...（两者不同，说明装错了）

解决方案：不要用 sudo 安装，改用当前用户身份重装：

# 先卸载 root 下的版本
sudo npm uninstall -g openclaw

# 用普通用户重装
npm install -g openclaw@latest

验证修复成功

# 验证命令可执行
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 官方安装文档：docs.openclaw.ai/install
接入国产大模型（OpenClaw 配置完成后）：qiniu.com/ai/models

本文基于 OpenClaw 2026 年 3 月版本，nvm v0.40.4，npm v10.x。