跳到主要内容

BlueBubbles (iMessage) 设置

通过 BlueBubbles 将 Hermes 连接到 Apple iMessage — 这是一个免费、开源的 macOS 服务器，将 iMessage 桥接到任何设备。

前置要求​

  • 一台始终在线的 Mac，运行 BlueBubbles Server
  • Apple ID 已登录到该 Mac 上的 Messages.app
  • BlueBubbles Server v1.0.0+（webhook 需要此版本）
  • Hermes 与 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. 配置 Hermes​

运行设置向导：

hermes gateway setup

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

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

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

4. 授权用户​

选择一种方式：

DM 配对（推荐）： 当有人发送 iMessage 时，Hermes 自动发送配对码。使用以下命令审批：

hermes pairing approve bluebubbles <CODE>

使用 hermes pairing list 查看待审批码和已批准用户。

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

BLUEBUBBLES_ALLOWED_USERS=[email protected],+15551234567

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

BLUEBUBBLES_ALLOW_ALL_USERS=true

5. 启动网关​

hermes gateway run

Hermes 将连接到 BlueBubbles 服务器，注册 webhook 并开始监听 iMessage 消息。

工作原理​

iMessage → Messages.app → BlueBubbles Server → Webhook → Hermes
Hermes → BlueBubbles REST API → Messages.app → iMessage
  • 入站： 新消息到达时，BlueBubbles 将 webhook 事件发送到本地监听器。无轮询 — 即时交付。
  • 出站： Hermes 通过 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允许所有用户
BLUEBUBBLES_SEND_READ_RECEIPTS否true自动标记消息为已读

功能​

文本消息​

发送和接收 iMessage。Markdown 会自动去除以提供纯文本。

富媒体​

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

Tapback 反应​

喜欢、点赞、踩、笑、强人和疑问反应。需要 BlueBubbles Private API helper。

打字指示器​

当 agent 处理时，在 iMessage 对话中显示"typing..."。需要 Private API。

已读回执​

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

聊天寻址​

可以通过邮箱或电话号码寻址聊天 — Hermes 自动将其解析为 BlueBubbles 聊天 GUID。无需使用原始 GUID 格式。

Private API​

某些功能需要 BlueBubbles Private API helper：

  • Tapback 反应
  • 打字指示器
  • 已读回执
  • 通过地址创建新聊天

没有 Private API，基本文本消息和媒体仍可正常工作。

故障排除​

"无法连接服务器"​

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

消息未到达​

  • 检查 webhook 是否在 BlueBubbles Server → Settings → API → Webhooks 中注册
  • 验证 webhook URL 可从 Mac 访问
  • 检查 hermes logs gateway 中的 webhook 错误（或 hermes logs -f 实时跟踪）

"Private API helper 未连接"​

  • 安装 Private API helper：docs.bluebubbles.app
  • 基本消息功能可以正常工作 — 只有反应、打字和已读回执需要它