来自 BlueBubbles
BlueBubbles 支持已被移除。OpenClaw 仅通过官方 @openclaw/imessage 插件支持 iMessage,该插件通过 JSON-RPC 驱动 steipete/imsg,并覆盖 BlueBubbles 曾拥有的相同私有 API 表面(react、edit、unsend、reply、sendWithEffect、原生投票、群组管理、附件)。单个 CLI 二进制文件取代了 BlueBubbles 服务器 + 客户端应用 + webhook 管道:没有 REST 端点,也没有 webhook 认证。
本指南将旧的 channels.bluebubbles 配置迁移到 channels.imessage。没有其他受支持的迁移路径。在当前 OpenClaw 中,残留的 channels.bluebubbles 配置块是惰性的——没有运行时读取它。
Note
如需简要公告和运维人员摘要,请参阅 BlueBubbles 移除与 imsg iMessage 路径。
迁移检查清单¶
当你已经了解旧 BlueBubbles 配置时,最短的安全路径如下:
- 使用
openclaw plugins install @openclaw/imessage安装官方插件,并检查应用结果。 - 在运行 Messages.app 的 Mac 上直接验证
imsg(imsg chats、imsg history、imsg send、imsg rpc --help)。 - 将行为键从
channels.bluebubbles复制到channels.imessage:dmPolicy、allowFrom、groupPolicy、groupAllowFrom、groups、includeAttachments、attachmentRoots、mediaMaxMb、textChunkLimit和actions。 - 删除不再存在的传输键:
serverUrl、password、webhook URL 及 BlueBubbles 服务器设置。 - 如果 Gateway 未在 Messages Mac 上运行,请将
channels.imessage.cliPath设置为 SSH 包装器在 Gateway 本地的绝对路径,并保持dbPath为该 Mac 上的绝对路径。对于复杂的包装器,将remoteHost设置为 Messages Mac;OpenClaw 会自动检测简单的透明包装器形态以保持兼容性。 - 启用
channels.imessage,然后运行openclaw channels status --probe --channel imessage。配置更改遵循热重载;如果 Gateway 离线,请启动它。 - 测试一条私信、一个允许的群组、附件(如果已启用),以及你期望代理使用的每个私有 API 操作。
- 在 iMessage 路径验证通过后,删除 BlueBubbles 服务器和旧的
channels.bluebubbles配置。
Note
远程 imsg v0.13.4 有两个范围受限的 RPC 限制:投票必须使用 pollOptionId 而不是索引或选项文本,并且附件回复不能针对非零的消息部分索引。本地 imsg 行为不变。
imsg 的作用¶
imsg 是用于 Messages 的本地 macOS CLI。OpenClaw 将 imsg rpc 作为子进程启动,并通过 stdin/stdout 进行 JSON-RPC 通信。没有 HTTP 服务器、webhook URL、后台守护进程、启动代理或需要暴露的端口。
- 读取操作通过只读 SQLite 句柄从
~/Library/Messages/chat.db获取数据。 - 实时入站消息来自
imsg watch/watch.subscribe,它跟踪chat.db的文件系统事件,并以轮询作为回退。 - 发送操作使用 Messages.app 的自动化功能进行普通文本和文件发送。
- 高级操作使用
imsg launch将imsg辅助程序注入 Messages.app。这正是解锁已读回执、输入指示器、富文本发送、编辑、撤回、线程回复、点按回应、投票和群组管理的方式。 - Linux 构建可以检查复制的
chat.db,但无法发送、监视 Mac 实时数据库或驱动 Messages.app。对于 OpenClaw iMessage,请在已登录的 Mac 上运行imsg,或通过 SSH 包装器连接到该 Mac 运行。
开始之前¶
- 在运行 Messages.app 的 Mac 上安装
imsg:
对于通常的本地设置,OpenClaw 设置程序可以在已登录的 Messages Mac 上提供用户确认的 Homebrew 安装或更新 imsg。手动设置和 SSH 包装器拓扑仍由运维人员管理:在将运行 imsg 的相同本地或远程用户上下文中重复 Homebrew 更新。如果 imsg chats 失败并显示 unable to open database file、空输出或 authorization denied,请授予启动 imsg 的终端、编辑器、Node 进程、Gateway 服务或 SSH 父进程完全磁盘访问权限,然后重新打开该父进程。
- 在更改 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 的自动化(Automation)权限。如果 OpenClaw 将通过 SSH 运行,请通过 OpenClaw 将使用的相同 SSH 包装器或用户上下文运行这些命令。如果读取正常但发送失败并显示 AppleEvents -1743,请检查自动化权限是否落在 /usr/libexec/sshd-keygen-wrapper 上;请参阅 SSH 包装器发送失败并显示 AppleEvents -1743。
- 启用私有 API 桥接。对于 OpenClaw iMessage,强烈建议启用它,因为回复、点按回应、特效、投票、附件回复和群组操作都依赖它:
imsg launch 要求禁用 SIP(在较新的 macOS 上,还需要放宽库验证——请参阅启用 imsg 私有 API)。基本的发送、历史和监视功能无需 imsg launch 即可工作;但完整的 OpenClaw iMessage 操作表面需要它。
- 启用
channels.imessage并启动 Gateway 后,通过 OpenClaw 验证桥接:
iMessage 账户应报告 works;使用 --json 时,检查负载包含 privateApi.available: true。如果报告为 false,请先修复该问题——请参阅能力检测。检查需要可访问的 Gateway(否则 CLI 将回退到仅配置输出),并且只检查已配置且已启用的账户。
- 备份你的配置:
配置转换¶
iMessage 和 BlueBubbles 共享大多数通道级行为键。变化的是传输方式(REST 服务器 vs 本地 CLI)以及群组注册表键格式。
| BlueBubbles | iMessage 插件 | 说明 |
|---|---|---|
channels.bluebubbles.enabled |
channels.imessage.enabled |
相同语义(一旦该配置块存在,默认 true)。 |
channels.bluebubbles.serverUrl |
(已移除) | 无 REST 服务器——插件通过 stdio 启动 imsg rpc。 |
channels.bluebubbles.password |
(已移除) | 无需 webhook 身份验证。 |
| (隐式) | channels.imessage.cliPath |
imsg 的路径(默认 imsg);对于 SSH,请使用 Gateway 主机上包装器的绝对路径。 |
| (隐式) | channels.imessage.dbPath |
可选的 Messages.app chat.db 覆盖;对于 SSH,这是 Messages Mac 上的绝对路径,且永远不会相对于 Gateway 主目录展开。 |
| (隐式) | channels.imessage.remoteHost |
将 Messages Mac 指定为 host 或 user@host;显式配置优先,而简单的透明 SSH 包装器会在每个进程中自动检测一次。启用通过严格 SSH/SCP 的入站附件获取和仅限所有者的出站暂存。清理为尽力而为;失败会发出警告,并可能留下仅限所有者的残留文件。 |
channels.bluebubbles.dmPolicy |
channels.imessage.dmPolicy |
相同取值(pairing / allowlist / open / disabled);默认 pairing。 |
channels.bluebubbles.allowFrom |
channels.imessage.allowFrom |
相同 handle 格式(+15555550123、user@example.com)。配对存储中的批准不会迁移——见下文。 |
channels.bluebubbles.groupPolicy |
channels.imessage.groupPolicy |
相同取值(allowlist / open / disabled);默认 allowlist。 |
channels.bluebubbles.groupAllowFrom |
channels.imessage.groupAllowFrom |
相同。未设置时,iMessage 回退到 allowFrom;显式空 groupAllowFrom: [] 会在 groupPolicy: "allowlist" 下阻止所有群组。 |
channels.bluebubbles.groups |
channels.imessage.groups |
原样复制 "*" 通配符条目;按数字 iMessage chat_id 重新设置每个群组条目的键——参见“群组注册表陷阱”。requireMention、tools、toolsBySender、systemPrompt 会沿用。 |
channels.bluebubbles.sendReadReceipts |
channels.imessage.sendReadReceipts |
默认 true。仅当私有 API 检查可用时才会触发。 |
channels.bluebubbles.includeAttachments |
channels.imessage.includeAttachments |
相同结构,默认同样关闭。如果附件在 BlueBubbles 上可用,请显式设置此项——否则入站照片/媒体会被静默丢弃(没有 Inbound message 日志行),直到你设置为止。 |
| BlueBubbles | iMessage 插件 | 说明 |
|---|---|---|
channels.bluebubbles.attachmentRoots |
channels.imessage.attachmentRoots |
本地根目录;通配符规则相同。 |
| (不适用) | channels.imessage.remoteAttachmentRoots |
仅当为 SCP 获取设置了 remoteHost 时使用。 |
channels.bluebubbles.mediaMaxMb |
channels.imessage.mediaMaxMb |
iMessage 上默认 16 MB(BlueBubbles 默认曾为 8 MB)。如需保留较低上限,请显式设置。 |
channels.bluebubbles.textChunkLimit |
channels.imessage.textChunkLimit |
两者默认均为 4000。 |
channels.bluebubbles.coalesceSameSenderDms |
(已移除) | 不要迁移此键。imsg 0.13.1 及更高版本会在 OpenClaw 接收之前合并 Apple URL 预览的拆分发送;openclaw doctor --fix 会移除过时的 iMessage 键。 |
channels.bluebubbles.enrichGroupParticipantsFromContacts |
(不适用) | imsg 已提供来自 chat.db 的发送者显示名称。 |
channels.bluebubbles.actions.* |
channels.imessage.actions.* |
相同的按操作开关(reactions、edit、unsend、reply、sendWithEffect、renameGroup、setGroupIcon、addParticipant、removeParticipant、leaveGroup、sendAttachment),并新增 polls。默认均启用;私有 API 操作仍需要 bridge。 |
多账户配置(channels.bluebubbles.accounts.*)可一对一转换为 channels.imessage.accounts.*。
群组注册表陷阱¶
iMessage 插件会连续执行两个群组关卡。群组消息必须同时通过这两个关卡才能到达代理:
- 发送者 / 聊天目标允许列表(
channels.imessage.groupAllowFrom)——匹配发送者 handle 或聊天目标(chat_id:、chat_guid:、chat_identifier:条目)。当groupAllowFrom未设置时,此关卡会回退到allowFrom;显式设置groupAllowFrom: []会禁用该回退,并在groupPolicy: "allowlist"下丢弃所有群组消息。 - 群组注册表(
channels.imessage.groups)——以数字 iMessagechat_id为键: - 没有
groups块(或为空):只要关卡 1 存在非空的有效发送者允许列表,群组即可通过此关卡;访问由发送者过滤控制,且不会触发启动时全部丢弃警告。 groups有条目但没有"*":只有列出的chat_id键能通过。列出任何群组都会使注册表成为允许列表,即使在groupPolicy: "open"下也是如此。groups: { "*": { ... } }:所有群组都能通过此关卡。
迁移陷阱:BlueBubbles 使用聊天 GUID / 聊天标识符作为 groups 条目的键,而 iMessage 注册表以数字 chat_id 为键。逐字复制的按群组条目会创建一个非空注册表,但其键永远不会匹配,因此所有群组消息都会在关卡 2 被丢弃。请逐字复制 "*" 通配符;使用 imsg chats 中的 chat_id 值重新设置特定群组条目的键。
两种丢弃路径在默认日志级别下都可以通过 warn 行看到:
- 启动时每个账户一次,当设置了
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,其中指明了需要添加的确切键。
无论如何,DM 都会继续工作——它们走不同的代码路径,因此 DM 成功并不能证明群组路由正常。
使用 groupPolicy: "allowlist" 的最小发送者范围配置:
{
channels: {
imessage: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15555550123", "chat_guid:any;-;..."],
},
},
}
这会在任意群组中允许已配置的发送者。添加 groups 条目以限定允许的聊天,或设置每个聊天的选项(例如 requireMention);逐字复制 BlueBubbles 的 "*" 条目,但将特定条目以数字 iMessage chat_id 值作为键重新命名。
分步操作¶
- 转换配置。编辑期间保持新块处于禁用状态;当前 OpenClaw 会忽略旧的
channels.bluebubbles块,它可以保留在旁边作为参考:
{
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
},
},
}
- 切换并检查。 将
channels.imessage.enabled: true,让 热重载 应用更改,并确认该通道报告健康:
openclaw channels status --probe --channel imessage # expect "works"; --json shows privateApi.available: true
该检查要求 Gateway 可达,并且只检查已配置、已启用的账户。使用 开始前 中的直接 imsg 命令来验证 Mac 本身。
-
验证私信。 向代理发送一条私信;确认回复送达。
-
单独验证群组。 私信和群组走不同的代码路径——私信成功并不能证明群组正在路由。在允许的群聊中发送一条消息,并确认回复送达。如果群组没有响应(没有代理回复,也没有错误),请检查 Gateway 日志中上面“群组注册表陷阱”部分的两条
warn行。启动警告表示有效的发送者允许列表为空;按chat_id的警告表示已填充的groups注册表不包含该聊天。 -
验证操作功能。 从已配对的私信中,要求代理执行反应、编辑、撤回、回复、发送照片,以及(在群组中)重命名群组或添加/移除参与者。每个操作都应原生地出现在 Messages.app 中。如果任何操作抛出
iMessage <action> requires the imsg private API bridge,请再次运行imsg launch,并使用openclaw channels status --probe刷新。 -
移除 BlueBubbles 服务器和
channels.bluebubbles块,在 iMessage 私信、群组和操作均已验证后。OpenClaw 不会读取channels.bluebubbles。
操作功能对照¶
| 操作 | 旧版 BlueBubbles | iMessage 插件 |
|---|---|---|
| 发送文本 / SMS 回退 | ✅ | ✅ |
| 发送媒体(照片、视频、文件、语音) | ✅ | ✅ |
线程回复(reply_to_guid) |
✅ | ✅(关闭 #51892) |
Tapback(react) |
✅ | ✅ |
| 编辑 / 撤回(macOS 13+ 接收者) | ✅ | ✅ |
| 带屏幕效果发送 | ✅ | ✅(关闭 #9394 的一部分) |
| 富文本粗体 / 斜体 / 下划线 / 删除线 | ✅ | ✅(通过 attributedBody 的 typed-run 格式) |
| 原生 Messages 投票(创建和投票) | ❌ | ✅(actions.polls;接收者需要 iOS/macOS 26+ 才能原生渲染) |
| 重命名群组 / 设置群组图标 | ✅ | ✅ |
| 添加 / 移除参与者、退出群组 | ✅ | ✅ |
| 已读回执和正在输入指示器 | ✅ | ✅(受私有 API 检查控制) |
| Apple URL 预览拆分发送合并 | ✅ | ✅(由 imsg 0.13.1 及更高版本在上游处理;无 OpenClaw 设置) |
| 重启后的入站恢复 | ✅ | ✅(自动:since_rowid 重放 + GUID 去重;本地有更大的窗口) |
iMessage 会恢复 Gateway 宕机期间错过的消息:启动时,它通过 imsg watch.subscribe 的 since_rowid 从最后已分发的 rowid 开始重放,按 GUID 去重,并且一个陈旧积压年龄围栏会抑制 Push 刷新“积压炸弹”。这通过 imsg RPC 连接运行,因此也适用于远程 SSH cliPath 设置;本地设置拥有更大的恢复窗口,因为它们可以读取 chat.db。参见 桥接或 Gateway 重启后的入站恢复。
配对、会话和 ACP 绑定¶
- 允许列表按 handle 延续。
channels.imessage.allowFrom识别 BlueBubbles 使用的相同+15555550123/user@example.com字符串——逐字复制它们。 - 配对存储中的批准不会转移。 配对存储按通道划分,没有任何内容会迁移旧的 BlueBubbles 存储。仅通过配对获得批准的发送者必须在 iMessage 下再次配对,或者你将他们的 handle 添加到
allowFrom。 - 会话 仍按代理 + 聊天划分作用域。在默认
session.dmScope=main下,私信会合并到代理主会话;在默认session.groupScope="per-group"下,群会话按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 运行时可供切换回。如果 iMessage 验证失败,请设置 channels.imessage.enabled: false,使用 openclaw channels status 确认该通道已停止,修复 imsg 阻塞问题,然后重试切换。如果自动配置重载已关闭,请按照 手动应用 操作。
回复缓存位于 SQLite 插件状态中。要导入六月之前的
imessage/reply-cache.jsonl 附属文件,请 通过 2026.9.5 升级
并先运行其 Doctor。当前版本不会修改旧文件。
相关¶
- BlueBubbles 移除和 imsg iMessage 路径 — 简短公告和运维摘要。
- iMessage — 完整的 iMessage 通道参考,包括
imsg launch设置和能力检测。 /channels/bluebubbles— 重定向到本迁移指南的旧 URL。- 配对 — DM 身份验证和配对流程。
- 通道路由 — 网关如何为出站回复选择通道。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw