Skip to main content
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. 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:
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. SQLite storage workers inherit the main process’s selected library. Opening another database or restarting a storage worker reuses that selection without repeating Bun’s one-shot library initialization. Set OPENCLAW_SQLITE_LIBRARY in the process environment before starting OpenClaw to override discovery:
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:
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

  • Desktop WebSockets: OpenClaw uses the installed ws transport for desktop observers and paired-node desktop/portal streams. Bun 1.4.2’s built-in ws server adapter lacks pause/resume and the Duplex stream bridge; the installed transport preserves backpressure, payload limits, and cleanup when a desktop disconnects.
  • 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.
  • PTY terminals: macOS and Linux require an installed Node runtime for terminal I/O. OpenClaw skips Bun’s node shim when selecting that runtime, including under bun --bun.
  • Gateway computer control: the host worker requires an installed Node runtime. OpenClaw skips Bun’s node shim when selecting that runtime, including under bun --bun.
  • 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.
  • SQLite storage workers: Bun uses one worker per distinct database and can use up to 64 dedicated workers within the host’s 64-client cap. Clients of the same database share its worker. Closing the last client waits for worker exit to release native handles; capacity exhaustion rejects new work without interrupting existing stores. Node multiplexes databases across four shared workers. Bun’s dedicated layout can be revisited after the upstream close fix ships and repeated close/reopen tests prove native handles and locks are released.
  • 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