Appearance
OpenClaw ERR_UNSUPPORTED_ESM_URL_SCHEME 报错完整解决方案
安装 OpenClaw 时遇到 ERR_UNSUPPORTED_ESM_URL_SCHEME 报错？这是 Windows 用户最常见的问题之一。别慌，这篇教程帮你彻底解决。
报错信息长什么样
完整的报错信息通常是这样的：
Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: Only file and data URLs are supported by the default ESM loader. Received protocol 'node:'
at new NodeError (node:internal/errors:405:5)
at defaultLoad (node:internal/modules/esm/load:131:11)
...或者：
Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: Only file and data URLs are supported by the default ESM loader这个错误发生在安装或启动 OpenClaw 时，特别是配置模型后的下一步。
报错原因分析
根本原因
OpenClaw 的某些依赖包（如 @matrix-org/matrix-sdk-crypto-nodejs）使用 ESM 模块格式，而 Node.js 默认只支持特定的 URL 方案（如 file://）。
当 Node.js 尝试通过不支持的路径方式加载模块时，就会触发这个错误。
常见触发场景
- Node.js 版本不兼容：版本过低或过高都可能出现问题
- 模块加载方式不正确：相对路径加载 ESM 模块
- Windows 系统特有问题：路径处理差异
- OpenClaw 版本 Bug：某些版本存在已知问题
解决方案汇总
方案一：升级 Node.js 版本（推荐）
这是最简单有效的解决方案。
检查当前版本：
bash
node -v推荐版本：
| Node.js 版本 | 兼容性 | 建议 |
|---|---|---|
| v18.x | ⚠️ 部分兼容 | 建议升级 |
| v20.x | ✅ 完全兼容 | 推荐使用 |
| v22.x | ✅ 完全兼容 | 推荐使用 |
| v23.x | ⚠️ 可能有新问题 | 谨慎使用 |
升级方法：
使用 nvm（推荐）：
bash
# Windows 用户下载 nvm-windows
# 然后执行：
nvm install 22
nvm use 22或直接去 nodejs.org 下载 LTS 版本安装。
验证升级：
bash
node -v
# 应该显示 v20.x 或 v22.x
# 重新安装 OpenClaw
npm install -g @openclaw/cli方案二：降级 Node.js 版本
如果升级后仍有问题，可以尝试降级到稳定版本：
bash
nvm install 20.11.0
nvm use 20.11.0然后重新安装 OpenClaw。
方案三：清理缓存后重装
有时候缓存会导致问题：
bash
# 清理 npm 缓存
npm cache clean --force
# 删除已安装的 OpenClaw
npm uninstall -g @openclaw/cli
# 删除本地配置（可选，会清除你的配置）
rm -rf ~/.openclaw # Mac/Linux
rmdir /s %USERPROFILE%\.openclaw # Windows
# 重新安装
npm install -g @openclaw/cli方案四：使用官方安装脚本
官方安装脚本会自动处理依赖问题：
Windows：
powershell
iwr -useb https://openclaw.ai/install.ps1 | iexMac/Linux：
bash
curl -fsSL https://openclaw.ai/install.sh | sh方案五：设置环境变量
添加以下环境变量：
Windows（PowerShell）：
powershell
$env:NODE_OPTIONS="--experimental-vm-modules"Mac/Linux：
bash
export NODE_OPTIONS="--experimental-vm-modules"然后重新启动 OpenClaw。
方案六：检查路径问题
Windows 用户特别注意：
- 不要在中文路径下安装：如
C:\用户\张三\... - 避免空格路径：如
C:\Program Files\... - 使用管理员权限运行
推荐安装路径：
C:\openclaw\
或
D:\openclaw\完整排查步骤
按照这个顺序排查，通常能解决问题：
Step 1：检查 Node.js 版本
bash
node -v
npm -v确保 Node.js 版本在 20-22 之间。
Step 2：清理并重装
bash
# 清理
npm cache clean --force
npm uninstall -g @openclaw/cli
# 重装
npm install -g @openclaw/cliStep 3：验证安装
bash
openclaw --versionStep 4：运行诊断
bash
openclaw doctor这个命令会自动检测常见问题。
Step 5：查看详细日志
如果以上步骤都失败，启用详细日志：
bash
# Windows
$env:OPENCLAW_VERBOSE=1
openclaw start
# Mac/Linux
OPENCLAW_VERBOSE=1 openclaw start根据日志信息定位具体问题。
其他常见报错
在解决 ERR_UNSUPPORTED_ESM_URL_SCHEME 的过程中，可能还会遇到这些错误：
错误一：EACCES permission denied
权限不足：
bash
# Mac/Linux
sudo npm install -g @openclaw/cli
# Windows：以管理员身份运行 PowerShell错误二：Network timeout
网络超时，换国内镜像：
bash
npm config set registry https://registry.npmmirror.com
npm install -g @openclaw/cli错误三：Port 3000 already in use
端口被占用：
bash
# Windows
netstat -ano | findstr :3000
taskkill /PID <进程ID> /F
# 或使用其他端口
openclaw start --port 3001错误四：Python not found
缺少构建工具：
bash
npm install -g windows-build-tools预防措施
为了避免以后再遇到类似问题：
- 使用 nvm 管理 Node.js 版本：方便切换
- 保持 Node.js 在 LTS 版本：不要追最新版
- 定期更新 OpenClaw：
npm update -g @openclaw/cli - 避免中文路径：使用英文路径安装
总结
ERR_UNSUPPORTED_ESM_URL_SCHEME 报错的核心原因是 Node.js 版本或模块加载方式问题。
快速解决步骤：
- 升级 Node.js 到 v20 或 v22
- 清理缓存重装 OpenClaw
- 运行
openclaw doctor诊断 - 检查路径是否有中文或空格
按这个流程走一遍，90% 的情况都能解决。如果还有问题，查看详细日志或去 GitHub Issues 寻找类似案例。
