BlueBubbles

Status：內建的舊版 Plugin，透過 HTTP 與 BlueBubbles macOS 伺服器通訊。現有 BlueBubbles 設定會繼續運作，但新的 OpenClaw iMessage 部署在需求符合主機條件時，應優先使用原生 iMessage Plugin。

# 概觀

• 透過 BlueBubbles 輔助應用程式在 macOS 上執行（bluebubbles.app）。
• 適用於已依賴 BlueBubbles 頻道 ID、webhook 狀態、群組目標、cron 傳遞或工作區路由的安裝，作為舊版備援。
• 建議/已測試：macOS Sequoia (15)。macOS Tahoe (26) 可運作；目前 Tahoe 上的編輯功能已損壞，群組圖示更新可能回報成功但未同步。
• OpenClaw 透過其 REST API 與它通訊（GET /api/v1/ping、POST /message/text、POST /chat/:id/*）。
• 傳入訊息會透過 webhooks 抵達；傳出回覆、輸入中指示、已讀回條與 tapbacks 都是 REST 呼叫。
• 附件與貼圖會作為傳入媒體擷取（並在可行時呈現給代理）。
• 會合成 MP3 或 CAF 音訊的自動 TTS 回覆，會以 iMessage 語音備忘錄泡泡傳遞，而不是一般檔案附件。
• 配對/允許清單的運作方式與其他頻道相同（/channels/pairing 等），搭配 channels.bluebubbles.allowFrom + 配對碼。
• 反應會像 Slack/Telegram 一樣以系統事件呈現，讓代理可在回覆前「提及」它們。
• 進階功能：編輯、收回、回覆串接、訊息效果、群組管理。

# 快速開始

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

# 讓 Messages.app 保持運作（VM / 無頭設定）

某些 macOS VM / 常時開機設定可能會讓 Messages.app 進入「閒置」狀態（傳入事件會停止，直到應用程式被開啟/帶到前景）。一個簡單的解法是使用 AppleScript + LaunchAgent 每 5 分鐘 poke Messages 一次。

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

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

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

精靈會提示輸入：

你也可以透過 CLI 新增 BlueBubbles：

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

# 存取控制（DM + 群組）

# 聯絡人名稱補充（macOS，選用）

BlueBubbles 群組 webhooks 通常只包含原始參與者位址。如果你希望 GroupMembers context 改為顯示本機聯絡人名稱，可以在 macOS 上選擇啟用本機聯絡人補充：

• channels.bluebubbles.enrichGroupParticipantsFromContacts = true 會啟用查詢。預設：false。
• 查詢只會在群組存取、命令授權與提及門控允許訊息通過後執行。
• 只會補充未命名的電話參與者。
• 找不到本機相符項目時，原始電話號碼仍會作為備援。

{
  channels: {
    bluebubbles: {
      enrichGroupParticipantsFromContacts: true,
    },
  },
}

# 提及門控（群組）

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.groups.* 底下的每個項目都接受選用的 systemPrompt 字串。該值會在處理該群組訊息的每一輪注入代理的系統提示，因此你可以設定每群組 persona 或行為規則，而不用編輯代理提示：

{
  channels: {
    bluebubbles: {
      groups: {
        "iMessage;-;chat123": {
          systemPrompt: "Keep responses under 3 sentences. Mirror the group's casual tone.",
        },
      },
    },
  },
}

鍵會對應 BlueBubbles 回報給該群組的 chatGuid / chatIdentifier / 數字 chatId，而 "*" 萬用字元項目會為每個沒有精確相符項目的群組提供預設值（與 requireMention 以及每群組工具政策使用相同模式）。精確相符一律優先於萬用字元。DM 會忽略此欄位；請改用代理層級或帳號層級的提示自訂。

# 實例：串接回覆與 tapback 反應（私有 API）

啟用 BlueBubbles 私有 API 後，傳入訊息會帶有短訊息 ID（例如 [[reply_to:5]]），且代理可以呼叫 action=reply 來串接到特定訊息，或呼叫 action=react 放置 tapback。每群組 systemPrompt 是讓代理選擇正確工具的可靠方式：

{
  channels: {
    bluebubbles: {
      groups: {
        "iMessage;+;chat-family": {
          systemPrompt: "When replying in this group, always call action=reply with the [[reply_to:N]] messageId from context so your response threads under the triggering message. Never send a new unlinked message. For short acknowledgements ('ok', 'got it', 'on it'), use action=react with an appropriate tapback emoji (❤️, 👍, 😂, ‼️, ❓) instead of sending a text reply.",
        },
      },
    },
  },
}

Tapback 反應與串接回覆都需要 BlueBubbles 私有 API；底層機制請參閱進階動作與訊息 ID。

# ACP 對話繫結

BlueBubbles 聊天可以轉換成持久的 ACP 工作區，而不需要變更傳輸層。

快速操作員流程：

• 在 DM 或允許的群組聊天中執行 /acp spawn codex --bind here。
• 未來同一個 BlueBubbles 對話中的訊息會路由到產生的 ACP 工作階段。
• /new 與 /reset 會就地重設同一個已繫結的 ACP 工作階段。
• /acp close 會關閉 ACP 工作階段並移除繫結。

也支援透過頂層 bindings[] 項目設定持久繫結，其中包含 type: "acp" 與 match.channel: "bluebubbles"。

match.peer.id 可以使用任何支援的 BlueBubbles 目標形式：

• 正規化的 DM 識別碼，例如 +15555550123 或 [email protected]
• chat_id:<id>
• chat_guid:<guid>
• chat_identifier:<identifier>

若要穩定的群組繫結，優先使用 chat_id:* 或 chat_identifier:*。

範例：

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "bluebubbles",
        accountId: "default",
        peer: { kind: "dm", id: "+15555550123" },
      },
      acp: { label: "codex-imessage" },
    },
  ],
}

請參閱 ACP 代理程式了解共用 ACP 繫結行為。

# 輸入中 + 已讀回執

• 輸入中指示器：在回應產生前及期間自動傳送。
• 已讀回執：由 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
      },
    },
  },
}

# 訊息 ID（短版與完整）

為節省 token，OpenClaw 可能會顯示_短版_訊息 ID（例如 1、2）。

• MessageSid / ReplyToId 可以是短 ID。
• MessageSidFull / ReplyToIdFull 包含提供者完整 ID。
• 短 ID 存於記憶體中；重新啟動或快取淘汰時可能會過期。
• 動作接受短版或完整 messageId，但若短 ID 已無法取得會報錯。

若要用於持久的自動化和儲存，請使用完整 ID：

• 範本：{{MessageSidFull}}、{{ReplyToIdFull}}
• 脈絡：傳入酬載中的 MessageSidFull / ReplyToIdFull

請參閱設定了解範本變數。

# 合併分割傳送的 DM（同一段撰寫中的命令 + URL）

當使用者在 iMessage 中把命令和 URL 一起輸入時，例如 Dump https://example.com/article，Apple 會將傳送拆成兩個獨立的 Webhook 傳遞：

1. 一則文字訊息（"Dump"）。
2. 一個 URL 預覽泡泡（"https://..."），並以附件附上 OG 預覽圖片。

在多數環境中，兩個 Webhook 抵達 OpenClaw 的間隔約為 0.8-2.0 秒。若未合併，代理程式會在第 1 輪只收到命令並回覆（通常是「把 URL 傳給我」），到第 2 輪才看到 URL，此時命令脈絡已經遺失。

channels.bluebubbles.coalesceSameSenderDms 讓 DM 選擇將連續且同一傳送者的 Webhook 合併為單一代理程式輪次。群組聊天仍會以每則訊息作為鍵，因此保留多使用者輪次結構。

{
  channels: {
    bluebubbles: {
      coalesceSameSenderDms: true, // opt in (default: false)
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 2500 ms works for most setups; raise to 4000 ms if your Mac is slow
        // or under memory pressure (observed gap can stretch past 2 s then).
        bluebubbles: 2500,
      },
    },
  },
}

# 情境以及代理程式看到的內容

# 分割傳送合併疑難排解

如果旗標已開啟，但分割傳送仍以兩個輪次抵達，請逐層檢查：

grep coalesceSameSenderDms ~/.openclaw/openclaw.json

grep -E "Dispatching event to webhook" main.log | tail -20

# 區塊串流

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

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

# 媒體 + 限制

• 傳入附件會下載並儲存在媒體快取中。
• 透過 channels.bluebubbles.mediaMaxMb 設定傳入與傳出媒體的媒體上限（預設：8 MB）。
• 傳出文字會依 channels.bluebubbles.textChunkLimit 分塊（預設：4000 字元）。

# 設定參考

完整設定：設定

相關全域選項：

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

# 定址 / 傳送目標

偏好使用 chat_guid 以取得穩定路由：

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

# iMessage 與 SMS 路由

當同一個帳號代稱在 Mac 上同時有 iMessage 和 SMS 聊天時（例如某個電話號碼已註冊 iMessage，但也曾收到綠色泡泡後備訊息），OpenClaw 會偏好 iMessage 聊天，且絕不會無聲降級到 SMS。若要強制使用 SMS 聊天，請使用明確的 sms: 目標前綴（例如 sms:+15555550123）。沒有相符 iMessage 聊天的帳號代稱，仍會透過 BlueBubbles 回報的任何聊天傳送。

# 安全性

• Webhook 請求會透過比對 guid/password 查詢參數或標頭與 channels.bluebubbles.password 進行驗證。
• 請保密 API 密碼和 Webhook 端點（將它們視為憑證）。
• BlueBubbles Webhook 驗證沒有 localhost 旁路。如果你代理 Webhook 流量，請讓 BlueBubbles 密碼在請求端到端保留。gateway.trustedProxies 在此不會取代 channels.bluebubbles.password。請參閱 Gateway 安全性。
• 如果將 BlueBubbles 伺服器暴露到 LAN 之外，請啟用 HTTPS 與防火牆規則。

# 疑難排解

• 如果輸入/讀取事件停止運作，請檢查 BlueBubbles Webhook 記錄，並確認 Gateway 路徑符合 channels.bluebubbles.webhookPath。
• 配對碼會在一小時後到期；請使用 openclaw pairing list bluebubbles 和 openclaw pairing approve bluebubbles <code>。
• 反應需要 BlueBubbles Private API（POST /api/v1/message/react）；請確認伺服器版本有公開它。
• 編輯/收回需要 macOS 13+ 和相容的 BlueBubbles 伺服器版本。在 macOS 26（Tahoe）上，編輯目前因 Private API 變更而無法運作。
• 群組圖示更新在 macOS 26（Tahoe）上可能不穩定：API 可能回傳成功，但新圖示不會同步。
• OpenClaw 會根據 BlueBubbles 伺服器的 macOS 版本自動隱藏已知無法運作的動作。如果編輯仍出現在 macOS 26（Tahoe）上，請用 channels.bluebubbles.actions.edit=false 手動停用。
• 已啟用 coalesceSameSenderDms，但分開傳送（例如 Dump + URL）仍以兩個回合抵達：請參閱分開傳送合併疑難排解檢查清單 - 常見原因包括防抖視窗太緊、工作階段記錄時間戳記被誤讀為 Webhook 抵達時間，或傳送的是回覆引用（它使用 replyToBody，不是第二個 Webhook）。
• 如需狀態/健康資訊：openclaw status --all 或 openclaw status --deep。

如需一般頻道工作流程參考，請參閱頻道和 Plugins 指南。

# 相關

• 頻道路由 - 訊息的工作階段路由
• 頻道概覽 - 所有支援的頻道
• 群組 - 群組聊天行為與提及閘門檢查
• 配對 - DM 驗證與配對流程
• 安全性 - 存取模型與強化