Coming from BlueBubbles

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

When this migration makes sense

• You already run imsg on the same Mac (or one reachable over SSH) where Messages.app is signed in.
• You want one fewer moving part — no separate BlueBubbles server, no REST endpoint to authenticate, no webhook plumbing. Single CLI binary instead of a server + client app + helper.
• You are on a supported macOS / imsg build where the private API probe reports available: true.

​

What imsg does

• Reads come from ~/Library/Messages/chat.db using a read-only SQLite handle.
• Live inbound messages come from imsg watch / watch.subscribe, which follows chat.db filesystem events with a polling fallback.
• Sends use Messages.app automation for normal text and file sends.
• Advanced actions use imsg launch to inject the imsg helper into Messages.app. That is what unlocks read receipts, typing indicators, rich sends, edit, unsend, threaded reply, tapbacks, and group management.
• Linux builds can inspect a copied chat.db, but cannot send, watch the live Mac database, or drive Messages.app. For OpenClaw iMessage, run imsg on the signed-in Mac or through an SSH wrapper to that Mac.

​

Before you start

1. Install imsg on the Mac that runs Messages.app:
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   If imsg chats fails with unable to open database file, empty output, or authorization denied, grant Full Disk Access to the terminal, editor, Node process, Gateway service, or SSH parent process that launches imsg, then reopen that parent process.
2. Verify the read, watch, send, and RPC surfaces before changing OpenClaw config:
   imsg chats --limit 10 --json | jq -s
   imsg history --chat-id 42 --limit 10 --attachments --json | jq -s
   imsg watch --chat-id 42 --reactions --json
   imsg send --chat-id 42 --text "OpenClaw imsg test"
   imsg rpc --help
   
   Replace 42 with a real chat id from imsg chats. Sending requires Automation permission for Messages.app. If OpenClaw will run through SSH, run these commands through the same SSH wrapper or user context that OpenClaw will use.
3. Enable the private API bridge when you need advanced actions:
   imsg launch
   imsg status --json
   
   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:
   openclaw channels status --probe
   
   You want imessage.privateApi.available: true. If it reports false, fix that first — see Capability detection.
5. Snapshot your config:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

Config translation

​

Group registry footgun

1. Sender / chat-target allowlist (channels.imessage.groupAllowFrom) — checked by isAllowedIMessageSender. Matches inbound messages by sender handle, chat_guid, chat_identifier, or chat_id. Same shape as BlueBubbles.
2. Group registry (channels.imessage.groups) — checked by resolveChannelGroupPolicy from inbound-processing.ts:199. With groupPolicy: "allowlist", this gate requires either:
   • a groups: { "*": { ... } } wildcard entry (sets allowAll = true), or
   • an explicit per-chat_id entry under groups.

• A one-time startup warn per account when groupPolicy: "allowlist" is set but channels.imessage.groups is empty (no "*" wildcard, no per-chat_id entries) — fired before any messages land.
• A one-time per-chat_id warn the first time a specific group is dropped at runtime, naming the chat_id and the exact key to add to groups to allow it.

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123", "chat_guid:any;-;..."],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

​

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:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false, // turn on after the dry run below
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // copy from bluebubbles.groups — silently drops groups if missing, see "Group registry footgun" above
         actions: {
           reactions: true,
           edit: true,
           unsend: true,
           reply: true,
           sendWithEffect: true,
           sendAttachment: true,
         },
       },
     },
   }
   
2. Dry-run probe — start the gateway and confirm iMessage reports healthy:
   openclaw gateway
   openclaw channels status
   openclaw channels status --probe   # 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.
3. Cut over. Remove the BlueBubbles config and enable iMessage in one config edit:
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   Restart the gateway. Inbound iMessage traffic now flows through the bundled plugin.
4. Verify DMs. Send the agent a direct message; confirm the reply lands.
5. Verify groups separately. DMs and groups take different code paths — DM success does not prove groups are routing. Send the agent a message in a paired group chat and confirm the reply lands. If the group goes silent (no agent reply, no error), check the gateway log for imessage: dropping group message from chat_id=<id> or the startup imessage: groupPolicy="allowlist" but channels.imessage.groups is empty line — both fire at the default log level. If either appears, your groups block is missing or empty — see “Group registry footgun” above.
6. Verify the action surface — from a paired DM, ask the agent to react, edit, unsend, reply, send a photo, and (in a group) rename the group / add or remove a participant. Each action should land natively in Messages.app. If any throws “iMessage <action> requires the imsg private API bridge”, run imsg launch again and refresh channels status --probe.
7. Remove the BlueBubbles server and config once iMessage DMs, groups, and actions are verified. OpenClaw will not use channels.bluebubbles.

​

Action parity at a glance

​

Pairing, sessions, and ACP bindings

• Pairing approvals carry over by handle. You do not need to re-approve known senders — channels.imessage.allowFrom recognizes the same +15555550123 / user@example.com strings BlueBubbles used.
• Sessions stay scoped per agent + chat. DMs collapse into the agent main session under default session.dmScope=main; group sessions stay isolated per chat_id. The session keys differ (agent:<id>:imessage:group:<chat_id> vs the BlueBubbles equivalent) — old conversation history under BlueBubbles session keys does not carry into iMessage sessions.
• ACP bindings referencing match.channel: "bluebubbles" need to be updated to "imessage". The match.peer.id shapes (chat_id:, chat_guid:, chat_identifier:, bare handle) are identical.

​

No rollback channel

​

Related

• iMessage — full iMessage channel reference, including imsg launch setup and capability detection.
• /channels/bluebubbles — legacy URL that redirects to this migration guide.
• Pairing — DM authentication and pairing flow.
• Channel Routing — how the gateway picks a channel for outbound replies.