iMessage

स्थिति: native external CLI integration। Gateway imsg rpc spawn करता है और stdio पर JSON-RPC से संवाद करता है (अलग daemon/port नहीं)। उन्नत क्रियाओं के लिए imsg launch और सफल private API probe आवश्यक है।

त्वरित setup

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

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

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

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

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

imsg private API सक्षम करना

imsg दो operational modes में ship होता है:

• 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, poll और poll-vote (native Messages polls), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, साथ ही typing indicators और read receipts unlock करता है।

इस channel page में documented advanced action surface तक पहुंचने के लिए, आपको Private API mode चाहिए। imsg README requirement के बारे में स्पष्ट है:

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 करने से मना कर देता है।

helper-injection technique Messages private APIs तक पहुंचने के लिए imsg की अपनी dylib का उपयोग करती है। OpenClaw iMessage path में कोई third-party server या BlueBubbles runtime नहीं है।

Setup

1. Messages.app चलाने वाले Mac पर imsg install (या upgrade) करें:

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

   imsg status --json output bridge_version, rpc_methods, और प्रति-method selectors report करता है ताकि शुरू करने से पहले आप देख सकें कि 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 and later), 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 hold करें, फिर csrutil disable। Virtual-machine setups अलग flow follow करते हैं, इसलिए पहले VM snapshot लें।

   macOS 11 और बाद में, केवल csrutil disable आम तौर पर पर्याप्त नहीं है। Apple अभी भी Messages.app के विरुद्ध platform binary के रूप में library validation enforce करता है, इसलिए 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 आवश्यक नहीं हैं। plist decisive 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 हो जाता है। Tahoe पर ज्यादातर लोगों को यही timeout symptom मिलता है, और fix ऊपर वाला plist है, उससे अधिक drastic कुछ नहीं।

   यह macOS 26.5.1 (Apple Silicon) पर controlled before/after के साथ confirm किया गया था: plist के साथ, dylib Messages.app में map होता है और bridge up हो जाता है; plist हटाकर 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 फ्लो अपनाएं।

3. helper inject करें। SIP अक्षम होने और Messages.app में साइन इन होने पर:

   imsg launch

   SIP अभी भी सक्षम होने पर imsg launch inject करने से इनकार करता है, इसलिए यह इस बात की पुष्टि भी कर देता है कि चरण 2 लागू हुआ।

4. OpenClaw से bridge सत्यापित करें:

   openclaw channels status --probe

   iMessage एंट्री को works रिपोर्ट करना चाहिए, और imsg status --json | jq '{rpc_methods, selectors}' को आपके macOS build द्वारा उजागर capabilities दिखानी चाहिए। Poll creation के लिए selectors.pollPayloadMessage आवश्यक है; voting के लिए selectors.pollVoteMessage और poll.vote RPC method दोनों आवश्यक हैं। OpenClaw plugin केवल cached probe द्वारा समर्थित actions को advertise करता है, जबकि खाली cache optimistic रहता है और first dispatch पर probe करता है।

यदि openclaw channels status --probe channel को works के रूप में रिपोर्ट करता है लेकिन विशिष्ट actions dispatch समय पर "iMessage <action> requires the imsg private API bridge" फेंकते हैं, तो imsg launch फिर से चलाएं — helper बाहर हो सकता है (Messages.app restart, OS update, आदि) और cached available: true status अगले probe refresh होने तक actions advertise करता रहेगा।

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

यदि SIP-disabled आपके threat model के लिए स्वीकार्य नहीं है:

• 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: {        "*": { 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

Legacy iMessage chats को ACP sessions से भी bind किया जा सकता है।

Fast operator flow:

• 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 को close करता है और binding हटाता है।

Configured persistent bindings top-level bindings[] entries के माध्यम से supported हैं, जिनमें type: "acp" और match.channel: "imessage" होता है।

match.peer.id उपयोग कर सकता है:

• normalized DM handle जैसे +15555550123 या user@example.com
• chat_id:<id> (stable group bindings के लिए recommended)
• chat_guid:<guid>
• chat_identifier:<identifier>

Example:

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

Shared ACP binding behavior के लिए ACP Agents देखें।

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

Media, chunking, और delivery targets

imsg chats --limit 20

निजी API कार्रवाइयाँ

जब imsg launch चल रहा हो और openclaw channels status --probe privateApi.available: true रिपोर्ट करे, तो मैसेज टूल सामान्य टेक्स्ट भेजने के अलावा 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,        polls: true,      },    },  },}

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

Config writes

iMessage डिफ़ॉल्ट रूप से channel-initiated config writes की अनुमति देता है (/config set|unset के लिए जब commands.config: true हो)।

बंद करें:

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

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

जब कोई user एक command और URL साथ टाइप करता है — जैसे Dump https://example.com/article — Apple का Messages app send को दो अलग-अलग chat.db rows में split कर देता है:

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

अधिकांश setups पर ये दो rows OpenClaw तक ~0.8-2.0 s के अंतर से पहुँचती हैं। Coalescing के बिना, agent को turn 1 पर केवल command मिलती है, वह reply करता है (अक्सर "मुझे URL भेजें"), और URL केवल turn 2 पर दिखता है — उस समय तक command context पहले ही खो चुका होता है। यह Apple की send pipeline है, OpenClaw या imsg द्वारा जोड़ी गई कोई चीज़ नहीं।

channels.imessage.coalesceSameSenderDms किसी DM को consecutive same-sender rows buffer करने के लिए opt करता है। जब imsg source rows में से किसी एक पर structural URL-preview marker balloon_bundle_id: "com.apple.messages.URLBalloonProvider" expose करता है, तो OpenClaw केवल उस वास्तविक split-send को merge करता है और किसी भी अन्य buffered rows को अलग turns के रूप में रखता है। पुराने imsg builds पर, जो कोई balloon metadata बिल्कुल emit नहीं करते, OpenClaw split-send और अलग-अलग sends में अंतर नहीं कर सकता, इसलिए वह bucket merge करने पर fallback करता है। यह Dump <url> split-sends को दो turns में regress करने के बजाय pre-metadata behavior को preserve करता है। Group chats per-message dispatch करती रहती हैं ताकि multi-user turn structure preserved रहे।

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

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

परिदृश्य और एजेंट क्या देखता है

"फ़्लैग चालू" कॉलम उस imsg बिल्ड पर व्यवहार दिखाता है जो balloon_bundle_id उत्सर्जित करता है। पुराने imsg बिल्ड पर, जो बिल्कुल भी बैलून मेटाडेटा उत्सर्जित नहीं करते, नीचे "दो टर्न" / "N टर्न" चिह्नित पंक्तियाँ इसके बजाय लीगेसी मर्ज (एक टर्न) पर वापस जाती हैं: OpenClaw संरचनात्मक रूप से स्प्लिट-सेंड को अलग-अलग सेंड से नहीं पहचान सकता, इसलिए यह प्री-मेटाडेटा मर्ज को बनाए रखता है। जैसे ही बिल्ड बैलून मेटाडेटा उत्सर्जित करता है, सटीक पृथक्करण सक्रिय हो जाता है।

ब्रिज या Gateway रीस्टार्ट के बाद इनबाउंड रिकवरी

iMessage उन संदेशों को रिकवर करता है जो Gateway डाउन रहने के दौरान छूट गए थे, और उसी समय उस पुराने "बैकलॉग बम" को दबाता है जिसे Apple Push रिकवरी के बाद फ़्लश कर सकता है। डिफ़ॉल्ट व्यवहार हमेशा चालू रहता है, और इनबाउंड डीड्यूप पर बना है।

• रीप्ले डीड्यूप। हर डिस्पैच किया गया इनबाउंड संदेश उसके Apple GUID द्वारा पर्सिस्टेंट Plugin स्टेट (imessage.inbound-dedupe) में रिकॉर्ड किया जाता है, इंजेशन पर क्लेम किया जाता है और हैंडलिंग के बाद कमिट किया जाता है (क्षणिक विफलता पर रिलीज़ किया जाता है ताकि यह दोबारा कोशिश कर सके)। जो भी पहले से हैंडल हो चुका है, उसे दोबारा डिस्पैच करने के बजाय ड्रॉप किया जाता है। यही रिकवरी को प्रति-संदेश बहीखाते के बिना आक्रामक रूप से रीप्ले करने देता है।
• डाउनटाइम रिकवरी। स्टार्टअप पर मॉनिटर अंतिम डिस्पैच किए गए chat.db rowid (एक पर्सिस्ट किया गया प्रति-अकाउंट कर्सर) को याद रखता है और उसे since_rowid के रूप में imsg watch.subscribe को पास करता है, ताकि imsg Gateway डाउन रहने के दौरान आई पंक्तियों को रीप्ले करे, फिर लाइव टेल करे। रीप्ले सबसे हाल की पंक्तियों और ~2 घंटे तक पुराने संदेशों तक सीमित होता है, और डीड्यूप पहले से हैंडल की गई किसी भी चीज़ को ड्रॉप कर देता है।
• पुराने-बैकलॉग की उम्र-सीमा। स्टार्टअप सीमा से ऊपर की पंक्तियाँ सचमुच लाइव होती हैं; जिसकी भेजने की तारीख उसके आगमन से ~15 मिनट से अधिक पुरानी है, वह Push-फ़्लश बैकलॉग है और दबा दी जाती है। रीप्ले की गई पंक्तियाँ (सीमा पर या उससे नीचे) इसके बजाय व्यापक रिकवरी विंडो का उपयोग करती हैं, ताकि हाल में छूटा संदेश डिलीवर हो जबकि बहुत पुराना इतिहास न हो।

रिकवरी स्थानीय और रिमोट दोनों cliPath सेटअप पर काम करती है, क्योंकि since_rowid रीप्ले उसी imsg RPC कनेक्शन पर चलता है। अंतर विंडो का है: जब Gateway chat.db पढ़ सकता है (स्थानीय), तो यह स्टार्टअप rowid सीमा को एंकर करता है, रीप्ले स्पैन को सीमित करता है, और कुछ घंटों तक पुराने छूटे संदेश डिलीवर करता है। रिमोट SSH cliPath पर यह डेटाबेस नहीं पढ़ सकता, इसलिए रीप्ले अनकैप्ड होता है और हर पंक्ति लाइव उम्र-सीमा का उपयोग करती है — यह फिर भी हाल में छूटे संदेश रिकवर करता है और पुराने बैकलॉग को दबाता है, बस संकरे लाइव विंडो के साथ। व्यापक रिकवरी विंडो के लिए Gateway को Messages Mac पर चलाएँ।

ऑपरेटर-दृश्यमान संकेत

दबाया गया बैकलॉग डिफ़ॉल्ट स्तर पर लॉग किया जाता है, कभी चुपचाप ड्रॉप नहीं किया जाता (recovery फ़्लैग दिखाता है कि कौन-सी विंडो लागू हुई):

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

माइग्रेशन

channels.imessage.catchup.* डिप्रिकेटेड है — डाउनटाइम रिकवरी अब स्वचालित है और नए सेटअप के लिए किसी कॉन्फ़िग की आवश्यकता नहीं है। catchup.enabled: true वाले मौजूदा कॉन्फ़िग रिकवरी रीप्ले विंडो के लिए कॉम्पैटिबिलिटी प्रोफ़ाइल के रूप में अब भी सम्मानित रहते हैं। अक्षम catchup ब्लॉक (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
• Gateway कॉन्फ़िगरेशन
• पेयरिंग

संबंधित

• चैनल अवलोकन — सभी समर्थित चैनल
• BlueBubbles हटाना और imsg iMessage पथ — घोषणा और माइग्रेशन सारांश
• BlueBubbles से आ रहे हैं — कॉन्फ़िग अनुवाद तालिका और चरण-दर-चरण कटओवर
• पेयरिंग — DM प्रमाणीकरण और पेयरिंग फ़्लो
• ग्रुप — ग्रुप चैट व्यवहार और मेंशन गेटिंग
• चैनल रूटिंग — संदेशों के लिए सेशन रूटिंग
• सुरक्षा — एक्सेस मॉडल और हार्डनिंग