BlueBubbles (macOS REST)

状态:与 BlueBubbles macOS 服务器通过 HTTP 通信的捆绑插件。推荐用于 iMessage 集成,因其相比传统 imsg 频道具有更丰富的 API 和更简单的设置。

概述

通过 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 到达;发送回复、输入指示器、已读回执和点按反应都是 REST 调用。
附件和贴纸作为入站媒体提取(并在可能时呈现给代理)。
配对/白名单的工作方式与其他频道相同(/start/pairing 等),使用 channels.bluebubbles.allowFrom + 配对码。
反应作为系统事件呈现,就像 Slack/Telegram 一样,因此代理可以在回复前"提及"它们。
高级功能:编辑、撤回、回复线程、消息效果、群组管理。

快速开始

在您的 Mac 上安装 BlueBubbles 服务器(遵循 bluebubbles.app/install 上的说明)。
在 BlueBubbles 配置中,启用 Web API 并设置密码。

运行 openclaw onboard 并选择 BlueBubbles,或手动配置:

json5

{
  channels: {
    bluebubbles: {
      enabled: true,
      serverUrl: "http://192.168.1.100:1234",
      password: "example-password",
      webhookPath: "/bluebubbles-webhook",
    },
  },
}

将 BlueBubbles webhooks 指向您的网关(例如:https://your-gateway-host:3000/bluebubbles-webhook?password=<password>)。
启动网关;它将注册 webhook 处理程序并开始配对。

保持 Messages.app 活跃(VM / 无头设置)

某些 macOS VM / 常驻设置可能导致 Messages.app 进入"空闲"状态(传入事件停止,直到应用被打开/前台显示)。一个简单的解决方法是每 5 分钟使用 AppleScript + LaunchAgent 唤醒 Messages。

1) 保存 AppleScript

将此保存为:

~/Scripts/poke-messages.scpt

示例脚本(非交互式;不会抢夺焦点):

applescript

try
  tell application "Messages"
    if not running then
      launch
    end if

    -- Touch the scripting interface to keep the process responsive.
    set _chatCount to (count of chats)
  end tell
on error
  -- Ignore transient failures (first-run prompts, locked session, etc).
end try

2) 安装 LaunchAgent

将此保存为:

~/Library/LaunchAgents/com.user.poke-messages.plist

xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.user.poke-messages</string>

    <key>ProgramArguments</key>
    <array>
      <string>/bin/bash</string>
      <string>-lc</string>
      <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>StartInterval</key>
    <integer>300</integer>

    <key>StandardOutPath</key>
    <string>/tmp/poke-messages.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/poke-messages.err</string>
  </dict>
</plist>

注意:

这将每 300 秒运行一次,并且在登录时运行。
首次运行可能会触发 macOS 自动化提示(osascript → Messages)。在运行 LaunchAgent 的同一用户会话中批准它们。

加载它:

bash

launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist

入门

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

openclaw onboard

向导会提示输入:

服务器 URL(必需):BlueBubbles 服务器地址(例如,http://192.168.1.100:1234)
密码(必需):来自 BlueBubbles 服务器设置的 API 密码
Webhook 路径(可选):默认为 /bluebubbles-webhook
DM 策略:pairing、allowlist、open 或 disabled
允许列表:电话号码、电子邮件或聊天目标

您也可以通过 CLI 添加 BlueBubbles:

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

访问控制(DM + 群组)

DM:

默认: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 时,代理仅在被提及时响应。
来自授权发送者的控制命令绕过提及限制。

每个群组的配置:

json5

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // default for all groups
        "iMessage;-;chat123": { requireMention: false }, // override for specific group
      },
    },
  },
}

命令限制

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

输入状态 + 已读回执

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

json5

{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // disable read receipts
    },
  },
}

高级操作

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

json5

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // tapbacks (default: true)
        edit: true, // edit sent messages (macOS 13+, broken on macOS 26 Tahoe)
        unsend: true, // unsend messages (macOS 13+)
        reply: true, // reply threading by message GUID
        sendWithEffect: true, // message effects (slam, loud, etc.)
        renameGroup: true, // rename group chats
        setGroupIcon: true, // set group chat icon/photo (flaky on macOS 26 Tahoe)
        addParticipant: true, // add participants to groups
        removeParticipant: true, // remove participants from groups
        leaveGroup: true, // leave group chats
        sendAttachment: true, // send attachments/media
      },
    },
  },
}

可用操作:

react:添加/移除点按反应(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)以节省令牌。

MessageSid / ReplyToId 可以是短 ID。
MessageSidFull / ReplyToIdFull 包含提供者的完整 ID。
短 ID 存储在内存中;它们可能在重启或缓存清除时过期。
操作接受短或完整 messageId,但短 ID 如果不再可用将出错。

对于持久自动化和存储,使用完整 ID:

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

参见配置了解模板变量。

阻塞流式传输

控制响应是作为单条消息发送还是以块的形式流式传输:

json5

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // enable block streaming (off by default)
    },
  },
}

媒体 + 限制

入站附件被下载并存储在媒体缓存中。
媒体上限通过 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:DM 白名单(句柄、电子邮件、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:DM 历史记录限制。
channels.bluebubbles.actions:启用/禁用特定操作。
channels.bluebubbles.accounts:多账户配置。

寻址 / 传递目标

优先使用 chat_guid 以实现稳定路由:

chat_guid:iMessage;-;+15555550123(群组首选)
chat_id:123
chat_identifier:...
直接句柄:+15555550123、user@example.com
- 如果直接句柄没有现有的 DM 聊天,OpenClaw 将通过 POST /api/v1/chat/new 创建一个。这需要启用 BlueBubbles Private API。

安全性

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

故障排除

如果输入/已读事件停止工作,请检查 BlueBubbles webhook 日志并验证网关路径是否匹配 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。

有关一般频道工作流参考,请参见频道和插件指南。

BlueBubbles (macOS REST) ​

概述 ​

快速开始 ​

保持 Messages.app 活跃(VM / 无头设置) ​

1) 保存 AppleScript ​

2) 安装 LaunchAgent ​

入门 ​

访问控制(DM + 群组) ​

提及限制(群组) ​

命令限制 ​

输入状态 + 已读回执 ​

高级操作 ​

消息 ID(短 vs 完整) ​

阻塞流式传输 ​

媒体 + 限制 ​

配置参考 ​

寻址 / 传递目标 ​

安全性 ​

故障排除 ​

BlueBubbles (macOS REST)

概述

快速开始

保持 Messages.app 活跃(VM / 无头设置)

1) 保存 AppleScript

2) 安装 LaunchAgent

入门

访问控制(DM + 群组)

提及限制(群组)

命令限制

输入状态 + 已读回执

高级操作

消息 ID(短 vs 完整)

阻塞流式传输

媒体 + 限制

配置参考

寻址 / 传递目标

安全性

故障排除