Connecting OpenClaw to iMessage via BlueBubbles

Why BlueBubbles

If you previously used OpenClaw's native iMessage integration (based on AppleScript bridging), you may have noticed its limitations: polling delays, inability to send rich media, sensitivity to macOS system updates, and more. Starting from the latest version of OpenClaw, the legacy iMessage integration has been officially deprecated, and BlueBubbles is the officially recommended alternative for connecting to iMessage.

BlueBubbles is an open-source project that runs a server on macOS, exposing iMessage's full functionality through a REST API. OpenClaw interacts with iMessage through this API, offering significant advantages over the old approach:

• REST API architecture: Stable and reliable, no longer dependent on fragile AppleScript bridging
• Full feature support: Send and receive text, images, attachments, Tapback reactions, and more
• Real-time message delivery: Instant notifications via WebSocket, eliminating polling delays
• Native integration: OpenClaw has built-in BlueBubbles channel support — no extra plugins needed
• Active maintenance: The BlueBubbles community is active and keeps pace with macOS updates

Prerequisites

Before getting started, confirm the following:

Unlike the legacy approach, OpenClaw itself does not need to run on macOS. You can run OpenClaw on a Linux VPS while using a Mac mini as the BlueBubbles server. This decoupled architecture offers greater flexibility.

Step 1: Install and Configure the BlueBubbles Server

1.1 Download BlueBubbles

Visit the official BlueBubbles website to download the macOS server application, or install via Homebrew:

brew install --cask bluebubbles

1.2 Initial Setup

After launching BlueBubbles for the first time, follow the setup wizard:

1. Grant BlueBubbles Full Disk Access (System Settings > Privacy & Security > Full Disk Access)
2. Make sure Messages.app is signed in with your Apple ID
3. Configure a server password in BlueBubbles (you'll need to enter this in the OpenClaw configuration later)

1.3 Get the REST API Address

Once BlueBubbles is running, it will display the server's local address in the menu bar, typically:

http://localhost:1234

If OpenClaw is running on a different machine, you need to ensure this port is remotely accessible. This can be achieved through:

• LAN direct connection: Ensure both machines are on the same network, using the Mac's LAN IP
• Reverse proxy: Use Nginx or Cloudflare Tunnel to expose the API
• BlueBubbles' built-in Ngrok/Dynamic DNS functionality

Step 2: Configure OpenClaw to Connect to BlueBubbles

2.1 Add the Channel

Run the following command to add the BlueBubbles channel:

openclaw channel add bluebubbles

The wizard will guide you through entering the BlueBubbles server address and password.

2.2 Manual Configuration

You can also directly edit ~/.config/openclaw/openclaw.json5:

{
  channels: {
    bluebubbles: {
      enabled: true,

      // BlueBubbles server address
      serverUrl: "http://192.168.1.100:1234",

      // BlueBubbles server password
      password: "your-server-password",

      // Security configuration
      security: {
        allowedIdentifiers: [
          "+8613800138000",
          "[email protected]"
        ],
        groupChatEnabled: false,
        allowUnknown: false
      },

      // Trigger configuration
      trigger: {
        autoReply: true,
        keywords: [],
        groupTrigger: "keyword",
        groupKeywords: ["@AI", "/ask"]
      },

      // Message configuration
      message: {
        maxLength: 10000,
        sendTypingIndicator: true,
        sendReadReceipts: true,
        supportAttachments: true
      }
    }
  }
}

2.3 Start and Verify

openclaw restart

# View BlueBubbles channel logs
openclaw logs -f --component channel:bluebubbles

Upon successful connection, you should see:

[INFO] [channel:bluebubbles] BlueBubbles connection established
[INFO] [channel:bluebubbles] Server version: 1.x.x
[INFO] [channel:bluebubbles] WebSocket connected, waiting for real-time messages...
[INFO] [channel:bluebubbles] Allowed contacts: 2

Migrating from the Legacy iMessage Integration

If you were previously using the old AppleScript-based approach, migration is straightforward:

1. Stop the OpenClaw service: openclaw stop
2. Set channels.imessage.enabled to false in the configuration file
3. Follow the steps above to configure the BlueBubbles channel
4. Restart: openclaw up

The legacy imessage channel configuration can remain in the configuration file — just make sure enabled is set to false. If OpenClaw detects that the legacy iMessage channel is still enabled at startup, it will output a deprecation warning and suggest switching to BlueBubbles.

Message Type Support Comparison

The BlueBubbles approach is a major improvement over the legacy integration:

Common Troubleshooting

Cannot connect to the BlueBubbles server

# Test network connectivity
curl http://192.168.1.100:1234/api/v1/server/info -H "Authorization: Bearer your-password"

If it returns server information JSON, both the network and authentication are fine. Otherwise, check your firewall settings and verify the password is correct.

Mac sleep causes disconnection

The Mac serving as the server must not enter sleep mode. Disable automatic sleep in System Settings:

System Settings > Energy > Prevent automatic sleeping

For a Mac mini, it is recommended to connect a display or use an HDMI dummy plug to prevent the system from reducing performance due to the absence of a display.

Connection issues after a BlueBubbles update

BlueBubbles updates may change API behavior. If this occurs, make sure OpenClaw is also updated to the latest version:

openclaw update
openclaw restart

Summary

BlueBubbles is the officially recommended iMessage connection solution for OpenClaw, fully replacing the deprecated legacy AppleScript integration. It provides a stable, feature-complete iMessage experience through REST API and WebSocket. Key takeaways:

• Migrate now: The legacy iMessage integration is deprecated and may be removed in future versions
• Flexible architecture: OpenClaw and the BlueBubbles server can be deployed separately
• Full-featured: Supports images, attachments, Tapback, read receipts, and more
• Set up an allowlist: As with all channels, configuring a contact allowlist is recommended to protect privacy and API quotas
• Keep the Mac running: Ensure the Mac running BlueBubbles does not sleep or shut down