安装 OpenClaw 后输入 `openclaw` 却提示 `command not found`？别着急，绝大多数情况下根本原因只有一个——**npm 全局 bin 目录没有被添加到系统的 PATH 环境变量中**。本文会完整讲解 macOS（zsh/bash）、Linux、Windows、WSL2 四大主流平台的修复方法，同时涵盖 nvm 用户和 sudo 安装两种特殊场景。每条命令都已直接给出，你只需按步骤操作，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 及之后的版本默认 shell 是 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 已加载，但未设置默认 Node 版本 ```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。*