Install OpenClaw on Mac Mini: The Proven Home Server Setup

Skip to the wrong step and you waste an hour debugging a problem that the correct sequence prevents entirely. Here's what we've seen consistently: people install Node.js the wrong way, get the gateway running once, and then wonder why it dies overnight. This guide fixes all of that in one read.

Prerequisites: What You Need Before You Start

You need a Mac Mini running macOS Ventura (13) or later. Sonoma (14) and Sequoia (15) both work. The setup steps are identical across these versions with one exception noted in the sleep prevention section.

Open Terminal. You'll use it throughout this guide. If you're new to Terminal, it lives in Applications > Utilities > Terminal. Everything in this guide is a terminal command unless otherwise noted.

Check what's already installed:

# Check if Node.js is installed
node --version

# Check if npm is available
npm --version

If node returns a version below 18, or "command not found", proceed to Step 1. If you already have Node.js 18+ installed via nvm, skip to Step 2. If you installed Node.js via Homebrew or the pkg installer, we're going to replace it — the nvm approach is more reliable for home server use.

Step 1: Install Node.js via nvm

nvm (Node Version Manager) installs Node.js in your home directory without touching system paths. It takes 2 minutes.

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# The installer adds nvm to your shell config automatically
# Reload your shell configuration
source ~/.zshrc

# Verify nvm works
nvm --version

Now install the LTS version of Node.js. As of early 2025, that's Node.js 22 LTS.

# Install the latest LTS
nvm install --lts

# Set it as the default for new shells
nvm alias default node

# Verify
node --version   # should show v22.x.x
npm --version    # should show 10.x.x

Node.js is installed. The binary lives inside ~/.nvm/versions/node/. Keep note of the full path — you'll need it for the launchd plist.

# Find the exact binary path — copy this output
which node

Step 2: Install OpenClaw

One command. The -g flag installs OpenClaw globally under your nvm Node.js installation.

npm install -g openclaw

Installation takes 30–60 seconds depending on your connection. When it completes:

# Verify the install
openclaw --version

# Check where the binary landed
which openclaw

Copy the output of which openclaw. It'll look like /Users/yourname/.nvm/versions/node/v22.x.x/bin/openclaw. You need this exact path for the launchd service.

Step 3: Gateway Configuration

Create a dedicated directory for your OpenClaw server files. This keeps logs, config, and agent definitions together.

mkdir -p ~/openclaw-server
cd ~/openclaw-server

# Initialize gateway config
openclaw init --gateway

This creates gateway.yaml. Open it in your preferred editor:

nano gateway.yaml

The critical settings for a home server:

gateway:
  port: 8080
  token: "CHANGE-THIS-TO-A-LONG-RANDOM-SECRET"
  log_level: info
  log_file: ./gateway.log

agents: []

Generate a strong token. Run this in Terminal to get a random 32-character hex string:

openssl rand -hex 32

Paste the output as your token value. Save the file. Test the gateway starts correctly before setting up auto-start:

cd ~/openclaw-server
openclaw gateway start

# Should output:
# Gateway running on http://localhost:8080
# Press Ctrl+C to stop

With the gateway running, open a new terminal tab and verify the health endpoint:

curl http://localhost:8080/health
# Should return: {"status":"ok"}

Stop the gateway with Ctrl+C. The manual start works. Now make it automatic.

Step 4: Prevent macOS from Sleeping

Here's where most home server setups fail quietly.

System Settings change: Go to System Settings > Energy (or Battery on laptops). Find "Prevent automatic sleeping when the display is off" and turn it on. On macOS Sonoma 14+, this option is under Energy > Options.

caffeinate plist — create this file to block all sleep triggers:

cat > ~/Library/LaunchAgents/com.openclaw.caffeinate.plist << 'PLIST'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.openclaw.caffeinate</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/bin/caffeinate</string>
    <string>-s</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
</dict>
</plist>
PLIST

launchctl load ~/Library/LaunchAgents/com.openclaw.caffeinate.plist

Step 5: OpenClaw Gateway as a launchd Service

Replace YOUR_USERNAME and NODE_VERSION with your actual values from the which openclaw output earlier.

cat > ~/Library/LaunchAgents/com.openclaw.gateway.plist << 'PLIST'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.openclaw.gateway</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/YOUR_USERNAME/.nvm/versions/node/vNODE_VERSION/bin/openclaw</string>
    <string>gateway</string>
    <string>start</string>
  </array>
  <key>WorkingDirectory</key>
  <string>/Users/YOUR_USERNAME/openclaw-server</string>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key>
  <string>/Users/YOUR_USERNAME/openclaw-server/gateway.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/YOUR_USERNAME/openclaw-server/gateway-error.log</string>
</dict>
</plist>
PLIST

launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist

Verify the service is running:

# Check service status
launchctl list | grep openclaw

# Test the gateway endpoint
curl http://localhost:8080/health

The gateway is now a proper background service. It starts on login, restarts on crash, and survives reboots. Test the full cycle: restart your Mac Mini, wait 60 seconds for login agents to load, then curl the health endpoint from another device on your network.

Frequently Asked Questions

What Node.js version does OpenClaw require on Mac Mini?

OpenClaw requires Node.js 18 or later. Node.js 20 or 22 LTS are recommended for home server use. Install via nvm to pin the version and avoid conflicts with macOS system tools or future Xcode updates that can overwrite other Node.js installations.

How do I install OpenClaw globally on Mac Mini?

Run npm install -g openclaw after installing Node.js via nvm. Verify with openclaw --version. If the command is not found after install, run source ~/.zshrc to reload your PATH, then check again.

What is the gateway config file?

The gateway config is gateway.yaml, created by openclaw init --gateway. It defines port, gateway token, agent registrations, and log settings. The token is your authentication secret — generate it with openssl rand -hex 32 and never commit it to source control.

How do I stop the Mac Mini from sleeping and killing OpenClaw?

Two layers: set Energy Saver to prevent sleeping on AC power in System Settings, and create a launchd plist running caffeinate -s with RunAtLoad and KeepAlive set to true. Both layers together block all macOS sleep triggers reliably.

How do I run OpenClaw gateway as a background service?

Create a launchd plist in ~/Library/LaunchAgents/ pointing to the openclaw binary with the gateway start subcommand. Set RunAtLoad and KeepAlive to true. Load with launchctl load. The service starts on login and restarts automatically on crash.

How do I verify the OpenClaw gateway is running?

Run curl http://localhost:8080/health — a 200 response with {"status":"ok"} confirms the gateway is up. Also check launchctl list | grep openclaw to see service state and last exit code.