Why Build from Source
Most users can quickly install OpenClaw via npm install -g openclaw@latest. However, in certain scenarios building from source is the better choice: you want to contribute code to fix bugs or add new features, you need the latest development version rather than a stable release, you want to deeply understand OpenClaw's internals, or you need to customize the source code for specific requirements.
This article covers the complete process from git clone to a finished build.
Prerequisites
Building OpenClaw from source requires the following tools:
- Node.js 22+: OpenClaw's minimum runtime requirement. Do not use Bun, as there are known bugs when handling WhatsApp and Telegram connections
- pnpm: The OpenClaw project uses pnpm as its package manager
- Git: For cloning the source repository
- C/C++ build toolchain: Some native dependencies require compilation
Installing Node.js 22
If Node.js is not yet installed, using nvm is recommended:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
Verify the version:
node --version # Should display v22.x.x
Installing pnpm
Enable pnpm via Node.js's built-in corepack:
corepack enable
corepack prepare pnpm@latest --activate
Or install via npm:
npm install -g pnpm
Verify the installation:
pnpm --version
Installing the Build Toolchain
On Ubuntu/Debian:
sudo apt install -y build-essential python3
On macOS:
xcode-select --install
Cloning the Source Repository
Clone the OpenClaw repository from GitHub:
git clone https://github.com/openclaw/openclaw.git
cd openclaw
If you want to use the latest development version:
git checkout dev
If you want to build from a specific stable version:
git tag -l
git checkout v1.0.0 # Replace with the actual version number
Installing Dependencies
Install all project dependencies using pnpm:
pnpm install
OpenClaw is a monorepo project, and pnpm automatically handles dependency relationships between packages within the workspace. Some native Node.js modules may need to be compiled during installation, which is why the C/C++ build toolchain was required earlier.
Approving Native Builds
Some dependencies contain native code that requires compilation. For security reasons, pnpm will ask you to explicitly approve these builds:
pnpm approve-builds -g
This command lists all packages requiring native compilation and requests your confirmation. Review the list to confirm nothing unusual, then approve.
Building the Project
OpenClaw's build consists of two steps: first build the frontend UI, then build the entire project.
Building the Frontend Dashboard
pnpm ui:build
This compiles the OpenClaw admin panel frontend code and typically takes 1-3 minutes depending on your machine's performance.
Building the Main Project
pnpm build
This command compiles the TypeScript source code, bundles all modules, and generates the final executable artifacts.
After the build completes, you can find the compiled artifacts in the project root directory.
Verifying the Build
Run tests to ensure the build is correct:
pnpm test
Then try starting OpenClaw:
pnpm start
Or run the built CLI directly:
node ./dist/cli.js --version
Linking as a Global Command
If you want to use the openclaw command from anywhere, just like an npm installation, you can use pnpm's link feature:
pnpm link --global
After that, you can run from any location on the system:
openclaw --version
openclaw doctor
Initial Configuration
When running OpenClaw for the first time, execute the onboarding process:
openclaw onboard --install-daemon
The onboarding process guides you through AI model configuration, chat platform connection setup, and daemon installation based on your operating system (LaunchAgent on macOS, systemd service on Linux).
Configuration files are saved in ~/.openclaw/openclaw.json.
Development Mode
If you're building to contribute code, you can start in development mode:
pnpm dev
Development mode enables hot reloading — when you modify source code, it automatically recompiles and restarts the service, greatly improving development efficiency.
Project Structure Overview
Understanding the project structure helps you locate the code you want to modify:
openclaw/
├── packages/
│ ├── core/ # Core engine, message routing and AI model scheduling
│ ├── cli/ # Command-line tool
│ ├── ui/ # Dashboard frontend
│ ├── whatsapp/ # WhatsApp connector
│ ├── telegram/ # Telegram connector
│ ├── discord/ # Discord connector
│ └── ... # Other platform connectors
├── pnpm-workspace.yaml
└── package.json
Updating Source Code
When the upstream repository has updates, you can pull the latest code and rebuild:
git pull origin main
pnpm install
pnpm approve-builds -g
pnpm ui:build
pnpm build
If you have local modifications, consider stashing them or working on a branch to avoid merge conflicts.
Common Build Issues
pnpm install Fails
Ensure Node.js version is 22+ and pnpm is sufficiently up to date. Clear the cache and retry:
pnpm store prune
rm -rf node_modules
pnpm install
Native Module Build Fails
Check that the complete build toolchain is installed. On Ubuntu, make sure build-essential and python3 are installed.
ui:build Runs Out of Memory
Frontend builds can consume significant memory. You can increase the Node.js memory limit:
NODE_OPTIONS="--max-old-space-size=4096" pnpm ui:build
Errors After Building
Run openclaw doctor to check environment configuration and ensure all dependency versions are compatible.
Summary
Building OpenClaw from source involves more steps than a direct npm install, but it gives you full control. Whether you're participating in open source contributions, using development version features, or deeply customizing OpenClaw for your specific scenario, building from source is an essential skill. Once you master this process, you can keep up with OpenClaw's latest development progress and actively participate in community contributions.