Connect Openclaw to BlueBubbles

Table of contents: [Show]

Quick Start

BlueBubbles bridges iMessage to Openclaw, letting your agent send and receive messages through Apple's ecosystem. This guide covers setup in under 5 minutes.

Prerequisites

A Mac signed into iMessage
BlueBubbles server installed on that Mac
Openclaw Gateway running

Step 1: Configure BlueBubbles Server

Download and install the BlueBubbles server on your Mac
Open BlueBubbles settings and enable the Web API
Set a secure API password
Note your Mac's IP address (e.g., http://192.168.1.100:1234)

Step 2: Interactive Setup (Recommended)

Run the Openclaw onboarding wizard:

Openclaw onboard

Or add the channel directly:

Openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password your-api-password

Step 3: Manual Configuration

Edit your ~/.Openclaw/Openclaw.json:

{
  "channels": {
    "bluebubbles": {
      "enabled": true,
      "serverUrl": "http://192.168.1.100:1234",
      "password": "your-api-password",
      "webhookPath": "/bluebubbles-webhook"
    }
  }
}

Step 4: Restart and Test

Restart your Openclaw Gateway:

Openclaw gateway restart

Send a test message to your iMessage account
Your Openclaw agent should receive and respond

Working Example

User sends: "Remind me to call mom at 5pm"

Openclaw receives via BlueBubbles webhook:

{
  "text": "Remind me to call mom at 5pm",
  "handle": "+1234567890",
  "isFromMe": false
}

Troubleshooting

Issue	Fix
Connection refused	Verify Mac firewall allows BlueBubbles port
Messages not received	Check webhookPath matches your reverse proxy config
Auth errors	Confirm password matches BlueBubbles server settings

Best Practices

Use a static IP or Tailscale for your Mac to avoid IP changes
Enable BlueBubbles auto-start on Mac login
Consider iOS deployment for mobile agent access

Related: iMessage Setup Guide