الانتقال من BlueBubbles

​

قائمة تحقق الترحيل

1. تحقق من imsg مباشرة على جهاز Mac الذي يشغّل Messages.app (imsg chats وimsg history وimsg send وimsg rpc --help).
2. انسخ مفاتيح السلوك من channels.bluebubbles إلى channels.imessage: dmPolicy وallowFrom وgroupPolicy وgroupAllowFrom وgroups وincludeAttachments وattachmentRoots وmediaMaxMb وtextChunkLimit وcoalesceSameSenderDms وactions.
3. احذف مفاتيح النقل التي لم تعد موجودة: serverUrl وpassword وعناوين URL الخاصة بالـ Webhook وإعداد خادم BlueBubbles.
4. إذا لم يكن Gateway يعمل على جهاز Mac الخاص بالرسائل، فاضبط channels.imessage.cliPath على غلاف SSH واضبط remoteHost لجلب المرفقات عن بعد.
5. مع إيقاف Gateway، فعّل channels.imessage، ثم شغّل openclaw channels status --probe --channel imessage.
6. اختبر رسالة مباشرة واحدة، ومجموعة واحدة مسموحًا بها، والمرفقات إذا كانت مفعّلة، وكل إجراء API خاص تتوقع أن يستخدمه الوكيل.
7. احذف خادم BlueBubbles وإعداد channels.bluebubbles القديم بعد التحقق من مسار iMessage.

​

متى يكون هذا الترحيل مناسبًا

• أنت تشغّل imsg بالفعل على جهاز Mac نفسه (أو على جهاز يمكن الوصول إليه عبر SSH) حيث تم تسجيل الدخول إلى Messages.app.
• تريد جزءًا متحركًا أقل — لا خادم BlueBubbles منفصل، ولا نقطة نهاية REST للمصادقة، ولا توصيل Webhook. ملف CLI تنفيذي واحد بدلًا من خادم + تطبيق عميل + مساعد.
• أنت تستخدم إصدار macOS / imsg مدعومًا حيث يعرض فحص API الخاص available: true.

​

ما الذي يفعله imsg

• تأتي القراءات من ~/Library/Messages/chat.db باستخدام مقبض SQLite للقراءة فقط.
• تأتي الرسائل الواردة الحية من imsg watch / watch.subscribe، الذي يتتبع أحداث نظام الملفات في chat.db مع رجوع احتياطي إلى الاستقصاء.
• تستخدم عمليات الإرسال أتمتة Messages.app لإرسال النصوص والملفات العادية.
• تستخدم الإجراءات المتقدمة imsg launch لحقن مساعد imsg في Messages.app. هذا ما يتيح إيصالات القراءة، ومؤشرات الكتابة، والإرسال الغني، والتحرير، والتراجع عن الإرسال، والردود المتسلسلة، وtapbacks، وإدارة المجموعات.
• يمكن لإصدارات Linux فحص نسخة من chat.db، لكنها لا تستطيع الإرسال، أو مراقبة قاعدة بيانات Mac الحية، أو تشغيل Messages.app. بالنسبة إلى iMessage في OpenClaw، شغّل imsg على جهاز Mac الذي تم تسجيل الدخول عليه أو من خلال غلاف SSH إلى ذلك الجهاز.

​

قبل أن تبدأ

1. ثبّت imsg على جهاز Mac الذي يشغّل Messages.app:
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   إذا فشل imsg chats برسالة unable to open database file، أو بإخراج فارغ، أو authorization denied، فامنح وصول القرص الكامل للطرفية، أو المحرر، أو عملية Node، أو خدمة Gateway، أو عملية SSH الأصلية التي تطلق imsg، ثم أعد فتح تلك العملية الأصلية.
2. تحقق من أسطح القراءة والمراقبة والإرسال وRPC قبل تغيير إعداد OpenClaw:
   imsg chats --limit 10 --json | jq -s
   imsg history --chat-id 42 --limit 10 --attachments --json | jq -s
   imsg watch --chat-id 42 --reactions --json
   imsg send --chat-id 42 --text "OpenClaw imsg test"
   imsg rpc --help
   
   استبدل 42 بمعرّف محادثة حقيقي من imsg chats. يتطلب الإرسال إذن Automation لـ Messages.app. إذا كان OpenClaw سيعمل عبر SSH، فشغّل هذه الأوامر من خلال غلاف SSH نفسه أو سياق المستخدم نفسه الذي سيستخدمه OpenClaw. إذا نجحت القراءات/الفحوصات لكن فشل الإرسال مع AppleEvents -1743، فتحقق مما إذا كان إذن Automation قد وصل إلى /usr/libexec/sshd-keygen-wrapper؛ راجع فشل إرسال غلاف SSH مع AppleEvents -1743.
3. فعّل جسر API الخاص عندما تحتاج إلى الإجراءات المتقدمة:
   imsg launch
   imsg status --json
   
   يتطلب imsg launch تعطيل SIP. تعمل وظائف الإرسال الأساسي والسجل والمراقبة بدون imsg launch؛ أما الإجراءات المتقدمة فلا تعمل بدونه.
4. بعد إضافة إعداد channels.imessage مفعّل، تحقق من الجسر عبر OpenClaw:
   openclaw channels status --probe
   
   تحتاج إلى imessage.privateApi.available: true. إذا أبلغ عن false، فأصلح ذلك أولًا — راجع اكتشاف الإمكانات. لا يفحص channels status --probe إلا الحسابات المهيأة والمفعّلة.
5. خذ لقطة من إعدادك:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

ترجمة الإعداد

​

مطب سجل المجموعات

1. قائمة سماح المرسل / هدف المحادثة (channels.imessage.groupAllowFrom) — يتحقق منها isAllowedIMessageSender. تطابق الرسائل الواردة حسب معرف المرسل أو chat_guid أو chat_identifier أو chat_id. لها بنية BlueBubbles نفسها.
2. سجل المجموعات (channels.imessage.groups) — يتحقق منه resolveChannelGroupPolicy من inbound-processing.ts:199. مع groupPolicy: "allowlist"، تتطلب هذه البوابة أحد الأمرين:
   • إدخال بدل groups: { "*": { ... } } (يضبط allowAll = true)، أو
   • إدخالاً صريحاً لكل chat_id تحت groups.

• تحذير بدء تشغيل warn مرة واحدة لكل حساب عندما يكون groupPolicy: "allowlist" مضبوطاً لكن channels.imessage.groups فارغ (لا يوجد بدل "*" ولا إدخالات لكل chat_id)؛ يُطلق قبل وصول أي رسائل.
• تحذير warn مرة واحدة لكل chat_id في أول مرة تُسقط فيها مجموعة محددة وقت التشغيل، مع تسمية chat_id والمفتاح الدقيق المطلوب إضافته إلى groups للسماح بها.

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123", "chat_guid:any;-;..."],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

​

خطوة بخطوة

1. أضف كتلة iMessage إلى جانب كتلة BlueBubbles الحالية. أبقها معطلة ما دام Gateway لا يزال يوجّه حركة BlueBubbles:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false,
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // copy from bluebubbles.groups — silently drops groups if missing, see "Group registry footgun" above
         actions: {
           reactions: true,
           edit: true,
           unsend: true,
           reply: true,
           sendWithEffect: true,
           sendAttachment: true,
         },
       },
     },
   }
   
2. اختبر قبل أن تصبح حركة الرسائل مهمة — أوقف Gateway، وفعّل كتلة iMessage مؤقتًا، وتأكد من أن iMessage يبلّغ عن حالة سليمة من CLI:
   openclaw gateway stop
   # edit config: channels.imessage.enabled = true
   openclaw channels status --probe --channel imessage   # expect imessage.privateApi.available: true
   
   لا يفحص channels status --probe إلا الحسابات المضبوطة والمفعلة. لا تُعد تشغيل Gateway مع تفعيل كل من BlueBubbles وiMessage إلا إذا كنت تقصد تشغيل مراقبي القناتين معًا. إذا لم تكن ستنتقل فورًا، فأعد ضبط channels.imessage.enabled إلى false قبل إعادة تشغيل Gateway. استخدم أوامر imsg المباشرة في قبل أن تبدأ للتحقق من Mac قبل تفعيل حركة OpenClaw.
3. انتقل. بعد أن يبلّغ حساب iMessage المفعّل عن حالة سليمة، أزل إعدادات BlueBubbles وأبق iMessage مفعّلًا:
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   أعد تشغيل Gateway. ستتدفق حركة iMessage الواردة الآن عبر Plugin المضمّن.
4. تحقق من الرسائل المباشرة. أرسل إلى الوكيل رسالة مباشرة؛ وتأكد من وصول الرد.
5. تحقق من المجموعات بشكل منفصل. الرسائل المباشرة والمجموعات تسلك مسارات برمجية مختلفة — نجاح الرسائل المباشرة لا يثبت أن المجموعات موجّهة. أرسل إلى الوكيل رسالة في دردشة جماعية مقترنة وتأكد من وصول الرد. إذا صمتت المجموعة (لا رد من الوكيل، ولا خطأ)، فتحقق من سجل Gateway بحثًا عن imessage: dropping group message from chat_id=<id> أو سطر بدء التشغيل imessage: groupPolicy="allowlist" but channels.imessage.groups is empty — كلاهما يظهر عند مستوى السجل الافتراضي. إذا ظهر أي منهما، فكتلة groups مفقودة أو فارغة — راجع “فخ سجل المجموعات” أعلاه.
6. تحقق من سطح الإجراءات — من رسالة مباشرة مقترنة، اطلب من الوكيل إضافة تفاعل، أو تعديل رسالة، أو إلغاء إرسالها، أو الرد عليها، أو إرسال صورة، و(في مجموعة) إعادة تسمية المجموعة / إضافة مشارك أو إزالته. يجب أن يظهر كل إجراء أصليًا في Messages.app. إذا ألقى أي إجراء الخطأ “iMessage <action> requires the imsg private API bridge”، فشغّل imsg launch مرة أخرى وحدّث channels status --probe.
7. أزل خادم BlueBubbles وإعداداته بعد التحقق من رسائل iMessage المباشرة والمجموعات والإجراءات. لن يستخدم OpenClaw channels.bluebubbles.

​

تكافؤ الإجراءات بنظرة سريعة

​

الاقتران والجلسات وارتباطات ACP

• موافقات الاقتران تنتقل حسب المعرف. لا تحتاج إلى إعادة الموافقة على المرسلين المعروفين — يتعرف channels.imessage.allowFrom على سلاسل +15555550123 / user@example.com نفسها التي استخدمها BlueBubbles.
• الجلسات تبقى محددة النطاق لكل وكيل + دردشة. تُدمج الرسائل المباشرة في الجلسة الرئيسية للوكيل وفق الإعداد الافتراضي session.dmScope=main؛ وتبقى جلسات المجموعات معزولة لكل chat_id. تختلف مفاتيح الجلسات (agent:<id>:imessage:group:<chat_id> مقابل مكافئ BlueBubbles) — لا ينتقل سجل المحادثات القديم ضمن مفاتيح جلسات BlueBubbles إلى جلسات iMessage.
• ارتباطات ACP التي تشير إلى match.channel: "bluebubbles" يجب تحديثها إلى "imessage". أشكال match.peer.id (chat_id:، وchat_guid:، وchat_identifier:، والمعرف المجرد) متطابقة.

​

لا قناة رجوع

​

ذات صلة

• إزالة BlueBubbles ومسار imsg iMessage — إعلان قصير وملخص للمشغّلين.
• iMessage — مرجع قناة iMessage الكامل، بما في ذلك إعداد imsg launch واكتشاف القدرات.
• /channels/bluebubbles — عنوان URL قديم يعيد التوجيه إلى دليل الترحيل هذا.
• الاقتران — مصادقة الرسائل المباشرة وتدفق الاقتران.
• توجيه القنوات — كيف يختار Gateway قناة للردود الصادرة.