BlueBubbles (macOS REST)

状态：内置插件，通过 HTTP 与 BlueBubbles macOS 服务端通信。推荐用于 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 接收；出站回复、输入指示、已读回执和 tapback 回应均为 REST 调用。
  • 附件和贴纸作为入站媒体被接收（在可能的情况下会提供给 Agent）。
  • 配对/白名单机制与其他频道相同（/channels/pairing 等），使用 channels.bluebubbles.allowFrom + 配对码。
  • 表情回应以系统事件形式呈现，与 Slack/Telegram 类似，Agent 可在回复前”引用”它们。
  • 高级功能：编辑、撤回、回复线程、消息效果、群组管理。

快速开始

  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 处理器并开始配对。

安全提示：

  • 务必设置 webhook 密码。
  • Webhook 认证始终是必需的。OpenClaw 会拒绝未包含与 channels.bluebubbles.password 匹配的 password/guid 参数的 BlueBubbles webhook 请求（例如 ?password=<password> 或 x-password），无论网络拓扑如何。
  • 在读取/解析完整 webhook 请求体之前就会进行密码验证。

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

部分 macOS 虚拟机或常驻运行的环境可能出现 Messages.app 进入”空闲”状态的情况（收不到新事件，直到手动打开/前台化该应用）。一个简单的解决方案是使用 AppleScript + LaunchAgent 每 5 分钟唤醒一次 Messages。

1) 保存 AppleScript

保存为：

  • ~/Scripts/poke-messages.scpt

示例脚本（非交互式；不会抢占焦点）：

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 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 的同一用户会话中批准这些提示。

加载方式：

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
  • 私信策略：配对、白名单、开放或禁用
  • 白名单：电话号码、邮箱或聊天目标

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

提及门控（群组）

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

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

按群组配置：

{
  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, // 消息效果（猛击、大声等）
        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（短 ID 与完整 ID）

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

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

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

  • 模板：{{MessageSidFull}}、{{ReplyToIdFull}}
  • 上下文：入站 payload 中的 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.mediaLocalRoots：允许出站本地媒体路径的绝对目录白名单。除非配置此项，否则默认拒绝本地路径发送。按账户覆盖：channels.bluebubbles.accounts.<accountId>.mediaLocalRoots。
  • 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、[email protected]
    • 如果直接句柄没有现有的私信聊天，OpenClaw 会通过 POST /api/v1/chat/new 创建一个。这需要启用 BlueBubbles Private API。

安全

  • Webhook 请求通过比对 guid/password 查询参数或 header 与 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。

有关频道工作流的一般参考，请参阅频道和插件指南。

arrow_back
上一页
Channels
下一页
Discord
arrow_forward