> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# BlueBubbles removal and the imsg iMessage path

# BlueBubbles removal and the imsg iMessage path

OpenClaw no longer ships the BlueBubbles channel. iMessage support runs through the bundled `imessage` plugin: the Gateway spawns [`imsg`](https://github.com/steipete/imsg) as a child process, locally or through an SSH wrapper, and talks JSON-RPC over stdin/stdout. No server, no webhook, no port.

If your config still contains `channels.bluebubbles`, migrate it to `channels.imessage`. The legacy `/channels/bluebubbles` docs URL redirects to [Coming from BlueBubbles](/channels/imessage-from-bluebubbles), which has the full config translation table and cutover checklist.

## What changed

* The supported iMessage path has no BlueBubbles HTTP server, webhook route, REST password, or BlueBubbles plugin runtime.
* OpenClaw reads and watches Messages through `imsg` on the Mac where Messages.app is signed in.
* Basic send, receive, history, and media use the normal `imsg` surfaces and macOS permissions.
* Advanced actions (threaded replies, tapbacks, edit, unsend, effects, read receipts, typing indicators, group management) need the private API bridge: run `imsg launch`, which requires SIP disabled.
* Linux and Windows gateways can still use iMessage by pointing `channels.imessage.cliPath` at an SSH wrapper that runs `imsg` on the signed-in Mac.

## What to do

1. Install and verify `imsg` on the Messages Mac:

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   imsg rpc --help
   ```

2. Grant Full Disk Access and Automation permissions to the process context that runs `imsg` and OpenClaw.

3. Translate the old config:

   ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
   {
     channels: {
       imessage: {
         enabled: true,
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"],
         groupPolicy: "allowlist",
         groupAllowFrom: ["+15555550123"],
         groups: {
           "*": { requireMention: true },
         },
         includeAttachments: true,
       },
     },
   }
   ```

4. Restart the gateway and verify:

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   openclaw channels status --probe
   ```

5. Test DMs, groups, attachments, and any private API actions you depend on before deleting your old BlueBubbles server.

## Migration notes

* `channels.bluebubbles.serverUrl` and `channels.bluebubbles.password` have no iMessage equivalent; there is no server to reach or authenticate.
* `allowFrom`, `groupAllowFrom`, `groups`, `includeAttachments`, `attachmentRoots`, `mediaMaxMb`, `textChunkLimit`, and `actions.*` keep their meaning under `channels.imessage`.
* `channels.imessage.includeAttachments` is still off by default. Set it explicitly if you expect inbound photos, voice memos, videos, or files to reach the agent.
* With `groupPolicy: "allowlist"`, copy the old `groups` block, including any `"*"` wildcard entry. Group sender allowlists and the group registry are separate gates; a `groups` block with entries but no matching `chat_id` (or no `"*"`) drops the message at runtime, and an empty `groups` block logs a startup warning even though sender filtering still lets messages through.
* ACP bindings with `match.channel: "bluebubbles"` must change to `"imessage"`.
* Old BlueBubbles session keys do not become iMessage session keys. Pairing approvals key off sender handles, so copied `allowFrom` entries keep working, but conversation history under BlueBubbles session keys does not carry over.

## See also

* [Coming from BlueBubbles](/channels/imessage-from-bluebubbles)
* [iMessage](/channels/imessage)
* [Configuration reference - iMessage](/gateway/config-channels#imessage)