跳转至

Bun

Warning

Node 仍然是 OpenClaw 的主要、默认和推荐运行时。提供 WAL 重置安全 node:sqlite 的 Bun 1.4+ 构建可以作为显式可选方案运行 CLI、Gateway 和受管节点宿主。OpenClaw 需要 SQLite 3.51.3+、3.50.x 中的 3.50.7+、或 3.44.x 中的 3.44.6+;较旧的 Bun 版本以及 SQLite 不安全的构建将被拒绝。

桌面应用管理自己的运行时:原生 macOS 应用和 Linux 上全新的本地 Tauri 安装使用相同的固定 OpenClaw Bun 分支。现有的 Linux Tauri 安装在启动和应用更新期间保留其运行时,直到你明确选择使用捆绑运行时…。macOS Tauri 保持其现有行为,独立于原生 macOS 应用。参见 Linux 配套。

Bun 仍可用作可选的包脚本运行器。默认包管理器仍然是 pnpm,文档工具完全支持并使用它。Bun 无法使用 pnpm-lock.yaml 并会忽略它;当前 Bun 版本在 bun install 期间无法解析此仓库的 pnpm-workspace.yaml 布局,因此依赖安装应使用 pnpm install。

安装

1. 安装依赖

pnpm install

Bun 无法解析此仓库的 pnpm workspace 布局,因此 bun install 会在 workspace 解析期间失败。请使用 pnpm install。

2. 构建并测试

bun run build
bun run vitest run

启动 OpenClaw 的命令默认使用 Node。

在 Bun 下从源码运行时,复用当前可执行文件的工作线程会使用 Bun 的原生 TypeScript 支持,即使该可执行文件具有自定义文件名。显式要求 Node 的工作线程保留其 Node 加载器。

3. 使用 Bun 运行 OpenClaw

要在 Bun 下运行引导流程并在 Bun 下安装受管 Gateway:

bun --no-install openclaw.mjs onboard --install-daemon --daemon-runtime bun

对于受管节点宿主,请单独选择 Bun:

bun --no-install openclaw.mjs node install --runtime bun

OpenClaw 会为其 Bun 服务命令及其拥有的运行时子进程(包括插件集成的 exec 密钥提供程序)添加 --no-install。缺失的导入会失败,而不是获取软件包,即使工作目录的 bunfig.toml 设置了 [install] auto = "fallback"。请显式安装所需的依赖。现有的服务定义会在正常的服务重新安装或更新期间收到该标志;无需状态迁移。这不会控制第三方插件自行启动的进程。直接调用原版 Bun 时,请使用 --no-install,如上所示。

仅使用 Bun 的全局安装

使用受支持的 OpenClaw Bun 分支 可执行文件:

OPENCLAW_PACKAGE_BUN_LAUNCHER=/absolute/path/to/bun /absolute/path/to/bun add -g --trust openclaw
export PATH="$(/absolute/path/to/bun pm bin -g):$PATH"
openclaw --version
openclaw status --json

在没有 Node 的 macOS 和 Linux 上,受信任的包生命周期会安装一个使用该确切 Bun 可执行文件的启动器。更新会保留该启动器。要修复较旧或缺失的启动器,请运行 /absolute/path/to/bun <package-root>/openclaw.mjs doctor --fix。包含空格、引号、美元符号、反引号、反斜杠和 glob 模式的路径仍按字面处理。包含换行符或回车符的路径需要显式调用 Bun,而不是使用生成的启动器。有关更新、回滚和自定义 bin 行为,请参见 仅使用 Bun 的安装。

生命周期脚本

Bun 会阻止依赖生命周期脚本,除非显式信任这些脚本。对于此仓库,通常被阻止的脚本并非必需:

  • baileys preinstall:检查 Node 主版本 >= 20(OpenClaw 需要 Node 24.16+ 或 26.1+,推荐使用 Node 26)
  • protobufjs postinstall:发出关于不兼容版本方案的警告(无构建产物)

如果你遇到需要这些脚本的运行时问题,请显式信任它们:

bun pm trust baileys protobufjs

注意事项

在 macOS 上,运行 brew install sqlite 以获得原生向量搜索支持。Bun 1.4.2 在关闭后可能仍保留 SQLite 句柄和 WAL/共享内存文件;当需要及时释放文件时,请使用 Node。有关库的选择、要求和限制,请参见 Bun 兼容性。

某些包脚本在内部硬编码了 pnpm(例如 check:docs、ui:*、protocol:check)。通过 bun run 运行它们仍会转交给 pnpm,因此直接使用 pnpm 运行即可。

仓库的 npm 打包辅助工具会在 Bun 下直接运行打包好的 npm CLI,包括在 Windows 上。它们不需要在 Bun 可执行文件旁放置 npm。显式选择的 Node 工具链仍会使用其自身附带的 npm 安装。

Gateway 进程检查会识别 Bun 的 --watch 和 --hot 标志。ACP 桥接检测会识别 Bun 和当前运行时可执行文件,包括自定义文件名。使用任一运行时构建的可移植云 worker 归档都会以 Node 为目标,且 worker 推理错误会从其受限的诊断消息中省略运行时堆栈属性。

已知限制

从 2026.9.7 配合较旧的系统 Node 进行更新

2026.9.7 CLI 会将受信任的系统目录(/usr/bin、/bin)放在用户的 PATH 之前,以防二进制劫持。通过 Bun 托管的更新器,npm 因此可以使用较旧的系统 Node 运行目标版本的安装检查,即使调用方的 PATH 中有受支持的 Node。如果该 Node 低于受支持的最低版本,暂存过程会拒绝更新并保持现有安装不变。此限制影响由 2026.9.7 驱动的更新。

对于这一次更新,请在受支持的 Node 24 上同时运行 Gateway 和更新器,然后再切换回 Bun。仅切换更新器是不够的。经过验证的步骤使用 Node 24.19.0,并在 270.9 秒内完成更新:

runtime=/path/to/node-24/bin/node
bun=/path/to/bun
package=/path/to/lib/node_modules/openclaw
export PATH="/path/to/node-24/bin:$PATH"

"$runtime" "$package/openclaw.mjs" gateway install --runtime node --runtime-path "$runtime" --force --json

请使用你实际的绝对路径,并使用与 Gateway 相同的安装前缀、profile 和状态/配置。等待 Node Gateway 就绪后,再运行常规更新:

"$runtime" "$package/openclaw.mjs" update --yes

若要指定特定版本或本地包,请添加 --tag <version> 或 --tag ./openclaw.tgz(参见 更新)。

仅在更新成功后,再恢复 Bun:

"$bun" "$package/openclaw.mjs" gateway install --runtime bun --runtime-path "$bun" --force --json

等待 Bun Gateway 就绪,然后验证其状态:

"$bun" "$package/openclaw.mjs" gateway status --json

2026.9.7 的回滚完成

更新失败后,2026.9.7 更新器可以逐字节恢复之前的安装,然后等待 Gateway 就绪,再报告回滚成功,即使使用了 --no-restart 也是如此。已验证的 Node 和 Bun 运行在 --timeout 1200 下均等待了约 20 分钟;这并非 Bun 特有的问题。请让更新器完成,然后按照其打印的恢复命令操作。如果 Gateway 服务已停止,请运行 openclaw gateway start,或运行 openclaw doctor 获取恢复指导(如有需要,请显式使用 Bun 调用它,如上文所示)。包回滚成功并不意味着失败的更新已成功,也不意味着已验证 Gateway 就绪。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw