OpenClaw接入BlueBubbles方法

BlueBubbles（macOS REST）

状态：内置插件，通过 HTTP 与 BlueBubbles macOS 服务器通信。由于其更丰富的 API 和更简便的设置，推荐用于 iMessage 集成，优于旧版 imsg 渠道。

概述

• 通过 BlueBubbles 辅助应用在 macOS 上运行（bluebubbles.app）。
• 推荐/已测试版本：macOS Sequoia (15)。macOS Tahoe (26) 可用；但在 Tahoe 上编辑功能目前不可用，群组图标更新可能显示成功但实际未同步。
• OpenClaw 通过其 REST API 与之通信（GET /api/v1/ping、POST /message/text、POST /chat/:id/*）。
• 传入消息通过 webhook 到达；发出的回复、输入指示器、已读回执和 tapback 均为 REST 调用。
• 附件和贴纸作为入站媒体被接收（并在可能时呈现给智能体）。
• 配对/白名单的工作方式与其他渠道相同（/channels/pairing等），使用channels.bluebubbles.allowFrom配对码。
• 回应作为系统事件呈现，与 Slack/Telegram 类似，智能体可以在回复前”提及”它们。
• 高级功能：编辑、撤回、回复线程、消息效果、群组管理。

快速开始

1. 在你的 Mac 上安装 BlueBubbles 服务器（按照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. 将 BlueBubbles webhook 指向你的 Gateway 网关（示例：https://your-gateway-host:3000/bluebubbles-webhook?password=<password）。

5. 启动 Gateway 网关；它将注册 webhook 处理程序并开始配对。

新手引导

BlueBubbles 可在交互式设置向导中使用：

向导会提示输入：

• 服务器 URL（必填）：BlueBubbles 服务器地址（例如http://192.168.1.100:1234）
• 密码（必填）：来自 BlueBubbles 服务器设置的 API 密码
• Webhook 路径（可选）：默认为/bluebubbles-webhook
• 私信策略：配对、白名单、开放或禁用
• 白名单：电话号码、电子邮件或聊天目标

你也可以通过 CLI 添加 BlueBubbles：

openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password

访问控制（私信 + 群组）

私信：

• 默认：channels.bluebubbles.dmPolicy = "pairing"。
• 未知发送者会收到配对码；在批准之前消息会被忽略（配对码 1 小时后过期）。
• 批准方式：
• openclaw pairing list bluebubbles
• openclaw pairing approve bluebubbles <CODE
• 配对是默认的令牌交换方式。详情：配对

群组：

• channels.bluebubbles.groupPolicy = open | allowlist | disabled（默认：allowlist）。
• 当设置为allowlist时，channels.bluebubbles.groupAllowFrom控制谁可以在群组中触发。

提及门控（群组）

BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致：

• 使用agents.list[].groupChat.mentionPatterns（或messages.groupChat.mentionPatterns）检测提及。
• 当群组启用requireMention时，智能体仅在被提及时响应。
• 来自授权发送者的控制命令会绕过提及门控。

单群组配置：

{ channels: { bluebubbles: { groupPolicy: "allowlist", groupAllowFrom: ["+15555550123"], groups: { "*": { requireMention: true }, // 所有群组的默认设置 "iMessage;-;chat123": { requireMention: false }, // 特定群组的覆盖设置 }, }, }, }

命令门控

• 控制命令（例如/config、/model）需要授权。
• 使用allowFrom和groupAllowFrom确定命令授权。
• 授权发送者即使在群组中未被提及也可以运行控制命令。

输入状态 + 已读回执

• 输入指示器：在响应生成前和生成期间自动发送。
• 已读回执：由channels.bluebubbles.sendReadReceipts控制（默认：true）。
• 输入指示器：OpenClaw 发送输入开始事件；BlueBubbles 在发送或超时时自动清除输入状态（通过 DELETE 手动停止不可靠）。

{ channels: { bluebubbles: { sendReadReceipts: false, // 禁用已读回执 }, }, }

高级操作

BlueBubbles 在配置中启用时支持高级消息操作：

{ channels: { bluebubbles: { actions: { reactions: true, // tapback（默认：true） edit: true, // 编辑已发送消息（macOS 13+，在 macOS 26 Tahoe 上不可用） unsend: true, // 撤回消息（macOS 13+） reply: true, // 通过消息 GUID 进行回复线程 sendWithEffect: true, // 消息效果（slam、loud 等） renameGroup: true, // 重命名群聊 setGroupIcon: true, // 设置群聊图标/照片（在 macOS 26 Tahoe 上不稳定） addParticipant: true, // 将参与者添加到群组 removeParticipant: true, // 从群组移除参与者 leaveGroup: true, // 离开群聊 sendAttachment: true, // 发送附件/媒体 }, }, }, }

可用操作：

• react：添加/移除 tapback 回应（messageId、emoji、remove）
• edit：编辑已发送的消息（messageId、text）
• unsend：撤回消息（messageId）
• reply：回复特定消息（messageId、text、to）
• sendWithEffect：带 iMessage 效果发送（text、to、effectId）
• renameGroup：重命名群聊（chatGuid、displayName）
• setGroupIcon：设置群聊图标/照片（chatGuid、media）— 在 macOS 26 Tahoe 上不稳定（API 可能返回成功但图标未同步）。
• addParticipant：将某人添加到群组（chatGuid、address）
• removeParticipant：将某人从群组移除（chatGuid、address）
• leaveGroup：离开群聊（chatGuid）
• sendAttachment：发送媒体/文件（to、buffer、filename、asVoice）
• 语音备忘录：将asVoice: true与MP3或CAF音频一起设置，以 iMessage 语音消息形式发送。BlueBubbles 在发送语音备忘录时会将 MP3 转换为 CAF。

消息 ID（短格式 vs 完整格式）

OpenClaw 可能会显示短消息 ID（例如1、2）以节省 token。

• MessageSid/ReplyToId可以是短 ID。
• MessageSidFull/ReplyToIdFull包含提供商的完整 ID。
• 短 ID 存储在内存中；它们可能在重启或缓存清除后过期。
• 操作接受短或完整的messageId，但如果短 ID 不再可用将会报错。

对于持久化自动化和存储，请使用完整 ID：

• 模板：{{MessageSidFull}}、{{ReplyToIdFull}}
• 上下文：入站负载中的MessageSidFull/ReplyToIdFull

参见配置了解模板变量。

分块流式传输

控制响应是作为单条消息发送还是分块流式传输：

{ channels: { bluebubbles: { blockStreaming: true, // 启用分块流式传输（默认关闭） }, }, }

媒体 + 限制

• 入站附件会被下载并存储在媒体缓存中。
• 媒体上限通过channels.bluebubbles.mediaMaxMb设置（默认：8 MB）。
• 出站文本按channels.bluebubbles.textChunkLimit分块（默认：4000 字符）。

配置参考

完整配置：配置提供商选项：

• channels.bluebubbles.enabled：启用/禁用渠道。
• channels.bluebubbles.serverUrl：BlueBubbles REST API 基础 URL。
• channels.bluebubbles.password：API 密码。
• channels.bluebubbles.webhookPath：Webhook 端点路径（默认：/bluebubbles-webhook）。
• channels.bluebubbles.dmPolicy：pairing | allowlist | open | disabled（默认：pairing）。
• channels.bluebubbles.allowFrom：私信白名单（句柄、电子邮件、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：启用分块流式传输（默认：false；流式回复必需）。
• channels.bluebubbles.textChunkLimit：出站分块大小（字符）（默认：4000）。
• channels.bluebubbles.chunkMode：length（默认）仅在超过textChunkLimit时分割；newline在长度分块前先按空行（段落边界）分割。
• channels.bluebubbles.mediaMaxMb：入站媒体上限（MB）（默认：8）。
• channels.bluebubbles.historyLimit：上下文的最大群组消息数（0 表示禁用）。
• channels.bluebubbles.dmHistoryLimit：私信历史限制。
• channels.bluebubbles.actions：启用/禁用特定操作。
• channels.bluebubbles.accounts：多账户配置。

相关全局选项：

• agents.list[].groupChat.mentionPatterns（或messages.groupChat.mentionPatterns）。
• messages.responsePrefix。

地址 / 投递目标

优先使用chat_guid以获得稳定的路由：

• chat_guid:iMessage;-;+15555550123（群组推荐）
• chat_id:123
• chat_identifier:...
• 直接句柄：+15555550123、user@example.com
• 如果直接句柄没有现有的私信聊天，OpenClaw 将通过POST /api/v1/chat/new创建一个。这需要启用 BlueBubbles Private API。

安全性

• Webhook 请求通过比较guid/password查询参数或头部与channels.bluebubbles.password进行身份验证。来自localhost的请求也会被接受。
• 保持 API 密码和 webhook 端点的机密性（将它们视为凭证）。
• localhost 信任意味着同主机的反向代理可能无意中绕过密码验证。如果你使用代理 Gateway 网关，请在代理处要求身份验证并配置gateway.trustedProxies。参见Gateway 网关安全性。
• 如果将 BlueBubbles 服务器暴露在局域网之外，请启用 HTTPS + 防火墙规则。

故障排除

• 如果输入/已读事件停止工作，请检查 BlueBubbles webhook 日志并验证 Gateway 网关路径是否与channels.bluebubbles.webhookPath匹配。
• 配对码在一小时后过期；使用openclaw pairing list bluebubbles和openclaw pairing approve bluebubbles <code。
• 回应需要 BlueBubbles private API（POST /api/v1/message/react）；确保服务器版本支持它。
• 编辑/撤回需要 macOS 13+ 和兼容的 BlueBubbles 服务器版本。在 macOS 26（Tahoe）上，由于 private API 变更，编辑功能目前不可用。
• 在 macOS 26（Tahoe）上群组图标更新可能不稳定：API 可能返回成功但新图标未同步。
• OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知不可用的操作。如果在 macOS 26（Tahoe）上编辑仍然显示，请使用channels.bluebubbles.actions.edit=false手动禁用。
• 查看状态/健康信息：openclaw status --all或openclaw status --deep。

有关通用渠道工作流参考，请参阅渠道和插件指南。