<!-- Source: https://hermesbible.com/docs/user-guide/messaging/bluebubbles -->

Section: Messaging Platforms · URL: https://hermesbible.com/docs/user-guide/messaging/bluebubbles

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 或 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

選用：群組聊天中要求提及（mention）

預設情況下，Hermes 會回覆所有授權的 BlueBubbles/iMessage 私訊和群組訊息。若要讓群組聊天改為需要 @提及才回覆，請啟用 mention 閘控：

platforms:
  bluebubbles:
    enabled: true
    extra:
      require_mention: true

設定 require_mention: true 後，私訊仍正常運作，但群組訊息只有在符合 mention 模式時才會被處理。若未自訂模式，Hermes 會使用保守的預設值，如 Hermes 和 @Hermes agent 等變體。

若要自訂代理名稱，可設定正規表達式：

platforms:
  bluebubbles:
    extra:
      require_mention: true
      mention_patterns:
        - '(?<![\w@])@?amos\b[,:\-]?'

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. 啟動 Gateway

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 傳送訊息。
• 媒體： 雙向支援圖片、語音訊息、影片和文件。接收的附件會下載並暫存於本地，供代理處理。

環境變數

自動將訊息標為已讀的功能，由 ~/.hermes/config.yaml 中 platforms.bluebubbles.extra 下的 send_read_receipts 鍵控制（預設：true）。沒有對應的環境變數。

功能

文字訊息

傳送和接收 iMessage。Markdown 會自動移除，以純文字方式傳送。

多媒體

• 圖片： 照片以 iMessage 原生方式顯示在對話中
• 語音訊息： 音訊檔案以 iMessage 語音訊息方式傳送
• 影片： 影片附件
• 文件： 檔案以 iMessage 附件方式傳送

Tapback 回應

支援愛心、讚、倒讚、笑、強調和疑問回應。需要 BlueBubbles Private API 輔助工具。

輸入指示器

代理處理訊息時，iMessage 對話中會顯示「正在輸入...」。需要 Private API。

已讀回條

處理訊息後自動標為已讀。需要 Private API。

聊天尋址

你可以用電子郵件或電話號碼來指定聊天對象 — Hermes 會自動將它們解析為 BlueBubbles 的聊天 GUID。無需使用原始 GUID 格式。

Private API

部分功能需要 BlueBubbles Private API 輔助工具：

• Tapback 回應
• 輸入指示器
• 已讀回條
• 透過位址建立新聊天

若未安裝 Private API，基本的文字訊息和多媒體功能仍可正常使用。

疑難排解

"Cannot reach server"

• 確認 Server URL 正確且 Mac 已開機
• 檢查 BlueBubbles Server 是否正在運作
• 確認網路連線正常（防火牆、連接埠轉發）

訊息未送達

• 檢查 BlueBubbles Server → Settings → API → Webhooks 中是否已註冊 webhook
• 確認 Mac 可以連線到 webhook URL
• 使用 hermes logs gateway 查看 webhook 錯誤（或 hermes logs -f 即時追蹤）

"Private API helper not connected"

• 安裝 Private API 輔助工具：docs.bluebubbles.app
• 基本訊息功能無需此工具 — 僅回應、輸入指示器和已讀回條需要它

---

---

DingTalk