Moltbot macOS App Setup
The Moltbot.app is the recommended way to run Moltbot on macOS. It lives in your menu bar and manages the Gateway automatically.
TL;DR
# 1. Install the app (download from releases or brew)
# 2. Launch Moltbot.app from Applications
# 3. Complete onboarding permissions
# 4. Connect your channels:
moltbot channels login
# 5. Verify:
moltbot healthStep-by-Step Guide
1. Install Moltbot.app
Download the latest release from the Moltbot releases page or install via Homebrew:
brew install --cask moltbot2. Launch the App
Open Moltbot.app from your Applications folder. You'll see a new icon appear in your menu bar.
3. Complete Onboarding
The app will guide you through initial setup:
- Permissions checklist - Grant required TCC permissions (Accessibility, Automation, etc.)
- Gateway setup - The app will start the bundled Gateway automatically
- Initial configuration - Set your preferred AI model and basic settings
moltbot setup
moltbot channels login
moltbot gateway4. Verify Gateway Status
In the menu bar app, check that:
- Gateway Status: Should show "Running" or "Local"
- Connection Mode: Should be "Local"
You can also verify via CLI:
moltbot health5. Connect Your Channels
Link messaging platforms using the CLI:
moltbot channels loginThis interactive command will:
- Show available channels (WhatsApp, Telegram, Discord, Slack)
- Guide you through authentication for each
- Store credentials securely in ~/.clawdbot/credentials/
For example, to connect WhatsApp:
moltbot channels login whatsappScan the QR code with your phone, and you're connected!
Gateway Management
Understanding Gateway Modes
| Mode | Description | Use Case |
|---|---|---|
| Bundled | App runs its own Gateway | Default, easiest |
| Local | App connects to external Gateway | Development |
| Remote | App connects to remote server | Advanced |
Checking Gateway Status
From the menu bar, click the Moltbot icon and view "Gateway Status". Or from CLI:
moltbot healthRestarting the Gateway
If you encounter issues, click the Moltbot menu bar icon and select "Restart Gateway". Or via CLI:
moltbot gateway restartCommon Issues
macOS requires explicit permissions for automation. Go to System Settings → Privacy & Security → Accessibility and add Moltbot.app to the allowed list.
Check if the port is already in use. Kill any conflicting process or change the Gateway port in settings.
lsof -i :18789Ensure both app and CLI are using the same port. Default WebSocket: ws://127.0.0.1:18789. Check ~/.clawdbot/moltbot.json for port settings.
Where Things Live
| What | Location |
|---|---|
| Config | ~/.clawdbot/moltbot.json |
| Credentials | ~/.clawdbot/credentials/ |
| Sessions | ~/.clawdbot/agents/<agentId>/sessions/ |
| Logs | /tmp/moltbot/ |
| Workspace | ~/clawd |
Updating the App
Via Homebrew
brew upgrade moltbotManual Update
- Download the latest release
- Replace the app in /Applications
- Relaunch
Uninstalling
To completely remove Moltbot:
# Remove the app
brew uninstall moltbot
# Or delete from /Applications
# Optional: Remove config and data
rm -rf ~/.clawdbot
rm -rf ~/clawd