openclaw安装报错多因node.js版本不匹配或环境冲突，官方要求v20.x lts及以上（推荐v24.12.0），需禁用多版本混用、中文路径及权限不足；推荐方案包括：一、macos/linux用nvm统一管理版本；二、windows彻底卸载旧版+官网重装并校验path；三、全平台运行官方fix-env脚本自动修复；四、linux服务器可用docker容器化隔离运行。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在安装OpenClaw时遇到“node: command not found”、“npm ERR! Unsupported engine”或“Gateway启动失败”等报错，大概率是Node.js版本不匹配或环境冲突所致。OpenClaw官方明确要求Node.js v20.x LTS及以上（推荐v24.x），且严禁多版本混用、中文路径、权限不足等情况。以下是针对性解决该问题的多种实操方案：
一、使用nvm统一管理Node.js版本（推荐macOS/Linux）
nvm（Node Version Manager）可隔离不同项目所需的Node.js版本，彻底规避全局版本污染与权限错误，是跨平台开发者的首选方案。
1、执行安装命令（macOS/Linux终端中运行）：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
2、刷新Shell配置文件：
source ~/.zshrc（macOS默认）或 source ~/.bashrc（Linux常用）
3、安装并切换至OpenClaw兼容版本：
nvm install 24.12.0
nvm use 24.12.0
4、验证版本是否生效：
node --version 应输出 v24.12.0；npm --version 应高于10.0.0
二、Windows平台使用Node.js官方安装包+手动清理旧环境
Windows系统自带PowerShell或CMD易受旧版Node残留干扰，直接覆盖安装常导致PATH错乱或registry残留，需彻底清除后重装。
1、卸载所有已安装的Node.js：控制面板→程序和功能→卸载所有含“Node.js”名称的条目
2、删除残留目录：
C:\Program Files\nodejs\
C:\Users\[用户名]\AppData\Roaming\npm
C:\Users\[用户名]\AppData\Roaming\npm-cache
3、从官网下载Node.js v24.12.0 LTS安装包（.msi格式），安装时务必勾选“Add to PATH”选项
4、以管理员身份打开PowerShell，执行：
node --version
npm config get prefix
5、确认npm全局路径为纯英文路径（如C:\Users\Admin\AppData\Roaming\npm），严禁出现中文、空格或括号
三、一键脚本自动检测并修复（全平台通用）
OpenClaw官方提供跨平台环境自检脚本，可自动识别Node.js版本、PATH有效性、权限状态及常见冲突项，并引导修复，无需人工判断。
1、Windows（PowerShell管理员模式）执行：
iwr -useb https://openclaw.ai/fix-env.ps1 | iex
2、macOS/Linux（终端）执行：
curl -fsSL https://openclaw.ai/fix-env.sh | bash
3、脚本将输出三项关键结果：
✅ Node.js version check: v24.12.0 OK
✅ PATH integrity: clean
❌ Conflicting nvm/nodenv detected — auto-disabled
4、执行完成后，重启终端或PowerShell，再次运行node --version验证
四、Docker容器化隔离运行（适用于Linux服务器/阿里云ECS）
当宿主机Node.js环境不可控（如系统预装低版本、无管理员权限）时，Docker可完全屏蔽底层依赖，确保OpenClaw在纯净Node v24.12.0环境中运行。
1、确保已安装Docker与Docker Compose（v2.20+）
2、创建docker-compose.yml文件，内容如下：
version: '3.8'
services:
openclaw:
image: node:24.12-slim
working_dir: /app
volumes:
- ./openclaw-win:/app
command: ["sh", "-c", "npm install && npm start"]
ports:
- "18789:18789"]
3、在同级目录下执行：
docker compose up -d
4、检查容器日志确认启动成功：
docker logs -f openclaw | grep "Gateway online"
