Skip to content
OpenClaw Docs

BlueBubbles

狀態：內建外掛，透過 HTTP 與 BlueBubbles macOS 伺服器通訊。由於其 API 豐富且設定比舊版 imsg 頻道簡單，建議用於 iMessage 整合。

概覽

Section titled “概覽”
  • 透過 BlueBubbles 輔助應用程式在 macOS 上執行 (bluebubbles.app)。
  • 推薦/測試環境：macOS Sequoia (15)。macOS Tahoe (26) 也可運作；但在 Tahoe 上編輯功能目前損壞，且群組圖示更新可能回報成功卻未同步。
  • OpenClaw 透過其 REST API (GET /api/v1/ping, POST /message/text, POST /chat/:id/*) 與其通訊。
  • 傳入訊息透過 webhooks 抵達；傳出回覆、輸入指示器、已讀回執和輕拍表情則透過 REST 呼叫發送。
  • 附件和貼圖會被攝入為內傳媒體（並在可能的情況下顯示給代理人）。
  • 合成 MP3 或 CAF 音訊的自動 TTS 回覆會以 iMessage 語音備忘錄氣泡的形式傳送，而非單純的檔案附件。
  • 配對/允許清單的運作方式與其他頻道相同 (/channels/pairing 等)，需使用 channels.bluebubbles.allowFrom 加上配對碼。
  • 反應會像 Slack/Telegram 一樣作為系統事件呈現，以便代理人在回覆前「提及」它們。
  • 進階功能：編輯、取消傳送、回覆串接、訊息特效、群組管理。

快速開始

Section titled “快速開始”

  1. 安裝 BlueBubbles

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

  2. 啟用網頁 API

    在 BlueBubbles 設定中，啟用網頁 API 並設定密碼。

  3. 設定 OpenClaw

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

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

  4. 將 webhooks 指向閘道

    將 BlueBubbles webhooks 指向您的閘道（例如：`https://your-gateway-host:3000/bluebubbles-webhook?password=

    `）。

  5. 啟動閘道

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

保持 Messages.app 運作（VM / 無人值守設定）

Section titled “保持 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：

    Label

    com.user.poke-messages

    ProgramArguments

    /bin/bash

    -lc

    /usr/bin/osascript “$HOME/Scripts/poke-messages.scpt”

    RunAtLoad

    StartInterval

    300

    StandardOutPath

    /tmp/poke-messages.log

    StandardErrorPath

    /tmp/poke-messages.err

    這會 **每 300 秒** 和 **登入時** 執行一次。首次執行可能會觸發 macOS **Automation** 提示（`osascript` → Messages）。請在執行 LaunchAgent 的相同使用者工作階段中核准它們。

  3. 載入它

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

入門

Section titled “入門”

BlueBubbles 可在互動式入門中使用：

openclaw onboard

精靈會提示輸入：

BlueBubbles 伺服器位址（例如 `http://192.168.1.100:1234`）。 來自 BlueBubbles Server 設定的 API 密碼。 Webhook 端點路徑。 `pairing`、`allowlist`、`open` 或 `disabled`。 電話號碼、電子郵件或聊天目標。

您也可以透過 CLI 新增 BlueBubbles：

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

存取控制（DM + 群組）

Section titled “存取控制（DM + 群組）”
  • 預設：channels.bluebubbles.dmPolicy = "pairing"。
  • 未知發送者會收到配對代碼；在核准之前，訊息將被忽略（代碼在 1 小時後過期）。
  • 透過以下方式核准：
    • openclaw pairing list bluebubbles
    • `openclaw pairing approve bluebubbles

` - 配對是預設的權杖交換方式。詳情：配對

連絡人姓名充實（macOS，選用）

Section titled “連絡人姓名充實（macOS，選用）”

BlueBubbles 群組 webhook 通常只包含原始參與者位址。如果您希望 GroupMembers 語境改為顯示本機連絡人姓名，您可以選擇在 macOS 上啟用本機連絡人充實功能：

  • channels.bluebubbles.enrichGroupParticipantsFromContacts = true 啟用查詢。預設：false。
  • 查詢僅在群組存取權限、指令授權和提及閘門允許訊息通過後才會執行。
  • 只有未命名的電話參與者會被充實。
  • 當找不到本機匹配項時，原始電話號碼會作為備案。
{
  channels: {
    bluebubbles: {
      enrichGroupParticipantsFromContacts: true,
    },
  },
}

提及閘門（群組）

Section titled “提及閘門（群組）”

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
      },
    },
  },
}

指令閘控

Section titled “指令閘控”
  • 控制指令（例如 /config、/model）需要授權。
  • 使用 allowFrom 和 groupAllowFrom 來判斷指令授權。
  • 授權的發送者即使在群組中未提及也能執行控制指令。

每個群組的系統提示

Section titled “每個群組的系統提示”

channels.bluebubbles.groups.* 下的每個項目接受可選的 systemPrompt 字串。該值會在處理該群組訊息的每個回合中注入到代理人的系統提示，因此您可以設定每個群組的個性或行為規則，而無需編輯代理人提示：

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

索引鍵會符合 BlueBubbles 回報的群組 chatGuid / chatIdentifier / 數字 chatId，而 "*" 萬用字元項目則為沒有完全符合的每個群組提供預設值（與 requireMention 和每個群組的工具政策使用相同的模式）。完全符合永遠優先於萬用字元。DM 會忽略此欄位；請改用代理人層級或帳號層級的提示自訂。

實作範例：主旨回覆和輕觸反應（Private API）

Section titled “實作範例：主旨回覆和輕觸反應（Private API）”

啟用 BlueBubbles Private API 後，傳入訊息會帶有簡短的訊息 ID（例如 [[reply_to:5]]），並且代理人可以呼叫 action=reply 來回覆特定訊息，或呼叫 action=react 來傳送輕觸反應。每個群組的 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 對話綁定

Section titled “ACP 對話綁定”

BlueBubbles 聊天可以轉換為持久的 ACP 工作區，而無需更改傳輸層。

快速操作員流程：

  • 在私訊或允許的群組聊天中執行 /acp spawn codex --bind here。
  • 該 BlueBubbles 對話中的後續訊息將路由到生成的 ACP 會話。
  • /new 和 /reset 會就地重置同一個綁定的 ACP 會話。
  • /acp close 會關閉 ACP 會話並移除綁定。

也支援通過頂層 bindings[] 條目搭配 type: "acp" 和 match.channel: "bluebubbles" 來配置持久綁定。

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

  • 標準化的私訊代碼，例如 +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 Agents。

輸入指示 + 已讀回執

Section titled “輸入指示 + 已讀回執”
  • 輸入指示：在生成回應之前和期間會自動發送。
  • 已讀回執：由 channels.bluebubbles.sendReadReceipts 控制（預設值：true）。
  • 輸入指示：OpenClaw 發送正在輸入的開始事件；BlueBubbles 會在發送或逾時時自動清除正在輸入的狀態（透過 DELETE 手動停止並不可靠）。
{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // disable read receipts
    },
  },
}

進階操作

Section titled “進階操作”

如果在配置中啟用，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：新增/移除輕觸回應（messageId、emoji、remove）。iMessage 原生的輕觸回應集合為 love、like、dislike、laugh、emphasize 和 question。當代理程式選擇該集合以外的表情符號（例如 👀）時，反應工具會還原為 love，以便輕觸回應仍能正確顯示，而不會導致整個請求失敗。設定的 ack 反應仍會嚴格驗證，並在遇到未知值時報錯。
  • 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）。
  • upload-file：傳送媒體/檔案（to、buffer、filename、asVoice）。
    • 語音備忘錄：將 asVoice: true 設定為 MP3 或 CAF 音訊，以 iMessage 語音訊息形式傳送。BlueBubbles 在傳送語音備忘錄時會將 MP3 轉換為 CAF。
  • 舊版別名：sendAttachment 仍可使用，但 upload-file 是標準的動作名稱。

訊息 ID（簡短 vs 完整）

Section titled “訊息 ID（簡短 vs 完整）”

OpenClaw 可能會顯示簡短訊息 ID（例如 1、2）以節省 tokens。

  • MessageSid / ReplyToId 可以是簡短 ID。
  • MessageSidFull / ReplyToIdFull 包含提供者的完整 ID。
  • 簡短 ID 僅儲存在記憶體中；它們會在重新啟動或快取被清除時過期。
  • 動作接受簡短或完整的 messageId，但如果簡短 ID 不再可用，則會報錯。

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

  • 範本：{{MessageSidFull}}、{{ReplyToIdFull}}
  • 內文：輸入負載中的 MessageSidFull / ReplyToIdFull

請參閱 Configuration 以取得範本變數。

合併拆分發送的私訊（一次編排中的指令 + URL）

Section titled “合併拆分發送的私訊（一次編排中的指令 + URL）”

當使用者在 iMessage 中同時輸入指令和 URL 時 — 例如 Dump https://example.com/article — Apple 會將發送拆分為兩個單獨的 webhook 傳遞：

  1. 一則文字訊息（"Dump"）。
  2. 一個 URL 預覽氣球（"https://..."），其中包含 OG 預覽圖片作為附件。

這兩個 webhook 在大多數設定中會相隔約 0.8-2.0 秒到達 OpenClaw。如果沒有合併，代理程式會在第 1 輪單獨收到指令，回覆（通常是「傳送 URL 給我」），然後才在第 2 輪看到 URL — 此時指令語境已經遺失。

channels.bluebubbles.coalesceSameSenderDms 可選擇將私訊設為將連續相同發送者的 webhook 合併為單一代理程式輪次。群組聊天則繼續按每則訊息設定鍵值，以保留多使用者輪次結構。

啟用時機：

  • 您推出的技能預期 command + payload 會出現在同一則訊息中（傾印、貼上、儲存、佇列等）。
  • 您的使用者會在指令旁貼上 URL、圖片或長內容。
  • 您可以接受增加的私訊輪次延遲（見下文）。

保持停用時機：

  • 您需要單字私訊觸發器的最低指令延遲。
  • 您所有的流程都是沒有後續負載的一次性指令。

場景與代理看到的內容

Section titled “場景與代理看到的內容”
使用者組合Apple 傳遞標誌關閉（預設）標誌開啟 + 2500 毫秒窗口
Dump https://example.com （一次發送）2 個 webhook，間隔約 1 秒兩次代理輪次：先是單獨的 “Dump”，然後是 URL一次輪次：合併的文字 Dump https://example.com
Save this 📎image.jpg caption （附件 + 文字）2 個 webhook兩次輪次一次輪次：文字 + 圖片
/status （獨立指令）1 個 webhook即時發送等待至視窗結束，然後發送
單獨貼上 URL1 個 webhook即時發送即時發送（桶中只有一個條目）
文字和 URL 作為兩條刻意分開的訊息發送，間隔數分鐘2 個 webhook，位於窗口之外兩次輪次兩次輪次（窗口在它們之間過期）
快速湧入（窗口內超過 10 條小型 DM）N 個 webhookN 次輪次一次輪次，輸出受限（僅第一個 + 最新一個，套用文字/附件上限）

分拆發送合併疑難排解

Section titled “分拆發送合併疑難排解”

如果標誌已開啟但分拆發送仍以兩次輪次到達，請檢查每個層級：

Config actually loaded
grep coalesceSameSenderDms ~/.openclaw/openclaw.json

然後 openclaw gateway restart — 該標誌在建立 debouncer-registry 時讀取。

Debounce window wide enough for your setup

查看 BlueBubbles 伺服器日誌中的 ~/Library/Logs/bluebubbles-server/main.log：

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

測量 "Dump" 風格的文字發送與隨後的 "https://..."; Attachments: 發送之間的間隔。提高 messages.inbound.byChannel.bluebubbles 以寬裕地覆蓋該間隔。

Session JSONL timestamps ≠ webhook arrival

Session 事件時間戳 (`~/.openclaw/agents/

/sessions/*.jsonl) 反映的是 gateway 將訊息傳遞給代理的時間，**而不是** webhook 到達的時間。標記為 [Queued messages while agent was busy]` 的排隊第二則訊息表示在第二個 webhook 到達時第一輪仍在執行中 —— 合併桶已經排空了。請根據 BB 伺服器日誌而非 session 日誌來調整視窗。

Memory pressure slowing reply dispatch

在較小的機器 (8 GB) 上，代理執行回合可能耗時過長，導致合併桶在回覆完成前就已排空，URL 會作為排隊的第二回合落區。請檢查 memory_pressure 和 ps -o rss -p $(pgrep openclaw-gateway)；如果 gateway 超過約 500 MB RSS 且壓縮器正在運作，請關閉其他重度程序或升級到更大的主機。

Reply-quote sends are a different path

如果使用者將 Dump 作為現有 URL 氣球的 回覆 輕觸 (iMessage 會在 Dump 氣球上顯示「1 Reply」徽章)，則 URL 存在於 replyToBody 中，而不在第二個 webhook 中。合併並不適用 —— 這是 skill/prompt 的考量，而非 debouncer 的考量。

區塊串流

Section titled “區塊串流”

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

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

媒體 + 限制

Section titled “媒體 + 限制”
  • 傳入的附件會下載並儲存在媒體快取中。
  • 透過 channels.bluebubbles.mediaMaxMb 設定傳入及傳出媒體的大小上限（預設：8 MB）。
  • 傳出的文字會分割為 channels.bluebubbles.textChunkLimit（預設：4000 個字元）。

設定參考

Section titled “設定參考”

完整設定：Configuration

Connection and webhook
  • channels.bluebubbles.enabled：啟用/停用頻道。
  • channels.bluebubbles.serverUrl：BlueBubbles REST API 基礎 URL。
  • channels.bluebubbles.password：API 密碼。
  • channels.bluebubbles.webhookPath：Webhook 端點路徑（預設：/bluebubbles-webhook）。
Access policy
  • channels.bluebubbles.dmPolicy：pairing | allowlist | open | disabled（預設：pairing）。
  • channels.bluebubbles.allowFrom：DM 白名單（ handles、電子郵件、E.164 號碼、chat_id:*、chat_guid:*）。
  • channels.bluebubbles.groupPolicy：open | allowlist | disabled（預設：allowlist）。
  • channels.bluebubbles.groupAllowFrom：群組傳送者白名單。
  • channels.bluebubbles.enrichGroupParticipantsFromContacts：在 macOS 上，可選擇在通過閘道檢查後，從本機連絡人補充未命名的群組參與者資訊。預設值：false。
  • channels.bluebubbles.groups：各群組設定（requireMention 等）。
傳遞與分塊
  • channels.bluebubbles.sendReadReceipts：發送已讀回執（預設值：true）。
  • channels.bluebubbles.blockStreaming：啟用區塊串流（預設值：false；串流回覆所需）。
  • channels.bluebubbles.textChunkLimit：輸出分塊大小，以字元為單位（預設值：4000）。
  • channels.bluebubbles.sendTimeoutMs：透過 /api/v1/message/text 發送輸出文字時的單次請求逾時時間，單位為毫秒（預設值：30000）。在 macOS 26 設定中，如果 Private API iMessage 發送可能在 iMessage 架構內停頓 60 秒以上，請調高此數值；例如 45000 或 60000。探測、聊天查詢、反應、編輯和健康檢查目前保持較短的 10 秒預設值；計劃在後續版本中擴大對反應和編輯的支援。每個帳號的覆寫設定：`channels.bluebubbles.accounts.

.sendTimeoutMs。 - channels.bluebubbles.chunkMode：length（預設值）僅在超過 textChunkLimit 時才進行分割；newline` 會在空白行（段落邊界）處進行分割，然後再根據長度進行分塊。

媒體與歷史
  • channels.bluebubbles.mediaMaxMb：入站/出站媒體上限（單位：MB，預設值：8）。
  • channels.bluebubbles.mediaLocalRoots：明確允許的絕對本地目錄白名單，僅限用於出站本地媒體路徑。除非進行此設定，否則預設會拒絕傳送本地路徑。帳號層級覆寫：`channels.bluebubbles.accounts.

.mediaLocalRoots。 - channels.bluebubbles.coalesceSameSenderDms：將連續的相同發送者私人訊息 webhook 合併為一次 agent 週期，讓 Apple 的「文字+URL 分割傳送」作為單一訊息抵達（預設值：false）。請參閱[合併分割傳送的私人訊息](#coalescing-split-send-dms-command--url-in-one-composition)以了解情境、視窗調整與權衡。若在未指定 messages.inbound.byChannel.bluebubbles的情況下啟用，會將預設的入站防抖視窗從 500 毫秒加寬至 2500 毫秒。 -channels.bluebubbles.historyLimit：用於語境的群組訊息數量上限（0 表示停用）。 - channels.bluebubbles.dmHistoryLimit：私人訊息歷史記錄限制。 - channels.bluebubbles.replyContextApiFallback：當入站回覆抵達時未附帶 replyToBody/replyToSender，且記憶體中的回覆語境快取未命中時，作為盡力而為的備援方案，從 BlueBubbles HTTP API 取得原始訊息（預設值：false）。適用於共用一個 BlueBubbles 帳號的多實例部署、程序重啟後，或長期 TTL/LRU 快取被驅逐之後。此擷取操作受到與所有其他 BlueBubbles 用戶端請求相同的政策 SSRF 防護，絕不會拋出錯誤，並會填入快取以便後續回覆分攤成本。帳號層級覆寫：channels.bluebubbles.accounts.

.replyContextApiFallback`。頻道層級的設定會傳播至省略該旗標的帳號。

動作與帳號
  • channels.bluebubbles.actions：啟用/停用特定動作。
  • channels.bluebubbles.accounts：多帳號設定。

相關的全域選項：

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

定址 / 傳送目標

Section titled “定址 / 傳送目標”

為了穩定的路由，建議優先使用 chat_guid：

  • chat_guid:iMessage;-;+15555550123（群組首選）
  • chat_id:123
  • chat_identifier:...
  • 直接處理方式：+15555550123、[email protected]
    • 如果直接處理方式沒有現有的 DM 聊天，OpenClaw 將透過 POST /api/v1/chat/new 建立一個。這需要啟用 BlueBubbles 私有 API。

iMessage 與 SMS 路由

Section titled “iMessage 與 SMS 路由”

當同一個處理方式在 Mac 上同時擁有 iMessage 和 SMS 聊天時（例如已註冊 iMessage 的電話號碼，但也收到了綠色氣泡的備用訊息），OpenClaw 優先選擇 iMessage 聊天，並且從不自動降級為 SMS。若要強制使用 SMS 聊天，請使用明確的 sms: 目標前綴（例如 sms:+15555550123）。沒有匹配 iMessage 聊天的處理方式仍然會透過 BlueBubbles 回報的任何聊天發送。

安全性

Section titled “安全性”
  • Webhook 請求是透過比對 guid/password 查詢參數或標頭與 channels.bluebubbles.password 來進行驗證的。
  • 請將 API 密碼和 webhook 端點保密（將其視為憑證）。
  • BlueBubbles webhook 驗證沒有本地主機繞過機制。如果您代理 webhook 流量，請確保請求端對端保留 BlueBubbles 密碼。gateway.trustedProxies 在此不會取代 channels.bluebubbles.password。請參閱 閘道安全性。
  • 如果將 BlueBubbles 伺服器暴露在區域網路 (LAN) 之外，請在其上啟用 HTTPS + 防火牆規則。

疑難排解

Section titled “疑難排解”
  • 如果輸入/已讀事件停止運作，請檢查 BlueBubbles webhook 日誌並驗證閘道路徑是否符合 channels.bluebubbles.webhookPath。
  • 配對代碼在一小時後過期；請使用 openclaw pairing list bluebubbles 和 openclaw pairing approve bluebubbles <code>。
  • 反應需要 BlueBubbles 私有 API（POST /api/v1/message/react）；請確保伺服器版本已公開該 API。
  • 編輯/取消傳送需要 macOS 13+ 及相容的 BlueBubbles 伺服器版本。在 macOS 26 (Tahoe) 上，由於私有 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。

關於一般通道工作流程參考，請參閱 通道 與 外掛程式 指南。

相關

Section titled “相關”