跳到主要內容

BlueBubbles (iMessage)

通過 BlueBubbles 將 Hermes 與 Apple iMessage 連接 —— 一個免費、開源的 macOS 服務器，可將 iMessage 橋接到任何設備。

先決條件​

  • 一臺 Mac（始終開機）並運行 BlueBubbles Server
  • 在該 Mac 上的 Messages.app 中已登錄 Apple ID
  • BlueBubbles Server v1.0.0+（Webhook 功能需要此版本）
  • Hermes 與 BlueBubbles 服務器之間的網絡連通性

設置步驟​

1. 安裝 BlueBubbles Server​

從 bluebubbles.app 下載並安裝。完成設置嚮導 —— 使用您的 Apple ID 登錄，並配置連接方式（本地網絡、Ngrok、Cloudflare 或動態 DNS）。

2. 獲取服務器 URL 和密碼​

在 BlueBubbles Server → 設置 → API 中記錄以下信息：

  • 服務器 URL（例如 http://192.168.1.10:1234）
  • 服務器密碼

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. 授權用戶​

選擇以下任一方式：

私聊配對（推薦）：
當有人向您的 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 服務器，註冊一個 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否—用於定時任務投遞的電話號碼/郵箱
BLUEBUBBLES_ALLOWED_USERS否—逗號分隔的授權用戶列表
BLUEBUBBLES_ALLOW_ALL_USERS否false允許所有用戶
BLUEBUBBLES_SEND_READ_RECEIPTS否true自動將消息標記為已讀

功能特性​

文本消息​

發送和接收 iMessage。Markdown 會自動被剝離，以確保純文本清晰傳遞。

富媒體支持​

  • 圖像：照片在 iMessage 會話中原生顯示
  • 語音消息：音頻文件作為 iMessage 語音消息發送
  • 視頻：視頻附件
  • 文檔：文件作為 iMessage 附件發送

按贊反應（Tapback）​

支持愛、贊、不喜歡、笑、強調和疑問等反應。需要安裝 BlueBubbles 私有 API 輔助工具。

輸入狀態指示​

當 Agent 正在處理消息時，iMessage 會顯示“正在輸入...”。需要私有 API 支持。

已讀回執​

消息處理完成後自動標記為已讀。需要私有 API 支持。

聊天地址引用​

您可以使用郵箱或電話號碼來引用聊天 —— Hermes 會自動將它們解析為 BlueBubbles 的聊天 GUID，無需使用原始 GUID 格式。

私有 API​

部分功能需要安裝 BlueBubbles 私有 API 輔助工具：

  • 按贊反應
  • 輸入狀態指示
  • 已讀回執
  • 通過地址創建新聊天

未安裝私有 API 時，基礎文本消息和媒體功能仍可正常使用。

故障排除​

“無法連接到服務器”​

  • 確認服務器 URL 正確且 Mac 已開機
  • 檢查 BlueBubbles Server 是否正在運行
  • 確保網絡連通性（防火牆、端口轉發）

消息未到達​

  • 檢查 BlueBubbles Server → 設置 → API → Webhooks 中是否已註冊 Webhook
  • 確認 Webhook URL 從 Mac 可訪問
  • 檢查 hermes logs gateway 是否存在 Webhook 錯誤（或使用 hermes logs -f 實時跟蹤）

“私有 API 輔助工具未連接”​

  • 安裝私有 API 輔助工具：docs.bluebubbles.app
  • 基礎消息功能無需該工具即可使用 —— 僅反應、輸入狀態和已讀回執需要它