iMessage

وضعیت: یکپارچه‌سازی بومی CLI خارجی. Gateway، imsg rpc را اجرا می‌کند و از طریق JSON-RPC روی stdio ارتباط برقرار می‌کند (بدون daemon/port جداگانه). کنش‌های پیشرفته به imsg launch و یک probe موفق API خصوصی نیاز دارند.

راه‌اندازی سریع

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

نیازمندی‌ها و مجوزها (macOS)

• Messages باید روی Macی که imsg را اجرا می‌کند وارد حساب شده باشد.
• برای process contextی که OpenClaw/imsg را اجرا می‌کند، Full Disk Access لازم است (دسترسی به DB پیام‌ها).
• برای ارسال پیام از طریق Messages.app، مجوز Automation لازم است.
• برای کنش‌های پیشرفته (react / edit / unsend / threaded reply / effects / polls / group ops)، System Integrity Protection باید غیرفعال باشد — بخش فعال‌سازی API خصوصی imsg را در پایین ببینید. ارسال/دریافت متن و رسانه پایه بدون آن کار می‌کند.

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

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

فعال‌سازی API خصوصی imsg

imsg در دو حالت عملیاتی عرضه می‌شود:

• حالت پایه (پیش‌فرض، بدون نیاز به تغییرات SIP): متن و رسانه خروجی از طریق send، watch/history ورودی، فهرست chat. این همان چیزی است که با یک brew install steipete/tap/imsg تازه به‌همراه مجوزهای استاندارد macOS در بالا به‌صورت آماده دریافت می‌کنید.
• حالت API خصوصی: imsg یک helper dylib را به Messages.app inject می‌کند تا توابع داخلی IMCore را فراخوانی کند. این همان چیزی است که react، edit، unsend، reply (threaded)، sendWithEffect، poll و poll-vote (نظرسنجی‌های بومی Messages)، renameGroup، setGroupIcon، addParticipant، removeParticipant، leaveGroup، به‌همراه indicators مربوط به typing و read receipts را فعال می‌کند.

برای رسیدن به سطح کنش‌های پیشرفته‌ای که این صفحه channel مستند می‌کند، به حالت API خصوصی نیاز دارید. README مربوط به imsg درباره این نیازمندی صریح است:

قابلیت‌های پیشرفته‌ای مانند read، typing، launch، ارسال غنی پشتیبانی‌شده با bridge، تغییر پیام، و مدیریت chat اختیاری هستند. آن‌ها نیاز دارند SIP غیرفعال باشد و یک helper dylib به Messages.app inject شود. imsg launch وقتی SIP فعال باشد از inject کردن خودداری می‌کند.

تکنیک helper-injection از dylib خود imsg برای دسترسی به APIهای خصوصی Messages استفاده می‌کند. در مسیر iMessage در OpenClaw هیچ سرور شخص ثالث یا runtime مربوط به BlueBubbles وجود ندارد.

راه‌اندازی

1. imsg را نصب (یا upgrade) کنید روی Macی که Messages.app را اجرا می‌کند:

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

   خروجی imsg status --json، bridge_version، rpc_methods، و selectors به‌ازای هر method را گزارش می‌کند تا پیش از شروع ببینید build فعلی از چه چیزهایی پشتیبانی می‌کند.

2. System Integrity Protection و (در macOSهای مدرن) Library Validation را غیرفعال کنید. inject کردن یک helper dylib غیر Apple به Messages.app امضاشده توسط Apple نیاز دارد SIP خاموش باشد و library validation relaxed شود. مرحله SIP در حالت Recovery مخصوص نسخه macOS است:

   • macOS 10.13-10.15 (Sierra-Catalina): Library Validation را از طریق Terminal غیرفعال کنید، به Recovery Mode راه‌اندازی مجدد کنید، csrutil disable را اجرا کنید، restart کنید.
   • macOS 11+ (Big Sur و بعدتر)، Intel: Recovery Mode (یا Internet Recovery)، csrutil disable، restart.
   • macOS 11+، Apple Silicon: دنباله startup با دکمه power برای ورود به Recovery؛ در نسخه‌های اخیر macOS وقتی Continue را کلیک می‌کنید کلید Left Shift را نگه دارید، سپس csrutil disable. راه‌اندازی‌های ماشین مجازی flow جداگانه‌ای دارند، پس ابتدا یک snapshot از VM بگیرید.

   در macOS 11 و بعدتر، معمولاً csrutil disable به‌تنهایی کافی نیست. Apple همچنان library validation را در برابر Messages.app به‌عنوان یک platform binary اعمال می‌کند، بنابراین یک helper با امضای adhoc رد می‌شود (Library Validation failed: ... platform binary, but mapped file is not) حتی وقتی SIP خاموش است. پس از غیرفعال کردن SIP، library validation را نیز غیرفعال کنید و reboot کنید:

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

   macOS 26 (Tahoe)، تأییدشده روی 26.5.1: خاموش بودن SIP به‌علاوه دستور DisableLibraryValidation در بالا برای inject کردن helper در سراسر 26.0 تا 26.5.x کافی است. هیچ boot-args لازم نیست. plist عامل تعیین‌کننده و رایج‌ترین مرحله جاافتاده هنگام شکست injection روی Tahoe است:

   • با plist: imsg launch inject می‌کند و imsg status، advanced_features: true را گزارش می‌کند.
   • بدون plist (حتی با SIP خاموش): imsg launch با Failed to launch: Timeout waiting for Messages.app to initialize شکست می‌خورد. AMFI، helper با امضای adhoc را هنگام load رد می‌کند، بنابراین bridge هرگز آماده نمی‌شود و launch timeout می‌شود. این timeout همان علامتی است که بیشتر افراد روی Tahoe با آن روبه‌رو می‌شوند، و راه‌حل plist بالاست، نه اقدام شدیدتر.

   این موضوع با یک قبل/بعد کنترل‌شده روی macOS 26.5.1 (Apple Silicon) تأیید شد: با plist، dylib در Messages.app map می‌شود و bridge بالا می‌آید؛ plist را حذف کنید و reboot کنید، و imsg launch خطای timeout بالا را با map نشدن dylib تولید می‌کند.

   اگر تزریق imsg launch یا selectors خاص پس از ارتقای macOS شروع به برگرداندن false کنند، این دروازه معمولا علت معمول است. پیش از این‌که فرض کنید خود مرحله SIP شکست خورده است، وضعیت SIP و اعتبارسنجی کتابخانه را بررسی کنید. اگر آن تنظیمات درست هستند و bridge همچنان نمی‌تواند تزریق کند، خروجی imsg status --json به‌همراه خروجی imsg launch را جمع‌آوری کنید و به‌جای تضعیف کنترل‌های امنیتی بیشتر در سطح کل سیستم، آن را به پروژه imsg گزارش دهید.

   پیش از اجرای imsg launch، جریان Recovery-mode اپل را برای Mac خود دنبال کنید تا SIP را غیرفعال کنید.

3. helper را تزریق کنید. با SIP غیرفعال و Messages.app واردشده:

   imsg launch

   وقتی SIP هنوز فعال باشد، imsg launch از تزریق خودداری می‌کند؛ بنابراین این کار همچنین تأیید می‌کند که مرحله ۲ اعمال شده است.

4. bridge را از OpenClaw بررسی کنید:

   openclaw channels status --probe

   ورودی iMessage باید works گزارش کند، و imsg status --json | jq '{rpc_methods, selectors}' باید قابلیت‌هایی را نشان دهد که build مربوط به macOS شما در معرض می‌گذارد. ایجاد نظرسنجی به selectors.pollPayloadMessage نیاز دارد؛ رأی‌دادن هم به selectors.pollVoteMessage و هم به روش RPC با نام poll.vote نیاز دارد. Plugin مربوط به OpenClaw فقط اقداماتی را تبلیغ می‌کند که توسط probe کش‌شده پشتیبانی می‌شوند، درحالی‌که کش خالی خوش‌بین باقی می‌ماند و هنگام نخستین dispatch، probe می‌کند.

اگر openclaw channels status --probe کانال را به‌صورت works گزارش می‌کند اما اقدامات خاص هنگام dispatch خطای "iMessage <action> requires the imsg private API bridge" می‌دهند، دوباره imsg launch را اجرا کنید — helper ممکن است خارج شود (راه‌اندازی مجدد Messages.app، به‌روزرسانی OS و غیره) و وضعیت کش‌شده available: true تا زمانی که probe بعدی تازه‌سازی شود، همچنان اقدامات را تبلیغ خواهد کرد.

وقتی نمی‌توانید SIP را غیرفعال کنید

اگر SIP-disabled برای مدل تهدید شما پذیرفتنی نیست:

• imsg به حالت پایه برمی‌گردد — فقط متن + رسانه + دریافت.
• Plugin مربوط به OpenClaw همچنان ارسال متن/رسانه و پایش ورودی را تبلیغ می‌کند؛ فقط react، edit، unsend، reply، sendWithEffect و عملیات گروهی را از سطح اقدام پنهان می‌کند (بر اساس دروازه قابلیت هر روش).
• می‌توانید یک Mac جداگانه غیر Apple-Silicon (یا یک Mac اختصاصی bot) را با SIP خاموش برای بار کاری iMessage اجرا کنید، درحالی‌که SIP را روی دستگاه‌های اصلی خود فعال نگه می‌دارید. پایین‌تر کاربر اختصاصی bot در macOS (هویت جداگانه iMessage) را ببینید.

کنترل دسترسی و مسیریابی

{  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

گفت‌وگوهای قدیمی iMessage نیز می‌توانند به نشست‌های ACP متصل شوند.

جریان سریع operator:

• /acp spawn codex --bind here را داخل DM یا گفت‌وگوی گروهی مجاز اجرا کنید.
• پیام‌های آینده در همان گفت‌وگوی iMessage به نشست ACP ایجادشده مسیریابی می‌شوند.
• /new و /reset همان نشست ACP متصل را درجا reset می‌کنند.
• /acp close نشست ACP را می‌بندد و اتصال را حذف می‌کند.

اتصال‌های پایدار پیکربندی‌شده از طریق ورودی‌های سطح بالای bindings[] با type: "acp" و match.channel: "imessage" پشتیبانی می‌شوند.

match.peer.id می‌تواند از این‌ها استفاده کند:

• handle عادی‌سازی‌شده 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" },    },  ],}

برای رفتار مشترک اتصال 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: {        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 به‌طور پیش‌فرض اجازه نوشتن پیکربندی آغازشده از کانال را می‌دهد (برای /config set|unset وقتی commands.config: true باشد).

غیرفعال‌سازی:

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

ادغام پیام‌های مستقیم split-send (فرمان + URL در یک ترکیب)

وقتی کاربر یک فرمان و یک URL را با هم تایپ می‌کند — مثلاً Dump https://example.com/article — برنامه Messages شرکت Apple ارسال را به دو ردیف جداگانه chat.db تقسیم می‌کند:

1. یک پیام متنی ("Dump").
2. یک حباب پیش‌نمایش URL ("https://...") با تصاویر پیش‌نمایش OG به‌عنوان پیوست.

این دو ردیف در بیشتر راه‌اندازی‌ها با فاصله حدود 0.8 تا 2.0 ثانیه به OpenClaw می‌رسند. بدون ادغام، عامل در نوبت 1 فقط فرمان را دریافت می‌کند، پاسخ می‌دهد (اغلب «URL را برایم بفرست») و URL را فقط در نوبت 2 می‌بیند — در آن نقطه زمینه فرمان از دست رفته است. این خط لوله ارسال Apple است، نه چیزی که OpenClaw یا imsg معرفی کرده باشد.

channels.imessage.coalesceSameSenderDms یک پیام مستقیم را وارد بافرکردن ردیف‌های پیاپی از همان فرستنده می‌کند. وقتی imsg نشانگر ساختاری پیش‌نمایش URL یعنی balloon_bundle_id: "com.apple.messages.URLBalloonProvider" را روی یکی از ردیف‌های منبع ارائه کند، OpenClaw فقط همان split-send واقعی را ادغام می‌کند و هر ردیف بافرشده دیگر را به‌عنوان نوبت‌های جداگانه نگه می‌دارد. روی بیلدهای قدیمی‌تر imsg که اصلاً هیچ فراداده حبابی منتشر نمی‌کنند، OpenClaw نمی‌تواند split-send را از ارسال‌های جداگانه تشخیص دهد، بنابراین به ادغام bucket برمی‌گردد. این رفتار پیش از فراداده را حفظ می‌کند، به‌جای اینکه split-sendهای Dump <url> را دوباره به دو نوبت تبدیل کند. گفت‌وگوهای گروهی همچنان به‌ازای هر پیام ارسال می‌شوند تا ساختار نوبت چندکاربره حفظ شود.

{  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 تخلیه کند سرکوب می‌کند. رفتار پیش‌فرض همیشه روشن است و بر پایهٔ حذف تکرار ورودی ساخته شده است.

• حذف تکرار بازپخش. هر پیام ورودیِ ارسال‌شده با GUID اپل خود در وضعیت پایدار Plugin (imessage.inbound-dedupe) ثبت می‌شود، هنگام دریافت claim می‌شود و پس از پردازش commit می‌شود (در خطای گذرا آزاد می‌شود تا بتواند دوباره تلاش کند). هر چیزی که قبلاً پردازش شده باشد به‌جای ارسال دوباره حذف می‌شود. این همان چیزی است که اجازه می‌دهد بازیابی بدون حسابداری تک‌پیامی، بازپخش تهاجمی انجام دهد.
• بازیابی زمان خاموشی. هنگام راه‌اندازی، ناظر آخرین rowid ارسال‌شدهٔ chat.db را به خاطر می‌سپارد (یک مکان‌نمای پایدار به‌ازای هر حساب) و آن را به‌عنوان since_rowid به imsg watch.subscribe می‌دهد، تا imsg ردیف‌هایی را که هنگام خاموش بودن gateway رسیده‌اند بازپخش کند و سپس زنده دنبال کند. بازپخش به تازه‌ترین ردیف‌ها و پیام‌های حداکثر حدود ۲ ساعت قبل محدود است، و حذف تکرار هر چیزی را که قبلاً پردازش شده باشد حذف می‌کند.
• حصار سنی صف عقب‌ماندهٔ کهنه. ردیف‌های بالاتر از مرز راه‌اندازی واقعاً زنده هستند؛ موردی که تاریخ ارسالش بیش از حدود ۱۵ دقیقه قدیمی‌تر از زمان رسیدنش باشد، صف عقب‌ماندهٔ تخلیه‌شده توسط Push است و سرکوب می‌شود. ردیف‌های بازپخش‌شده (در مرز یا پایین‌تر از آن) به‌جای آن از پنجرهٔ بازیابی گسترده‌تر استفاده می‌کنند، بنابراین پیامی که اخیراً از دست رفته تحویل داده می‌شود، اما تاریخچهٔ بسیار قدیمی نه.

بازیابی روی هر دو راه‌اندازی محلی و راه‌اندازی‌های cliPath راه‌دور کار می‌کند، چون بازپخش since_rowid از همان اتصال RPC به imsg اجرا می‌شود. تفاوت در پنجره است: وقتی gateway می‌تواند chat.db را بخواند (محلی)، مرز rowid راه‌اندازی را لنگر می‌کند، گسترهٔ بازپخش را محدود می‌کند، و پیام‌های ازدست‌رفته تا چند ساعت قبل را تحویل می‌دهد. روی cliPath راه‌دور با SSH نمی‌تواند پایگاه داده را بخواند، پس بازپخش بدون سقف است و هر ردیف از حصار سنی زنده استفاده می‌کند — همچنان پیام‌های اخیراً ازدست‌رفته را بازیابی می‌کند و همچنان صف عقب‌ماندهٔ قدیمی را سرکوب می‌کند، فقط با پنجرهٔ زندهٔ باریک‌تر. برای پنجرهٔ بازیابی گسترده‌تر، gateway را روی Mac مربوط به Messages اجرا کنید.

سیگنال قابل مشاهده برای اپراتور

صف عقب‌ماندهٔ سرکوب‌شده در سطح پیش‌فرض ثبت می‌شود و هرگز بی‌صدا حذف نمی‌شود (پرچم 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
• Pairing

مرتبط

• نمای کلی کانال‌ها — همهٔ کانال‌های پشتیبانی‌شده
• حذف BlueBubbles و مسیر imsg iMessage — اعلامیه و خلاصهٔ مهاجرت
• مهاجرت از BlueBubbles — جدول ترجمهٔ پیکربندی و انتقال گام‌به‌گام
• Pairing — احراز هویت DM و جریان pairing
• گروه‌ها — رفتار گفت‌وگوی گروهی و gating اشاره
• مسیریابی کانال — مسیریابی نشست برای پیام‌ها
• امنیت — مدل دسترسی و سخت‌سازی