Problem: OpenClaw Install Fails or Gateway Won't Start

You ran the installer, it seemed to work, but openclaw gateway status shows errors or openclaw: command not found appears in your Terminal. This happens with Node.js version mismatches, PATH issues, and dependency build failures.

You'll learn:

Why the installer needs Node 22+ (not 18 or 20)
How to fix the sharp@0.34.5 build error on Apple Silicon
When to use openclaw doctor --fix vs manual fixes

Time: 20 min | Level: Intermediate

Why This Happens

OpenClaw runs as a persistent daemon that needs specific Node.js versions, proper PATH configuration, and native dependencies. The installer auto-detects your environment but fails silently on Arch Linux, old Node versions, or when npm global permissions are misconfigured.

Common symptoms:

openclaw: command not found after successful install
Gateway shows Error: Cannot find module after updates
sharp: Please add node-gyp to your dependencies on npm install
Port 18789 shows "connection refused"

Solution

Step 1: Verify Node.js Version

OpenClaw requires Node 22 or newer—not 18 or 20.

node --version

Expected: v22.x.x or v24.x.x

If you see v18 or v20:

# macOS/Linux - install via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc  # or ~/.zshrc
nvm install 22
nvm use 22

Why this matters: The codebase uses Node 22+ features. Older versions cause module resolution errors.

Step 2: Fix "openclaw: command not found"

This means npm's global bin directory isn't in your PATH.

# Check where npm installs global packages
npm prefix -g

# Add to PATH (bash/zsh on macOS/Linux)
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify
which openclaw

Expected: Shows /path/to/npm/bin/openclaw

On Windows: Add %AppData%\npm to your PATH environment variable, then restart PowerShell.

Step 3: Fix sharp Build Failure (Apple Silicon)

The sharp@0.34.5 dependency fails when prebuilt binaries are unavailable.

# Install Xcode Command Line Tools (macOS only)
xcode-select --install

# Set environment variable to skip system libvips
export SHARP_IGNORE_GLOBAL_LIBVIPS=1

# Reinstall OpenClaw
npm install -g openclaw@latest

Why this works: Forces sharp to use bundled binaries instead of building from source.

If it still fails:

# Install node-gyp globally
npm install -g node-gyp

# Try again
npm install -g openclaw@latest

Step 4: Check Gateway Status

openclaw gateway status

Expected output:

✓ Gateway running (PID: 12345)
✓ Port: 18789
✓ Config: ~/.openclaw/openclaw.json

If you see "Gateway not running":

# Run diagnostics
openclaw doctor

# Install/reinstall gateway service
openclaw onboard --install-daemon

If port 18789 is already in use:

# macOS/Linux - find what's using the port
lsof -ti:18789

# Kill the process
kill -9 <PID>

# Restart gateway
openclaw gateway restart

Step 5: Fix npm Permission Errors

Never use sudo with npm global installs—it causes ownership issues.

# Fix npm directory ownership
sudo chown -R $USER:$(id -gn $USER) ~/.npm

# Set proper global prefix
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# Update PATH
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Reinstall without sudo
npm install -g openclaw@latest

Why this matters: Root-owned files prevent normal updates and cause cryptic errors.

Step 6: Fix Installer Failure on Arch Linux

The installer doesn't detect pacman as a package manager.

# Install Node.js 22+ manually via pacman
sudo pacman -S nodejs npm

# Verify version
node --version  # Should be 22+

# Install OpenClaw via npm
npm install -g openclaw@latest

Alternative:

# Use the npm method directly
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm

Step 7: Fix "Module Not Found" After Updates

When OpenClaw updates between versions, soft restarts (SIGUSR1) don't reload new module hashes.

# Full restart required
openclaw gateway restart

# Or use doctor to fix
openclaw doctor --fix

Why this happens: Hashed filenames change between versions (e.g., auth-profiles-tVeejgE4.js → auth-profiles-CfFGCDJa.js), but SIGUSR1 keeps old references in memory.

Step 8: Fix Gateway Configuration Errors

Invalid config prevents gateway startup.

# Validate configuration
openclaw doctor

# Check for common issues
cat ~/.openclaw/openclaw.json | jq .

Common invalid values:

gateway.bind: "invalid" → Use "loopback", "lan", or "tailnet"
Missing gateway.auth.token when using non-loopback binds

Fix template:

{
  "gateway": {
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "generate-via-openclaw-doctor"
    }
  }
}

Step 9: Fix Docker Permission Errors

Container user (UID 1000) can't access mounted volumes.

# Fix ownership on host
sudo chown -R 1000:1000 ~/.openclaw ~/openclaw/workspace

# Restart container
cd ~/openclaw
docker compose restart

Verify:

docker compose ps
# Should show "Up" status

Step 10: Fix "npm install failed; cleaning up and retrying"

Generic upgrade failures during installer runs.

# Clear npm cache
npm cache clean --force

# Remove existing installation
npm uninstall -g openclaw

# Reinstall
npm install -g openclaw@latest

# If that fails, use the installer script
curl -fsSL https://openclaw.ai/install.sh | bash

Check logs:

openclaw logs --follow

Look for: Actual error messages (often dependency-related or network timeouts).

Verification

# Check installation
openclaw --version

# Verify gateway is running
openclaw gateway status

# Test control UI
openclaw dashboard

You should see:

Version 2026.2.x or newer
Gateway showing "Up" with PID
Dashboard opens at http://127.0.0.1:18789

What You Learned

OpenClaw strictly requires Node 22+—installers fail silently on older versions
PATH issues cause "command not found" even after successful npm installs
sharp build failures need Xcode tools + SHARP_IGNORE_GLOBAL_LIBVIPS on macOS
Never use sudo with npm global installs
Full restarts required after updates (SIGUSR1 doesn't reload new modules)

Limitations:

Arch Linux installer doesn't auto-detect pacman (manual Node install needed)
Windows users should use WSL2 instead of native PowerShell
Apple Silicon requires Xcode Command Line Tools for native dependencies

Tested on OpenClaw 2026.2.x, Node.js 22.x/24.x, macOS 14+, Ubuntu 22.04/24.04, Arch Linux