一、问题现象：为什么执行 openclaw 命令总失败？
很多用户在运行 openclaw configure、openclaw dashboard 或 openclaw gateway 时遇到如下典型报错：
'openclaw' is not recognized as an internal or external command（Windows）zsh: command not found: openclaw（macOS/Linux）npm ERR! code EACCES或EPERM operation not permitted（npm 全局安装被拒）openclaw configure启动后无响应、卡在空白界面或报错Cannot find module 'xxx'
二、常见原因分析
这些报错通常不是 OpenClaw 本身缺陷，而是本地环境未满足其运行前提：
- Node.js 版本不兼容：OpenClaw 当前依赖 Node.js ≥ 18.x（部分功能需 20.x），低于 16.x 将大概率触发模块加载失败；
- npm 全局 bin 目录未加入 PATH：即使
npm install -g openclaw成功，若系统找不到全局 bin 路径（如C:UsersxxxAppDataRoamingnpm或~/.npm-global/bin），命令仍不可用； - 权限策略限制：Windows UAC、macOS SIP 或 Linux 的 npm 默认 prefix 权限设置可能导致安装被拦截；
- 网络或镜像问题：国内用户直接使用默认 npm registry 易出现超时、包下载不全，导致 CLI 工具缺失可执行文件；
- CLI 与后端服务版本不匹配：例如用新版 CLI 连接旧版 gateway API，可能触发配置向导无法加载 UI。
三、分步解决方案
✅ 步骤 1：确认 Node.js 与 npm 环境
node -v # 应输出 v18.17.0 或更高
npm -v # 应输出 9.x 或 10.x若版本过低，请从 nodejs.org 下载 LTS 版本重新安装。
✅ 步骤 2：安全安装 OpenClaw（推荐方式）
避免使用 sudo 或管理员权限，改用本地 prefix：
# 创建全局 npm 目录（非系统路径）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
# 将 bin 加入 PATH（写入 shell 配置）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc # macOS/Linux
# 或 echo 'set PATH=%USERPROFILE%.npm-globalbin;%PATH%' >> %USERPROFILE%DocumentsWindowsPowerShellMicrosoft.PowerShell_profile.ps1 # Windows PowerShell
source ~/.zshrc
# 安装（无需 --verbose，除非调试）
npm install -g openclaw✅ 步骤 3：验证命令是否可用
which openclaw # Linux/macOS
where openclaw # Windows CMD
openclaw --version若返回路径和版本号，说明 CLI 已就绪。
✅ 步骤 4：启动并验证各子命令
openclaw configure：首次运行会引导生成~/.openclaw/config.yaml，请确保终端有读写权限；openclaw dashboard：默认打开http://localhost:3000，需浏览器支持 WebSocket；openclaw gateway：启动本地 HTTP+WebSocket 服务，默认监听:8080，可通过curl http://localhost:8080/health验证。
四、如何确认已修复成功？
完成上述步骤后，请按顺序验证：
- 终端输入
openclaw --help能列出完整子命令； - 运行
openclaw configure后生成~/.openclaw/config.yaml且无报错； - 访问
http://localhost:3000可加载 Dashboard 页面； - 终端中看到
Gateway server listening on :8080日志，且curl -I http://localhost:8080/health返回200 OK。
五、仍无法解决？补充建议
- 检查杀毒软件/防火墙是否拦截了 node 进程或本地端口（3000/8080）；
- 尝试清除 npm 缓存：
npm cache clean --force； - 如需导入 QQ 账号或启用「心跳」等高级功能，请确认已部署配套服务端（如
openclaw-server），CLI 仅提供控制接口； - 所有配置项最终生效依赖于
config.yaml中gateway_url和auth_token的正确填写——这是连接真实服务的关键，不可跳过。
⚠️ 注意：本文所述命令与行为基于 OpenClaw 官方 GitHub 仓库当前主分支（截至 2024 年中）的公开文档。具体参数、端口、路径请以 GitHub 主页 README 及
openclaw --help输出为准。