iMessage

​

快速設定

brew install steipete/tap/imsg
imsg rpc --help
imsg launch
openclaw channels status --probe

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

openclaw gateway

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

#!/usr/bin/env bash
exec 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: extra allowed attachment roots (merged with the default
      // /Users/*/Library/Messages/Attachments).
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

​

需求與權限（macOS）

• Messages 必須在執行 imsg 的 Mac 上登入。
• 執行 OpenClaw/imsg 的處理程序情境需要 Full Disk Access（Messages DB 存取）。
• 透過 Messages.app 傳送訊息需要 Automation 權限。
• 對於進階動作（react / edit / unsend / threaded reply / effects / polls / group ops），必須停用 System Integrity Protection — 請參閱啟用 imsg 私有 API。基本文字與媒體傳送/接收不需要停用。

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

Not authorized to send Apple events to Messages. (-1743)

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

​

啟用 imsg 私有 API

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

read、typing、launch、橋接器支援的 rich send、訊息修改與聊天管理等進階功能是選用功能。它們需要停用 SIP，並將輔助 dylib 注入 Messages.app。啟用 SIP 時，imsg launch 會拒絕注入。

​

設定

1. 在執行 Messages.app 的 Mac 上安裝（或升級）imsg：
   brew install steipete/tap/imsg
   imsg --version
   imsg status --json
   
   imsg status --json 輸出會回報 bridge_version、rpc_methods 與每個方法的 selectors，讓你可以在開始前查看目前建置支援哪些功能。
2. 停用 System Integrity Protection，並且（在現代 macOS 上）停用 Library Validation。 將非 Apple 輔助 dylib 注入 Apple 簽署的 Messages.app 需要關閉 SIP，並且放寬 library validation。Recovery 模式的 SIP 步驟依 macOS 版本而異：
   • **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 11 與更新版本上，只有 csrutil disable 通常不夠。 Apple 仍會將 Messages.app 作為平台二進位檔強制套用 library validation，因此 adhoc 簽署的輔助程式會遭拒（Library Validation failed: ... platform binary, but mapped file is not），即使 SIP 已關閉也一樣。停用 SIP 後，也請停用 library validation 並重新啟動：
   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 會在載入時拒絕 adhoc 輔助程式，因此橋接器永遠不會就緒，launch 也會逾時。該逾時是大多數人在 Tahoe 上遇到的症狀；修正方式是上述 plist，而不是更激進的做法。
   如果在 macOS 升級後，imsg launch 注入或特定 selectors 開始回傳 false，這個 gate 通常就是原因。請先檢查你的 SIP 與 library-validation 狀態，再假設 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 外掛只會宣告快取探測支援的動作，而空快取會保持樂觀，並在首次分派時探測。

​

當 SIP 保持啟用時

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

​

存取控制與路由

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: { "*": { "requireMention": true } },
    },
  },
}

{
  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 對話綁定

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

• 正規化的 DM 控制代碼，例如 +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" },
    },
  ],
}

​

部署模式

{
  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 bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

​

媒體、分塊與傳遞目標

imsg chats --limit 20

​

私有 API 動作

{
  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,
    },
  },
}

​

設定寫入

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

​

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

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

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

{
  messages: {
    inbound: {
      byChannel: {
        // 7000 ms covers observed Messages.app URL-preview delays.
        imessage: 7000,
      },
    },
  },
}

​

情境與代理程式會看到的內容

​

橋接或閘道重新啟動後的入站復原

• 重播去重。 每則已派送的入站訊息都會以其 Apple GUID 記錄在持久性外掛狀態（imessage.inbound-dedupe）中，在擷取時宣告，並在處理後提交（遇到暫時性失敗時釋放，以便重試）。任何已處理的項目都會被丟棄，而不是派送兩次。這讓復原可以積極重播，而不需要逐訊息記帳。
• 停機復原。 啟動時，監控器會記住最後派送的 chat.db rowid（持久化的每帳號游標），並將它作為 since_rowid 傳給 imsg watch.subscribe，因此 imsg 會重播閘道停機期間落入的列，然後追蹤即時內容。重播上限為最近 500 列，且只包含約 2 小時內的訊息，去重會丟棄任何已處理的項目。
• 陳舊積壓年齡柵欄。 啟動邊界以上的列是真正的即時內容；若某列的傳送日期比其抵達時間早超過約 15 分鐘，就是 Push 清出的積壓內容，會被抑制。重播列（位於邊界或以下）則改用較寬的復原視窗，因此最近遺漏的訊息會被送達，而久遠歷史不會。

​

操作者可見訊號

imessage: suppressed stale inbound backlog account=<id> sent=<iso> recovery=<bool> (<N> suppressed since start)

​

遷移

​

疑難排解

imsg rpc --help
imsg status --json
openclaw channels status --probe

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

launchctl kickstart -k system/com.apple.apsd
launchctl kickstart -k gui/$(id -u)/com.apple.CommCenter
launchctl kickstart -k gui/$(id -u)/com.apple.identityservicesd
launchctl kickstart -k gui/$(id -u)/com.apple.imagent
imsg launch
openclaw gateway restart

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

openclaw channels status --probe --channel imessage

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

​

設定參考指標

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

​

相關內容

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