iMessage 从 BlueBubbles 迁移

BlueBubbles 支持已移除，OpenClaw 现在通过 imsg 工具直接与 Messages.app 通信。本文是从 channels.bluebubbles 迁移到 channels.imessage 的指南。

迁移前提

• 在运行 Messages.app 的 Mac 上安装 imsg：brew install steipete/tap/imsg
• 验证 imsg chats、imsg history、imsg send、imsg rpc --help 均可用
• 需要高级操作（react/edit/unsend 等）时运行 imsg launch（需禁用 SIP）

迁移检查清单

1. 验证 imsg 在 Messages.app 所在 Mac 上可用
2. 将行为配置从 channels.bluebubbles 复制到 channels.imessage：dmPolicy、allowFrom、groupPolicy、groupAllowFrom、groups、includeAttachments 等
3. 删除传输层配置：serverUrl、password、webhook URL
4. 若 Gateway 不在 Messages Mac 上，设置 channels.imessage.cliPath 为 SSH wrapper
5. 运行 openclaw channels status --probe --channel imessage 验证

配置对照表

BlueBubbles 配置	iMessage 配置	说明
channels.bluebubbles.serverUrl	已移除	改为 stdio 通信
channels.bluebubbles.password	已移除	无需认证
channels.bluebubbles.dmPolicy	channels.imessage.dmPolicy	相同语义
channels.bluebubbles.allowFrom	channels.imessage.allowFrom	按 handle 继承
channels.bluebubbles.groupPolicy	channels.imessage.groupPolicy	相同语义
channels.bluebubbles.groups	channels.imessage.groups	必须完整复制
channels.bluebubbles.includeAttachments	channels.imessage.includeAttachments	默认关闭，需显式设置
channels.bluebubbles.mediaMaxMb	channels.imessage.mediaMaxMb	iMessage 默认 16MB

关键陷阱：Group Registry

iMessage 插件有两道独立的群组白名单检查：

1. 发送者白名单（groupAllowFrom）
2. 群组注册表（groups）— 使用 groupPolicy: "allowlist" 时必须配置

若只复制了 groupAllowFrom 而遗漏 groups 块，群消息会被静默丢弃。最小配置：

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

逐步迁移

// 第一步：并行配置，imessage 先禁用
{
  channels: {
    bluebubbles: { enabled: true },
    imessage: {
      enabled: false,
      cliPath: "/opt/homebrew/bin/imsg",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

验证通过后，删除 channels.bluebubbles，将 channels.imessage.enabled 设为 true。

相关链接

• channel-routing — 消息路由机制
• channel-pairing — DM 配对流程