What is the openclaw gateway install launchctl command?

The openclaw gateway install command sets up a launchd LaunchAgent so the OpenClaw Gateway runs automatically as a background service on macOS. The service is labeled bot.molt.gateway. You can control it with launchctl commands like launchctl kickstart -k gui/$UID/bot.molt.gateway to force restart.

OpenClaw on Mac | Complete macOS Installation Guide (2025)

Q: What are the system requirements for OpenClaw on macOS?

OpenClaw requires macOS 13 Ventura or newer, Node.js 22+, and at least 4 GB of RAM. It runs on both Apple Silicon (M1, M2, M3, M4) and Intel Macs.

Q: Does OpenClaw work on MacBook Air?

Yes, OpenClaw runs on MacBook Air. However, since the MacBook Air is a portable laptop, keeping it running 24/7 leads to battery drain and thermal concerns. It works great for on-demand usage or paired with a VPS for always-on operation.

Q: Can I install OpenClaw on Mac with Homebrew?

OpenClaw is not currently available via Homebrew. The official installation method is the installer script: curl -fsSL https://openclaw.ai/install.sh | bash. Alternatively, you can install via npm: npm install -g openclaw@latest.

Q: Does OpenClaw work on Intel Macs?

Yes, OpenClaw works on Intel Macs running macOS 13 Ventura or newer. Apple Silicon (M-series) Macs will generally have better performance and lower power consumption, but Intel Macs are fully supported.

Q: Should I run OpenClaw on my Mac or on a VPS?

A VPS is recommended for always-on operation because it provides true 24/7 uptime, better security isolation, and doesn't require keeping your Mac running. Running on your Mac is great for testing, development, or using macOS-specific features like voice wake and screen recording. Many users run the Gateway on a VPS and connect their Mac as a remote node.

A note from the author

I run OpenClaw on both a VPS and my Mac. The macOS companion app is genuinely impressive -- voice wake, menu bar integration, and camera/screen access make it feel like a native AI assistant built right into your Mac. That said, if you want true 24/7 uptime, pair it with a VPS and use your Mac as a remote node. It's the best of both worlds.

What's in This Guide

Security Warning: Local Installation Risks

Running OpenClaw locally on your personal computer can pose significant security risks. The AI agent has access to execute commands, read/write files, and interact with your system. A misconfigured setup could expose sensitive data or allow unintended actions.

Data exposure: The agent can read files on your system, including sensitive documents and credentials
System access: Commands executed by the agent run with your user permissions
Network risks: Improperly secured installations could be accessed by others on your network
No isolation: Unlike a VPS, your personal files and data share the same environment

Recommended: Use a VPS Instead

For a safer and more reliable setup, we strongly recommend running OpenClaw on a dedicated VPS. This provides:

Isolation from your personal computer
24/7 uptime without keeping your computer on
Better security with a controlled environment
Easy setup with our step-by-step guide

View VPS Setup Guide

macOS System Requirements

Before installing OpenClaw on your Mac, make sure your system meets these minimum requirements.

macOS Version

macOS 13 Ventura or newer. Sonoma (14) and Sequoia (15) are fully supported.

Processor

Apple Silicon (M1, M2, M3, M4) or Intel. Apple Silicon recommended for better efficiency.

Memory & Storage

Minimum 4 GB RAM. 8 GB+ recommended. Around 500 MB disk space for OpenClaw and dependencies.

Node.js 22+

Required runtime. The installer script will install it for you if it's missing.

Check your Node version: Run node --version in Terminal. If you see v22 or higher, you're good. If Node isn't installed, the OpenClaw installer handles it automatically.

Which Mac Is Best for OpenClaw?

OpenClaw runs on any Mac that meets the requirements above. But some setups work better than others depending on how you plan to use it.

Mac Mini / Mac Studio

Best for always-on local use

Desktop Macs are ideal if you want to run OpenClaw locally 24/7. No battery concerns, low power consumption (especially Apple Silicon Mac Mini), and they can be tucked away running quietly. The Mac Mini is particularly popular as a headless home server.

MacBook Pro

Good for on-demand + remote node

The MacBook Pro handles OpenClaw well thanks to strong sustained performance. It's great for using macOS-specific features like voice wake and screen recording during your work sessions. For 24/7 operation, pair it with a VPS and use your MacBook Pro as a remote node.

MacBook Air

Good for on-demand use

OpenClaw runs fine on MacBook Air for on-demand sessions. Just keep in mind the fanless design means thermal throttling under sustained load, and running 24/7 on battery is not practical. Use it as a remote node connected to a VPS Gateway for the best experience.

iMac / Mac Pro

Works great, perhaps overkill

Any iMac or Mac Pro will handle OpenClaw effortlessly. If you already have one as your daily driver, just install OpenClaw alongside your normal workflow. No special considerations needed.

How to Install OpenClaw on macOS

Follow these steps to get OpenClaw running on your Mac. The entire process takes about 10-15 minutes.

Step 1

Install OpenClaw CLI

Open Terminal.app (or iTerm2) and run the installer script. This downloads the OpenClaw CLI, installs it globally via npm, and handles Node.js detection:

curl -fsSL https://openclaw.ai/install.sh | bash

The script works on both Apple Silicon and Intel Macs. If Node.js 22+ isn't already installed, the script installs it for you.

Step 2

Run the Onboarding Wizard

The onboarding wizard configures authentication, gateway settings, and optional channels (like Telegram, Discord, etc.):

openclaw onboard --install-daemon

The --install-daemon flag also installs the Gateway as a macOS LaunchAgent, so it starts automatically and runs in the background.

Step 3

Verify the Gateway Is Running

Confirm that the OpenClaw Gateway is running:

openclaw gateway status

You can also open the Control UI in your browser to chat directly:

openclaw dashboard

This opens http://127.0.0.1:18789/ in your browser. If it loads, you're all set.

Step 4 (Optional)

Install the macOS Companion App

For the full macOS experience, install the OpenClaw companion app. It lives in your menu bar and adds features you can't get from the CLI alone:

Menu bar status and quick controls
Voice wake word detection (hands-free activation)
Native macOS notifications via Notification Center
Canvas, Camera, and Screen Recording capabilities
TCC permissions management
PeekabooBridge for UI automation

The macOS app can also install the global openclaw CLI for you if you haven't done it via Terminal yet.

Step 5

Grant macOS Permissions

If you installed the companion app, macOS will ask for permissions during the onboarding flow. Grant the ones you want to use:

Notifications -- For alerts and status updates
Accessibility -- For UI automation features
Microphone -- For voice wake word detection
Speech Recognition -- For voice commands
Screen Recording -- For screen capture features
Camera -- For photo and video capture
Automation/AppleScript -- For system automation

Tip: You can skip permissions during onboarding and grant them later in System Settings → Privacy & Security. OpenClaw will prompt again when a feature that requires a permission is used.

Alternative Installation Methods

The installer script is the recommended approach, but you can also install OpenClaw manually on macOS.

Install via npm

If you already have Node.js 22+ installed and prefer managing the install yourself:

npm install -g openclaw@latest

openclaw onboard --install-daemon

Sharp build errors? If you have libvips installed globally via Homebrew and sharp fails, force prebuilt binaries: SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

Install via pnpm

pnpm requires explicit approval for packages with build scripts:

pnpm add -g openclaw@latest

pnpm approve-builds -g

openclaw onboard --install-daemon

What About Homebrew?

OpenClaw is not currently available via Homebrew (brew install openclaw will not work). The official installation method is the installer script or npm. This may change in the future -- check the official install docs for updates.

Build from Source

For contributors or anyone who wants to run from a local checkout:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
pnpm link --global

For the macOS companion app specifically:

cd apps/macos && swift build
swift run OpenClaw

Package the app with: scripts/package-mac-app.sh

The macOS Companion App

The OpenClaw macOS app is a menu-bar companion that manages the Gateway, owns macOS permissions, and exposes Mac-specific capabilities to the AI agent.

What the macOS App Does

Shows native notifications and real-time status in the menu bar
Owns TCC prompts (Notifications, Accessibility, Screen Recording, Microphone, Speech Recognition, Automation/AppleScript, Camera)
Runs or connects to the Gateway (local or remote mode)
Exposes macOS-only tools: Canvas, Camera, Screen Recording, system.run
Optionally hosts PeekabooBridge for UI automation
Can install the global openclaw CLI via npm/pnpm on request

macOS-Specific Features

These features are unique to running OpenClaw on macOS and aren't available on Linux or Windows.

Menu Bar Companion

Native menu bar app showing real-time status, notifications, and quick controls for your OpenClaw Gateway.

Voice Wake

Wake your AI assistant with your voice using macOS Speech Recognition. Hands-free interaction right from your Mac.

Native Notifications

Receive alerts and status updates through macOS Notification Center, just like any native Mac app.

System Integration

Deep macOS integration including AppleScript automation, screen recording, camera access, and Canvas for interactive content.

macOS Permissions (TCC) Explained

macOS uses TCC (Transparency, Consent, and Control) to manage app permissions. Here's what you need to know about OpenClaw's permissions.

How TCC Permissions Work

macOS associates permission grants with the app's code signature, bundle identifier, and on-disk path. If any of these change (like moving the app or updating it), macOS may drop permissions and require re-granting.

For stable permissions:

Run the app from a fixed location
Keep the same bundle identifier
Use a signed app (ad-hoc builds do not persist permissions)

If Permission Prompts Disappear

Sometimes macOS "forgets" to show permission prompts. Follow this recovery checklist:

1. Quit OpenClaw.app
2. Remove the app entry in System Settings → Privacy & Security
3. Relaunch the app from the same path and re-grant permissions
4. If prompts still don't appear, reset TCC entries:

sudo tccutil reset Accessibility bot.molt.mac
sudo tccutil reset ScreenCapture bot.molt.mac
sudo tccutil reset AppleEvents

Some permissions only reappear after a full macOS restart.

Local vs Remote Mode

The macOS app can either manage a local Gateway or connect to a remote one. Understanding the difference helps you decide the best setup.

Local Mode (Default)

The app attaches to a running local Gateway. If none exists, it enables the launchd service via openclaw gateway install. Everything runs on your Mac.

Best for: Running OpenClaw entirely on your Mac.

Remote Mode

Connects to a Gateway over SSH or Tailscale. Never starts a local Gateway process. The app starts a local node host service so the remote Gateway can reach your Mac for macOS-specific features.

Best for: VPS Gateway + Mac as a remote node.

My recommendation: If you want 24/7 uptime, run the Gateway on a VPS and use your Mac in Remote mode. You get the best of both worlds -- always-on AI from the VPS, plus macOS features like voice wake and camera when your Mac is awake. Get a VPS here.

macOS Agent Capabilities

The macOS app presents itself as a "node" to the Gateway, exposing these capabilities to the AI agent.

Canvas

Interactive web canvas for displaying rich content and UI elements.

canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*

Camera

Capture photos or short video clips from your Mac's camera.

camera.snap, camera.clip

Screen

Record screen activity for the agent to reference or analyze.

screen.record

System

Execute commands on your Mac and show native notifications.

system.run, system.notify

The node reports a permissions map so agents can determine what's allowed before attempting an action.

Exec Approvals (system.run Security)

Control what commands the AI agent can execute on your Mac. This is configured in the macOS app under Settings → Exec Approvals.

Configuration Location:

~/.openclaw/exec-approvals.json

Example Configuration:

{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [
        { "pattern": "/opt/homebrew/bin/rg" }
      ]
    }
  }
}

Security Options:

deny -- Block all commands by default
allowlist -- Only allow specific command patterns (glob patterns for resolved binary paths)
ask -- Prompt for each new command (recommended)

Choosing "Always Allow" in a prompt adds that command to your allowlist automatically. Environment overrides are filtered for security (drops PATH, DYLD_*, LD_*, NODE_OPTIONS, etc.).

Deep Links & Automation

The macOS app registers the openclaw:// URL scheme so you can trigger OpenClaw actions from scripts, Shortcuts, or other automation tools.

Send a message to OpenClaw:

open 'openclaw://agent?message=Hello%20from%20automation'

Available parameters:

message (required) -- The message to send
sessionKey -- Target a specific session
channel -- Route to a specific channel
thinking -- Enable thinking mode
timeoutSeconds -- Set a timeout
key -- Unattended mode key (skips confirmation prompt)

Safety: Without a key, the app prompts for confirmation. With a valid key, the run is unattended (intended for personal automations like Shortcuts or cron jobs).

Useful macOS Commands

Quick reference for common OpenClaw commands on macOS.

openclaw statusCheck overall status

openclaw gateway statusCheck gateway status

openclaw gateway installInstall launchd service

openclaw gateway restartRestart gateway

openclaw dashboardOpen Control UI

openclaw doctorDiagnose issues

Launchd Service Control

The Gateway runs as a LaunchAgent labeled bot.molt.gateway. Use these commands for direct launchd control:

launchctl kickstart -k gui/$UID/bot.molt.gateway

Force restart the service

launchctl bootout gui/$UID/bot.molt.gateway

Stop and unload the service

If using a named profile, replace bot.molt.gateway with bot.molt.<profile>.

Limitations of Running OpenClaw on Mac

Before committing to a Mac-only setup, be aware of these trade-offs.

Always-on requirement: Your Mac must stay awake 24/7 for continuous operation. Sleep mode breaks uptime and proactive messaging.
Battery drain on laptops: Running OpenClaw constantly on a MacBook Air or MacBook Pro will drain your battery quickly when not plugged in.
macOS updates: System updates may interrupt the Gateway service and require a restart.
Voice wake needs awake Mac: Voice wake word detection only works when your Mac is awake and not in sleep mode.
No isolation: Unlike a VPS, your personal files share the same environment as the AI agent.

Consider a VPS for true 24/7 operation without keeping your Mac awake.

Get a VPS Learn more about VPS vs Local

Troubleshooting OpenClaw on macOS

Common issues and their solutions when running OpenClaw on Mac.

"openclaw: command not found"

Your shell can't find the global npm binary. Add the npm global bin directory to your PATH:

export PATH="$(npm prefix -g)/bin:$PATH"

Add this line to your ~/.zshrc (or ~/.bashrc) and restart your terminal.

Gateway Not Starting

Run the built-in diagnostic tool to identify config issues:

openclaw doctor

You can also try running the Gateway in the foreground to see errors directly:

openclaw gateway --port 18789

Sharp Build Errors During Install

If you have libvips installed globally via Homebrew and see sharp compilation errors:

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

If you see "Please add node-gyp to your dependencies", install Xcode Command Line Tools and node-gyp:

xcode-select --install

npm install -g node-gyp

Files & Folders Permission Issues

macOS may gate access to Desktop, Documents, and Downloads for background processes. If file reads hang or fail, move files into the OpenClaw workspace:

~/.openclaw/workspace

Or grant Full Disk Access to Terminal / the OpenClaw.app in System Settings → Privacy & Security.

Environment Variables

If you need custom config or state locations, set these environment variables:

OPENCLAW_HOME -- Sets the home directory for internal path resolution
OPENCLAW_STATE_DIR -- Overrides the state directory
OPENCLAW_CONFIG_PATH -- Overrides the config file path

Frequently Asked Questions

Common questions about running OpenClaw on macOS.

What are the system requirements for OpenClaw on macOS?

You need macOS 13 Ventura or newer, Node.js 22+, and at least 4 GB of RAM. OpenClaw runs on both Apple Silicon (M1, M2, M3, M4) and Intel Macs. The installer script handles Node.js installation if it's missing.

Does OpenClaw work on MacBook Air?

Yes. OpenClaw runs on MacBook Air without issues for on-demand use. The fanless design means you might see thermal throttling under sustained heavy load, and keeping it running 24/7 on battery is not practical. For always-on operation, use a VPS for the Gateway and your MacBook Air as a remote node.

Can I install OpenClaw on Mac with Homebrew?

Not currently. brew install openclaw is not available. The official installation method is the installer script (curl -fsSL https://openclaw.ai/install.sh | bash) or npm (npm install -g openclaw@latest). Check the official install docs for updates on Homebrew support.

Does OpenClaw work on Intel Macs?

Yes. OpenClaw fully supports Intel Macs running macOS 13 Ventura or newer. Apple Silicon Macs will generally have better performance and lower power consumption, but Intel Macs are a solid option.

What does "openclaw gateway install" do on macOS?

It sets up a launchd LaunchAgent so the OpenClaw Gateway runs automatically as a background service on your Mac. The service is labeled bot.molt.gateway. You can control it with launchctl kickstart -k gui/$UID/bot.molt.gateway (force restart) or launchctl bootout gui/$UID/bot.molt.gateway (stop).

Should I run OpenClaw on my Mac or on a VPS?

It depends on your use case. A VPS is recommended for always-on 24/7 operation because it provides true uptime, better security isolation, and doesn't require keeping your Mac running. Running on your Mac is great for testing, development, or leveraging macOS-specific features like voice wake and screen recording. The ideal setup for many users is a VPS Gateway with the Mac as a remote node. Get a VPS here.

Is there a macOS app or is it CLI only?

Both. OpenClaw has a CLI that runs in Terminal and a native macOS companion app that lives in your menu bar. The CLI is sufficient for most operations. The companion app adds voice wake, native notifications, camera/screen access, and a visual menu bar interface. You can use either or both.

Want 24/7 Uptime Instead?

Your Mac sleeps, but a VPS doesn't. Get true always-on AI assistance without keeping your Mac running around the clock.

Get a VPS VPS Setup Guide All Installation Methods