OpenClaw on macOS: The Complete Setup and Optimization Guide

macOS is the best platform for running OpenClaw. You get a native menu bar companion, system-level integrations, voice wake-word, Canvas for visual output, camera access, and screen recording — all tightly wired to your AI agent. But the setup has a few non-obvious steps, and the wrong choices early on (iCloud sync, ad-hoc signing, scattered installs) will cause subtle headaches for months.

This is the guide I wish existed when I first set up OpenClaw on macOS. Everything from first install to a fully optimized daily-driver configuration.

What the macOS App Actually Does

First, a mental model shift. The OpenClaw macOS app is not the agent. It's the companion that manages the agent's relationship with your Mac.

Specifically, the macOS app:

• Owns all TCC permission prompts (Notifications, Accessibility, Screen Recording, Microphone, Camera, AppleScript)
• Manages the Gateway process — either running it locally via launchd or connecting to a remote Gateway over SSH
• Exposes macOS-specific tools to your agent: Canvas, camera, screen recording, system.run
• Shows agent activity in the menu bar with live status glyphs
• Handles the Browser Relay so your agent can control Chrome tabs

The Gateway is the actual engine — the WebSocket server that routes messages between your channels (Slack, Telegram, iMessage, etc.) and the AI model. The macOS app either spawns it or attaches to it. The agent runs inside the Gateway.

Step 1: Install the App Correctly

Download OpenClaw.app from openclaw.ai and put it in /Applications. That's not optional — it matters for TCC permission stability.

macOS associates permission grants with your app's code signature, bundle identifier, and on-disk path. Move the app after granting permissions and macOS may silently revoke them. This is a macOS TCC quirk that bites a lot of people.

After launching the app for the first time, it runs through a permissions checklist. Grant everything it asks for — you can always revoke individual permissions later from System Settings. Skipping permissions now means your agent will silently fail on tools that require them.

Step 2: Understand Local vs Remote Mode

The macOS app has two operating modes:

• Local mode (default): The app manages a Gateway running on your Mac via launchd. The Gateway starts automatically on login, runs in the background, and restarts if it crashes.
• Remote mode: The app connects to a Gateway on a different machine (a VPS, a Raspberry Pi, your home server). In this mode, the app starts a local node host service so the remote Gateway can reach your Mac's tools — camera, screen recording, Canvas, voice.

For most people starting out: use Local mode. It's simpler, has no networking complexity, and your agent has full access to your Mac's capabilities. Switch to Remote only when you need a persistent agent that runs 24/7 regardless of whether your Mac is on.

In Local mode, the Gateway is installed as a LaunchAgent:

launchctl kickstart -k gui/$UID/ai.openclaw.gateway   # restart
launchctl bootout gui/$UID/ai.openclaw.gateway         # stop

You can also manage it via the menu bar app or the CLI: openclaw gateway start / openclaw gateway stop.

Step 3: Configure Your State Directory (Critical)

This is the most commonly skipped step and causes the most subtle problems. Set your OpenClaw state directory to a local, non-synced path:

OPENCLAW_STATE_DIR=~/.openclaw

Do not put it in:

• ~/Library/Mobile Documents/com~apple~CloudDocs/... (iCloud Drive)
• ~/Library/CloudStorage/... (any cloud-synced folder)
• A Dropbox or OneDrive-synced folder

OpenClaw's state directory contains session files, credentials, and memory that get written frequently. Cloud sync introduces file-lock races and latency that cause sessions to corrupt or lose data mid-conversation. openclaw doctor will warn you if it detects a cloud-synced state path — if you see that warning, move your state directory before doing anything else.

The CLI is installed separately. If you want terminal access to your agent:

openclaw install-cli

Or trigger it from the macOS app's preferences. This installs the openclaw global command via npm. The app recommends npm or pnpm — avoid bun for the Gateway runtime, it has compatibility issues.

Step 4: The Menu Bar — What You're Looking At

The menu bar icon tells you what your agent is doing in real time. The critter in your menu bar changes state based on activity:

• Idle critter: Gateway is running, agent is idle, health is OK
• 💻 badge: Agent is running an exec command
• 📄 badge: Agent is reading a file
• ✍️ badge: Agent is writing a file
• 📝 badge: Agent is making edits
• 🛠️ badge: Agent is using any other tool

The status row shows which session is active and what it's doing: Main · exec: pnpm test or Other · read: src/app.ts. The main session always takes priority — if main is active, that's what you see. Sub-agents show as "Other" when your main session is idle.

Health status (Gateway connectivity, model availability) shows when the agent is idle and disappears when there's work happening. This is intentional — you don't need connectivity noise while the agent is mid-task.

Step 5: Set Up Exec Approvals

Your agent runs shell commands via system.run. By default, the app prompts for approval on every new command. For a daily-driver setup, you want to configure an allowlist so your agent can run common commands without interrupting you.

Exec approvals are stored at ~/.openclaw/exec-approvals.json. A useful starting config:

{codeBlock1}

You can also build this allowlist organically: when the approval prompt appears, click "Always Allow" and OpenClaw adds that binary to your allowlist automatically. After a week of normal use, you'll have a clean allowlist that covers your actual workflow.

One important behavior: shell commands containing control operators (&&, ||, ;, |) or expansions ($, backticks) always require explicit approval or shell binary allowlisting, regardless of the base command. This is a deliberate safety constraint.

Step 6: macOS Capabilities Your Agent Gets

This is where macOS really shines as an OpenClaw platform. Your agent on macOS gets tools that simply aren't available on other platforms:

Canvas

Canvas is a persistent WebView that your agent can control — navigate to URLs, inject JavaScript, take visual snapshots, and interact with rendered UIs. It's useful for dashboards, visual output, and UI automation without the overhead of a full browser session.

canvas.present  — show the canvas window
canvas.navigate — load a URL
canvas.eval     — run JavaScript in the page
canvas.snapshot — capture a screenshot

Camera

Your agent can take photos from your Mac's camera (or connected cameras) and analyze them. Useful for workflows that need visual input: checking what's on a desk, reading a physical document, monitoring a space.

camera.snap  — take a still photo
camera.clip  — record a short video clip

Screen Recording

The agent can record your screen — useful for creating demos, capturing bugs, or analyzing what's happening in an app. Requires Screen Recording permission to be granted in System Settings.

Voice

The macOS app supports wake-word activation and push-to-talk. Configure a wake phrase, and your agent listens passively and wakes when it hears the phrase. Push-to-talk lets you hold a hotkey and speak directly to your agent without typing.

The voice overlay shows transcribed text in real time. If you trigger push-to-talk while the wake-word overlay is already visible, it adopts the existing text as a prefix — so you don't lose what was already transcribed. Wake-word auto-sends on silence; push-to-talk sends on hotkey release.

Step 7: Permission Troubleshooting

Permissions are the #1 source of macOS OpenClaw issues. Symptoms: tools silently fail, camera returns nothing, screen recording is blank, AppleScript doesn't work.

The recovery process when permissions get stuck:

1. Quit OpenClaw.app completely
2. Go to System Settings → Privacy & Security, find OpenClaw, and remove it from any relevant categories
3. Relaunch from /Applications/OpenClaw.app (exact path matters)
4. Re-grant permissions when prompted
5. If prompts don't appear: reset with tccutil and restart

sudo tccutil reset Accessibility ai.openclaw.mac
sudo tccutil reset ScreenCapture ai.openclaw.mac
sudo tccutil reset AppleEvents

Some permissions only reappear after a full macOS restart — specifically Accessibility and some AppleScript grants. If you're stuck in a loop of granting and losing permissions, a restart usually resolves it.

One non-obvious issue: if your agent reads or writes files in Desktop, Documents, or Downloads, macOS may gate access for the background process. The easiest workaround is keeping files in ~/.openclaw/workspace, which doesn't require per-folder grants.

Step 8: Deep Links for Automation

OpenClaw registers the openclaw:// URL scheme, which lets you trigger agent actions from anywhere on macOS — Shortcuts, scripts, other apps, Alfred, Raycast.

open 'openclaw://agent?message=Good%20morning%2C%20what%27s%20on%20the%20agenda%3F'

Without an authentication key, the app shows a confirmation prompt before sending. For unattended automation (cron jobs, Shortcuts), generate a key in the app settings and pass it as a query parameter:

open 'openclaw://agent?message=Run%20daily%20standup&key=YOUR_KEY_HERE'

This is how you wire OpenClaw into macOS-native automation workflows — morning briefings from a Shortcut, agent triggers from a keyboard shortcut, integration with other apps via URL schemes.

Common Optimization Tips

Let launchd manage the Gateway

Don't start the Gateway manually. Let the LaunchAgent handle it — it starts on login, restarts on crash, and the macOS app shows current status. If you manually start the Gateway and it conflicts with the LaunchAgent, you'll see connection errors.

Use the CLI for debugging

The macOS app has a debug CLI for testing Gateway connectivity without launching the full app:

cd apps/macos
swift run openclaw-mac connect --json
swift run openclaw-mac discover --timeout 3000 --json

Compare against openclaw gateway discover --json to check if the app and CLI see the same gateways — if they differ, it usually points to a discovery or network configuration issue.

Keep your workspace local

Your ~/.openclaw/workspace is where your agent reads and writes context files — SOUL.md, MEMORY.md, AGENTS.md, daily notes. Keep it local. If you want backup, use git to sync it on your own schedule, not a live cloud sync service.

Name your agent properly

Set your agent's name and identity in ~/.openclaw/workspace/SOUL.md and IDENTITY.md. The macOS app surfaces the agent's "main" session as the primary identity in the menu. When you have multiple agents configured, only one is "main" — make sure it's the one you interact with most.

What You End Up With

A properly set up OpenClaw on macOS gives you an AI agent that:

• Starts automatically on login via launchd
• Responds to your messages in Slack, Telegram, iMessage, or wherever you've connected it
• Shows current activity in your menu bar in real time
• Can be triggered by voice, keyboard shortcut, deep link, or cron
• Has access to your camera, screen, and running apps via proper TCC grants
• Runs shell commands with your configured allowlist, no interruptions for known-safe commands
• Stores all memory and context locally — no cloud sync, no latency, no file-lock races

This is what it means to have an AI agent that actually runs like a real employee — always on, aware of its environment, and integrated into your actual workflow instead of living in a browser tab you have to remember to open.

Want the complete guide? Get The OpenClaw Playbook — $9.99