OpenClaw macOS App: Menu Bar Companion and Native Tools

The macOS app serves as OpenClaw's menu bar companion, offering native tray UI, macOS permission prompts, notifications, WebChat, voice input, a hosted-widget panel, and Mac-hosted node tools like system.run.

Quick Chat gives you a Spotlight-style composer for the main session without opening a full window. By default, Option-Space (⌥Space) triggers it, or you can select it from the menu bar menu, or assign a different shortcut in Settings → General.

The full native chat supports image attachments via its picker, paste, and drag and drop. Assistant-generated images display inline through short-lived Gateway artifact URLs and expand into a larger preview; iOS and macOS share the same bounded image model and renderer.

If you only require the CLI and Gateway, begin with Getting started.

Download

You can obtain macOS app builds from OpenClaw GitHub releases. When a release includes macOS app assets, search for:

• OpenClaw-<version>.dmg (preferred)
• OpenClaw-<version>.zip

Some releases contain only CLI, evidence, or Windows assets. If the latest release lacks a macOS app asset, pick the most recent one that has it, or compile from source using macOS dev setup.

First run

1. Install and launch OpenClaw.app.
2. Select This Mac for a local Gateway, or connect to a remote Gateway.
3. For a new local Gateway, wait while the app installs its external CLI runtime and starts the Gateway. Connecting to a remote or independently managed local Gateway does not require installing a CLI on this Mac.
4. Verify inference with a live model check. If the app reused a login you did not want, Choose a different AI on the success banner reopens the picker, including the API-key option.
5. Finish. The app opens the dashboard, where OpenClaw guides the rest of the setup (memory import, channels, permissions) in one conversation. Grant macOS permissions any time from Settings → Permissions.

If the app reaches an existing Gateway whose default agent has a configured model, it treats that Gateway as already set up, skips provider onboarding and OpenClaw, and opens the dashboard. If the Gateway cannot connect or its default agent has no model, inference onboarding remains available for recovery.

For the CLI/Gateway setup path, use Getting started. For permission recovery, use macOS permissions.

Updates

The dashboard update card specifies what the app will update:

• Update Mac app + Gateway means the signed app owns the local launchd Gateway. Sparkle updates the app first; after relaunch, the app automatically updates and restarts its Gateway at the matching version, then verifies the connection.
• Update Gateway means the app is connected to a remote Gateway, a manually managed local Gateway, or another install the app does not own. The button runs that Gateway's normal update flow instead of changing the Mac app.

Either button asks for confirmation first. The card hands the update to the app only after you choose Update Mac app and restart, so a misclick never starts Sparkle.

A failed coordinated update stays in its setup-style window with retry, update guide, and Discord actions. Automatic repair never downgrades a newer Gateway or overrides an extended-stable channel pin.

After a successful update, the app finds the most recently human-used, top-level direct session and gives that agent a one-time update event. Heartbeat and cron activity do not affect this choice. The agent can then welcome you back from the conversation you were most likely using. In remote mode, a separately installed, app-managed node service retains its own runtime update and recovery flow; the app skips the notification when the remote Gateway is older than the app. The app's private node worker updates with the app bundle itself.

Sparkle follows the Gateway's update.channel setting. beta and dev opt in to beta app builds; extended-stable accepts only extended-stable app releases, so it stays quiet when no matching app release exists. stable, missing, and unknown values stay on stable app builds.

Open dashboard links

In the macOS app's embedded dashboard, clicking an external web link opens it in a resizable browser sidebar at half the window width while keeping the dashboard navigation visible. Drag the divider to choose another width; the app remembers it. Each link opens in its own tab, the tab strip appears when multiple pages are open, and clicking the same link again reuses its existing tab. Drag tabs to reorder them, close them with the tab close button or a middle-click, and right-click a tab for Open in Default Browser, Copy Link, Reload, Close Tab, and Close Other Tabs. The window's titlebar back/forward controls and trackpad swipes navigate dashboard history; the sidebar's own back/forward controls navigate the active tab's history. The sidebar also has reload, open-in-default-browser, and close controls.

The titlebar controls follow the app sidebar: while it is expanded, back/forward sit at its right edge next to the sidebar toggle; while it is collapsed, they make way for a search button (opens the command palette) and a new-session button.

Drag the empty header space or title in the docked OpenClaw chat panel to move the app window. Its dock-position and close buttons remain clickable.

Right-click an external link to choose Open in Sidebar, Open in Default Browser, or Copy Link. Modified clicks and user-activated new-window links from the dashboard continue to open in the default browser; new-window links inside the sidebar open as new sidebar tabs. Regular browser-hosted Control UI pages keep the browser's normal link and context-menu behavior.

Import browser logins

The first time the browser sidebar opens while the app runs against a local Gateway, the dashboard shows a dismissible banner when a Chrome-family profile with cookies exists on the Mac. The banner offers to copy those cookies into an isolated managed profile that agents use for browsing. Choose a profile from its Import control (Touch ID may be required); progress and the imported-cookie count appear inline, and only cookies are copied, passwords never leave the source browser. Dismissing the banner records the choice; Settings → General → Browser login → Import… re-offers it at any time. See Browser for the underlying import flow and the browser.allowSystemProfileImport gate.

Sync cookies to a remote computer

Import copies cookies once into a profile on the same Mac. When your Gateway and agent browser run on a separate computer (a dedicated box, a headless Linux host, or a cloud container), turn on cookie sync so this Mac keeps that remote browser signed in to the sites you choose.

Open Settings → General → Cookie sync. It is off by default and only takes effect while the app runs in remote mode. Turn on Sync cookies to the remote computer, add the sites you want kept in sync to the Domains allowlist (for example github.com and accounts.google.com), and set the Target profile that receives them (the managed profile name on the remote Gateway, imported by default). A status row shows whether sync is running.

While enabled, the app supervises the openclaw browser cookie-sync --watch command against the connected Gateway. Cookies are decrypted locally on this Mac (one macOS Keychain or Touch ID prompt per session) and pushed to the remote profile over the app's existing encrypted Gateway connection; only the domains on the allowlist are ever sent, and cookie values are never written to logs. An empty allowlist syncs nothing. As with import, some Google sessions use device-bound session credentials (DBSC) that stay tied to this Mac and may still require re-authentication after sync; for those sites, drive the browser on the Mac itself through the browser node proxy instead.

Choose a Gateway mode

Regardless of the mode, the app's Mac node relies on its bundled private runtime. The separate CLI install is needed only to set up and manage an app-owned local Gateway. That installation is not required for remote mode or for attaching to an independently managed local Gateway. Optional cookie sync still calls for an external CLI on this Mac, and a pre-existing separate node service manages its own CLI lifecycle. For manual recovery, see Gateway on macOS.

What the app owns

• Menu bar status, notifications, health, WebChat, and the floating Quick Chat bar.
• macOS permission prompts for screen, microphone, speech, automation, and accessibility.
• A single Mac node that merges the native widget panel, camera/screen capture, notifications, location, and computer control with the CLI node host's system, browser, plugin, skill, and MCP commands.
• Exec approval prompts for Mac-hosted commands.
• App-context execution for approved shell commands, which keeps the app's macOS permission attribution while the CLI runtime handles shared node policy.
• Remote-mode SSH tunnels or direct Gateway connections.

Within the embedded Control UI, Settings → Notifications displays the app's native notification permission rather than browser push, since the app handles notifications natively.

The app does not replace the Gateway or general CLI documentation. Gateway configuration, providers, plugins, channels, tools, and security are covered in their own docs.

macOS detail pages

Related

• Platforms
• Getting started
• Gateway
• Exec approvals