Complete Guide to Installing OpenClaw on macOS

Introduction

macOS is one of the ideal platforms for running OpenClaw, offering a stable Unix environment and an excellent terminal experience. This article covers two installation methods — Homebrew and npm — and explains in detail how to use macOS's launchd to enable automatic startup at login.

System Requirements

Step 1: Install Prerequisites

Install Xcode Command Line Tools

Some OpenClaw dependencies require compiling native modules during installation, so the Xcode Command Line Tools are needed:

xcode-select --install

Click "Install" in the dialog that appears and wait for the download and installation to complete.

Verify the installation:

xcode-select -p
# Output: /Library/Developer/CommandLineTools

Install Homebrew

If you haven't installed Homebrew yet, run:

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

Apple Silicon users need to add Homebrew to their PATH after installation:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Step 2: Install Node.js

Option A: Via Homebrew (Recommended)

brew install node@22

# Link node@22 to PATH
brew link --overwrite node@22

# Verify versions
node --version
npm --version

Option B: Via nvm

# Install nvm
brew install nvm

# Configure nvm environment
mkdir -p ~/.nvm
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && . "/opt/homebrew/opt/nvm/nvm.sh"' >> ~/.zshrc
source ~/.zshrc

# Install Node.js 22
nvm install 22
nvm use 22
nvm alias default 22

Step 3: Install OpenClaw

You can choose between Homebrew or npm for installation.

Option A: Homebrew Installation (Recommended)

brew install openclaw

The Homebrew approach automatically handles dependencies and makes updates easier.

Option B: npm Global Installation

npm install -g openclaw@latest

Verify the Installation

openclaw --version

Step 4: Initial Configuration

Run the setup wizard:

openclaw onboard

Follow the prompts to complete these settings:

1. Select an AI model provider (Claude / OpenAI / Ollama / Gemini / OpenRouter)
2. Enter the corresponding API key
3. Select messaging channels to connect
4. Confirm the gateway port (default: 18789)

The configuration file is saved at:

~/.config/openclaw/openclaw.json5

You can open it with VS Code or any other editor for manual adjustments:

code ~/.config/openclaw/openclaw.json5

Step 5: Start OpenClaw

openclaw up

On successful startup, you'll see:

[OpenClaw] Gateway started on port 18789
[OpenClaw] Model provider: Claude (claude-sonnet-4-20250514)
[OpenClaw] Channels: ready
[OpenClaw] Dashboard: http://localhost:18789/dashboard

Common Management Commands

# Check status and run diagnostics
openclaw doctor

# Open the admin panel
openclaw dashboard

# View real-time logs
openclaw logs

# Restart the service
openclaw restart

# List installed skills
openclaw skill list

Step 6: Configure launchd for Auto-Start

macOS uses launchd to manage background services, similar to systemd on Linux. The following steps register OpenClaw as a user-level launchd service.

Create the plist File

mkdir -p ~/Library/LaunchAgents

Create the file ~/Library/LaunchAgents/com.openclaw.agent.plist with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.openclaw.agent</string>

    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/openclaw</string>
        <string>up</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>WorkingDirectory</key>
    <string>/Users/YOUR_USERNAME</string>

    <key>StandardOutPath</key>
    <string>/Users/YOUR_USERNAME/.openclaw/logs/stdout.log</string>

    <key>StandardErrorPath</key>
    <string>/Users/YOUR_USERNAME/.openclaw/logs/stderr.log</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
    </dict>
</dict>
</plist>

Replace YOUR_USERNAME with your actual username. If you installed via npm, replace /opt/homebrew/bin/openclaw with the output of which openclaw.

Create the Log Directory and Load the Service

# Create the log directory
mkdir -p ~/.openclaw/logs

# Load the service
launchctl load ~/Library/LaunchAgents/com.openclaw.agent.plist

# Confirm the service is running
launchctl list | grep openclaw

Manage the launchd Service

# Stop the service
launchctl unload ~/Library/LaunchAgents/com.openclaw.agent.plist

# Start the service
launchctl load ~/Library/LaunchAgents/com.openclaw.agent.plist

# Check service status (macOS 13+)
launchctl print gui/$(id -u)/com.openclaw.agent

macOS-Specific Optimization Tips

Allow Background Network Connections

When OpenClaw starts for the first time, macOS may show a firewall prompt. Click "Allow" to proceed.

If you missed the prompt, you can add it manually:

1. Open "System Settings" > "Network" > "Firewall"
2. Click "Options"
3. Find Node.js or OpenClaw and set it to "Allow incoming connections"

Prevent macOS Sleep from Interrupting the Service

If your Mac runs OpenClaw for extended periods, consider preventing system sleep:

# Prevent system sleep (run in terminal)
caffeinate -s &

# Or adjust via System Settings
# System Settings > Lock Screen > Turn display off after never

Apple Silicon Performance Optimization

If you're running local models (such as Ollama) on an Apple Silicon Mac, you can take advantage of Metal acceleration:

# Install Ollama
brew install ollama

# Start Ollama (automatically uses Metal GPU acceleration)
ollama serve

# Configure Ollama as a model provider in openclaw.json5

Monitoring with iTerm2

We recommend using iTerm2's split-pane feature to simultaneously monitor OpenClaw logs and system resources:

# Left pane: View OpenClaw logs
openclaw logs

# Right pane: Monitor system resources
top -pid $(pgrep -f openclaw)

Homebrew Updates

For users who installed via Homebrew, updating is straightforward:

# Update Homebrew index
brew update

# Upgrade OpenClaw
brew upgrade openclaw

# Restart the service
openclaw restart

Uninstallation

If you need to uninstall OpenClaw:

# If installed via Homebrew
brew uninstall openclaw

# If installed via npm
npm uninstall -g openclaw

# Clean up configuration files (optional)
rm -rf ~/.config/openclaw
rm -rf ~/.openclaw

# Remove the launchd service
launchctl unload ~/Library/LaunchAgents/com.openclaw.agent.plist
rm ~/Library/LaunchAgents/com.openclaw.agent.plist

Summary

With its stable Unix foundation and excellent hardware performance, macOS is an outstanding choice for running OpenClaw. Installing via Homebrew provides the smoothest experience, and combined with launchd auto-start, your AI assistant will always be online. Continue reading the channel integration and skill plugin tutorials to further unlock OpenClaw's potential.