Node.js 兼容性

本参考介绍了受支持的 Node.js 系列、最低版本存在的原因以及它们在 OpenClaw 版本之间的变化。安装步骤参见Node.js；有关 macOS 配套应用程序要求，请参阅 macOS。

支持的版本

确切的引擎表达式是 >=24.16.0 <25 || >=26.1.0。它仍然是已记录的支持策略和包管理器使用的 package.json 引擎系列。

Bun 选择加入运行时需要 Bun 1.4.3+ 或固定的 OpenClaw 叉；请参阅 Bun 兼容性。

门如何决定

启动、医生、网关运行时选择、更新预检和安装程序运行时验证检查实际的 node:sqlite 绑定：它必须存在，加载 WAL-safe SQLite 库，并通过 TEXT、BLOB 和 JSON 往返保留嵌入和尾随的 NUL。检查使用内存数据库并缓存当前处理结果；对另一个可执行文件的检查在该可执行文件中运行相同的检查，并具有有限的超时时间。如果检查失败，则拒绝支持版本表中的构建。

当检查通过时，正在运行的包的启动防护和网关运行时选择在表外承认 Node 24 或更新版本，并注明该版本不受支持，但其功能通过了验证。它的功能满足该包的正确性门，但它仍然在测试的支持策略之外。这允许供应商向后移植，而无需声明支持其版本。 Node 22 和 23 仍然被排除，包管理器引擎检查仍然适用。

安装人员保留数字 Node 要求并将检查添加为第二个门。包和 Git 更新预检还需要选定目标的 engines.node 数字范围，包括任何后备运行时。通过检查不能放宽另一个包的要求：旧版本可能仍会在启动时强制执行其版本表。

更新恢复建议满足候选引擎范围和上述更新程序支持范围的最低标准版本。例如，需要 >=22.19.0 的较旧候选者仍需要 24.16.0 的建议，以便更新程序可以运行。如果这些范围没有共同支持的版本，则该消息会标识这两个范围并要求您选择兼容的目标。选择运行时后，继续通过保留的绝对启动器，以便更新程序在安装前重新检查前缀和服务所有权；遵循完整的 恢复序列 。

楼层为何存在

SQLite WAL-reset 损坏 bug 需要安全加载的库：SQLite 3.51.3+， 3.50.7+在3.50.x内，或3.44.6+在3.44.x内。 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-safe SQLite 库无法修复此解码器。 Node 23 之前因不兼容的 node:sqlite 行为而被排除。

V8 编译器设置

OpenClaw 保留 Node 的默认 V8 编译器设置，包括 Maglev 和并发 Sparkplug。其可执行入口点关闭其拥有的资源，等待接受的工作，并在返回之前记录 process.exitCode。它们不会强制使用 process.exit() 进行正常终止。

在受影响的 Node 24 和 26 版本上，强制退出可以加入正在等待主线程垃圾收集的编译器工作线程，输出已经出现后死锁 （nodejs/node#64274）。自然关闭让 Node 在加入平台工作人员之前拆除隔离。运行时边界 linter 拒绝 process.exit() 和 process.reallyExit()，因此新入口点保留此生命周期。这不会修复不相关的本机关闭停顿，包括 macOS 系统证书枚举；系统证书信任保持启用状态。

平台后果

官方 Node 24+ macOS 二进制文件是为 macOS 13.5+（Node 支持的最旧版本）构建的。 macOS 不会在旧版本上阻止它们，并且已观察到 CLI 和网关在带有官方 Node 24 的 macOS 12 上运行。OpenClaw 不测试或支持 macOS 11 到 13.4，因此附带的功能他们自己的本机二进制文件仍然可能在那里失败。配套应用程序具有单独的 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

H跨版本的历史记录

行标识第一个有效版本，包括适用的测试版。即使数字要求保持不变，也会列出建议和安装程序更改。

相关内容

• Bun兼容性
• 安装器内部
• Linux
• macOS
• Node.js