跳到主要内容

BlueBubbles（iMessage）

通过 BlueBubbles 将 Hermes 接入 Apple iMessage。BlueBubbles 是一个免费、开源的 macOS 服务端，可把 iMessage 桥接到任意设备。

前提条件​

  • 一台持续在线、运行 BlueBubbles Server 的 Mac
  • 该 Mac 上的 Messages.app 已登录 Apple ID
  • BlueBubbles Server v1.0.0 或更高版本（webhook 需要此版本）
  • Hermes 与 BlueBubbles Server 之间网络可达

设置​

1. 安装 BlueBubbles Server​

从 bluebubbles.app 下载并安装。完成安装向导，登录你的 Apple ID，并配置连接方式（局域网、Ngrok、Cloudflare 或 Dynamic DNS）。

2. 获取 Server URL 和密码​

在 BlueBubbles Server → Settings → API 中记录：

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

3. 配置 Hermes​

运行设置向导：

hermes gateway setup

选择 BlueBubbles (iMessage)，并输入你的 Server 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=user@icloud.com,+15551234567

开放访问（写入 ~/.hermes/.env）：

BLUEBUBBLES_ALLOW_ALL_USERS=true

5. 启动网关​

hermes gateway run

Hermes 会连接到你的 BlueBubbles Server、注册 webhook，并开始监听 iMessage 消息。

工作原理​

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

环境变量​

VariableRequiredDefaultDescription
BLUEBUBBLES_SERVER_URLYes—BlueBubbles 服务器 URL
BLUEBUBBLES_PASSWORDYes—服务器密码
BLUEBUBBLES_WEBHOOK_HOSTNo127.0.0.1webhook 监听绑定地址
BLUEBUBBLES_WEBHOOK_PORTNo8645webhook 监听端口
BLUEBUBBLES_WEBHOOK_PATHNo/bluebubbles-webhookwebhook URL 路径
BLUEBUBBLES_HOME_CHANNELNo—用于 cron 投递的手机号/邮箱
BLUEBUBBLES_ALLOWED_USERSNo—逗号分隔的授权用户列表
BLUEBUBBLES_ALLOW_ALL_USERSNofalse是否允许所有用户
BLUEBUBBLES_SEND_READ_RECEIPTSNotrue自动将消息标记为已读

功能​

文本消息​

可收发 iMessage。Markdown 会自动去除，确保以干净的纯文本形式发送。

富媒体​

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

Tapback 表情反馈​

支持 love、like、dislike、laugh、emphasize、question 等反应。需要 BlueBubbles 的 Private API helper。

正在输入提示​

agent 处理消息时，会在 iMessage 对话里显示 “typing...”。需要 Private API。

已读回执​

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

聊天寻址​

你可以用邮箱地址或手机号来指定聊天对象，Hermes 会自动解析为 BlueBubbles chat GUID，无需手动使用原始 GUID。

Private API​

以下功能需要 BlueBubbles 的 Private API helper：

  • Tapback 表情反馈
  • 正在输入提示
  • 已读回执
  • 通过地址创建新聊天

即使没有 Private API，基础文本消息和媒体功能仍可正常使用。

故障排除​

“Cannot reach server”​

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

消息没有到达​

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

“Private API helper not connected”​

  • 安装 Private API helper：docs.bluebubbles.app
  • 不安装也能正常使用基础消息功能，只有表情反馈、输入状态和已读回执依赖它