Installing OpenClaw on macOS

Prerequisites

macOS 12 Monterey or newer is recommended. Python 3.10+ is required.

python3 --version
# Python 3.10+ required

ℹ️

macOS System Python

macOS ships with Python 3 in recent versions, but we recommend installing a fresh Python via Homebrew or pyenv for better control over versions.

Method 1: Homebrew (Recommended)

Homebrew is the easiest way to manage Python and OpenClaw on macOS:

# Install Homebrew if you haven't already
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python@3.11

# Install OpenClaw
pip3 install openclaw

# Verify
openclaw --version

Apple Silicon (M1/M2/M3) Notes

Homebrew on Apple Silicon installs to /opt/homebrew. Make sure the binary path is correct:

# Add Homebrew to PATH in ~/.zshrc
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

# Verify pip3 location
which pip3
# /opt/homebrew/bin/pip3

Method 2: pip3 + Virtual Environment

# Create venv
python3 -m venv ~/venvs/openclaw

# Activate
source ~/venvs/openclaw/bin/activate

# Install
pip install openclaw

# Verify
openclaw --version

Auto-activate in your shell profile:

echo 'source ~/venvs/openclaw/bin/activate' >> ~/.zshrc
source ~/.zshrc

Method 3: Conda

If you use Anaconda or Miniconda:

# Create a dedicated conda env
conda create -n openclaw python=3.11 -y
conda activate openclaw
pip install openclaw
openclaw --version

Post-Install Verification

openclaw --version
openclaw config set openai.api_key "sk-proj-..."
openclaw run "What is your status?"

Zsh Completion

macOS uses Zsh as the default shell since Catalina:

openclaw completion zsh >> ~/.zshrc
source ~/.zshrc

Autostart with LaunchAgent

To run OpenClaw automatically at login, create a LaunchAgent plist:

<?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>top.openclaw-wiki.agent</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/YOUR_USER/venvs/openclaw/bin/openclaw</string>
    <string>start</string>
    <string>--daemon</string>
    <string>--port</string>
    <string>8080</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/openclaw.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/openclaw.err</string>
</dict>
</plist>

cp openclaw.plist ~/Library/LaunchAgents/top.openclaw-wiki.agent.plist
launchctl load ~/Library/LaunchAgents/top.openclaw-wiki.agent.plist
launchctl list | grep openclaw

💡

See Also

Verify Your Installation

After installation, confirm OpenClaw is working correctly:

# Check version
openclaw --version
# OpenClaw v1.x.x

# Check config
openclaw config show

# Quick test
openclaw run "Say 'macOS installation successful' in one sentence"

First Real Task on macOS

# Configure your API key
openclaw config set openai.api_key "sk-proj-..."
openclaw config set provider openai
openclaw config set openai.model gpt-4o-mini

# Test with a practical command
openclaw run "List the top 3 macOS keyboard shortcuts every developer should know"

# Use Apple Silicon with Ollama for private local AI (zero API cost):
# brew install ollama
# ollama pull llama3.2
# openclaw config set provider ollama && openclaw config set model llama3.2

Update & Uninstall

Upgrade via pip

pip install --upgrade openclaw
# or: pip3 install --upgrade openclaw

Upgrade via Homebrew (if installed via brew)

brew upgrade openclaw

Uninstall

pip uninstall openclaw -y

# Remove config files (optional)
rm -rf ~/.openclaw/

macOS-Specific Troubleshooting

Error	Cause	Fix
`externally-managed-environment`	macOS Homebrew Python is protected	Always use a venv: `python3 -m venv ~/.venv/openclaw && source ~/.venv/openclaw/bin/activate`
`xcrun: error: invalid active developer path`	Xcode Command Line Tools not installed	Run: `xcode-select --install`
`SSL: CERTIFICATE_VERIFY_FAILED`	macOS Python doesn't use system certs by default	Run: `/Applications/Python\ 3.12/Install\ Certificates.command`
`zsh: command not found: openclaw`	venv not activated or PATH not set	Add to `~/.zshrc`: `export PATH="$HOME/.venv/openclaw/bin:$PATH"`
Slow on Apple Silicon with Ollama	Model using CPU fallback	Ensure Ollama version supports Metal: `ollama list` should show GPU layers

Running OpenClaw Tasks as a launchd Agent

For automated schedules on macOS, use launchd instead of cron (it handles sleep/wake correctly):

<!-- ~/Library/LaunchAgents/com.openclaw.daily.plist -->
<?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.daily</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/yourname/.venv/openclaw/bin/openclaw</string>
    <string>run</string>
    <string>Daily summary task</string>
  </array>
  <key>StartCalendarInterval</key>
  <dict>
    <key>Hour</key><integer>8</integer>
    <key>Minute</key><integer>0</integer>
  </dict>
  <key>StandardOutPath</key>
  <string>/tmp/openclaw-daily.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/openclaw-daily-err.log</string>
</dict>
</plist>

# Load and start the agent
launchctl load ~/Library/LaunchAgents/com.openclaw.daily.plist
# Unload to stop:
launchctl unload ~/Library/LaunchAgents/com.openclaw.daily.plist

← Linux Installation Windows Installation →