If you already run an OpenClaw gateway locally but keep wishing for a single click to check its pulse or fire off a voice command, the companion macOS menu bar app is what you are looking for. This guide walks through downloading, installing, granting macOS permissions, wiring the app to your gateway, and poking at the bundled WebChat + debug tools. Screenshots are overrated; precise commands and config snippets matter more, so that’s what you’ll find below.

Why a Menu Bar Companion Instead of Yet Another Tab?

Leaving localhost:5111 open in a browser works, yet it burns a tab, misses microphone shortcuts, and won’t warn you when the daemon silently crashes. The menu bar app ships three things that the browser tab can’t:

  • Health Monitor – a red/yellow/green indicator reflecting the daemon’s /health endpoint every three seconds.
  • Voice Wake & Push-to-Talk (PTT) – hands-free “Hey Claw” hotword or a keyboard combo for privacy-first mic activation.
  • Native macOS Permissions – notifications, login item, accessibility callbacks for automation.

It is strictly a UI shim; nothing runs in the cloud unless you point it there. You can disconnect Ethernet, keep talking to the agent, and still get replies.

System Requirements & Download Channels

The companion app is a notarized universal binary: a single build that contains both x86_64 and arm64 slices. Tests were done on:

  • macOS 13.6 Ventura
  • macOS 14.4 Sonoma
  • Apple Silicon M1 Pro, M2 Max, and one lonely 2019 Intel MBP

The app itself is Electron 28.2.1 with Node 22.4.0 embedded, so you don’t need a global Node install. However, your gateway still needs Node 22+ if you run it on the same box.

Release Sources

  • Signed DMG (recommended) – GitHub Releases > OpenClaw/companion-app – assets are OpenClawCompanion-vX.Y.Z.dmg, notarized in CI via apple-notary-tool.
  • Unsigned ZIP – same repo, marked -unsigned. Only grab this if you rebuild from source and Gatekeeper is your friend.
  • Homebrew Cask – brew install --cask openclaw-companion. Takes 2–4 h to appear after each tag.

File size sits at ~98 MB because of the Chromium runtime. Cold start is 400 ms on an M2, 1.2 s on Intel.

Installation & First Run

Option A – Signed DMG

  1. Mount the DMG and drag OpenClaw Companion.app into /Applications.
  2. Eject the DMG. You can delete it; auto-update uses Squirrel.Mac afterwards.
  3. Open Launchpad > run the app. Gatekeeper should show no warnings – the bundle carries a `Developer ID Application` signature.

Option B – Homebrew Cask

brew update brew install --cask openclaw-companion

Brew handles quarantine attributes, so step 3 above is identical.

Option C – Unsigned ZIP

  1. Unzip into /Applications/OpenClaw Companion.app.
  2. Right-click → Open (twice) to bypass Gatekeeper’s “unidentified developer” lock.
  3. System Settings → Privacy & Security → Allow Anyway if you still get blocked.

Honestly, spend the extra 30 s and download the signed build. Life is short.

Connecting the App to Your Local Gateway

The first launch shows a minimal connection wizard. Under the hood the app just POSTs to /v1/system/ws and subscribes over WebSocket. You need three bits of data:

  • Host – usually 127.0.0.1 or whatever box runs the daemon.
  • Port – default 5111, overridable via OPENCLAW_PORT.
  • Auth Token – the value of OPENCLAW_TOKEN in your .env. Empty string if you never set one. (Probably fix that.)

Quick Config Via CLI

You can pre-seed the above in a JSON file so the wizard never pops. Create ~/.openclaw-companion.json:

{ "host": "127.0.0.1", "port": 5111, "token": "claw-dev-psk-9fc2b...", "autoLaunch": true, "hotword": "Hey Claw", "pttShortcut": "^⌥⌘C" }

Next time the app boots it slurps the file, validates the JSON schema, and writes a mirrored plist under ~/Library/Preferences/io.openclaw.companion.plist. JSON wins on conflicts.

Connection Status LEDs

  • Gray – not connected, retry back-off running.
  • Yellow – WebSocket connected but /health returned 400-level – typically your agent is loading or rate-limited.
  • Green – all good.
  • Red – hard disconnect after 5 failed WebSocket pings.

Logs live in ~/Library/Logs/OpenClaw Companion/. Hit ⌥ while clicking the menu bar icon to reveal the Open Log Directory menu item.

macOS Permissions – What, Why, and How to Revoke

Because the companion deals with microphones, keyboard shortcuts, and notifications, you will get a small parade of permission sheets on first use. Here is what each does and how to audit later:

1. Microphone

Needed for voice wake and PTT. Toggling the mic off from inside the tray also halts hotword detection. Re-enable in System Settings → Privacy & Security → Microphone.

2. Accessibility

Required solely for global PTT shortcuts with key-up detection. Without it, ⌃⌥⌘C will start listening but will never know when you released the keys. If you’re paranoid, uncheck the permission and stick to hotword.

3. Notifications

The app surfaces agent replies as native alerts. If you disable notifications the agent still works; you’ll just have to open WebChat or a terminal to see responses.

4. Login Item

The installer adds itself to Login Items → Allow in Background so you aren’t forced to click the dock icon after every reboot. Toggle in System Settings → General → Login Items.

Troubleshooting Gatekeeper & TCC

# Reset just the companion's TCC entries (extreme measure) tccutil reset All io.openclaw.companion

After running the above you’ll get the permission prompts again.

Feature Tour – What Lives Behind the Claw Icon

1. Voice Wake (“Hey Claw”)

  • Recognizer: Vosk 0.3.45, on-device, uses 6–8 % single CPU core idle.
  • Language: en-US model only for now; community PRs welcome.
  • Timeout: 5 s silence by default. Override via ~/.openclaw-companion.json → silenceTimeout.

2. Push-to-Talk (PTT)

  • Global shortcut captured via io.openclaw.globalHotKey electron-localshortcut.
  • Shortcut editable in the Preferences → Shortcuts pane; config file wins if conflicts.
  • Hold the combo, speak, release. The menu bar icon animates from hollow to filled claw when the mic is live.

3. Quick Gateway Control

  • Restart Gateway – sends POST /v1/system/restart, waits for WebSocket reconnect.
  • Open Config Folder – jumps into your gateway’s working dir (looks for package.json with openclaw-gateway script).
  • Check for Update – forces an autoUpdater tick; updates download into ~/Library/Caches, 2 × restart needed.

4. Health Monitor

A 32 × 32 SF Symbol with one of four fills (see earlier color list). Hovering reveals last latency in ms plus daemon version. The monitor pings /health?timeout=50; if >50 ms it flips to yellow.

5. Friendly Battery Discipline

On laptops the app detects IOPMGetBatteryLevel. If you dip below 15 % and the daemon consumes >100 % CPU for 30 s, it offers to pause embeddings retrains. Accepting sends POST /v1/embeddings/pause. Nerds asked; yes, timeout and battery threshold are hidden prefs.

WebChat & Debug Tools Bundled

Click Open WebChat in the tray or navigate to http://localhost:5111?embed=1. The app embeds the same React build the gateway serves, which means dark-mode detection, markdown rendering, and tool call traces are identical to what you would see in a browser.

Packets Tab

A mini-Wireshark riff showing the last 100 JSON messages across the WebSocket. Useful when your custom tool returns garbage and you want to confirm whether it is the daemon or the companion choking.

Profiler

Under an experimental flag: Preferences → Advanced → Show Profiler. It instruments gateway function calls via the /v1/system/profile?sample=250 endpoint and charts median latency. Not persisted, disappears at quit.

Updating and Uninstalling

Auto-Update

The app polls GitHub API every six hours; if a semver-newer release with the same signing team is available, it downloads the zipped .darwin-universal asset and prompts for restart. If you installed via Homebrew, Brew owns updates instead – run brew upgrade --cask openclaw-companion.

Manual Update

cd /Applications/OpenClaw\ Companion.app/Contents/MacOS ./OpenClaw\ Companion --checkForUpdates

This spits human-readable output to the console, helpful on headless Mac mini build agents.

Uninstall

rm -rf /Applications/OpenClaw\ Companion.app rm -rf ~/Library/Preferences/io.openclaw.companion.plist rm -rf ~/Library/Application\ Support/OpenClaw\ Companion rm -rf ~/Library/Logs/OpenClaw\ Companion

Homebrew users: brew uninstall openclaw-companion.

Putting It All Together – A 60-Second Sanity Test

  1. Start your gateway in a terminal: export OPENCLAW_TOKEN=claw-dev-psk-9fc2b openclaw gateway --port 5111
  2. Launch the companion. LED goes green.
  3. Hold ⌃⌥⌘C, say “list my GitHub PRs”, release.
  4. You should hear the agent reply in TTS and see a native notification. WebSocket console shows a tools.github.listPullRequests call.
  5. Kill the gateway process. LED flips red. Restart gateway; LED returns to green without touching the app.

If the above works, your setup is solid. Script or forget—the choice is yours. To fold this into a bigger workflow, chain a Shortcuts automation that toggles the “Enable Hotword” pref when you join a Zoom call, or pipe the WebSocket feed into a VS Code extension. The companion just speaks HTTP; how you wire it up is unlimited.

Next stop: point the same companion at a ClawCloud instance (gateway hostname shows in the ClawCloud dashboard) and keep the rest of your configuration unchanged. Same toolchain, zero local CPU burn.