BlueBubbles
通过 BlueBubbles macOS Server（REST）接入 iMessage：收发、输入状态、反应与高级动作
状态：内置插件，通过 HTTP 与 BlueBubbles macOS Server 通信。由于 API 更丰富、安装更顺滑，推荐用 BlueBubbles 做 iMessage 集成（优先于旧的 imsg 通道）。
概览
- 运行在 macOS 上：BlueBubbles helper app（bluebubbles.app）。
- 推荐/测试：macOS Sequoia（15）。macOS Tahoe（26）可用，但 编辑（edit）目前在 Tahoe 上坏掉，并且群头像更新可能返回成功但不同步。
- OpenClaw 通过 REST API 访问（例如 GET /api/v1/ping、POST /message/text、POST /chat/:id/*）。
- 入站消息通过 webhook 到达；出站回复、输入状态、已读回执与 tapbacks 通过 REST 调用。
- 附件与贴纸会作为入站媒体进入媒体流水线（尽可能呈现给 agent）。
- pairing/allowlist 与其他通道一致（/start/pairing）：通过 channels.bluebubbles.allowFrom + 配对码。
- 反应（reactions）会像 Slack/Telegram 一样作为系统事件进入上下文，便于 agent “先提及反应再回复”。
- 高级能力：编辑、撤回、按消息引用回复、消息特效、群管理。
快速开始
1. 在你的 Mac 上安装 BlueBubbles Server（按 bluebubbles.app/install 的说明）。
2. 在 BlueBubbles 配置中启用 Web API 并设置密码。
3. 运行 openclaw onboard 并选择 BlueBubbles，或手动配置：
{
channels: {
bluebubbles: {
enabled: true,
serverUrl: "http://192.168.1.100:1234",
password: "example-password",
webhookPath: "/bluebubbles-webhook",
},
},
}4. Point the BlueBubbles webhook to your Gateway (example: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>).
5. 启动 gateway；它会注册 webhook handler，并开始 pairing 流程。
Onboarding
BlueBubbles 支持交互式向导：
openclaw onboard
向导会询问：
- Server URL（必填）：BlueBubbles server 地址（例如 http://192.168.1.100:1234）
- Password（必填）：BlueBubbles Server 设置里的 API 密码
- Webhook path（可选）：默认 /bluebubbles-webhook
- 私聊策略（DM policy）：pairing、allowlist、open 或 disabled
- Allow list：手机号、邮箱或 chat targets
你也可以通过 CLI 添加：
openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>
访问控制（私聊 + 群聊）
私聊（DM）：
- 默认：channels.bluebubbles.dmPolicy = "pairing"。
- 未知发送者会收到配对码；在批准之前消息会被忽略（配对码 1 小时过期）。
- 批准方式：
- openclaw pairing list bluebubbles
- openclaw pairing approve bluebubbles <CODE>
- pairing 是默认的 token exchange。细节：/start/pairing
群聊：
- channels.bluebubbles.groupPolicy = open | allowlist | disabled（默认 allowlist）。
- 当 allowlist 时，channels.bluebubbles.groupAllowFrom 控制谁可以在群里触发。
mention 门禁（群聊）
BlueBubbles 的群聊 mention 门禁与 iMessage/WhatsApp 行为一致：
- 使用 agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns）检测 mentions。
- 当某个群的 requireMention 启用时，只有被提到才会回复。
- 受信任的控制命令发送者可以绕过 mention 门禁。
按群配置：
{
channels: {
bluebubbles: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15555550123"],
groups: {
"*": { requireMention: true },
"iMessage;-;chat123": { requireMention: false },
},
},
},
}命令门禁（Command gating）
- 控制命令（例如 /config、/model）需要鉴权。
- 使用 allowFrom 与 groupAllowFrom 判断是否有权限执行控制命令。
- 授权发送者在群里可以不 @mention 也执行控制命令。
输入状态 + 已读回执
- 输入状态（Typing）：在生成回复之前与过程中自动发送。
- 已读回执：由 channels.bluebubbles.sendReadReceipts 控制（默认 true）。
- 输入状态由 BlueBubbles 侧在发送后或超时时自动清除（手动 stop 的 DELETE 调用不可靠）。
{
channels: {
bluebubbles: {
sendReadReceipts: false
},
},
}高级动作（Actions）
启用后，BlueBubbles 支持更高级的消息动作：
{
channels: {
bluebubbles: {
actions: {
reactions: true,
edit: true,
unsend: true,
reply: true,
sendWithEffect: true,
renameGroup: true,
setGroupIcon: true,
addParticipant: true,
removeParticipant: true,
leaveGroup: true,
sendAttachment: true,
},
},
},
}动作列表：
- react：添加/移除 tapback（messageId、emoji、remove）
- edit：编辑已发送消息（messageId、text）（macOS 13+；macOS 26 Tahoe 当前坏掉）
- unsend：撤回消息（messageId）（macOS 13+）
- reply：按指定消息引用回复（messageId、text、to）
- sendWithEffect：发送带 iMessage 特效（text、to、effectId）
- renameGroup：重命名群聊（chatGuid、displayName）
- setGroupIcon：设置群头像（chatGuid、media）（macOS 26 Tahoe 上可能成功但不同步）
- addParticipant：添加群成员（chatGuid、address）
- removeParticipant：移除群成员（chatGuid、address）
- leaveGroup：退出群聊（chatGuid）
- sendAttachment：发送附件/媒体（to、buffer、filename、asVoice）
- 语音条：设置 asVoice: true，并提供 MP3 或 CAF 音频发送为 iMessage 语音消息。BlueBubbles 会在发送语音条时把 MP3 转为 CAF。
Message IDs（短 ID vs 全量 ID）
为节省 tokens，OpenClaw 可能会在上下文中暴露“短 message id”（例如 1、2）。
- MessageSid / ReplyToId 可能是短 ID。
- MessageSidFull / ReplyToIdFull 是提供商的全量 ID。
- 短 ID 是内存缓存：重启或缓存驱逐后会失效。
- Actions 同时接受短/全量 messageId，但短 ID 不再可用时会报错。
如果你要做长期自动化/存储，请使用全量 ID：
- 模板：<code>'{'{MessageSidFull}'}'</code>、<code>'{'{ReplyToIdFull}'}'</code>
- 上下文：入站 payload 中的 MessageSidFull / ReplyToIdFull
模板变量详见 /gateway/configuration。
分块流式发送
控制回复是一次性发送还是按块流式发送：
{
channels: {
bluebubbles: {
blockStreaming: true
},
},
}媒体与限制
- 入站附件会被下载并存入媒体缓存。
- 上限：channels.bluebubbles.mediaMaxMb（默认 8MB）。
- 出站文本会按 channels.bluebubbles.textChunkLimit 分段（默认 4000 字符）。
配置参考
Provider 选项：
- channels.bluebubbles.enabled
- channels.bluebubbles.serverUrl
- channels.bluebubbles.password
- channels.bluebubbles.webhookPath（默认 /bluebubbles-webhook）
- channels.bluebubbles.dmPolicy：pairing | allowlist | open | disabled（默认 pairing）
- channels.bluebubbles.allowFrom：私聊 allowlist（handles、emails、E.164、chat_id:*、chat_guid:*）
- channels.bluebubbles.groupPolicy：open | allowlist | disabled（默认 allowlist）
- channels.bluebubbles.groupAllowFrom
- channels.bluebubbles.groups（按群覆盖：requireMention 等）
- channels.bluebubbles.sendReadReceipts（默认 true）
- channels.bluebubbles.blockStreaming（默认 true）
- channels.bluebubbles.textChunkLimit（默认 4000）
- channels.bluebubbles.chunkMode：length（默认）/ newline
- channels.bluebubbles.mediaMaxMb（默认 8）
- channels.bluebubbles.historyLimit（群上下文条数；0 禁用）
- channels.bluebubbles.dmHistoryLimit
- channels.bluebubbles.actions
- channels.bluebubbles.accounts
相关全局选项：
- agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns）
- messages.responsePrefix
地址与投递目标（targets）
推荐使用 chat_guid 做稳定路由：
- chat_guid:iMessage;-;+15555550123（群聊优先）
- chat_id:123
- chat_identifier:...
- 直接 handle：+15555550123、[email protected]
- 如果该 handle 没有现成的 DM chat，OpenClaw 会通过 POST /api/v1/chat/new 创建一个（需要启用 BlueBubbles Private API）。
安全
- webhook 请求通过比较 query params 或 headers 中的 guid/password 与 channels.bluebubbles.password 来鉴权；来自 localhost 的请求也会被接受。
- 把 API 密码与 webhook endpoint 当作凭据对待（不要泄露）。
- localhost 信任意味着：同机反向代理可能会无意绕过密码。若你代理 gateway，请在 proxy 层做鉴权，并配置 gateway.trustedProxies。见 Gateway security。
- 如果你要把 BlueBubbles server 暴露到 LAN 之外，请启用 HTTPS 并配置防火墙规则。
排障
- 输入状态/已读事件不再工作：检查 BlueBubbles webhook logs，并确认 gateway path 与 channels.bluebubbles.webhookPath 匹配。
- 配对码 1 小时后过期：openclaw pairing list bluebubbles / openclaw pairing approve bluebubbles <code>
- Reactions 需要 BlueBubbles private API（POST /api/v1/message/react）；确认 server 版本暴露该接口。
- edit/unsend 需要 macOS 13+ 与兼容的 BlueBubbles server；macOS 26（Tahoe）上 edit 当前因 private API 变化而不可用。
- 群头像更新在 macOS 26（Tahoe）可能不稳定：API 可能返回成功但图标不同步。
- OpenClaw 会根据 BlueBubbles server 的 macOS 版本自动隐藏已知不可用的动作。如果你在 macOS 26（Tahoe）上仍看到 edit，可用 channels.bluebubbles.actions.edit=false 手动关闭。
- 状态/健康信息：openclaw status --all 或 openclaw status --deep。