OpenClaw on Mac Mini: Complete Setup Guide

#Why Mac Mini M4 for OpenClaw?

The Mac Mini M4 has become the de facto standard hardware for running OpenClaw in production. With its compact form factor, low power consumption (as low as 5W idle), and Apple Silicon performance, it is the ideal always-on host for your autonomous AI agent. The community overwhelmingly recommends it, and Peter Steinberger (OpenClaw's creator) himself runs his primary agent on one.

#Recommended Hardware Configurations

For most users, the base Mac Mini M4 with 16 GB of unified memory is more than sufficient. The heavier lifting happens on the LLM provider's servers, not on the Mini: the Gateway's job is to hold channel connections open, schedule automations, and shuttle turns to and from the model. OpenClaw's docs publish no RAM or CPU figure for the Gateway, so treat any number you see quoted in the community as a local measurement rather than a spec.

#Step 1: Prepare macOS for Always-On Operation

A Mac Mini running OpenClaw should never sleep. The agent needs to be available around the clock to respond to messages, execute scheduled tasks, and run heartbeat cycles.

#Disable Sleep and Energy Saver Settings

Open System Settings > Energy and configure the following:

• Set Turn display off after to Never (or 1 minute if you have a display connected, because the display sleeping is fine)
• Disable Put hard disks to sleep when possible
• Enable Prevent automatic sleeping when the display is off
• Enable Start up automatically after a power failure
• Enable Wake for network access

You can also configure these settings from the terminal:

Verify your settings:

#Enable Automatic Login

For headless operation (no monitor, keyboard, or mouse), you want the Mac Mini to boot straight to the desktop:

1. Open System Settings > Users & Groups
2. Click Automatic Login and select your user account
3. Enter your password to confirm

#Disable Software Update Auto-Restart

macOS can automatically install updates and restart your machine, which would take your agent offline:

1. Open System Settings > General > Software Update
2. Click Automatic Updates
3. Disable Install macOS updates
4. Keep Download new updates when available enabled so you can install them on your schedule

#Step 2: Create a Dedicated User Account (Recommended)

Running OpenClaw under a dedicated macOS user account provides better security isolation. This is optional but recommended.

1. 1
   Create the account

   Open System Settings > Users & Groups. Click Add Account. Create a Standard user named 'openclaw' with a strong password.

2. 2
   Enable automatic login for this account

   Set the 'openclaw' user as the automatic login account under System Settings > Users & Groups > Automatic Login.

3. 3
   Log in as the new user

   Log out of your current account and log in as 'openclaw'. All subsequent steps should be performed as this user.

4. 4
   Configure the home directory

   The user's home directory will be /Users/openclaw. All OpenClaw data, configuration, and skills will live here.

#Step 3: Install Prerequisites

#Install Homebrew

Homebrew is the package manager for macOS. If you do not already have it installed:

After installation, follow the instructions to add Homebrew to your PATH. For Apple Silicon Macs:

#What Node.js Version Does OpenClaw Need?

The install docs list the supported runtimes as "Node 24.16+ or 26.1+", and recommend Node 26. Install a current Node via Homebrew:

Verify the installation:

Anything below 24.16 is outside the supported range for the latest release listed as of September 19, 2026, so upgrade before you install OpenClaw rather than after.

#Install pnpm (Optional)

pnpm is one of the documented global install paths for OpenClaw, and it is handy for skill development:

#Install Git

Git is required for skill management and updates:

#Step 4: Install OpenClaw

With prerequisites in place, use the documented installer script:

If you would rather install the package globally, the docs give an npm path and a pnpm path. On npm 12, the --allow-scripts flag is required because npm now blocks unapproved lifecycle scripts by default:

Either global install is followed by onboarding, which is also where the managed service gets installed:

#What Does Onboarding Actually Ask?

openclaw onboard is documented as "Guided setup that establishes inference first: it detects existing AI access, waits for your provider choice, verifies that connection, persists only the working route, and then starts OpenClaw to configure the rest." The documented phases are:

1. Security notice and agent naming
2. Discovery access-level choice
3. AI provider detection and selection: have an API key ready. See the API Key Setup Guide.
4. Live connection verification: only a working route gets persisted.
5. Memory import offer, if there is anything to import
6. Standard setup application
7. Plugin and skill recommendations
8. Control UI dashboard handoff, or a terminal fallback

The docs do not name a default or recommended model for a new agent, so pick based on your own cost and capability trade-off rather than on a number quoted in a blog post. Messaging channels are configured after onboarding; see the Messaging Channels Guide.

#Where Does OpenClaw Put Its Files?

After installation, "Everything lives under $OPENCLAW_STATE_DIR (default: ~/.openclaw)", which the docs describe as holding "config, channel/provider state, auth profiles, sessions, logs". These are the paths the docs actually name:

~/.openclaw/
  openclaw.json                              # Main configuration file
  .env                                       # Global environment fallback
  secrets.json                               # Secret values referenced from config
  credentials/oauth.json                     # OAuth credentials
  state/openclaw.sqlite                      # Shared state database
  skills/                                    # Shared managed skills
  agents/<agentId>/agent/auth.json           # Per-agent auth profile
  agents/<agentId>/agent/openclaw-agent.sqlite
  agents/<agentId>/sessions/                 # Per-agent session records
  workspace/                                 # Agent workspace (agents.defaults.workspace)

The agent workspace is a separate concept from the state directory, even though it sits inside it by default. Its documented default is OPENCLAW_WORKSPACE_DIR when set, otherwise <state-dir>/workspace, which is ~/.openclaw/workspace for a default install. Bootstrap writes these files:

~/.openclaw/workspace/
  AGENTS.md              # Operating rules, including a `## Tools` section
  SOUL.md                # Agent personality (optional bootstrap file)
  IDENTITY.md            # Name, role and avatar (optional bootstrap file)
  USER.md                # Context about you (optional bootstrap file)
  BOOTSTRAP.md           # First-run only
  MEMORY.md              # Curated long-term memory (optional)
  BOOT.md                # Optional
  memory/YYYY-MM-DD.md   # Daily memory files
  skills/                # Optional workspace-local skills

A few things worth knowing, because older write-ups get them wrong:

• There is no data/ or backups/ directory, and skills/ is not split into built-in, community and custom folders.
• TOOLS.md and HEARTBEAT.md are retired. Local tool and environment notes "now live in the ## Tools section of AGENTS.md", and HEARTBEAT.md "is accepted but a no-op since heartbeat context moved to cron monitor scratch". See the Memory System Guide for the current heartbeat mechanism.
• The .env at ~/.openclaw/.env is a global fallback: OpenClaw reads env vars from the parent process and additionally loads a .env from the current working directory plus that global fallback. Neither .env normally overrides an existing variable.
• The optional bootstrap files (SOUL.md, USER.md, IDENTITY.md) can be skipped with agents.defaults.skipOptionalBootstrapFiles.

The persistent store is the shared SQLite database at ~/.openclaw/state/openclaw.sqlite.

#Step 5: Grant macOS Permissions

OpenClaw needs specific macOS permissions to function fully. Without these, certain skills and system interactions will fail silently.

#Full Disk Access

Full Disk Access allows OpenClaw to read and write files across your system, which is essential for file management skills.

1. Open System Settings > Privacy & Security > Full Disk Access
2. Click the + button
3. Navigate to the OpenClaw binary (typically /usr/local/bin/openclaw or the path shown by which openclaw)
4. Toggle it On

#Accessibility Access

Accessibility permissions enable OpenClaw to interact with the macOS UI, control applications, and use automation skills.

1. Open System Settings > Privacy & Security > Accessibility
2. Click the + button
3. Add the OpenClaw binary
4. Toggle it On

#Automation (Optional)

If you want OpenClaw to control other applications via AppleScript:

1. Open System Settings > Privacy & Security > Automation
2. Grant OpenClaw access to System Events and any specific applications

#Step 6: Install the Daemon

The daemon ensures OpenClaw starts automatically when your Mac boots and stays running in the background. This is the critical step that makes your agent truly autonomous.

There is no bare openclaw --install-daemon. openclaw gateway install "installs and starts the service"; the --install-daemon flag belongs to onboarding, where it "starts the managed gateway install path first".

On macOS this installs a LaunchAgent. The documented label is ai.openclaw.gateway for the default profile (or ai.openclaw.<profile> for a named profile), and the plist lives at:

~/Library/LaunchAgents/ai.openclaw.gateway.plist

You can inspect it through launchd directly:

launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

#Verify the Daemon

Check that the Gateway is answering:

openclaw health is documented as fetching "a health snapshot from the running Gateway over WebSocket RPC (no direct channel sockets from the CLI)". It takes --json for machine-readable output, --timeout <ms> (default 10000), and --verbose, which "forces a live probe and expands output across all configured accounts and agents". There is no --quiet flag, so scripts should parse --json rather than grep prose.

#Managing the Daemon

Start, stop, or restart the service:

The Gateway runbook says to use openclaw gateway restart rather than chaining stop and start. gateway stop uses launchctl bootout by default; add --disable if you want the suppression to survive a reboot.

Check the service status:

openclaw gateway status --deep adds system-level service scanning, and openclaw doctor --fix audits and repairs service config drift.

View real-time logs. There is no openclaw gateway logs subcommand; openclaw logs tails "Gateway file logs over RPC" and follows with --follow:

#Where Do the Log Files Live?

Not in ~/.openclaw/logs/, despite what a lot of setup posts claim. The documented default log file is /tmp/openclaw/openclaw-YYYY-MM-DD.log, with /tmp/openclaw/openclaw-<profile>-YYYY-MM-DD.log for named profiles. Point it somewhere durable in ~/.openclaw/openclaw.json if you want logs to survive a reboot:

{
  "logging": {
    "file": "/path/to/openclaw.log"
  }
}

The state directory does get one log of its own: Gateway lifecycle mutations "append best-effort key-value audit records to <state-dir>/logs/gateway-restart.log".

#Step 7: Configure Headless Access with Tailscale

If your Mac Mini runs headless (no monitor or keyboard), you need a way to access it remotely. Tailscale is the recommended solution because it creates a secure, zero-config VPN mesh network.

#Install Tailscale

Open Tailscale from your Applications folder and sign in with your account. Your Mac Mini will appear on your Tailscale network with a stable IP address.

#Enable SSH Access

1. Open System Settings > General > Sharing
2. Enable Remote Login (SSH)
3. Restrict access to Only these users and add your user account

Now you can SSH into your Mac Mini from any device on your Tailscale network:

ssh openclaw@your-mac-mini.tailnet-name.ts.net

#Access the Control UI Remotely

OpenClaw serves its Control UI from the same port as the Gateway WebSocket: one port multiplexing "WebSocket + HTTP (Control UI, hooks, etc.)". The documented default is 18789, not 3420, and the precedence is --port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789. The default bind mode is loopback.

Open it locally with:

That command is documented as opening "the Control UI with a short-lived, one-time owner pairing link. A successful handoff gives that signed browser a durable administrator device credential." Pass --no-open to print the URL without launching a browser.

Option A: SSH tunnel (keeps the bind on loopback)

ssh -L 18789:localhost:18789 openclaw@your-mac-mini.tailnet-name.ts.net

Option B: Bind to the tailnet

There is no gateway.host key. Binding is controlled by gateway.bind, whose documented values are auto, loopback (default), lan (0.0.0.0), tailnet, or custom (one IPv4 address). The docs specifically recommend the tailnet mode here: "Use gateway.bind: \"tailnet\" to limit non-loopback exposure to the Tailnet while retaining the required same-host 127.0.0.1 listener."

Edit ~/.openclaw/openclaw.json and set:

{
  "gateway": {
    "bind": "tailnet",
    "port": 18789
  }
}

#Step 8: Your First Interaction

With everything set up, it is time to talk to your agent. Open your configured messaging channel (e.g., Telegram) and send a message:

Hey, are you there?

Your agent should respond within a few seconds, drawing on its SOUL.md personality and any installed skills. Try a few things:

• Ask a question: "What's the weather forecast for today?"
• Give a task: "Remind me to call the dentist tomorrow at 2pm"
• Test a skill: "Summarize the top stories on Hacker News"

#Essential CLI Commands Reference

Here is a quick reference of the most important openclaw commands you will use day to day:

openclaw automations is an alias: the command "registers as openclaw cron with openclaw automations as an alias".

#Post-Installation Checklist

Before you consider your setup complete, verify each of these items:

• macOS sleep is disabled and auto-restart on power failure is enabled
• Node.js 24.16+ or 26.1+ is installed and on your PATH
• OpenClaw is installed and the onboarding wizard is complete
• At least one LLM provider API key is configured
• At least one messaging channel is connected
• macOS permissions (Full Disk Access, Accessibility) are granted
• The daemon is installed and running (openclaw health shows healthy)
• Remote access is configured (Tailscale + SSH)
• You have successfully sent and received a message with your agent

#Next Steps

With your Mac Mini running OpenClaw, explore these guides to get the most out of your agent:

• API Key Setup & Model Configuration: fine-tune which models your agent uses and when
• Messaging Channels: connect additional platforms like Discord, Slack, or WhatsApp
• Security Hardening: lock down your agent for production use
• Understanding Skills: learn how to extend your agent with skills from ClawHub
• SOUL.md Mastery: refine your agent's personality
• Cost Optimization: keep your API bills under control
• Heartbeat & Cron Configuration: schedule recurring tasks

#Frequently Asked Questions

#Can I use an older Mac Mini?

The docs list macOS as a supported platform without naming a minimum OS version, so the binding constraint in practice is Node: the install docs require "Node 24.16+ or 26.1+". If your Mini can run a supported Node build, it can host the Gateway. The M4 still offers the best performance-per-watt for an always-on box.

#How much bandwidth does OpenClaw use?

The docs publish no bandwidth figure, so we will not invent one. The Gateway talks to LLM APIs over JSON, which is cheap; what actually moves the needle is skills that download or upload files. Measure your own host for a week rather than budgeting from a number you read somewhere.

#Can I run OpenClaw alongside other services?

Absolutely. The Mac Mini M4 has plenty of headroom. Many users run Home Assistant, Plex, Pi-hole, and development servers alongside OpenClaw without any issues.

#What happens during a power outage?

If you enabled Start up automatically after a power failure in System Settings and installed the managed service with openclaw gateway install, your Mac Mini will boot up and OpenClaw will start automatically when power returns. You may want to invest in a small UPS for graceful handling.

#How do I update OpenClaw?

Run openclaw update, documented as "Update OpenClaw and switch between stable/extended-stable/beta/dev channels." It restarts the Gateway service after a successful update unless you pass --no-restart, and package-manager updates that do restart "verify the restarted service reports the expected version before the command succeeds." Use --dry-run to preview the planned actions first. Always check the release notes before updating, as some versions may require configuration changes.