macOS Setup

Overview

macOS is fully supported and provides the best experience for iMessage integration.

Requirements

macOS 10.15 (Catalina) or later
Python 3.10+
Homebrew (recommended)

Installation

Install Homebrew (if not already installed)

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

Install Python
Terminal window
```
brew install python@3.11
```

Clone Clawdbot

git clone https://github.com/polvoazul/clawdbot.git
cd clawdbot

Create virtual environment

python3 -m venv venv
source venv/bin/activate

Install dependencies
Terminal window
```
pip install -r requirements.txt
```

Configure

cp .env.example .env
# Edit .env with your settings

Running as a Service

Using launchd

Create ~/Library/LaunchAgents/com.clawdbot.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.clawdbot</string>
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/clawdbot/venv/bin/python</string>
        <string>-m</string>
        <string>clawdbot</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/path/to/clawdbot</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/clawdbot.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/clawdbot.error.log</string>
</dict>
</plist>

Load the service:

launchctl load ~/Library/LaunchAgents/com.clawdbot.plist

Managing the Service

# Start
launchctl start com.clawdbot

# Stop
launchctl stop com.clawdbot

# Unload
launchctl unload ~/Library/LaunchAgents/com.clawdbot.plist

iMessage Integration

macOS enables native iMessage support:

Grant Terminal Full Disk Access
Grant Accessibility permissions
Enable in .env:
Terminal window
```
IMESSAGE_ENABLED=true
```

See iMessage Setup for details.

Troubleshooting

“Permission denied” accessing Messages

System Preferences → Security & Privacy → Full Disk Access
Add Terminal or your IDE

Python command not found

# Add to ~/.zshrc
export PATH="/usr/local/opt/python@3.11/bin:$PATH"