Node.js 兼容性

本参考文档介绍受支持的 Node.js 版本线、最低版本存在的缘由，以及它们在各个 OpenClaw 版本中的变化。安装步骤请参阅 Node.js；macOS 配套应用要求请参阅 macOS。

支持的版本¶

精确的 engines 表达式为 >=24.16.0 <25 || >=26.1.0。它仍是文档化的支持策略，也是包管理器所使用的 package.json engines 范围。

门控如何判定¶

启动、doctor、Gateway 运行时选择、更新预检以及安装程序运行时验证都会检查实际的 node:sqlite 绑定：该绑定必须存在、加载 WAL 安全的 SQLite 库，并在 TEXT、BLOB 和 JSON 往返过程中保留内嵌及末尾的 NUL。该探测使用内存数据库，并缓存当前进程的结果；对另一个可执行文件的检查会以有界超时的方式在该可执行文件中运行相同的探测。受支持版本表中的构建如果探测失败，也会被拒绝。

当探测通过时，当前运行包的启动保护和 Gateway 运行时选择会接纳表外 Node 24 或更高版本，并提示 unsupported version, capability probe passed。这些版本的能力满足本包的正确性门控，但仍不在经过测试的支持策略范围内。这允许供应商进行反向移植，而无需声称支持其版本。Node 22 和 23 仍被排除，且包管理器的 engines 检查仍然生效。

安装程序保留数字形式的 Node 要求，并增设探测作为第二道门控。包和 Git 更新预检还要求所选目标的 engines.node 范围满足数值要求，包括任何后备运行时。探测通过并不能放宽其他包的要求：较旧的版本在启动时仍可能强制执行其版本表。

更新恢复会推荐同时满足候选版本 engines 范围和上述更新程序受支持范围的最低标准版本。例如，要求 >=22.19.0 的旧候选版本仍需要推荐 24.16.0，更新程序才能运行。如果两个范围没有共同受支持的版本，提示信息会同时指明这两个范围，并要求你选择兼容的目标。选择运行时后，请通过保留的绝对路径启动器继续，以便更新程序在安装前重新检查前缀路径和服务归属；请遵循完整的恢复流程。

为何存在最低版本门槛¶

SQLite WAL 重置损坏错误要求加载安全的库：SQLite 3.51.3+、3.50.x 系列中的 3.50.7+ 或 3.44.x 系列中的 3.44.6+。OpenClaw 会验证实际加载的库，因为链接到系统共享 SQLite 的 Node 构建可能使用与 Node 自身元数据不同的版本。

另外，Node 22.23.x、24.15.0、25.9.0 和 26.0.0 中的 node:sqlite TEXT 解码器会在内嵌 NUL 字符处静默截断值。首批修复版本是 Node 24.16.0 和 26.1.0；WAL 安全的 SQLite 库并不能修复此解码器。Node 23 早前因 node:sqlite 行为不兼容而被排除。

平台影响¶

官方 Node 24+ 二进制文件要求 macOS 13.5+，因此 macOS 11 至 13.4 不再支持基于 Node 的 CLI 或 Gateway。配套应用有单独的 macOS 要求。

受支持的 Node 版本线没有官方 Linux ARMv7 构建。请在兼容的 ARM 硬件上使用 64 位操作系统，或改用其他受支持的主机。

在基于 RPM 的发行版上，安装程序会保留发行版自带的受支持 Node 包（其链接的是不安全的系统 SQLite），并为 OpenClaw 预置独立的用户空间运行时。

安装程序预置的内容¶

推荐版本、受支持版本和预置版本是三个不同的概念。

预置详情请参阅 安装程序内部机制。

检查运行时¶

node -v

推荐的安装路径请使用受支持的 Node 版本。损坏的 TEXT 解码器会被拒绝，并显示如下诊断信息：

Node <v>: node:sqlite truncates TEXT at embedded NUL (nodejs/node#61954); use 24.16+/26.1+ or a build with the fix

各版本历史¶

各行标明首个生效的版本（如适用，包括测试版）。即使数字要求未变，也会列出推荐和安装程序的变化。

相关¶

• Bun 兼容性
• 安装程序内部机制
• Linux
• macOS
• Node.js