الانتقال من BlueBubbles

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

• أنت تشغّل بالفعل 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. بالنسبة إلى OpenClaw iMessage، شغّل 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، فامنح Full Disk Access للطرفية أو المحرر أو عملية 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.
3. فعّل جسر API الخاص عندما تحتاج إلى إجراءات متقدمة:
   imsg launch
   imsg status --json
   
   يتطلب imsg launch تعطيل SIP. يعمل الإرسال الأساسي، والسجل، والمراقبة بدون imsg launch؛ أما الإجراءات المتقدمة فلا تعمل.
4. تحقّق من الجسر عبر OpenClaw:
   openclaw channels status --probe
   
   تريد imessage.privateApi.available: true. إذا أبلغ عن false، فأصلح ذلك أولًا — راجع اكتشاف القدرات.
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 الحالية. أبقِ الكتلة القديمة كمصدر نسخ فقط حتى يتم التحقق من المسار الجديد:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false, // turn on after the dry run below
         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 يبلغ عن حالة سليمة:
   openclaw gateway
   openclaw channels status
   openclaw channels status --probe   # expect imessage.privateApi.available: true
   
   بما أن imessage.enabled لا يزال false، فلن يتم توجيه أي حركة iMessage واردة بعد — لكن --probe يختبر الجسر حتى تكتشف مشكلات الأذونات/التثبيت قبل التحويل.
3. حوّل المسار. أزل تهيئة 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:، والمعرّف المجرّد) متطابقة.

​

لا توجد قناة للرجوع

​

ذات صلة

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