How to Connect OpenClaw to BlueBubbles

Prerequisites

• ✓A Mac running the BlueBubbles server via the helper app from bluebubbles.app (recommended/tested: macOS Sequoia 15; macOS Tahoe 26 works but edit and some group icon updates are broken).
• ✓An existing OpenClaw gateway installation with access to edit its configuration and restart the gateway.
• ✓Network connectivity from the OpenClaw gateway to the BlueBubbles REST API base URL (for example, http://192.168.1.100:1234) and from BlueBubbles back to the gateway’s public webhook URL.
• ✓A BlueBubbles API password configured in the BlueBubbles server settings so OpenClaw can authenticate REST calls and webhooks.

Steps

1. 1

   Install and configure the BlueBubbles server on macOS

   app to OpenClaw over HTTP. During setup, enable the web API and set a password, since OpenClaw uses that password for both outbound REST calls and webhook authentication.

   textCopy

   1.   Install the BlueBubbles server on your Mac (follow the instructions at [bluebubbles.app/install](https://bluebubbles.app/install)).
   2.   In the BlueBubbles config, enable the web API and set a password.

2. 2

   Onboard the BlueBubbles channel using the OpenClaw wizard

   Use the interactive onboarding flow so OpenClaw can prompt you for the BlueBubbles server URL, password, and webhook path. This is the quickest way to get a working config without hand-editing JSON, and it also lets you set DM policy and allow lists up front.

   bashCopy

   openclaw onboard

3. 3

   Configure BlueBubbles connection details in OpenClaw

   If you prefer explicit configuration or want to version-control your setup, define the BlueBubbles channel block directly in your gateway config. This block enables the channel and tells OpenClaw where the BlueBubbles REST API lives, what password to use, and which webhook path to expose.

   jsonCopy

   {
     channels: {
       bluebubbles: {
         enabled: true,
         serverUrl: "http://192.168.1.100:1234",
         password: "example-password",
         webhookPath: "/bluebubbles-webhook",
       },
     },
   }

4. 4

   Add the BlueBubbles channel via CLI for scripted setups

   You can also register the BlueBubbles channel in one command, which is useful for automation or ephemeral environments. This wires in the HTTP URL and password; the webhook path defaults to /bluebubbles-webhook unless you override it in the config file.

   bashCopy

   openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>

5. 5

   Start the gateway and approve pairing requests

   Once the channel is configured, start or restart your OpenClaw gateway so it registers the BlueBubbles webhook handler and begins the DM pairing flow. With the default pairing policy, unknown senders get a pairing code that you must approve from the CLI before the agent responds.

   bashCopy

   openclaw pairing list bluebubbles
   openclaw pairing approve bluebubbles <CODE>

6. 6

   Keep Messages.app alive on VM or headless macOS setups

   app can go idle and stop delivering events until you foreground it. Use the provided AppleScript to poke Messages every 5 minutes so BlueBubbles keeps receiving events without stealing focus.

   textCopy

   try
     tell application "Messages"
       if not running then
         launch
       end if
   
       -- Touch the scripting interface to keep the process responsive.
       set _chatCount to (count of chats)
     end tell
   on error
     -- Ignore transient failures (first-run prompts, locked session, etc).
   end try

7. 7

   Install a LaunchAgent to run the Messages keepalive script

   Create a LaunchAgent plist so macOS runs the AppleScript on login and every 300 seconds. This keeps Messages responsive and logs output to /tmp so you can debug if events stop flowing.

   textCopy

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
     <dict>
       <key>Label</key>
       <string>com.user.poke-messages</string>
   
       <key>ProgramArguments</key>
       <array>
         <string>/bin/bash</string>
         <string>-lc</string>
         <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
       </array>
   
       <key>RunAtLoad</key>
       <true/>
   
       <key>StartInterval</key>
       <integer>300</integer>
   
       <key>StandardOutPath</key>
       <string>/tmp/poke-messages.log</string>
       <key>StandardErrorPath</key>
       <string>/tmp/poke-messages.err</string>
     </dict>
   </plist>

8. 8

   Load the LaunchAgent so the keepalive starts running

   After saving the plist under ~/Library/LaunchAgents, load it with launchctl so macOS starts running the script on schedule. The unload call is safe even if the agent is not yet loaded and lets you reload changes without rebooting.

   bashCopy

   launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
   launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist

9. 9

   Enable contact enrichment and mention gating for groups

   Once basic messaging works, you can improve group UX by enriching participants from Contacts and requiring mentions in noisy group chats. These flags let you control when the agent responds and how group members appear in context.

   jsonCopy

   {
     channels: {
       bluebubbles: {
         enrichGroupParticipantsFromContacts: true,
       },
     },
   }
   
   {
     channels: {
       bluebubbles: {
         groupPolicy: "allowlist",
         groupAllowFrom: ["+15555550123"],
         groups: {
           "*": { requireMention: true }, // default for all groups
           "iMessage;-;chat123": { requireMention: false }, // override for specific group
         },
       },
     },
   }

10. 10

    Turn on advanced actions and tune streaming behavior

    BlueBubbles supports rich actions like reactions, edit, unsend, and media sending, plus options for read receipts and block streaming. Enable only the actions you trust and adjust streaming so responses arrive as single messages or in blocks that match your UX.

    jsonCopy

    {
      channels: {
        bluebubbles: {
          actions: {
            reactions: true, // tapbacks (default: true)
            edit: true, // edit sent messages (macOS 13+, broken on macOS 26 Tahoe)
            unsend: true, // unsend messages (macOS 13+)
            reply: true, // reply threading by message GUID
            sendWithEffect: true, // message effects (slam, loud, etc.)
            renameGroup: true, // rename group chats
            setGroupIcon: true, // set group chat icon/photo (flaky on macOS 26 Tahoe)
            addParticipant: true, // add participants to groups
            removeParticipant: true, // remove participants from groups
            leaveGroup: true, // leave group chats
            sendAttachment: true, // send attachments/media
          },
        },
      },
    }
    
    {
      channels: {
        bluebubbles: {
          sendReadReceipts: false, // disable read receipts
        },
      },
    }
    
    {
      channels: {
        bluebubbles: {
          blockStreaming: true, // enable block streaming (off by default)
        },
      },
    }

Configuration

Troubleshooting

openclaw pairing list bluebubbles
openclaw pairing approve bluebubbles <code>

{
  channels: {
    bluebubbles: {
      actions: {
        edit: false,
      },
    },
  },
}

openclaw status --all
openclaw status --deep

Frequently asked questions