BlueBubbles support was removed. OpenClaw supports iMessage through `imsg` only. This guide is for migrating old `channels.bluebubbles` configs to `channels.imessage`; there is no other supported migration path.

<Note>

For the short announcement and operator summary, see [BlueBubbles removal and the imsg iMessage path](/announcements/bluebubbles-imessage).

</Note>

## Migration checklist

Use this checklist when you already know your old BlueBubbles config and want the shortest safe path:

1. Verify `imsg` directly on the Mac that runs Messages.app (`imsg chats`, `imsg history`, `imsg send`, and `imsg rpc --help`).

2. Copy behavior keys from `channels.bluebubbles` to `channels.imessage`: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `includeAttachments`, `attachmentRoots`, `mediaMaxMb`, `textChunkLimit`, `coalesceSameSenderDms`, and `actions`.

3. Drop transport keys that no longer exist: `serverUrl`, `password`, webhook URLs, and BlueBubbles server setup.

4. If the Gateway is not running on the Messages Mac, set `channels.imessage.cliPath` to an SSH wrapper and set `remoteHost` for remote attachment fetches.

5. With the Gateway stopped, enable `channels.imessage`, then run `openclaw channels status --probe --channel imessage`.

6. Test one DM, one allowed group, attachments if enabled, and every private API action you expect the agent to use.

7. Delete the BlueBubbles server and old `channels.bluebubbles` config after the iMessage path is verified.

## When this migration makes sense

- You already run `imsg` on the same Mac (or one reachable over SSH) where Messages.app is signed in.

`imsg launch` requires SIP to be disabled. Basic send, history, and watch work without `imsg launch`; advanced actions do not.

4. Verify the bridge through OpenClaw:

4. After you add an enabled `channels.imessage` config, verify the bridge through OpenClaw:

```bash

openclaw channels status --probe

```

You want `imessage.privateApi.available: true`. If it reports `false`, fix that first — see [Capability detection](/channels/imessage#private-api-actions).

You want `imessage.privateApi.available: true`. If it reports `false`, fix that first — see [Capability detection](/channels/imessage#private-api-actions). `channels status --probe` only probes configured, enabled accounts.

5. Snapshot your config:

## Step-by-step

1. Add an iMessage block alongside the existing BlueBubbles block. Keep the old block only as a copy source until the new path is verified:

1. Add an iMessage block alongside the existing BlueBubbles block. Keep it disabled while the Gateway is still routing BlueBubbles traffic:

```json5

{

// ... existing config ...

},

imessage: {

enabled: false, // turn on after the dry run below

enabled: false,

cliPath: "/opt/homebrew/bin/imsg",

dmPolicy: "pairing",

allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom

}

```

2. **Dry-run probe** — start the gateway and confirm iMessage reports healthy:

2. **Probe before traffic matters** — stop the Gateway, temporarily enable the iMessage block, and confirm iMessage reports healthy from the CLI:

```bash

openclaw gateway

openclaw channels status

openclaw channels status --probe # expect imessage.privateApi.available: true

openclaw gateway stop

# edit config: channels.imessage.enabled = true

openclaw channels status --probe --channel imessage # expect imessage.privateApi.available: true

```

Because `imessage.enabled` is still `false`, no inbound iMessage traffic is routed yet — but `--probe` exercises the bridge so you catch permission/install issues before the cutover.

`channels status --probe` only probes configured, enabled accounts. Do not restart the Gateway with both BlueBubbles and iMessage enabled unless you intentionally want both channel monitors running. If you are not cutting over immediately, set `channels.imessage.enabled` back to `false` before restarting the Gateway. Use the direct `imsg` commands in [Before you start](#before-you-start) to validate the Mac before enabling OpenClaw traffic.

3. **Cut over.** Remove the BlueBubbles config and enable iMessage in one config edit:

3. **Cut over.** Once the enabled iMessage account reports healthy, remove the BlueBubbles config and keep iMessage enabled:

```json5

{

## Related

- [BlueBubbles removal and the imsg iMessage path](/announcements/bluebubbles-imessage) — short announcement and operator summary.

- [iMessage](/channels/imessage) — full iMessage channel reference, including `imsg launch` setup and capability detection.

- `/channels/bluebubbles` — legacy URL that redirects to this migration guide.

- [Pairing](/channels/pairing) — DM authentication and pairing flow.