name: bluebubbles-setup
description: |
Set up BlueBubbles for iMessage integration with OpenClaw. Use when:
(1) configuring iMessage on macOS, (2) troubleshooting BlueBubbles webhooks,
(3) fixing config validation errors, (4) setting up allowlists and policies.
Covers Full Disk Access, Cloudflare tunnels, and OpenClaw channel config.
category: development
user-invocable: true

BlueBubbles Setup

Configure BlueBubbles for iMessage integration with OpenClaw on macOS.

Prerequisites

Step 1: Install BlueBubbles Server

1. Download from bluebubbles.app/downloads/server
2. Move to Applications folder
3. Right-click and select "Open" to bypass Gatekeeper
4. Grant Full Disk Access when prompted

Granting Full Disk Access

If BlueBubbles shuts down requesting Full Disk Access:

1. Open System Settings
2. Go to Privacy & Security
3. Click Full Disk Access
4. Click the + button
5. Add BlueBubbles from Applications
6. Toggle it ON
7. Reopen BlueBubbles

Step 2: Configure BlueBubbles Server

Required Settings

Server Settings

In BlueBubbles Settings, find:

Note the Server URL and Password. You need these for OpenClaw.

Step 3: Configure OpenClaw

Add BlueBubbles channel to OpenClaw config:

{
  "channels": {
    "bluebubbles": {
      "enabled": true,
      "serverUrl": "https://your-cloudflare-url.trycloudflare.com",
      "password": "your-server-password",
      "webhookPath": "/bluebubbles-webhook",
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567"],
      "groupPolicy": "disabled",
      "sendReadReceipts": true
    }
  }
}

Policy Options

Critical Config Rule

Open policies require wildcards:
- dmPolicy: "open" requires allowFrom: ["*"]
- groupPolicy: "open" requires groupAllowFrom: ["*"]

Forgetting the wildcard crashes the gateway.

Fix with: openclaw doctor --fix

Step 4: Set Up Webhook

In BlueBubbles API & Webhooks section:

1. Click to add a new webhook
2. Set URL to: http://localhost:18789/bluebubbles-webhook?password=YOUR_PASSWORD
3. Enable All Events
4. Save the webhook

The webhook connects BlueBubbles to OpenClaw.

Step 5: Verify Connection

openclaw status --deep

Should show:

Channels
┌─────────────┬─────────┬────────┬─────────────┐
│ Channel     │ Enabled │ State  │ Detail      │
├─────────────┼─────────┼────────┼─────────────┤
│ BlueBubbles │ ON      │ OK     │ configured  │
└─────────────┴─────────┴────────┴─────────────┘

Troubleshooting

Gateway Crashes on Startup

Symptom: Gateway exits immediately after config change.

Cause: Open policy without wildcard.

Fix:

openclaw doctor --fix
openclaw gateway restart

Messages Not Received

Symptom: Send a message but OpenClaw does not respond.

Check:
1. Is the sender in allowFrom?
2. Is the webhook URL correct?
3. Is BlueBubbles webhook showing in the list?

Debug:

tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep -i bubble

Private API Not Enabled

Symptom: Error about "Private API not enabled."

Impact: Read receipts and typing indicators will not work.

Resolution: This is optional. Messaging still works without it.

Pairing Codes

When using dmPolicy: "pairing":
- New contacts receive a pairing code
- Approve with: openclaw pairing approve bluebubbles CODE
- List pending: openclaw pairing list bluebubbles

Security Notes

• Keep the server password secret
• Use allowlists in production
• Avoid dmPolicy: "open" unless needed
• Consider groupPolicy: "disabled" to prevent unintended group responses

Skill Chaining