Files
openclaw/docs/install/bun.md
Peter Steinberger 6a6635abb3 feat(daemon): support Bun 1.4 managed services (#129593)
* feat(daemon): support Bun 1.4 managed runtimes

Amp-Thread-ID: https://ampcode.com/threads/T-01a037b7-66db-71f0-91e7-1578b383afb2

* fix(daemon): enforce Bun SQLite safety

Amp-Thread-ID: https://ampcode.com/threads/T-01a037b7-66db-71f0-91e7-1578b383afb2

* fix(daemon): preserve lightweight Bun startup

Amp-Thread-ID: https://ampcode.com/threads/T-01a037b7-66db-71f0-91e7-1578b383afb2

* docs: show Bun runtime opt-in commands

Amp-Thread-ID: https://ampcode.com/threads/T-01a037b7-66db-71f0-91e7-1578b383afb2

---------

Co-authored-by: Amp <amp@ampcode.com>
2026-08-26 00:45:43 -07:00

2.5 KiB

summary, read_when, title
summary read_when title
Bun workflow for installs, package scripts, and opt-in runtime use
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
Bun
Node remains OpenClaw's primary, default, and recommended runtime. Bun 1.4+ builds that provide WAL-reset-safe `node:sqlite` can run the CLI, Gateway, and managed node host as an explicit opt-in. OpenClaw requires SQLite 3.51.3+, 3.50.7+ within 3.50.x, or 3.44.6+ within 3.44.x; older Bun versions and builds with unsafe SQLite are rejected.

Bun remains usable as an optional package-script runner. The default package manager remains pnpm, which is fully supported and used by docs tooling. Bun cannot use pnpm-lock.yaml and ignores it, and current Bun versions fail to resolve this repo's pnpm-workspace.yaml layout during bun install, so dependency installs should use pnpm install.

Install

```sh pnpm install ```
Bun cannot resolve this repo's pnpm workspace layout, so `bun install` fails during workspace resolution. Use `pnpm install`.
```sh bun run build bun run vitest run ```
Use Node by default for commands that launch OpenClaw.
To run onboarding under Bun and install the managed Gateway under Bun:
```sh
bun openclaw.mjs onboard --install-daemon --daemon-runtime bun
```

For a managed node host, select Bun separately:

```sh
bun openclaw.mjs node install --runtime bun
```

Lifecycle scripts

Bun blocks dependency lifecycle scripts unless explicitly trusted. For this repo, the commonly blocked scripts are not required:

  • baileys preinstall: checks Node major >= 20 (OpenClaw requires Node 22.22.3+, 24.15+, or 25.9+, with Node 26 recommended)
  • protobufjs postinstall: emits warnings about incompatible version schemes (no build artifacts)

If you hit a runtime issue that needs these scripts, trust them explicitly:

bun pm trust baileys protobufjs

Caveats

Some package scripts hardcode pnpm internally (for example check:docs, ui:*, protocol:check). Running them via bun run still shells out to pnpm, so just run those via pnpm directly.