iMessage

狀態：原生外部命令列介面整合。閘道會啟動 imsg rpc，並透過標準輸入輸出使用 JSON-RPC 通訊 — 不需要獨立的常駐程式或連接埠。強烈建議使用私有 API 模式，以獲得功能完整的 iMessage 頻道；回覆、點按回應、特效、投票、附件回覆及群組操作都需要執行 imsg launch，並成功通過私有 API 探測。

在常見的本機設定中，OpenClaw 設定流程可以在已登入「訊息」的 Mac 上，提供經使用者確認的 Homebrew imsg 安裝或更新。手動設定與 SSH 包裝指令碼拓撲仍由操作者管理：請在將執行閘道或包裝指令碼的同一使用者環境中安裝或更新 imsg。

快速設定

brew install steipete/tap/imsgbrew update && brew upgrade 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>

ssh messages-mac 'brew install steipete/tap/imsg && brew update && brew upgrade imsg'

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

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // 用於透過 SCP 擷取附件  includeAttachments: true,  // 選用：額外允許的附件根目錄（會與預設的  // /Users/*/Library/Messages/Attachments 合併）。  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

需求與權限（macOS）

• 執行 imsg 的 Mac 必須已登入「訊息」。
• 執行 OpenClaw／imsg 的處理程序環境需要「完全取用磁碟」權限（用於存取「訊息」資料庫）。
• 透過 Messages.app 傳送訊息需要「自動化」權限。
• 若要使用進階操作（回應／編輯／收回／討論串回覆／特效／投票／群組操作），必須停用「系統完整性保護」— 請參閱啟用 imsg 私有 API。不停用也能進行基本的文字與媒體傳送／接收。

未獲授權將 Apple 事件傳送至「訊息」。（-1743）

kTCCServiceAppleEvents | /usr/libexec/sshd-keygen-wrapper | auth_value=0 | com.apple.MobileSMS

啟用 imsg 私有 API

imsg 提供兩種運作模式。對 OpenClaw 而言，建議使用私有 API 模式，因為它能為頻道提供使用者期望的原生 iMessage 操作。基本模式仍適用於低風險安裝、初始驗證，或無法停用 SIP 的主機。

• 基本模式（預設，不需要變更 SIP）：透過 send 傳出文字與媒體、監看／歷史記錄輸入訊息，以及聊天清單。全新執行 brew install steipete/tap/imsg，並授予上述標準 macOS 權限後，即可使用這些功能。
• 私有 API 模式：imsg 會將輔助 dylib 注入 Messages.app，以呼叫內部 IMCore 函式。這會解鎖 react、edit、unsend、reply（討論串）、sendWithEffect、poll 與 poll-vote（「訊息」原生投票）、renameGroup、setGroupIcon、addParticipant、removeParticipant、leaveGroup，以及輸入狀態指示器和已讀回條。

本頁建議的操作功能需要私有 API 模式。imsg README 明確說明此需求：

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

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

設定

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

   brew install steipete/tap/imsgbrew update && brew upgrade imsgimsg --versionimsg status --json

   imsg status --json 輸出會回報 bridge_version、rpc_methods 及各方法的 selectors，讓你能在開始前查看目前組建支援哪些功能。

2. 停用「系統完整性保護」，並且（在較新的 macOS 上）停用「程式庫驗證」。 若要將非 Apple 的輔助 dylib 注入由 Apple 簽署的 Messages.app，必須停用 SIP，並且放寬程式庫驗證。復原模式中的 SIP 操作步驟會因 macOS 版本而異：

   • **macOS 10.13-10.15（Sierra-Catalina）：**透過終端機停用「程式庫驗證」、重新啟動至復原模式、執行 csrutil disable，然後重新啟動。
   • **macOS 11+（Big Sur 及更新版本），Intel：**進入復原模式（或網際網路復原）、執行 csrutil disable，然後重新啟動。
   • **macOS 11+，Apple Silicon：**使用電源按鈕啟動程序進入復原模式；在近期的 macOS 版本上，按一下 Continue 時請按住 Left Shift 鍵，然後執行 csrutil disable。虛擬機器設定使用不同的流程，因此請先建立 VM 快照。

   在 macOS 11 及更新版本上，僅執行 csrutil disable 通常還不夠。 Apple 仍會將 Messages.app 視為平台二進位檔並對其強制執行程式庫驗證，因此即使已關閉 SIP，臨時簽署的輔助程式仍會遭到拒絕（Library Validation failed: ... platform binary, but mapped file is not）。停用 SIP 後，也請停用程式庫驗證並重新啟動：

   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true

   macOS 26 (Tahoe)，已在 26.5.1 驗證： 關閉 SIP 並執行上述 DisableLibraryValidation 命令，就足以在 26.0 至 26.5.x 中注入輔助程式。不需要任何 boot-args。 該 plist 是決定性因素，也是 Tahoe 上注入失敗時最常遺漏的步驟：

   • 有 plist： imsg launch 會完成注入，而 imsg status 會回報 advanced_features: true。
   • 沒有 plist（即使已關閉 SIP）： imsg launch 會失敗並顯示 Failed to launch: Timeout waiting for Messages.app to initialize。AMFI 會在載入時拒絕臨時簽署的輔助程式，因此橋接器永遠無法就緒，啟動作業最終會逾時。這個逾時是大多數人在 Tahoe 上遇到的症狀；修正方式是使用上述 plist，而不是採取更激烈的措施。

   如果 macOS 升級後，imsg launch 注入或特定 selectors 開始傳回 false，通常就是這項限制所致。在認定 SIP 步驟本身失敗之前，請先檢查 SIP 與程式庫驗證狀態。如果這些設定正確，但橋接器仍無法注入，請收集 imsg status --json 與 imsg launch 的輸出，並向 imsg 專案回報，而不要進一步削弱其他全系統安全控制。

3. 注入輔助程式。 停用 SIP 並登入 Messages.app 後：

   imsg launch

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

4. 從 OpenClaw 驗證橋接器：

   openclaw channels status --probe

   iMessage 項目應回報 works，而 imsg status --json | jq '{rpc_methods, selectors}' 應顯示你的 macOS 組建所公開的功能。建立投票需要 selectors.pollPayloadMessage；投票則同時需要 selectors.pollVoteMessage 與 poll.vote RPC 方法。OpenClaw 外掛只會公布快取探測結果支援的動作；快取為空時則會維持樂觀判定，並在首次分派時探測。

如果 openclaw channels status --probe 將頻道回報為 works，但特定動作在分派時擲回 "iMessage <action> requires the imsg private API bridge"，請再次執行 imsg launch——輔助程式可能會中斷（Messages.app 重新啟動、作業系統更新等），而快取的 available: true 狀態會持續公布這些動作，直到下一次探測更新為止。

SIP 維持啟用時

如果你的威脅模型不允許停用 SIP：

• imsg 會退回基本模式——僅支援文字、媒體與接收。
• OpenClaw 外掛仍會公布文字／媒體傳送與傳入訊息監控功能；它會依各方法的功能限制，從動作介面隱藏 react、edit、unsend、reply、sendWithEffect 與群組操作。
• 你可以使用另一台非 Apple Silicon Mac（或專用機器人 Mac），關閉其 SIP 以處理 iMessage 工作負載，同時讓主要裝置維持啟用 SIP。請參閱下方的專用機器人 macOS 使用者（獨立的 iMessage 身分）。

存取控制與路由

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "使用英式拼字。" },        "8421": {          requireMention: true,          systemPrompt: "這是值班輪調聊天。回覆請控制在 3 句以內。",        },        "9907": {          // 明確抑制：此處不套用萬用字元的「使用英式拼字。」          systemPrompt: "",        },      },    },  },}

ACP 對話繫結

iMessage 聊天可以繫結至 ACP 工作階段。

操作員快速流程：

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

設定的持續性繫結使用頂層 bindings[] 項目，其中包含 type: "acp" 與 match.channel: "imessage"。

match.peer.id 可以使用：

• 正規化的私訊控制代碼，例如 +15555550123 或 user@example.com
• 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 繫結行為請參閱 ACP 代理程式。

部署模式

{  channels: {    imessage: {      enabled: true,      cliPath: "~/.openclaw/scripts/imsg-ssh",      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",      includeAttachments: true,      dbPath: "/Users/bot/Library/Messages/chat.db",    },  },}

#!/usr/bin/env bashexec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

媒體、分段與傳遞目標

imsg chats --limit 20

私有 API 動作

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

所有動作預設皆為啟用；使用 channels.imessage.actions 可個別關閉動作：

{  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,        polls: true,      },    },  },}

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

組態寫入

iMessage 預設允許由頻道發起組態寫入（當 commands.config: true 時，用於 /config set|unset）。

停用方式：

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

合併分次傳送的私訊（在一次撰寫中包含命令與 URL）

當使用者同時輸入命令和 URL（例如 Dump https://example.com/article）時，Apple 的「訊息」App 會將傳送內容拆分為 兩個獨立的 chat.db 資料列：

1. 一則文字訊息（"Dump"）。
2. 一個 URL 預覽泡泡（"https://..."），並以附件形式包含 OG 預覽圖片。

在大多數設定中，這兩個資料列抵達 OpenClaw 的時間會相隔約 0.8-2.0 秒。若未進行合併，代理程式會在第 1 回合只收到命令（並且常會回覆 “send me the URL”），之後 URL 才於第 2 回合抵達。這是 Apple 的傳送管線所造成，並非 OpenClaw 或 imsg 引入的行為。

channels.imessage.coalesceSameSenderDms 會讓私訊選擇將連續且來自相同傳送者的資料列納入緩衝。當 imsg 在其中一個來源資料列上提供結構化 URL 預覽標記 balloon_bundle_id: "com.apple.messages.URLBalloonProvider" 時，OpenClaw 只會合併這個真正的分次傳送，並將其他已緩衝的資料列保留為個別輪次。在完全不會發出氣泡中繼資料的舊版 imsg 組建中，OpenClaw 無法區分分次傳送與個別傳送，因此會退回合併該批次。這會保留引入中繼資料前的行為，而不會讓 Dump <url> 分次傳送退化為兩個輪次。群組聊天仍會逐則訊息分派，以保留多使用者的輪次結構。

{  channels: {    imessage: {      coalesceSameSenderDms: true, // 選擇啟用（預設值：false）    },  },}

{  messages: {    inbound: {      byChannel: {        // 7000 ms 可涵蓋觀察到的 Messages.app URL 預覽延遲。        imessage: 7000,      },    },  },}

情境及代理程式看到的內容

“啟用旗標”欄顯示會發出 balloon_bundle_id 的 imsg 組建之行為。在完全不會發出氣泡中繼資料的舊版 imsg 組建中，下表標示為“兩個輪次”／“N 個輪次”的資料列會改為退回舊版合併（一個輪次）：OpenClaw 無法從結構上區分分次傳送與個別傳送，因此會保留引入中繼資料前的合併行為。組建開始發出氣泡中繼資料後，就會啟用精準分離。

橋接器或閘道重新啟動後的傳入訊息復原

iMessage 會復原閘道停機期間遺漏的訊息，同時抑制 Apple 在 Push 復原後可能大量送出的陳舊“積壓炸彈”。預設行為一律啟用，並以傳入訊息去重複機制為基礎。

• 重播去重複。 每則已分派的傳入訊息都會依其 Apple GUID 記錄於持久化外掛狀態（imessage.inbound-dedupe）中，在擷取時宣告處理權，並於處理後提交（若暫時失敗則釋放，讓其可以重試）。任何已處理的項目都會遭捨棄，而不會重複分派。正因如此，復原可以積極重播，而不需要逐則訊息記帳。
• 停機復原。 啟動時，監控器會記住最後一個已分派的 chat.db rowid（每個帳號各有一個持久化游標），並將其以 since_rowid 傳給 imsg watch.subscribe，讓 imsg 重播閘道停機期間寫入的資料列，然後持續追蹤即時資料。重播範圍以最近 500 個資料列及最久約 2 小時的訊息為限，而去重複機制會捨棄任何已處理的項目。
• 陳舊積壓的訊息年齡界線。 啟動邊界之上的資料列確實是即時資料；若某個資料列的傳送日期比其抵達時間早超過約 15 分鐘，即屬於 Push 大量送出的積壓資料，因此會遭抑制。重播的資料列（位於邊界或邊界以下）則使用較寬的復原時間窗，因此最近遺漏的訊息會被傳遞，而久遠的歷史訊息則不會。

本機及遠端 cliPath 設定都支援復原，因為 since_rowid 重播會透過相同的 imsg RPC 連線執行。兩者的差異在於時間窗：當閘道可以讀取 chat.db（本機）時，它會固定啟動 rowid 邊界、限制重播跨度，並傳遞最久約數小時前遺漏的訊息。透過遠端 SSH cliPath 時，它無法讀取資料庫，因此重播沒有數量上限，而且每個資料列都使用即時訊息年齡界線——它仍可復原最近遺漏的訊息，也仍會抑制舊的積壓資料，只是採用較窄的即時時間窗。若要使用較寬的復原時間窗，請在執行 Messages 的 Mac 上執行閘道。

操作者可見的訊號

遭抑制的積壓資料會以預設層級記錄，絕不會無聲捨棄（recovery 旗標會顯示套用哪個時間窗）：

imessage: 已抑制陳舊的傳入積壓資料 account=<id> sent=<iso> recovery=<bool>（自啟動後已抑制 &lt;N&gt; 個）

遷移

channels.imessage.catchup.* 已淘汰——停機復原會自動進行，新設定不需要任何組態。既有設定中的 catchup.enabled: true 仍會作為復原重播時間窗的相容性設定檔受到支援。已停用的補追區塊（enabled: false 或沒有 enabled: true）已退役；openclaw doctor --fix 會移除這些區塊。

疑難排解

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

imsg chats --limit 10 --jsonimsg watch --chat-id <chat-id> --jsonsqlite3 ~/Library/Messages/chat.db \"select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

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

openclaw channels status --probe --channel imessage

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

設定參考指南

• 設定參考 - iMessage
• 閘道設定
• 配對

相關內容

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