BlueBubbles Setup

Connect OpenClaw to iMessage via BlueBubbles

iMessage without Mac? BlueBubbles runs on a Mac and relays to OpenClaw. You need one Mac with iMessage—OpenClaw itself can run elsewhere. For direct iMessage on Mac, see iMessage setup.

OpenClaw connects to iMessage via BlueBubbles—an open-source REST API server that bridges iMessage to any client. Use iMessage with OpenClaw even when OpenClaw runs on Linux, a VPS, or another machine. BlueBubbles must run on a physical Mac with iMessage configured (macOS Sequoia 15+ recommended).

Requirements

  • Mac with iMessage — Physical Mac running macOS Sequoia (15) or later
  • BlueBubbles server — Install from bluebubbles.app
  • OpenClaw — Local or remote; reachable via webhook
  • Always-on Mac — The Mac must stay powered on and connected

Quick Setup

  1. Install BlueBubbles on the Mac; enable Web API and set a password
  2. Configure OpenClaw: openclaw onboard and add BlueBubbles channel, or edit config manually
  3. Point BlueBubbles webhooks to your gateway: https://your-gateway/bluebubbles-webhook?password=...
  4. Approve pairing: openclaw pairing approve bluebubbles <CODE>

Configuration

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

Replace serverUrl with your BlueBubbles server address. Ensure the gateway is reachable from the Mac (Tailscale, ngrok, or public URL).

Supported Features

  • Text, media, attachments
  • Reply threading, reactions (tapbacks)
  • Message editing, unsending
  • Group chats, read receipts

BlueBubbles often supports more iMessage features than legacy bridge methods.

Headless Mac Tips

If the Mac runs headless, keep Messages active. Some setups use an AppleScript to "poke" the Messages app periodically. Check BlueBubbles docs for macOS Tahoe (26) considerations—message editing and group icons may have known issues.

Related