iMessage

狀態：原生外部 CLI 整合。Gateway 會產生 imsg rpc，並透過 stdio 上的 JSON-RPC 通訊（沒有獨立 daemon/port）。進階動作需要 imsg launch 和成功的私有 API 探測。

快速設定

brew install steipete/tap/imsgimsg rpc --helpimsg launchopenclaw channels status --probe

{channels: {imessage: {enabled: true,cliPath: "/usr/local/bin/imsg",dbPath: "/Users/user/Library/Messages/chat.db",},},}

openclaw gateway

openclaw pairing list imessageopenclaw pairing approve imessage <CODE>

#!/usr/bin/env bashexec ssh -T gateway-host imsg "$@"

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // used for SCP attachment fetches  includeAttachments: true,  // Optional: override allowed attachment roots.  // Defaults include /Users/*/Library/Messages/Attachments  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

需求與權限（macOS）

• Messages 必須已在執行 imsg 的 Mac 上登入。
• 執行 OpenClaw/imsg 的處理程序內容需要完整磁碟存取權（Messages 資料庫存取）。
• 需要自動化權限才能透過 Messages.app 傳送訊息。
• 對於進階動作（react / edit / unsend / 串接回覆 / 效果 / 群組操作），必須停用 System Integrity Protection — 請參閱下方啟用 imsg 私有 API。基本文字與媒體傳送/接收不需要停用。

啟用 imsg 私有 API

imsg 以兩種操作模式提供：

• 基本模式（預設，不需要變更 SIP）：透過 send 傳出文字與媒體、傳入監看/歷史記錄、聊天清單。這是全新 brew install steipete/tap/imsg 加上上述標準 macOS 權限後開箱即可取得的功能。
• 私有 API 模式：imsg 會將輔助 dylib 注入 Messages.app，以呼叫內部 IMCore 函式。這會解鎖 react、edit、unsend、reply（串接）、sendWithEffect、renameGroup、setGroupIcon、addParticipant、removeParticipant、leaveGroup，以及輸入指示器和已讀回執。

若要使用此頻道頁面記錄的進階動作介面，你需要私有 API 模式。imsg README 對需求說得很明確：

read、typing、launch、橋接支援的豐富傳送、訊息變更與聊天管理等進階功能為選擇啟用。它們需要停用 SIP，並將輔助 dylib 注入 Messages.app。啟用 SIP 時，imsg launch 會拒絕注入。

輔助注入技術使用 imsg 自己的 dylib 來存取 Messages 私有 API。OpenClaw iMessage 路徑中沒有第三方伺服器或 BlueBubbles 執行階段。

設定

1. 在執行 Messages.app 的 Mac 上安裝（或升級）imsg：

   brew install steipete/tap/imsgimsg --versionimsg status --json

   imsg status --json 輸出會報告 bridge_version、rpc_methods 和每個方法的 selectors，因此你可以在開始前查看目前建置支援哪些項目。

2. 停用 System Integrity Protection。 這會因 macOS 版本而異，因為底層 Apple 需求取決於作業系統與硬體：

   • macOS 10.13–10.15（Sierra–Catalina）： 透過 Terminal 停用 Library Validation、重新啟動到 Recovery Mode、執行 csrutil disable、重新啟動。
   • macOS 11+（Big Sur 及更新版本），Intel： Recovery Mode（或 Internet Recovery）、csrutil disable、重新啟動。
   • macOS 11+，Apple Silicon： 使用電源按鈕啟動序列進入 Recovery；在近期 macOS 版本中，點選 Continue 時按住 Left Shift 鍵，然後執行 csrutil disable。虛擬機器設定有另一套流程 — 請先建立 VM 快照。
   • macOS 26 / Tahoe： library-validation 政策與 imagent 私有權利檢查已進一步收緊；imsg 可能需要更新的建置才能跟上。如果 macOS 主要版本升級後，imsg launch 注入或特定 selectors 開始回傳 false，請先查看 imsg 的發行說明，再假設 SIP 步驟已成功。

   執行 imsg launch 前，請依照 Apple 的 Recovery-mode 流程為你的 Mac 停用 SIP。

3. 注入輔助程式。 在 SIP 已停用且 Messages.app 已登入時：

   imsg launch

   當 SIP 仍啟用時，imsg launch 會拒絕注入，因此這也可作為步驟 2 生效的確認。

4. 從 OpenClaw 驗證橋接：

   openclaw channels status --probe

   iMessage 項目應報告 works，且 imsg status --json | jq '.selectors' 應顯示 retractMessagePart: true，以及你的 macOS 建置公開的任何 edit / typing / read selector。actions.ts 中的 OpenClaw Plugin 每方法閘控只會宣告底層 selector 為 true 的動作，因此你在代理工具清單中看到的動作介面，會反映此主機上的橋接實際能做什麼。

如果 openclaw channels status --probe 報告頻道為 works，但特定動作在派送時拋出「iMessage <action> requires the imsg private API bridge」，請再次執行 imsg launch — 輔助程式可能會脫離（Messages.app 重新啟動、OS 更新等），而快取的 available: true 狀態會持續宣告動作，直到下一次探測刷新。

當你無法停用 SIP 時

如果你的威脅模型無法接受停用 SIP：

• imsg 會退回基本模式 — 僅文字 + 媒體 + 接收。
• OpenClaw Plugin 仍會宣告文字/媒體傳送與傳入監控；它只是會從動作介面隱藏 react、edit、unsend、reply、sendWithEffect 和群組操作（依每方法能力閘控）。
• 你可以為 iMessage 工作負載執行一台獨立的非 Apple-Silicon Mac（或專用 bot Mac）並關閉 SIP，同時在主要裝置上保持 SIP 啟用。請參閱下方專用 bot macOS 使用者（獨立 iMessage 身分）。

存取控制與路由

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "Use British spelling." },        "8421": {          requireMention: true,          systemPrompt: "This is the on-call rotation chat. Keep replies under 3 sentences.",        },        "9907": {          // explicit suppression: the wildcard "Use British spelling." does not apply here          systemPrompt: "",        },      },    },  },}

ACP 對話繫結

舊版 iMessage 聊天也可以繫結到 ACP 工作階段。

快速操作流程：

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

可透過頂層 bindings[] 項目支援已設定的持久繫結，其中包含 type: "acp" 和 match.channel: "imessage"。

match.peer.id 可以使用：

• 正規化的 DM handle，例如 +15555550123 或 [email protected]
• chat_id:<id>（建議用於穩定的群組繫結）
• chat_guid:<guid>
• chat_identifier:<identifier>

範例：

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

請參閱 ACP Agents 了解共用 ACP 繫結行為。

部署模式

{  channels: {    imessage: {      enabled: true,      cliPath: "~/.openclaw/scripts/imsg-ssh",      remoteHost: "[email protected]",      includeAttachments: true,      dbPath: "/Users/bot/Library/Messages/chat.db",    },  },}

#!/usr/bin/env bashexec ssh -T [email protected] imsg "$@"

媒體、分塊與傳送目標

imsg chats --limit 20

私有 API 動作

當 imsg launch 正在執行，且 openclaw channels status --probe 回報 privateApi.available: true 時，message tool 除了一般文字傳送外，也可以使用 iMessage 原生動作。

{  channels: {    imessage: {      actions: {        reactions: true,        edit: true,        unsend: true,        reply: true,        sendWithEffect: true,        sendAttachment: true,        renameGroup: true,        setGroupIcon: true,        addParticipant: true,        removeParticipant: true,        leaveGroup: true,      },    },  },}

{  channels: {    imessage: {      sendReadReceipts: false,    },  },}

設定寫入

iMessage 預設允許由 channel 發起的設定寫入（當 commands.config: true 時供 /config set|unset 使用）。

停用：

{  channels: {    imessage: {      configWrites: false,    },  },}

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

當使用者同時輸入命令與 URL，例如 Dump https://example.com/article，Apple 的 Messages app 會將傳送拆成兩筆獨立的 chat.db 列：

1. 文字訊息（"Dump"）。
2. 帶有 OG 預覽圖片作為附件的 URL 預覽泡泡（"https://..."）。

在多數設定中，這兩列會相隔約 0.8-2.0 秒抵達 OpenClaw。若沒有合併，代理會在第 1 回合只收到命令並回覆（通常是「傳 URL 給我」），直到第 2 回合才看到 URL，而此時命令情境已經遺失。這是 Apple 的傳送管線造成的，不是 OpenClaw 或 imsg 引入的行為。

channels.imessage.coalesceSameSenderDms 會讓 DM 選擇加入，把連續的同一寄件者列合併成單一代理回合。群組聊天會繼續逐訊息分派，以保留多使用者回合結構。

{  channels: {    imessage: {      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).        imessage: 2500,      },    },  },}

情境與代理看到的內容

Gateway 停機後補抓

當 Gateway 離線（當機、重新啟動、Mac 睡眠、機器關機）時，imsg watch 會在 Gateway 恢復後，從目前的 chat.db 狀態繼續；預設情況下，間隔期間抵達的任何內容都不會被看見。補抓會在下次啟動時重播這些訊息，讓代理不會默默錯過傳入流量。

補抓預設為停用。請依 channel 啟用：

channels: {  imessage: {    catchup: {      enabled: true,             // master switch (default: false)      maxAgeMinutes: 120,        // skip rows older than now - 2h (default: 120, clamp 1..720)      perRunLimit: 50,           // max rows replayed per startup (default: 50, clamp 1..500)      firstRunLookbackMinutes: 30, // first run with no cursor: look back 30 min (default: 30)      maxFailureRetries: 10,     // give up on a wedged guid after 10 dispatch failures (default: 10)    },  },}

執行方式

每次 monitorIMessageProvider 啟動時執行一次，順序為 imsg launch 就緒 → watch.subscribe → performIMessageCatchup → 即時分派迴圈。補抓本身會透過 imsg watch 使用的同一個 JSON-RPC 用戶端，對 chats.list + 每個聊天的 messages.history 執行操作。補抓過程中抵達的任何內容都會照常經由即時分派流程；既有的傳入去重複快取會吸收與重播列的任何重疊。

每個重播列都會送入即時分派路徑（evaluateIMessageInbound + dispatchInboundMessage），因此 allowlist、群組政策、防抖器、echo 快取與讀取回條，在重播與即時訊息上的行為完全相同。

游標與重試語意

補抓會在 <openclawStateDir>/imessage/catchup/<account>__<hash>.json 保留每個帳號的游標（OpenClaw 狀態目錄預設為 ~/.openclaw，可用 OPENCLAW_STATE_DIR 覆寫）：

{  "lastSeenMs": 1717900800000,  "lastSeenRowid": 482910,  "updatedAt": 1717900801234,  "failureRetries": { "<guid>": 1 }}

• 游標會在每次成功分派時前進；當某列的分派拋出錯誤時會保持不動，下一次啟動會從保留的游標重試同一列。
• 對同一個 guid 連續拋出 maxFailureRetries 次後，補抓會記錄 warn，並強制把游標前進到卡住的訊息之後，讓後續啟動能繼續進行。
• 已放棄的 guid 在後續執行時一看到就會跳過（不嘗試分派），並在執行摘要中計入 skippedGivenUp。

操作者可見訊號

imessage catchup: replayed=N skippedFromMe=… skippedGivenUp=… failed=… givenUp=… fetchedCount=…imessage catchup: giving up on guid=<guid> after &lt;N&gt; failures; advancing cursor past itimessage catchup: fetched &lt;X&gt; rows across chats, capped to perRunLimit=&lt;Y&gt;

WARN ... capped to perRunLimit 行代表單次啟動沒有清空完整積壓。如果你的中斷經常超過預設的 50 列處理量，請提高 perRunLimit（最高 500）。

何時保持關閉

• Gateway 持續執行，並有 watchdog 自動重新啟動，且間隔永遠小於幾秒；維持預設關閉即可。
• DM 流量很低，而且漏掉訊息不會改變代理行為；第一次啟用時，firstRunLookbackMinutes 初始視窗可能會分派令人意外的舊情境。

當你開啟補抓時，沒有游標的第一次啟動只會回看 firstRunLookbackMinutes（預設 30 分鐘），而不是完整的 maxAgeMinutes 視窗；這可避免重播一長串啟用前的訊息歷史。

疑難排解

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

#!/usr/bin/env bashexec ssh -T messages-mac imsg "$@"

openclaw channels status --probe --channel imessage

imsg chats --limit 1imsg send <handle> "test"

設定參考指標

• 設定參考 - iMessage
• Gateway 設定
• 配對

相關

• Channels 概觀 — 所有支援的 channel
• BlueBubbles 移除與 imsg iMessage 路徑 — 公告與遷移摘要
• 從 BlueBubbles 轉移 — 設定轉換表與逐步切換
• 配對 — DM 驗證與配對流程
• 群組 — 群組聊天行為與提及閘控
• Channel Routing — 訊息的工作階段路由
• 安全性 — 存取模型與強化