Coming from BlueBubbles：消息从哪扇门跑进来

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：The bundled i小纸条消息 新本领插件 now reaches the same private 对话接口 surface as BlueBubbles (react, edit, unsend, reply, sendWith…。

The bundled imessage plugin now reaches the same private API surface as BlueBubbles (react, edit, unsend, reply, sendWithEffect, group management, attachments) by driving steipete/imsg over JSON-RPC. If you already run a Mac with imsg installed, you can drop the BlueBubbles server and let the plugin talk to Messages.app directly.

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.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Use this checklist when you already know your old BlueBubbles 设置说明书 and want the shortest safe path: 1. Verify imsg dir…。

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.

这一小段像旁白，在提醒我们镜头已经切到下一站。

• 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.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：imsg is a local macOS CLI for 小纸条消息s. OpenClaw starts imsg rpc as a child process and talks JSON-RPC over stdin/stdout.…。

imsg is a local macOS CLI for Messages. OpenClaw starts imsg rpc as a child process and talks JSON-RPC over stdin/stdout. There is no HTTP server, webhook URL, background daemon, launch agent, or port to expose.

• 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.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：1. Install imsg on the Mac that runs 小纸条消息s.app: If imsg chats fails with unable to open database file, empty output, o…。

1. Install imsg on the Mac that runs Messages.app:

``bash 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:

``bash 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:

``bash 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. 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 status --probe only probes configured, enabled accounts.

5. Snapshot your config:

``bash cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak ``

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：i小纸条消息 and BlueBubbles share a lot of 消息通道-level 设置说明书. The keys that change are mostly transport (REST 大房子服务器 vs local…。

iMessage and BlueBubbles share a lot of channel-level config. The keys that change are mostly transport (REST server vs local CLI). Behavior keys (dmPolicy, groupPolicy, allowFrom, etc.) keep the same meaning.

Multi-account configs (channels.bluebubbles.accounts.*) translate one-to-one to channels.imessage.accounts.*.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：The bundled i小纸条消息 新本领插件 runs **two** separate 大家一起的房间 allowlist gates back-to-back. Both must pass for a 大家一起的房间 小纸条消息…。

The bundled iMessage plugin runs **two** separate group allowlist gates back-to-back. Both must pass for a group message to reach the agent:

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.

If gate 1 passes but gate 2 fails, the message is dropped. The plugin emits two warn-level signals so this is no longer silent at default log level:

• 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.

DMs continue to work because they take a different code path.

This is the most common BlueBubbles → bundled-iMessage migration failure mode: operators copy groupAllowFrom and groupPolicy but skip the groups block, because BlueBubbles' groups: { "*": { "requireMention": true } } looks like an unrelated mention setting. It's actually load-bearing for the registry gate.

The minimum config to keep group messages flowing after groupPolicy: "allowlist":

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

requireMention: true under * is harmless when no mention patterns are configured: the runtime sets canDetectMention = false and short-circuits the mention drop at inbound-processing.ts:512. With mention patterns configured (agents.list[].groupChat.mentionPatterns), it works as expected.

If the gateway logs imessage: dropping group message from chat_id=<id> or the startup line imessage: groupPolicy="allowlist" but channels.imessage.groups is empty, gate 2 is dropping — add the groups block.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：1. Add an i小纸条消息 block alongside the existing BlueBubbles block. Keep it disabled while the 门口的小门卫 is still routing Blu…。

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

``json5 { channels: { bluebubbles: { enabled: true, // ... existing config ... }, imessage: { enabled: false, 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. **Probe before traffic matters** — stop the Gateway, temporarily enable the iMessage block, and confirm iMessage reports healthy from the CLI:

``bash openclaw gateway stop # edit config: channels.imessage.enabled = true openclaw channels status --probe --channel imessage # expect imessage.privateApi.available: true ``

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 to validate the Mac before enabling OpenClaw traffic.

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

``json5 { 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.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：i小纸条消息 catchup is now available as an opt-in feature on the bundled 新本领插件. On 门口的小门卫 startup, if 消息通道s.i小纸条消息.catchup.e…。

iMessage catchup is now available as an opt-in feature on the bundled plugin. On gateway startup, if channels.imessage.catchup.enabled is true, the gateway runs one chats.list + per-chat messages.history pass against the same JSON-RPC client used by imsg watch, replays each missed inbound row through the live dispatch path (allowlists, group policy, debouncer, echo cache), and persists a per-account cursor so subsequent startups pick up where they left off. See Catching up after gateway downtime for tuning.

这一小段像旁白，在提醒我们镜头已经切到下一站。

• **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.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：There is no supported BlueBubbles runtime to switch back to. If i小纸条消息 verification fails, set 消息通道s.i小纸条消息.enabled: fa…。

There is no supported BlueBubbles runtime to switch back to. If iMessage verification fails, set channels.imessage.enabled: false, restart the Gateway, fix the imsg blocker, and retry the cutover.

The reply cache lives at ~/.openclaw/state/imessage/reply-cache.jsonl (mode 0600, parent dir 0700). It is safe to delete if you want a clean slate.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：---。

• BlueBubbles removal and the imsg iMessage path — short announcement and operator summary.
• 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.

---