iMessage

الحالة: تكامل CLI خارجي أصلي. يشغّل Gateway الأمر imsg rpc ويتواصل عبر JSON-RPC على stdio (من دون daemon/منفذ منفصل). تتطلب الإجراءات المتقدمة imsg launch وفحص 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.
• يلزم Full Disk Access لسياق العملية الذي يشغّل OpenClaw/imsg (للوصول إلى قاعدة بيانات Messages).
• يلزم إذن Automation لإرسال الرسائل عبر Messages.app.
• للإجراءات المتقدمة (التفاعل / التحرير / إلغاء الإرسال / الرد المتسلسل / التأثيرات / الاستطلاعات / عمليات المجموعات)، يجب تعطيل 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، ومراقبة/سجل الوارد، وقائمة المحادثات. هذا ما تحصل عليه مباشرة من تثبيت brew install steipete/tap/imsg جديد مع أذونات macOS القياسية أعلاه.
• وضع API الخاص: يحقن imsg مكتبة dylib مساعدة في Messages.app لاستدعاء دوال IMCore داخلية. هذا ما يفعّل react وedit وunsend وreply (المتسلسل)، وsendWithEffect، وpoll وpoll-vote (استطلاعات Messages الأصلية)، وrenameGroup، وsetGroupIcon، وaddParticipant، وremoveParticipant، وleaveGroup، بالإضافة إلى مؤشرات الكتابة وإيصالات القراءة.

للوصول إلى سطح الإجراءات المتقدمة الذي توثقه صفحة القناة هذه، تحتاج إلى وضع API الخاص. يوضح README الخاص بـ imsg المتطلب صراحةً:

الميزات المتقدمة مثل read وtyping وlaunch والإرسال الغني المدعوم بالجسر وتعديل الرسائل وإدارة المحادثات اختيارية. تتطلب تعطيل SIP وحقن مكتبة dylib مساعدة في Messages.app. يرفض imsg launch الحقن عند تفعيل SIP.

تستخدم تقنية حقن المساعد مكتبة dylib الخاصة بـ imsg للوصول إلى واجهات API الخاصة في Messages. لا يوجد خادم تابع لجهة خارجية أو وقت تشغيل BlueBubbles في مسار OpenClaw iMessage.

الإعداد

1. ثبّت (أو حدّث) imsg على Mac الذي يشغّل Messages.app:

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

   يعرض خرج imsg status --json القيم bridge_version وrpc_methods وselectors لكل طريقة حتى تتمكن من معرفة ما يدعمه البناء الحالي قبل البدء.

2. عطّل System Integrity Protection، و(على macOS الحديث) Library Validation. يتطلب حقن مكتبة dylib مساعدة غير تابعة لـ Apple داخل Messages.app الموقّع من Apple إيقاف SIP و تخفيف library validation. خطوة SIP في وضع Recovery خاصة بإصدار macOS:

   • macOS 10.13-10.15 (Sierra-Catalina): عطّل Library Validation عبر Terminal، وأعد التشغيل إلى Recovery Mode، وشغّل csrutil disable، ثم أعد التشغيل.
   • macOS 11+ (Big Sur والأحدث)، Intel: Recovery Mode (أو Internet Recovery)، ثم csrutil disable، ثم أعد التشغيل.
   • macOS 11+، Apple Silicon: تسلسل بدء التشغيل بزر الطاقة للدخول إلى Recovery؛ في إصدارات macOS الحديثة اضغط باستمرار على مفتاح Left Shift عند النقر على Continue، ثم csrutil disable. تتبع إعدادات الآلات الافتراضية مسارًا منفصلًا، لذلك خذ لقطة VM أولًا.

   في macOS 11 والأحدث، لا يكون csrutil disable وحده كافيًا عادةً. لا تزال Apple تفرض library validation على Messages.app باعتباره ثنائيًا للنظام الأساسي، لذلك تُرفض مكتبة مساعدة موقعة adhoc (Library Validation failed: ... platform binary, but mapped file is not) حتى مع إيقاف SIP. بعد تعطيل SIP، عطّل library validation أيضًا وأعد التشغيل:

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

   macOS 26 (Tahoe)، تم التحقق على 26.5.1: إيقاف SIP مع أمر DisableLibraryValidation أعلاه كافيان لحقن المساعد عبر 26.0 حتى 26.5.x. لا حاجة إلى boot-args. ملف plist هو العامل الحاسم والخطوة الأكثر شيوعًا التي تنقص عند فشل الحقن على Tahoe:

   • مع plist: يحقن imsg launch ويعرض imsg status القيمة advanced_features: true.
   • من دون plist (حتى مع إيقاف SIP): يفشل imsg launch بالرسالة Failed to launch: Timeout waiting for Messages.app to initialize. ترفض AMFI تحميل المساعد الموقّع adhoc، لذلك لا يصبح الجسر جاهزًا أبدًا وتنتهي عملية التشغيل بالمهلة. هذه المهلة هي العرض الأكثر شيوعًا على Tahoe، والإصلاح هو plist أعلاه، وليس أي إجراء أشد.

   تم تأكيد ذلك بمقارنة مضبوطة قبل/بعد على macOS 26.5.1 (Apple Silicon): مع plist، تُحمّل dylib داخل Messages.app ويعمل الجسر؛ أزل plist وأعد التشغيل، وسيُنتج imsg launch فشل المهلة أعلاه من دون تحميل dylib.

   إذا بدأ حقن imsg launch أو بدأت selectors معيّنة تُرجع false بعد ترقية macOS، فهذه البوابة هي السبب المعتاد. تحقّق من حالة SIP والتحقق من المكتبات قبل افتراض أن خطوة SIP نفسها فشلت. إذا كانت هذه الإعدادات صحيحة وما زال الجسر غير قادر على الحقن، فاجمع imsg status --json مع خرج imsg launch وأبلغ مشروع imsg بذلك بدلاً من إضعاف عناصر تحكم أمان إضافية على مستوى النظام.

   اتبع مسار Apple في وضع الاسترداد لجهاز Mac لديك لتعطيل SIP قبل تشغيل imsg launch.

3. احقن المساعد. مع تعطيل SIP وتسجيل الدخول إلى Messages.app:

   imsg launch

   يرفض imsg launch الحقن عندما يظل SIP مفعلاً، لذلك يعمل هذا أيضاً كتأكيد على نجاح الخطوة 2.

4. تحقّق من الجسر من OpenClaw:

   openclaw channels status --probe

   يجب أن يُبلغ إدخال iMessage عن works، ويجب أن يُظهر imsg status --json | jq '{rpc_methods, selectors}' القدرات التي يتيحها بناء macOS لديك. يتطلب إنشاء الاستطلاعات selectors.pollPayloadMessage؛ ويتطلب التصويت كلاً من selectors.pollVoteMessage وطريقة RPC poll.vote. لا يعلن Plugin الخاص بـ OpenClaw إلا عن الإجراءات التي يدعمها الفحص المخزن مؤقتاً، بينما تبقى الذاكرة المؤقتة الفارغة متفائلة وتفحص عند أول إرسال.

إذا أبلغ openclaw channels status --probe أن القناة works لكن إجراءات معيّنة ترمي الخطأ "يتطلب iMessage <action> جسر واجهة برمجة التطبيقات الخاصة imsg" وقت الإرسال، فشغّل imsg launch مرة أخرى — يمكن أن يسقط المساعد (إعادة تشغيل Messages.app، تحديث نظام التشغيل، إلخ) وستستمر حالة available: true المخزنة مؤقتاً في الإعلان عن الإجراءات حتى يحدّث الفحص التالي الحالة.

عندما لا يمكنك تعطيل SIP

إذا لم يكن تعطيل SIP مقبولاً لنموذج التهديد لديك:

• يعود imsg إلى الوضع الأساسي — النص + الوسائط + الاستقبال فقط.
• يظل Plugin الخاص بـ OpenClaw يعلن إرسال النص/الوسائط والمراقبة الواردة؛ لكنه يخفي فقط react وedit وunsend وreply وsendWithEffect وعمليات المجموعات من سطح الإجراءات (وفقاً لبوابة القدرة لكل طريقة).
• يمكنك تشغيل Mac منفصل غير Apple-Silicon (أو Mac مخصص للبوت) مع إيقاف SIP لعبء عمل iMessage، مع إبقاء SIP مفعلاً على أجهزتك الأساسية. راجع مستخدم 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.

تدفق سريع للمشغّل:

• شغّل /acp spawn codex --bind here داخل الرسالة المباشرة أو دردشة المجموعة المسموح بها.
• تُوجّه الرسائل المستقبلية في محادثة iMessage نفسها إلى جلسة ACP المنشأة.
• يعيد /new و/reset ضبط جلسة ACP المرتبطة نفسها في مكانها.
• يغلق /acp close جلسة ACP ويزيل الارتباط.

تُدعم الارتباطات الدائمة المهيأة عبر إدخالات bindings[] على المستوى الأعلى مع type: "acp" وmatch.channel: "imessage".

يمكن أن يستخدم match.peer.id:

• معرّف رسالة مباشرة مطبّع مثل +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,    },  },}

دمج الرسائل المباشرة ذات الإرسال المقسم (أمر + URL في إنشاء واحد)

عندما يكتب المستخدم أمرًا وURL معًا — مثل Dump https://example.com/article — يقسم تطبيق Messages من Apple الإرسال إلى صفّين منفصلين في chat.db:

1. رسالة نصية ("Dump").
2. بالون معاينة URL ("https://...") مع صور معاينة OG كمرفقات.

يصل الصفان إلى OpenClaw بفاصل يقارب 0.8-2.0 ثانية في معظم الإعدادات. بدون الدمج، يتلقى الوكيل الأمر وحده في الدور 1، ويرد (غالبًا "أرسل لي URL")، ولا يرى URL إلا في الدور 2 — وعندها يكون سياق الأمر قد فُقد بالفعل. هذا مسار إرسال Apple، وليس شيئًا يضيفه OpenClaw أو imsg.

يختار channels.imessage.coalesceSameSenderDms إدخال الرسالة المباشرة في تخزين مؤقت للصفوف المتتالية من نفس المرسل. عندما يكشف imsg علامة معاينة URL البنيوية balloon_bundle_id: "com.apple.messages.URLBalloonProvider" في أحد الصفوف المصدرية، يدمج OpenClaw ذلك الإرسال المقسم الحقيقي فقط ويحافظ على أي صفوف مخزنة مؤقتًا أخرى كأدوار منفصلة. في إصدارات imsg الأقدم التي لا تصدر أي بيانات وصفية للبالون إطلاقًا، لا يستطيع OpenClaw تمييز الإرسال المقسم عن الإرسالات المنفصلة، لذلك يعود إلى دمج الحاوية. يحافظ ذلك على سلوك ما قبل البيانات الوصفية بدلًا من التراجع عن إرسالات 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. السلوك الافتراضي مفعل دائمًا، ومبني على إزالة تكرار الوارد.

• إزالة تكرار إعادة التشغيل. تُسجل كل رسالة واردة مُرسلة بواسطة Apple GUID الخاص بها في حالة Plugin الدائمة (imessage.inbound-dedupe)، وتُحجز عند الإدخال وتُثبت بعد المعالجة (وتُحرر عند فشل عابر حتى يمكن إعادة المحاولة). يُسقط أي شيء عولج مسبقًا بدلًا من إرساله مرتين. هذا ما يسمح لإعادة الاسترداد بأن تكون عدوانية بلا تتبع لكل رسالة.
• استرداد وقت التعطل. عند بدء التشغيل، يتذكر المراقب آخر chat.db rowid مُرسل (مؤشر مستمر لكل حساب) ويمرره إلى imsg watch.subscribe باسم since_rowid، بحيث يعيد imsg تشغيل الصفوف التي وصلت أثناء تعطل Gateway، ثم يتابع المباشر. إعادة التشغيل محدودة بأحدث الصفوف وبالرسائل التي يصل عمرها إلى ~ساعتين، وتُسقط إزالة التكرار أي شيء عولج مسبقًا.
• سياج عمر السجل المتراكم القديم. الصفوف فوق حد بدء التشغيل مباشرة بالفعل؛ أما الصف الذي يكون تاريخ إرساله أقدم من وصوله بأكثر من ~15 دقيقة فهو سجل 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
• الاقتران

ذو صلة

• نظرة عامة على القنوات — كل القنوات المدعومة
• إزالة BlueBubbles ومسار imsg iMessage — الإعلان وملخص الترحيل
• الانتقال من BlueBubbles — جدول ترجمة الإعدادات والتحويل خطوة بخطوة
• الاقتران — مصادقة DM وتدفق الاقتران
• المجموعات — سلوك محادثات المجموعات وبوابة الإشارات
• توجيه القنوات — توجيه الجلسات للرسائل
• الأمان — نموذج الوصول والتقوية