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.
What the macOS App Actually Does
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.
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.
Step 2: Local vs Remote Mode
Two operating modes:
- Local mode (default): The app manages a Gateway running on your Mac via launchd. Starts automatically on login, runs in background, restarts on crash.
- Remote mode: The app connects to a Gateway on a different machine (VPS, Pi, home server). The app starts a local node host service so the remote Gateway can reach your Mac's tools.
For most people: use Local mode. Switch to Remote only when you need a persistent agent running 24/7 regardless of whether your Mac is on.
launchctl kickstart -k gui/$UID/ai.openclaw.gateway # restart
launchctl bootout gui/$UID/ai.openclaw.gateway # stop
Or manage via the CLI: openclaw gateway start / openclaw gateway stop.
Step 3: Configure Your State Directory (Critical)
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. openclaw doctor will warn you if it detects a cloud-synced state path.
Step 4: The Menu Bar — What You're Looking At
The menu bar icon tells you what your agent is doing in real time:
- Idle critter: Gateway running, agent idle, health OK
- 💻 badge: Agent running an exec command
- 📄 badge: Reading a file
- ✍️ badge: Writing a file
- 📝 badge: Making edits
- 🛠️ badge: Using any other tool
The status row shows which session is active: Main · exec: pnpm test or Other · read: src/app.ts. Main session always takes priority.
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. Configure an allowlist at ~/.openclaw/exec-approvals.json:
{
"version": 1,
"defaults": {
"security": "deny",
"ask": "on-miss"
},
"agents": {
"main": {
"security": "allowlist",
"ask": "on-miss",
"allowlist": [
{ "pattern": "/opt/homebrew/bin/git" },
{ "pattern": "/opt/homebrew/bin/node" },
{ "pattern": "/usr/bin/env" },
{ "pattern": "/bin/zsh" }
]
}
}
}
Build this organically: when the approval prompt appears, click "Always Allow" and OpenClaw adds that binary automatically. After a week, you'll have a clean allowlist covering your actual workflow.
Important: Shell commands with control operators (&&, ||, ;, |) or expansions ($, backticks) always require explicit approval, regardless of the base command.
Step 6: macOS Capabilities Your Agent Gets
This is where macOS really shines as an OpenClaw platform.
Canvas
A persistent WebView your agent can control — navigate to URLs, inject JavaScript, take visual snapshots, and interact with rendered UIs.
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 and analyze them. Useful for reading physical documents, monitoring a space, or any workflow needing visual input.
Screen Recording
Record your screen — useful for creating demos, capturing bugs, or analyzing app behavior. Requires Screen Recording permission in System Settings.
Voice
Wake-word activation and push-to-talk. Configure a wake phrase and your agent listens passively. Push-to-talk lets you hold a hotkey and speak directly.
The voice overlay shows transcribed text in real time. 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.
Recovery process:
- Quit OpenClaw.app completely
- System Settings → Privacy & Security → find OpenClaw → remove from relevant categories
- Relaunch from
/Applications/OpenClaw.app(exact path matters) - Re-grant permissions when prompted
- If prompts don't appear, reset with
tccutil:
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.
Non-obvious issue: If your agent reads/writes files in Desktop, Documents, or Downloads, macOS may gate access. Keep files in ~/.openclaw/workspace to avoid per-folder grants.
Step 8: Deep Links for Automation
OpenClaw registers the openclaw:// URL scheme — trigger agent actions from Shortcuts, scripts, Alfred, Raycast, or any app:
open 'openclaw://agent?message=Good%20morning%2C%20what%27s%20on%20the%20agenda%3F'
For unattended automation (cron jobs, Shortcuts), generate a key in app settings:
open 'openclaw://agent?message=Run%20daily%20standup&key=YOUR_KEY_HERE'
Wire OpenClaw into macOS-native automation — morning briefings from a Shortcut, triggers from keyboard shortcuts, integration with other apps.
Common Optimization Tips
Let launchd manage the Gateway. Don't start it manually. The LaunchAgent handles start-on-login, restart-on-crash, and the macOS app shows status. Manual start + LaunchAgent = connection errors.
Use the CLI for debugging:
cd apps/macos
swift run openclaw-mac connect --json
swift run openclaw-mac discover --timeout 3000 --json
Keep your workspace local. ~/.openclaw/workspace is where your agent reads and writes context files — SOUL.md, MEMORY.md, AGENTS.md. If you want backup, use git. Not live cloud sync.
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 messages in Slack, Telegram, iMessage, or wherever
- 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 TCC grants
- Runs shell commands with your configured allowlist
- Stores all memory and context locally — no cloud sync, no latency
This is what it means to have an AI agent that runs like a real employee — always on, aware of its environment, and integrated into your actual workflow.
Originally published at openclawplaybook.ai. Get The OpenClaw Playbook — $9.99.
Top comments (0)