iMessage

Documentation Index

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

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

​

快速設定

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: 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 chats --limit 1
# or
imsg send <handle> "test"

​

啟用 imsg 私有 API

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

read、typing、launch、橋接支援的豐富傳送、訊息變更與聊天管理等進階功能為選擇啟用。它們需要停用 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 版本而異，因為底層 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 的動作，因此你在代理工具清單中看到的動作介面，會反映此主機上的橋接實際能做什麼。

​

當你無法停用 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: { "*": { "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 handle，例如 +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,
      },
    },
  },
}

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

​

設定寫入

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

​

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

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

{
  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 停機後補抓

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

​

執行方式

​

游標與重試語意

{
  "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 <N> failures; advancing cursor past it
imessage catchup: fetched <X> rows across chats, capped to perRunLimit=<Y>

​

何時保持關閉

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

​

疑難排解

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

#!/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
• Gateway 設定
• 配對

​

相關

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