OpenClaw (formerly Clawdbot, then Moltbot) is an open-source AI assistant that runs on your own machine. It connects to your messaging apps, executes tasks, browses the web, manages files, and integrates with macOS features like Apple Notes, Reminders, Calendar, and iMessage. With 228,000+ stars on GitHub, it's the most popular self-hosted AI assistant available.
This guide walks you through setting up OpenClaw on a Mac from scratch. No prior experience required.
What You'll Set Up
- OpenClaw Gateway running as a background service on your Mac
- Messaging channels like WhatsApp, Telegram, or iMessage connected
- Your choice of LLM (Claude, GPT, or local Ollama)
- macOS companion app with menu bar control and voice support
- Essential skills from ClawHub for productivity
Prerequisites
Before installing OpenClaw, make sure your Mac meets these requirements:
- macOS 14 (Sonoma) or later — required for the companion app
- Node.js 22 or higher — OpenClaw's runtime requirement
- Homebrew — the easiest way to install Node.js and other dependencies
- An LLM API key (optional) — from Anthropic, OpenAI, or run local models free with Ollama
If you don't have Homebrew yet, install it first:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Then install Node.js 22:
brew install node@22
Verify your Node version:
node --version
# Should output v22.x.x or higher
Installation Methods
OpenClaw offers several installation methods. Pick the one that fits your comfort level.
Method 1: One-Line Installer (Recommended)
The fastest way to get started. This downloads the CLI, installs it globally, and launches the onboarding wizard:
curl -fsSL https://openclaw.ai/install.sh | bash
The installer script handles Node.js installation if you don't have it, and immediately starts the onboarding wizard when finished.
Method 2: npm Install
If you already have Node.js 22+ installed:
npm install -g openclaw@latest
openclaw onboard --install-daemon
The --install-daemon flag creates a launchd service so OpenClaw starts automatically and survives reboots.
Method 3: From Source
For developers who want to contribute or customize:
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
pnpm link --global
openclaw onboard --install-daemon
The Onboarding Wizard
After installation, the openclaw onboard wizard walks you through four setup steps:
1Gateway configuration — Sets up the local server that powers your assistant. The default port is 18789.
2Workspace setup — Creates your workspace directory at ~/.openclaw/workspace where OpenClaw stores files, logs, and configuration.
3Channel connections — Optionally connects your messaging platforms (WhatsApp, Telegram, Discord, etc.). You can skip this and add channels later.
4Skills installation — Optionally installs starter skills from ClawHub.
The wizard saves everything to ~/.openclaw/openclaw.json. You can edit this file directly anytime to change settings.
Connecting Messaging Platforms
OpenClaw supports a wide range of messaging channels. Here are the most popular options for Mac users:
| Platform | Library | Setup Difficulty |
|---|---|---|
| Telegram | grammY | Easiest (recommended first) |
| Baileys | Easy (QR code scan) | |
| iMessage | BlueBubbles | Moderate (Mac-only) |
| Discord | discord.js | Easy (bot token) |
| Slack | Bolt | Moderate (OAuth setup) |
| Signal | signal-cli | Moderate |
| Matrix | Matrix SDK | Moderate |
Telegram is the recommended starting point because it has the simplest setup process. Create a bot via @BotFather on Telegram, copy the token, and paste it during onboarding.
For iMessage on Mac, OpenClaw uses BlueBubbles to bridge messages. This is a Mac-exclusive feature — no other platform gets native iMessage integration.
Choosing and Configuring Your LLM
OpenClaw works with any LLM, but the choice matters. Here's how the main options compare for Mac users:
Claude (Recommended)
The official OpenClaw documentation recommends Anthropic Claude — specifically Opus 4.6 for its long-context strength and prompt-injection resistance. To configure:
{
"agent": {
"model": "anthropic/claude-opus-4-6"
}
}
You'll need an Anthropic API key. Costs typically run $0.50 to $2 per 100 tasks depending on complexity.
GPT (OpenAI)
If you prefer OpenAI models:
{
"agent": {
"model": "openai/gpt-4o"
}
}
Ollama (Local, Free)
For fully local operation with no API costs, install Ollama and run a model like Llama 3 or Mistral:
brew install ollama
ollama pull llama3.3
ollama serve
Then configure OpenClaw to use it:
{
"agent": {
"model": "ollama/llama3.3"
}
}
macOS Companion App
OpenClaw includes a native macOS menu bar app that provides quick access to your assistant without opening Terminal.
To install it:
- Download the companion app from openclaw.ai
- Mount the DMG and drag OpenClaw.app to /Applications
- Launch the app and approve the macOS security warning
- Complete the permissions checklist when prompted
The companion app provides:
- Menu bar status — see your gateway status at a glance
- Voice Wake — always-on speech detection (with ElevenLabs)
- Talk Mode — continuous conversation overlay
- Push-to-Talk — hold a key to talk to your assistant
- WebChat — browser-based chat interface
- Canvas — visual tools for screenshots and UI automation
The app manages these macOS permissions via TCC prompts:
- Notifications
- Accessibility
- Screen Recording
- Microphone
- Speech Recognition
- AppleScript/Automation
Running as a Background Service
If you used --install-daemon during onboarding, OpenClaw is already running as a launchd service. It starts automatically on login and restarts if it crashes.
The launchd plist is stored in ~/Library/LaunchAgents/. Useful commands:
# Check status
openclaw status
# Restart the gateway
openclaw gateway restart
# View logs
openclaw gateway logs
# Manual start (if not using daemon)
openclaw gateway --port 18789 --verbose
Verify everything is healthy:
openclaw doctor
The openclaw doctor command checks your configuration, flags security issues with DM policies, and verifies that all services are running. Add --fix to auto-repair common issues:
openclaw doctor --fix
Mac Mini as an Always-On Server
A Mac Mini makes an excellent dedicated OpenClaw server. It draws only 5-15 watts, runs silently, and gives OpenClaw 24/7 availability.
Recommended hardware: Mac Mini M4 with 16-32 GB unified memory. The M4 chip delivers fast single-threaded Node.js performance and enough GPU for local model inference with Ollama. Expect around $1-2/month in electricity costs.
To configure a Mac Mini as an always-on server, prevent sleep and enable auto-restart after power failure:
# Prevent sleep entirely
sudo pmset -a sleep 0 displaysleep 0 disksleep 0
# Auto-restart after power failure
sudo pmset -a autorestart 1
You can also set these in System Settings > Energy:
- Enable "Prevent automatic sleeping when the display is off"
- Enable "Wake for network access"
- Enable "Start up automatically after a power failure"
With the launchd daemon installed, OpenClaw starts automatically after every reboot. Connect to your Mac Mini remotely via SSH or the OpenClaw companion app's remote mode (which works over SSH or Tailscale).
Essential First Skills to Install
ClawHub is the public skill registry for OpenClaw. Skills extend what your assistant can do. Install them with:
openclaw skills install <skill-name>
openclaw skills enable <skill-name>
Recommended starter skills for Mac users:
- Skill Vetter — security scanner (install this first)
- Summarize — condense long articles, emails, or documents
- Humanizer — rewrite AI-generated text to sound natural
- Session Logs — searchable history of past conversations
- Google Calendar Sync or CalDAV Connect (for Apple Calendar) — calendar management
- Gmail Assistant or Generic IMAP — email integration
Troubleshooting Common Issues
sharp/libvips Build Error
If npm fails with a sharp or libvips compilation error:
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
This is common when Homebrew's libvips conflicts with the version sharp expects. The environment variable forces prebuilt binaries.
Node Version Too Old
OpenClaw requires Node.js 22+. Check your version:
node --version
If it's below 22, update via Homebrew:
brew install node@22
# Add to your PATH if needed:
export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
openclaw Command Not Found
If your terminal can't find the openclaw command after installation, add npm's global bin directory to your PATH:
export PATH="$(npm prefix -g)/bin:$PATH"
Add that line to your ~/.zshrc to make it permanent.
Gateway Won't Start
Run the doctor command to diagnose:
openclaw doctor --fix
Common causes include port 18789 already in use, missing configuration files, or permission issues with the launchd plist.
macOS Companion App Can't Connect
Make sure your Gateway is running (openclaw status). The companion app in Local mode expects the Gateway on localhost. If you're using Remote mode, verify your SSH or Tailscale connection.
Frequently Asked Questions
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest. This forces prebuilt binaries instead of compiling against your system's libvips, which is the most common cause of this error on macOS with Homebrew.
Dictate to Your Mac, Hands-Free
Use EmberType alongside OpenClaw to dictate commands, messages, and notes — 100% offline.
Download EmberType FreemacOS 14+ required. Apple Silicon only. $39 after 7-day trial.