BlueBubbles (iMessage)

OpenClaw BlueBubbles channel plugin. Connect to iMessage via BlueBubbles server.

The BlueBubbles plugin connects OpenClaw to Apple's iMessage ecosystem via the BlueBubbles server application. BlueBubbles is an open-source project that runs on a Mac (always-on) and provides an HTTP/WebSocket API to send and receive iMessages. This plugin bridges that API into OpenClaw's channel system, giving your AI agent the ability to chat through iMessage — the holy grail for Apple users who want their assistant in their native messaging app. The architecture requires a Mac running the BlueBubbles server application (macOS Monterey or later), signed into an Apple ID with iMessage enabled. The server exposes an API that the OpenClaw plugin connects to, relaying messages bidirectionally. The Mac must remain powered on and connected to the internet for continuous operation — a Mac Mini is the most common dedicated setup. Setting up iMessage through BlueBubbles is notoriously one of the trickier OpenClaw configurations. Common pain points include Full Disk Access permissions for accessing chat.db, the Mac needing to stay awake and logged in, and message delivery issues when the agent goes to sleep. Multiple Reddit threads document the "iMessage setup hell" experience, though the community consensus is that once working, it's an incredibly satisfying integration. This plugin is for Apple ecosystem users who want their AI assistant accessible through iMessage — the messaging app they already use daily. It's not for casual experimentation — expect to dedicate a Mac (Mini recommended) and invest time in getting permissions right. If you just need a quick setup, Telegram or Discord are far easier alternatives.

Tags: channel, messaging, apple

Use Cases

Personal AI assistant accessible through iMessage — the messaging app already on every iPhone
iMessage-based AI concierge for business owners who communicate with clients primarily via text/iMessage
Automated iMessage responses and smart replies when you're busy or traveling
Family AI assistant that everyone in the household can text via iMessage without installing additional apps
Content marketing assistant accessible over iMessage for quick creative brainstorming on the go

Tips

Use a Mac Mini as a dedicated always-on server — it's the most reliable and cost-effective option for 24/7 iMessage
Create a dedicated macOS user account and Apple ID for the bot to keep it isolated from personal accounts
Disable sleep entirely: System Settings > Energy Saver > Prevent automatic sleeping when display is off
Grant Full Disk Access via System Settings > Privacy & Security — use 'Go to Folder' to navigate if drag/drop doesn't work
Test with Telegram first to verify OpenClaw is working, then add BlueBubbles as a second channel
Enable BlueBubbles' private API for additional features like typing indicators and read receipts
Set up caffeinate or Amphetamine app to ensure the Mac never sleeps

Known Issues & Gotchas

The Mac running BlueBubbles MUST stay awake — disable sleep in System Settings > Energy and keep the lid open or use a Mac Mini
Full Disk Access must be granted to BlueBubbles, Terminal, AND sshd if you're running OpenClaw remotely — this is the #1 setup failure
If messages show 'permissionDenied (code 23)' in logs, it's almost always a Full Disk Access issue with chat.db
Manual 'imsg chats --limit 1' working but gateway failing usually means background process permissions differ from your interactive session
BlueBubbles server and OpenClaw plugin versions must be compatible — check the plugin README for supported BlueBubbles versions
Duplicate plugin/extension errors ('Cannot find module') usually mean conflicting iMessage plugins — delete old plugin folders and clean config
The Mac must be signed into iCloud/iMessage — if the Apple ID gets locked or needs re-auth, messages stop silently
Consider dedicating a separate Apple ID for the bot Mac to avoid disrupting your personal iMessage

Alternatives

imsg (built-in macOS integration)
WhatsApp (built-in)
Telegram (built-in)
OpenBubbles

Community Feedback

I have iMessage configured but it basically sucks - I use BlueBubbles as the server program running on the Mac as the interface between Messages and OpenClaw.
— Reddit r/openclaw

It works fine for iMessages back and forth with my agent when it's awake, but I can't wake it up via iMessage like I can with WhatsApp.
— Reddit r/openclaw

Setting up OpenClaw Jarvis on a dedicated Mac Mini. iMessage via imsg has been a nightmare. Tried BlueBubbles too — installed server, enabled API, got duplicate plugin/extension errors.
— Reddit r/clawdbot

Why is the iMessage factor such a big deal when you can use Telegram and/or WhatsApp on any device? Because iMessage IS my daily driver — it's where all my conversations already happen.
— Reddit r/openclaw

Frequently Asked Questions

Do I need a dedicated Mac for BlueBubbles?

Technically no — you can run BlueBubbles server on your daily Mac. But for reliability, a dedicated Mac Mini running 24/7 is strongly recommended. The Mac must stay awake and signed into iMessage at all times.

Why does iMessage work manually but not through the OpenClaw gateway?

This is almost always a Full Disk Access permission issue. Background processes (like the OpenClaw gateway) need separate FDA grants. Make sure BlueBubbles, Terminal, and sshd all have Full Disk Access in System Settings > Privacy & Security.

Why aren't messages being delivered when my agent is asleep?

The Mac must stay awake for BlueBubbles to receive iMessages in real-time. Disable sleep in System Settings, use caffeinate command, or install Amphetamine to prevent the Mac from sleeping. Unlike WhatsApp, iMessage delivery requires an active connection.

Is BlueBubbles better than imsg for iMessage integration?

BlueBubbles provides a more stable HTTP/WebSocket API layer, while imsg accesses chat.db directly. BlueBubbles is generally more reliable for long-running setups but requires installing additional server software. Both have their permission quirks.

Can I send and receive SMS through BlueBubbles too?

SMS relay requires an iPhone with the same Apple ID signed in and Text Message Forwarding enabled. If you only have a Mac, you'll get iMessage (blue bubbles) but not SMS (green bubbles) unless an iPhone is part of the setup.

Should I just use Telegram instead?

If you don't specifically need iMessage, yes — Telegram is dramatically easier to set up and works on all platforms. BlueBubbles is worth the effort only if iMessage is your primary communication channel and you're willing to maintain a dedicated Mac.

Configuration Examples

Basic BlueBubbles Connection

channels:
  bluebubbles:
    enabled: true
    host: http://localhost:1234
    password: ${BLUEBUBBLES_PASSWORD}

Remote BlueBubbles Server

channels:
  bluebubbles:
    enabled: true
    host: https://my-mac-mini.example.com:1234
    password: ${BLUEBUBBLES_PASSWORD}
    dm:
      policy: pairing
    pollInterval: 5000

BlueBubbles with Contact Allowlist

channels:
  bluebubbles:
    enabled: true
    host: http://localhost:1234
    password: ${BLUEBUBBLES_PASSWORD}
    contacts:
      allowed:
        - '+1234567890'
        - 'user@icloud.com'

Installation

openclaw plugins install @openclaw/bluebubbles