OpenClaw on Bun

The docs open the Bun page with a warning rather than a pitch: Node remains OpenClaw’s primary, default and recommended runtime, and Bun 1.4 builds that provide a write-ahead-log-safe SQLite binding can run the CLI, the Gateway and the managed node host as an explicit opt-in. Older Bun versions and builds with unsafe SQLite are rejected. Here is what the opt-in covers, the SQLite rules, the install and lifecycle caveats, the known limitations, and the history that explains why the page reads the way it does.

What the opt-in covers

• Bun 1.4.0 or newer, an available node-style SQLite API, and the same write-ahead-log-safe SQLite floor as Node: 3.51.3 or newer, or the patched floors within the 3.50 and 3.44 lines.
• Running OpenClaw under Bun is a flag at onboarding, installing the managed Gateway with the Bun daemon runtime, and a separate flag for a managed node host; commands that launch OpenClaw otherwise use Node by default.
• As a package-script runner Bun stays usable for build and test scripts, but the default package manager remains pnpm: Bun cannot use the pnpm lockfile and fails to resolve the repository’s workspace layout, so dependency installs use pnpm.
• Bun blocks dependency lifecycle scripts unless trusted; the commonly blocked ones here, a Node-major check and a warning-only post-install, are not required, and the trust command exists if a runtime issue needs them.

Node remains OpenClaw's primary, default, and recommended runtime.

SQLite on each platform

On Linux and Windows Bun ships a statically linked SQLite with extension loading, so nothing else is needed. On macOS Bun uses Apple’s system SQLite by default, whose extension loading is unavailable, so OpenClaw selects a suitable library before opening databases: an explicit library variable first, then the Homebrew prefix, the Apple-silicon and Intel Homebrew paths, and MacPorts, each candidate having to meet the safety floor and support extension loading. Installing Homebrew SQLite is the docs’ one-line fix for native vector search. Managed Bun services on macOS persist the library variable and the Homebrew prefix from the installing shell, a forced reinstall changes them, startup logs the library it chose, and the doctor reports the selection. When the memory search child cannot load extensions, search falls back to a batched embedding scan that keeps the filters but can be slower on large indexes.

Known limitations

• Desktop WebSocket streams use the installed transport rather than Bun’s built-in adapter, which lacks pause, resume and the stream bridge that preserves backpressure and cleanup.
• Bun 1.4.2 can retain SQLite statement handles and write-ahead-log files after close, which OpenClaw cannot finalise through the public API; the docs say to use Node when prompt file release matters. Storage workers are one per distinct database with at most four open, and a fifth fails without disturbing the rest.
• Some package scripts hardcode pnpm and shell out to it even under Bun, and the workspace install limitation stands.

OpenClaw system requirements carries the Node and SQLite floors this page inherits, and Install OpenClaw on a Mac the conventional install on the platform where the library rule matters.

The history behind the warning

The release table explains the tone: early 2026 documented Bun as an optional script runner, then introduced a Bun daemon runtime only with WhatsApp disabled because a WebSocket reconnect path could corrupt memory, then labelled Gateway use experimental after WhatsApp and Telegram bugs, then removed Bun from the runtime picker; mid-year rejected Bun outright when the SQLite binding was unavailable, and v2026.8.1 restored explicit managed-service selection with the current requirements, followed by a WebSocket compatibility repair in v2026.8.2. OpenClaw memory explained explains the vector search that the macOS library rule exists for.

On Diali

On Diali the runtime is Node, pinned per release and exercised on our own assistants before it rolls out, so the Bun question never reaches you. Hosted OpenClaw on Diali is the assistant and We run every release on our own agents first describes the release train.

• Node by default; Bun by explicit flag on 1.4 with safe SQLite.
• macOS needs an extension-capable SQLite library.
• Install with pnpm; Bun cannot read the workspace.