BlueBubbles（macOS REST）

狀態：內建外掛，透過 HTTP 與 BlueBubbles macOS 伺服器通訊。建議作為 iMessage 整合方案，相較於舊版 imsg 頻道，BlueBubbles 的 API 更豐富、設定也更簡單。

概覽

• 透過 BlueBubbles 輔助程式在 macOS 上執行（bluebubbles.app）。
• 建議/已測試版本：macOS Sequoia (15)。macOS Tahoe (26) 可用；但目前編輯功能在 Tahoe 上無法正常運作，群組圖示更新可能回報成功但不會同步。
• OpenClaw 透過 REST API 與其通訊（GET /api/v1/ping、POST /message/text、POST /chat/:id/*）。
• 訊息透過 webhook 接收；回覆、輸入中指示器、已讀回條及 tapback 則透過 REST 呼叫處理。
• 附件和貼圖會作為收到的媒體擷取（並在可能時呈現給代理）。
• 配對/允許名單的運作方式與其他頻道相同（/channels/pairing 等），搭配 channels.bluebubbles.allowFrom + 配對碼。
• 回應通知會作為系統事件呈現（如同 Slack/Telegram），讓代理可以在回覆前「提及」它們。
• 進階功能：編輯、收回、回覆串、訊息特效、群組管理。

快速開始

1. 在 Mac 上安裝 BlueBubbles 伺服器（依照 bluebubbles.app/install 的指示操作）。

2. 在 BlueBubbles 設定中啟用 Web API 並設定密碼。

3. 執行 openclaw onboard 並選擇 BlueBubbles，或手動設定：

   {
     channels: {
       bluebubbles: {
         enabled: true,
         serverUrl: "http://192.168.1.100:1234",
         password: "example-password",
         webhookPath: "/bluebubbles-webhook",
       },
     },
   }

4. 將 BlueBubbles webhook 指向你的閘道（例如：https://your-gateway-host:3000/bluebubbles-webhook?password=<password>）。

5. 啟動閘道；它會註冊 webhook 處理程式並開始配對。

安全注意事項：

• 務必設定 webhook 密碼。
• Webhook 驗證是必要的。OpenClaw 會拒絕未包含與 channels.bluebubbles.password 相符的 password/guid 的 BlueBubbles webhook 請求（例如 ?password=<password> 或 x-password），不論 loopback/proxy 拓撲為何。
• 密碼驗證會在讀取/解析完整 webhook 內容之前進行。

保持 Messages.app 活躍（VM/無頭環境設定）

某些 macOS VM/常駐設定可能導致 Messages.app 進入「閒置」狀態（收到的事件會停止，直到重新開啟/前景化該程式）。簡單的解決方法是使用 AppleScript + LaunchAgent 每 5 分鐘觸發一次 Messages。

1) 儲存 AppleScript

另存為：

• ~/Scripts/poke-messages.scpt

範例腳本（非互動式；不會搶佔焦點）：

try
  tell application "Messages"
    if not running then
      launch
    end if

    -- Touch the scripting interface to keep the process responsive.
    set _chatCount to (count of chats)
  end tell
on error
  -- Ignore transient failures (first-run prompts, locked session, etc).
end try

2) 安裝 LaunchAgent

另存為：

• ~/Library/LaunchAgents/com.user.poke-messages.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.user.poke-messages</string>

    <key>ProgramArguments</key>
    <array>
      <string>/bin/bash</string>
      <string>-lc</string>
      <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>StartInterval</key>
    <integer>300</integer>

    <key>StandardOutPath</key>
    <string>/tmp/poke-messages.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/poke-messages.err</string>
  </dict>
</plist>

注意事項：

• 這會每 300 秒及登入時執行。
• 首次執行可能會觸發 macOS 自動化權限提示（osascript → Messages）。請在執行 LaunchAgent 的同一使用者工作階段中核准。

載入：

launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist

引導設定

BlueBubbles 可在互動式設定精靈中使用：

openclaw onboard

精靈會提示：

• 伺服器 URL（必填）：BlueBubbles 伺服器位址（例如 http://192.168.1.100:1234）
• 密碼（必填）：BlueBubbles Server 設定中的 API 密碼
• Webhook 路徑（選填）：預設為 /bluebubbles-webhook
• DM 政策：pairing、allowlist、open 或 disabled
• 允許名單：電話號碼、電子郵件或聊天對象

你也可以透過 CLI 新增 BlueBubbles：

openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>

存取控制（DM + 群組）

DM：

• 預設：channels.bluebubbles.dmPolicy = "pairing"。
• 未知發送者會收到配對碼；訊息會被忽略直到核准（配對碼在 1 小時後過期）。
• 核准方式：
  • openclaw pairing list bluebubbles
  • openclaw pairing approve bluebubbles <CODE>
• 配對是預設的 token 交換機制。詳細資訊：配對

群組：

• channels.bluebubbles.groupPolicy = open | allowlist | disabled（預設：allowlist）。
• channels.bluebubbles.groupAllowFrom 控制在 allowlist 模式下誰可以在群組中觸發。

提及過濾（群組）

BlueBubbles 支援群組聊天的提及過濾，行為與 iMessage/WhatsApp 一致：

• 使用 agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns）偵測提及。
• 當群組啟用 requireMention 時，代理只會在被提及時回應。
• 已授權發送者的控制指令可跳過提及過濾。

每群組設定：

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // default for all groups
        "iMessage;-;chat123": { requireMention: false }, // override for specific group
      },
    },
  },
}

指令授權

• 控制指令（例如 /config、/model）需要授權。
• 使用 allowFrom 和 groupAllowFrom 判斷指令授權。
• 已授權發送者可以在群組中不需提及就執行控制指令。

輸入中狀態 + 已讀回條

• 輸入中指示器：在回應產生之前和期間自動傳送。
• 已讀回條：由 channels.bluebubbles.sendReadReceipts 控制（預設：true）。
• 輸入中指示器：OpenClaw 會傳送輸入開始事件；BlueBubbles 在傳送或逾時後自動清除輸入中狀態（透過 DELETE 手動停止不太可靠）。

{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // disable read receipts
    },
  },
}

進階操作

BlueBubbles 在設定中啟用後支援進階訊息操作：

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // tapbacks (default: true)
        edit: true, // edit sent messages (macOS 13+, broken on macOS 26 Tahoe)
        unsend: true, // unsend messages (macOS 13+)
        reply: true, // reply threading by message GUID
        sendWithEffect: true, // message effects (slam, loud, etc.)
        renameGroup: true, // rename group chats
        setGroupIcon: true, // set group chat icon/photo (flaky on macOS 26 Tahoe)
        addParticipant: true, // add participants to groups
        removeParticipant: true, // remove participants from groups
        leaveGroup: true, // leave group chats
        sendAttachment: true, // send attachments/media
      },
    },
  },
}

可用操作：

• react：新增/移除 tapback 回應（messageId、emoji、remove）
• edit：編輯已傳送的訊息（messageId、text）
• unsend：收回訊息（messageId）
• reply：回覆特定訊息（messageId、text、to）
• sendWithEffect：以 iMessage 特效傳送（text、to、effectId）
• renameGroup：重新命名群組聊天（chatGuid、displayName）
• setGroupIcon：設定群組聊天的圖示/照片（chatGuid、media）— 在 macOS 26 Tahoe 上不穩定（API 可能回報成功但圖示不會同步）。
• addParticipant：將某人加入群組（chatGuid、address）
• removeParticipant：將某人從群組移除（chatGuid、address）
• leaveGroup：離開群組聊天（chatGuid）
• sendAttachment：傳送媒體/檔案（to、buffer、filename、asVoice）
  • 語音備忘錄：設定 asVoice: true 搭配 MP3 或 CAF 音訊即可作為 iMessage 語音訊息傳送。BlueBubbles 在傳送語音備忘錄時會將 MP3 轉換為 CAF。

訊息 ID（短 vs 完整）

OpenClaw 可能呈現_短_訊息 ID（例如 1、2）以節省 token 用量。

• MessageSid / ReplyToId 可能是短 ID。
• MessageSidFull / ReplyToIdFull 包含提供者的完整 ID。
• 短 ID 儲存在記憶體中；重新啟動或快取淘汰後可能過期。
• 操作接受短或完整的 messageId，但如果短 ID 已不可用會回報錯誤。

對於持久性自動化和儲存，請使用完整 ID：

• 範本：{{MessageSidFull}}、{{ReplyToIdFull}}
• 內容：收到的 payload 中的 MessageSidFull / ReplyToIdFull

參閱 設定 了解範本變數。

區塊串流

控制回應是作為單一訊息傳送還是以區塊串流：

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // enable block streaming (off by default)
    },
  },
}

媒體 + 限制

• 收到的附件會下載並儲存在媒體快取中。
• 媒體上限透過 channels.bluebubbles.mediaMaxMb 設定收到和傳出的媒體（預設：8 MB）。
• 傳出文字會根據 channels.bluebubbles.textChunkLimit 進行分段（預設：4000 字元）。

設定參考

完整設定：設定

提供者選項：

• channels.bluebubbles.enabled：啟用/停用頻道。
• channels.bluebubbles.serverUrl：BlueBubbles REST API 基底 URL。
• channels.bluebubbles.password：API 密碼。
• channels.bluebubbles.webhookPath：Webhook 端點路徑（預設：/bluebubbles-webhook）。
• channels.bluebubbles.dmPolicy：pairing | allowlist | open | disabled（預設：pairing）。
• channels.bluebubbles.allowFrom：DM 允許名單（handle、電子郵件、E.164 號碼、chat_id:*、chat_guid:*）。
• channels.bluebubbles.groupPolicy：open | allowlist | disabled（預設：allowlist）。
• channels.bluebubbles.groupAllowFrom：群組發送者允許名單。
• channels.bluebubbles.groups：每群組設定（requireMention 等）。
• channels.bluebubbles.sendReadReceipts：傳送已讀回條（預設：true）。
• channels.bluebubbles.blockStreaming：啟用區塊串流（預設：false；串流回覆需要此項）。
• channels.bluebubbles.textChunkLimit：傳出分段大小（字元數）（預設：4000）。
• channels.bluebubbles.chunkMode：length（預設）僅在超過 textChunkLimit 時分割；newline 在長度分段前先依空行（段落邊界）分割。
• channels.bluebubbles.mediaMaxMb：收到/傳出媒體上限（MB）（預設：8）。
• channels.bluebubbles.mediaLocalRoots：明確允許的絕對本地目錄清單，用於傳出的本地媒體路徑。除非設定此項，否則預設拒絕本地路徑傳送。每帳戶覆寫：channels.bluebubbles.accounts.<accountId>.mediaLocalRoots。
• channels.bluebubbles.historyLimit：群組訊息上下文的最大數量（0 停用）。
• channels.bluebubbles.dmHistoryLimit：DM 歷史記錄限制。
• channels.bluebubbles.actions：啟用/停用特定操作。
• channels.bluebubbles.accounts：多帳戶設定。

相關全域選項：

• agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns）。
• messages.responsePrefix。

定址/送達目標

建議使用 chat_guid 以確保穩定的路由：

• chat_guid:iMessage;-;+15555550123（群組建議使用）
• chat_id:123
• chat_identifier:...
• 直接 handle：+15555550123、[email protected]
  • 如果直接 handle 沒有現有的 DM 聊天，OpenClaw 會透過 POST /api/v1/chat/new 建立。這需要啟用 BlueBubbles Private API。

安全性

• Webhook 請求透過比對 guid/password 查詢參數或標頭與 channels.bluebubbles.password 來驗證。也接受來自 localhost 的請求。
• API 密碼和 webhook 端點應保密（視同憑證）。
• Localhost 信任表示同主機反向代理可能無意間繞過密碼驗證。如果你使用代理閘道，請在代理要求驗證並設定 gateway.trustedProxies。參閱 閘道安全性。
• 如果將 BlueBubbles 伺服器暴露在區域網路之外，請啟用 HTTPS + 防火牆規則。

疑難排解

• 如果輸入中/已讀事件停止運作，請檢查 BlueBubbles webhook 記錄，並確認閘道路徑與 channels.bluebubbles.webhookPath 相符。
• 配對碼在一小時後過期；使用 openclaw pairing list bluebubbles 和 openclaw pairing approve bluebubbles <code>。
• 回應需要 BlueBubbles private API（POST /api/v1/message/react）；請確認伺服器版本有提供此 API。
• 編輯/收回需要 macOS 13+ 及相容的 BlueBubbles 伺服器版本。在 macOS 26（Tahoe）上，編輯目前因 private API 變更而無法使用。
• 群組圖示更新在 macOS 26（Tahoe）上可能不穩定：API 可能回報成功但新圖示不會同步。
• OpenClaw 會根據 BlueBubbles 伺服器的 macOS 版本自動隱藏已知有問題的操作。如果編輯功能在 macOS 26（Tahoe）上仍然出現，請手動停用：channels.bluebubbles.actions.edit=false。
• 查看狀態/健康資訊：openclaw status --all 或 openclaw status --deep。

關於一般頻道工作流程參考，請參閱 頻道 和 外掛 指南。