OpenClaw on macOS: Docker Desktop, Homebrew, and Apple Silicon Installation

You’ve heard about OpenClaw—the open-source personal AI agent that runs locally on your machine, connects to 25+ messaging platforms, and gives you real control over your AI infrastructure. Now you want to get it running on your Mac. Smart move. But here’s the thing: macOS gives you options, and each one has tradeoffs you should understand before you commit.

Whether you’re sitting at an M1 MacBook Pro or a brand-new M4 Mac Studio, this guide walks you through every path forward. We’ll cover Docker Desktop (the straightforward route), native Node.js installation via Homebrew (the performance option), and the specific considerations that matter on Apple Silicon.

Why macOS Deserves Special Attention

macOS is weird in the best way. It’s Unix underneath, but Apple’s done enough customization that generic “install this on Linux” guides don’t quite work. Factor in Apple Silicon—the M1, M2, M3, M4, and M5 chips—and you’ve got a genuinely different architecture than Intel x86. Some tools run natively, some run through Rosetta 2 emulation, and some are… well, let’s just say they have opinions about where you can put things.

OpenClaw knows about these quirks. It’s designed to work smoothly on Apple Silicon. But you need to make the right choice upfront, because switching methods midstream is annoying.

The Three Installation Paths: Which One Is For You?

Let’s be honest about what each path actually means:

Docker Desktop: Containerized, isolated, easy rollback. Your OpenClaw instance runs in its own sandbox. Updates are cleaner. But you’re trading some performance for convenience, and Docker Desktop on Mac has its own overhead.

Native Node.js (Homebrew): Runs directly on your system. Faster. Closer to the metal. But you’re managing Node.js versions, npm packages, and system dependencies yourself. Rollback means knowing what you changed.

Docker Desktop with Apple Silicon Native Images: Best of both worlds—if you set it up right. Docker Desktop on Mac can use native ARM64 images now, eliminating Rosetta 2 emulation entirely.

Most people starting out? Docker Desktop. Most people who’ve been running OpenClaw for a while? Native Node.js. We’ll cover both thoroughly.

Path 1: Docker Desktop Installation (The Easy Route)

Prerequisites

You’ll need:

• macOS 11 (Big Sur) or later (M1 or Intel)
• At least 8GB of RAM (16GB recommended for comfortable usage)
• About 4GB of disk space for Docker, another 2-3GB for OpenClaw
• An Apple ID or download permission (Docker Desktop needs it)

Step 1: Install Docker Desktop

Head to docker.com/products/docker-desktop and grab the installer. Here’s the important part: there are two versions. You want the one for Apple Silicon if you have an M-series chip. Docker Desktop detects your architecture and defaults correctly, but verify the download says “Apple Silicon” not “Intel Chip.”

Run the installer. It’ll ask for your password—Docker Desktop needs privileged access to manage the virtualization layer.

Once installed, open Docker Desktop from Applications. You’ll see the Docker menu appear in your menu bar. Wait for it to say “Docker Desktop is running”—not “starting,” but actually running. On the first launch, this takes a couple of minutes. Go grab coffee.

Step 2: Verify Docker Installation

Open Terminal and run:

docker --version

You should see something like Docker version 24.0.6. Good sign. Now test that it actually works:

docker run hello-world

This downloads a tiny test image and runs it. You’ll see a bunch of text ending with “Hello from Docker!” If you see that, Docker is properly installed.

Step 3: Clone OpenClaw

Pick a directory where you want OpenClaw to live. Your home directory is fine. Most people use something like ~/projects/ or just put it in ~/.openclaw/ (OpenClaw’s default workspace location). Let’s go with:

cd ~
git clone https://github.com/open-claw/openclaw.git
cd openclaw

Step 4: Configure Your Workspace

OpenClaw stores everything—your skills, memory, conversations, platform tokens—in a workspace directory. On macOS, this defaults to ~/.openclaw/.

Create it:

mkdir -p ~/.openclaw/

This directory will contain:

• config.yaml: Platform connections and settings
• skills/: Your skill definitions
• memory/: Knowledge base and conversation history
• soul.md: Your agent’s personality and behavior guidelines

You don’t need to populate these yet—OpenClaw will create defaults when it first runs.

Step 5: Build and Run with Docker

Navigate to your openclaw directory and build the Docker image:

docker build -t openclaw:latest .

This takes 2-3 minutes. Docker is downloading Node.js, installing dependencies, setting up the environment. Watch the output. If you see warnings, don’t panic—they’re usually fine. If you see errors (red text that says “Error”), something went wrong. Note the error and check the Docker output.

Once built, run it:

docker run -d \
  --name openclaw \
  -v ~/.openclaw:/root/.openclaw \
  -p 8080:8080 \
  openclaw:latest

What’s happening here:

• -d: Run in detached mode (background)
• --name openclaw: Give the container a name so you can reference it
• -v ~/.openclaw:/root/.openclaw: Mount your workspace directory into the container
• -p 8080:8080: Expose port 8080 (OpenClaw’s default API port)
• openclaw:latest: The image to run

Verify it’s running:

docker ps

You should see your openclaw container listed. Check the logs:

docker logs openclaw

You’re looking for a line that says something like “OpenClaw initialized” or “Listening on port 8080.” If you see errors here, we’ve got troubleshooting to do.

Docker Desktop Performance on Apple Silicon: The Reality

Here’s what people don’t tell you: Docker Desktop on macOS is slower than native installation. Not catastrophically slower, but noticeably. There’s a virtualization layer—Docker Desktop runs a lightweight Linux VM under the hood. Even on Apple Silicon with native ARM64 images, there’s overhead.

Typical latency increases you might see:

• File I/O: 10-15% slower
• Memory startup: Container takes 30-40% longer to initialize
• CPU-intensive tasks: 5-8% slower
• Network: Usually identical

For most OpenClaw usage—responding to messages, processing memory, running skills—you won’t notice. You’re waiting for the LLM backend to respond anyway, which dominates. But if you’re running bulk data processing or training a custom skill, you’ll feel the difference.

The tradeoff: isolation, easier rollback, no system clutter. For most people, that’s worth it.

Path 2: Native Node.js Installation via Homebrew (The Performance Route)

Why Choose Native?

You want maximum performance. You’re comfortable managing Node.js yourself. You want OpenClaw to feel like a native application, not a container. You plan to run it long-term and want the fastest possible execution.

Prerequisites

• macOS 11 or later
• At least 4GB of RAM (8GB recommended)
• About 1.5GB disk space for Node.js and OpenClaw
• Command line comfort level

Step 1: Install Homebrew (If You Don’t Have It)

Homebrew is macOS’s package manager. If you don’t have it, install it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the prompts. It’ll ask for your password and might take a few minutes. On Apple Silicon Macs, Homebrew is native—no emulation required.

Verify installation:

brew --version

Step 2: Install Node.js via Homebrew

brew install node

Homebrew installs the latest LTS version. OpenClaw requires Node.js 18.x or later, so you’re good. The installation includes npm (Node’s package manager), which you’ll need.

Verify:

node --version
npm --version

You should see versions like v20.x.x and 10.x.x.

Step 3: Clone OpenClaw

cd ~
git clone https://github.com/open-claw/openclaw.git
cd openclaw

Step 4: Install Dependencies

npm install

This reads the package.json file and installs all required packages. On Apple Silicon, npm is smart about downloading arm64-native bindings when available. This step takes 2-5 minutes depending on your internet speed.

Watch for warnings—npm warns about outdated packages but usually they’re fine. Errors are red and scary. If you see errors, check npm’s output. Common issues:

• Missing build tools: Run xcode-select --install
• Permission errors: Don’t use sudo. Fix with npm install -g npm@latest

Step 5: Create and Configure Your Workspace

mkdir -p ~/.openclaw

Create the initial config:

cp config.example.yaml ~/.openclaw/config.yaml

Edit ~/.openclaw/config.yaml with your text editor. You’ll configure:

• Platform tokens (Slack, Discord, Telegram, etc.)
• LLM backend settings
• Workspace paths
• Log level

For your first run, the defaults are fine. You can add platform tokens later.

Step 6: Start OpenClaw

npm start

You’ll see startup output. OpenClaw initializes its memory system, loads skills, connects to configured platforms. Within a few seconds, you should see “OpenClaw ready” or similar. The process stays running in the foreground.

To run in the background, use:

npm start &

Or use a process manager like pm2 for long-term deployment:

npm install -g pm2
pm2 start openclaw
pm2 logs openclaw

Performance Reality Check: Native vs Docker

Let’s talk numbers on Apple Silicon:

Metric	Docker Desktop	Native Node.js	Difference
Startup time	3-5 seconds	1-2 seconds	2-3x faster
Memory footprint	200-300MB base	40-60MB base	4-5x less
File I/O (100 file read)	800ms	700ms	10-15% faster
Message latency	~20ms overhead	None	Noticeable if you care

For actual conversation latency, the LLM response time (usually 1-5 seconds) dwarfs any infrastructure differences. But startup matters. Boot time matters. Memory efficiency matters if you’re running on a MacBook Air.

Native installation is genuinely faster. It’s the right choice if performance is a priority.

Apple Silicon Specific Considerations: What You Actually Need to Know

Rosetta 2 and Why You Care (Or Don’t)

Apple Silicon Macs include Rosetta 2—a transparent emulation layer that runs Intel code. It’s actually pretty good. When Docker Desktop uses native ARM64 images, Rosetta is irrelevant. When it doesn’t, code runs at about 80-85% native speed.

OpenClaw? All its dependencies support Apple Silicon natively now. No Rosetta overhead. You get true native speed.

M-Series Performance Tiers and Optimization

Apple’s M-series chips vary, and it’s worth understanding what you get at each tier:

• M1/M2: 8-core CPU (4 performance + 4 efficiency), 7-10 core GPU. Solid for OpenClaw. M1 MacBook Air handles continuous OpenClaw usage beautifully.
• M3/M4: 8-12 core CPU (better efficiency cores). Overkill for OpenClaw specifically. You’ll get faster response times, but the difference is 5-10% speed improvement—noticeable in benchmarks, not in daily use.
• M5: Coming in 2026, expect 15-20% faster performance than M4.

The honest truth: even M1 handles OpenClaw beautifully. You don’t need the latest chip. M2 MacBook Air? Totally fine. Will run 10+ simultaneous conversations without breaking a sweat.

Performance Optimization by Chip:

M1 MacBook Air: Can run 1-2 instances comfortably. Expect 2-3 second response latency.

M1 Pro/Max: Can run 3-5 instances simultaneously. LLM API calls dominate, so infrastructure barely matters. Response latency still 2-3 seconds (bottlenecked by LLM backend, not Mac hardware).

M2/M3/M4: Overkill for OpenClaw alone. These machines shine when you’re running multiple services (OpenClaw + local LLM via Ollama + other services). That’s a different conversation.

Thermal Performance on Mac: Understanding Your Hardware

Macs don’t have traditional cooling like PCs. M-series chips are thermally efficient. Running CPU-intensive tasks might cause throttling, but this is intentional, not a failure. Let’s be specific:

MacBook Air (no fan, passive cooling):

• Normal operation: 30-50C
• Running OpenClaw + active usage: 50-65C
• Running local LLM: 70-80C (thermal throttling begins)
• Maximum safe: 95C (designed safety limit)

You’ll feel warmth on the aluminum chassis. This is fine. Macs are built for this. Aluminum dissipates heat excellently.

MacBook Pro (has fan):

• Normal operation: 30-45C
• Running OpenClaw + active usage: 50-60C
• Running local LLM: 65-75C
• Fan spins up around 70C (very quiet)
• Maximum safe: 97C

The fan is nearly silent. You’ll barely notice it spinning.

Mac Mini / Mac Studio (desktop, active cooling):

• These machines have better thermal design than laptops
• Thermal throttling is uncommon
• Can run multiple instances + local LLMs simultaneously

Real scenario breakdown:

Your MacBook Air is running OpenClaw. You ask it a complex question. The agent needs to make 5 API calls, fetch a web page, and run local processing.

• Seconds 0-2: LLM processes your question (not using much CPU, waiting for API response)
• Seconds 2-4: Web fetch (network bound, not CPU bound)
• Seconds 4-6: Processing results (30-40% CPU for 2-3 seconds)
• During second 5, CPU hits 100%, Mac temperature climbs to 65-70C
• Fan might spin up slightly (if Pro) or you feel warmth (if Air)
• Seconds 6-8: Response returned

This is normal operation. Your Mac isn’t in distress. The thermal throttling at 80C+ exists to protect the hardware—you’ve got 15C of headroom before that triggers.

If you run local LLMs via Ollama:

Running a 7B-parameter model on M1 is different. That’s CPU-intensive, sustained inference.

• CPU: 100% for 20-30 seconds
• Temperature: 80-85C (possible thermal throttling)
• Performance: Inference might drop 5-15% as throttling activates
• This is fine. Still not a problem. Your Mac stays safe.

The thermal design is intentional. Apple’s engineering team says “keep it under 100C.” If you approach that, throttle. It’s safety, not a bug.

Docker Desktop vs Native Performance Comparison on Apple Silicon

Docker Desktop on Mac has an interesting performance profile on Apple Silicon:

Docker Desktop with native ARM64 images (which OpenClaw uses):

• No Rosetta 2 overhead
• Virtualization overhead: ~10-15% slower than native
• Startup: 3-5 seconds (Linux VM initialization)
• Memory: Base 200-300MB (Linux VM overhead)

Native Node.js via Homebrew:

• No virtualization, pure native
• Startup: 1-2 seconds
• Memory: Base 40-60MB
• Performance: 100% native speed

The difference sounds significant, but in practice:

• LLM inference dominates (1-5 second wait)
• Network latency dominates for web calls (200-500ms minimum)
• File I/O differences (Docker slower by ~50-100ms)

If you’re building an app where response time is critical and you need under 100ms latency per request, Docker matters. For typical OpenClaw usage, it’s invisible.

Real numbers on M1 MacBook Air:

Task: Process Slack message → call Claude API → respond

Native Node.js:
  - Parse message: 2ms
  - Call LLM API: 2,000ms (wait for response)
  - Format response: 3ms
  - Total: ~2,005ms

Docker Desktop:
  - Parse message: 2ms (Docker overhead added)
  - Call LLM API: 2,000ms
  - Format response: 3ms
  - Total: ~2,005-2,050ms

Difference: 45ms on a 2 second operation. Invisible to user.

Docker’s overhead appears in file-heavy operations (analyzing large repos, processing big datasets). For typical message processing, negligible.

Battery Impact Analysis (for Laptop Users)

If you’re running OpenClaw on a MacBook Air with battery:

Idle (OpenClaw running, not processing):

• M1 MacBook Air: 80-95W system power draw
• OpenClaw: ~10-20W (depending on platform connections)
• Battery life: ~8-9 hours unplugged

Active usage (processing messages):

• Peak CPU during inference: ~25-40W
• Overall system: 100-120W
• During active phase: Drops maybe 20-30 minutes from battery life (for 30 seconds of processing)
• Sustained usage (OpenClaw constantly processing): ~5-6 hours unplugged

Practical reality:

If you’re running OpenClaw on a laptop unplugged, plug in when you’re using it actively. If you’re using it as a background service, it draws enough power that you’ll want AC power.

For reference, Slack also runs in background and draws similar power. If you’re comfortable running Slack unplugged, you’re comfortable running OpenClaw.

Docker vs Native battery impact:

Native Node.js is marginally more efficient (~5-10W less under load), but the difference is small enough that Docker’s added overhead is negligible in battery calculations.

Use whichever installation method you prefer. Battery impact is not the deciding factor.

Comparison: Docker vs Native Side-by-Side

Factor	Docker Desktop	Native Node.js
Installation time	15 minutes	10 minutes
Performance	85-95% native	100% native
Upgrades	Clean, repeatable	Manual management
Rollback	Easy (restart container)	Manual (restore node_modules)
System clutter	None (isolated)	Adds Node.js system-wide
Development	Good (can modify image)	Better (instant feedback)
Memory usage	Higher (VM overhead)	Lower
First-time user?	Recommended	Advanced
Long-term reliability?	Excellent	Excellent

Post-Installation: Actually Using OpenClaw

Regardless of which path you chose, you now have OpenClaw running. Next steps:

1. Configure platforms: Edit your config.yaml to add Slack tokens, Discord webhooks, etc.
2. Customize your SOUL.md: OpenClaw’s personality lives in ~/.openclaw/soul.md. Edit this to define how your agent behaves.
3. Add skills: Skills live in ~/.openclaw/skills/. Each skill is a SKILL.md file defining what your agent can do.
4. Monitor: Use docker logs openclaw (Docker) or check stdout (native) to watch what’s happening.

Troubleshooting: When Things Don’t Work

Docker Desktop Won’t Start

• Check if virtualization is enabled in your Mac’s settings
• Restart Docker Desktop (quit and reopen)
• Check available disk space (Docker needs room)
• If all else fails, uninstall and reinstall Docker Desktop

OpenClaw Crashes Immediately

Check the logs. The error message tells you what’s wrong:

• “ENOENT: no such file or directory”: Workspace doesn’t exist or can’t be accessed
• “Port 8080 in use”: Something else is using that port. Kill it or configure a different port.
• “Module not found”: Dependencies didn’t install. Try npm install again.

Node.js Installation Issues

node --version
npm --version

If npm is missing, reinstall with brew reinstall node. If version is wrong, use nvm for version management:

brew install nvm
nvm use 20

File Permission Issues

macOS has some quirks with file permissions. If you get permission errors:

chmod -R u+rw ~/.openclaw/

This gives your user read-write access to the workspace. Don’t use sudo unless you want to create permission headaches later.

Performance Tuning: Getting the Most Out of Your Mac

Before we dive into advanced config, let’s talk about squeezing performance. Both Docker and native installations benefit from understanding your hardware.

Memory Allocation (Docker)

Docker Desktop on Mac lets you control how much RAM the Linux VM gets:

1. Open Docker Desktop preferences
2. Go to Resources
3. Set Memory slider to 6-8GB (leaving your Mac 4-8GB free)

Too much RAM allocated? Your Mac gets sluggish. Too little? OpenClaw runs out of memory and gets OOM-killed.

The sweet spot depends on your Mac’s total RAM:

• 8GB total: Allocate 4GB to Docker, keep 4GB for macOS
• 16GB total: Allocate 8-10GB, keep 6GB for macOS
• 32GB+ total: Allocate 16GB+, you’re fine

Docker on Apple Silicon is efficient. Even 4GB allocation handles most workloads.

CPU and Network (Docker)

Docker Desktop also controls CPU cores. The default is reasonable—it uses whatever cores are available. Don’t fiddle with this unless you’re having issues.

Network: Docker’s networking on Mac uses a lightweight virtualization bridge. It’s transparent. Incoming connections work via localhost (127.0.0.1). If you want external apps (on your network) to reach OpenClaw, you need more config—beyond scope here.

Native Node.js: No Tuning Needed

Native Node.js runs directly on your Mac’s hardware. No allocation decisions. It uses what it needs. Simple.

The only tuning: if you run the pm2 process manager, you can limit workers:

apps:
  - name: openclaw
    script: node
    args: index.js
    instances: 2 # Max 2 worker processes
    max_memory_restart: 500M # Restart if it hits 500MB

But for typical usage, default settings are fine.

Advanced Configuration: Getting More Out of OpenClaw

Both installation paths support deeper configuration once you’re running. Let’s talk about what experienced users typically do.

Memory Management and Optimization

OpenClaw’s memory system—the knowledge base that powers context awareness—can be tuned. In your config.yaml, you’ll find memory settings:

memory:
  backend: sqlite # or postgresql for production
  retention_days: 90
  max_conversations: 1000
  embedding_model: sentence-transformers

On macOS, the defaults are sensible. But here’s what advanced users know: if you’re running on a MacBook Air with limited RAM, lowering max_conversations and retention_days helps. If you’re on a Mac Studio with 96GB, crank them up.

Memory storage happens in ~/.openclaw/memory/. On native installation, this is your filesystem. Docker mounts it, so performance is slightly worse. If you’re processing high volumes of conversations, native wins here.

Platform Token Management

Adding tokens to config.yaml is straightforward, but doing it securely matters. Never hardcode tokens in version control.

Instead, use environment variables:

platforms:
  slack:
    token: ${SLACK_TOKEN}
  discord:
    token: ${DISCORD_TOKEN}

Then set them in your shell:

export SLACK_TOKEN="xoxb-your-token-here"
export DISCORD_TOKEN="your-discord-token"

For Docker, pass them at runtime:

docker run -d \
  --name openclaw \
  -e SLACK_TOKEN="xoxb-..." \
  -e DISCORD_TOKEN="..." \
  -v ~/.openclaw:/root/.openclaw \
  -p 8080:8080 \
  openclaw:latest

This keeps secrets out of your workspace files.

Skill Development and Testing

Skills are the extension system. Each skill is a SKILL.md file in ~/.openclaw/skills/. Writing custom skills is beyond this guide, but here’s what to know for your installation:

On native Node.js, you can hot-reload skills. Edit a skill file, and OpenClaw picks up the change in seconds. Development is fast.

On Docker, file changes require container restart. Less convenient for development. But if you’re just using existing skills, irrelevant.

If you plan to develop custom skills, native installation is better. If you’re consuming community skills, Docker is fine.

Workspace Backup Strategy

We mentioned this briefly, but it deserves expansion. Your workspace is your inventory:

~/.openclaw/
├── config.yaml          # Platform tokens, settings
├── soul.md              # Personality guidelines
├── skills/              # 5-20 skill files
├── memory/              # Conversation history (can be huge)
└── logs/                # Activity logs

Memory can grow. If you’ve been running OpenClaw for months, memory/ might be 500MB-2GB. Full backups matter.

Backups on macOS are easy with Time Machine:

sudo tmutil addexclusion -p ~/.openclaw  # Add to Time Machine

Actually, don’t. You want explicit versioned backups:

tar -czf ~/openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

This creates a compressed archive. Store it somewhere safe.

Monitoring and Logging

OpenClaw logs to stdout (native) or Docker logs. On macOS, you can redirect to a file:

npm start >> ~/.openclaw/logs/openclaw.log 2>&1 &

Then tail it:

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

Watch for patterns: repeated errors, connection failures, memory spikes. Occasional warnings are fine. Patterns suggest issues.

Docker logging is easier:

docker logs -f openclaw

The -f flag follows new logs in real-time. Press Ctrl+C to stop.

Migration: Switching Between Installation Methods

You started with Docker. Now you want native speed. Or vice versa. Here’s how:

Docker → Native

1. Stop Docker: docker stop openclaw
2. Backup workspace: cp -r ~/.openclaw ~/.openclaw.docker-backup
3. Install native Node.js (Homebrew)
4. Clone OpenClaw source
5. npm install
6. npm start

Your workspace files are untouched. Everything transfers cleanly.

Native → Docker

1. Stop native: npm stop or Ctrl+C
2. Backup workspace: cp -r ~/.openclaw ~/.openclaw.native-backup
3. Verify ~/.openclaw exists (should)
4. Build Docker image: docker build -t openclaw:latest .
5. Run container with workspace mount

Also transfers cleanly.

Between installations, the only dependency is your workspace files. Skills, memory, config—it all stays.

Troubleshooting: Common Gotchas on macOS

“npm ERR! Error: EACCES: permission denied”

This means npm is trying to write to system directories without permission. Don’t use sudo. Instead:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Add that export to your shell profile (~/.zshrc on modern Macs):

echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

What this does: By default, npm wants to install global packages to /usr/local/ which requires sudo. Instead, you’re telling it to use a directory in your home folder where you have write permission.

Why not sudo?: If you use sudo for npm, package installations run as root. This causes permission issues later when you try to use those packages as a regular user. It’s a permission mess waiting to happen. Avoid it.

Docker: “Error response from daemon: dial unix /var/run/docker.sock: connect: permission denied”

Docker Desktop didn’t start properly. Quit it, reopen it, wait for the menu bar icon to stabilize.

If that doesn’t work:

1. Check Activity Monitor for Docker processes (Cmd+Space, type Activity Monitor)
2. Force quit any lingering Docker processes
3. Reopen Docker Desktop from Applications
4. Wait for “Docker Desktop is running” message (not just “starting”)

If still broken: Restart your Mac. This clears the socket file that Docker uses.

OpenClaw: “Port 8080 already in use”

Something else is using that port. Find it:

lsof -i :8080

You’ll see what’s using it. Common culprits:

• Old OpenClaw instance still running
• Some other local development server
• Occasionally, a system service

If it’s an old OpenClaw instance, kill it:

kill -9 <PID>

Or configure OpenClaw to use a different port in config.yaml:

server:
  port: 8081

Then restart OpenClaw.

Git: “fatal: not a git repository”

You didn’t properly clone OpenClaw. Make sure you’re in the directory with .git:

ls -la | grep git

If you don’t see .git/, reclone:

cd ..
rm -rf openclaw
git clone https://github.com/open-claw/openclaw.git
cd openclaw

Why this happens: You accidentally ran git clone from inside the openclaw directory (creating openclaw/openclaw/), or you extracted a ZIP file instead of cloning. Clone using git, not ZIP.

“Cannot find module ‘openclaw'”

Dependencies didn’t install. Run:

npm install
npm install --global  # Sometimes needed for global deps

If that doesn’t work, nuclear option:

rm -rf node_modules package-lock.json
npm install

This reinstalls everything from scratch. Takes 2-5 minutes.

If that still fails: Check for Apple Silicon compatibility. Make sure you installed Node.js via Homebrew (native ARM64), not downloading Intel binaries.

node -p process.arch

Should return “arm64” on M-series Macs. If it returns “x64”, you have Intel Node.js running under Rosetta—performance is fine, but rebuilds are slower.

“ENOTDIR: not a directory” or permission errors in workspace

Your ~/.openclaw/ directory doesn’t exist or has wrong permissions:

# Create it
mkdir -p ~/.openclaw

# Ensure you own it
chmod -R u+rw ~/.openclaw

Don’t use sudo unless you’ve created the directory with sudo (then you have to sudo everything).

Docker: “Cannot connect to Docker daemon”

Docker Desktop is installed but not running. Open Applications, find Docker.app, double-click to launch it.

Wait for the menu bar icon to become active (the whale icon in the top right). This takes 10-30 seconds on first launch.

OpenClaw starts but immediately crashes

Check the logs:

Native Node.js:

npm start
# Look for error messages in the output

Docker:

docker logs openclaw

Common crash causes:

1. “ENOENT: no such file” → Workspace directory missing

2. Fix: mkdir -p ~/.openclaw/

3. “Port already in use” → Another process on 8080

4. Fix: Change port or kill the other process

5. “Module not found” → Dependencies didn’t install

6. Fix: npm install again

7. “Cannot read property ‘token’ of undefined” → Missing config

8. Fix: Create config.yaml with platform tokens

Look at the full error message. The first line usually tells you exactly what’s wrong.

“M1/Apple Silicon-specific” build failures

Some npm packages don’t have pre-built binaries for ARM64. During npm install, they try to compile from source.

This requires build tools. Install them:

xcode-select --install

This is a one-time setup. Takes a few minutes. After this, npm can compile native modules.

Docker Desktop memory/CPU issues

On M1 Macs, Docker sometimes uses excessive resources. Check Docker preferences:

1. Open Docker Desktop
2. Click menu bar icon → Preferences
3. Go to Resources
4. Adjust Memory slider (recommend 6-8GB of your total)
5. Keep CPU default (uses all cores when needed)
6. Click Apply & Restart

If OpenClaw constantly crashes with “out of memory,” reduce the memory allocated to OpenClaw or split into multiple instances.

File permission issues after updates

Sometimes git pulls or npm updates create files with wrong permissions:

# Fix recursive ownership
chmod -R u+rw ~/.openclaw/

# If still broken (rare):
sudo chown -R $(whoami) ~/.openclaw/

Avoid the sudo version unless absolutely necessary. It creates cascading permission issues.

OpenClaw seems slow after update

After updating OpenClaw or Node.js, rebuild native dependencies:

npm ci  # Clean install
npm rebuild  # Rebuild native modules
npm start

This ensures everything is compiled for your exact system architecture.

“Xcode license has not been accepted”

If you see this during npm install:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept

Then retry your npm command.

Git authentication issues (for cloning)

If cloning fails with “Permission denied”:

1. You need SSH keys set up
2. Generate one: ssh-keygen -t ed25519
3. Add public key to GitHub (GitHub.com → Settings → SSH Keys)
4. Try cloning again

Or, use HTTPS instead:

git clone https://github.com/open-claw/openclaw.git

(HTTPS works but prompts for GitHub personal access token. SSH is smoother after one-time setup.)

When to Use Docker vs Native: Final Decision Matrix

Let’s be explicit. Here’s how to choose:

Use Docker if:

• You’re new to command line
• You want zero system impact
• You don’t plan to develop custom skills
• You like containerized isolation
• You want simple upgrades

Use Native if:

• You want maximum performance
• You develop custom skills
• You’re comfortable with Node.js
• You’re running on limited resources (MacBook Air)
• You want instant feedback on changes

Most beginners gravitate Docker. Most advanced users go native. Neither is wrong.

When to Upgrade Your Installation

You’ve got OpenClaw running. When do you switch methods?

• Started with Docker, want better performance? → Migrate to native
• Running native, want easier updates? → Consider Docker
• Both work fine for most people. Switching is optional.

The migration is painless. Your workspace transfers instantly. So don’t agonize over the choice. Pick one, get running, iterate later.

Final Thoughts

OpenClaw on macOS is genuinely easy. Both installation paths work. Docker is newbie-friendly and beginner-proof. Native is faster and gives you more control. Apple Silicon support is excellent—you’re not dealing with emulation nonsense anymore.

Pick the path that matches your comfort level and use case. Both will be humming along, running your personal AI agent, in under 30 minutes.

The setup is straightforward. The real power comes after: connecting platforms, building skills, training your agent’s personality. That’s where OpenClaw becomes yours.

Questions or stuck? The OpenClaw community is helpful. Check the GitHub issues, the Discord, the docs. We’ve all been where you are.

Happy running.