macOS App Guide

The OpenClaw macOS app is not the whole engine. It is the cockpit. The Gateway still does the heavy lifting, but the app gives you the menu bar controls, Apple permissions, native notifications, and Mac-only capabilities that are painful to manage by hand.

That distinction matters. A lot of setup confusion comes from expecting the app to be a self-contained desktop bundle. It is closer to a control tower for your local or remote OpenClaw setup.

What the macOS app actually does

• Shows OpenClaw status in the menu bar
• Owns sensitive macOS permission prompts like Accessibility, Screen Recording, Microphone, and Automation
• Runs or attaches to a local Gateway in Local mode
• Connects to a remote Gateway over SSH or direct ws and wss in Remote mode
• Exposes this Mac as a node for Canvas, camera, screen tools, notifications, and system.run

What you need before you start

• A Mac with the OpenClaw app installed
• Node 24 recommended, or Node 22.16+ for compatibility
• A global openclaw CLI install for Local mode
• About 10 to 15 minutes
• Patience for macOS permission prompts, because Apple never misses a chance to be dramatic

Step 1: Install the CLI for Local mode

The app no longer bundles Node or the Gateway runtime. If you want the Mac to run OpenClaw locally, install the CLI first.

npm install -g openclaw@latest
openclaw --version

You can also use the app's Install CLI button. Under the hood it prefers npm first, then pnpm, then bun. If the app later warns about version compatibility, update the CLI so it matches the app version.

Step 2: Choose Local or Remote mode

This is the first fork in the road.

Local mode

Use this when the Mac itself should run or attach to the Gateway. The app can enable the per-user launchd service automatically if no local Gateway is already running.

Remote mode

Use this when the real Gateway lives on a server, another desktop, or a home box. The Mac app becomes a remote control and a local node. By default it uses an SSH tunnel, but direct ws or wss also works when you already expose the Gateway safely.

Step 3: Let the app manage the Gateway on macOS

In Local mode, the app manages a per-user LaunchAgent. If OpenClaw is already running on the configured port, the app attaches instead of starting a duplicate process.

# Install or refresh the launchd service
openclaw gateway install

# Kick the service
launchctl kickstart -k gui/$UID/ai.openclaw.gateway

# Stop the service
launchctl bootout gui/$UID/ai.openclaw.gateway

Useful log path:

/tmp/openclaw/openclaw-gateway.log

Step 4: Handle macOS permissions before they bite you later

This is the part people skip, then regret. The app owns TCC prompts for things like Accessibility, Screen Recording, Microphone, Speech Recognition, Notifications, and AppleScript automation.

Think of TCC like a nightclub bouncer with a clipboard. If your app path, bundle ID, or code signature changes, your old stamp may stop counting. macOS then acts like it has never seen you before.

Rules for stable permissions

• Run the app from a stable path
• Keep the same bundle identifier
• Use a consistent real signature if you are testing signed builds
• Avoid treating ad-hoc builds like production installs

When prompts disappear

1. Quit the app
2. Remove its entries in System Settings under Privacy & Security
3. Launch it again from the same path
4. If needed, reset the relevant TCC category and retry

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

Step 5: Keep your state out of iCloud

Do not put your OpenClaw state directory inside iCloud Drive or another sync-first folder. Sessions and credentials hate sync races.

OPENCLAW_STATE_DIR=~/.openclaw

If you notice strange file locks, lag, or missing state, this is one of the first things worth checking.

Step 6: Configure Remote mode if your Gateway lives elsewhere

Remote mode is where the macOS app starts to feel like a proper control surface. You keep your heavy runtime on a server, but still use the Mac for permissions, UI, notifications, and node features.

Remote prerequisites

• A working remote OpenClaw CLI
• SSH access with key auth
• A stable remote path and CLI on PATH for non-interactive shells
• A healthy Gateway on the remote host

Common remote setup flow

1. Open Settings → General in the macOS app
2. Choose Remote over SSH
3. Set the SSH target like user@host or user@host:port
4. Pick SSH tunnel or direct ws and wss transport
5. Run Test remote

One subtle detail: in SSH tunnel mode, the Gateway sees this Mac as 127.0.0.1. That is expected. If you need the real client IP to appear, use direct ws or wss instead.

Step 7: Verify health from the menu bar

The menu bar is not just decoration. Use it.

• Green dot → linked and recently healthy
• Orange dot → connecting or retrying
• Red dot → logged out, disconnected, or probe failed

You can also run a CLI smoke test if the UI feels vague.

openclaw status
openclaw status --deep
openclaw health --json

Mac-specific capabilities you unlock

Once paired properly, the Mac app is more than a status tray.

• Canvas: render local UI, snapshots, and evaluation flows
• Camera: capture images or clips
• Screen tools: screenshots and screen recording
• System actions: notifications and approved local command execution with system.run

This is where the app stops being a convenience layer and starts becoming part of the agent system itself.

Troubleshooting

The app says the CLI is missing

Install the global CLI and confirm it is on PATH for the same shell context the app relies on. In Remote mode, exit 127 usually means the remote host cannot find openclaw.

Permissions keep resetting

Check whether the app path changed, the signature changed, or you are testing ad-hoc builds. Those three cause most permission drama.

Dashboard works but Mac capabilities stay offline

That usually means the control connection is fine but the Mac node connection is not. Check pairing, node status, and whether the needed permission surface is still granted.

File access hangs in Desktop or Documents

macOS may block folder access for the exact process context doing the work. Move files into ~/.openclaw/workspace if you want fewer surprises.

Best practices

• Use Local mode when you want the simplest single-machine setup
• Use Remote mode when uptime matters more than laptop convenience
• Keep state local, not in cloud-synced folders
• Do not ignore menu bar health colors
• Treat macOS permissions as part of setup, not an afterthought

Summary

The OpenClaw macOS app is best understood as a companion, not a magic box. It handles the messy Mac-native parts, gives you a clean control surface, and can turn your Mac into a capable node for automation, media, and UI work.

If you set up the CLI cleanly, choose the right mode early, and keep permissions stable, the whole thing becomes pleasantly boring. On macOS, that counts as a small miracle.