來自 BlueBubbles

​

遷移檢查清單

1. 直接在執行 Messages.app 的 Mac 上驗證 imsg（imsg chats、imsg history、imsg send、imsg rpc --help）。
2. 將行為鍵從 channels.bluebubbles 複製到 channels.imessage：dmPolicy、allowFrom、groupPolicy、groupAllowFrom、groups、includeAttachments、attachmentRoots、mediaMaxMb、textChunkLimit、coalesceSameSenderDms 和 actions。
3. 移除已不存在的傳輸鍵：serverUrl、password、網路鉤子 URL，以及 BlueBubbles 伺服器設定。
4. 如果閘道不是在 Messages Mac 上執行，請將 channels.imessage.cliPath 設為 SSH 包裝器，並設定 remoteHost 以進行遠端附件擷取。
5. 啟用 channels.imessage，重新啟動閘道，然後執行 openclaw channels status --probe --channel imessage。
6. 測試一則私訊、一個允許的群組、已啟用時的附件，以及你預期代理程式會使用的每個私有 API 動作。
7. 在 iMessage 路徑驗證完成後，刪除 BlueBubbles 伺服器與舊的 channels.bluebubbles 設定。

​

imsg 的功能

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

​

開始之前

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 的終端機、編輯器、節點程序、閘道服務或 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 的真實聊天 ID。傳送需要 Messages.app 的自動化權限。如果 OpenClaw 將透過 SSH 執行，請透過 OpenClaw 將使用的相同 SSH 包裝器或使用者情境執行這些命令。如果讀取可用但傳送因 AppleEvents -1743 失敗，請檢查自動化權限是否落在 /usr/libexec/sshd-keygen-wrapper；請參閱 SSH 包裝器傳送因 AppleEvents -1743 失敗。
3. 當你需要進階動作時，啟用私有 API 橋接：
   imsg launch
   imsg status --json
   
   imsg launch 需要停用 SIP（在現代 macOS 上，還需要放寬函式庫驗證，請參閱 啟用 imsg 私有 API）。基本傳送、歷史紀錄與監看不需要 imsg launch；進階動作則需要。
4. 啟用 channels.imessage 並啟動閘道後，透過 OpenClaw 驗證橋接：
   openclaw channels status --probe
   
   iMessage 帳戶應回報 works；搭配 --json 時，探測承載會包含 privateApi.available: true。如果回報 false，請先修正該問題，請參閱 功能偵測。探測需要可連線的閘道（否則命令列介面會退回僅設定輸出），且只會探測已設定並啟用的帳戶。
5. 建立設定快照：
   cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
   

​

設定轉換

​

群組登錄陷阱

1. 寄件者 / 聊天目標允許清單（channels.imessage.groupAllowFrom）— 比對寄件者控制代碼或聊天目標（chat_id:、chat_guid:、chat_identifier: 項目）。未設定 groupAllowFrom 時，此閘門會退回使用 allowFrom；明確的 groupAllowFrom: [] 會停用該退回機制，並在 groupPolicy: "allowlist" 下丟棄每個群組訊息。
2. 群組登錄（channels.imessage.groups）— 以數值型 iMessage chat_id 為鍵：
   • 沒有 groups 區塊（或區塊為空）：只要閘門 1 具有非空的有效寄件者允許清單，群組就會通過此閘門；寄件者篩選會控管存取，且不會觸發全部丟棄的啟動警告。
   • groups 有項目但沒有 "*"：只有列出的 chat_id 鍵會通過。列出任何群組都會讓登錄變成允許清單，即使在 groupPolicy: "open" 下也是如此。
   • groups: { "*": { ... } }：每個群組都會通過此閘門。

• 啟動時每個帳號一次，當設定 groupPolicy: "allowlist" 且有效群組寄件者允許清單為空時：imessage: groupPolicy="allowlist" for account "<id>" but no group sender allowlist is configured ...。設定 groupAllowFrom（或 allowFrom）以允許寄件者；只新增 groups 並不會滿足寄件者閘門。
• 執行階段每個 chat_id 一次，當登錄丟棄群組時：imessage: dropping group message from chat_id=<id> ... not in channels.imessage.groups allowlist，並指出要新增的確切鍵。

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

​

逐步操作

1. 翻譯設定。編輯時保持新區塊停用；舊的 channels.bluebubbles 區塊目前會被 OpenClaw 忽略，可並列保留作為參考：
   {
     channels: {
       imessage: {
         enabled: false, // flip to true when ready to cut over
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // wildcard copies verbatim; re-key per-chat entries by chat_id
         // actions default to enabled; set individual toggles false to disable
       },
     },
   }
   
2. 切換並探測。 設定 channels.imessage.enabled: true，重新啟動閘道，並確認通道回報為健康：
   openclaw gateway restart
   openclaw channels status --probe --channel imessage   # expect "works"; --json shows privateApi.available: true
   
   探測需要可連線的閘道，且只會探測已設定並啟用的帳號。使用 開始之前 中的直接 imsg 命令來驗證 Mac 本身。
3. 驗證私訊。 傳送直接訊息給代理程式；確認回覆送達。
4. 分開驗證群組。 私訊和群組採用不同程式碼路徑，私訊成功並不能證明群組已正確路由。在允許的群組聊天中傳送訊息，並確認回覆送達。如果群組沒有回應（沒有代理程式回覆，也沒有錯誤），請檢查閘道日誌中上方「群組登錄表陷阱」的兩行 warn。啟動警告表示有效的寄件者允許清單是空的；每個 chat_id 的警告表示已填入的 groups 登錄表不包含該聊天。
5. 驗證動作介面。 從已配對的私訊中，請代理程式做出反應、編輯、收回、回覆、傳送照片，並且（在群組中）重新命名群組或新增/移除參與者。每個動作都應以原生方式送達 Messages.app。如果任何動作拋出 iMessage <action> requires the imsg private API bridge，請再次執行 imsg launch，並使用 openclaw channels status --probe 重新整理。
6. 一旦 iMessage 私訊、群組和動作都已驗證，移除 BlueBubbles 伺服器和 channels.bluebubbles 區塊。OpenClaw 不會讀取 channels.bluebubbles。

​

動作一致性概覽

​

配對、工作階段和 ACP 繫結

• 允許清單會依控制代碼沿用。 channels.imessage.allowFrom 會辨識 BlueBubbles 使用的相同 +15555550123 / user@example.com 字串，請原樣複製。
• 配對儲存的核准不會轉移。 配對儲存是每個通道各自獨立，且不會遷移舊的 BlueBubbles 儲存。只透過配對核准的寄件者必須在 iMessage 下重新配對一次，或由你將其控制代碼新增至 allowFrom。
• 工作階段 仍以每個代理程式 + 聊天為範圍。私訊會在預設 session.dmScope=main 下摺疊到代理程式主工作階段；群組工作階段則會依每個 chat_id 隔離（agent:<agentId>:imessage:group:<chat_id>）。BlueBubbles 工作階段鍵下的舊對話歷史不會帶入 iMessage 工作階段。
• 參照 match.channel: "bluebubbles" 的 ACP 繫結 必須改為 "imessage"。match.peer.id 形狀（chat_id:、chat_guid:、chat_identifier:、裸控制代碼）相同。

​

沒有回復通道

​

相關

• BlueBubbles 移除與 imsg iMessage 路徑 — 簡短公告與操作員摘要。
• iMessage — 完整 iMessage 通道參考，包含 imsg launch 設定和能力偵測。
• /channels/bluebubbles — 會重新導向至本遷移指南的舊版 URL。
• 配對 — 私訊驗證與配對流程。
• 通道路由 — 閘道如何為傳出回覆選擇通道。