OpenClaw BlueBubbles 頻道
即時通訊
中等
透過 BlueBubbles REST API 將 OpenClaw 連接到 iMessage。此整合將您的 Mac 變為 iMessage 閘道——安裝 BlueBubbles 伺服器應用程式，啟用 Web API，您的 AI 助理即可收發 iMessage 訊息、tapback 表情回應和媒體附件。BlueBubbles 是推薦的 iMessage 頻道，取代了舊版 imsg CLI 方案。
快速資訊
難度中等
分類即時通訊
支援功能數4 / 6
BlueBubbles 支援功能
文字訊息
支援
媒體與檔案
支援
表情回應
支援
討論串
不支援
語音訊息
不支援
群組聊天
支援
BlueBubbles 前置條件
- 執行 macOS High Sierra (10.13) 或更高版本的 Mac（建議 Ventura 13+ 以獲得完整功能；Tahoe 26 有部分限制）
- 已安裝 BlueBubbles 伺服器應用程式（從 bluebubbles.app 下載）
- 在 BlueBubbles 設定中啟用 Web API 並設定密碼
- OpenClaw Gateway 已執行並設定
BlueBubbles 快速設定
1
在 Mac 上安裝 BlueBubbles 伺服器
從 bluebubbles.app/install 下載並安裝 BlueBubbles 伺服器應用程式。啟動應用程式，使用 Apple ID 登入，並完成初始設定。確保 iMessage 在該 Mac 上正常運作。
2
啟用 Web API
在 BlueBubbles 伺服器設定中，啟用 Web/REST API 並設定一組強密碼。記下伺服器 URL（例如 http://localhost:1234）——您將在 OpenClaw 設定中使用它。
3
新增 BlueBubbles 頻道設定
執行 'openclaw onboard' 並選擇 BlueBubbles，或手動將頻道設定新增至 ~/.openclaw/openclaw.json，填入 serverUrl 和 password。如需要可設定 webhookPath。
4
設定 Webhook 並測試
將 BlueBubbles Webhook 指向您的 Gateway：https://your-gateway-host:3000/bluebubbles-webhook?password=<password>。啟動 Gateway 並傳送一則測試 iMessage 以驗證連線。如使用 pairing 策略，透過 'openclaw pairing approve bluebubbles <code>' 核准傳送者。
BlueBubbles 設定範例
config.json
{
"channels": {
"bluebubbles": {
"enabled": true,
"serverUrl": "http://localhost:1234",
"password": "YOUR_BLUEBUBBLES_PASSWORD",
"webhookPath": "/bluebubbles-webhook",
"dmPolicy": "pairing"
}
}
}BlueBubbles 深入了解
架構概覽
OpenClaw 透過執行在 Mac 上的 BlueBubbles 伺服器應用程式連接 iMessage。BlueBubbles 提供 REST API，Gateway 透過該 API 傳送訊息、表情回應和管理聊天。傳入訊息透過 Webhook 投遞——BlueBubbles 將新訊息事件推送到 Gateway 的 Webhook 端點。
架構流程為：iMessage 到達 Mac → BlueBubbles 伺服器 → Webhook 推送到 Gateway → OpenClaw 使用 AI 處理 → REST API 回呼 BlueBubbles → iMessage 傳送。
此方案需要一台保持在線的 Mac（實體機或虛擬機），因為 iMessage 是 Apple 專有服務。Mac 充當 Apple 訊息生態和 OpenClaw 助理之間的橋樑。
專用的 Mac Mini 或 macOS 虛擬機是執行 BlueBubbles 作為持久 iMessage 閘道的理想選擇。
BlueBubbles 支援 Private API 以實現進階功能（如 tapback 表情回應、訊息編輯和收回）——請確保在 BlueBubbles 設定中啟用。
BlueBubbles 伺服器設定
設定 BlueBubbles 需要在 Mac 上安裝伺服器應用程式：
1. 從 bluebubbles.app/install 下載 BlueBubbles 並啟動應用程式。
2. 使用 Apple ID 登入，確保 iMessage 在該 Mac 上正常運作。
3. 在 BlueBubbles 設定中啟用 Web/REST API。
4. 設定一組強 API 密碼——此密碼用於驗證所有 API 請求和 Webhook 投遞。
5. 記下應用程式中顯示的伺服器 URL（預設：http://localhost:1234）。
6. 可選：啟用 Private API 以取得進階功能（表情回應、編輯、收回）。
伺服器必須保持執行，iMessage 橋接才能運作。建議設定 BlueBubbles 開機自啟以確保可靠性。
webhook URL
# Gateway 的 Webhook URL 格式
https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD請妥善保管 BlueBubbles API 密碼。如果在網路上公開伺服器，請在 BlueBubbles 上啟用 HTTPS 並使用防火牆規則限制存取。同主機反向代理會繞過密碼驗證——需新增代理層級驗證並設定 gateway.trustedProxies。
私訊策略
私訊（DM）策略控制誰可以透過 iMessage 與您的 AI 助理互動。OpenClaw 支援四種策略：
• pairing（預設）——未知傳送者會收到限時配對碼（1 小時後到期）。透過 'openclaw pairing approve bluebubbles <CODE>' 核准或拒絕。核准後即可自由聊天。
• allowlist——僅 allowFrom 清單中的電話號碼和電子郵件地址可以傳送訊息。其他人會被靜默忽略。電話號碼支援 E.164 格式。
• open——任何人傳送訊息都會收到回覆。請謹慎使用。
• disabled——完全關閉私訊處理。
openclaw.json
{
"channels": {
"bluebubbles": {
"dmPolicy": "allowlist",
"allowFrom": ["+15551234567", "user@example.com"]
}
}
}allowFrom 欄位同時接受電話號碼（E.164 格式，如 +15551234567）和電子郵件地址，用於 iMessage 路由。
群組聊天管理
OpenClaw 透過 BlueBubbles 支援 iMessage 群組聊天，提供靈活的存取控制：
• groupPolicy 控制誰可以在群組聊天中觸發機器人：
- open——任何群組成員都可以互動
- allowlist——僅 groupAllowFrom 清單中的地址可以觸發
- disabled（預設）——忽略群組訊息
• 提及觸發——當 requireMention 為 true（群組預設）時，機器人僅在被提及時回覆。提及模式在 agents.list[].groupChat.mentionPatterns 中設定。
• 按群組設定——使用 groups 物件為特定群組聊天設定不同的 requireMention 規則。
openclaw.json
{
"channels": {
"bluebubbles": {
"groupPolicy": "allowlist",
"groupAllowFrom": ["+15551234567"],
"groups": {
"iMessage;+;chat123456": {
"requireMention": false
}
}
}
}
}iMessage 操作與特效
BlueBubbles 透過 Private API 提供豐富的 iMessage 原生操作。每個操作可單獨切換：
• reactions——傳送和接收 tapback 表情回應（喜愛、按讚、倒讚、大笑、強調、疑問）
• edit——修改已傳送訊息（需 macOS 13+；macOS Tahoe 上目前無法使用）
• unsend——收回已傳送訊息（macOS 13+）
• reply——透過 GUID 引用訊息實現對話串
• sendWithEffect——傳送帶氣泡特效的訊息（猛擊、響亮、溫柔、隱形墨水等）
• sendAttachment——傳送媒體檔案和語音備忘錄（語音使用 MP3/CAF 格式；BlueBubbles 自動處理 MP3→CAF 轉換）
群組管理操作：
• renameGroup——重新命名群組聊天
• setGroupIcon——設定群組聊天圖片（macOS Tahoe 上不穩定）
• addParticipant / removeParticipant / leaveGroup——管理群組成員
openclaw.json
{
"channels": {
"bluebubbles": {
"actions": {
"reactions": true,
"edit": true,
"unsend": true,
"reply": true,
"sendWithEffect": true,
"sendAttachment": true
}
}
}
}在 macOS Tahoe (26) 上，由於 Private API 變更，edit 操作目前無法使用，setGroupIcon 不可靠（API 回傳成功但圖示不同步）。如果您執行的是 Tahoe，請手動停用這些操作。
訊息傳送與分塊
OpenClaw 為長 AI 回覆提供可設定的分塊傳送：
• textChunkLimit——每則訊息塊的最大字元數（預設：4000）。iMessage 沒有嚴格限制，但過長的訊息在某些裝置上可能顯示不佳。
• chunkMode——控制文字分割方式：
- length（預設）——按 textChunkLimit 字元數硬分割
- newline——在段落邊界分割，閱讀更自然
• blockStreaming——為 true 時，回覆在產生過程中以塊方式傳送，而非等待完整回覆。
已讀回執預設傳送以保持自然的對話感。AI 回覆產生前和產生過程中會自動傳送輸入指示器。
openclaw.json
{
"channels": {
"bluebubbles": {
"textChunkLimit": 4000,
"chunkMode": "newline",
"blockStreaming": false,
"sendReadReceipts": true
}
}
}媒體與附件
BlueBubbles 支援透過 iMessage 收發媒體：
• 傳入附件由 Gateway 自動下載和快取。最大傳入檔案大小由 mediaMaxMb 控制（預設：8 MB）。
• 可透過 sendAttachment 操作傳送語音備忘錄，設定 asVoice: true。BlueBubbles 會自動將 MP3 轉換為 CAF 格式以實現原生 iMessage 語音備忘錄播放。
• 透過 sendAttachment 操作傳送外發媒體，需提供 buffer、filename 和可選的 mime 類型參數。
語音備忘錄請使用 MP3 或 CAF 格式。BlueBubbles 會自動將 MP3 轉換為 CAF 以實現原生 iMessage 播放。
如需處理更大的附件，可調整 mediaMaxMb——預設 8 MB 可涵蓋大多數照片和短影片。
訊息 ID 處理
BlueBubbles 使用兩種訊息識別碼：
• 短 ID——記憶體中的暫時令牌（如 1, 2, 3），速度快但暫時性。Gateway 重啟或快取清除後會到期。
• 完整 ID——持久化的提供者識別碼（MessageSidFull, ReplyToIdFull），可在重啟後保留，適合長期參照。
操作參數（messageId, replyTo 等）接受兩種格式。對於需要跨重啟參照訊息的持久化自動化和整合，請始終使用完整 ID。
對於需要在 Gateway 重啟後仍然有效的自動化，請使用完整訊息 ID。短 ID 適合互動使用，但重啟後會失效。
位址與路由
BlueBubbles 支援多種位址格式進行訊息投遞。按穩定性排序的首選路由順序：
1. chat_guid——最穩定格式：chat_guid:iMessage;-;+15555550123
2. chat_id——數字聊天識別碼：chat_id:123
3. chat_identifier——聊天識別碼字串
4. 直接位址——電話號碼（+15555550123）或電子郵件（user@example.com）
當向沒有現有聊天的直接位址傳送訊息時，BlueBubbles 會透過 POST /api/v1/chat/new 自動建立新的私訊（需要 Private API）。
在自動化中使用 chat_guid 格式以取得最可靠的訊息路由。
安全與 Webhook 驗證
BlueBubbles 使用設定的密碼對 Webhook 投遞進行驗證。Gateway 驗證密碼參數（透過查詢字串或請求標頭）是否與 channels.bluebubbles.password 設定匹配。
安全注意事項：
• 本機請求（localhost）自動信任，略過密碼驗證。
• 同主機反向代理也會繞過密碼檢查——如果使用同一機器上的反向代理，請新增代理層級驗證並設定 gateway.trustedProxies。
• 在 BlueBubbles 伺服器啟用 HTTPS 以加密通訊。
• 使用防火牆規則限制外部對 BlueBubbles API 連接埠的存取。
正式部署時，務必使用 HTTPS 並確保 Webhook 端點在無驗證的情況下不可公開存取。
同主機反向代理會繞過 BlueBubbles 密碼驗證。使用反向代理時，請務必設定代理層級驗證並設定 gateway.trustedProxies。
Messages.app 保活（無頭模式/虛擬機）
如果在無頭 Mac 或虛擬機上執行 BlueBubbles，Messages.app 可能會進入閒置狀態並停止處理訊息。解決方案是設定一個 LaunchAgent，每 5 分鐘執行一次 AppleScript 來觸發 Messages 腳本介面。
此保活腳本會安全地忽略暫時性故障，不會搶佔其他應用程式的焦點。它對於 iMessage 橋接的可靠無人值守運作至關重要。
設定一個 macOS LaunchAgent plist，定期執行 AppleScript 以保持 Messages.app 的回應性。
這僅在無頭/虛擬機環境下需要。如果您的 Mac 有活躍的桌面工作階段且 Messages.app 可見，則無需保活。
使用 launchctl 管理 LaunchAgent——設定開機載入以實現完全無人值守運作。
BlueBubbles 設定參考
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | false | 啟用或停用 BlueBubbles 頻道 |
| serverUrl | string | "" | BlueBubbles REST API 基礎 URL（例如 http://localhost:1234） |
| password | string | "" | 用於驗證的 BlueBubbles API 密碼 |
| webhookPath | string | "/bluebubbles-webhook" | 接收傳入訊息的 Webhook 端點路徑 |
| dmPolicy | string | "pairing" | 控制誰可以私訊機器人。選項：pairing, allowlist, open, disabled |
| allowFrom | string[] | [] | 允許傳送訊息的電話號碼和電子郵件（電話使用 E.164 格式） |
| groupPolicy | string | "allowlist" | 群組聊天策略。選項：open, allowlist, disabled |
| groupAllowFrom | string[] | [] | 群組聊天中授權觸發機器人的傳送者位址 |
| sendReadReceipts | boolean | true | 處理訊息時傳送已讀回執確認 |
| blockStreaming | boolean | false | 啟用塊式回應串流，而非等待完整回覆 |
| textChunkLimit | number | 4000 | 每則外發文字訊息塊的最大字元數 |
| chunkMode | string | "length" | 文字分割模式。選項：length（按大小）, newline（按段落） |
| mediaMaxMb | number | 8 | 傳入附件的最大檔案大小（MB） |
| historyLimit | number | - | 作為 AI 上下文的最大群組訊息數（0 為停用） |
| dmHistoryLimit | number | - | AI 上下文的私訊歷史記錄限制 |
| actions.reactions | boolean | true | 啟用 tapback 表情回應（需要 Private API） |
| actions.edit | boolean | true | 啟用訊息編輯（需要 macOS 13+；Tahoe 上無法使用） |
| actions.unsend | boolean | true | 啟用訊息收回（需要 macOS 13+） |
| actions.reply | boolean | true | 啟用透過 GUID 的訊息串 |
| actions.sendWithEffect | boolean | true | 啟用 iMessage 氣泡特效（猛擊、響亮、溫柔等） |
| actions.sendAttachment | boolean | true | 啟用媒體和語音備忘錄傳送 |
enabled
Type: booleanDefault: false
啟用或停用 BlueBubbles 頻道
serverUrl
Type: stringDefault: ""
BlueBubbles REST API 基礎 URL（例如 http://localhost:1234）
password
Type: stringDefault: ""
用於驗證的 BlueBubbles API 密碼
webhookPath
Type: stringDefault: "/bluebubbles-webhook"
接收傳入訊息的 Webhook 端點路徑
dmPolicy
Type: stringDefault: "pairing"
控制誰可以私訊機器人。選項：pairing, allowlist, open, disabled
allowFrom
Type: string[]Default: []
允許傳送訊息的電話號碼和電子郵件（電話使用 E.164 格式）
groupPolicy
Type: stringDefault: "allowlist"
群組聊天策略。選項：open, allowlist, disabled
groupAllowFrom
Type: string[]Default: []
群組聊天中授權觸發機器人的傳送者位址
sendReadReceipts
Type: booleanDefault: true
處理訊息時傳送已讀回執確認
blockStreaming
Type: booleanDefault: false
啟用塊式回應串流，而非等待完整回覆
textChunkLimit
Type: numberDefault: 4000
每則外發文字訊息塊的最大字元數
chunkMode
Type: stringDefault: "length"
文字分割模式。選項：length（按大小）, newline（按段落）
mediaMaxMb
Type: numberDefault: 8
傳入附件的最大檔案大小（MB）
historyLimit
Type: numberDefault: -
作為 AI 上下文的最大群組訊息數（0 為停用）
dmHistoryLimit
Type: numberDefault: -
AI 上下文的私訊歷史記錄限制
actions.reactions
Type: booleanDefault: true
啟用 tapback 表情回應（需要 Private API）
actions.edit
Type: booleanDefault: true
啟用訊息編輯（需要 macOS 13+；Tahoe 上無法使用）
actions.unsend
Type: booleanDefault: true
啟用訊息收回（需要 macOS 13+）
actions.reply
Type: booleanDefault: true
啟用透過 GUID 的訊息串
actions.sendWithEffect
Type: booleanDefault: true
啟用 iMessage 氣泡特效（猛擊、響亮、溫柔等）
actions.sendAttachment
Type: booleanDefault: true
啟用媒體和語音備忘錄傳送
BlueBubbles 常見問題
BlueBubbles 故障排除
Webhook 未收到訊息
BlueBubbles 中的 Webhook URL 與 Gateway 端點不匹配，或密碼參數不正確。
確認 Webhook URL 設定為 https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD。檢查 channels.bluebubbles.webhookPath 是否與 URL 中的路徑匹配。檢視 Gateway 記錄中的傳入 Webhook 請求。
Gateway 已連線但操作失敗（表情回應、編輯、收回）
BlueBubbles Private API 未啟用，或伺服器版本不支援所需的 API 端點。
在 BlueBubbles 伺服器設定中啟用 Private API。將 BlueBubbles 更新到最新版本。如果特定操作在 macOS Tahoe 上失敗，請單獨停用：channels.bluebubbles.actions.edit=false。
無頭 Mac 上 Messages.app 停止回應
Messages.app 在無頭/虛擬機環境下進入閒置狀態，停止處理腳本介面。
設定 AppleScript 保活 LaunchAgent，每 5 分鐘觸發一次 Messages 腳本介面。確保 LaunchAgent 透過 launchctl 載入並在開機時執行。
機器人傳送的訊息不是 iMessage（綠色氣泡）
接收方的電話號碼或電子郵件未註冊 iMessage，或 Mac 上的 Apple ID 未啟用 iMessage。
在 Mac 的 Messages.app 偏好設定中確認 iMessage 已啟用。檢查接收方是否使用啟用了 iMessage 的 Apple 裝置。綠色氣泡表示 SMS 回退，BlueBubbles 可能不支援（取決於設定）。
macOS Tahoe 上編輯操作失敗
已知問題——macOS Tahoe (26) 破壞了訊息編輯的 Private API 端點。
停用編輯操作：將 channels.bluebubbles.actions.edit 設為 false。這是 Tahoe 上的已知 BlueBubbles 限制。關注 BlueBubbles 更新以取得修復。