Installation is the first hurdle in using OpenClaw. Whether you're hitting Homebrew errors, npm package conflicts, Node.js version issues, or permission errors, this guide provides systematic troubleshooting steps to get past common installation blockers and get OpenClaw running.
Why This Is Hard to Do Yourself
These are the common pitfalls that trip people up.
Homebrew not installed or broken
macOS users often have incomplete Homebrew installs, XCode CLT missing, or conflicting versions
Node.js version conflicts
System Node version too old, nvm/fnm version mismatch, or multiple Node installations conflicting
Permission errors
npm trying to write to system directories, node_modules permission issues, file ownership problems
Native module compilation
Some npm packages require build tools and fail on systems without C compiler, Python, or gcc
Step-by-Step Guide
Check and install prerequisites
Verify Node.js, npm, and Git are installed with correct versions.
node --version # Should be 20.x or higher
npm --version # Should be 8.x or higher
git --version # Should be 2.x or higher
# If any are missing or outdated:
# On macOS with Homebrew:
brew install node@20 git
# On Ubuntu/Debian:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs gitFix Homebrew issues (macOS)
Diagnose and repair broken Homebrew installations.
brew --version
brew doctor # Shows any issues
# Common fixes:
brew update
brew upgrade
# If Homebrew is broken:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Reinstall Node:
brew uninstall node@20
brew install node@20
# Verify:
which node
node --versionWarning: Never use sudo with Homebrew. It causes permission issues. If you see "sudo: brew: command not found", reinstall Homebrew without sudo.
Resolve Node.js version conflicts
Fix mismatched Node versions from nvm, fnm, or system installs.
# Check which node you're using:
which node
# If using nvm:
nvm list # See installed versions
nvm use 20 # Switch to Node 20
nvm alias default 20 # Set as default
# If using fnm (faster Node manager):
fnm list
fnm use 20
fnm default 20
# If node comes from Homebrew:
brew list | grep node
brew uninstall node # Remove old versions
brew install node@20 # Install correct version
# Verify after switching:
node --version # Must be 20.x+Clear npm cache to fix package conflicts
Remove corrupted npm cache that causes install failures.
npm cache clean --force
# Also clear npm config:
rm ~/.npmrc # Removes custom npm settings
# Set safe npm defaults:
npm config set registry https://registry.npmjs.org/
# Verify npm is healthy:
npm doctor
# Then retry install:
cd ~/openclaw
rm -rf node_modules package-lock.json
npm installWarning: After cache clean, npm install will be slower (first time downloading all packages again) but will be clean.
Fix permission errors in npm
Resolve "npm ERR! permission denied" errors.
# Problem: npm trying to write to /usr/local/lib/node_modules
# Solution 1: Use nvm or fnm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20
# Now npm writes to ~/.nvm instead of /usr/local
# Solution 2: Fix npm prefix (if not using nvm)
mkdir ~/.npm-global
npm config set prefix "~/.npm-global"
export PATH=~/.npm-global/bin:$PATH
echo "export PATH=~/.npm-global/bin:$PATH" >> ~/.bashrc # Or ~/.zshrc for zsh
# Solution 3: Fix existing node_modules permissions
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modulesInstall C compiler for native modules
Some npm packages compile native code and need build tools.
# macOS:
xcode-select --install # Install Xcode Command Line Tools
# Ubuntu/Debian:
sudo apt install -y build-essential python3
# CentOS/RHEL:
sudo yum install -y gcc g++ make python3
# After installing build tools, retry:
cd ~/openclaw
npm installWarning: Xcode CLT is large (~4GB). If install fails, try again or check your internet connection.
Try alternative installation methods if npm fails
Use Docker, Bun, or pre-built binaries if npm install persistently fails.
# Option 1: Use Docker (no Node.js needed)
docker pull openclaw/openclaw:latest
docker run -d -p 3000:3000 openclaw/openclaw:latest
# Option 2: Use Bun (faster npm alternative)
curl -fsSL https://bun.sh/install | bash
cd ~/openclaw
bun install
bun run start
# Option 3: Download pre-built binary (if available)
# Check GitHub releases for your OS
# Option 4: Try with different npm settings
npm install --omit=optional # Skip optional dependencies that might fail
npm install --legacy-peer-deps # Ignore peer dependency conflictsVerify installation succeeded
Confirm OpenClaw installed correctly and can start.
# Check if files installed:
ls -la ~/.openclaw/
ls -la ~/openclaw/node_modules | head -20
# Test npm commands:
npm list # Shows installed packages
npm --version
# Try starting OpenClaw:
cd ~/openclaw
npm start
# Should see:
# > OpenClaw starting on port 3000
# Access at http://localhost:3000
# If you see errors, capture full output:
npm start 2>&1 | tee openclaw-startup.log
# Share log with supportInstallation Blocking You?
Our installation experts debug Node.js setup, npm configuration, permission issues, and environment problems. Get OpenClaw running in your environment without the frustration.
Get matched with a specialist who can help.
Sign Up for Expert Help →