macOS App

macOS App

OpenClaw provides a native macOS application that offers a convenient interface for managing your OpenClaw gateway, monitoring activity, and interacting with AI agents directly from your Mac.

Installation

Download and Install

1. Download the latest version:

   • Visit OpenClaw Releases
   • Download OpenClaw-latest.dmg for macOS

2. Install the application:

   • Open the downloaded DMG file
   • Drag OpenClaw.app to your Applications folder
   • Launch OpenClaw from Applications or Spotlight

3. Grant necessary permissions:

   • OpenClaw will prompt for various permissions on first launch
   • Grant Full Disk Access, Automation, and Network permissions as needed

Homebrew Installation

# Install via Homebrew
brew install --cask openclaw

# Or install from tap
brew tap openclaw/openclaw
brew install --cask openclaw

First Launch Setup

Initial Configuration

1. Launch OpenClaw:

   • Open OpenClaw.app from Applications
   • The app will open to the setup wizard

2. Configure gateway settings:

   • Choose installation location
   • Set gateway port (default: 18789)
   • Configure security settings

3. Set up messaging channels:

   • Configure WhatsApp, Telegram, Discord, or iMessage
   • Enter API keys and tokens
   • Test connections

4. Configure AI agent:

   • Choose AI model (Claude, GPT-4, etc.)
   • Enter API keys
   • Set agent preferences

Permission Setup

OpenClaw requires several macOS permissions:

Full Disk Access

1. Open System Settings → Privacy & Security → Full Disk Access
2. Click the + button
3. Add OpenClaw.app from Applications
4. Restart OpenClaw

Automation

1. Open System Settings → Privacy & Security → Automation
2. Find OpenClaw in the list
3. Enable access to Messages, Safari, and other apps as needed

Network

1. Open System Settings → Network
2. Ensure OpenClaw can access network resources
3. Configure firewall if needed

App Interface

Main Window

The OpenClaw app features a clean, native macOS interface:

Sidebar Navigation

• Dashboard: Overview of gateway status and activity
• Channels: Configure messaging platforms
• Agents: Manage AI agents and models
• Messages: View and manage message history
• Settings: Configure app and gateway settings
• Logs: View detailed logs and debug information

Dashboard

• Gateway Status: Online/offline status, uptime, version
• Active Channels: Connected messaging platforms
• Message Statistics: Messages sent/received, error rates
• Resource Usage: CPU, memory, network usage
• Recent Activity: Latest messages and events

Channels Tab

• WhatsApp: Login, QR code scanning, connection status
• Telegram: Bot token configuration, webhook setup
• Discord: Bot token, server permissions, slash commands
• iMessage: imsg CLI setup, contact management

Agents Tab

• Model Selection: Choose AI model and provider
• API Configuration: Enter API keys and endpoints
• Agent Settings: Temperature, max tokens, system prompts
• Performance: Response times, token usage, costs

Menu Bar Integration

OpenClaw integrates with the macOS menu bar:

Menu Bar Icon

• Quick Status: Gateway status at a glance
• Quick Actions: Start/stop gateway, send test messages
• Notifications: Message alerts and system notifications
• Preferences: Quick access to settings

Voice Wake (Optional)

• Voice Activation: “Hey OpenClaw” wake word support
• Voice Commands: Execute commands via voice
• Privacy: On-device voice processing

Features

Native macOS Integration

Spotlight Search

• Search OpenClaw messages and configuration
• Quick access to commands and settings
• Integration with macOS search

Touch Bar Support

• Quick actions on MacBook Pro Touch Bar
• Message shortcuts and status indicators
• Customizable Touch Bar layout

Notification Center

• Message notifications in macOS Notification Center
• Actionable notifications (reply, mark as read)
• Do Not Disturb integration

Handoff and Continuity

• Start conversation on Mac, continue on iOS
• Universal Clipboard support
• Handoff between devices

Advanced Features

Shortcuts App Integration

# Create OpenClaw shortcuts in Shortcuts app
# Available actions:
# - Send Message
# - Check Status
# - Start/Stop Gateway
# - Execute Command

AppleScript Support

-- Example AppleScript to send a message
tell application "OpenClaw"
    send message to "+1234567890" with content "Hello from AppleScript"
end tell

-- Check gateway status
tell application "OpenClaw"
    set gatewayStatus to get gateway status
    display dialog "Gateway Status: " & gatewayStatus
end tell

File Provider Integration

• Access OpenClaw files in Finder
• Quick Look for message attachments
• Share menu integration

Configuration

App Preferences

General Settings

• Launch at Login: Start OpenClaw automatically
• Show in Menu Bar: Menu bar icon visibility
• Notifications: Configure notification preferences
• Updates: Automatic update checking

Gateway Settings

• Gateway Path: Path to gateway executable
• Configuration File: Location of config file
• Log Level: Verbosity of logging
• Resource Limits: CPU and memory limits

Security Settings

• Token Storage: Secure token storage options
• Biometric Lock: Touch ID/Face ID for app access
• Auto-lock: Automatic app locking
• Audit Logging: Security event logging

Advanced Configuration

Configuration File Location

# App configuration
~/Library/Containers/com.openclaw.openclaw/Data/Library/Application Support/OpenClaw/

# Gateway configuration
~/.openclaw/openclaw.json

# Logs
~/Library/Containers/com.openclaw.openclaw/Data/Library/Logs/OpenClaw/

Environment Variables

# Set in ~/.zshrc or ~/.bash_profile
export OPENCLAW_CONFIG_PATH="$HOME/.openclaw/openclaw.json"
export OPENCLAW_LOG_LEVEL="info"
export OPENCLAW_MACOS_MENU_BAR=true

Usage

Daily Operations

Starting the Gateway

1. Launch OpenClaw app
2. Click “Start Gateway” in the dashboard
3. Monitor startup in the logs tab
4. Verify all channels are connected

Sending Messages

1. Go to Messages tab
2. Click “New Message”
3. Select channel and recipient
4. Type message and send
5. Monitor delivery status

Monitoring Activity

1. Check Dashboard for real-time status
2. Review message history in Messages tab
3. Monitor resource usage
4. Check logs for any issues

Voice Commands

Enable Voice Wake

1. Go to Preferences → Voice
2. Enable “Voice Wake”
3. Train wake word (optional)
4. Configure voice commands

Available Voice Commands

• “Hey OpenClaw, send message to [contact]”
• “Hey OpenClaw, what’s the status?”
• “Hey OpenClaw, start gateway”
• “Hey OpenClaw, check WhatsApp”

Automation

Automator Actions

Create automated workflows with OpenClaw:

1. Open Automator
2. Create new workflow
3. Add OpenClaw actions from the library
4. Configure and save workflow

Cron Jobs

Schedule regular tasks:

# Edit crontab
crontab -e

# Add daily health check
0 9 * * * /usr/bin/openclaw health-check

# Weekly log cleanup
0 2 * * 0 /usr/bin/openclaw logs cleanup

Troubleshooting

Common Issues

App Won’t Launch

# Check app permissions
ls -la /Applications/OpenClaw.app

# Reset permissions
sudo xattr -r -d com.apple.quarantine /Applications/OpenClaw.app

# Check system logs
log show --predicate 'process == "OpenClaw"' --last 1h

Gateway Connection Issues

# Check gateway status from app
# Go to Dashboard → Gateway Status

# Test gateway manually
openclaw gateway status

# Check logs in app
# Go to Logs tab → Gateway logs

Permission Issues

# Reset app permissions
sudo tccutil reset All com.openclaw.openclaw

# Re-grant permissions
# System Settings → Privacy & Security → Full Disk Access
# Add OpenClaw.app again

Performance Issues

# Monitor resource usage
# Activity Monitor → OpenClaw process

# Clear app cache
# Preferences → Advanced → Clear Cache

# Restart gateway
# Dashboard → Restart Gateway

Debug Mode

Enable debug logging in the app:

1. Go to Preferences → Advanced
2. Enable “Debug Mode”
3. Set log level to “Debug”
4. Restart the app
5. Check logs tab for detailed information

Crash Reports

If the app crashes:

1. Crash reports are saved to: ~/Library/Logs/DiagnosticReports/OpenClaw_*.crash

2. Generate support bundle:

   • Help → Generate Support Bundle
   • Includes logs, configuration, and crash reports

3. Report issue:

   • Include crash report and support bundle
   • File issue on GitHub

Updates

Automatic Updates

OpenClaw supports automatic updates:

1. Update checking:

   • Preferences → Updates → Check for updates automatically
   • Checks daily for new versions

2. Update installation:

   • Prompts when updates are available
   • Downloads and installs automatically
   • Restores previous version if needed

Manual Updates

# Check for updates manually
# Help → Check for Updates

# Download latest version
# Visit GitHub releases page

# Install new version
# Drag new app to Applications
# Replace old version when prompted

Beta Versions

Join beta program:

1. Enable beta updates:

   • Preferences → Updates → Include beta versions
   • Get early access to new features

2. Beta stability:

   • Beta versions may have bugs
   • Report issues to help improve stability

Security

App Security

Code Signing

• OpenClaw is code signed for security
• Verified by Apple on launch
• Prevents tampering and malware

Sandboxing

• App runs in macOS sandbox
• Limited file system access
• Network access controlled

Secure Storage

• Tokens and API keys stored securely
• macOS Keychain integration
• Biometric protection available

Network Security

TLS/SSL

• All network communications encrypted
• Certificate validation
• Secure connections to APIs

Local Network

• Gateway runs locally by default
• No external network exposure
• Configurable remote access

Best Practices

Performance

• Keep app updated to latest version
• Monitor resource usage regularly
• Clear logs and cache periodically
• Use SSD for better performance

Security

• Enable automatic updates
• Use strong passwords and tokens
• Regular security audits
• Backup configuration regularly

Backup

• Export configuration regularly
• Backup message history if needed
• Store backups securely
• Test restore procedures

Integration

Other Apps

Safari Extension

• Send web content to OpenClaw
• Quick actions from context menu
• Integration with Reading List

Notes App

• Send notes to OpenClaw
• Create messages from notes
• Sync across devices

Calendar Integration

• Schedule messages
• Set reminders for responses
• Calendar event creation

Development

API Access

# Enable API in preferences
# Preferences → Advanced → Enable API

# Use API from other apps
curl -X POST http://localhost:18789/api/v1/message \
  -H "Content-Type: application/json" \
  -d '{"channel": "whatsapp", "target": "+1234567890", "message": "Hello"}'

Plugin Development

• Create custom plugins for OpenClaw
• Extend app functionality
• Share with community

Support

Getting Help

• In-app Help: Help → OpenClaw Help
• Online Documentation: docs.openclaw.dev
• Community: discord.gg/openclaw
• Issues: github.com/openclaw/openclaw/issues

Feedback

• Feature Requests: Help → Send Feedback
• Bug Reports: Help → Report Bug
• Community Forum: discuss.openclaw.dev

---

The OpenClaw macOS app provides a seamless, native experience for managing your AI gateway on macOS. Enjoy the power of OpenClaw with the familiarity of your Mac! 🍎