How to Fix OpenClaw Installation Errors

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 git

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 --version

# 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+

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 install

# 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_modules

# 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 install

# 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 conflicts

# 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 support