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. 安装依赖
Bun 无法解析此仓库的 pnpm workspace 布局,因此 bun install 会在 workspace 解析期间失败。请使用 pnpm install。
2. 构建并测试
启动 OpenClaw 的命令默认使用 Node。
在 Bun 下从源码运行时,复用当前可执行文件的工作线程会使用 Bun 的原生 TypeScript 支持,即使该可执行文件具有自定义文件名。显式要求 Node 的工作线程保留其 Node 加载器。
3. 使用 Bun 运行 OpenClaw
要在 Bun 下运行引导流程并在 Bun 下安装受管 Gateway:
对于受管节点宿主,请单独选择 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 会阻止依赖生命周期脚本,除非显式信任这些脚本。对于此仓库,通常被阻止的脚本并非必需:
baileyspreinstall:检查 Node 主版本 >= 20(OpenClaw 需要 Node 24.16+ 或 26.1+,推荐使用 Node 26)protobufjspostinstall:发出关于不兼容版本方案的警告(无构建产物)
如果你遇到需要这些脚本的运行时问题,请显式信任它们:
注意事项¶
在 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 就绪后,再运行常规更新:
若要指定特定版本或本地包,请添加 --tag <version> 或 --tag ./openclaw.tgz(参见 更新)。
仅在更新成功后,再恢复 Bun:
等待 Bun Gateway 就绪,然后验证其状态:
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