OpenClaw + BlueBubbles: iMessage on Any Device With AI [Guide]

BlueBubbles solves the single biggest limitation of OpenClaw's native iMessage integration: it's tied to one Mac. Teams running shared agents, developers building cross-device workflows, anyone who needs iMessage automation available beyond a single machine — this is the path. The Mac still does the heavy lifting, but BlueBubbles makes it a server.

What Is BlueBubbles?

BlueBubbles is an open-source self-hosted server application that runs on macOS. It connects to your Messages app, captures iMessages in real time, and exposes them via a REST API and WebSocket interface. Client apps — including OpenClaw — connect to the BlueBubbles server to send and receive iMessages without running on the Mac itself.

The project started in 2021 as a way to bring iMessage to Android and has grown into a platform used by thousands of developers. As of early 2025, it's the most stable self-hosted iMessage relay available, with an active community and regular updates tracking macOS releases.

Critically: BlueBubbles does not break Apple's ToS in the same way that commercial iMessage relay services might. It runs on hardware you own, using an Apple ID you control, in a way that's architecturally similar to how you'd access your Mac remotely. That said, Apple doesn't officially support or endorse it — proceed knowing this is community-built infrastructure.

Why Use BlueBubbles With OpenClaw

Three concrete reasons this setup beats the direct approach for anything beyond personal use.

1. Cross-device agent access. Your OpenClaw instance doesn't have to run on the Mac where Messages lives. Run OpenClaw on a Linux server, a Windows machine, or a cloud VM — it connects to BlueBubbles over HTTP and processes iMessages from anywhere on your network.

2. Group chat support. BlueBubbles exposes full group chat data through its API. The direct macOS setup struggles with group threads because the database schema is different and AppleScript doesn't handle them cleanly. With BlueBubbles, group messages arrive with a group_id field and full participant lists, making multi-user agent interactions viable.

3. Event-driven architecture. Instead of OpenClaw polling the Messages database every few seconds, BlueBubbles pushes events via webhook when messages arrive. This means faster response times and no polling overhead. Webhook delivery is near-instant after the message hits the Mac.

BlueBubbles Server Setup on Mac

Download BlueBubbles from the official site at bluebubbles.app. Install the DMG like any other macOS app. First launch will request several permissions — grant all of them, including Full Disk Access, Accessibility, and Contacts if prompted.

Once open, the BlueBubbles interface walks you through initial setup. The key configuration decisions:

1. Server URL — For local network use, this is your Mac's local IP (e.g., http://192.168.1.50:1234). For remote access, use BlueBubbles' proxy service or set up your own reverse proxy.
2. Password — Set a strong password. This protects the API. OpenClaw will use this as the BLUEBUBBLES_PASSWORD env var.
3. Private API — Enable this for full feature support including reactions and typing indicators. Requires an additional macOS helper app — follow the in-app instructions.

After setup, BlueBubbles shows a green "Server Running" indicator. The server URL is displayed in the top bar — copy it, you'll need it in the next step.

Webhook URL Configuration

BlueBubbles pushes message events to a webhook URL that you specify. OpenClaw provides this webhook endpoint through its gateway.

First, get your OpenClaw gateway URL:

openclaw gateway url
# Output: https://gateway.openclaw.io/webhooks/YOUR-AGENT-ID

In BlueBubbles, go to Settings → Webhooks → Add Webhook. Paste your OpenClaw gateway URL. Select the events to subscribe to:

• new-message — fires on every incoming iMessage
• updated-message — fires when a message is edited or reacted to
• group-name-change — optional, for group chat management

Save the webhook. BlueBubbles will send a test event to confirm the URL is reachable. You should see a confirmation in the OpenClaw gateway logs within 5 seconds.

Connecting OpenClaw to BlueBubbles

With BlueBubbles running and the webhook configured, connecting OpenClaw is a single command with a few required environment variables.

# Set environment variables
export BLUEBUBBLES_URL="http://192.168.1.50:1234"
export BLUEBUBBLES_PASSWORD="your-bluebubbles-password"

# Add the BlueBubbles channel
openclaw channels add bluebubbles \
  --url "$BLUEBUBBLES_URL" \
  --password "$BLUEBUBBLES_PASSWORD" \
  --group-chats true

# Verify connection
openclaw channels status bluebubbles

The --group-chats true flag tells OpenClaw to process group iMessage threads in addition to 1-on-1 conversations. Without it, group messages are ignored even if BlueBubbles sends them.

A successful connection outputs:

BlueBubbles channel connected.
Server: http://192.168.1.50:1234
Status: active
Group chats: enabled
Webhook registered: https://gateway.openclaw.io/webhooks/YOUR-AGENT-ID

Testing the Integration

Send a test iMessage from any device to your Mac's Apple ID. Watch OpenClaw logs for the incoming event:

openclaw logs --channel bluebubbles --follow

# Expected output:
# [BlueBubbles] Webhook received: new-message from +1-555-0100
# [BlueBubbles] Message: "test message"
# [Agent] Routing through pipeline...
# [Agent] Reply sent via BlueBubbles API

If the webhook fires but OpenClaw doesn't reply, check that your agent pipeline has a handler for the bluebubbles channel in your openclaw.config.yaml. The channel key must match exactly.

Advantages Over Direct iMessage Setup

Here's where the two approaches genuinely differ in practice — not just on paper.

• No polling overhead: BlueBubbles pushes events; the direct setup polls every 2–5 seconds. Under heavy message volume, polling causes noticeable latency.
• Group chat works: Tested with groups of up to 20 participants in an internal team setup. Messages route cleanly with correct group IDs.
• Runs anywhere: OpenClaw can live on a $5/month cloud server. Only BlueBubbles server needs the Mac.
• Better attachment handling: BlueBubbles exposes attachment metadata through the API. The direct setup has no clean path for handling image or file attachments in agent logic.
• Community support: The BlueBubbles Discord has a dedicated channel for OpenClaw integrations with active maintainers as of early 2025.

Frequently Asked Questions

Does BlueBubbles work without a Mac?

No. BlueBubbles requires a Mac as the server because iMessage only runs on Apple hardware. The benefit is that OpenClaw and client apps connect to the BlueBubbles server, so your other devices (Windows, Linux, iPhone) can interact with iMessage through it.

What port does BlueBubbles use and do I need to port forward?

BlueBubbles defaults to port 1234. For local network setups, no port forwarding is needed. For remote access or cloud deployment, you'll need to expose this port or use the BlueBubbles proxy service. OpenClaw connects over HTTP to the webhook URL you configure.

Is BlueBubbles free to use with OpenClaw?

BlueBubbles is open-source and free to self-host. The BlueBubbles organization offers an optional proxy service for a small fee if you need remote access without port forwarding. OpenClaw's BlueBubbles channel support is included in all plan tiers.

Can OpenClaw via BlueBubbles handle group iMessage chats?

Yes. BlueBubbles exposes group chat data through its API, which OpenClaw can consume. You need to configure the group_chats: true flag in your channel config. Individual group messages arrive with a group_id field for routing.

What happens if the BlueBubbles server goes offline?

OpenClaw will log connection errors and pause message processing. Incoming iMessages still arrive on your Mac's Messages app — they just won't trigger agent responses until BlueBubbles is back online. OpenClaw auto-reconnects once the server is reachable.

How is the BlueBubbles setup different from the direct iMessage channel?

Direct iMessage uses AppleScript and local database polling — simpler but single-machine only. BlueBubbles adds an HTTP API layer on top of iMessage, so any networked device can connect. Setup takes longer but adds group chat support and multi-client access.