OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Runtimes

Bun compatibility

Bun is an explicit opt-in runtime for OpenClaw's CLI, Gateway, and managed node host. Node remains the primary and recommended runtime. This reference covers Bun requirements and compatibility; see Bun for installation and opt-in steps, or Node.js compatibility for Node requirements.

Requirements

OpenClaw requires Bun 1.4.0+, an available node:sqlite API, and the same WAL-safe SQLite floor as Node.

Platform SQLite library Bun uses Extension loading What OpenClaw does
Linux Statically linked SQLite; 3.53.2 in Bun 1.4.2 Supported No additional library setup needed.
macOS Apple system SQLite by default Unavailable in Apple's library Automatically selects a suitable library; see below.
Windows Same static SQLite build as Linux Supported No additional library setup needed.

The platform defaults come from Bun's SQLite build policy; the Bun 1.4.2 version definition pins SQLite 3.53.2.

SQLite library selection on macOS

Install Homebrew SQLite for native sqlite-vec KNN memory queries:

sh
brew install sqlite

Before opening databases, OpenClaw selects a library in this order:

  1. An explicit library path supplied internally, otherwise OPENCLAW_SQLITE_LIBRARY.
  2. $HOMEBREW_PREFIX/opt/sqlite/lib/libsqlite3.dylib.
  3. /opt/homebrew/opt/sqlite/lib/libsqlite3.dylib.
  4. /usr/local/opt/sqlite/lib/libsqlite3.dylib.
  5. /opt/local/lib/libsqlite3.dylib (MacPorts).

Candidates must meet the WAL safety floor and support extension loading before selection. If automatic discovery finds no qualifying library, Bun keeps its runtime library; ordinary agent databases can open if that library meets the WAL floor. The memory KNN child uses the same selected library.

Set OPENCLAW_SQLITE_LIBRARY in the process environment before starting OpenClaw to override discovery:

sh
OPENCLAW_SQLITE_LIBRARY=/path/to/libsqlite3.dylib bun openclaw.mjs gateway

On macOS, openclaw gateway install --runtime bun, openclaw node install --runtime bun, and wrapper-based installs persist OPENCLAW_SQLITE_LIBRARY and HOMEBREW_PREFIX from the installing shell into the managed service definition, so the service selects the same library. To change these values for an already-installed service, reinstall with openclaw gateway install --runtime bun --force (or openclaw node install --runtime bun --force for a managed node host) from a shell with the desired values; a bare reinstall of an already-loaded service is a no-op. Direct Node-runtime services never persist them.

An invalid override fails with:

text
Cannot use SQLite library <path>: <reason>. Fix or unset OPENCLAW_SQLITE_LIBRARY; install a supported library with brew install sqlite.

Node and non-macOS Bun ignore this override, with a warning in Gateway startup logs. When a library is selected, Gateway startup logs SQLite: using <path> (<version>, extension loading enabled). openclaw doctor reports the selection for the doctor process.

Daemon install, openclaw gateway start repair, openclaw doctor, and service audits probe candidate Bun executables through the same selection, so they judge and report the library the Gateway will actually open rather than Bun's runtime SQLite. An invalid override fails those probes with the message above instead of advising a Bun upgrade or switching the service to Node.

If you previously used a preload that calls Database.setCustomSQLite(), remove it and set OPENCLAW_SQLITE_LIBRARY to the same path instead. The hook is one-shot: keeping the preload causes SQLite already loaded, even if both selections name the same library. OpenClaw's override also forwards the path to the KNN child.

Memory search without an extension-capable library

When the KNN child cannot load extensions, memory search falls back to a batched embedding scan. It preserves provider and source filters and cancellation checks between batches, but can be slower on large indexes. See Memory configuration.

Known limitations

  • Lifecycle scripts: Bun blocks dependency lifecycle scripts unless explicitly trusted with bun pm trust.
  • Package scripts: Some scripts hardcode pnpm, so bun run still invokes pnpm internally.
  • SQLite handles: Bun 1.4.2 can retain statement handles and WAL/shared-memory files after DatabaseSync.close() or Symbol.dispose(); OpenClaw cannot finalize them through Bun's public node:sqlite API. See the upstream close fix; use Node when prompt file release matters.
  • Workspace installation: bun install cannot resolve this repository's pnpm workspace layout. Use pnpm install.

See Bun for the workflow and lifecycle trust commands.

History across releases

Release Change
Unreleased (main) Managed Bun services on macOS persist OPENCLAW_SQLITE_LIBRARY and HOMEBREW_PREFIX from the installing shell.
Unreleased (main) Daemon install, repair, doctor, and service audits probe Bun executables through the same SQLite library selection as Gateway startup, with a minimal probe environment. #142186
Unreleased (main) Automatically selects a WAL-safe, extension-capable macOS SQLite library and propagates it to the memory KNN child. Adds OPENCLAW_SQLITE_LIBRARY. #141854
Unreleased (main) Documents Bun 1.4.2 retaining native statements and WAL/shared-memory files after close or disposal, with Node advised when prompt file release matters. #141846
Unreleased (main) Adds batched embedding-scan fallback when the KNN child cannot load extensions, preserving provider/source filters and cancellation between batches. #141104
Unreleased (main) Allows ordinary agent databases on SQLite builds without extension loading. Native vector search still needs an extension-capable library. #139487
v2026.8.2 Repairs Bun 1.4 authenticated Gateway WebSocket compatibility with the installed npm receiver, preserving payload limits and request scheduling. #134282
v2026.8.1 Restores explicit managed-service selection for the CLI, Gateway, and managed node host, requiring Bun 1.4.0+, node:sqlite, and WAL-safe SQLite. #129593
v2026.7.2-beta.5; stable v2026.8.1 Restores experimental CLI/Gateway support for builds providing node:sqlite, documented as 1.4.0 canary and later; the guard uses an API probe without a numeric Bun minimum at this stage. #114256
v2026.7.2-beta.5; stable v2026.8.1 Documents bun install failing on the pnpm workspace layout and changes dependency instructions to pnpm install; Bun remains a script runner. #114256
v2026.7.1; main v2026.7.2-beta.1 Rejects Bun CLI/Gateway use because node:sqlite is unavailable, makes managed runtime selection Node-only, and directs legacy Bun services to Node. Package-script use remains available. #106065
v2026.1.12 Labels Bun Gateway use experimental and not recommended because of WhatsApp/Telegram bugs; recommends Node for production.
v2026.1.9 Removes Bun from the interactive daemon-runtime picker while the explicit validator still accepts Bun.
v2026.1.8 Documents Bun as an optional package-script runner for local builds/tests, with optional dependency installation at that time. pnpm remains primary.
v2026.1.8 Documents ignored pnpm lockfiles, a historical postinstall patch bridge, lifecycle trust, and scripts that invoke pnpm internally. The patch bridge is not a current install recommendation.
v2026.1.8 Introduces optional --daemon-runtime bun when WhatsApp is disabled because the Baileys WebSocket reconnect path could corrupt memory under Bun. Node remains the default and recommendation.
Was this useful?
On this page

On this page