$cd ../troubleshooting/
High📦 Installation
Node.js 版本过旧 — 语法错误与 tsx 崩溃
// OpenClaw 当前发行版面向 Node.js 22.14 或更新（24 LTS 亦可）。在 Ubuntu 默认 node 18/20、旧 nvm 别名或其他工具捆绑的 Node 上运行会立即失败：可选 import 语法 SyntaxError、为错误 ABI 编译的原生插件，或 gateway 启动前 tsx 崩溃。症状像随机堆栈而非明确的「请升级 Node」。本非官方指南说明如何在 gateway 实际上下文（SSH 与 systemd）中检查 `node -v`、用 nvm/fnm/NodeSource 安装 22.14+，并重建原生模块，使 openclaw doctor 与 gateway 安装在 Mac Mini 与 Linux VPS 上都能成功。
diagnose.sh
🔍 这是您的问题吗？
?`node -v` 显示 v18.x、低于 20.18 的 v20.x 或任何低于 v22.14 的版本
?Gateway 启动时出现 SyntaxError 或 tsx 模块错误
?原生模块错误提及 NODE_MODULE_VERSION 不匹配
?笔记本上 openclaw 正常但 VPS 上旧发行版 Node 失败
?`openclaw doctor` 警告不支持的 Node 运行时
check_node.sh
✅ 修复方法 1 — 在各处检查 Node 版本
对比 shell Node 与 daemon Node
# 交互 shell node -v which node npm -v # Gateway 实际看到的环境 systemctl --user show-environment | grep -i path grep -E 'ExecStart|Environment' ~/.config/systemd/user/openclaw-gateway.service
退出码 1 表示 Node 过旧
# 快速下限检查（bash）
NODE_MAJOR=$(node -p "process.versions.node.split('.')[0]")
NODE_MINOR=$(node -p "process.versions.node.split('.')[1]")
# 需要：major >= 22 且 (major > 22 或 minor >= 14)
node -e "const [M,m]=process.versions.node.split('.').map(Number); if(M<22||(M===22&&m<14)) process.exit(1)"install_node22.sh
✅ 修复方法 2 — 安装 Node 22.14+（nvm / fnm / NodeSource）
通过 nvm 安装 Node 22 LTS 线
# nvm（Mac / Linux 常见） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash source ~/.nvm/nvm.sh nvm install 22 nvm alias default 22 nvm use 22 node -v
选一种安装方式——服务器用 fnm 或 NodeSource
# fnm 替代（快，VPS 友好） curl -fsSL https://fnm.vercel.app/install | bash fnm install 22 fnm default 22 node -v # Ubuntu NodeSource（系统级，无 nvm） # curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - # sudo apt-get install -y nodejs
rebuild_openclaw.sh
✅ 修复方法 3 — 重建原生模块并重装 OpenClaw
原生插件须匹配新 Node 版本
# 为新 Node ABI 重建全局 openclaw npm rebuild -g openclaw # 或干净重装 npm uninstall -g openclaw npm i -g openclaw@latest openclaw --version openclaw doctor
让服务指向 Node 22 二进制，而非 /usr/bin/node
# 更新 systemd 使用正确 node 路径 NODE_PATH=$(which node) # 编辑 openclaw-gateway.service 的 ExecStart 使用 $NODE_PATH systemctl --user daemon-reload systemctl --user restart openclaw-gateway openclaw gateway status
💡 专业技巧：Gateway 的 Node 与 Shell 一致
交互式 SSH 常加载 nvm；systemd 不会。在 service unit 的 Environment 中放入 nvm/fnm init，或在 ExecStart 中使用 Node 22 的绝对路径。升级后，服务上下文中的 `which node` 须与终端中 `node -v` 一致。
🛡️ 预防清单
- • 在项目根与 gateway 主机用 .nvmrc 或 .node-version 固定 Node 22.14+
- • 在 CI、Docker 基础镜像与 systemd 中运行 `node -v`——不要只在笔记本上检查
- • OS 升级（apt upgrade nodejs）后重新确认版本——发行版包常落后于上游
- • 避免在同一主机混用 Homebrew node、nvm node 与 /usr/bin/node
- • 在 runbook 的 openclaw 安装步骤旁注明所需 Node 版本
❓ 常见问题
Q1. OpenClaw 最低 Node 版本是多少？
社区测试与近期发行说明表明 Node 22.14+ 为实际下限。Node 24 LTS 可用。Node 18 与早期 Node 20 常在 OpenClaw 内部使用的现代 ESM/tsx 路径上失败。运行 `openclaw doctor`——较新版本低于阈值时会明确警告。不确定时安装最新 Node 22 补丁版而非能用的最旧版本。
Q2. SSH 里 node -v 是 22 但 gateway 仍崩溃？
systemd、launchd 与 cron 使用不含 nvm/fnm profile 的精简环境。Gateway 服务可能调用 /usr/bin/node（v18）而 shell 用 ~/.nvm/versions/node/v22.x/bin/node。检查 service 文件 ExecStart=。修复方式：嵌入 Node 22 完整路径或在 ExecStartPre 中 source nvm。Docker 基础镜像 node:18 而本地 node:22 开发时同理。
Q3. 哪些错误 specifically 指向 Node 版本问题？
常见模式：`SyntaxError: Unexpected token 'with'`、内置路径 `Cannot find module`、原生模块 `ERR_DLOPEN_FAILED`、tsx/esbuild 版本不匹配，或极旧运行时 `ReferenceError: structuredClone is not defined`。堆栈指向 dist/gateway.js 第 1 行常表示运行时无法解析 bundle——先升级 Node 再查应用逻辑。
Q4. 该用 nvm、fnm 还是系统包？
nvm 与 fnm 在家庭实验室与 Mac Mini 流行——多版本方便。无头 Ubuntu VPS 可用 NodeSource setup_22.x 或带全局默认的 fnm。除非其上再用 nvm，否则避免 apt 的 nodejs 18。fnm 更快且可用绝对路径配合 systemd。选一种管理器；不要像双重 openclaw 二进制那样堆三种 Node 安装。
Q5. 升级 Node 后要重装 openclaw 吗？
建议重装。全局 npm 包可能链接为旧 Node ABI 编译的原生插件。在新 Node 下运行 `npm rebuild -g openclaw` 或 `npm uninstall -g openclaw && npm i -g openclaw@latest`。然后 `openclaw doctor` 并重启 gateway。跳过 rebuild 会在 node -v 看起来正确时出现 MODULE_VERSION 不匹配。
Q6. Raspberry Pi arm64 需要特殊 Node 构建吗？
使用 Node.js 下载页或 nvm 的官方 arm64 二进制——不要在 Pi 上假设 x64 nvm。原生模块编译更慢；首次安装多留时间。Pi 4/5 64 位 OS 有 Node 22 arm64 构建。原生 rebuild 失败时确保已装 build-essential python3。官方仓库：github.com/openclaw/openclaw。