macOS app

The macOS app is the OpenClaw menu bar companion: native tray UI, macOS permission prompts, notifications, WebChat, voice input, a hosted-widget panel, and Mac-hosted node tools such as system.run.

Use Quick Chat for a Spotlight-style main-session composer without opening a full window. Press Option-Space (⌥Space) by default, choose it from the menu bar menu, or record another shortcut in Dashboard → Settings → This Mac → App.

Use the green window button to enter native full screen. The Dashboard's sidebar and chat controls remain available at the top of the window. Leaving full screen restores the normal titlebar and window controls.

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

Only need the CLI and Gateway? Start with Getting started.

Requirements

OpenClaw.app requires macOS 15.0 (Sequoia) or later. This also applies to its native openclaw-mac helper. Voice Wake and push-to-talk require macOS 26 or later.

The Node-based CLI and Gateway need a supported Node version on an operating system supported by that runtime. Official Node 24 and Node 26 macOS binaries require macOS 13.5 or later. Running the CLI on an older Mac does not make the native app compatible with that macOS version.

Building from source also requires the toolchain listed in macOS developer setup.

Download

Get macOS app builds from OpenClaw GitHub releases. When a release ships macOS app assets, look for:

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

Some releases only ship CLI, evidence, or Windows assets. If the newest release has no macOS app asset, use the newest one that does, or build from source with macOS dev setup.

First run

1. Install and launch OpenClaw.app.
2. Pick This Mac for a local Gateway, or Connect to an existing Gateway to enter its address and sign in. A saved Gateway opens its dashboard after connection and completes first-run setup without changing the Mac's primary Gateway. Continue below when setting up a new 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. Choose the AI connection you want. Detection only presents available connections; selecting one starts its live model check. An existing configured route appears as Current model.
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 Dashboard → Settings → This Mac → Permissions.

During onboarding, an existing Gateway's configured model also waits for your selection before its live check. A successful check opens the normal dashboard and preserves the configured route. If the Gateway cannot connect or its default agent has no model, inference onboarding remains available for recovery. Normal app launches after onboarding continue to use the saved Gateway.

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

To add another Gateway for dashboard and chat access, open Connection… → Gateways → Add Gateway and enter its hostname or HTTPS address. Cloudflare Access Gateways let you sign in with your personal account in the default browser. You can also start from Get the apps → Open in Mac app on the Gateway's website. See browser sign-in.

Choose Settings… from the menu bar or press Cmd-, to open Dashboard settings. This Mac contains app preferences, local capabilities, browser login import, cookie sync, and permissions. Device voice controls appear under Settings → Talk → This Mac, and app update preferences under Settings → Updates → This Mac. These device controls appear only in the macOS app's embedded Dashboard, not in an ordinary browser.

Enabling sensitive capabilities opens a native confirmation with Cancel as the default. Closing or replacing the Dashboard page cancels pending consent; request the change again from the current page.

Connection

Choose Connection… to open the small native window even when the Gateway is unreachable. Its Connection tab contains local Gateway status, remote/SSH options, Tailscale, and discovery; Gateways manages saved Gateway profiles. A Debug tab appears while the developer toggle in This Mac → Developer is enabled. About OpenClaw opens the standard macOS About panel with the app version, build information, and credits.

If the app-managed local Gateway is missing, outdated, or broken, the Connection tab offers Install Gateway, Update Gateway, or Repair Gateway. The action opens the existing setup prompt, shows installation progress, and checks the Gateway afterward. You can retry here after cancelling an earlier prompt. For an incompatible Gateway newer than the app, Set Up Gateway lets you review the setup choice. Independently managed Gateways retain their own update workflow.

App-local settings (permissions, Quick Chat, voice, updates) live in Dashboard → Settings → This Mac and require a Gateway release that includes those pages. The Connection tab's Open Dashboard Settings button opens that Dashboard.

Updates

Open Dashboard → Settings → Updates → This Mac to turn automatic app updates on or off, choose Check for Updates…, and see the installed app version and build. The page explains when updates are unavailable, including while a named app profile is active.

If the primary Gateway connection rejects the app's protocol version, the app shows an update alert and keeps the explanation in its connection status. Remote setup and connection probes show the same guidance inline. The message names the app release and both protocol versions, and tells you which side needs updating: run openclaw update on an older Gateway host, or install a newer Mac app from the download options. A rejected handshake may not report the Gateway's release version; the app marks that information as unavailable. Different release numbers alone do not trigger this alert.

The dashboard update card names 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

For a saved Gateway added with browser sign-in, the dashboard uses that profile's Keychain-backed personal session. You do not need a second sign-in inside the embedded browser. Reconnect in Connection… → Gateways renews an expired session.

For a remote Gateway with identity-aware authentication, the app opens the dashboard at its sign-in address: HTTPS gateway.publicOrigin for trusted-proxy authentication, or the active managed Tailscale Serve address when Tailscale identity is enabled. Serve does not require gateway.publicOrigin. Complete the sign-in inside the dashboard window if that profile has no saved browser session; your existing Gateway profile then owns the displayed identity and chat attribution. The native device connection keeps its configured transport, including SSH, and its credentials are not sent to the public dashboard or sign-in provider. Shared-secret Gateways without a personal sign-in route continue to use the shared owner profile.

Open windows for saved Gateway profiles follow sign-in route changes after a reconnect. An unchanged route keeps the current dashboard and its navigation.

Opening the embedded dashboard at its default Chat landing restores the last page you visited, such as Usage, for that Gateway origin. Explicit session links and navigation requests take precedence over the remembered page, and first-run model setup still runs when needed.

In the macOS app's embedded dashboard, clicking an external web link opens it as a Mac tab in the Browser tab of the chat side panel. On non-chat routes, it opens in the shell-level Browser dock. While Settings is open, external links open in the default browser because the Browser panel is hidden. WebKit renders Mac tabs natively, alongside Agent browser tabs backed by the Gateway-controlled browser. Older Control UI bundles that still send the legacy inline link request open the default browser; current bundles open Mac tabs through the native Browser bridge.

Use the tab strip to select or close a page, the URL bar to navigate, and the back, forward, reload, stop, and Open in Default Browser controls to manage the active Mac tab. Opening the same link again reuses its existing tab, including a retained original URL after an initial redirect. Mac tabs belong to each window and survive chat session switches. Annotate and Inspect capture a one-shot snapshot of a Mac tab for sharing page context with the agent. Navigating that tab to a different URL discards the capture and restores its live view. The window's titlebar back/forward controls and trackpad swipes navigate dashboard history; the Browser panel's controls navigate the active page.

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 in the dashboard to choose Open in Browser Panel, Open in Default Browser, or Copy Link. Modified clicks still open the default browser. New-window links inside a Mac tab open another Mac tab; pointer-activated downloads hand off to the default browser. Responses WebKit cannot display hand off only for pointer-activated main-frame navigation; other non-displayable responses are cancelled silently. Regular browser-hosted Control UI pages keep their normal link and context-menu behavior unless you enable the Browser panel link preference.

Import browser logins

The first time a Mac tab 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; Dashboard → Settings → This Mac → Browser can re-open the native import flow while a local Gateway and eligible profile are available. 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 Dashboard → Settings → This Mac → Browser. Cookie sync is off by default and is available only in remote mode with an external CLI on this Mac. Turn on cookie sync, 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.

If a pending addition would restore a domain removed in another Dashboard window, it is discarded. Review the updated list and add the intended domains again.

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

The app's Mac node uses its bundled private runtime in both modes. Only setup and management of an app-owned local Gateway require the separate CLI install. Remote mode and attachment to an independently managed local Gateway skip that installation. Optional cookie sync still requires an external CLI on this Mac, and an existing separate node service keeps its own CLI lifecycle. See Gateway on macOS for manual recovery.

What the app owns

Native code owns device-local capabilities and the Connection window; the Dashboard owns all settings UI. Device preferences stay on this Mac, while the embedded Dashboard asks the app to read or change them and open native permission, shortcut, microphone-test, or browser-import panels.

• Menu bar status, notifications, health, WebChat, and the floating Quick Chat bar.
• macOS permission prompts for screen, microphone, speech, automation, and accessibility.
• One Mac node that combines 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, preserving the app's macOS permission attribution while the CLI runtime owns shared node policy.
• Remote-mode SSH tunnels or direct Gateway connections.

In the embedded Control UI, Dashboard → Settings → Notifications shows the app's native notification permission instead of browser push because the app delivers notifications natively.

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

macOS detail pages

Related

• Platforms
• Getting started
• Onboarding - the macOS app's first-run flow: where the Gateway runs, runtime install, and connecting a provider
• Gateway
• Exec approvals