ClawdBot for Mac

💻 System Requirements

Supported macOS Versions

Hardware Requirements

Apple Silicon vs Intel

Apple Silicon (M1/M2/M3):

• ✅ Native ARM64 support
• ✅ Excellent performance
• ✅ Better battery life
• ✅ Perfect for local AI models (Ollama)

Intel Macs:

• ✅ Fully compatible via Rosetta 2
• ⚠️ Slightly slower than Apple Silicon
• ✅ All features work perfectly

🚀 Installation Steps

Method 1: Quick Install (Recommended)

This is the easiest method for most users.

Step 1: Install Homebrew

If you don't have Homebrew installed:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step 2: Install Node.js

brew install node@22

Step 3: Install ClawdBot

npm install -g clawdbot@latest

Step 4: Verify Installation

clawdbot --version

Step 5: Run Onboarding

clawdbot onboard

Method 2: Manual Install

For users who prefer manual control.

Step 1: Download Node.js

Visit nodejs.org and download the macOS installer (v22+).

Step 2: Install Node.js

Open the downloaded .pkg file and follow the installer.

Step 3: Open Terminal

Applications → Utilities → Terminal

Step 4: Install ClawdBot

sudo npm install -g clawdbot@latest

Step 5: Configure

clawdbot onboard

🍺 Using Homebrew (Recommended)

Why Homebrew?

• ✅ Easy package management
• ✅ Automatic dependency handling
• ✅ Simple updates
• ✅ Clean uninstallation

Installing Homebrew

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Add Homebrew to PATH (for Apple Silicon)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# Verify installation
brew --version

Installing Dependencies

# Install Node.js
brew install node@22

# Verify Node.js
node --version  # Should show v22.x.x
npm --version   # Should show 10.x.x or higher

Updating ClawdBot

# Update npm packages
npm update -g clawdbot

# Or reinstall latest
npm install -g clawdbot@latest

🔐 Permissions Setup

Required Permissions

ClawdBot needs certain macOS permissions to function properly:

1. Terminal/iTerm2 Permissions

System Settings → Privacy & Security → Full Disk Access

• Add Terminal.app or iTerm2
• Required for file operations

2. Accessibility (Optional)

System Settings → Privacy & Security → Accessibility

• Required for advanced automation
• Only if using system control features

3. Network Permissions

ClawdBot needs internet access for:

• AI API calls (Claude, GPT-4, etc.)
• Messaging platform connections
• Browser automation

Firewall Configuration

# Allow Node.js through firewall
# System Settings → Network → Firewall → Options
# Add Node.js to allowed applications

iMessage Integration (macOS Only)

ClawdBot can integrate with iMessage on Mac:

# Enable iMessage channel
clawdbot channel add imessage

# Grant permissions when prompted
# System Settings → Privacy & Security → Automation

⚡ macOS Optimization

Performance Tips

1. Use Apple Silicon Optimizations

For M1/M2/M3 Macs, ensure you're using native ARM64 builds:

# Check architecture
uname -m  # Should show "arm64" on Apple Silicon

# If showing x86_64, reinstall Node.js:
brew reinstall node@22

2. Increase File Descriptor Limit

# Add to ~/.zshrc or ~/.bash_profile
ulimit -n 10240

# Apply changes
source ~/.zshrc

3. Optimize for Battery Life

# In config.yaml
performance:
  lowPowerMode: true
  idleTimeout: 300  # seconds

4. Use Unified Memory Efficiently

For Apple Silicon Macs with unified memory:

# Configure memory limits in config.yaml
system:
  maxMemory: "4GB"  # Adjust based on your Mac's RAM

Running as Background Service

Keep ClawdBot running even when Terminal is closed:

Option 1: Using launchd (Recommended)

# Create launch agent
clawdbot service install

# Start service
clawdbot service start

# Check status
clawdbot service status

Option 2: Using screen/tmux

# Install tmux
brew install tmux

# Start ClawdBot in tmux session
tmux new -s clawdbot
clawdbot start

# Detach: Ctrl+B, then D
# Reattach: tmux attach -t clawdbot

Auto-Start on Login

# Add to login items
# System Settings → General → Login Items
# Add ClawdBot service

🔧 Troubleshooting

Common Issues

Issue: "command not found: clawdbot"

Solution:

# Check if npm global bin is in PATH
npm config get prefix

# Add to PATH (add to ~/.zshrc)
export PATH="/usr/local/bin:$PATH"

# For Apple Silicon:
export PATH="/opt/homebrew/bin:$PATH"

# Reload shell
source ~/.zshrc

Issue: Permission Denied

Solution:

# Fix npm permissions
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

# Reinstall ClawdBot
npm install -g clawdbot@latest

Issue: Node.js Version Too Old

Solution:

# Update Node.js via Homebrew
brew upgrade node@22

# Or use nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22

Issue: Port Already in Use

Solution:

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 [PID]

# Or change ClawdBot port in config.yaml
server:
  port: 3001

Issue: Rosetta 2 Required (Intel Apps on Apple Silicon)

Solution:

# Install Rosetta 2
softwareupdate --install-rosetta --agree-to-license

❓ macOS FAQ