Bun Compatibility and Installation Guide for OpenClaw
This page explains Bun's limited compatibility with OpenClaw and provides installation steps. It is intended for developers using Bun as a package-script runner who need to know when to use pnpm instead.
Read this when
- You want to install dependencies or run package scripts with Bun
- You want to run OpenClaw with Bun 1.4+
- You hit Bun install/patch/lifecycle script issues
Warning
OpenClaw's CLI and Gateway are incompatible with Bun releases up to 1.3.x, as those versions lack the required
node:sqliteAPI. The runtime is probed by OpenClaw for features: Bun builds shippingnode:sqlite(1.4.0 canary and later) support experimental CLI and Gateway execution, while older Bun versions get rejected during startup. For every OpenClaw runtime command, Node stays the officially supported and recommended runtime.
As an optional package-script runner, Bun remains viable. The default package manager stays pnpm, which is fully supported and utilized by the docs tooling. Since Bun cannot use pnpm-lock.yaml and simply disregards it, and because current Bun releases fail to resolve this repo's pnpm-workspace.yaml layout during bun install, dependency installations should go through pnpm install.
Install
Install dependencies
pnpm install
Workspace resolution fails with current Bun versions (including 1.4 canary) because they cannot resolve this repo's pnpm workspace layout, so bun install errors out. Instead, use pnpm install.
Build and test
bun run build
bun run vitest run
Commands that start OpenClaw itself should still be executed with Node; Bun runtimes providing node:sqlite (1.4.0 canary and later) can run them on an experimental basis.
Lifecycle scripts
Unless explicitly trusted, Bun blocks dependency lifecycle scripts. For this repo, the scripts that commonly get blocked are not necessary:
baileyspreinstall: verifies that Node major is >= 20 (OpenClaw needs Node 22.22.3+, 24.15+, or 25.9+, with Node 26 being the recommended choice)protobufjspostinstall: outputs warnings about incompatible version schemes (no build artifacts are produced)
If a runtime issue arises that requires these scripts, trust them explicitly:
bun pm trust baileys protobufjs
Caveats
Some package scripts have pnpm hardcoded internally (for instance check:docs, ui:*, protocol:check). Even when executed via bun run, they still shell out to pnpm, so it's simpler to run those directly through pnpm.