OpenClaw for macOS

Native macOS menu bar companion app. Owns TCC permissions, manages/attaches to the Gateway, exposes macOS-only tools (Canvas, Camera, Screen Recording, system.run).

The macOS app is the definitive OpenClaw companion — a native menu bar application that acts as the bridge between your Mac's capabilities and the OpenClaw Gateway. Unlike channel-based interactions (Telegram, Discord), the macOS app gives your agent direct access to macOS-specific tools: Canvas for rendering live UI, Camera for snapshots and clips, Screen Recording for visual context, and system.run for executing commands in the macOS UI context with full TCC (Transparency, Consent, and Control) permission handling. The app operates in two modes. In Local mode (default), it attaches to a Gateway running on the same machine — either detecting an existing process or installing a launchd LaunchAgent (ai.openclaw.gateway) to manage it automatically. In Remote mode, it connects to a Gateway running elsewhere (a Linux server, a VPS, another Mac) over SSH or Tailscale, while starting a local node host service so the remote Gateway can reach back to invoke macOS capabilities. One of the most powerful features is system.run, which executes commands in the app's UI/TCC context via a local Unix socket with HMAC+TTL authentication. This means your agent can run AppleScript, control apps via Accessibility APIs, and interact with macOS in ways that a headless process never could. Exec approvals are configurable per-agent with allowlist patterns, providing granular security control. The app also hosts PeekabooBridge for UI automation and manages the global CLI installation. It handles all the permission prompts (Notifications, Accessibility, Screen Recording, Microphone, Speech Recognition, Automation/AppleScript) so the agent has the access it needs without manual fiddling.

Tags: native, desktop, menu-bar, launchd

Use Cases

  • Hands-free computer control via voice wake and Talk mode — ask your agent to open apps, search files, or run scripts
  • Visual AI assistant — agent can take screen snapshots to understand what you're looking at and offer contextual help
  • Automated workflow orchestration — schedule cron jobs that use system.run to control macOS apps (mail, calendar, browsers)
  • Development companion — agent monitors your screen, reads code context, and provides suggestions without switching windows
  • Remote Mac administration — connect from a Linux Gateway over Tailscale to run diagnostics or capture screen state on a headless Mac

Tips

  • Use 'openclaw gateway install' to set up the launchd service if the app doesn't detect an existing Gateway
  • For remote setups, Tailscale is strongly recommended over manual SSH tunnels — it handles NAT traversal and encryption automatically
  • Configure exec approvals in Settings → Exec approvals to allowlist frequently-used commands and avoid repeated approval prompts
  • Check 'openclaw nodes status' to verify the macOS node is connected and reporting capabilities correctly
  • Use profiles (--profile <name>) to run multiple isolated OpenClaw instances on the same Mac for different projects
  • Canvas capabilities pair well with the macOS app — agents can render interactive dashboards, charts, and web views directly on your Mac

Known Issues & Gotchas

  • TCC permissions (Screen Recording, Accessibility, Microphone) must be granted manually in System Settings — the app can prompt but macOS requires user confirmation
  • In local mode, the app manages a launchd LaunchAgent — if you also run the Gateway manually, you may get port conflicts on 18789
  • system.run commands with shell operators (&&, ||, |, ;) are treated as allowlist misses and require explicit approval even if the binary is allowlisted
  • Bun is not recommended as the Gateway runtime when using the macOS app — stick with Node.js
  • Legacy com.openclaw.* LaunchAgent labels may conflict with the new ai.openclaw.* labels during upgrades — the app handles migration but check with launchctl list if things seem stuck
  • Environment overrides in system.run are filtered for security — PATH, DYLD_*, NODE_OPTIONS are dropped automatically

Community Feedback

The macOS app is what makes OpenClaw click. Without it, you're just chatting with an LLM. With it, the agent can actually see your screen, snap photos, and run commands.

— Reddit r/selfhosted

Getting TCC permissions right was a pain at first — had to go to System Settings and manually toggle Screen Recording and Accessibility for the OpenClaw app.

— Reddit r/LocalLLaMA

Remote mode over Tailscale is brilliant. I have the Gateway on my always-on Linux box and the macOS app on my laptop. Agent can use my Mac's camera and screen even when I'm not at my desk.

— Reddit r/OpenClawInstall

Frequently Asked Questions

How do I grant Screen Recording permission to the OpenClaw macOS app?

Go to System Settings → Privacy & Security → Screen Recording, then toggle on the OpenClaw app. You may need to restart the app after granting the permission. The app will prompt you when it first needs the capability.

Can I run the macOS app without a local Gateway?

Yes — use Remote mode to connect to a Gateway running on another machine (Linux server, VPS, another Mac). The macOS app starts a local node host service so the remote Gateway can invoke macOS capabilities like Camera and Screen Recording.

What is system.run and is it safe?

system.run lets the agent execute commands in the macOS app's UI context with TCC permissions. It's secured via local Unix socket with HMAC+TTL authentication, and you control access through exec approvals — allowlists, per-agent security policies, and interactive approval prompts.

How do I fix Gateway port conflicts?

If you see port 18789 already in use, check for duplicate processes: 'lsof -i :18789'. The app manages a launchd service — use 'launchctl bootout gui/$UID/ai.openclaw.gateway' to stop it, then let the app manage it cleanly.

Does the macOS app work with Apple Silicon and Intel Macs?

Yes, the Homebrew Cask installs a universal binary that runs natively on both Apple Silicon (M1/M2/M3/M4) and Intel Macs. macOS 13 Ventura or later is required.

Can I use multiple profiles on the same Mac?

Yes, use the --profile flag to isolate state under ~/.openclaw-<name>. Each profile gets its own LaunchAgent (ai.openclaw.<profile>), config, and workspace. Useful for separating work and personal setups.

Installation

brew install --cask openclaw