Bun 兼容性

Bun 是 OpenClaw CLI、Gateway 和托管节点主机中显式选择启用的运行时。Node 仍然是主要且推荐的运行时。本参考涵盖 Bun 的要求和兼容性；有关安装和选择启用步骤，请参见 Bun；有关 Node 要求，请参见 Node.js 兼容性。

要求¶

OpenClaw 需要 Bun 1.4.0+、可用的 node:sqlite API，以及与 Node 相同的 WAL 安全 SQLite 下限。

平台默认值来自 Bun 的 SQLite 构建策略；Bun 1.4.2 版本定义 固定 SQLite 3.53.2。

macOS 上的 SQLite 库选择¶

安装 Homebrew SQLite 以支持原生 sqlite-vec KNN 内存查询：

brew install sqlite

在打开数据库之前，OpenClaw 按以下顺序选择库：

1. 内部提供的显式库路径，否则为 OPENCLAW_SQLITE_LIBRARY。
2. $HOMEBREW_PREFIX/opt/sqlite/lib/libsqlite3.dylib。
3. /opt/homebrew/opt/sqlite/lib/libsqlite3.dylib。
4. /usr/local/opt/sqlite/lib/libsqlite3.dylib。
5. /opt/local/lib/libsqlite3.dylib（MacPorts）。

候选库必须满足 WAL 安全下限并支持扩展加载，然后才会被选择。如果自动发现未找到符合条件的库，Bun 会保留其运行时库；如果该库满足 WAL 下限，普通代理数据库仍可打开。内存 KNN 子进程使用同一已选库。

SQLite 存储工作进程继承主进程已选择的库。打开另一个数据库或重启存储工作进程会复用该选择，而不会重复 Bun 的一次性库初始化。

在启动 OpenClaw 之前，在进程环境中设置 OPENCLAW_SQLITE_LIBRARY 以覆盖发现：

OPENCLAW_SQLITE_LIBRARY=/path/to/libsqlite3.dylib bun openclaw.mjs gateway

在 macOS 上，openclaw gateway install --runtime bun、openclaw node install --runtime bun 以及基于包装器的安装会将安装 shell 中的 OPENCLAW_SQLITE_LIBRARY 和 HOMEBREW_PREFIX 持久化到托管服务定义中，因此服务会选择相同的库。若要更改已安装服务的这些值，请从具有所需值的 shell 中重新安装：openclaw gateway install --runtime bun --force（对于托管节点主机，使用 openclaw node install --runtime bun --force）；对已加载服务进行普通重新安装不会生效。直接 Node 运行时服务从不持久化这些值。

无效的覆盖会失败，并显示：

Cannot use SQLite library <path>: <reason>. Fix or unset OPENCLAW_SQLITE_LIBRARY; install a supported library with brew install sqlite.

Node 和非 macOS 上的 Bun 会忽略此覆盖，并在 Gateway 启动日志中发出警告。当选择某个库时，Gateway 启动日志会记录 SQLite: using <path> (<version>, extension loading enabled)。openclaw doctor 会报告 doctor 进程的选择。

守护进程安装、openclaw gateway start 修复、openclaw doctor 和服务审计会通过相同的选择流程探测候选 Bun 可执行文件，因此它们会判断并报告 Gateway 实际打开的库，而不是 Bun 的运行时 SQLite。无效的覆盖会使这些探测以上述消息失败，而不是建议升级 Bun 或将服务切换到 Node。

如果你之前使用了调用 Database.setCustomSQLite() 的预加载，请移除它，并改为将 OPENCLAW_SQLITE_LIBRARY 设置为相同路径。该钩子是一次性的：保留预加载会导致 SQLite already loaded，即使两个选择指向同一库。OpenClaw 的覆盖还会将该路径转发给 KNN 子进程。

无扩展支持库时的内存搜索¶

当 KNN 子进程无法加载扩展时，内存搜索会回退到批量嵌入扫描。它会保留提供者和来源过滤器以及批次之间的取消检查，但在大型索引上可能更慢。参见 内存配置。

浏览器子进程¶

浏览器插件使用运行 OpenClaw 的 Bun 可执行文件启动其辅助进程，因此浏览器自动化无需单独安装 Node：

• Chrome MCP： 现有会话配置文件 会在 Bun 上启动打包的 Chrome DevTools MCP 服务器，用于 --autoConnect、browserUrl 和 wsEndpoint 连接。操作、快照、屏幕截图、坐标点击、跨站点导航期间的等待以及服务器进程树的清理行为与 Node 上相同。自定义 mcpCommand 按配置运行。
• Chrome 扩展： 在 macOS 和 Linux 上，原生消息主机及其启动的中继守护进程使用运行 openclaw browser extension install 的运行时。

仅 Bun 安装¶

将 Gateway 服务固定到你的 Bun 可执行文件，以便更新和 Doctor 保留它。如果没有 Node，openclaw 启动器无法启动，因此使用 Bun 运行包入口点：

<bun> <package-root>/openclaw.mjs gateway install --runtime bun --runtime-path <bun> --force

更新、修复和 Doctor 维护子进程使用正在运行的 Bun 可执行文件。 Bun 包管理器探测和安装使用显式可执行文件：更新其根目录时使用已验证的服务 Bun，否则当更新器在 Bun 下运行时使用 process.execPath，最后回退到 PATH 中的裸 bun。即使 PATH 中没有 Bun 或包含不同构建，这也会保留所选的 Bun。

当受所有权的受管 Bun Gateway 从与 CLI 不同的包根提供服务时， openclaw update 会就地升级 Gateway 安装，并保持调用该命令的 CLI 安装不变。更新器会验证该服务实际使用的 Bun 是否满足 Bun 1.4+ 以及 WAL 安全的 node:sqlite，而不会将其模拟的 Node 版本与 engines.node 进行比较。如果更新器运行在 Node 上，则该 Node 也必须满足目标包的 Node 和 SQLite 要求，因为最终化会使用它。 现有的服务安装/重启路径会保留已记录的 Bun 固定版本。Node 拆分根路由保持不变，仅位于 ~/.openclaw 下的路径本身不会建立 Bun 全局安装所有权。

从另一个安装运行 Doctor 或 openclaw update repair 时，该 Bun Gateway 会保持在其自身根目录下。显式修复会报告安装漂移，并在停止服务前拒绝维护。请使用 <bun> <service-root>/openclaw.mjs update repair 或 <bun> <service-root>/openclaw.mjs doctor --fix 从服务自身的安装进行修复。

在没有持久 Node 的情况下，首次安装和更新器暂存要求将 OPENCLAW_PACKAGE_BUN_LAUNCHER 设置为启动 CLI 的绝对 Bun 可执行文件路径。更新器在 Bun 下运行时会自动设置它；应用必须在首次执行 bun add -g --trust openclaw@<version> 时设置它。Preinstall 会验证该启动器为 Bun 1.4+。如果没有该标记，preinstall 仍要求存在持久 Node；即使设置了标记，在 PATH 上找到的 Node 也必须满足包的 Node 要求。

截至 2026.9.6 的已发布更新器无法更新仅 Bun 安装。它们不会设置该标记，因此新包的 preinstall 会停止暂存（global-install-failed）。如果调用方设置了该标记，其自身的裸 node 探测会改为启动失败（update-executor-settlement-failed）。两种拒绝都发生在 Gateway 停止之前，Gateway 会继续运行。必须由修复版本来驱动更新；安装修复候选版本无法更改已经运行的更新器。

已安装的更新器会先运行。在 Linux 拆分根测试夹具中，已发布的 2026.9.6 会因 ENOENT 提前拒绝，当 PATH 中不存在 Bun 时，Gateway 和两个安装均保持不变。当 PATH 中存在 fork Bun 时，同一个已发布驱动会就地更新 Gateway 安装并使其健康重启，同时保持调用该命令的 CLI 不变。上述路由和显式 Bun 选择从包含修复的第一个更新器开始生效；更新的候选版本无法更改已安装更新器的首跳行为。

npm 来源的插件在 Bun 下使用 OpenClaw 捆绑的 npm 11.20.0 CLI，不需要单独安装 Node 或 npm。

已知限制¶

• 桌面 WebSocket： OpenClaw 使用已安装的 ws 传输用于桌面观察器和配对节点桌面/门户流。Bun 1.4.2 内置的 ws 服务器适配器缺少 pause/resume 和 Duplex 流桥接；已安装的传输会在桌面断开时保留背压、负载限制和清理。
• 生命周期脚本： 除非使用 bun pm trust 显式信任，否则 Bun 会阻止依赖项生命周期脚本。
• 包脚本： 某些脚本硬编码了 pnpm，因此 bun run 内部仍会调用 pnpm。
• PTY 终端： macOS 和 Linux 仅在提供 Bun.Terminal.pause() 和 Bun.Terminal.resume() 的构建中，才使用 Bun 的原生 PTY 而不需要 Node 运行时，例如同时包含 macOS 子进程退出修复 的 OpenClaw Bun fork 构建。其他 Bun 版本使用 Node 辅助程序，并且终端 I/O 需要已安装的 Node 运行时。OpenClaw 在选择该运行时时会跳过 Bun 的 node 垫片，包括在 bun --bun 下。Windows 保留 node-pty。
• Windows 浏览器扩展： 原生消息注册仅接受 node.exe 作为宿主解释器。在 Windows 上请使用 Node 运行 openclaw browser extension install。
• 启动的桌面应用： Node 在启动时将继承的描述符标记为 close-on-exec，而 Bun 1.4.2 不会，因此由 Gateway 计算机控制启动的应用会继承辅助程序的标准流。随后，Gateway 的 30 秒清理超时会在其执行关闭时停止该应用。OpenClaw 的 Bun fork 在 openclaw/bun#12 中采用了 Node 的行为。
• SQLite 句柄： Bun 1.4.2 在 DatabaseSync.close() 或 Symbol.dispose() 之后可能保留语句句柄和 WAL/共享内存文件；OpenClaw 无法通过 Bun 公开的 node:sqlite API 最终化它们。参见 上游关闭修复；当提示文件释放很重要时，请使用 Node。
• 共享状态读取： 成功的读取会复用其 worker 和原生 reader。在 Bun 上，关闭或替换 reader 仍会等待 worker 退出，包括宿主请求的清理。空闲 reader 会在 30 分钟后随其 worker 一起退役；转录发现仍会在释放捕获的数据库别名之前退役其 worker。
• SQLite 存储 worker： Bun 为每个不同数据库使用一个 worker，并可在宿主的 64 个客户端上限内使用多达 64 个专用 worker。同一数据库的客户端共享其 worker。关闭最后一个客户端时会等待 worker 退出以释放原生句柄；容量耗尽会拒绝新工作，而不会中断现有存储。Node 在四个共享 worker 之间复用数据库。在上游关闭修复发布，并且反复的关闭/重新打开测试证明原生句柄和锁已释放后，可以重新评估 Bun 的专用布局。
• Windows 上的无头 node 更新： 运行在 Bun 上的 node 宿主仍会使用 npm 准备更新，因为 Bun 的 Windows 二进制启动器无法暂存。Windows 仅 Bun 宿主会在每次每小时检查时记录该失败，并继续运行当前版本。
• 工作区安装： bun install 无法解析此仓库的 pnpm 工作区布局。请使用 pnpm install。

有关工作流和生命周期信任命令，请参阅 Bun。

版本历史¶

| 版本 | 变更 |

相关¶

• Bun
• 环境变量
• 内存配置
• Node.js 兼容性