Coming from BlueBubbles

​

迁移检查清单

1. 在运行 Messages.app 的 Mac 上直接验证 imsg（imsg chats、imsg history、imsg send、imsg rpc --help）。
2. 将行为键从 channels.bluebubbles 复制到 channels.imessage：dmPolicy、allowFrom、groupPolicy、groupAllowFrom、groups、includeAttachments、attachmentRoots、mediaMaxMb、textChunkLimit、coalesceSameSenderDms 和 actions。
3. 删除不再存在的传输键：serverUrl、password、webhook URL，以及 BlueBubbles 服务器设置。
4. 如果 Gateway 网关未在 Messages Mac 上运行，请将 channels.imessage.cliPath 设置为 SSH 包装器，并为远程附件获取设置 remoteHost。
5. 启用 channels.imessage，重启 Gateway 网关，然后运行 openclaw channels status --probe --channel imessage。
6. 测试一个私信、一个允许的群组、附件（如果已启用），以及你期望智能体使用的每个私有 API 操作。
7. 在验证 iMessage 路径后，删除 BlueBubbles 服务器和旧的 channels.bluebubbles 配置。

​

imsg 的作用

• 读取通过只读 SQLite 句柄来自 ~/Library/Messages/chat.db。
• 实时入站消息来自 imsg watch / watch.subscribe，它会跟踪 chat.db 文件系统事件，并带有轮询后备机制。
• 发送对普通文本和文件发送使用 Messages.app 自动化。
• 高级操作使用 imsg launch 将 imsg 帮助程序注入 Messages.app。这会解锁已读回执、正在输入指示、富文本发送、编辑、撤回、线程回复、tapbacks、投票和群组管理。
• Linux 构建可以检查复制的 chat.db，但不能发送、监听实时 Mac 数据库，也不能驱动 Messages.app。对于 OpenClaw iMessage，请在已登录的 Mac 上运行 imsg，或通过指向该 Mac 的 SSH 包装器运行。

​

开始之前

1. 在运行 Messages.app 的 Mac 上安装 imsg：
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   如果 imsg chats 因 unable to open database file、空输出或 authorization denied 而失败，请向启动 imsg 的终端、编辑器、Node 进程、Gateway 网关服务或 SSH 父进程授予完全磁盘访问权限，然后重新打开该父进程。
2. 在更改 OpenClaw 配置之前，验证读取、监听、发送和 RPC 表面：
   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
   
   将 42 替换为来自 imsg chats 的真实聊天 ID。发送需要 Messages.app 的自动化权限。如果 OpenClaw 将通过 SSH 运行，请通过 OpenClaw 将使用的同一个 SSH 包装器或用户上下文运行这些命令。如果读取正常但发送因 AppleEvents -1743 失败，请检查自动化权限是否落在 /usr/libexec/sshd-keygen-wrapper 上；参阅 SSH 包装器发送因 AppleEvents -1743 失败。
3. 当你需要高级操作时，启用私有 API 桥接：
   imsg launch
   imsg status --json
   
   imsg launch 要求禁用 SIP（并且在现代 macOS 上，需要放宽库验证——参阅 启用 imsg 私有 API）。基本发送、历史记录和监听不需要 imsg launch；高级操作需要。
4. 启用 channels.imessage 并启动 Gateway 网关后，通过 OpenClaw 验证桥接：
   openclaw channels status --probe
   
   iMessage 账户应报告 works；使用 --json 时，探测载荷包含 privateApi.available: true。如果它报告 false，请先修复该问题——参阅 能力检测。探测需要可访问的 Gateway 网关（否则 CLI 会回退到仅配置输出），并且只探测已配置且已启用的账户。
5. 创建你的配置快照：
   cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
   

​

配置转换

​

群组注册表陷阱

1. 发送者 / 聊天目标允许列表（channels.imessage.groupAllowFrom）— 匹配发送者句柄或聊天目标（chat_id:、chat_guid:、chat_identifier: 条目）。未设置 groupAllowFrom 时，此门禁会回退到 allowFrom；显式的 groupAllowFrom: [] 会禁用该回退，并在 groupPolicy: "allowlist" 下丢弃每条群组消息。
2. 群组注册表（channels.imessage.groups）— 以数字形式的 iMessage chat_id 为键：
   • 没有 groups 块（或为空）：只要门禁 1 有一个非空的有效发送者允许列表，群组就会通过此门禁；发送者过滤控制访问权限，并且不会触发全部丢弃的启动警告。
   • groups 有条目但没有 "*"：只有列出的 chat_id 键会通过。列出任意群组都会让注册表变成允许列表，即使在 groupPolicy: "open" 下也是如此。
   • groups: { "*": { ... } }：每个群组都会通过此门禁。

• 启动时每个账号一次，当设置了 groupPolicy: "allowlist" 且有效群组发送者允许列表为空时：imessage: groupPolicy="allowlist" for account "<id>" but no group sender allowlist is configured ...。设置 groupAllowFrom（或 allowFrom）以允许发送者；仅添加 groups 不会满足发送者门禁。
• 运行时每个 chat_id 一次，当注册表丢弃群组时：imessage: dropping group message from chat_id=<id> ... not in channels.imessage.groups allowlist，并指出要添加的确切键。

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

​

分步说明

1. 翻译配置。编辑时保持新块禁用；旧的 channels.bluebubbles 块会被当前 OpenClaw 忽略，可以作为参考并存：
   {
     channels: {
       imessage: {
         enabled: false, // flip to true when ready to cut over
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // wildcard copies verbatim; re-key per-chat entries by chat_id
         // actions default to enabled; set individual toggles false to disable
       },
     },
   }
   
2. 切换并探测。 设置 channels.imessage.enabled: true，重启 Gateway 网关，并确认该渠道报告为健康：
   openclaw gateway restart
   openclaw channels status --probe --channel imessage   # expect "works"; --json shows privateApi.available: true
   
   该探测需要可访问的 Gateway 网关，并且只探测已配置、已启用的账号。使用 开始之前 中的直接 imsg 命令验证 Mac 本身。
3. 验证私信。 向智能体发送一条直接消息；确认回复送达。
4. 单独验证群组。 私信和群组走不同的代码路径——私信成功并不能证明群组正在路由。在允许的群聊中发送一条消息，并确认回复送达。如果群组静默（没有智能体回复，也没有错误），请检查 Gateway 网关日志中来自上文“群组注册表陷阱”的两条 warn 行。启动警告表示有效发送者允许列表为空；按 chat_id 的警告表示已填充的 groups 注册表不包含该聊天。
5. 验证操作表面。 从已配对的私信中，让智能体执行表情回应、编辑、撤回、回复、发送照片，以及（在群组中）重命名群组或添加/移除参与者。每个操作都应原生送达 Messages.app。如果任何操作抛出 iMessage <action> requires the imsg private API bridge，请再次运行 imsg launch，并用 openclaw channels status --probe 刷新。
6. 移除 BlueBubbles 服务器和 channels.bluebubbles 块，前提是 iMessage 私信、群组和操作都已验证。OpenClaw 不会读取 channels.bluebubbles。

​

操作对等性速览

​

配对、会话和 ACP 绑定

• 允许列表按 handle 继承。 channels.imessage.allowFrom 可识别 BlueBubbles 使用的相同 +15555550123 / user@example.com 字符串——请逐字复制。
• 配对存储批准不会转移。 配对存储按渠道划分，不会迁移旧的 BlueBubbles 存储。仅通过配对获批的发送者必须在 iMessage 下重新配对一次，或者你将其 handle 添加到 allowFrom。
• 会话 仍按智能体 + 聊天限定范围。在默认 session.dmScope=main 下，私信会折叠到智能体主会话；群组会话按 chat_id 保持隔离（agent:<agentId>:imessage:group:<chat_id>）。BlueBubbles 会话键下的旧对话历史不会带入 iMessage 会话。
• ACP 绑定 中引用 match.channel: "bluebubbles" 的地方必须改为 "imessage"。match.peer.id 形状（chat_id:、chat_guid:、chat_identifier:、裸 handle）相同。

​

无回滚渠道

​

相关

• BlueBubbles removal and the imsg iMessage path——简短公告和操作员摘要。
• iMessage——完整 iMessage 渠道参考，包括 imsg launch 设置和能力检测。
• /channels/bluebubbles——重定向到本迁移指南的旧版 URL。
• 配对——私信认证和配对流程。
• 频道路由——Gateway 网关如何为出站回复选择渠道。