Bun (Experimental)

CLI-only usage via the Bun runtime. Fastest local dev loop but not recommended for Gateway runtime (WhatsApp/Telegram bugs).

Bun is an experimental runtime option for OpenClaw, offering the fastest local development loop thanks to Bun's speed advantages over Node.js for dependency installation and script execution. However, it is explicitly not recommended for running the Gateway in production — known bugs with WhatsApp and Telegram channel integrations make it unreliable for persistent messaging. The Bun path is primarily useful for contributors and plugin developers who want faster `bun install` and `bun run build` cycles during development. Bun's near-instant dependency resolution and built-in TypeScript support make iterating on OpenClaw's codebase noticeably faster than the equivalent Node.js workflow. Test suites run well under Bun, and the CLI tooling works for local agent interactions. The key limitation is runtime compatibility. Bun's Node.js compatibility layer doesn't perfectly replicate Node's networking behavior, which causes intermittent failures in WebSocket-heavy channel integrations like WhatsApp (which uses the Baileys library) and Telegram (which relies on grammy's long-polling). These bugs manifest as dropped connections, missed messages, and authentication failures that don't occur under Node.js. Use Bun for development and testing, but switch to Node.js (22.16+ or 24) for running the Gateway. The OpenClaw team monitors Bun compatibility and may promote it to supported status as Bun's Node.js compatibility improves.

Tags: bun, experimental, fast, dev

Use Cases

  • Faster development iteration when contributing to OpenClaw's codebase
  • Running the test suite quickly during plugin or skill development
  • Quick local agent interactions via CLI where channel stability doesn't matter

Tips

  • Use Bun only for development: bun install for fast deps, bun run build for quick builds, bun run vitest for tests
  • Switch to Node.js for running the actual gateway — keep Bun as your build tool only
  • If testing channel integrations, always test under Node.js before concluding something is broken
  • Bun's built-in TypeScript support means you can skip the build step for quick CLI testing

Known Issues & Gotchas

  • WhatsApp channel has known connection stability bugs under Bun — messages may be dropped or auth may fail
  • Telegram long-polling can behave erratically under Bun's networking layer
  • The macOS companion app expects Node.js — Bun won't integrate with launchd service management
  • Some native Node modules (like sharp) may not build correctly with Bun
  • Gateway daemon install (openclaw gateway install) assumes Node.js — Bun lacks systemd/launchd integration
  • Production use is explicitly unsupported — don't file bugs for gateway issues when running under Bun

Alternatives

  • Node.js (npm/pnpm)
  • From Source (pnpm)

Community Feedback

Bun is not recommended for the Gateway runtime. WhatsApp and Telegram have known bugs under Bun. Use Node.js for production.

— OpenClaw Docs

bun install is 3x faster than pnpm install for OpenClaw's dependency tree. Great for dev, just don't run the gateway with it.

— GitHub Issues

Tried running the gateway on Bun for speed. WhatsApp kept disconnecting. Switched back to Node and it's been stable since.

— Reddit r/selfhosted

Frequently Asked Questions

Why isn't Bun recommended for the Gateway?

Bun's Node.js compatibility layer has known issues with WebSocket-heavy libraries used by WhatsApp (Baileys) and Telegram (grammy). This causes dropped connections and missed messages that don't occur under Node.js.

Can I use Bun for install and Node for runtime?

Partially. You can use bun install for faster dependency resolution, but you should run the gateway with Node.js. However, some native modules may behave differently between the two runtimes, so this isn't officially supported.

When will Bun be fully supported?

The OpenClaw team monitors Bun's Node.js compatibility improvements. When the WebSocket and networking issues are resolved upstream, Bun may be promoted to supported status. No ETA has been announced.

Does the CLI work under Bun?

Yes, basic CLI commands like openclaw --version, openclaw doctor, and local agent interactions work fine. The issues are specific to the long-running gateway process and its channel integrations.