跳到主要内容

BlueBubbles（iMessage）

通过 BlueBubbles 将 AigenLabs 连接至 Apple iMessage——这是一款免费、开源的 macOS 服务端，可将 iMessage 桥接至任意设备。

前提条件​

  • 一台始终开机的 Mac，运行 BlueBubbles Server
  • 该 Mac 上的 Messages.app 已登录 Apple ID
  • BlueBubbles Server v1.0.0+（webhook 需要此版本）
  • AigenLabs 与 BlueBubbles 服务端之间的网络连通性

配置步骤​

1. 安装 BlueBubbles Server​

从 bluebubbles.app 下载并安装。完成设置向导——使用 Apple ID 登录，并配置连接方式（本地网络、Ngrok、Cloudflare 或动态 DNS）。

2. 获取服务端 URL 和密码​

在 BlueBubbles Server → Settings → API 中，记录：

  • Server URL（例如 http://192.168.1.10:1234）
  • Server Password

3. 配置 AigenLabs​

运行设置向导：

aigenlabs gateway setup

选择 BlueBubbles (iMessage) 并输入服务端 URL 和密码。

或直接在 ~/.aigenlabs/.env 中设置环境变量：

BLUEBUBBLES_SERVER_URL=http://192.168.1.10:1234
BLUEBUBBLES_PASSWORD=your-server-password

4. 授权用户​

选择以下任一方式：

DM 配对（推荐）： 当有人向你的 iMessage 发送消息时，AigenLabs 会自动向其发送配对码。使用以下命令批准：

aigenlabs pairing approve bluebubbles <CODE>

使用 aigenlabs pairing list 查看待处理的配对码和已授权用户。

预授权特定用户（在 ~/.aigenlabs/.env 中）：

BLUEBUBBLES_ALLOWED_USERS=user@icloud.com,+15551234567

开放访问（在 ~/.aigenlabs/.env 中）：

BLUEBUBBLES_ALLOW_ALL_USERS=true

5. 启动 Gateway​

aigenlabs gateway run

AigenLabs 将连接至你的 BlueBubbles 服务端，注册 webhook，并开始监听 iMessage 消息。

工作原理​

iMessage → Messages.app → BlueBubbles Server → Webhook → AigenLabs
AigenLabs → BlueBubbles REST API → Messages.app → iMessage
  • 入站： 新消息到达时，BlueBubbles 向本地监听器发送 webhook 事件。无需轮询——即时送达。
  • 出站： AigenLabs 通过 BlueBubbles REST API 发送消息。
  • 媒体： 双向支持图片、语音消息、视频和文档。入站附件会被下载并在本地缓存，供 Agent 处理。

环境变量​

变量必填默认值说明
BLUEBUBBLES_SERVER_URL是—BlueBubbles 服务端 URL
BLUEBUBBLES_PASSWORD是—服务端密码
BLUEBUBBLES_WEBHOOK_HOST否127.0.0.1Webhook 监听器绑定地址
BLUEBUBBLES_WEBHOOK_PORT否8645Webhook 监听器端口
BLUEBUBBLES_WEBHOOK_PATH否/bluebubbles-webhookWebhook URL 路径
BLUEBUBBLES_HOME_CHANNEL否—cron 投递使用的手机号/邮箱
BLUEBUBBLES_ALLOWED_USERS否—逗号分隔的授权用户列表
BLUEBUBBLES_ALLOW_ALL_USERS否false允许所有用户

自动将消息标记为已读由 ~/.aigenlabs/config.yaml 中 platforms.bluebubbles.extra 下的 send_read_receipts 键控制（默认值：true）。该选项没有对应的环境变量。

功能特性​

文字消息​

发送和接收 iMessage。Markdown 会自动去除，以确保纯文本的整洁呈现。

富媒体​

  • 图片： 照片在 iMessage 对话中原生显示
  • 语音消息： 音频文件以 iMessage 语音消息形式发送
  • 视频： 视频附件
  • 文档： 文件以 iMessage 附件形式发送

Tapback 反应​

支持喜爱、点赞、踩、大笑、强调和疑问等反应。需要 BlueBubbles Private API helper。

正在输入指示器​

Agent 处理消息期间，iMessage 对话中会显示"正在输入……"。需要 Private API。

已读回执​

处理消息后自动标记为已读。需要 Private API。

聊天寻址​

你可以通过邮箱或手机号寻址聊天——AigenLabs 会自动将其解析为 BlueBubbles 聊天 GUID，无需使用原始 GUID 格式。

Private API​

部分功能需要 BlueBubbles Private API helper：

  • Tapback 反应
  • 正在输入指示器
  • 已读回执
  • 通过地址创建新聊天

不使用 Private API 时，基本文字消息和媒体功能仍可正常使用。

故障排查​

"Cannot reach server"​

  • 确认服务端 URL 正确且 Mac 已开机
  • 检查 BlueBubbles Server 是否正在运行
  • 确保网络连通（防火墙、端口转发）

消息未送达​

  • 检查 webhook 是否已在 BlueBubbles Server → Settings → API → Webhooks 中注册
  • 确认 webhook URL 可从 Mac 访问
  • 查看 aigenlabs logs gateway 中的 webhook 错误（或使用 aigenlabs logs -f 实时跟踪）

"Private API helper not connected"​

  • 安装 Private API helper：docs.bluebubbles.app
  • 不安装也可使用基本消息功能——仅反应、正在输入和已读回执需要它