iMessage

از یک Apple ID و کاربر macOS اختصاصی استفاده کنید تا ترافیک ربات از نمایه شخصی Messages شما جدا باشد.

جریان معمول:

1. یک کاربر اختصاصی macOS ایجاد کنید/وارد آن شوید.
2. در آن کاربر، با Apple ID ربات وارد Messages شوید.
3. imsg را در آن کاربر نصب کنید.
4. یک پوشش SSH ایجاد کنید تا OpenClaw بتواند imsg را در زمینهٔ آن کاربر اجرا کند.
5. channels.imessage.accounts.<id>.cliPath و .dbPath را به پروفایل آن کاربر ارجاع دهید.

نخستین اجرا ممکن است در نشست کاربر ربات به تأییدهای رابط گرافیکی (Automation + Full Disk Access) نیاز داشته باشد.

توپولوژی متداول:

• gateway روی Linux/VM اجرا می‌شود
• iMessage و imsg روی یک Mac در tailnet شما اجرا می‌شوند
• پوشش cliPath برای اجرای imsg از SSH استفاده می‌کند
• remoteHost دریافت پیوست‌ها با SCP را فعال می‌کند

نمونه:

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

از کلیدهای SSH استفاده کنید تا SSH و SCP هر دو غیرتعاملی باشند. ابتدا مطمئن شوید کلید میزبان مورد اعتماد است (برای مثال ssh bot@mac-mini.tailnet-1234.ts.net) تا known_hosts پر شود.

iMessage از پیکربندی جداگانهٔ هر حساب در channels.imessage.accounts پشتیبانی می‌کند.

هر حساب می‌تواند فیلدهایی مانند cliPath، dbPath، allowFrom، groupPolicy، mediaMaxMb، تنظیمات تاریخچه و فهرست‌های مجاز ریشهٔ پیوست‌ها را بازنویسی کند.

برای مقداردهی اولیهٔ نشست‌های جدید پیام مستقیم با تاریخچهٔ رمزگشایی‌شدهٔ اخیر imsg مربوط به آن مکالمه، channels.imessage.dmHistoryLimit را تنظیم کنید. برای بازنویسی‌های مختص هر فرستنده، از channels.imessage.dms["<sender>"].historyLimit استفاده کنید؛ از جمله 0 برای غیرفعال‌کردن تاریخچهٔ یک فرستنده.

تاریخچهٔ پیام مستقیم iMessage هنگام نیاز از imsg واکشی می‌شود. تنظیم‌نکردن dmHistoryLimit مقداردهی اولیهٔ سراسری تاریخچهٔ پیام مستقیم را غیرفعال می‌کند، اما مقدار مثبت channels.imessage.dms["<sender>"].historyLimit برای هر فرستنده همچنان مقداردهی اولیه را برای همان فرستنده فعال می‌کند.

• دریافت پیوست ورودی به‌طور پیش‌فرض غیرفعال است — برای ارسال عکس‌ها، یادداشت‌های صوتی، ویدئو و دیگر پیوست‌ها به عامل، channels.imessage.includeAttachments: true را تنظیم کنید. در صورت غیرفعال‌بودن آن، iMessageهایی که فقط پیوست دارند پیش از رسیدن به عامل حذف می‌شوند و ممکن است اصلاً هیچ خط گزارش Inbound message تولید نکنند.
• وقتی remoteHost تنظیم شده باشد، مسیرهای پیوست راه‌دور را می‌توان از طریق SCP واکشی کرد
• مسیرهای پیوست باید با ریشه‌های مجاز مطابقت داشته باشند:
  • channels.imessage.attachmentRoots (محلی)
  • channels.imessage.remoteAttachmentRoots (حالت SCP راه‌دور)
  • ریشه‌های پیکربندی‌شده الگوی ریشهٔ پیش‌فرض /Users/*/Library/Messages/Attachments را گسترش می‌دهند (ادغام می‌شوند، جایگزین نمی‌شوند)
• SCP از بررسی سخت‌گیرانهٔ کلید میزبان استفاده می‌کند (StrictHostKeyChecking=yes)
• اندازهٔ رسانهٔ خروجی از channels.imessage.mediaMaxMb استفاده می‌کند (پیش‌فرض 16 MB)

• محدودیت قطعهٔ متن: channels.imessage.textChunkLimit (پیش‌فرض 4000)
• حالت قطعه‌بندی: channels.imessage.streaming.chunkMode
  • length (پیش‌فرض)
  • newline (تقسیم ابتدا بر اساس بندها)
• قالب‌بندی ضخیم/مورب/زیرخط‌دار/خط‌خوردهٔ Markdown خروجی به متن قالب‌بندی‌شدهٔ بومی تبدیل می‌شود (گیرندگان macOS 15+ قالب‌بندی را نمایش می‌دهند؛ گیرندگان قدیمی‌تر متن ساده را بدون نشانه‌ها می‌بینند)؛ جدول‌های Markdown مطابق حالت جدول Markdown کانال تبدیل می‌شوند
• channels.imessage.sendTransport (auto پیش‌فرض، bridge، applescript) چگونگی تحویل ارسال‌ها توسط imsg را تعیین می‌کند

مقصدهای صریح ترجیحی:

• chat_id:123 (برای مسیریابی پایدار توصیه می‌شود)
• chat_guid:...
• chat_identifier:...

مقصدهای مبتنی بر شناسه نیز پشتیبانی می‌شوند:

• imessage:+1555...
• sms:+1555...
• user@example.com

imsg chats --limit 20

• react: افزودن/حذف tapbackهای iMessage (messageId، emoji، remove). tapbackهای پشتیبانی‌شده به عشق، پسندیدن، نپسندیدن، خنده، تأکید و پرسش نگاشت می‌شوند. حذف بدون ایموجی، هر tapback تنظیم‌شده‌ای را پاک می‌کند.
• reply: ارسال پاسخ رشته‌ای به یک پیام موجود (messageId، text یا message، به‌علاوهٔ chatGuid، chatId، chatIdentifier یا to). پاسخ همراه پیوست علاوه بر این به ساختی از imsg نیاز دارد که send-rich آن از --file پشتیبانی کند.
• sendWithEffect: ارسال متن با یک جلوهٔ iMessage (text یا message، effect یا effectId). نام‌های کوتاه: slam، loud، gentle، invisibleink، confetti، lasers، fireworks، balloon، heart، echo، happybirthday، shootingstar، sparkles، spotlight.
• edit: ویرایش پیام ارسال‌شده در نسخه‌های پشتیبانی‌شدهٔ macOS/API خصوصی (messageId، text یا newText). فقط پیام‌هایی که خود Gateway ارسال کرده است قابل ویرایش‌اند.
• unsend: پس‌گرفتن پیام ارسال‌شده در نسخه‌های پشتیبانی‌شدهٔ macOS/API خصوصی (messageId). فقط پیام‌هایی که خود Gateway ارسال کرده است قابل پس‌گرفتن‌اند.
• upload-file: ارسال رسانه/فایل‌ها (buffer به‌صورت base64 یا یک media/path/filePath آماده‌شده، filename، و asVoice اختیاری). نام مستعار قدیمی: sendAttachment.
• renameGroup، setGroupIcon، addParticipant، removeParticipant، leaveGroup: مدیریت گفت‌وگوهای گروهی هنگامی که مقصد فعلی یک مکالمهٔ گروهی است. این کنش‌ها هویت Messages میزبان را تغییر می‌دهند، بنابراین به یک فرستندهٔ مالک یا یک کلاینت Gateway با operator.admin نیاز دارند.
• poll: ایجاد یک نظرسنجی بومی Apple Messages (pollQuestion، تکرار pollOption از 2 تا 12 بار، به‌علاوهٔ chatGuid، chatId، chatIdentifier یا to). گیرندگان دارای iOS/iPadOS/macOS 26+ آن را به‌صورت بومی می‌بینند و رأی می‌دهند؛ نسخه‌های قدیمی‌تر سیستم‌عامل متن جایگزین "یک نظرسنجی ارسال شد" را دریافت می‌کنند. به selectors.pollPayloadMessage نیاز دارد.
• poll-vote: رأی‌دادن در یک نظرسنجی موجود (pollId یا messageId، به‌علاوهٔ دقیقاً یکی از pollOptionIndex، pollOptionId یا pollOptionText). به selectors.pollVoteMessage و متد RPC به نام poll.vote نیاز دارد.

نظرسنجی‌های ورودی پذیرفته‌شده برای عامل همراه با پرسش، برچسب‌های شماره‌دار گزینه‌ها، تعداد رأی‌ها و شناسهٔ پیام نظرسنجی موردنیاز poll-vote نمایش داده می‌شوند.

زمینهٔ iMessage ورودی، در صورت وجود، هم مقادیر کوتاه MessageSid و هم GUIDهای کامل پیام (MessageSidFull) را شامل می‌شود. شناسه‌های کوتاه به حافظهٔ نهان پاسخ اخیرِ مبتنی بر SQLite محدودند و پیش از استفاده در برابر گفت‌وگوی فعلی بررسی می‌شوند. اگر یک شناسهٔ کوتاه منقضی شد، هنگام هدف‌گیری مکالمه‌ای که آن را ارائه کرده است، با MessageSidFull آن دوباره تلاش کنید. شناسه‌های کامل مقیدبودن به مکالمه یا حساب را دور نمی‌زنند؛ بنابراین شناسه‌ای از گفت‌وگویی دیگر را با شناسه‌ای از مقصد فعلی جایگزین کنید. فراخوانی‌های واگذارشدهٔ راه‌دور ممکن است شناسه‌های کامل قدیمی را هنگامی که شواهد مکالمهٔ فعلی در دسترس نیست رد کنند.

OpenClaw کنش‌های API خصوصی را فقط زمانی پنهان می‌کند که وضعیت کاوش ذخیره‌شده در حافظهٔ نهان نشان دهد پل در دسترس نیست. اگر وضعیت ناشناخته باشد، کنش‌ها قابل‌مشاهده می‌مانند و هنگام ارسال، کاوش‌ها را به‌صورت تنبل اجرا می‌کنند تا نخستین کنش بتواند پس از imsg launch بدون تازه‌سازی دستی جداگانهٔ وضعیت موفق شود.

وقتی پل API خصوصی فعال است، گفت‌وگوهای ورودی پذیرفته‌شده به‌عنوان خوانده‌شده علامت‌گذاری می‌شوند و گفت‌وگوهای مستقیم به‌محض پذیرش نوبت، درحالی‌که عامل زمینه را آماده و پاسخ را تولید می‌کند، حباب تایپ را نشان می‌دهند. علامت‌گذاری خوانده‌شدن را با این تنظیم غیرفعال کنید:

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

ساخت‌های قدیمی‌تر imsg که پیش از فهرست قابلیت‌های هر متد ساخته شده‌اند، تایپ/خواندن را بی‌سروصدا غیرفعال می‌کنند؛ OpenClaw در هر راه‌اندازی مجدد یک هشدار یک‌باره ثبت می‌کند تا علت نبود رسید مشخص باشد.

OpenClaw در tapbackهای iMessage مشترک می‌شود و واکنش‌های پذیرفته‌شده را به‌جای متن عادی پیام به‌صورت رویدادهای سیستمی مسیریابی می‌کند؛ بنابراین tapback کاربر یک حلقهٔ پاسخ عادی را فعال نمی‌کند.

حالت اعلان با channels.imessage.reactionNotifications کنترل می‌شود:

• "own" (پیش‌فرض): فقط وقتی کاربران به پیام‌های نوشته‌شده توسط ربات واکنش نشان می‌دهند اعلان کنید.
• "all": برای همهٔ tapbackهای ورودی از فرستندگان مجاز اعلان کنید.
• "off": tapbackهای ورودی را نادیده بگیرید.

بازنویسی‌های مختص هر حساب از channels.imessage.accounts.<id>.reactionNotifications استفاده می‌کنند.

وقتی approvals.exec.enabled یا approvals.plugin.enabled مقدار true دارد و درخواست به iMessage مسیریابی می‌شود، Gateway یک درخواست تأیید را به‌صورت بومی تحویل می‌دهد و برای تعیین تکلیف آن یک tapback را می‌پذیرد:

• 👍 (tapback پسندیدن) → allow-once
• 👎 (tapback نپسندیدن) → deny
• allow-always به‌عنوان راه‌حل جایگزین دستی باقی می‌ماند: /approve <id> allow-always را به‌صورت یک پاسخ عادی ارسال کنید.

پردازش واکنش مستلزم آن است که شناسهٔ کاربر واکنش‌دهنده صراحتاً در میان تأییدکنندگان باشد. فهرست تأییدکنندگان از channels.imessage.allowFrom (یا channels.imessage.accounts.<id>.allowFrom) خوانده می‌شود؛ شمارهٔ تلفن کاربر را با قالب E.164 یا ایمیل Apple ID او اضافه کنید (مقصدهای گفت‌وگو مانند chat_id:* ورودی معتبر تأییدکننده نیستند). ورودی عام "*" پذیرفته می‌شود، اما به هر فرستنده‌ای اجازهٔ تأیید می‌دهد؛ فهرست خالی تأییدکنندگان میان‌بر واکنش را کاملاً غیرفعال می‌کند. میان‌بر واکنش عمداً reactionNotifications، dmPolicy و groupAllowFrom را دور می‌زند، زیرا فهرست مجاز صریح تأییدکنندگان تنها محدودیتی است که برای تعیین تکلیف تأیید اهمیت دارد.

مجوزدهی فرمان متنی /approve از همان فهرست پیروی می‌کند: وقتی channels.imessage.allowFrom خالی نیست، /approve <id> <decision> در برابر همان فهرست تأییدکنندگان مجاز می‌شود (نه فهرست مجاز گسترده‌تر پیام مستقیم) و فرستندگانی که در فهرست مجاز پیام مستقیم اجازه دارند اما در allowFrom نیستند، یک رد صریح دریافت می‌کنند. وقتی allowFrom خالی است، راه‌حل جایگزین همان گفت‌وگو برقرار می‌ماند و /approve هر کسی را که فهرست مجاز پیام مستقیم اجازه می‌دهد مجاز می‌کند. هر اپراتوری را که باید تأیید کند — از طریق /approve یا واکنش‌ها — به allowFrom اضافه کنید.

یادداشت‌های اپراتور:

• اتصال واکنش هم در حافظه و هم در ذخیره‌ساز کلیددار پایدار Gateway نگه‌داری می‌شود (TTL با زمان انقضای تأیید مطابقت دارد) و Gateway همچنین درخواست‌های در انتظار را برای tapbackها بررسی می‌کند؛ بنابراین tapbackی که اندکی پس از راه‌اندازی مجدد Gateway برسد، همچنان تأیید را نهایی می‌کند.
• tapback متعلق به خود اپراتور در is_from_me=true (برای مثال از یک دستگاه Apple جفت‌شده) زمانی تأیید را نهایی می‌کند که آن شناسه به‌صراحت تأییدکننده باشد.
• درخواست‌های تأیید فقط زمانی به گفت‌وگوی گروهی هدایت می‌شوند که تأییدکنندگان صریح پیکربندی شده باشند؛ در غیر این صورت، هر عضو گروه می‌تواند تأیید کند.
• tapbackهای متنی قدیمی (Liked "…" متن ساده از کلاینت‌های بسیار قدیمی Apple) نمی‌توانند تأییدها را نهایی کنند، زیرا GUID پیام ندارند؛ نهایی‌سازی واکنش به فرادادهٔ ساختاریافتهٔ tapback نیاز دارد که کلاینت‌های فعلی macOS / iOS تولید می‌کنند.

برای یک درخواست ask_user با یک پرسش غیرمحرمانه و تک‌انتخابی و یک تا چهار گزینه، OpenClaw گزینه‌های ایموجی شماره‌دار اضافه می‌کند. برای پاسخ‌دادن، با شمارهٔ متناظر به درخواست تحویل‌شده واکنش نشان دهید. واکنش باید GUID پایدار پیام نوشته‌شده توسط ربات را داشته باشد؛ سپس OpenClaw از طریق Gateway شماره را به گزینهٔ متعارف نگاشت می‌کند. لمس‌های منقضی یا تکراری نادیده گرفته می‌شوند.

درخواست‌های چندپرسشی، چندانتخابی و متن آزاد همچنان فقط با پاسخ متنی کار می‌کنند. واکنش‌های پرسش از قواعد معمول پذیرش پیام خصوصی/گروهی iMessage پیروی می‌کنند. این واکنش‌ها حتی زمانی که reactionNotifications عمومی روی "off" تنظیم شده باشد شناسایی می‌شوند، بدون آنکه واکنش‌های نامرتبط به رویدادهای عامل تبدیل شوند.

فایل اجرایی و پشتیبانی RPC را اعتبارسنجی کنید:

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

اگر بررسی پشتیبانی‌نشدن RPC را گزارش کرد، imsg را به‌روزرسانی کنید. اگر کنش‌های API خصوصی در دسترس نیستند، imsg launch را در نشست کاربر واردشدهٔ macOS اجرا کنید و دوباره بررسی کنید. اگر Gateway روی macOS اجرا نمی‌شود، به‌جای مسیر محلی پیش‌فرض imsg از راه‌اندازی Remote Mac از طریق SSH در بالا استفاده کنید.

ابتدا مشخص کنید آیا پیام به Mac محلی رسیده است. اگر chat.db تغییر نکند، حتی زمانی که imsg status --json سلامت پل را گزارش می‌کند، OpenClaw نمی‌تواند پیام را دریافت کند.

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;"

اگر پیام‌های ارسال‌شده از تلفن هیچ ردیف جدیدی ایجاد نمی‌کنند، پیش از تغییر پیکربندی OpenClaw، لایه‌های Messages در macOS و Apple Push را تعمیر کنید. یک تازه‌سازی یک‌بارهٔ سرویس اغلب کافی است:

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

یک iMessage جدید از تلفن ارسال کنید و پیش از عیب‌یابی نشست‌های OpenClaw، ایجاد یک ردیف جدید chat.db یا رویداد imsg watch را تأیید کنید. این کار را به‌صورت حلقهٔ دوره‌ای راه‌اندازی مجدد پل اجرا نکنید؛ اجرای مکرر imsg launch همراه با راه‌اندازی مجدد Gateway هنگام کار فعال می‌تواند تحویل‌ها را مختل و اجراهای در حال انجام کانال را معلق کند.

cliPath: "imsg" پیش‌فرض باید روی Mac واردشده به Messages اجرا شود. در Linux یا Windows، channels.imessage.cliPath را روی یک اسکریپت پوششی تنظیم کنید که از طریق SSH به آن Mac متصل شود و imsg "$@" را اجرا کند.

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

سپس اجرا کنید:

openclaw channels status --probe --channel imessage

بررسی کنید:

• channels.imessage.dmPolicy
• channels.imessage.allowFrom
• تأییدهای جفت‌سازی (openclaw pairing list imessage)

بررسی کنید:

• channels.imessage.groupPolicy
• channels.imessage.groupAllowFrom
• رفتار فهرست مجاز channels.imessage.groups
• پیکربندی الگوی اشاره (agents.entries.*.groupChat.mentionPatterns)

بررسی کنید:

• channels.imessage.remoteHost
• channels.imessage.remoteAttachmentRoots
• احراز هویت کلیدی SSH/SCP از میزبان Gateway
• وجود کلید میزبان در ~/.ssh/known_hosts روی میزبان Gateway
• خوانا بودن مسیر راه‌دور روی Mac اجراکنندهٔ Messages

در یک ترمینال گرافیکی تعاملی، در همان بافت کاربر/نشست، دوباره اجرا و درخواست‌ها را تأیید کنید:

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

تأیید کنید که Full Disk Access + Automation برای بافت فرایندی که OpenClaw/imsg را اجرا می‌کند اعطا شده‌اند.