iMessage

الحالة: تكامل CLI خارجي أصلي. يشغّل Gateway العملية imsg rpc ويتواصل عبر JSON-RPC من خلال الإدخال والإخراج القياسيين — دون خدمة خفية أو منفذ منفصل. يُوصى بشدة بوضع API الخاص لتوفير قناة iMessage متكاملة؛ إذ تتطلب الردود وردود الفعل والتأثيرات والاستطلاعات والردود على المرفقات وإجراءات المجموعات imsg launch واجتياز فحص API الخاص بنجاح.

في الإعداد المحلي الشائع، يمكن لإعداد OpenClaw عرض تثبيت imsg أو تحديثه عبر Homebrew على جهاز Mac المسجّل الدخول إلى Messages بعد تأكيد المستخدم. تظل الإعدادات اليدوية والبنى التي تستخدم مغلّف SSH تحت إدارة المشغّل: ثبّت imsg أو حدّثه ضمن سياق المستخدم نفسه الذي سيشغّل Gateway أو المغلّف.

الإعداد السريع

brew install steipete/tap/imsgbrew update && brew upgrade 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>

ssh messages-mac 'brew install steipete/tap/imsg && brew update && brew upgrade imsg'

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

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // يُستخدم لجلب المرفقات عبر SCP  includeAttachments: true,  // اختياري: جذور إضافية مسموح بها للمرفقات (تُدمج مع الجذر الافتراضي  // /Users/*/Library/Messages/Attachments).  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

المتطلبات والأذونات (macOS)

• يجب تسجيل الدخول إلى Messages على جهاز Mac الذي يشغّل imsg.
• يلزم منح الوصول الكامل إلى القرص لسياق العملية الذي يشغّل OpenClaw‏/imsg (للوصول إلى قاعدة بيانات Messages).
• يلزم إذن الأتمتة لإرسال الرسائل عبر Messages.app.
• بالنسبة إلى الإجراءات المتقدمة (التفاعل / التعديل / إلغاء الإرسال / الرد المتسلسل / التأثيرات / الاستطلاعات / عمليات المجموعات)، يجب تعطيل حماية تكامل النظام — راجع تمكين API الخاص لـ imsg. يعمل الإرسال والاستقبال الأساسيان للنصوص والوسائط من دون تعطيلها.

غير مصرّح بإرسال أحداث Apple إلى Messages. (-1743)

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

تمكين API الخاص لـ imsg

يأتي imsg بوضعين تشغيليين. بالنسبة إلى OpenClaw، يُعد وضع API الخاص الإعداد الموصى به لأنه يمنح القناة إجراءات iMessage الأصلية التي يتوقعها المستخدمون. ويظل الوضع الأساسي مفيدًا للتثبيتات منخفضة المخاطر أو التحقق الأولي أو المضيفات التي لا يمكن تعطيل SIP عليها.

• الوضع الأساسي (الافتراضي، لا يلزم إجراء تغييرات على 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 ضمن مسار iMessage في OpenClaw.

الإعداد

1. ثبّت (أو رقِّ) imsg على جهاز Mac الذي يشغّل Messages.app:

   brew install steipete/tap/imsgbrew update && brew upgrade imsgimsg --versionimsg status --json

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

2. عطّل حماية تكامل النظام، و(في إصدارات macOS الحديثة) التحقق من صحة المكتبات. يتطلب حقن مكتبة dylib مساعدة غير تابعة لـ Apple في Messages.app الموقّع من Apple تعطيل SIP وكذلك تخفيف قيود التحقق من صحة المكتبات. تعتمد خطوة SIP في وضع الاسترداد على إصدار macOS:

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

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

   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 الأداة المساعدة الموقّعة بتوقيع مخصص عند التحميل، فلا يصبح الجسر جاهزًا أبدًا وتنتهي مهلة التشغيل. انتهاء المهلة هذا هو العَرَض الذي يواجهه معظم الأشخاص على Tahoe؛ والحل هو ملف plist أعلاه، وليس إجراءً أكثر تشددًا.

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

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> requires the imsg private API bridge" وقت الإرسال، فشغّل 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: "استخدم التهجئة البريطانية." },        "8421": {          requireMention: true,          systemPrompt: "هذه محادثة مناوبة الدعم. اجعل الردود أقل من 3 جمل.",        },        "9907": {          // تعطيل صريح: لا ينطبق حرف البدل "استخدم التهجئة البريطانية." هنا          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 لتعطيل إجراءات فردية:

{  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 s في معظم الإعدادات. من دون الدمج، يتلقى الوكيل الأمر وحده في التفاعل 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, // تفعيل اختياري (الافتراضي: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // تغطي 7000 ms تأخيرات معاينة عنوان URL الملحوظة في Messages.app.        imessage: 7000,      },    },  },}

السيناريوهات وما يراه الوكيل

يعرض عمود «العلامة مفعّلة» السلوك في إصدار imsg يرسل balloon_bundle_id. في إصدارات imsg الأقدم التي لا ترسل أي بيانات وصفية للفقاعة إطلاقًا، تعود الصفوف أدناه المعلَّمة «تفاعلان» / «N من التفاعلات» بدلًا من ذلك إلى الدمج القديم (تفاعل واحد): لا يستطيع OpenClaw بنيويًا تمييز الإرسال المجزّأ من عمليات الإرسال المنفصلة، لذا يحافظ على الدمج السابق للبيانات الوصفية. يبدأ الفصل الدقيق بمجرد أن يرسل الإصدار بيانات وصفية للفقاعة.

استرداد الرسائل الواردة بعد إعادة تشغيل الجسر أو Gateway

تسترد iMessage الرسائل الفائتة أثناء توقف Gateway، وفي الوقت نفسه تمنع «قنبلة التراكم» القديمة التي قد تفرغها Apple بعد استعادة Push. السلوك الافتراضي مفعّل دائمًا ومبني على إزالة تكرار الوارد.

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

يعمل الاسترداد عبر إعدادات cliPath المحلية والبعيدة على حد سواء، لأن إعادة تشغيل since_rowid تعمل عبر اتصال RPC نفسه في imsg. يكمن الاختلاف في النافذة: عندما يستطيع Gateway قراءة chat.db (محليًا)، فإنه يثبّت حد rowid لبدء التشغيل، ويحد نطاق إعادة التشغيل، ويسلّم الرسائل الفائتة التي يصل عمرها إلى نحو ساعتين. عبر cliPath بعيد باستخدام SSH، لا يمكنه قراءة قاعدة البيانات، لذا لا تكون إعادة التشغيل محدودة ويستخدم كل صف حاجز العمر الحي — ويظل يسترد الرسائل الفائتة حديثًا ويمنع التراكم القديم، ولكن ضمن النافذة الحية الأضيق. شغّل Gateway على جهاز Mac الذي يستضيف Messages للحصول على نافذة الاسترداد الأوسع.

إشارة مرئية للمشغّل

يُسجَّل التراكم الممنوع بالمستوى الافتراضي، ولا يُسقط بصمت أبدًا (توضح علامة recovery النافذة المطبقة):

imessage: تم منع تراكم وارد قديم account=<id> sent=<iso> recovery=<bool> (تم منع &lt;N&gt; منذ البدء)

الترحيل

أصبح channels.imessage.catchup.* مهمَلًا — فالاسترداد بعد التوقف تلقائي ولا يحتاج إلى إعدادات في عمليات الإعداد الجديدة. تظل الإعدادات الحالية التي تتضمن catchup.enabled: true مُحترمة بوصفها ملف توافق لنافذة إعادة تشغيل الاسترداد. أما كتل الاستدراك المعطّلة (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 ومسار iMessage عبر imsg — ملخص الإعلان والترحيل
• الانتقال من BlueBubbles — جدول تحويل الإعداد وخطوات الانتقال التفصيلية
• الإقران — مصادقة الرسائل المباشرة ومسار الإقران
• المجموعات — سلوك المحادثات الجماعية وتقييد الاستجابة بالإشارات
• توجيه القنوات — توجيه جلسات الرسائل
• الأمان — نموذج الوصول والتعزيز الأمني