OpenClaw ERR_UNSUPPORTED_ESM_URL_SCHEME 报错完整解决方案

安装 OpenClaw 时遇到 ERR_UNSUPPORTED_ESM_URL_SCHEME 报错？这是 Node.js ESM 模块加载问题，这篇教程帮你彻底解决。

报错信息长什么样

Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: 
Only file and data URLs are supported by the default ESM loader. 
Received protocol 'node:'

或者：

Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: 
Only URLs with a scheme in: file, data are supported by the default ESM loader.

报错原因分析

这个错误的核心原因：Node.js 版本与 ESM 模块加载方式不兼容。

常见触发场景

场景	原因	解决方案
Node.js 版本过低	< 16.x 不完全支持 ESM	升级到 18.x 或更高
使用 node: 协议导入	旧版本不支持	升级 Node.js
package.json 缺少 type 字段	CommonJS/ESM 混用	添加 "type": "module"
路径包含特殊字符	Windows 路径问题	使用 file:// 协议
依赖包版本冲突	锁文件过时	删除 node_modules 重装

解决方案

方案一：升级 Node.js（推荐）

最彻底的解决方案：升级到 Node.js 18.x 或更高版本。

检查当前版本：

node -v

如果版本低于 18：

1. Windows 用户：去 nodejs.org 下载 LTS 版本安装
2. Mac 用户：

   brew install node@20

3. Linux 用户：

   curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
   sudo apt-get install -y nodejs

验证安装：

node -v  # 应该显示 v18.x.x 或更高
npm -v

方案二：使用 nvm 管理版本

如果你需要在不同项目间切换 Node.js 版本：

安装 nvm（Windows 用 nvm-windows）：

# Windows: 下载 nvm-windows 安装包
# Mac/Linux:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

切换版本：

nvm install 20
nvm use 20

方案三：清理并重新安装

如果 Node.js 版本没问题，可能是依赖缓存问题：

# 进入 OpenClaw 目录
cd openclaw

# 删除缓存和依赖
rm -rf node_modules package-lock.json
rm -rf ~/.npm  # 清理全局缓存

# 重新安装
npm install

方案四：检查 package.json

确保 package.json 中有正确的配置：

{
  "name": "openclaw",
  "type": "module",  // 必须有这行
  ...
}

方案五：Windows 路径问题

Windows 用户如果路径包含中文或特殊字符：

1. 换到纯英文路径：

   # 不要装在 C:\用户\... 
   # 改为 C:\dev\openclaw

2. 使用 Git Bash 或 WSL：

   • Git Bash 路径处理更规范
   • WSL 可以用 Linux 环境

验证修复

安装成功后，运行：

npm run dev

如果看到类似输出，说明问题解决：

> openclaw@1.0.0 dev
> node --import tsx src/index.ts

[INFO] OpenClaw is starting...

仍然报错？

尝试以下排查步骤：

1. 检查全局模块

npm list -g --depth=0

看看有没有冲突的全局安装。

2. 使用 pnpm 替代 npm

npm install -g pnpm
pnpm install

pnpm 的依赖管理更严格，有时能解决 npm 解决不了的问题。

3. 检查环境变量

# 查看是否有异常的 NODE_PATH
echo $NODE_PATH  # Mac/Linux
echo %NODE_PATH% # Windows

如果有设置异常的 NODE_PATH，先清除它。

4. 查看完整错误栈

npm run dev --verbose

获取更详细的错误信息，便于定位问题。

总结

问题	解决方案	优先级
Node.js 版本过低	升级到 18.x+	⭐⭐⭐⭐⭐
依赖缓存损坏	删除 node_modules 重装	⭐⭐⭐⭐
package.json 配置问题	添加 "type": "module"	⭐⭐⭐
Windows 路径问题	使用英文路径	⭐⭐⭐
依赖冲突	使用 pnpm	⭐⭐

90% 的情况升级 Node.js 就能解决，建议优先尝试。