Install OpenClaw on macOS

Run the self-hosted AI agent on your Mac-Intel or Apple Silicon (M1/M2/M3). This guide covers the one-line installer, optional Homebrew and manual setup, and running OpenClaw in the background on macOS 12+ (Monterey and later).

📘 Quick path: For the fastest setup (~5 min), use the Quick Start Guide. This page is the full macOS-specific reference.

1. Overview

OpenClaw runs natively on macOS and is popular with developers and power users on Mac Mini, MacBook, and Mac Studio. This guide covers:

  • System requirements (macOS 12+, Apple Silicon and Intel)
  • One-line installer (recommended) and manual installation
  • Installing Node.js 22+ via Homebrew or nodejs.org
  • Running OpenClaw in the background (Terminal or launchd)
  • Common issues and troubleshooting
  • Security and next steps

2. Prerequisites

  • macOS: macOS 12 (Monterey) or later. Supports both Apple Silicon (M1/M2/M3) and Intel Macs.
  • Node.js 22+ - Required. The one-line installer can install it for you, or install via nodejs.org or Homebrew (see below).
  • Terminal: Use Terminal.app or iTerm. Basic command-line familiarity helps.
  • LLM API key: At least one provider: Anthropic Claude, OpenAI, DeepSeek, or Ollama (local).
  • Optional: A messaging app account (e.g. Telegram, Discord, WhatsApp) for your first channel.

3. Quick Install (One-Line Installer)

Open Terminal and run:

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

The script will:

  • Detect macOS (Intel or Apple Silicon)
  • Install Node.js 22+ if needed (e.g. via Homebrew or nvm)
  • Download and install OpenClaw
  • Create ~/.openclaw and launch the onboarding wizard

After it finishes, run openclaw setup if the wizard did not start. See the Quick Start Guide for full onboarding (model provider, API key, first channel).

4. Manual Installation (Optional)

If you prefer not to use the install script, install Node.js 22+ first.

Option A: Install Node.js via Homebrew

If you use Homebrew:

brew install node@22
# Add to PATH (Apple Silicon: /opt/homebrew; Intel: /usr/local)
echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

On Intel Macs, the path is often /usr/local/opt/node@22/bin. Check with brew --prefix node@22.

Option B: Install Node.js from nodejs.org

Download the macOS installer (Apple Silicon or Intel) from nodejs.org (LTS 22.x or Current). Then in Terminal:

node -v   # should show v22.x.x
npm -v

Install OpenClaw

Clone and build, or use npm if the package is published:

# Clone and install (use official repo)
git clone https://github.com/openclaw/openclaw.git
cd openclaw
npm install
npm run setup

Or global install: npm install -g openclaw then openclaw setup. Ensure openclaw is on your PATH. If you get “openclaw command not found”, see Troubleshooting.

5. macOS-Specific Notes

Apple Silicon (M1/M2/M3)

OpenClaw and Node.js run natively on ARM. No Rosetta required. The one-line installer and Homebrew use native ARM builds. If you use nvm, choose the arm64 Node build.

Homebrew Path (PATH)

Homebrew on Apple Silicon installs to /opt/homebrew; on Intel, /usr/local. If openclaw or node is not found after install, add the correct bin directory to PATH in ~/.zshrc (or ~/.bash_profile) and open a new terminal.

Gatekeeper

If macOS blocks the OpenClaw binary (“cannot be opened because the developer cannot be verified”), go to System Settings → Privacy & Security and click Allow Anyway for the binary, or run: xattr -cr ~/.openclaw only if you trust the source.

6. Run in the Background (Optional)

For development, running openclaw start or leaving the gateway running in a Terminal window is enough. To run OpenClaw in the background and optionally start on login:

  • CLI: If your OpenClaw version supports it: openclaw service install (may install a LaunchAgent on macOS). Check openclaw service --help.
  • LaunchAgent: Create ~/Library/LaunchAgents/com.openclaw.gateway.plist with the correct ProgramArguments (path to openclaw and start), RunAtLoad, and KeepAlive. Use launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist to start. For details, see the official docs or our Official Documentation.

On a Mac used as a server (e.g. Mac Mini), bind the gateway to 127.0.0.1 and use SSH or a VPN for remote access. See Security Best Practices and Network Isolation.

7. Verify Installation

After installation and onboarding:

openclaw status
openclaw doctor

openclaw doctor checks configuration, gateway, and common issues. Send a test message from your connected channel (e.g. Telegram) to confirm the agent responds. For more diagnostics, see the Troubleshooting Guide.

8. Common Issues

Issue Solution
openclaw command not found The installer or npm may have placed the binary in a directory not on your PATH (e.g. ~/.local/bin, /opt/homebrew/bin). Add it to PATH in ~/.zshrc and run source ~/.zshrc, or use the full path. See Installation Errors.
Node.js version too old OpenClaw requires Node.js 22+. Run node -v. Install Node 22+ via nodejs.org, Homebrew (brew install node@22), or nvm, then re-run the installer.
Gateway won't start Check that port 1618 is free. Ensure the gateway binds to 127.0.0.1 on shared Macs. Run openclaw doctor and see Gateway Issues.
Permission denied / EACCES Fix ownership of ~/.openclaw; your user must be able to read and write it. Avoid running the CLI with sudo for normal use.
macOS blocks the binary (Gatekeeper) In System Settings → Privacy & Security, allow the app. Or remove quarantine: xattr -cr ~/.openclaw (only if you trust the installation source).

For more fixes, see the full Troubleshooting Guide.

9. Best Practices

  • Security: Follow our Security Best Practices. On a Mac exposed to the network, bind the gateway to localhost and use network isolation or a VPN.
  • Updates: Keep OpenClaw and Node.js updated. After upgrading, restart the gateway.
  • Logs: Monitor logs for errors: openclaw logs.
  • Backups: Back up ~/.openclaw (config and credentials). Keep API keys out of version control.
  • Post-install: Run through the Security Checklist after setup.

10. Next Steps

Related Resources