OpenClaw Quick Installation Guide (Mac)

One-Click Installation Script

For the fastest installation, create an installation script:

#!/bin/bash

echo "🚀 Starting OpenClaw installation..."

# 1. Install Homebrew (if not installed)
if ! command -v brew &> /dev/null; then
    echo "📦 Installing Homebrew..."
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
fi

# 2. Install Node.js
echo "📦 Installing Node.js..."
brew install node

# 3. Install Python 3.10
echo "📦 Installing Python 3.10..."
brew install [email protected]

# 4. Install OpenClaw
echo "📦 Installing OpenClaw CLI..."
npm install -g @openclaw/cli

# 5. Initialize Configuration
echo "⚙️  Initializing OpenClaw..."
openclaw init --quick

echo "✅ Installation complete!"
echo "📋 Next steps:"
echo "   openclaw gateway start  # Start the service"
echo "   openclaw web            # Open the Web interface"

Save as install-openclaw.sh, then run:

chmod +x install-openclaw.sh
./install-openclaw.sh

Which path should you take: Quick Install vs Full Install?

If your goal is to get OpenClaw running first, this quick-install path is the right starting point:

Best for: first-time setup, validating the local environment, getting Gateway / Web UI running quickly
Advantage: lower setup friction, faster feedback
Tradeoff: you are not solving every long-term config question on day one

If you already know you will run OpenClaw more seriously, connect multiple providers, or maintain it long-term, the fuller installation path is better:

Best for: production-minded setups, more complex model/provider layouts, fewer later rewrites
Advantage: cleaner long-term baseline
Tradeoff: more upfront reading and configuration

A practical approach is: use this guide to get to a minimum viable install, then continue into the fuller setup and troubleshooting docs.

FAQ: The 4 most common macOS install blockers

1) Which Node version should I use?

The safest answer is not “the newest one.” It is:

prefer a currently common / verified LTS-style Node version for OpenClaw
if you are on a very new Node release and see dependency, plugin, or asset-loading problems, treat Node as the first suspect

Useful checks:

node -v
which node

If you use multiple version managers (nvm, fnm, asdf, etc.), make sure your current shell is actually using the version you think it is.

2) What changes between Apple Silicon and Intel Macs?

In practice, the biggest difference is often not OpenClaw itself, but your package-manager paths:

Apple Silicon Homebrew commonly lives under /opt/homebrew
Intel Homebrew commonly lives under /usr/local

So if something looks installed but is not actually usable, check:

which brew
brew --prefix
which node
which python3

A surprising number of “install failed” reports are really PATH is pointing at the wrong toolchain.

3) What if the Web UI loads badly or plugins look broken?

Check in this order before doing anything drastic:

Check service status:

openclaw gateway status

Check logs:

openclaw logs

Confirm your Node / pnpm / build environment is the one you expect
If this is a source install or frontend assets look broken, rebuild dependencies/assets
Restart the Gateway last

The key is to distinguish between:

service not running
assets not built correctly
wrong runtime path/environment

4) Why does a Homebrew path mismatch break so much?

Typical symptoms:

brew install succeeds, but the command still is not found
openclaw, node, and python3 resolve to different prefixes
the machine has both /usr/local and /opt/homebrew, but your shell is still prioritizing the older one

Quick checks:

echo $PATH
which brew
which node
which openclaw

If the paths are inconsistent, clean that up before you keep installing more things.

Minimal Configuration Example

Create a minimal configuration file ~/.openclaw/openclaw-minimal.json:

{
  "models": {
    "providers": {
      "openai": {
        "baseUrl": "https://api.deepseek.com/v1",
        "apiKey": "YOUR_DEEPSEEK_API_KEY",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "DeepSeek Chat"
          }
        ]
      }
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local"
  }
}

Then start using this configuration:

openclaw --config ~/.openclaw/openclaw-minimal.json gateway start

If Mac installation finished but OpenClaw still does not work, where should you go next?

A quick-install guide should not trap readers at the install step. If OpenClaw is installed but your real problem starts immediately after that, jump to the narrower page that matches the failure mode:

Installation appears complete, but agents, models, or tools still fail in inconsistent ways: go to the OpenClaw troubleshooting guide to separate install success from runtime, gateway, provider, or outbound API failures.
You want to confirm whether the install is actually usable before adding channels, skills, or automation: go to the installation success checklist and verify CLI, Gateway, Web UI, and provider response in order.
You migrated from Moltbot or still suspect old commands, paths, image tags, or remotes are mixed into the machine: go to the 1-minute migration guide before you keep reinstalling.

That routing layer matters because many high-intent readers are not searching for installation steps alone. They are trying to decide whether the install actually worked, or whether the machine already moved into a troubleshooting state.

If you already used this Mac install guide once, what should you check before repeating the install?

Before reinstalling, add one more judgment first:

The CLI exists, but real runs fail later: that is usually no longer an installation problem, so start from the troubleshooting guide.
The service starts, but you are not sure the environment is fully usable: run the narrower validation flow in the installation success checklist.
The machine may still be carrying Moltbot-era residue: verify old naming, paths, and remotes with the migration guide.

The faster this page can hand readers into the correct next page, the less likely they are to bounce after a nominally successful install.

First-run validation: prove the Mac install is really usable

After the script finishes, do not treat installation as complete until one real end-to-end path works. A better first-run sequence is:

Run openclaw --version and confirm the command resolves from the package manager you intended to use.
Start or check the gateway with openclaw gateway status before opening more tooling.
Open the Web UI only after the gateway reports healthy, so browser errors do not hide a service startup problem.
Run one small model or agent action before adding plugins, channels, or automation.
Save the exact Node version, install method, and first successful command in your setup notes.

This gives Mac users a clear pass/fail checkpoint. If the CLI exists but the gateway cannot start, stay in install troubleshooting. If the gateway is healthy but real tasks fail, move to runtime troubleshooting instead of reinstalling the same packages.

If this guide is your first OpenClaw page from the homepage

GA4 now shows the homepage, the 2026.3.13 release note, and this Mac install guide in the same low-volume discovery path. Treat this page as the install checkpoint inside that path, not as the final destination.

New visitor from the homepage: finish the Mac install, then use the installation success checklist before adding automations.
Reader comparing the current release: read the 2026.3.13 release note after the install works, so release features do not hide setup failures.
Reader already seeing command delays: skip reinstall loops and use the CLI performance regression triage.

This keeps the Mac guide focused on installation while giving search and homepage visitors a next click that matches their real intent.

Common Commands Cheat Sheet

Service Management

# Start service
openclaw gateway start

# Stop service
openclaw gateway stop

# Restart service
openclaw gateway restart

# Check status
openclaw gateway status

Configuration Management

# View configuration
openclaw configure --show

# Set API Key
openclaw configure --set models.providers.openai.apiKey=YOUR_KEY

# Reset configuration
openclaw reset --config

Diagnostics

# Health check
openclaw doctor

# View logs
openclaw logs

# View version
openclaw --version

First task smoke test after Mac installation

After the CLI starts, run one tiny task before you call the Mac install finished. The task should prove four things: OpenClaw can read its config, the selected model provider returns a real assistant message, at least one safe local tool can run, and the session transcript is written where you expect it.

A good smoke test is deliberately boring: ask the agent to inspect a harmless project file, summarize it in one sentence, and then check that the session can be resumed. If that fails, you have an installation or permission issue, not a prompt-quality problem.

Rapid Installation Test

After installation, run this test script to verify all functions:

#!/bin/bash

echo "🧪 Starting OpenClaw installation test..."

# Test 1: Check CLI availability
if command -v openclaw &> /dev/null; then
    echo "✅ CLI installed"
    openclaw --version
else
    echo "❌ CLI not found"
    exit 1
fi

# Test 2: Start Gateway
echo "🚀 Starting Gateway service..."
openclaw gateway start --background

sleep 3

# Test 3: Check Gateway status
if openclaw gateway status | grep -q "running"; then
    echo "✅ Gateway service running normally"
else
    echo "❌ Gateway service failed to start"
    exit 1
fi

# Test 4: Check Web Interface
echo "🌐 Testing Web Interface..."
if curl -s http://localhost:18789/health > /dev/null; then
    echo "✅ Web Interface accessible"
else
    echo "❌ Web Interface not accessible"
fi

# Test 5: Stop service
echo "🛑 Stopping Gateway service..."
openclaw gateway stop

echo "🎉 All tests passed! OpenClaw installed successfully."

Troubleshooting Cheat Sheet

Issue: Command not found

# Solution: Relink
npm link @openclaw/cli
# Or
export PATH="/usr/local/bin:$PATH"

Issue: Port conflict

# Solution: Use a different port
openclaw gateway start --port 18790

Issue: Python version error

# Solution: Set correct version
export PATH="/usr/local/opt/[email protected]/bin:$PATH"

Issue: Insufficient permissions

# Solution: Fix permissions
sudo chown -R $(whoami) ~/.openclaw

Who should use the quick install guide first

This page is the best starting point if you want one of these outcomes:

get OpenClaw running on a Mac as fast as possible
validate whether your local Node, Python, Homebrew, and Gateway path are basically healthy
decide whether the machine can reach a minimum viable setup before you invest in deeper configuration
compare a fast-start path against the fuller installation checklist

If you already know you need a cleaner long-term setup, multi-provider config, or a more repeatable team handoff, the complete installation guide is usually the better primary entry.

Common quick-install judgment questions

When should you use quick install instead of the complete installation guide

Use quick install when speed matters more than completeness, and your main question is "can this Mac run OpenClaw cleanly at all?" It is the right first pass for local validation, demos, and solo setup. If you are documenting a more durable rollout, the complete guide reduces rework later.

When does a quick install failure mean you should stop and switch to troubleshooting

If the CLI installs but Gateway status, doctor checks, or Web UI access still fail after basic path and version checks, stop treating it as a simple quick-install problem. At that point the bottleneck is usually environment inconsistency, permissions, provider setup, or runtime health, so the troubleshooting checklist becomes the better next page.

Docker Installation (Alternative)

If you prefer using Docker:

# Pull image
docker pull openclaw/openclaw:latest

# Run container
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest

# Execute commands inside container
docker exec -it openclaw openclaw --help

Updating OpenClaw

# Check for updates
npm outdated -g @openclaw/cli

# Update to latest version
npm update -g @openclaw/cli

# Or reinstall
npm install -g @openclaw/cli@latest

Uninstalling OpenClaw

# 1. Stop all services
openclaw gateway stop

# 2. Uninstall CLI
npm uninstall -g @openclaw/cli

# 3. Delete configuration (optional)
rm -rf ~/.openclaw

# 4. Delete log files
rm -rf /tmp/openclaw

Exact searches this Mac quick-install guide should answer next

Use this section when a reader arrives from a Mac-specific install query and needs the shortest safe path from download to a working OpenClaw gateway.

OpenClaw install Mac quick guide: install the app, confirm the gateway starts, then open the local dashboard before adding channels or providers.
OpenClaw macOS setup gateway not reachable: check whether the gateway process is running, whether the local port is blocked, and whether the browser is pointed at the expected URL.
OpenClaw Mac install permission issue: approve the app in macOS security settings first, then rerun the smoke test instead of reinstalling repeatedly.

Turn Mac install traffic into a first-success checklist

If you arrived from searches for an OpenClaw quick install guide on Mac, do not treat a finished command as the only success signal. The real acceptance path is first success: the local CLI starts, Gateway status is readable, a browser or channel can open a session, and one minimal task returns a stable reply.

The minimal checklist includes the openclaw gateway status output, the active config-file location, one successful session URL or session id, and the shell, Node version, and install method when it fails. That routes install traffic toward first run, config verification, and troubleshooting intent instead of stopping at download steps.

Get Help

View full documentation: openclaw --help
View command-specific help: openclaw <command> --help
Visit official docs: https://docs.openclaw.ai
GitHub Issue Tracker: https://github.com/openclaw/openclaw/issues

Tip: If you encounter issues during installation, view detailed logs:

tail -f ~/.openclaw/logs/gateway.log

Search-entry triage: what to check first when Mac install gets stuck

If you landed here from searches like “OpenClaw Mac install”, “openclaw install mac”, or “npm install OpenClaw failed”, narrow the failure down in this order:

Check the Node version first: use the supported LTS line instead of the old Node version that may ship with the machine or an older shell profile.
Separate install failure from startup failure: package-manager errors point to npm/pnpm, network, or permissions; successful install with startup failure points to config, ports, or login state.
Do not mix global install sources: Homebrew, npm global, and pnpm global can leave the openclaw command pointing at an older binary.
Preserve the first real error: repeated retries create noise. The first complete error, plus the active shell environment, is usually the most useful debugging evidence.

The goal is not to “try the install again”. The goal is to identify whether the failure sits in dependency install, command resolution, config loading, or first startup.