BlueBubbles（macOS REST）

这是 OpenClaw 内置插件，通过 BlueBubbles macOS 辅助应用的 HTTP REST API 与 iMessage 通信。推荐用于 iMessage 集成，功能更丰富，配置比旧版 imsg 渠道更简单。

概述

运行于 macOS，需安装 BlueBubbles 辅助应用（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 调用
附件和贴纸作为入站媒体处理（尽可能暴露给 agent）
配对/白名单机制与其他渠道相同（/openclaw/channels/pairing），使用 channels.bluebubbles.allowFrom 和配对码
回应作为系统事件浮出，与 Slack/Telegram 一致，agent 可在回复前"看到"它们
高级功能：编辑、撤回、回复串、消息特效、群组管理

快速开始

在 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 Webhook 指向你的 Gateway（示例：https://your-gateway-host:3000/bluebubbles-webhook?password=<password>）
启动 Gateway，它会注册 Webhook 处理器并开始配对流程

安全提示：

务必设置 Webhook 密码
Webhook 认证是强制要求。OpenClaw 会拒绝不含密码/guid 的 BlueBubbles Webhook 请求（例如 ?password=<password> 或 x-password），无论来自回环还是代理
密码验证在读取/解析完整 Webhook 正文之前进行

保持 Messages.app 活跃（虚拟机/无头环境）

某些 macOS 虚拟机或常驻设置中，Messages.app 可能进入"空闲"状态（直到打开/前置才会继续收到事件）。一个简单的解决方案是使用 AppleScript + LaunchAgent 每 5 分钟"戳一下" Messages。

1）保存 AppleScript

保存到：~/Scripts/poke-messages.scpt

applescript

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

    -- 触摸脚本接口以保持进程响应
    set _chatCount to (count of chats)
  end tell
on error
  -- 忽略临时失败（首次运行提示、锁定会话等）
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
私信策略：pairing（配对）、allowlist（白名单）、open（开放）或 disabled（禁用）
允许列表：电话号码、邮箱或聊天目标

也可通过 CLI 添加：

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）
channels.bluebubbles.groupAllowFrom 在 allowlist 模式下控制谁可以在群组中触发

联系人名称增强（macOS，可选）

BlueBubbles 群组 Webhook 通常只包含原始参与者地址。如需在 GroupMembers 上下文中显示本地通讯录名称：

channels.bluebubbles.enrichGroupParticipantsFromContacts = true 启用查询，默认 false
仅在群组访问、命令授权和提及门控通过后才运行
只对无名称的电话参与者增强
当本地无匹配时，原始电话号码作为回退

json5

{
  channels: {
    bluebubbles: {
      enrichGroupParticipantsFromContacts: true,
    },
  },
}

提及门控（群组）

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

使用 agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns）检测提及
启用 requireMention 时，agent 只在被提及时才回复
已授权发送者的控制命令可绕过提及门控

按群组配置：

json5

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

命令门控

控制命令（如 /config、/model）需要授权
使用 allowFrom 和 groupAllowFrom 确定命令授权
已授权发送者即使在群组中不提及也可执行控制命令

打字提示 + 已读回执

打字提示：在回复生成前和生成期间自动发送
已读回执：由 channels.bluebubbles.sendReadReceipts 控制（默认：true）
打字提示：OpenClaw 发送打字开始事件；BlueBubbles 在发送或超时时自动清除打字状态

json5

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

高级操作

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

json5

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true,        // tapback 回应（默认：true）
        edit: true,             // 编辑已发送消息（macOS 13+，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 上不稳定
addParticipant：向群组添加成员（chatGuid、address）
removeParticipant：从群组移除成员（chatGuid、address）
leaveGroup：离开群聊（chatGuid）
upload-file：发送媒体/文件（to、buffer、filename、asVoice）
- 语音备忘录：将 asVoice: true 与 MP3 或 CAF 音频一起使用可发送 iMessage 语音消息；BlueBubbles 会将 MP3 转换为 CAF
旧版别名：sendAttachment 仍可用，但 upload-file 是规范操作名

消息 ID（短 ID vs 完整 ID）

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

MessageSid / ReplyToId 可以是短 ID
MessageSidFull / ReplyToIdFull 包含提供商完整 ID
短 ID 存于内存，重启或缓存失效后会消失
操作接受短 ID 或完整 messageId，但短 ID 若不再可用会报错

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

模板：、
上下文：入站载荷中的 MessageSidFull / ReplyToIdFull

参见配置了解模板变量。

分块流式传输

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

json5

{
  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：私信白名单（handles、邮箱、E.164 号码、chat_id:*、chat_guid:*）
channels.bluebubbles.groupPolicy：open | allowlist | disabled（默认：allowlist）
channels.bluebubbles.groupAllowFrom：群组发送者白名单
channels.bluebubbles.enrichGroupParticipantsFromContacts：macOS 上可选增强群组参与者名称，默认 false
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：入站/出站媒体上限（默认：8 MB）
channels.bluebubbles.mediaLocalRoots：出站本地媒体路径允许的绝对本地目录白名单（默认拒绝）
channels.bluebubbles.historyLimit：群组最大上下文消息数（0 禁用）
channels.bluebubbles.dmHistoryLimit：私信历史限制
channels.bluebubbles.actions：启用/禁用特定操作
channels.bluebubbles.accounts：多账号配置

寻址 / 投递目标

推荐使用 chat_guid 确保稳定路由：

chat_guid:iMessage;-;+15555550123（群组推荐）
chat_id:123
chat_identifier:...
直接 handle：+15555550123、user@example.com
- 若直接 handle 没有现有的私信聊天，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 一致
配对码 1 小时后过期，使用 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

养好你的龙虾并接上 iMessage，就能让它帮你处理 Apple 生态的消息了。一般渠道工作流参见渠道和插件指南。

BlueBubbles（macOS REST） ​

概述 ​

快速开始 ​

保持 Messages.app 活跃（虚拟机/无头环境） ​

1）保存 AppleScript ​

2）安装 LaunchAgent ​

引导配置 ​

访问控制（私信 + 群组） ​

联系人名称增强（macOS，可选） ​

提及门控（群组） ​

命令门控 ​

打字提示 + 已读回执 ​

高级操作 ​

消息 ID（短 ID vs 完整 ID） ​

分块流式传输 ​

媒体 + 限制 ​

配置参考 ​

寻址 / 投递目标 ​

安全 ​

故障排除 ​

BlueBubbles（macOS REST）

概述

快速开始

保持 Messages.app 活跃（虚拟机/无头环境）

1）保存 AppleScript

2）安装 LaunchAgent

引导配置

访问控制（私信 + 群组）

联系人名称增强（macOS，可选）

提及门控（群组）

命令门控

打字提示 + 已读回执

高级操作

消息 ID（短 ID vs 完整 ID）

分块流式传输

媒体 + 限制

配置参考

寻址 / 投递目标

安全

故障排除