Installing Clawdbot on macOS

Clawdbot offers native support on macOS through Clawdbot.app, a menu bar application designed for user-friendly local deployment. This guide covers installation on macOS 14 Sonoma or later. Prerequisites: Node.js (v18+), npm, and Git. If not installed, use Homebrew: brew install node git.

Installation Steps

Step 1: Download and Install Clawdbot.app

• Download the latest macOS DMG file from clawd.bot or GitHub
• Open the DMG and drag Clawdbot.app to your Applications folder
• Launch Clawdbot.app (it will appear in your menu bar)

Step 2: Complete Onboarding and Permissions

• The app will guide you through the setup wizard on first launch
• Grant required permissions (TCC prompts): Screen Recording, Accessibility, Notifications, and Automation. These are macOS security requirements for browser control and messaging integration
• Ensure Gateway is set to "Local" mode and shows green status (running)

Step 3: Install CLI Tools

• The app will prompt you to install the global CLI. Click the install button in General settings, or manually run: npm install -g clawdbot
• Verify installation by opening Terminal and running: clawdbot --version
• If the command fails, check npm permissions (may need sudo) or verify Homebrew PATH configuration

Step 4: Configure Gateway and Models

• In the app, set your API keys (Claude or OpenAI)
• Run clawdbot setup to configure messaging channels (WhatsApp, Telegram, etc.)
• For local models like Ollama, install Ollama first and specify it in your configuration

Step 5: Connect Messaging Platforms and Test

• Add channels in the app or CLI (e.g., scan WhatsApp QR code or enter Telegram token)
• Test by sending a message to Clawdbot (e.g., "hello") and confirm response

Developer Setup (Optional): Initialize Git submodules (git submodule update --init --recursive), install dependencies (npm install), and build the app (npm run build:mac). The entire process typically takes 5-15 minutes. Many users report macOS installation is simpler than Windows. For cloud deployment, macOS VMs (like Lume sandbox) are available, though local macOS is optimal for iMessage integration.

Common Issues and Solutions

While Clawdbot is relatively stable on macOS, users may encounter permission, dependency, or configuration issues. Below are common problems based on community feedback and GitHub issues (as of early 2026), sorted by frequency. Many can be resolved by restarting the app or checking logs. For persistent issues, join the official Discord.

Issue	Description	Solution
Installation fails or CLI not detected	npm install -g clawdbot errors, or app can't find CLI. Usually permission or PATH issues.	Run sudo npm install -g clawdbot; ensure /usr/local/bin is in PATH (echo $PATH); reinstall Node.js via Homebrew.
App crashes or syntax highlighting errors	App crashes on launch with CodeTokenizer errors in logs (reported in 2026 updates).	Update to latest version from GitHub; clear cache (delete ~/Library/Application Support/Clawdbot); report issue on GitHub.
Conflicting installations	Menu Bar App and CLI running simultaneously cause service conflicts (port occupation).	Uninstall one: run npm uninstall -g clawdbot to remove CLI, or delete app; restart computer; ensure only one Gateway is active.
Repeated permission prompts	TCC (Transparency, Consent, and Control) permissions not granted, causing browser or messaging failures.	System Settings > Privacy & Security > Accessibility/Automation/Screen Recording > Enable Clawdbot; restart app.
Missing dependencies or build failures	In developer mode, npm install errors (e.g., missing Xcode).	Install Xcode Command Line Tools (xcode-select --install); update npm (npm update); check prerequisites like Python/Rust.
Security concerns or potential compromise	Concerns about data leaks or malicious behavior, especially from unofficial sources.	Download only from official website/GitHub; run in sandbox mode; check system logs (Console.app); avoid granting unnecessary permissions.
WhatsApp/messaging channel connection errors	QR code scan fails or API issues.	Ensure phone WhatsApp is updated; reset channel config (clawdbot reset whatsapp); check network/firewall.
Gateway not running or local mode fails	Gateway shows red status, won't start.	Check port conflicts (default 18791); kill processes (killall clawdbot); restart computer or app.
External service dependency issues	LLM API rate limits or ElevenLabs voice failures.	Configure backup models (e.g., local Ollama); optimize prompts to reduce calls; verify API key validity.
Compatibility issues after updates	App incompatible after macOS updates.	Wait for official patch; roll back to previous version; use Docker container (non-native but bypasses OS issues).

Most issues occur during initial setup, and community feedback indicates 80% are self-resolvable. If you encounter specific errors, share logs for further analysis.