BlueBubbles Removal and imsg iMessage Setup

BlueBubbles removal and the imsg iMessage path

BlueBubbles is no longer included with OpenClaw. For iMessage, the official @openclaw/imessage plugin handles everything: the Gateway launches imsg as a subprocess, either directly or via an SSH wrapper, and communicates using JSON-RPC through stdin/stdout. There is no server component, no webhook, and no port involved.

When your configuration still references channels.bluebubbles, switch it over to channels.imessage. The outdated /channels/bluebubbles documentation URL now redirects to Coming from BlueBubbles, where you will find the complete config mapping table and a step-by-step migration checklist.

What changed

• The recommended iMessage setup does not include a BlueBubbles HTTP server, webhook endpoint, REST password, or BlueBubbles plugin runtime.
• OpenClaw accesses and monitors Messages through imsg on the Mac where Messages.app is signed in.
• Standard send, receive, history, and media operations rely on the usual imsg interfaces and macOS permission prompts.
• For advanced functionality (threaded replies, tapbacks, edit, unsend, effects, read receipts, typing indicators, group management), the private API bridge is required: run imsg launch, which demands SIP be turned off.
• Gateways on Linux and Windows can still use iMessage by setting channels.imessage.cliPath to an SSH wrapper that executes imsg on the Mac that is signed in.

What to do

1. Put the official plugin on the Gateway host and restart the Gateway:

   openclaw plugins install @openclaw/imessage
   

2. Install imsg on the Messages Mac and confirm it works:

   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   imsg rpc --help
   

3. Give Full Disk Access and Automation permissions to the process context that runs imsg and OpenClaw.

4. Convert the existing config:

   {
     channels: {
       imessage: {
         enabled: true,
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"],
         groupPolicy: "allowlist",
         groupAllowFrom: ["+15555550123"],
         groups: {
           "*": { requireMention: true },
         },
         includeAttachments: true,
       },
     },
   }
   

5. Restart the gateway and check everything:

   openclaw channels status --probe
   

6. Before removing your old BlueBubbles server, test DMs, groups, attachments, and any private API actions you rely on.

Migration notes

• channels.bluebubbles.serverUrl and channels.bluebubbles.password do not map to anything in iMessage; there is no server to reach or authenticate against.
• allowFrom, groupAllowFrom, groups, includeAttachments, attachmentRoots, mediaMaxMb, textChunkLimit, and actions.* retain their meaning under channels.imessage.
• channels.imessage.includeAttachments remains disabled by default. If you want inbound photos, voice memos, videos, or files delivered to the agent, set it explicitly.
• When using groupPolicy: "allowlist", carry over the old groups block, including any "*" wildcard entry. Group sender allowlists and the group registry act as separate gates; a groups block with entries but no matching chat_id (or no "*") causes the message to be dropped at runtime, and an empty groups block triggers a startup warning even though sender filtering still permits messages.
• ACP bindings that use match.channel: "bluebubbles" need to be updated to "imessage".
• BlueBubbles session keys do not convert to iMessage session keys. Pairing approvals depend on sender handles, so copied allowFrom entries continue to function, but conversation history tied to BlueBubbles session keys will not transfer.

See also

• Coming from BlueBubbles
• iMessage
• Configuration reference - iMessage