Moving OpenClaw iMessage from BlueBubbles to imsg

BlueBubbles support was removed from OpenClaw, and iMessage now works only through the official iMessage plugin, which drives the imsg command-line tool over JSON-RPC and reaches the same private API surface BlueBubbles had: reactions, edits, unsend, threaded replies, send with effect, native polls, group management and attachments. One CLI binary replaces the server, the client app and the webhook plumbing. The docs give a migration guide from an old BlueBubbles config, the only supported path, and note that a leftover BlueBubbles block is inert on current OpenClaw. Here is the checklist, what imsg does, the pre-flight checks, and the config translation.

The checklist

• Install the official plugin and check the application result, verify imsg directly on the Mac that runs Messages with the chats, history, send and RPC help commands, copy the behaviour keys from the old block to the new one, DM policy, allow-from, group policy, group allow-from, groups, include-attachments, attachment roots, media cap, text chunk limit and actions, and drop the transport keys that no longer exist, the server URL, the password and webhook URLs.
• If the Gateway is not on the Messages Mac, set the CLI path to the absolute Gateway-local path of an SSH wrapper, keep the database path absolute on that Mac, and set the remote host for complex wrappers, since OpenClaw only auto-detects the simple transparent wrapper shape.
• Enable the iMessage block, probe the channel status, which hot-reloads and needs a running Gateway, then test one DM, one allowed group, attachments if enabled, and every private-API action the agent will use, before deleting the BlueBubbles server and the old block.
• Remote imsg at the version the docs name has two narrow RPC limits: poll votes must use the poll option id rather than an index or text, and attachment replies cannot target a non-zero message part index; local behaviour is unchanged.

One CLI binary replaces the BlueBubbles server + client app + webhook plumbing: no REST endpoint, no webhook auth.

What imsg does

imsg is a local macOS CLI for Messages: OpenClaw starts its RPC mode as a child process and talks JSON-RPC over standard input and output, with no HTTP server, webhook URL, daemon, launch agent or port. Reads come from the Messages chat database over a read-only SQLite handle, live inbound messages come from a watch command that follows filesystem events with a polling fallback, sends use Messages automation for text and files, and advanced actions use a launch command that injects the imsg helper into Messages, which is what unlocks read receipts, typing indicators, rich sends, edit, unsend, threaded replies, tapbacks, polls and group management. Linux builds can inspect a copied database but cannot send, watch or drive Messages, so for OpenClaw the CLI runs on the signed-in Mac or through an SSH wrapper to it. Before changing config, install or upgrade imsg with Homebrew, grant Full Disk Access to whichever parent process launches it when the chats command fails to open the database, verify read, watch, send and RPC through the same wrapper or user context OpenClaw will use, watch for the automation error that means the permission landed on the SSH keygen wrapper, enable the private-API bridge with the launch command, which needs SIP disabled, and after enabling the channel confirm the probe reports the account working with the private API available; snapshot the config file first.

The translation table

• The behaviour keys keep their names and semantics: enabled, DM policy with its pairing default, allow-from with the same handle formats though pairing-store approvals do not transfer, group policy with its allowlist default, group allow-from where an explicitly empty list blocks all groups, groups where the wildcard entry copies verbatim while per-group entries are re-keyed by numeric chat id, read receipts, include-attachments which stays off by default and silently drops inbound media until set, attachment roots, and the media cap, whose iMessage default is sixteen megabytes against BlueBubbles’ eight.
• The transport keys are removed, the server URL and password, and three new ones appear: the CLI path, the database path override which for SSH is an absolute path on the Messages Mac never expanded against the Gateway home, and the remote host as host or user-at-host, which enables inbound attachment fetches and owner-only outbound staging over strict SSH and SCP with best-effort cleanup that warns on failure, plus remote attachment roots used only in that mode.
• The group registry footgun: BlueBubbles keyed groups differently, so per-group entries must be re-keyed by the numeric iMessage chat id from the chats command, and a group that worked before will be silently unmatched until it is.

OpenClaw on iMessage is the channel post the migration lands on, and Enabling the imsg private API the bridge that most of the copied actions depend on.

On Diali

iMessage is not among the channels Diali connects today: WhatsApp, Telegram, Discord, Slack, Mattermost, Matrix, SMS and voice. Connect your first channel in five minutes explains how those are linked, and Diali security the boundary that applies to each.

Why the change

Removing a server, a client app and a webhook from the path takes three credentials and an exposed endpoint out of the picture; what remains is one binary on a Mac you already trust with your messages. Hosted OpenClaw on Diali is the assistant and OpenClaw plugins the surface the official iMessage plugin installs through.

• One binary over JSON-RPC, no server, no webhook.
• Behaviour keys copy; transport keys vanish; groups re-key.
• Verify imsg first, cut over second, delete last.