🍎 Install OpenClaw on Mac

1 Prerequisites

Before you start, make sure you have:

• macOS 13 (Ventura) or later — older versions may work but aren't officially supported
• Terminal access — found in Applications → Utilities → Terminal (or use iTerm2)
• An AI API key — Anthropic (Claude) is recommended; OpenAI and Google also work
• ~20 minutes of uninterrupted time

Apple Silicon vs Intel

OpenClaw works on both. To check which chip you have:

uname -m

• arm64 = Apple Silicon (M1/M2/M3/M4) — you're on the latest architecture
• x86_64 = Intel — everything works, just slightly different Homebrew paths

2 Install Homebrew

Homebrew is the standard package manager for macOS. If you already have it, skip to Step 3.

Check if Homebrew is installed:

brew --version

If you see a version number, skip ahead. If not, install it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The script will ask for your macOS password — this is normal. It needs admin access to install to the system directories.

Verify:

brew --version
# Should output: Homebrew 4.x.x

3 Install Node.js 22+

OpenClaw requires Node.js 22.12.0 or higher. Check your current version:

node --version

If you see v22.x.x or higher, skip to Step 4.

Option A: Install via Homebrew (recommended)

brew install node@22

Option B: Install via nvm (if you manage multiple Node versions)

# Install nvm if you don't have it
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# Close and reopen Terminal, then:
nvm install 22
nvm use 22
nvm alias default 22

Option C: Download from nodejs.org

Visit nodejs.org and download the macOS installer. It auto-detects your chip architecture.

Verify Node and npm:

node --version   # Should be v22.x.x or higher
npm --version    # Should be 10.x.x or higher

4 Install OpenClaw

You have two options. Pick one.

Option A: One-liner (fastest)

This script detects your OS, checks Node, installs the CLI, and launches the onboarding wizard automatically:

curl -fsSL https://openclaw.ai/install.sh | bash

Option B: Manual via npm (more control)

npm install -g openclaw@latest

Then launch the onboarding wizard manually:

openclaw onboard --install-daemon

Verify the installation:

which openclaw    # Should show a path
openclaw --version # Should show v2026.x.x

5 Run the onboarding wizard

If you used the one-liner, the wizard started automatically. If you used npm, run:

openclaw onboard --install-daemon

The wizard walks you through:

1. Authentication — sets up a pairing code for secure DM access
2. Gateway settings — configures the local server (default port: 18789)
3. AI model — enter your API key (Anthropic recommended)
4. Channel connection — optionally connect Telegram, WhatsApp, Discord, etc.
5. Daemon installation — installs a macOS LaunchAgent so OpenClaw runs in the background

When the wizard finishes, you'll see:

🔧 Loading configuration from ~/.openclaw/openclaw.json
🧠 Gateway starting on ws://127.0.0.1:18789
📡 WebChat available at http://localhost:18789
✅ OpenClaw is running

6 Set up your AI model

If you didn't configure this during the wizard, add your API key now. Open the config:

nano ~/.openclaw/openclaw.json

Find the model section and add your key:

{
  "model": {
    "provider": "anthropic",
    "name": "claude-sonnet-4-5-20250929",
    "apiKey": "sk-ant-your-key-here"
  }
}

Save with Ctrl+O, exit with Ctrl+X, then restart:

openclaw gateway restart

Which model should you pick?

Use our Cost Calculator to estimate your monthly bill before committing.

7 Start the daemon (always-on)

The daemon keeps OpenClaw running in the background — even after you close Terminal or restart your Mac.

If the wizard installed it, it's already running. Check:

openclaw daemon status

If it's not running, start it:

openclaw daemon start

Other daemon commands:

openclaw daemon stop      # Stop the background service
openclaw daemon restart   # Restart after config changes
openclaw daemon status    # Check if it's running
openclaw logs --follow    # Watch live logs

What the daemon does

It installs a macOS LaunchAgent at ~/Library/LaunchAgents/com.openclaw.gateway.plist. This means:

• OpenClaw starts automatically when you log in
• It restarts if it crashes
• It survives Terminal being closed
• It runs on login, not on boot (it's a user service, not a system service)

8 Verify it works

Open your browser and go to:

http://localhost:18789

You should see the WebChat interface. Type something like:

Hello! What can you do?

If you get a response from your AI model — congratulations, OpenClaw is running.

You can also test from the Terminal:

# Quick health check
openclaw doctor

# Send a test message
openclaw agent --message "Hello, what's the time?"

# Check gateway status
openclaw gateway status

9 Key files & paths

Know where everything lives:

10 Troubleshooting

"command not found: openclaw"

Your PATH is missing the npm global bin. Fix:

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Port 18789 already in use

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

# Kill it
kill -9 <PID>

# Or change the port in config
openclaw config set port 18790

Node version too old

node --version  # Need 22.12.0+

# Upgrade via Homebrew
brew upgrade node@22

# Or via nvm
nvm install 22 && nvm use 22

Gateway won't start / crashes immediately

# Check the logs
openclaw logs --follow

# Run diagnostics
openclaw doctor --fix

# Reset gateway state (keeps config)
openclaw gateway restart --verbose

Slow on Apple Silicon (running under Rosetta)

# Check architecture
node -e "console.log(process.arch)"
# If it says "x64" — you're under Rosetta

# Reinstall Node natively
brew uninstall node
brew install node@22
# Verify: should say "arm64" now

Sharp / native module build errors

# Force prebuilt binaries
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

# Or install build tools
xcode-select --install
npm install -g node-gyp

macOS security prompts (Gatekeeper)

If macOS blocks OpenClaw from running: go to System Settings → Privacy & Security and click "Allow Anyway" for the blocked item. This is normal for CLI tools installed outside the App Store.

11 What's next

OpenClaw is installed and running. Here's what to do in the next 24 hours:

1. Write your SOUL.md — define your agent's personality, tone, and boundaries. This is the single most important config step. → First 24 Hours Guide
2. Connect a real channel — iMessage (if on macOS) or Telegram are the best first channels
3. Set up security — configure DM policies, enable pairing mode, lock down permissions
4. Enable heartbeat — so your agent checks in proactively and stays aware
5. Explore skills — browse 40+ bundled skills → Skill Explorer

Use the Cheatsheet as your quick reference for commands and config options.