Skip to Content
👋 欢迎来到 HowToUseMoltbot 快速入门
频道Blue Bubbles

BlueBubbles（macOS REST）

状态：内置插件，通过 HTTP 与 BlueBubbles macOS 服务端通信。iMessage 集成推荐方案，API 更丰富、配置比旧版 imsg 频道更简单。

概览

  • 在 macOS 上通过 BlueBubbles 辅助应用运行（bluebubbles.app ）。
  • 推荐/测试：macOS Sequoia (15)。macOS Tahoe (26) 可用；Tahoe 上编辑当前不可用，群组头像更新可能显示成功但不同步。
  • Moltbot 通过 REST API（GET /api/v1/ping、POST /message/text、POST /chat/:id/*）与之通信。
  • 入站消息经 webhook；出站回复、输入中、已读回执和 tapback 为 REST 调用。
  • 附件和贴纸作为入站媒体摄入（并在可能时提供给 agent）。
  • 配对/白名单与其他频道相同（/start/pairing 等），使用 channels.bluebubbles.allowFrom 与配对码。
  • 表态作为系统事件暴露，与 Slack/Telegram 一致，agent 可在回复前「提及」它们。
  • 高级功能：编辑、撤回、回复主题、消息效果、群组管理。

快速开始

  1. 在 Mac 上安装 BlueBubbles 服务端（按 bluebubbles.app/install  说明）。
  2. 在 BlueBubbles 配置中启用 Web API 并设置密码。
  3. 运行 moltbot onboard 并选择 BlueBubbles，或手动配置：
{
     channels: {
       bluebubbles: {
         enabled: true,
         serverUrl: "http://192.168.1.100:1234",
         password: "example-password",
         webhookPath: "/bluebubbles-webhook"
       }
     }
}
  1. 将 BlueBubbles webhook 指向你的网关（示例：https://your-gateway-host:3000/bluebubbles-webhook?password=<password>）。
  2. 启动网关；会注册 webhook 处理并开始配对。

引导

BlueBubbles 可在交互式设置向导中选择：

moltbot onboard

向导会询问：

  • Server URL（必填）：BlueBubbles 服务端地址（如 http://192.168.1.100:1234）
  • Password（必填）：BlueBubbles Server 设置中的 API 密码
  • Webhook path（可选）：默认 /bluebubbles-webhook
  • DM policy：pairing、allowlist、open 或 disabled
  • Allow list：手机号、邮箱或会话目标

也可通过 CLI 添加 BlueBubbles：

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

访问控制（私聊 + 群组）

私聊：

  • 默认：channels.bluebubbles.dmPolicy = "pairing"。
  • 未知发件人收到配对码；批准前消息被忽略（配对码 1 小时后过期）。
  • 批准方式：
    • moltbot pairing list bluebubbles
    • moltbot pairing approve bluebubbles <CODE>
  • 配对为默认 token 交换。详见 配对。

群组：

  • 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）。
  • 输入中：Moltbot 发送输入开始事件；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）

    • 语音备忘录：用 MP3 或 CAF 音频并设 asVoice: true 以 iMessage 语音消息发送。BlueBubbles 在发送语音备忘录时会做 MP3 → CAF 转换。

消息 ID（短 ID 与完整 ID）

Moltbot 可能暴露短消息 ID（如 1、2）以节省 token。

  • MessageSid / ReplyToId 可能是短 ID。
  • MessageSidFull / ReplyToIdFull 为提供方完整 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：私聊白名单（handle、邮箱、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（默认）仅在超过 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:...
  • 直接 handle：+15555550123、user@example.com
    • 若直接 handle 尚无私聊会话，Moltbot 会通过 POST /api/v1/chat/new 创建。需启用 BlueBubbles Private API。

安全

  • Webhook 请求通过比对 guid/password 查询参数或头与 channels.bluebubbles.password 认证。来自 localhost 的请求也会接受。
  • 将 API 密码和 webhook 端点视为机密（当凭据保管）。
  • 信任 localhost 意味着同机反向代理可能绕过密码。若对网关做代理，请在代理层做认证并配置 gateway.trustedProxies。见 网关安全。
  • 若在局域网外暴露 BlueBubbles 服务端，请启用 HTTPS 并配置防火墙规则。

故障排查

  • 若输入中/已读事件不工作，检查 BlueBubbles webhook 日志并确认网关路径与 channels.bluebubbles.webhookPath 一致。
  • 配对码 1 小时后过期；使用 moltbot pairing list bluebubbles 和 moltbot pairing approve bluebubbles <code>。
  • 表态需要 BlueBubbles private API（POST /api/v1/message/react）；确认服务端版本已暴露该接口。
  • 编辑/撤回需 macOS 13+ 及兼容的 BlueBubbles 服务端版本。macOS 26 (Tahoe) 上因 private API 变更，编辑当前不可用。
  • macOS 26 (Tahoe) 上群组头像更新可能不稳定：API 可能返回成功但新头像不同步。
  • Moltbot 会根据 BlueBubbles 服务端 macOS 版本自动隐藏已知不可用动作。若在 macOS 26 (Tahoe) 上仍显示编辑，可手动关闭：channels.bluebubbles.actions.edit=false。
  • 状态/健康信息：moltbot status --all 或 moltbot status --deep。

频道流程总览见 频道 与 插件 指南。

最后更新于:
频道总览Discord