How to Connect OpenClaw to macOS

The macOS app is the menu-bar companion for OpenClaw. It owns the Mac permission prompts, manages or attaches to the gateway locally, and exposes Mac-specific capabilities back to the agent as a node. That makes macOS a little different from the mobile apps: it is both an operator surface and a capability surface, so getting the mode right matters.

When this is the right move

Use the macOS app when your main machine is a Mac and you want a first-party operator experience, or when a remote gateway should still be able to use this Mac for Canvas, screen capture, camera, or tightly approved system.run tasks. It is especially useful when you want the node and the human operator to share the same desktop context.

The practical workflow

1. Install and launch the macOS app, then work through the permission checklist instead of skipping the TCC prompts and hoping tools will work later.
2. Pick the right run mode. Local mode attaches to a local gateway or enables the launchd service. Remote mode connects to another gateway over SSH or Tailscale and starts the local node host service instead.
3. If you want terminal access too, install the global openclaw CLI from the app's flow rather than mixing tools from different runtimes casually.
4. Review Exec approvals before the first serious system.run task so your trust boundary on the Mac is explicit.
5. Verify the menu-bar status, chat access, and one node capability such as Canvas or screen snapshot before you depend on the Mac in a real workflow.

Grounded command or config pattern

The docs show launchd control for the local gateway service and use openclaw gateway install when the LaunchAgent is not present.

openclaw gateway install

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

In remote mode, the app does not spawn the gateway as a child process. It connects to another gateway and runs the local node host service so the remote gateway can still reach this Mac. That difference is easy to miss and explains a lot of “why didn't the gateway start?” confusion.

Operator notes

The macOS app exposes node commands for Canvas, camera, screen recording, notifications, and system.run. It also keeps exec approvals local to the Mac, which is the correct place for that policy to live. The docs additionally warn against storing your OpenClaw state dir inside iCloud or other cloud-synced paths because sync and file locking can create avoidable state drift and latency.

Rollout approach

For connecting OpenClaw to macOS, I would make the first pass deliberately small: one mode, one Mac, one operator, and one capability test. The Mac app touches permissions, launchd, chat, and node surfaces, so forcing all of them to change at once is where a good setup becomes harder than it needs to be.

Common mistake

The common mistake is treating the command or config key as the whole feature. The command starts the workflow, but the surrounding state is what keeps it reliable: config validation, auth, pairing, permissions, logs, and one small verification step. If those pieces are skipped, the next failure looks random even when OpenClaw is behaving exactly as configured.

Maintenance rhythm

Once this is working, write down the exact command, config path, or approval decision you used. Future you will not remember the tiny detail that made the setup safe. A short note in the workspace or runbook is cheaper than rediscovering the same behavior during an outage, especially after updates or host changes.

Safety checks

Keep your state on a local non-synced path, and do not broad-allowlist shell access just because a single task needs system.run. If you use remote mode, make sure you understand that the gateway state still lives on the remote host. The Mac is a capability provider in that path, not the source of truth for sessions and auth.

How to verify it worked

The quick user-facing check is a healthy menu-bar status and a working chat view. The deeper check is one successful node capability and, if needed, the documented macOS debug CLI against the same connection path. If the UI looks alive but tools fail, revisit permissions and exec approvals before touching routing or model settings.

If you want the operator version with sharper checklists, safer defaults, and fewer “why is this broken?” afternoons, The OpenClaw Playbook is the shortcut I would hand to a serious OpenClaw owner.