Install OpenClaw on macOS Apple Silicon Without Errors

Complete guide to installing OpenClaw on M3/M4 Macs with fixes for sharp, node-gyp, and PATH errors in under 20 minutes.
·
8 min read
·
Mark
·
AI Tools

Problem: OpenClaw Installation Fails on Apple Silicon Macs

You're trying to install OpenClaw on your M3 or M4 Mac, but the installation fails with sharp build errors, node-gyp failures, or the openclaw command isn't recognized after installation.

You'll learn:

  • How to fix the sharp@0.34.5 build failure on Apple Silicon
  • How to properly configure your PATH for OpenClaw
  • How to verify your installation is working
  • Common pitfalls and how to avoid them

Time: 20 min | Level: Beginner

Why This Happens

OpenClaw installation on Apple Silicon fails because of three common issues:

1. Node.js Version Mismatch OpenClaw requires Node.js 22+, but many developers have older versions installed via Homebrew or nvm.

2. The sharp Module Build Problem The sharp image processing library tries to build from source when it can't find pre-built binaries for your exact Node.js version. On Apple Silicon, this triggers node-gyp which often isn't configured correctly.

3. PATH Configuration The npm global bin directory isn't in your shell's PATH, so the openclaw command isn't recognized even after successful installation.

Common symptoms:

  • npm install -g openclaw@latest fails with "sharp: Attempting to build from source via node-gyp"
  • Installation completes but openclaw: command not found
  • Error: "Node version must be >= 22"

Solution

Step 1: Install the Correct Node.js Version

OpenClaw requires Node.js 22 or newer. Using nvm (Node Version Manager) is the most reliable approach.

Install nvm if you don't have it:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

Close and reopen your Terminal, then install Node.js 22:

# Install latest Node.js 22.x
nvm install 22

# Set it as default
nvm use 22
nvm alias default 22

Verify:

node --version
# Should show v22.x.x

Expected: Output like v22.22.0 or higher.

If it fails:

  • Error: "nvm: command not found": Restart your terminal or run source ~/.zshrc (or ~/.bashrc if using bash)
  • Wrong version shown: Run nvm use 22 again to activate it for the current session

Step 2: Install Xcode Command Line Tools (Required for Building)

Apple Silicon Macs need Xcode Command Line Tools to compile native modules.

xcode-select --install

Accept the license agreement when prompted.

Already installed? Verify with:

xcode-select -p
# Should show: /Library/Developer/CommandLineTools

Why this works: The Command Line Tools include compilers and build tools that node-gyp needs to build native modules like sharp.

Step 3: Install OpenClaw

Now that Node.js 22+ and build tools are ready, install OpenClaw globally:

npm install -g openclaw@latest

This takes 2-5 minutes. You'll see packages installing. The sharp package should install without errors.

Expected output (end of installation):

added 847 packages in 3m

If it fails with sharp errors:

Follow Step 3a below to force the correct architecture.

Step 3a: Force Apple Silicon Architecture (If Sharp Fails)

If you see sharp: Attempting to build from source via node-gyp, force npm to use the correct pre-built binary:

# Remove broken installation
npm uninstall -g openclaw

# Clear npm cache
npm cache clean --force

# Reinstall with explicit platform flags
npm install -g openclaw@latest --platform=darwin --arch=arm64

Why this works: The --platform=darwin --arch=arm64 flags tell npm to fetch the pre-built binary specifically for Apple Silicon instead of trying to build from source.

Step 4: Fix PATH Configuration

After installation, verify the openclaw command is accessible:

openclaw --version

If you get "command not found":

The npm global bin directory isn't in your PATH. Add it to your shell configuration:

# For zsh (default on macOS)
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# For bash (if you're using bash)
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Verify again:

openclaw --version
# Should show: openclaw version 2026.x.x

Expected: Version output confirms OpenClaw is installed and in your PATH.

Step 5: Run the Onboarding Wizard

Initialize OpenClaw with the interactive setup wizard:

openclaw onboard --install-daemon

The wizard will guide you through:

  1. Authentication setup (Anthropic, OpenAI, Google, or local models)
  2. Gateway configuration
  3. Optional channel setup (Telegram, WhatsApp, Discord, etc.)
  4. Installing the daemon for background operation

Choose QuickStart when prompted — it configures safe defaults so you can test immediately.

For model provider, choose based on what you have:

  • Anthropic (Claude): You need an API key from console.anthropic.com and at least $5 credit
  • OpenAI (GPT-4): API key from platform.openai.com
  • Google (Gemini): Free tier available at ai.google.dev
  • Local (Ollama): Run models locally (requires separate Ollama installation)

Step 6: Verify Installation

Check that the gateway is running:

openclaw gateway status

Expected output:

Gateway Status
──────────────────────────────────
Runtime:  ● running
PID:      12345
Port:     18789 (local)
Uptime:   5 seconds
RPC:      ● healthy

Open the Control UI to test:

openclaw dashboard

Your browser should open to http://127.0.0.1:18789/ where you can chat with OpenClaw.

If the gateway isn't running:

# Start it manually
openclaw gateway --port 18789

Verification

Test with a simple message in the Control UI:

Type in the web interface:

Hello! Can you confirm you're working?

You should see: A response from your configured AI model.

Test the CLI (if you configured Telegram or another channel):

openclaw message send --target YOUR_TELEGRAM_USERNAME --message "Test message"

You should see: The message delivered to your configured channel.

What You Learned

  • Apple Silicon Macs require Node.js 22+ and Xcode Command Line Tools for OpenClaw
  • The sharp module needs explicit architecture flags on some systems
  • PATH configuration is critical for CLI tools installed via npm
  • The --install-daemon flag sets up OpenClaw to run in the background

Limitations:

  • This guide assumes you're using zsh (macOS default). Bash users need to modify ~/.bashrc instead of ~/.zshrc
  • Some AI providers require payment setup even if they have free tiers (e.g., Anthropic requires $5 minimum credit)

Next steps:

Common Errors and Fixes

Error: "sharp: Please add node-gyp to your dependencies"

Cause: npm is trying to build sharp from source instead of using pre-built binaries.

Fix:

npm uninstall -g openclaw
npm cache clean --force
npm install -g openclaw@latest --platform=darwin --arch=arm64

Error: "Node version must be >= 22"

Cause: You have an older Node.js version installed.

Fix:

# Use nvm to install Node.js 22
nvm install 22
nvm use 22
nvm alias default 22

# Verify
node --version  # Should show v22.x.x

# Retry installation
npm install -g openclaw@latest

Error: "openclaw: command not found" after successful install

Cause: npm's global bin directory isn't in your PATH.

Fix:

# Add to PATH
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify
openclaw --version

Alternative: Find where npm installed it:

npm config get prefix
# Should show something like /Users/yourname/.nvm/versions/node/v22.22.0

Then add /bin to that path manually in your shell config.

Error: "EADDRINUSE: port 18789 already in use"

Cause: Another process is using OpenClaw's default port.

Fix:

# Find what's using the port
lsof -i :18789

# Kill the process if it's old OpenClaw
kill -9 <PID>

# Or start OpenClaw on a different port
openclaw gateway --port 8080

Gateway status shows "RPC probe: failed"

Cause: The gateway process is running but not responding correctly.

Fix:

# Run the doctor command to diagnose and fix
openclaw doctor --fix

# Restart the gateway
openclaw gateway restart

Troubleshooting Checklist

Before asking for help, verify:

  • Node.js version is 22 or higher (node --version)
  • Xcode Command Line Tools installed (xcode-select -p)
  • npm global bin is in PATH (which openclaw should show a path)
  • Installation completed without errors
  • Gateway status shows "running" (openclaw gateway status)
  • You have API credits for your chosen provider (Anthropic requires $5 minimum)

Still stuck? Run the diagnostic:

openclaw status --all

This generates a complete report you can share when seeking help on:

Alternative: macOS App Installation (GUI Method)

If you prefer a graphical installer over the CLI:

Download the macOS app:

  • Visit OpenClaw Releases
  • Download the .dmg file (Universal Binary for M1/M2/M3/M4)
  • Drag to Applications folder

On first launch:

  • macOS will show a security warning
  • Go to System Settings → Privacy & Security
  • Click "Open Anyway"

The app provides a menu bar interface with:

  • Quick access to chat
  • Gateway status monitoring
  • Voice wake features
  • One-click channel setup

Note: The CLI installation is more flexible and recommended for developers who want full control.

Advanced: Running OpenClaw in a VM (Maximum Isolation)

For users who want complete sandboxing or need iMessage integration:

Use Lume to create a macOS VM:

# Install Lume
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"

# Create macOS VM with OpenClaw
lume create openclaw --os macos --ipsw latest

# Complete Setup Assistant when VM opens
# Enable Remote Login (SSH) in System Settings

# Run VM headlessly
lume run openclaw --no-display

# SSH into VM
ssh youruser@192.168.64.x

# Inside VM, install OpenClaw
npm install -g openclaw@latest
openclaw onboard --install-daemon

Benefits:

  • Your host Mac stays completely clean
  • Easy to reset by deleting the VM
  • Native iMessage support via BlueBubbles
  • Full macOS environment in isolation

Requirements:

  • Apple Silicon Mac (M1/M2/M3/M4)
  • macOS Sequoia or later on host
  • ~60GB free disk space per VM

Tested on:

  • macOS Sonoma 14.6 and Sequoia 15.2
  • MacBook Air M3, Mac Mini M4
  • Node.js 22.22.0
  • OpenClaw 2026.2.3

Summary

Installing OpenClaw on Apple Silicon is straightforward when you:

  1. Use Node.js 22+ (via nvm)
  2. Install Xcode Command Line Tools
  3. Force the correct architecture for sharp if needed
  4. Configure your PATH properly

The most common failure point is the sharp module trying to build from source. The fix is to clear your npm cache and reinstall with explicit platform flags.

Once installed, OpenClaw provides a powerful local AI assistant that integrates with messaging platforms, supports local models, and runs entirely under your control.