How to Install OpenClaw with Bun

Bun support in OpenClaw is for local development speed, not production Gateway hosting. The official docs put the warning right up front: Bun is not recommended for gateway runtime because of known WhatsApp and Telegram issues. That does not make Bun useless. It can still be a fast way to run TypeScript directly, test local loops, or watch development scripts when you understand the caveats.

30-second answer

Use Bun when you are working on OpenClaw locally and want a fast dev loop. Run bun install or bun install --no-save, then use bun run build or bun run vitest run where supported. Keep pnpm as the default package manager for normal repository workflows, and keep Node for production Gateway runtime unless the docs change.

Where it fits

This is for contributors and operators who already understand the Node-based path and want a faster local iteration mode. It is not the first setup I would give a non-technical operator. If the goal is a stable always-on assistant, follow the normal install path. If the goal is editing OpenClaw code or experimenting with a TypeScript script, Bun can be convenient.

Docs-grounded facts

• The docs call Bun experimental for OpenClaw.
• Bun is not recommended for Gateway runtime.
• Bun can run TypeScript directly with bun run and bun --watch.
• The default package manager remains pnpm.
• Bun cannot use pnpm-lock.yaml.
• bun.lock and bun.lockb are gitignored.

Set it up deliberately

Install Bun, run bun install in the repo, and remember that bun.lock or bun.lockb are gitignored so you do not create repo churn. Use --no-save when you want to skip lockfile writes entirely. Then try bun run build or bun run vitest run. Some scripts still hardcode pnpm, including docs and UI-related scripts, so run those through pnpm for now.

Use it safely

Do not swap the Gateway runtime to Bun just because a local build worked. The docs explicitly recommend Node for production. Also watch lifecycle scripts: Bun blocks dependency lifecycle scripts unless explicitly trusted. The docs mention @whiskeysockets/baileys preinstall and protobufjs postinstall as commonly blocked scripts that are not required for the repo’s usual path.

Common mistakes

The common mistake is treating Bun as a drop-in replacement for every command. It is not. It ignores pnpm-lock.yaml, and some scripts assume pnpm. Another mistake is trusting blocked lifecycle scripts reflexively. Only trust scripts when you know the runtime issue requires them; otherwise keep the default blocked behavior.

Verification checklist

Run the specific build or test you need, then run the same critical path through the canonical package manager before shipping. If you touched messaging integrations, test them under the Node Gateway runtime. For docs or UI scripts that hardcode pnpm, do not spend time fighting Bun; use pnpm and move on.

Playbook angle

The OpenClaw Playbook’s practical advice is to separate dev speed from production reliability. Bun can make local iteration pleasant, but the operator runbook should still say Node for the Gateway until Bun is officially recommended for that job.

Operator note

How to Install OpenClaw with Bun works best when it is written into a small runbook instead of left as tribal knowledge. Record the intended owner, the exact config surface, the channel where results should appear, the allowed inputs, the expected output, and the rollback step. OpenClaw gives agents broad tools, but the durable value comes from making each tool boring, repeatable, and auditable. I would rather have one well-scoped Bun setup workflow that survives a restart than five clever demos nobody can safely run next week. If the runbook cannot explain when not to use it, keep refining before automation becomes default.