Environment:Openclaw Openclaw Node 22 Runtime
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Runtime |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Node.js 22.12.0+ runtime environment with pnpm 10.23.0 package manager, required for running the OpenClaw CLI and Gateway server.
Description
OpenClaw requires Node.js version 22.12.0 or higher as its core runtime. The project uses ESM modules exclusively (type: "module" in package.json) and leverages Node 22 features including the experimental SQLite built-in module. The package manager is pnpm 10.23.0 (exact version, managed via Corepack). Bun is optionally supported for development workflows (running TypeScript files, tests) but Node remains required for production builds and the built output.
Usage
This environment is required for all OpenClaw operations: CLI commands, gateway server startup, plugin installation, and development workflows. It is the foundational runtime prerequisite for every Implementation in the repository.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux, macOS, or Windows (WSL2) | All major platforms supported; Windows requires WSL2 for some features (Signal) |
| Runtime | Node.js >= 22.12.0 | ESM-only; uses experimental SQLite built-in |
| Package Manager | pnpm 10.23.0 (exact) | Managed via Corepack; Bun supported for dev only |
| Disk | ~500MB for node_modules | Plus additional space for state directory (~100MB+) |
Dependencies
System Packages
- Node.js >= 22.12.0 (hard requirement, specified in package.json engines field)
- pnpm = 10.23.0 (exact version via Corepack, specified in packageManager field)
- Corepack (ships with Node.js 22+; must be enabled via `corepack enable`)
Optional Development Tools
- Bun (any recent version) — for running TypeScript directly, dev scripts, test execution
- tsdown — bundler used for production builds (installed via pnpm)
- Oxlint — linter (installed via pnpm)
- Oxfmt — formatter (installed via pnpm)
Credentials
No credentials are required for the base runtime environment. Model provider and channel credentials are documented in the Environment:Openclaw_Openclaw_State_Directory_And_Credentials page.
Quick Install
# Install Node.js 22+ (via nvm, fnm, or direct download)
nvm install 22
nvm use 22
# Enable Corepack (ships with Node.js 22)
corepack enable
# Install dependencies
pnpm install
# Build
pnpm build
# Run CLI
pnpm openclaw --help
Code Evidence
Node.js version requirement from `package.json:184-186`:
"engines": {
"node": ">=22.12.0"
}
Package manager pinning from `package.json:187`:
"packageManager": "pnpm@10.23.0"
ESM module type from `package.json:23`:
"type": "module"
SQLite experimental warning suppression from `src/infra/warnings.ts:16-21`:
if (
warning.name === "ExperimentalWarning" &&
warning.message?.includes("SQLite is an experimental feature")
) {
return true;
}
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `SyntaxError: Cannot use import statement outside a module` | Node.js < 22 or missing `type: "module"` | Upgrade to Node.js 22.12.0+ |
| `ERR_UNKNOWN_FILE_EXTENSION .ts` | Trying to run TypeScript with Node directly | Use `bun` for TS files or build first with `pnpm build` |
| `corepack: command not found` | Corepack not enabled | Run `corepack enable` (requires Node 22+) |
| `ERR_PNPM_UNSUPPORTED_ENGINE` | Wrong Node.js version | Upgrade to Node.js >= 22.12.0 |
Compatibility Notes
- Bun: Supported for dev workflows (running scripts, tests) but not for production builds. Keep `pnpm-lock.yaml` in sync.
- npm: Supported for global installs (`npm i -g openclaw`) but pnpm is required for development.
- Nix: When `OPENCLAW_NIX_MODE=1`, auto-install flows are disabled and Nix-specific error messages are shown.
- Windows: Requires WSL2 for Signal channel support. Entry point normalizes Windows-specific argv control characters.