從 BlueBubbles 轉移過來

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

何時適合進行此遷移

• 你已經在 Messages.app 已登入的同一台 Mac（或可透過 SSH 存取的 Mac）上執行 imsg。
• 你想減少一個移動部件 — 不需要獨立的 BlueBubbles 伺服器、不需要要驗證的 REST 端點，也不需要 Webhook 管線。使用單一 CLI 二進位檔，取代伺服器 + 用戶端應用程式 + 輔助程式。
• 你使用的是受支援的 macOS / imsg 建置版本，且私有 API 探測回報 available: true。

​

imsg 的功能

• 讀取會使用唯讀 SQLite handle 從 ~/Library/Messages/chat.db 取得。
• 即時傳入訊息來自 imsg watch / watch.subscribe，它會追蹤 chat.db 檔案系統事件，並以輪詢作為後備。
• 傳送一般文字與檔案時，會使用 Messages.app 自動化。
• 進階動作會使用 imsg launch 將 imsg 輔助程式注入 Messages.app。這會解鎖讀取回條、輸入指示器、豐富傳送、編輯、收回、對話串回覆、tapbacks，以及群組管理。
• Linux 建置可以檢查複製的 chat.db，但無法傳送、監看即時 Mac 資料庫，或驅動 Messages.app。若要使用 OpenClaw iMessage，請在已登入的 Mac 上執行 imsg，或透過指向該 Mac 的 SSH wrapper 執行。

​

開始之前

1. 在執行 Messages.app 的 Mac 上安裝 imsg：
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   如果 imsg chats 因 unable to open database file、空白輸出或 authorization denied 而失敗，請授予啟動 imsg 的終端機、編輯器、Node 程序、Gateway 服務，或 SSH 父程序完整磁碟存取權，然後重新開啟該父程序。
2. 在變更 OpenClaw 設定之前，先驗證讀取、監看、傳送與 RPC 介面：
   imsg chats --limit 10 --json | jq -s
   imsg history --chat-id 42 --limit 10 --attachments --json | jq -s
   imsg watch --chat-id 42 --reactions --json
   imsg send --chat-id 42 --text "OpenClaw imsg test"
   imsg rpc --help
   
   將 42 替換為 imsg chats 中的真實 chat id。傳送需要 Messages.app 的自動化權限。如果 OpenClaw 會透過 SSH 執行，請透過 OpenClaw 將使用的相同 SSH wrapper 或使用者情境來執行這些指令。
3. 需要進階動作時，啟用私有 API 橋接：
   imsg launch
   imsg status --json
   
   imsg launch 需要停用 SIP。基本傳送、歷史記錄與監看可在沒有 imsg launch 的情況下運作；進階動作則不行。
4. 透過 OpenClaw 驗證橋接：
   openclaw channels status --probe
   
   你需要看到 imessage.privateApi.available: true。如果它回報 false，請先修正該問題 — 參閱功能偵測。
5. 建立設定快照：
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

設定轉換

​

群組登錄陷阱

1. 寄件者 / 聊天目標允許清單（channels.imessage.groupAllowFrom）- 由 isAllowedIMessageSender 檢查。會依寄件者控制代碼、chat_guid、chat_identifier 或 chat_id 比對傳入訊息。形狀與 BlueBubbles 相同。
2. 群組登錄（channels.imessage.groups）- 由 inbound-processing.ts:199 中的 resolveChannelGroupPolicy 檢查。使用 groupPolicy: "allowlist" 時，此閘門需要以下其中一項：
   • groups: { "*": { ... } } 萬用字元項目（設定 allowAll = true），或
   • groups 下明確的個別 chat_id 項目。

• 當設定了 groupPolicy: "allowlist" 但 channels.imessage.groups 為空（沒有 "*" 萬用字元，也沒有個別 chat_id 項目）時，每個帳號會在啟動時發出一次性 warn，且會在任何訊息抵達前觸發。
• 當特定群組在執行期間首次被丟棄時，會依每個 chat_id 發出一次性 warn，指出該 chat_id，以及要新增到 groups 才能允許它的確切鍵。

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123", "chat_guid:any;-;..."],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

​

逐步操作

1. 在既有 BlueBubbles 區塊旁新增 iMessage 區塊。在新路徑驗證完成前，僅保留舊區塊作為複製來源：
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false, // turn on after the dry run below
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // copy from bluebubbles.groups — silently drops groups if missing, see "Group registry footgun" above
         actions: {
           reactions: true,
           edit: true,
           unsend: true,
           reply: true,
           sendWithEffect: true,
           sendAttachment: true,
         },
       },
     },
   }
   
2. 乾跑探測——啟動 Gateway，並確認 iMessage 回報為健康：
   openclaw gateway
   openclaw channels status
   openclaw channels status --probe   # expect imessage.privateApi.available: true
   
   因為 imessage.enabled 仍為 false，尚未路由任何傳入的 iMessage 流量——但 --probe 會測試橋接，因此你可以在切換前發現權限或安裝問題。
3. 切換。 移除 BlueBubbles 設定，並在同一次設定編輯中啟用 iMessage：
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   重新啟動 Gateway。傳入的 iMessage 流量現在會透過內建 Plugin 流動。
4. 驗證 DM。 傳送一則直接訊息給 agent；確認回覆已送達。
5. 分別驗證群組。 DM 和群組會走不同的程式碼路徑——DM 成功不代表群組正在路由。在已配對的群組聊天中傳送訊息給 agent，並確認回覆已送達。如果群組變得無聲（沒有 agent 回覆，也沒有錯誤），請檢查 Gateway 記錄是否有 imessage: dropping group message from chat_id=<id>，或啟動時是否出現 imessage: groupPolicy="allowlist" but channels.imessage.groups is empty 這行——兩者都會在預設記錄層級觸發。如果出現任一訊息，表示你的 groups 區塊缺失或為空——請參閱上方的「群組登錄陷阱」。
6. 驗證動作介面——從已配對的 DM 中，要求 agent 做出反應、編輯、收回、回覆、傳送照片，並且（在群組中）重新命名群組／新增或移除參與者。每個動作都應該原生送達 Messages.app。如果任何動作拋出「iMessage <action> requires the imsg private API bridge」，請再次執行 imsg launch，並重新整理 channels status --probe。
7. 驗證 iMessage DM、群組和動作後，移除 BlueBubbles 伺服器與設定。OpenClaw 不會使用 channels.bluebubbles。

​

動作對等一覽

​

配對、工作階段與 ACP 綁定

• 配對核准會依 handle 延續。你不需要重新核准已知寄件者——channels.imessage.allowFrom 會辨識 BlueBubbles 使用的相同 +15555550123 / user@example.com 字串。
• 工作階段仍以每個 agent + 聊天為範圍。DM 會在預設 session.dmScope=main 下收斂到 agent 主要工作階段；群組工作階段則依每個 chat_id 保持隔離。工作階段鍵不同（agent:<id>:imessage:group:<chat_id> 與 BlueBubbles 對應項不同）——BlueBubbles 工作階段鍵下的舊對話歷史不會帶入 iMessage 工作階段。
• 參照 match.channel: "bluebubbles" 的 ACP 綁定需要更新為 "imessage"。match.peer.id 形狀（chat_id:、chat_guid:、chat_identifier:、裸 handle）完全相同。

​

無回復通道

​

相關

• iMessage——完整 iMessage channel 參考，包括 imsg launch 設定與能力偵測。
• /channels/bluebubbles——重新導向至本遷移指南的舊版 URL。
• 配對——DM 驗證與配對流程。
• Channel Routing——Gateway 如何為傳出回覆選擇 channel。