BlueBubbles removal and the imsg iMessage path

Apus no longer ships the BlueBubbles channel. iMessage support runs through the official @openclaw/imessage plugin: the Gateway spawns 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, 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.
Apus 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

Install the official plugin on the Gateway host, then restart the Gateway:
```
apus plugins install @openclaw/imessage
```

Install and verify imsg on the Messages Mac:

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

Grant Full Disk Access and Automation permissions to the process context that runs imsg and Apus.

Translate the old config:

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

Restart the Gateway and verify:
```
apus channels status --probe
```
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.

BlueBubbles removal and the imsg iMessage path

What changed

What to do

Migration notes

See also