OpenClaw for macOS

On a Mac, OpenClaw fits right in: one command to install, then a native menu bar app, voice wake, and—only on macOS—iMessage as a channel. Whether you're setting it up for the first time or you want to run the Gateway in the background and use the menu bar daily, the sections below cover install, the app, voice, iMessage, and troubleshooting.

The fastest way to get OpenClaw on your Mac is the one-line install script: it installs Node.js if needed and the OpenClaw CLI, then you run the onboarding wizard to set up your workspace and optionally install a background service so the Gateway keeps running after you close the terminal. Once that’s done, you can add the menu bar app, voice wake, iMessage, and other channels, and tweak configuration (model, workspace).

curl -fsSL https://openclaw.ai/install.sh | bash

Then run the onboarding wizard (it will prompt for workspace path, model, and whether to install the daemon):

openclaw onboard --install-daemon

When the wizard finishes, open the Control UI with openclaw dashboard, add channels, and install the menu bar app if you want it. For npm, Docker, or manual install, see the full Installation guide.

Your Mac should meet these so the one-liner, CLI, menu bar app, and voice wake all work as expected:

• macOS version: macOS 14 (Sonoma) or later for the menu bar app and voice; older versions may run the CLI only—check the Installation guide for your OS.
• Architecture: Intel (x86_64) or Apple Silicon (arm64); the install script and app support both (use the Universal Binary for the menu bar app).
• Node.js: Node.js ≥22; the one-liner installs it if missing, or you need it before a manual npm install. Check with node -v.
• Storage: ~500MB for the install, plus space for your workspace (conversations, config, media).

On an older macOS you may still run OpenClaw from the CLI or Docker; see Installation and the project docs for minimum supported versions. For a ready-to-run script in your browser, use the Setup Wizard.

The macOS companion app lives in the menu bar (top right) and connects to your OpenClaw Gateway. It’s a client—it doesn’t run OpenClaw by itself, so the Gateway must be running on this Mac (or reachable over the network). Install OpenClaw first with the one-liner or npm, then add the menu bar app. From it you can chat with your assistant, use voice wake, view the Canvas, and see Gateway status without opening a terminal or browser; same conversations as channels and the CLI. More detail in Companion Apps.

Click the icon to open chat, Canvas, or settings; the icon reflects whether the Gateway is connected. If it shows disconnected, start the Gateway (see Running as a service) or run openclaw gateway in a terminal. The app also offers voice overlay during voice sessions, built-in WebChat, and quick actions (e.g. open chat, toggle voice) from the menu.

Installing the menu bar app

1. Download the macOS app (Universal Binary) from the OpenClaw GitHub releases page (or the project’s official download link)
2. Drag the app to your Applications folder
3. Open it from Applications—on first launch, macOS may block it as an unidentified developer
4. The app appears in the menu bar (top right); click it to open the menu

First launch

If macOS says the app can’t be opened because it’s from an unidentified developer:

1. Go to System Settings → Privacy & Security
2. Under “Security,” find the message about the blocked app and click Open Anyway
3. Confirm, then open the app again from Applications
4. When the app asks for Microphone or other permissions, allow them so voice wake and chat work

Voice wake lets you talk to OpenClaw hands-free. The menu bar app listens for a wake word (e.g. “Hey OpenClaw” or whatever you set); when it hears it, it switches to a voice conversation so you can speak and hear replies without typing. It uses the Mac’s microphone and, depending on your config, local or cloud speech and TTS. You can ask questions, give commands, or have a back-and-forth when your hands are busy or you’d rather speak. For talk mode, TTS providers, and wake-word options, see Voice features and Voice setup tutorial.

It runs continuously in the background (may use a bit more battery if left on all day), uses macOS speech recognition, and can trigger even when the app isn’t in the foreground. Processing is local when possible. You’ll need to grant Microphone access; some setups use Accessibility as well for better system integration.

Setting up voice wake

1. Open the macOS menu bar app and click the menu bar icon
2. Go to Settings → Voice Wake (or the equivalent in your app version)
3. Turn on voice wake
4. When macOS prompts for microphone access, allow it—required for wake word and voice
5. Choose your wake word if the app offers options; say it clearly to test

If voice wake doesn’t respond

Check that Microphone is allowed in System Settings → Privacy & Security → Microphone, that the menu bar app isn’t muted in its own settings, and that you’re saying the wake word clearly (try less background noise or moving closer to the mic). Restarting the menu bar app often helps.

On macOS, OpenClaw can use iMessage as a channel: your assistant sends and receives iMessages on this Mac via the imsg CLI and the Messages database. Your Mac must be signed into iMessage with your Apple ID; no jailbreak. You chat with OpenClaw from the Messages app like any other contact—text, photos, media—and you can add OpenClaw to group chats. Everything stays in your normal iMessage threads. To add other channels (WhatsApp, Telegram, etc.), see the Channel setup tutorial and Channels overview.

Setting up iMessage

1. Open the Messages app and sign in with your Apple ID if you haven’t already
2. In Terminal, run: openclaw channels login imessage
3. Follow the prompts (e.g. grant access to Messages if asked)
4. In the OpenClaw Control UI or channel config, add iMessage as a channel; you should see your iMessage threads and can start or continue conversations

Reinstalling OpenClaw or moving to a new Mac means running openclaw channels login imessage again so the channel can reconnect. After a macOS update, re-running that command often fixes iMessage. For channel-specific problems (e.g. messages not sending), see the iMessage channel page and the main Troubleshooting guide.

Running the Gateway in a terminal is fine until you close the window or log out—then it stops. Installing it as a launchd service keeps it running in the background and optionally starting at login, so the menu bar app, iMessage, and other channels stay connected. You can close terminals, lock the Mac, or (depending on config) log out and still get messages and use the menu bar when you return. If you’d rather run the Gateway only when you need it, skip the service and run openclaw gateway in a terminal; see the CLI reference for commands.

Installing the service

Easiest: run the onboarding wizard and choose to install the daemon when prompted:

openclaw onboard --install-daemon

That creates a launchd plist (e.g. in ~/Library/LaunchAgents/) and enables the service. If you’ve already run onboarding without the daemon, you can run the command again and select the install-daemon option.

Managing the service

• Start: launchctl start ~/Library/LaunchAgents/com.openclaw.gateway.plist (or the plist name your install uses)
• Stop: launchctl stop ~/Library/LaunchAgents/com.openclaw.gateway.plist
• Status: openclaw status — shows whether the Gateway is running
• Logs: openclaw doctor or check logs in your OpenClaw workspace directory (e.g. ~/.clawdbot or the path you chose during onboarding) if you need to debug

After you change configuration (e.g. add a channel or update the model), restart the service so the Gateway picks up the changes: stop it, then start it again (or run openclaw restart if your install supports it).

LaunchAgent / SQLite (2026.2.19+): If the Gateway failed with SQLITE_CANTOPEN when run as a LaunchAgent, recent versions forward TMPDIR into the service environment so temp/journal files can be created. If the service won’t load (e.g. “bootstrap failure”), the Gateway now clarifies when the cause is launchctl GUI vs user domain—check the error message and ensure you’re loading the plist in the correct domain for your setup.

The menu bar app ties into the system in a few ways so you can reach chat and voice without switching apps, get notified when messages arrive or the Gateway has issues, and (if your app version supports it) use keyboard shortcuts to open chat or toggle voice wake. Full rundown in Companion Apps.

Menu bar integration

The menu bar icon gives you one-click access without opening a full window. Use it to open the chat/Canvas panel, see whether the Gateway is connected (the icon or label usually reflects status), toggle voice wake, and open settings. If the icon shows “disconnected” or similar, the Gateway isn’t running—start the service or run openclaw gateway in a terminal.

System notifications

You can get notifications when new messages arrive or when the Gateway has an issue. Enable them in the menu bar app’s settings if available, and in System Settings → Notifications so the OpenClaw app is allowed to notify. If you don’t see alerts, check that Do Not Disturb isn’t on and that the app has notification permission.

Keyboard shortcuts

Depending on the app version, you may have keyboard shortcuts to open the chat window or toggle voice wake. Check the app’s menu (e.g. “OpenClaw” in the menu bar) for “Keyboard Shortcuts” or “Shortcuts,” or look in System Settings → Keyboard → Keyboard Shortcuts → App Shortcuts to add your own.

Below are the most common macOS issues and fixes. For anything else—Gateway, channels, config, logs—the main Troubleshooting guide and CLI reference (all openclaw commands) have more.

“Command not found” after install

The installer may have added OpenClaw to your PATH, but your current terminal session doesn’t see it. Close the terminal and open a new window, or run source ~/.zshrc (or ~/.bashrc) and try openclaw status again. If it still fails, the one-liner or npm global install may need to fix the PATH—see the Installation guide for your method.

Menu bar app shows disconnected

The app talks to the Gateway on this Mac. If the Gateway isn’t running, the app will show disconnected. Start it either by running openclaw gateway in a terminal (and leave that window open) or by starting the launchd service (see Running as a service). Then check the menu bar again.

Permission issues

If the menu bar app or voice wake can’t access the microphone, or iMessage can’t access Messages:

1. Go to System Settings → Privacy & Security
2. Open Microphone and ensure the OpenClaw app (and Terminal, if you use the CLI) is allowed
3. If voice or system integration still fails, check Accessibility and add the app if needed
4. Quit the app fully and reopen it after changing permissions

Service not starting

If the Gateway service doesn’t start at login or when you run launchctl start:

1. Run openclaw doctor to check config and see error messages
2. Run launchctl list | grep openclaw to see if the service is loaded; if it isn’t, load it with launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist (use the actual plist name from your install)
3. Check the plist path and that the paths inside it (e.g. to openclaw) are correct; fix or re-run openclaw onboard --install-daemon if needed

More fixes (logs, channels, config): Troubleshooting guide.

iMessage not working

If iMessage integration fails or stops working:

1. Confirm the Messages app is signed in with your Apple ID
2. Run openclaw channels login imessage again and complete any prompts (e.g. grant access to Messages)
3. After a macOS update, re-running the login command often restores access
4. See the iMessage channel page for channel-specific notes

A few habits keep the menu bar app and channels connected, avoid permission headaches, and make sure config changes actually take effect. For deeper tuning, Configuration and Troubleshooting have more.

• Use the menu bar app — One place for chat, Canvas, voice, and Gateway status; no need to keep a terminal open.
• Run the Gateway as a service — Then the menu bar app, iMessage, and other channels stay connected after you close the terminal or lock the Mac.
• Enable voice wake only when you need it — If you’re not using voice, turn it off in the app to avoid unnecessary microphone use and battery drain.
• Grant permissions up front — When the app or system asks for Microphone (and optionally Accessibility), allow it so voice and iMessage don’t break later.
• After config changes, restart the Gateway — New channels, model changes, or workspace edits often require a restart of the service (or openclaw restart) to take effect.
• Keep OpenClaw updated — npm install -g openclaw@latest (or re-run the one-liner), then restart the Gateway so you get the latest fixes and features.