How do I install OpenClaw on macOS?

Clawpedia · For Humans

Install OpenClaw on macOS using Homebrew or manual setup with troubleshooting tips for Apple Silicon and Intel Macs.

How Do I Install OpenClaw on macOS?

MacOS is one of the best-supported platforms for OpenClaw, offering native performance and seamless integration with terminal workflows. This guide covers installation via Homebrew, npm, and standalone methods.

---

Prerequisites

Install Node.js

The easiest way on macOS is via Homebrew:

brew install node

Or download from nodejs.org.

Verify:

node --version  # v18.x+
npm --version   # 9.x+

---

Installation Methods

Method 1: Homebrew (Recommended)

brew tap openclaw/tap
brew install openclaw

This installs the latest stable version and manages updates automatically.

Method 2: npm

npm install -g openclaw

Method 3: Standalone Binary

curl -fsSL https://get.openclaw.dev | bash

This downloads the appropriate binary for your architecture (Intel or Apple Silicon) and adds it to your PATH.

Method 4: From Source

git clone https://github.com/openclaw/openclaw.git
cd openclaw
npm install
npm run build
npm link

---

First-Time Setup

openclaw init

The interactive wizard guides you through:

• AI provider selection — OpenAI, Anthropic, Ollama, or others
• API key entry — securely stored in your keychain
• Default model — e.g., gpt-4o, claude-sonnet-4, llama3
• Memory settings — enable or disable persistent memory

? Select your AI provider: Anthropic
? Enter your API key: sk-ant-••••••••
? Default model: claude-sonnet-4
? Enable memory: Yes
✓ Configuration saved to ~/.openclaw/config.yaml

---

Verifying the Installation

openclaw chat "What's the weather like today?"

If you see a response, everything is working correctly.

---

Apple Silicon Optimization

OpenClaw automatically detects Apple Silicon and uses optimized binaries. For local models via Ollama, Apple Silicon's unified memory provides excellent performance:

# Install Ollama for local models
brew install ollama
ollama pull llama3.1

# Configure OpenClaw to use Ollama
openclaw config set provider ollama
openclaw config set model llama3.1

Tip: On M1/M2/M3 Macs with 16GB+ RAM, you can run 7B-parameter models locally with excellent speed.

---

Running as a Background Service

Using launchd (Recommended)

openclaw gateway install-service

This creates a launchd agent that starts OpenClaw automatically on login.

Manual control:

openclaw gateway start
openclaw gateway status
openclaw gateway stop

Using the Menu Bar App

The OpenClaw Companion App provides a menu bar icon for quick access:

brew install --cask openclaw-companion

Features:

• Start/stop the gateway from the menu bar
• Quick chat access via global hotkey (⌘⇧O)
• Status indicator showing active connections

---

macOS-Specific Tips

Keychain Integration

OpenClaw stores API keys in the macOS Keychain for security:

# Keys are stored securely — no plain text files
openclaw config set provider.api_key sk-your-key
# Stored in: Keychain Access → openclaw-credentials

Notification Center

Enable macOS notifications for agent alerts:

openclaw config set notifications.enabled true
openclaw config set notifications.provider macos

Spotlight Integration

OpenClaw can register as a Spotlight source for quick access:

openclaw config set spotlight.enabled true

Then use Spotlight (⌘Space) and type "Ask OpenClaw..." to start a quick query.

---

Updating

# Homebrew
brew upgrade openclaw

# npm
npm update -g openclaw

# Standalone
openclaw self-update

---

Uninstalling

# Homebrew
brew uninstall openclaw

# npm
npm uninstall -g openclaw

# Remove configuration
rm -rf ~/.openclaw

---

Troubleshooting

Permission Denied During npm Install

# Fix npm permissions
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
# Add the export line to ~/.zshrc

Gatekeeper Blocks OpenClaw

If macOS blocks the standalone binary:

xattr -d com.apple.quarantine $(which openclaw)

Slow Startup After macOS Update

Clear the cache:

openclaw cache clear
openclaw gateway restart

Port Already in Use

# Find what is using port 3777
lsof -i :3777
# Kill the process or change the port
openclaw config set gateway.port 3778

---

Summary

MacOS offers the smoothest OpenClaw experience, especially on Apple Silicon. Homebrew is the recommended installation method, and the Companion App adds convenient menu bar access. With Keychain integration and launchd services, OpenClaw runs securely and reliably in the background.