OpenClaw on Mac: Master the Effortless macOS Install Today

Eight minutes. That's the realistic install time for OpenClaw on a Mac with a working Node.js setup. The install itself takes 90 seconds. The rest is verification — and the developers who skip verification are the same ones posting "OpenClaw broke after a macOS update" three weeks later. Here's how to do it right the first time.

Prerequisites for macOS

OpenClaw has three hard requirements on Mac. Each one takes less than 5 minutes to resolve if you don't have it yet.

• macOS 13 Ventura or newer — check via Apple menu → About This Mac. Monterey (12.x) is not supported as of the 1.8 release series.
• Node.js 18.17 or higher — check with node --version. If it's missing or older, download from nodejs.org or install via Homebrew.
• Command Line Tools for Xcode — required for native npm modules. Install with xcode-select --install if you see build errors during npm install.

One thing most guides skip: the default macOS shell is now Zsh, not Bash. Any PATH modifications you make go in ~/.zshrc, not ~/.bash_profile. This matters for the npm global bin path setup.

Installation via npm

This is the recommended path for most developers. Open Terminal and run:

# Install OpenClaw globally
npm install -g openclaw

# Verify the installation
openclaw --version

# Run the health check
openclaw doctor

If openclaw --version succeeds, you're done with installation. The version string tells you the build target — look for darwin-arm64 on Apple Silicon or darwin-x64 on Intel.

Here's where most people stop. Don't. Run openclaw init next.

# Initialize OpenClaw config
openclaw init

# This creates ~/.openclaw/ with:
# - gateway.yaml   (gateway configuration)
# - agents/        (agent definitions directory)
# - .env.example   (environment variable template)

The init step is not optional for actual use — it creates the config directory that every subsequent OpenClaw command depends on. Without it, commands like openclaw gateway start will fail with a "config not found" error.

Fixing the PATH Issue

If openclaw returns "command not found" after a successful npm install, the npm global bin directory is missing from your PATH. Fix it permanently:

# Find the npm global prefix
npm config get prefix
# Example output: /opt/homebrew/  (Apple Silicon Homebrew)
# or: /usr/local/  (Intel Homebrew or system npm)

# Add the bin directory to PATH in ~/.zshrc
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc

# Reload the shell config
source ~/.zshrc

# Verify
openclaw --version

Installation via Homebrew

If Homebrew is your primary package manager, use this path instead. It's cleaner for managing Node.js versions alongside other development tools:

# Update Homebrew formulae
brew update

# Install Node.js (includes npm)
brew install node

# Verify Node.js
node --version   # Should be 18.17+
npm --version    # Should be 9.x+

# Install OpenClaw
npm install -g openclaw

# Verify
openclaw --version
openclaw doctor

Homebrew on Apple Silicon installs to /opt/homebrew. Homebrew on Intel Macs installs to /usr/local. The npm global prefix follows the same distinction. Keep this in mind if you're troubleshooting PATH issues on a machine that had both environments at different points.

Verification and First Run

A proper verification sequence catches issues before they surface in production. Run this after every install:

# Full health check
openclaw doctor

# Expected output includes:
# ✓ Node.js version: 20.x.x (>=18.17.0)
# ✓ Architecture: arm64
# ✓ Config directory: ~/.openclaw/
# ✓ Gateway config: ~/.openclaw/gateway.yaml
# ✓ Network: reachable

# Start the gateway
openclaw gateway start

# Check gateway status in a new terminal tab
openclaw gateway status

The gateway process runs in the foreground by default. For development, that's fine — you can see logs in real time. For persistent use, run it as a background service with openclaw gateway start --daemon.

Comparison: npm vs Homebrew Install Methods

Common Mistakes

• Installing with sudo — sudo npm install -g openclaw installs to the system Node.js path, creates permission issues, and often picks up the wrong Node.js. Never use sudo with npm global installs.
• Skipping openclaw init — the binary installs fine without it, but any gateway command will fail immediately. Always run init before trying to start the gateway.
• Using a Node.js version manager in a new terminal without activating it — nvm and fnm don't automatically activate in every shell type. If node --version is wrong in a new terminal, add the activation line to your shell profile.
• Installing on macOS 12 Monterey — the OpenClaw 1.8+ series requires macOS 13+. Check your macOS version first. If you're on Monterey, install OpenClaw 1.7.x, which is the last version with Monterey support.
• Not running openclaw doctor after macOS updates — major macOS updates can invalidate Command Line Tools. If OpenClaw breaks after an update, run xcode-select --install to reinstall the tools.

Frequently Asked Questions

What is the fastest way to install OpenClaw on Mac?

The fastest path is npm: install Node.js 18.17+ from nodejs.org, then run npm install -g openclaw. Total time under 5 minutes. If you use Homebrew, brew install node && npm install -g openclaw keeps everything in one ecosystem and is equally fast.

Does OpenClaw work on Intel Macs?

Yes. OpenClaw supports Intel Macs running macOS 13 Ventura or newer. Performance is solid for most workloads. The main difference from Apple Silicon is slower local LLM inference without unified memory. For cloud-based LLM providers, the performance gap between Intel and Apple Silicon is negligible.

How do I update OpenClaw on Mac?

Run npm update -g openclaw to update to the latest version. Check your current version first with openclaw --version. After updating, run openclaw doctor to verify the new version initialized correctly and your existing configs remain valid.

Why does "openclaw command not found" appear after npm install?

Your npm global bin directory is missing from PATH. Run npm config get prefix to find the global directory, then add that path's bin folder to PATH in ~/.zshrc. After editing, run source ~/.zshrc to reload without restarting Terminal.

Can I install multiple versions of OpenClaw on Mac?

Yes, using nvm to manage multiple Node.js versions. Install different Node.js versions and use npm to install different OpenClaw versions in each. Switch between them with nvm use [version]. Useful for testing config compatibility before upgrading a production setup.

Does OpenClaw require Xcode or Command Line Tools on Mac?

Command Line Tools for Xcode are required — the full Xcode IDE is not needed. Install them with xcode-select --install. They provide the compiler npm needs for native Node.js modules. Without them, the install fails on native dependencies with a build error.

How do I uninstall OpenClaw on Mac?

Run npm uninstall -g openclaw to remove the binary. Config files in ~/.openclaw/ are not removed automatically — delete that directory manually for a clean slate. If you installed via Homebrew, use brew uninstall openclaw instead.