OpenClaw macOS Companion App: Menubar Guide

Introduction

While OpenClaw primarily runs as a command-line tool that connects to chat apps, macOS users have access to a powerful companion app that lives in your menubar. This native macOS application provides quick access to OpenClaw, desktop notifications, and seamless integration with your Mac’s system.

The companion app complements the CLI version, giving you the best of both worlds: chat app integration plus native macOS convenience. This guide covers everything you need to know about installing, configuring, and using the OpenClaw macOS companion app.

What is the Companion App?

The OpenClaw macOS companion app is a native application that:

• Lives in Your Menubar — Quick access without opening a terminal
• Provides Desktop Notifications — Get alerts for important messages
• Offers Quick Query Interface — Ask questions without opening chat apps
• Integrates with macOS — Works with system services and shortcuts
• Complements CLI — Works alongside the command-line version

Think of it as a desktop companion to your chat-based OpenClaw instance, providing native macOS integration and convenience features.

Installation

Method 1: Direct Download

1. Visit the OpenClaw releases page
2. Download the latest .dmg file for macOS
3. Open the downloaded .dmg file
4. Drag OpenClaw to your Applications folder
5. Launch from Applications or Spotlight

Method 2: Homebrew Cask

brew install --cask openclaw

Method 3: Build from Source

If you want the latest development version:

git clone https://github.com/openclaw/openclaw.git
cd openclaw/companion-app
npm install
npm run build
npm run dist

First Launch Setup

When you first launch the companion app:

Step 1: Connect to Your OpenClaw Instance

The app needs to connect to your running OpenClaw CLI instance:

1. Start OpenClaw CLI — Ensure your CLI instance is running
2. Enter API Endpoint — Default is http://localhost:3000
3. Verify Connection — App will test the connection

Step 2: Configure Preferences

Access preferences via the menubar icon:

• General — Startup behavior, notifications
• Appearance — Theme, icon style
• Advanced — API endpoints, debugging

Step 3: Grant Permissions

The app may request:

• Accessibility — For system integration
• Notifications — For desktop alerts
• Full Disk Access — For file operations (if needed)

Grant these in System Settings > Privacy & Security.

Menubar Features

Quick Access Menu

Click the menubar icon to access:

• Quick Query — Ask questions directly
• Recent Conversations — View chat history
• Skills — Access installed skills
• Settings — Configure preferences
• Status — Check connection status

Status Indicators

The menubar icon shows:

• Green — Connected and ready
• Yellow — Connected but warnings
• Red — Disconnected or error
• Gray — Starting up

Keyboard Shortcuts

Configure global shortcuts:

• Cmd+Shift+C — Open quick query
• Cmd+Shift+A — Toggle assistant
• Cmd+Shift+S — Show status

Quick Query Interface

The companion app’s quick query feature lets you interact with OpenClaw without opening WhatsApp, Telegram, or Discord.

Opening Quick Query

1. Click menubar icon
2. Select “Quick Query” or use keyboard shortcut
3. Type your question
4. Press Enter to send

Use Cases

Quick Information:

• “What’s on my calendar today?”
• “Check my email for urgent messages”
• “What’s the weather?”

Quick Actions:

• “Add task: Review project proposal”
• “Set reminder: Call Sarah at 3pm”
• “Check GitHub PR status”

System Queries:

• “What files did I modify today?”
• “Show me recent terminal commands”
• “What’s my system status?”

Desktop Notifications

The companion app can send desktop notifications for:

Message Alerts

Get notified when OpenClaw receives messages on:

• WhatsApp
• Telegram
• Discord
• Other connected platforms

Task Reminders

Set up reminders that trigger desktop notifications:

• Calendar events
• Task deadlines
• Custom reminders

System Events

Notifications for:

• OpenClaw status changes
• Skill execution results
• Error alerts
• Update notifications

Configuring Notifications

1. Open Preferences
2. Go to Notifications section
3. Enable/disable notification types
4. Customize notification sounds
5. Set Do Not Disturb hours

Integration with CLI

The companion app works alongside your CLI instance:

Shared Configuration

Both use the same:

• API endpoints
• Authentication
• Skills and integrations
• Memory and context

Complementary Features

CLI Provides:

• Chat app bridges
• Full command-line access
• Server capabilities
• Advanced configuration

Companion App Provides:

• Native macOS integration
• Desktop notifications
• Quick access interface
• System services

Running Both Together

You can run both simultaneously:

1. Start CLI instance: npm start
2. Launch companion app
3. Both connect to same backend
4. Use whichever interface is convenient

Advanced Features

System Services Integration

The companion app can integrate with macOS Services:

Text Selection:

1. Select text in any app
2. Right-click → Services → “Ask OpenClaw”
3. Get AI response in notification

File Operations:

1. Select files in Finder
2. Right-click → Services → “Analyze with OpenClaw”
3. Get file analysis

Spotlight Integration

Search for OpenClaw commands via Spotlight:

• Type “OpenClaw” to open app
• Search for “Ask OpenClaw” to trigger query
• Quick access to recent conversations

Shortcuts App Integration

Create automations in macOS Shortcuts:

1. Open Shortcuts app
2. Create new shortcut
3. Add “Run Shell Script” action
4. Call OpenClaw API endpoints
5. Trigger from Siri or widgets

Customization

Appearance

Customize the app’s look:

• Icon Style — Choose from available icons
• Theme — Light, dark, or auto
• Menu Style — Compact or expanded

Behavior

Configure app behavior:

• Launch at Login — Start automatically
• Hide When Inactive — Minimize menubar icon
• Quit Behavior — Keep running or quit with app

Advanced Settings

Power user options:

• Custom API Endpoint — Point to remote instance
• Debug Mode — Enable verbose logging
• Proxy Settings — Configure network proxy
• Update Channel — Beta or stable releases

Troubleshooting

App Won’t Connect

Issue: Companion app can’t connect to CLI

Solutions:

1. Verify CLI is running: ps aux | grep openclaw
2. Check API endpoint matches CLI port
3. Verify firewall isn’t blocking localhost
4. Check CLI logs for errors

Notifications Not Working

Issue: Desktop notifications don’t appear

Solutions:

1. Check macOS notification settings
2. Verify app has notification permission
3. Check Do Not Disturb status
4. Restart the app

Menubar Icon Missing

Issue: Icon doesn’t appear in menubar

Solutions:

1. Check if icon is hidden (macOS may hide icons)
2. Reset menubar: killall SystemUIServer
3. Reinstall the app
4. Check for macOS compatibility

Performance Issues

Issue: App is slow or unresponsive

Solutions:

1. Check system resources
2. Reduce notification frequency
3. Clear app cache
4. Restart the app

Best Practices

Daily Workflow

1. Start CLI — Run OpenClaw CLI on startup
2. Launch Companion — Keep companion app running
3. Use Quick Query — For quick questions
4. Use Chat Apps — For longer conversations
5. Monitor Notifications — Stay informed

Resource Management

• Monitor memory usage
• Close companion app if not needed
• Use CLI-only mode for servers
• Optimize notification settings

Security

• Keep app updated
• Use secure API endpoints
• Don’t expose API publicly
• Review notification permissions

Comparison: Companion App vs CLI

When to Use Companion App

• Quick desktop queries
• Desktop notifications
• macOS system integration
• Visual status monitoring

When to Use CLI Only

• Server deployments
• Headless setups
• Advanced configuration
• Resource-constrained systems

Using Both

Best of both worlds:

• CLI for core functionality
• Companion app for convenience
• Shared backend and configuration
• Flexible access methods

Future Enhancements

The companion app continues to evolve with features like:

• Widget support for macOS
• Siri integration
• More system services
• Enhanced notifications
• Better performance

Conclusion

The OpenClaw macOS companion app provides native desktop integration that complements the CLI version perfectly. Whether you want quick queries, desktop notifications, or system integration, the companion app enhances your OpenClaw experience on macOS.

Install it alongside your CLI instance for the best experience. Use quick query for fast questions, rely on notifications for important alerts, and enjoy seamless macOS integration.

For more information, check out our installation guide and macOS-specific setup. If you have questions, visit our FAQ or explore other tutorials.