OpenClaw macOS Menu Bar App: Install and Use Guide

The OpenClaw menu bar companion for macOS provides a native tray interface, macOS permission prompts, notifications, WebChat, voice input, a hosted-widget panel, and node tools hosted on the Mac, such as system.run.

Quick Chat gives you a Spotlight-style composer for the main session without opening a full window. The default shortcut is Option-Space (⌥Space); you can also pick it from the menu bar menu, or record a different shortcut under Dashboard → Settings → This Mac → App.

Click the green window button to switch to native full screen. The Dashboard's sidebar and chat controls stay reachable at the top of the window. Exiting full screen brings back the usual titlebar and window controls.

Before the Dashboard finishes loading, its blank canvas matches the native window's appearance. After the page paints, the background comes from the theme selected in the Dashboard.

Images can be attached in the full native chat by picker, paste, or drag and drop. Images produced by the assistant appear inline via short-lived Gateway artifact URLs and open into a larger preview; iOS and macOS share one bounded image model and renderer.

If all you need is the CLI and Gateway, begin with Getting started.

Requirements

OpenClaw.app requires macOS 26.2 (Tahoe) or later. The same requirement covers its native openclaw-mac helper and Voice Wake and push-to-talk.

The Node-based CLI and Gateway require a supported Node version running on an operating system that runtime supports. Official Node 24 and Node 26 macOS binaries target macOS 13.5 or later, the oldest release Node supports. They may still run on older macOS releases, but those are unsupported. Running the CLI on an older Mac does not make the native app compatible with that macOS version.

Compiling from source additionally needs the toolchain described in macOS developer setup.

Download

Grab a macOS installer from the published 2026.10.3 release:

The links above are pinned to 2026.10.3. Newer builds and ZIP archives are listed in OpenClaw GitHub releases. Certain releases ship only CLI, evidence, or Windows assets. When the latest release carries no macOS app asset, take the most recent one that does, or compile from source using macOS dev setup.

First run

Install OpenClaw.app, then launch it. On a first install with no saved Gateway or configuration, a progress window shows while the app prepares its bundled runtime, launches a Gateway on This Mac, and opens the dashboard's onboarding conversation. It never joins a discovered Gateway on its own. The window displays the current step and dismisses itself when the dashboard is ready. If the dashboard reconnects during this handoff, setup continues in the same window, and Review permissions carries on in the dashboard. Pick Set up manually to use native setup instead.

Your AI is connected by the dashboard, which shows what it picked and suggests alternatives. From the setup card you can select a different Gateway or review this Mac's permissions. The rest of setup (memory import, channels, and permissions) then proceeds in that same conversation. macOS permissions can be granted at any point via Dashboard → Settings → This Mac → Permissions.

Should runtime preparation, Gateway startup or authentication, or dashboard loading fail, the same window moves to the matching native setup step and displays the error. An older Gateway that lacks automatic AI setup opens the native AI picker instead. Native setup stays reachable from the menu for manual recovery: pick This Mac or type an existing Gateway's address, prepare the local runtime if needed, then choose an AI connection so its live model check can run. When runtime readiness drops the installation step from the flow, native setup keeps the current page visible.

Saved setup is retained by existing installations and remote connections. Native AI detection only lists available connections; a connection is checked and activated after you choose it. If an existing model verifies, the normal dashboard opens and the configured route is left in place.

An already configured model is kept by automatic setup. Failing that, it tries saved OpenClaw auth profiles, a stored Codex login, a Claude CLI login, OPENAI_API_KEY, ANTHROPIC_API_KEY, and then eligible loaded models in Ollama, LM Studio, or llama.cpp. Whichever connection passes a live completion first gets activated. If nothing passes, it installs or enables the official Codex plugin and uses its login, or asks you to sign in with ChatGPT. Apple Foundation Models is never picked as the primary model, and native Claude/Codex conversation discovery remains off.

When Codex is reused during setup, the card reads Using your existing Codex login · sessions shared with Codex. Authentication and token refresh belong to Codex in the Gateway user's CODEX_HOME (or ~/.codex); OAuth tokens are not copied by OpenClaw. To sign in to an isolated OpenClaw agent home, select Use a separate login on the card. Providers can also be changed, or a separate sign-in done, via Model Setup. See Codex login and isolation.

For the CLI/Gateway path, see Getting started. For help recovering permissions, see macOS permissions.

To add another Gateway for dashboard and chat access, open Connection… → Gateways → Add Gateway and type its hostname or HTTPS address. With Cloudflare Access Gateways, you sign in using your personal account in the default browser. Another route is Get the apps → Open in Mac app on the Gateway's website. See browser sign-in.

Open Dashboard settings by choosing Settings… from the menu bar or pressing Cmd-. Under This Mac you'll find app preferences, local capabilities, browser login import, cookie sync, and permissions. Device voice controls live under Settings → Talk → This Mac, and app update preferences under Settings → Updates → This Mac. These device controls show up only in the macOS app's embedded Dashboard, not in an ordinary browser.

This Mac → Capabilities → Desktop sharing is on by default. It surfaces this Mac's existing Screen Sharing service in Systems, separately from Computer Control and Keep computer awake. Turn on Screen Sharing in System Settings → General → Sharing, and approve the node's desktop capability when asked. Any explicit disable settings you already have remain off after an update; changing the Mac setting reconnects the node on its own. See paired node desktops.

Turning on sensitive capabilities brings up a native confirmation where Cancel is the default. Pending consent is cancelled if the Dashboard page closes or is replaced; request the change again from the current page.

Connection

Pick Connection… to open the small native window even when the Gateway can't be reached. Local Gateway status, remote/SSH options, Tailscale, and discovery sit in its Connection tab; saved Gateway profiles are managed in Gateways. A Debug tab shows while the developer toggle under This Mac → Developer is on. That same toggle turns on Inspect Element in the Dashboard and widget panel context menus; changes take effect in open windows without a restart. About OpenClaw selects the About tab in this window, which holds the app version, build information, and resource links. Copy Build Info copies the full version, commit, and build timestamp. About works offline.

When 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, displays installation progress, and verifies the Gateway afterward. After cancelling an earlier prompt, you can retry here. For an incompatible Gateway newer than the app, Set Up Gateway lets you review the setup choice. Gateways managed independently keep their own update workflow.

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

Updates

To switch automatic app updates on or off, go to Dashboard → Settings → Updates → This Mac. That same page offers Check for Updates… and displays the installed app version and build. It also explains the situations where updates cannot be applied, such as when a named app profile is active.

When the primary Gateway connection refuses the app's protocol version, an update alert appears and the explanation is kept in the connection status. Remote setup and connection checks present the same guidance inline. The message identifies the app release and both protocol versions, and states which side must be updated: run openclaw update on a Gateway host running an older version, or get a newer Mac app through the download options. If the handshake is rejected, the Gateway's release version may go unreported, and the app labels that information as unavailable. Differing release numbers on their own do not cause this alert.

The dashboard update card tells you what the app is about to update:

• Update Mac app + Gateway applies when the signed app owns the local launchd Gateway. Sparkle updates the app first; once it relaunches, the app updates and restarts its Gateway to the matching version on its own, then checks the connection.
• Update Gateway applies when the app is linked to a remote Gateway, a local Gateway managed by hand, or another installation the app does not own. In that case the button triggers that Gateway's usual update flow rather than touching the Mac app.

Both buttons request confirmation before doing anything. The card only hands the update to the app after you pick Update Mac app and restart, so an accidental click never launches Sparkle.

If a coordinated update fails, its setup-style window stays open with retry, update guide, and Discord actions. Automatic repair never downgrades a Gateway that is newer, and it never overrides an extended-stable channel pin.

Onboarded launches with updates enabled also check the app-owned runtime whenever the post-update receipt is missing, stale, or unreadable. What gets done depends on current runtime ownership and version; receipts are what preserve interrupted progress and keep notifications from repeating. Pending welcome notifications wait until the current runtime is verified. Reconciling the same version without an app-update receipt does not send a second welcome.

An update interrupted in an older Mac app might point at its managed CLI package rather than the Gateway or node service currently selected. Before reconciling the selected runtime, the app confirms ownership and repairs that package. A newer package is kept and not downgraded; if a service update is separately needed, it still tracks its own recovery progress.

Once an update succeeds, the app locates the top-level direct webchat session most recently used by a person and hands that agent a one-time update event. Heartbeat and cron activity play no part in this choice. The agent can then greet you back in the conversation you were most likely using. In remote mode, a separately installed node service managed by the app keeps its own runtime update and recovery flow; when the remote Gateway is older than the app, the notification is skipped. The app's private node worker updates together with the app bundle.

Sparkle obeys 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 remain on stable app builds.

Open dashboard links

When a saved Gateway was added through browser sign-in, the dashboard relies on that profile's personal session, which is backed by the Keychain. No second sign-in inside the embedded browser is needed. To renew an expired session, use Reconnect in Connection… → Gateways.

For a remote Gateway that uses 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. If that profile has no saved browser session, finish signing in inside the dashboard window; your existing Gateway profile then owns the displayed identity and chat attribution. The native device connection keeps its configured transport, SSH included, and its credentials are never sent to the public dashboard or the sign-in provider. Gateways using a shared secret with no personal sign-in route keep using the shared owner profile.

Open windows for saved Gateway profiles follow sign-in route changes after a reconnect. If the route has not changed, the current dashboard and its navigation stay as they are.

The account card in the dashboard's bottom-left corner shows your name, the current Gateway, and its primary status. One subtitle under your name covers planned suspension and restart, reconnect, and recovery. An outbox count reflects unresolved messages for this Gateway, including those needing review; it does not guarantee that every message will send automatically. Expand the card's Gateway section to switch Gateways, Command-click or Control-click a Gateway to open it in another window, or pick Gateway settings…. Set as primary… shows up when the current Gateway can be promoted. All of these controls work even when only one Gateway is saved.

When the embedded dashboard opens at its default Chat landing, it restores the last page you visited for that Gateway origin, for example Usage. Explicit session links and navigation requests override the remembered page, and first-run model setup still runs when it is needed.

Inside the macOS app's embedded dashboard, an external web link opens 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 instead. While Settings is open, the Browser panel is hidden, so external links go to the default browser. WebKit renders Mac tabs natively, next to Agent browser tabs, which the Gateway-controlled browser backs. Older Control UI bundles that still send the legacy inline link request open the default browser; current bundles open Mac tabs via the native Browser bridge.

Use the tab strip to pick 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. Reopening the same link reuses its existing tab, including a retained original URL after an initial redirect. Mac tabs are per window and persist across chat session switches. Annotate and Inspect take a one-shot snapshot of a Mac tab so page context can be shared with the agent. Navigating that tab to a different URL throws the capture away and restores the live view. The window's titlebar back/forward controls and trackpad swipes move through dashboard history; the Browser panel's controls move through the active page.

Titlebar controls track the app sidebar: when it is expanded, back/forward sit at its right edge beside the sidebar toggle; when it is collapsed, a search button (which opens the command palette) and a new-session button take their place.

To move the window, drag the empty space next to the side-panel tabs. The header's full height is draggable, and the draggable area adjusts as tabs are added, removed, or resized. Tabs and header buttons keep their usual click and tab-reordering behavior.

Mac tabs remain visible when a menu or hover card opens elsewhere in the dashboard. A tab's page hides only temporarily when the menu overlaps its Browser pane, or while a modal dialog or the command palette is open, and it comes back once the obstruction is gone.

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

Right-click an external link in the dashboard to pick Open in Browser Panel, Open in Default Browser, or Copy Link. Modified clicks still go to the default browser. New-window links inside a Mac tab open another Mac tab; pointer-activated downloads are handed to the default browser. Responses WebKit cannot display are handed off only for pointer-activated main-frame navigation; other non-displayable responses are cancelled without notice. Regular browser-hosted Control UI pages keep their normal link and context-menu behavior unless you turn on the Browser panel link preference.

Import browser logins

To find Chrome-family profiles and bring up the import banner, go to Dashboard → Settings → This Mac → Browser and select Import browser logins. Other apps' browser data is not examined on first launch, during automatic setup, or on passive dashboard refreshes until you request this feature. When discovery begins, macOS may prompt for access. Pick a profile through the banner's Import control (Touch ID may be required). Progress and the count of imported cookies are shown inline, and cookies are the only thing copied, into an isolated managed profile. Passwords never leave the source browser. If you dismiss the banner, that choice is recorded, and the same Settings action brings it back. The underlying import flow and the browser.allowSystemProfileImport gate are described in Browser.

Leaving Local mode hides the import banner and throws away pending status or banner results. An import already handed to the local Gateway may still complete there, and changing modes does not reverse cookies that were copied. Once you return to Local mode, you can request a fresh offer from Settings → This Mac → Browser.

Sync cookies to a remote computer

An import copies cookies one time into a profile on the same Mac. If your Gateway and agent browser live on a separate computer (a dedicated box, a headless Linux host, or a cloud container), enable cookie sync so this Mac can keep that remote browser signed in to the sites you pick.

Go to Dashboard → Settings → This Mac → Browser. Cookie sync is off by default and works only in remote mode, with an external CLI present on this Mac. Enable cookie sync, put the sites to keep in sync on the Domains allowlist (for example github.com and accounts.google.com), and choose the Target profile that receives them (the managed profile name on the remote Gateway, imported by default). Whether sync is running appears in a status row.

A pending addition that would bring back a domain removed in another Dashboard window is dropped. Check the updated list, then add the domains you intended again.

While the feature is on, the app supervises the openclaw browser cookie-sync --watch command against the connected Gateway. Decryption of cookies happens locally on this Mac (one macOS Keychain or Touch ID prompt per session), and they are pushed to the remote profile over the app's existing encrypted Gateway connection. Only allowlisted domains are ever sent, and cookie values never reach the logs. With an empty allowlist, nothing syncs. As with import, certain Google sessions rely on device-bound session credentials (DBSC) that remain tied to this Mac and may still need re-authentication after sync. For such sites, use the browser node proxy to drive the browser on the Mac itself.

Choose a Gateway mode

In either mode, the app's Mac node relies on its bundled private runtime. A separate CLI install is needed only for setup and management of an app-owned local Gateway. Remote mode, and attaching to a local Gateway that is managed independently, skip that installation. Optional cookie sync still needs an external CLI on this Mac, while a separate node service that already exists keeps its own CLI lifecycle. Manual recovery steps are in Gateway on macOS.

What the app owns

Device-local capabilities and the Connection window are handled by native code, whereas all settings UI lives in the Dashboard. Device preferences remain on this Mac, and the embedded Dashboard requests reads or changes from the app, which also opens the native panels for permissions, shortcuts, microphone tests, and browser import.

• 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.

For native system.run, whatever launches it (Finder, the Dock, or login startup), the app adds its preferred tool folders, Homebrew and ~/.local/bin among them, to the inherited PATH. These folders are discovered once on first use and then reused for approval and execution, with no shell startup files loaded. After you change where tools are installed, relaunch the app; a tool installed into a folder already on the list needs no restart. Request-level PATH overrides stay blocked. Environment configuration for the CLI and for separately managed node services remains their own.

Inside the embedded Control UI, Dashboard → Settings → Notifications reports the app's native notification permission rather than browser push, since notifications are delivered natively by the app.

The app does not take the place of the Gateway or general CLI docs. Gateway configuration, providers, plugins, channels, tools, and security each have their own documentation.

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