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. Set OPENCLAW_SQLITE_LIBRARY in the process environment before starting OpenClaw to override discovery:
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

  • 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