iMessage

​

त्वरित setup

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"],
    },
  },
}

​

आवश्यकताएँ और permissions (macOS)

• imsg चलाने वाले Mac पर Messages signed in होना चाहिए।
• OpenClaw/imsg चलाने वाले process context के लिए Full Disk Access आवश्यक है (Messages DB access)।
• Messages.app के माध्यम से messages भेजने के लिए Automation permission आवश्यक है।
• उन्नत actions (react / edit / unsend / threaded reply / effects / group ops) के लिए, System Integrity Protection disabled होना चाहिए — नीचे imsg private API सक्षम करना देखें। Basic text और media send/receive इसके बिना काम करते हैं।

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 private API सक्षम करना

• Basic mode (default, SIP changes की आवश्यकता नहीं): send के माध्यम से outbound text और media, inbound watch/history, chat list। fresh brew install steipete/tap/imsg और ऊपर दी गई standard macOS permissions से out of the box यही मिलता है।
• Private API mode: imsg, internal IMCore functions call करने के लिए Messages.app में helper dylib inject करता है। यही react, edit, unsend, reply (threaded), sendWithEffect, renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, साथ ही typing indicators और read receipts unlock करता है।

read, typing, launch, bridge-backed rich send, message mutation, और chat management जैसी advanced features opt-in हैं। उन्हें SIP disabled होना और Messages.app में helper dylib inject होना आवश्यक है। SIP enabled होने पर imsg launch inject करने से मना करता है।

​

Setup

1. Messages.app चलाने वाले Mac पर imsg install (या upgrade) करें:
   brew install steipete/tap/imsg
   imsg --version
   imsg status --json
   
   imsg status --json output bridge_version, rpc_methods, और per-method selectors report करता है ताकि start करने से पहले आप देख सकें कि current build क्या support करता है।
2. System Integrity Protection, और (modern macOS पर) Library Validation disable करें। Apple-signed Messages.app में non-Apple helper dylib inject करने के लिए SIP off और library validation relaxed होना चाहिए। Recovery-mode SIP step macOS-version-specific है:
   • macOS 10.13-10.15 (Sierra-Catalina): Terminal के माध्यम से Library Validation disable करें, Recovery Mode में reboot करें, csrutil disable चलाएँ, restart करें।
   • macOS 11+ (Big Sur और बाद के), Intel: Recovery Mode (या Internet Recovery), csrutil disable, restart।
   • macOS 11+, Apple Silicon: Recovery में enter करने के लिए power-button startup sequence; recent macOS versions पर Continue click करते समय Left Shift key दबाए रखें, फिर csrutil disable। Virtual-machine setups अलग flow follow करते हैं, इसलिए पहले VM snapshot लें।
   macOS 11 और बाद में, केवल csrutil disable आमतौर पर पर्याप्त नहीं होता। Apple अभी भी Messages.app के against library validation enforce करता है क्योंकि वह platform binary है, इसलिए adhoc-signed helper reject हो जाता है (Library Validation failed: ... platform binary, but mapped file is not) भले ही SIP off हो। SIP disable करने के बाद, library validation भी disable करें और reboot करें:
   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true
   
   macOS 26 (Tahoe), 26.5.1 पर verified: SIP off plus ऊपर दिया गया DisableLibraryValidation command 26.0 से 26.5.x तक helper inject करने के लिए पर्याप्त है। कोई boot-args required नहीं हैं। plist निर्णायक factor है और Tahoe पर injection fail होने पर सबसे common missing step है:
   • plist के साथ: imsg launch inject करता है और imsg status advanced_features: true report करता है।
   • plist के बिना (SIP off होने पर भी): imsg launch Failed to launch: Timeout waiting for Messages.app to initialize के साथ fail होता है। AMFI adhoc helper को load पर reject करता है, इसलिए bridge कभी ready नहीं होता और launch timeout हो जाता है। वह timeout वह symptom है जिससे Tahoe पर अधिकांश लोग टकराते हैं, और fix ऊपर वाला plist है, कुछ अधिक drastic नहीं।
   macOS 26.5.1 (Apple Silicon) पर controlled before/after के साथ इसकी पुष्टि की गई: plist के साथ, dylib Messages.app में map हो जाती है और bridge up हो जाता है; plist remove करके reboot करें, और imsg launch ऊपर वाला timeout failure produce करता है, dylib mapped नहीं होती। यदि macOS अपग्रेड के बाद imsg launch इंजेक्शन या विशिष्ट selectors false लौटाने लगें, तो आमतौर पर यही गेट कारण होता है। यह मानने से पहले कि SIP चरण ही विफल हुआ, अपनी SIP और library-validation स्थिति जांचें। यदि ये सेटिंग सही हैं और bridge फिर भी inject नहीं कर पा रहा है, तो imsg status --json के साथ imsg launch आउटपुट इकट्ठा करें और अतिरिक्त सिस्टम-व्यापी सुरक्षा नियंत्रणों को कमजोर करने के बजाय इसे imsg प्रोजेक्ट को रिपोर्ट करें। imsg launch चलाने से पहले SIP अक्षम करने के लिए अपने Mac के लिए Apple के Recovery-mode flow का पालन करें।
3. helper inject करें। SIP अक्षम होने और Messages.app में sign in होने पर:
   imsg launch
   
   SIP अभी भी सक्षम होने पर imsg launch inject करने से इनकार करता है, इसलिए यह इस बात की पुष्टि भी करता है कि चरण 2 लागू हो गया।
4. OpenClaw से bridge सत्यापित करें:
   openclaw channels status --probe
   
   iMessage entry को works रिपोर्ट करना चाहिए, और imsg status --json | jq '.selectors' में retractMessagePart: true के साथ वे edit / typing / read selectors दिखने चाहिए जिन्हें आपका macOS build expose करता है। actions.ts में OpenClaw Plugin की per-method gating केवल उन्हीं actions को advertise करती है जिनका underlying selector true है, इसलिए agent की tool list में दिखने वाला action surface वही दर्शाता है जो bridge वास्तव में इस host पर कर सकता है।

​

जब आप SIP अक्षम नहीं कर सकते

• imsg basic mode पर fallback करता है — केवल text + media + receive।
• OpenClaw Plugin अभी भी text/media send और inbound monitoring advertise करता है; यह बस action surface से react, edit, unsend, reply, sendWithEffect, और group ops छिपा देता है (per-method capability gate के अनुसार)।
• आप iMessage workload के लिए SIP off वाला एक अलग non-Apple-Silicon Mac (या dedicated bot Mac) चला सकते हैं, जबकि अपने primary devices पर SIP enabled रख सकते हैं। नीचे Dedicated bot macOS user (separate iMessage identity) देखें।

​

Access control और routing

{
  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 conversation bindings

• DM या allowed group chat के अंदर /acp spawn codex --bind here चलाएं।
• उसी iMessage conversation में future messages spawned ACP session तक route होंगे।
• /new और /reset उसी bound ACP session को उसी जगह reset करते हैं।
• /acp close ACP session बंद करता है और binding हटाता है।

• normalized DM handle जैसे +15555550123 या user@example.com
• chat_id:<id> (stable group bindings के लिए recommended)
• 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" },
    },
  ],
}

​

Deployment patterns

{
  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 "$@"

​

Media, chunking, और delivery targets

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

​

Config writes

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

​

Split-send DMs को coalesce करना (एक composition में command + URL)

1. एक text message ("Dump")।
2. OG-preview images को attachments के रूप में रखने वाला URL-preview balloon ("https://...")।

{
  channels: {
    imessage: {
      coalesceSameSenderDms: true, // opt in (default: false)
    },
  },
}

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

​

Scenarios और agent क्या देखता है

​

bridge या gateway restart के बाद inbound recovery

• Replay dedupe। हर dispatched inbound message को persistent Plugin state (imessage.inbound-dedupe) में उसके Apple GUID द्वारा रिकॉर्ड किया जाता है, ingestion पर claim किया जाता है और handling के बाद commit किया जाता है (transient failure पर release किया जाता है ताकि retry हो सके)। जो भी पहले ही handle हो चुका है उसे दोबारा dispatch करने के बजाय drop कर दिया जाता है। इसी से recovery per-message bookkeeping के बिना आक्रामक replay कर पाती है।
• Downtime recovery। startup पर monitor अंतिम dispatched chat.db rowid (एक persisted per-account cursor) याद रखता है और उसे imsg watch.subscribe को since_rowid के रूप में पास करता है, ताकि Gateway बंद रहने के दौरान आई rows को imsg replay करे, फिर live tail करे। Replay सबसे हालिया rows और ~2 घंटे तक पुराने संदेशों तक bounded है, और dedupe पहले से handle हो चुकी किसी भी चीज़ को drop कर देता है।
• Stale-backlog age fence। startup boundary से ऊपर की rows वास्तव में live होती हैं; जिसकी send date उसके arrival से ~15 मिनट से अधिक पुरानी हो, वह Push-flush backlog है और suppressed होती है। Replayed rows (boundary पर या उससे नीचे) इसके बजाय wider recovery window का उपयोग करती हैं, ताकि हाल ही में छूटा message deliver हो जबकि बहुत पुराना इतिहास न हो।

​

Operator-visible signal

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

​

Migration

​

Troubleshooting

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"

​

Configuration reference pointers

• Configuration reference - iMessage
• Gateway configuration
• Pairing

​

Related

• Channels Overview — सभी supported channels
• BlueBubbles removal and the imsg iMessage path — announcement और migration summary
• Coming from BlueBubbles — config translation table और step-by-step cutover
• Pairing — DM authentication और pairing flow
• Groups — group chat behavior और mention gating
• Channel Routing — messages के लिए session routing
• Security — access model और hardening