Coming from BlueBubbles

Documentation Index

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

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

​

迁移检查清单

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. 在 Gateway 网关停止后，启用 channels.imessage，然后运行 openclaw channels status --probe --channel imessage。
6. 测试一个私信、一个允许的群组、附件（如果已启用），以及你预期智能体使用的每个私有 API 操作。
7. 在 iMessage 路径验证完成后，删除 BlueBubbles 服务器和旧的 channels.bluebubbles 配置。

​

何时适合此迁移

• 你已经在 Messages.app 已登录的同一台 Mac（或可通过 SSH 访问的 Mac）上运行 imsg。
• 你希望减少一个运行部件——没有单独的 BlueBubbles 服务器、没有需要认证的 REST 端点、没有 Webhook 管道。用单个 CLI 二进制文件替代服务器 + 客户端应用 + 辅助程序。
• 你正在使用受支持的 macOS / imsg 构建，并且私有 API 探测报告 available: true。

​

imsg 的作用

• 读取来自 ~/Library/Messages/chat.db，使用只读 SQLite 句柄。
• 实时传入消息来自 imsg watch / watch.subscribe，它会跟踪 chat.db 文件系统事件，并提供轮询回退。
• 发送使用 Messages.app 自动化来发送普通文本和文件。
• 高级操作使用 imsg launch 将 imsg 辅助程序注入 Messages.app。这会解锁已读回执、正在输入指示、富文本发送、编辑、撤回、线程回复、点按回应和群组管理。
• 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 包装器或用户上下文运行这些命令。
3. 当你需要高级操作时，启用私有 API 桥接：
   imsg launch
   imsg status --json
   
   imsg launch 需要禁用 SIP。基本发送、历史记录和监听无需 imsg launch 即可工作；高级操作不行。
4. 添加已启用的 channels.imessage 配置后，通过 OpenClaw 验证桥接：
   openclaw channels status --probe
   
   你需要看到 imessage.privateApi.available: true。如果报告 false，请先修复该问题——参见能力检测。channels status --probe 只会探测已配置并启用的账号。
5. 快照你的配置：
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

配置转换

​

群组注册表陷阱

1. 发送者 / 聊天目标允许列表（channels.imessage.groupAllowFrom）由 isAllowedIMessageSender 检查。按发送者 handle、chat_guid、chat_identifier 或 chat_id 匹配入站消息。结构与 BlueBubbles 相同。
2. 群组注册表（channels.imessage.groups）由 inbound-processing.ts:199 中的 resolveChannelGroupPolicy 检查。使用 groupPolicy: "allowlist" 时，此门禁要求以下任一项：
   • 一个 groups: { "*": { ... } } 通配符条目（设置 allowAll = true），或
   • groups 下有一个显式的按 chat_id 配置的条目。

• 当设置了 groupPolicy: "allowlist" 但 channels.imessage.groups 为空（没有 "*" 通配符，也没有按 chat_id 配置的条目）时，每个账号在启动时发出一次 warn，在任何消息进入前触发。
• 运行时第一次丢弃某个具体群组时，按 chat_id 发出一次 warn，其中会说明 chat_id 以及要添加到 groups 以允许它的确切键名。

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

​

分步说明

1. 在现有 BlueBubbles 块旁添加一个 iMessage 块。当 Gateway 网关仍在路由 BlueBubbles 流量时，先保持它禁用：
   {
     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. 在流量重要之前先探测——停止 Gateway 网关，临时启用 iMessage 块，并确认 iMessage 在 CLI 中报告健康：
   openclaw gateway stop
   # edit config: channels.imessage.enabled = true
   openclaw channels status --probe --channel imessage   # expect imessage.privateApi.available: true
   
   channels status --probe 只会探测已配置且已启用的账号。除非你有意同时运行两个渠道监视器，否则不要在 BlueBubbles 和 iMessage 同时启用的情况下重启 Gateway 网关。如果你不会立即切换，在重启 Gateway 网关前将 channels.imessage.enabled 设回 false。在启用 OpenClaw 流量前，使用 开始之前 中的直接 imsg 命令验证 Mac。
3. 切换。 已启用的 iMessage 账号报告健康后，移除 BlueBubbles 配置并保持 iMessage 启用：
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   重启 Gateway 网关。入站 iMessage 流量现在会通过内置插件流转。
4. 验证私信。 向智能体发送一条直接消息；确认回复能够送达。
5. 单独验证群组。 私信和群组走不同代码路径——私信成功并不能证明群组正在路由。在已配对的群聊中向智能体发送一条消息，并确认回复能够送达。如果群组变得无响应（没有智能体回复，也没有错误），检查 Gateway 网关日志中是否有 imessage: dropping group message from chat_id=<id>，或启动时的 imessage: groupPolicy="allowlist" but channels.imessage.groups is empty 行——两者都会在默认日志级别触发。如果出现任意一条，说明你的 groups 块缺失或为空——见上面的 “Group registry footgun”。
6. 验证操作面——从已配对的私信中，让智能体执行反应、编辑、撤回、回复、发送照片，以及（在群组中）重命名群组 / 添加或移除参与者。每个操作都应原生落到 Messages.app 中。如果任何操作抛出 “iMessage <action> requires the imsg private API bridge”，请再次运行 imsg launch 并刷新 channels status --probe。
7. 在 iMessage 私信、群组和操作都验证通过后，移除 BlueBubbles 服务器和配置。OpenClaw 不会使用 channels.bluebubbles。

​

操作能力对照一览

​

配对、会话和 ACP 绑定

• 配对审批 会按 handle 继承。你不需要重新审批已知发送者——channels.imessage.allowFrom 会识别 BlueBubbles 使用的同样 +15555550123 / user@example.com 字符串。
• 会话 保持按每个智能体 + 聊天限定范围。在默认 session.dmScope=main 下，私信会折叠进智能体主会话；群组会话会按每个 chat_id 保持隔离。会话键不同（agent:<id>:imessage:group:<chat_id> 对比 BlueBubbles 等价键）——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 网关如何为出站回复选择渠道。