OpenClaw BlueBubbles 整合指南：輕鬆串接 macOS iMessage

內建插件

目前的 OpenClaw 版本已經內建了 BlueBubbles，因此一般的封裝版本不需要額外執行 openclaw plugins install 步驟。

OpenClaw BlueBubbles 概覽

OpenClaw BlueBubbles 透過 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 接收；而外發的回覆、輸入狀態指示器、已讀回條以及 Tapbacks 則透過 REST 呼叫完成。附件和貼圖會被視為傳入媒體進行處理（並在可能的情況下呈現給代理程式）。配對與允許清單的運作方式與其他頻道相同（例如 /channels/pairing 等），需使用 channels.bluebubbles.allowFrom 以及配對碼。反應（Reactions）會像 Slack 或 Telegram 一樣以系統事件的形式呈現，讓代理程式可以在回覆前先「提及」這些反應。此外，它還支援進階功能：編輯、取消傳送、回覆串、訊息特效以及群組管理。

快速開始

在你的 Mac 上安裝 BlueBubbles 伺服器（請依照 bluebubbles.app/install 的說明進行操作）。
在 BlueBubbles 設定中，啟用 Web API 並設定密碼。

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

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

將 BlueBubbles 的 webhook 指向你的 Gateway（範例：https://your-gateway-host:3000/bluebubbles-webhook?password=<password>）。
啟動 Gateway；它會註冊 webhook 處理常式並開始進行配對。

安全性注意事項：

請務必設定 webhook 密碼。
webhook 驗證是強制要求的。除非 BlueBubbles 的 webhook 請求中包含與 channels.bluebubbles.password 相符的密碼或 GUID（例如 ?password=<password> 或 x-password），否則 OpenClaw 會拒絕該請求，無論其是否處於 loopback 或 proxy 拓撲中。
密碼驗證會在讀取或解析完整的 webhook 本體之前進行檢查。

保持 Messages.app 運作（虛擬機 / 無頭伺服器設定）

某些 macOS 虛擬機或全天候運作的伺服器可能會導致 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

AI Setup Assistant

入門指引

OpenClaw BlueBubbles 支援互動式入門流程，讓你快速設定好連線：

openclaw onboard

設定精靈會詢問以下資訊：

Server URL（必填）：BlueBubbles 伺服器位址（例如 http://192.168.1.100:1234）。
Password（必填）：來自 BlueBubbles Server 設定中的 API 密碼。
Webhook path（選填）：預設為 /bluebubbles-webhook。
DM policy：設定 pairing、allowlist、open 或 disabled。
Allow list：輸入電話號碼、電子郵件或聊天對象。

你也可以透過 CLI 直接加入 BlueBubbles：

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

存取控制 (DMs + 群組)

針對私人訊息 (DMs)：

預設設定為 channels.bluebubbles.dmPolicy = "pairing"。
未知的傳送者會收到配對碼；在核准前訊息會被忽略（配對碼 1 小時後過期）。
使用以下指令進行核准：
- openclaw pairing list bluebubbles
- openclaw pairing approve bluebubbles <CODE>
配對是預設的 token 交換方式。詳細資訊請參考：Pairing。

針對群組：

channels.bluebubbles.groupPolicy = open | allowlist | disabled（預設為 allowlist）。
當設定為 allowlist 時，channels.bluebubbles.groupAllowFrom 可控制誰能在群組中觸發指令。

聯絡人名稱增強 (macOS, 選用)

BlueBubbles 的群組 webhook 通常只包含原始的參與者位址。如果你希望 GroupMembers 上下文能顯示本地聯絡人名稱，可以在 macOS 上啟用聯絡人增強功能：

channels.bluebubbles.enrichGroupParticipantsFromContacts = true 可啟用此查詢功能。預設為 false。
查詢僅會在群組存取、指令授權及提及限制通過後才會執行。
僅會增強未命名的電話參與者。
若找不到本地匹配，則會保留原始電話號碼作為備用。

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

提及限制 (群組)

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

使用 agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns）來偵測提及。
當群組啟用 requireMention 時，Agent 僅在被提及時才會回應。
來自授權傳送者的控制指令會繞過提及限制。

針對個別群組的設定範例：

{
  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 來決定指令授權。
授權的傳送者即使在群組中沒有提及 Agent，也能執行控制指令。

ACP 對話綁定

BlueBubbles 聊天室可以在不更動傳輸層的情況下，轉變為持久化的 ACP 工作區。

快速操作流程：

在 DM 或已授權的群組聊天中執行 /acp spawn codex --bind here。
該 BlueBubbles 對話中後續的訊息將會路由至已建立的 ACP session。
/new 和 /reset 會在原地重置同一個已綁定的 ACP session。
/acp close 會關閉 ACP session 並移除綁定。

透過頂層 bindings[] 項目並設定 type: "acp" 與 match.channel: "bluebubbles"，也可以設定持久化綁定。

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

標準化的 DM 識別碼，例如 +15555550123 或 user@example.com。
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 Agents 以了解共享 ACP 綁定的行為。

輸入狀態 + 已讀回條

輸入狀態指示器：在回應生成前與生成期間會自動傳送。
已讀回條：由 channels.bluebubbles.sendReadReceipts 控制（預設為 true）。
輸入狀態：OpenClaw 會傳送輸入開始事件；BlueBubbles 會在傳送訊息或逾時後自動清除輸入狀態（手動透過 DELETE 停止並不穩定）。

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

AI Setup Assistant

進階動作

OpenClaw 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）。
upload-file：傳送媒體或檔案（參數包含 to、buffer、filename、asVoice）。
- 語音備忘錄：將 asVoice 設為 true 並使用 MP3 或 CAF 音訊，即可作為 iMessage 語音訊息傳送。BlueBubbles 會在傳送語音備忘錄時自動將 MP3 轉換為 CAF。
- 舊版別名：sendAttachment 仍然有效，但 upload-file 是目前建議使用的標準動作名稱。

訊息 ID（簡短版 vs 完整版）

OpenClaw 有時會提供「簡短」的訊息 ID（例如 1 或 2）來節省 token 使用量。

MessageSid 與 ReplyToId 可能是簡短 ID。
MessageSidFull 與 ReplyToIdFull 則包含提供者提供的完整 ID。
簡短 ID 僅存在於記憶體中，可能會在重啟或快取清除後失效。
動作同時接受簡短或完整 messageId，但若簡短 ID 已無法使用，則會發生錯誤。

若要進行持久化的自動化操作或儲存，請務必使用完整 ID：

模板：{{MessageSidFull}}、{{ReplyToIdFull}}。
內容：入站負載中的 MessageSidFull / ReplyToIdFull。

詳情請參閱 Configuration 中的模板變數說明。

區塊串流

你可以控制回應是要以單一訊息傳送，還是以區塊形式進行串流。

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

媒體與限制

當你使用 OpenClaw BlueBubbles 整合功能時，系統會自動處理傳入的附件並將其儲存在媒體快取中。你可以透過設定來管理傳輸流量，確保系統運作穩定。

傳入的附件會被下載並儲存在媒體快取中。
透過 channels.bluebubbles.mediaMaxMb 可以設定傳入與傳出媒體的上限（預設值為 8 MB）。
傳出的文字訊息會根據 channels.bluebubbles.textChunkLimit 進行分段（預設值為 4000 字元）。

設定參考

若要查看完整的設定說明，請參考 Configuration 文件。以下是所有可用的提供者選項：

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：私訊白名單（支援 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 發送卡頓（可能超過 60 秒），請調高此數值，例如設定為 45000 或 60000。目前的探測、聊天查詢、反應、編輯與健康檢查仍維持 10 秒的預設值；未來計畫將此範圍擴展至反應與編輯功能。若需針對特定帳號覆寫，請使用 channels.bluebubbles.accounts.<accountId>.sendTimeoutMs。
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：私訊的歷史紀錄上限。
channels.bluebubbles.actions：啟用或停用特定動作。
channels.bluebubbles.accounts：多帳號設定。

相關的全域選項：

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

AI Setup Assistant

尋址與發送目標

在設定訊息傳遞時，建議優先使用 chat_guid 以確保路由的穩定性，這能有效避免因識別碼變更導致的發送失敗。透過 OpenClaw 進行訊息傳遞時，你可以根據需求選擇不同的目標格式。

使用 chat_guid 作為首選（特別是針對群組）：chat_guid:iMessage;-;+15555550123
使用 chat_id：chat_id:123
使用 chat_identifier：chat_identifier:...
使用直接聯繫方式（如電話號碼或電子郵件）：+15555550123, user@example.com
- 若直接聯繫方式尚未建立私訊對話，OpenClaw 將會透過 POST /api/v1/chat/new 自動建立一個新對話。請注意，此功能必須啟用 BlueBubbles Private API。

安全性規範

為了確保你的系統通訊安全，請務必妥善管理 webhook 的驗證機制，避免未經授權的存取。請將 API 密碼與 webhook 端點視為敏感憑證，並採取適當的防護措施。

webhook 請求會透過比對 guid/password 查詢參數或標頭與 channels.bluebubbles.password 進行驗證。
請務必將 API 密碼與 webhook 端點保密，將其視為重要的憑證資料。
BlueBubbles 的 webhook 驗證機制不支援 localhost 繞過。若你使用代理伺服器處理 webhook 流量，請確保 BlueBubbles 密碼在請求端到端之間保持一致。gateway.trustedProxies 並不能取代此處的 channels.bluebubbles.password 設定。詳細資訊請參考 Gateway security。
若需將 BlueBubbles 伺服器暴露於區域網路之外，請務必啟用 HTTPS 並設定防火牆規則。

疑難排解

當你在使用 OpenClaw 進行 BlueBubbles 整合時遇到問題，可以參考以下常見狀況的排解方式。這些步驟能幫助你快速檢查 OpenClaw 的連線狀態與功能異常。

如果輸入中或已讀狀態停止運作，請檢查 BlueBubbles 的 webhook 日誌，並確認 Gateway 路徑是否與 channels.bluebubbles.webhookPath 設定相符。
配對代碼會在一個小時後過期；請使用 CLI 指令 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 將其停用。
若要查看狀態或健康資訊，請執行 openclaw status --all 或 openclaw status --deep。

關於一般頻道的工作流程參考，請參閱 Channels 以及 Plugins 指南。

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。

OpenClaw BlueBubbles 整合指南：輕鬆串接 macOS iMessage

內建插件

OpenClaw BlueBubbles 概覽

快速開始

保持 Messages.app 運作（虛擬機 / 無頭伺服器設定）

1) 儲存 AppleScript

2) 安裝 LaunchAgent

入門指引

存取控制 (DMs + 群組)

聯絡人名稱增強 (macOS, 選用)

提及限制 (群組)

指令限制

ACP 對話綁定

輸入狀態 + 已讀回條

進階動作

訊息 ID（簡短版 vs 完整版）

區塊串流

媒體與限制

設定參考

尋址與發送目標

安全性規範

疑難排解

相關文件

還是卡住了？