BlueBubbles

الحالة: Plugin قديم مضمّن يتواصل مع خادم BlueBubbles على macOS عبر HTTP. تستمر إعدادات BlueBubbles الحالية في العمل، لكن عمليات نشر OpenClaw iMessage الجديدة يجب أن تفضّل Plugin iMessage الأصلي عندما تناسب متطلباته مضيفك.

# نظرة عامة

• يعمل على macOS عبر تطبيق BlueBubbles المساعد (bluebubbles.app).
• بديل قديم للمنشآت التي تعتمد بالفعل على معرّفات قناة BlueBubbles، أو حالة Webhook، أو أهداف المجموعات، أو تسليم cron، أو توجيه مساحة العمل.
• موصى به/مختبر: macOS Sequoia (15). يعمل macOS Tahoe (26)؛ التحرير معطّل حاليًا على Tahoe، وقد تُبلغ تحديثات أيقونة المجموعة عن النجاح لكنها لا تتزامن.
• يتواصل OpenClaw معه عبر REST API الخاصة به (GET /api/v1/ping، POST /message/text، POST /chat/:id/*).
• تصل الرسائل الواردة عبر webhooks؛ أما الردود الصادرة، ومؤشرات الكتابة، وإيصالات القراءة، وtapbacks فهي استدعاءات REST.
• تُستوعب المرفقات والملصقات كوسائط واردة (وتُعرض للوكيل عند الإمكان).
• تُسلَّم ردود Auto-TTS التي تُنشئ صوت MP3 أو CAF كفقاعات مذكرة صوتية في iMessage بدلًا من مرفقات ملفات عادية.
• تعمل الاقتران/قائمة السماح بالطريقة نفسها مثل القنوات الأخرى (/channels/pairing وما إلى ذلك) مع channels.bluebubbles.allowFrom + رموز الاقتران.
• تُعرض التفاعلات كأحداث نظام تمامًا مثل Slack/Telegram حتى يتمكن الوكلاء من "ذكرها" قبل الرد.
• الميزات المتقدمة: التحرير، إلغاء الإرسال، ترابط الردود، تأثيرات الرسائل، إدارة المجموعات.

# البدء السريع

{
  channels: {
    bluebubbles: {
      enabled: true,
      serverUrl: "http://192.168.1.100:1234",
      password: "example-password",
      webhookPath: "/bluebubbles-webhook",
    },
  },
}

# إبقاء Messages.app نشطًا (إعدادات VM / بلا واجهة)

قد تنتهي بعض إعدادات macOS VM / الدائمة التشغيل إلى دخول Messages.app في حالة "خمول" (تتوقف الأحداث الواردة حتى يُفتح التطبيق/يُجلب إلى المقدمة). الحل البسيط هو تنبيه Messages كل 5 دقائق باستخدام AppleScript + LaunchAgent.

try
  tell application "Messages"
    if not running then
      launch
    end if

    -- Touch the scripting interface to keep the process responsive.
    set _chatCount to (count of chats)
  end tell
on error
  -- Ignore transient failures (first-run prompts, locked session, etc).
end try

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.user.poke-messages</string>

    <key>ProgramArguments</key>
    <array>
      <string>/bin/bash</string>
      <string>-lc</string>
      <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>StartInterval</key>
    <integer>300</integer>

    <key>StandardOutPath</key>
    <string>/tmp/poke-messages.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/poke-messages.err</string>
  </dict>
</plist>

launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist

# الإعداد الأولي

يتوفر BlueBubbles في الإعداد الأولي التفاعلي:

openclaw onboard

يطالبك المعالج بما يلي:

يمكنك أيضًا إضافة BlueBubbles عبر CLI:

openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>

# التحكم في الوصول (الرسائل المباشرة + المجموعات)

# إثراء أسماء جهات الاتصال (macOS، اختياري)

غالبًا ما تتضمن webhooks الخاصة بمجموعات BlueBubbles عناوين المشاركين الخام فقط. إذا كنت تريد أن يعرض سياق GroupMembers أسماء جهات الاتصال المحلية بدلًا من ذلك، فيمكنك الاشتراك في إثراء جهات الاتصال المحلية على macOS:

• يفعّل channels.bluebubbles.enrichGroupParticipantsFromContacts = true البحث. الافتراضي: false.
• لا تعمل عمليات البحث إلا بعد أن تسمح صلاحية الوصول إلى المجموعة، وتفويض الأوامر، وبوابة الذكر بمرور الرسالة.
• يُثري المشاركون ذوو أرقام الهاتف غير المسماة فقط.
• تبقى أرقام الهاتف الخام كبديل احتياطي عند عدم العثور على تطابق محلي.

{
  channels: {
    bluebubbles: {
      enrichGroupParticipantsFromContacts: true,
    },
  },
}

# بوابة الذكر (المجموعات)

يدعم BlueBubbles بوابة الذكر لدردشات المجموعات، بما يطابق سلوك iMessage/WhatsApp:

• يستخدم agents.list[].groupChat.mentionPatterns (أو messages.groupChat.mentionPatterns) لاكتشاف الإشارات.
• عند تفعيل requireMention لمجموعة، لا يرد الوكيل إلا عند ذكره.
• تتجاوز أوامر التحكم من المرسلين المصرح لهم بوابة الذكر.

إعداد كل مجموعة:

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // default for all groups
        "iMessage;-;chat123": { requireMention: false }, // override for specific group
      },
    },
  },
}

# بوابة الأوامر

• تتطلب أوامر التحكم (مثل /config و/model) تفويضًا.
• يستخدم allowFrom وgroupAllowFrom لتحديد تفويض الأوامر.
• يمكن للمرسلين المصرح لهم تشغيل أوامر التحكم حتى من دون ذكر في المجموعات.

# موجّه النظام لكل مجموعة

يقبل كل إدخال ضمن channels.bluebubbles.groups.* سلسلة systemPrompt اختيارية. تُحقن القيمة في موجّه نظام الوكيل في كل دورة تتعامل مع رسالة في تلك المجموعة، بحيث يمكنك ضبط شخصية أو قواعد سلوكية لكل مجموعة من دون تعديل موجّهات الوكيل:

{
  channels: {
    bluebubbles: {
      groups: {
        "iMessage;-;chat123": {
          systemPrompt: "Keep responses under 3 sentences. Mirror the group's casual tone.",
        },
      },
    },
  },
}

يطابق المفتاح ما يبلّغ عنه BlueBubbles كـ chatGuid / chatIdentifier / chatId رقمي للمجموعة، ويوفر إدخال حرف البدل "*" إعدادًا افتراضيًا لكل مجموعة من دون تطابق دقيق (النمط نفسه المستخدم بواسطة requireMention وسياسات الأدوات لكل مجموعة). تنتصر المطابقات الدقيقة دائمًا على حرف البدل. تتجاهل الرسائل المباشرة هذا الحقل؛ استخدم تخصيص الموجّه على مستوى الوكيل أو الحساب بدلًا من ذلك.

# مثال عملي: الردود المترابطة وتفاعلات tapback (API خاصة)

مع تفعيل API الخاصة في BlueBubbles، تصل الرسائل الواردة مع معرّفات رسائل قصيرة (مثل [[reply_to:5]]) ويمكن للوكيل استدعاء action=reply للترابط مع رسالة محددة أو action=react لإسقاط tapback. تُعد systemPrompt لكل مجموعة طريقة موثوقة لإبقاء الوكيل يختار الأداة الصحيحة:

{
  channels: {
    bluebubbles: {
      groups: {
        "iMessage;+;chat-family": {
          systemPrompt: "When replying in this group, always call action=reply with the [[reply_to:N]] messageId from context so your response threads under the triggering message. Never send a new unlinked message. For short acknowledgements ('ok', 'got it', 'on it'), use action=react with an appropriate tapback emoji (❤️, 👍, 😂, ‼️, ❓) instead of sending a text reply.",
        },
      },
    },
  },
}

تتطلب كل من تفاعلات tapback والردود المترابطة API الخاصة في BlueBubbles؛ راجع الإجراءات المتقدمة ومعرّفات الرسائل للآليات الأساسية.

# ارتباطات محادثات ACP

يمكن تحويل دردشات BlueBubbles إلى مساحات عمل ACP مستمرة من دون تغيير طبقة النقل.

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

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

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

يمكن لـ match.peer.id استخدام أي صيغة هدف BlueBubbles مدعومة:

• معرّف DM مُطبّع مثل +15555550123 أو [email protected]
• chat_id:<id>
• chat_guid:<guid>
• chat_identifier:<identifier>

لربط المجموعات بشكل مستقر، فضّل chat_id:* أو chat_identifier:*.

مثال:

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "bluebubbles",
        accountId: "default",
        peer: { kind: "dm", id: "+15555550123" },
      },
      acp: { label: "codex-imessage" },
    },
  ],
}

راجع وكلاء ACP لمعرفة سلوك ربط ACP المشترك.

# مؤشرات الكتابة + إيصالات القراءة

• مؤشرات الكتابة: تُرسل تلقائيًا قبل إنشاء الرد وأثناءه.
• إيصالات القراءة: يتحكم بها channels.bluebubbles.sendReadReceipts (الافتراضي: true).
• مؤشرات الكتابة: يرسل OpenClaw أحداث بدء الكتابة؛ ويمسح BlueBubbles حالة الكتابة تلقائيًا عند الإرسال أو انتهاء المهلة (الإيقاف اليدوي عبر DELETE غير موثوق).

{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // disable read receipts
    },
  },
}

# إجراءات متقدمة

يدعم BlueBubbles إجراءات رسائل متقدمة عند تفعيلها في الإعدادات:

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // tapbacks (default: true)
        edit: true, // edit sent messages (macOS 13+, broken on macOS 26 Tahoe)
        unsend: true, // unsend messages (macOS 13+)
        reply: true, // reply threading by message GUID
        sendWithEffect: true, // message effects (slam, loud, etc.)
        renameGroup: true, // rename group chats
        setGroupIcon: true, // set group chat icon/photo (flaky on macOS 26 Tahoe)
        addParticipant: true, // add participants to groups
        removeParticipant: true, // remove participants from groups
        leaveGroup: true, // leave group chats
        sendAttachment: true, // send attachments/media
      },
    },
  },
}

# معرّفات الرسائل (قصيرة مقابل كاملة)

قد يعرض OpenClaw معرّفات رسائل قصيرة (مثل 1 و2) لتوفير الرموز.

• يمكن أن تكون MessageSid / ReplyToId معرّفات قصيرة.
• تحتوي MessageSidFull / ReplyToIdFull على المعرّفات الكاملة للمزوّد.
• المعرّفات القصيرة موجودة في الذاكرة؛ وقد تنتهي صلاحيتها عند إعادة التشغيل أو إخلاء ذاكرة التخزين المؤقت.
• تقبل الإجراءات messageId قصيرًا أو كاملًا، لكن المعرّفات القصيرة ستُرجع خطأ إذا لم تعد متاحة.

استخدم المعرّفات الكاملة للأتمتة والتخزين الدائمين:

• القوالب: {{MessageSidFull}}، {{ReplyToIdFull}}
• السياق: MessageSidFull / ReplyToIdFull في الحمولات الواردة

راجع الإعدادات لمتغيرات القوالب.

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

عندما يكتب مستخدم أمرًا وURL معًا في iMessage - مثل Dump https://example.com/article - تقسم Apple الإرسال إلى تسليمين منفصلين عبر Webhook:

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

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

يُدخل channels.bluebubbles.coalesceSameSenderDms رسالة DM في دمج Webhooks المتتالية من المرسل نفسه في دور وكيل واحد. تستمر الدردشات الجماعية في استخدام مفتاح لكل رسالة للحفاظ على بنية الأدوار متعددة المستخدمين.

{
  channels: {
    bluebubbles: {
      coalesceSameSenderDms: true, // opt in (default: false)
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 2500 ms works for most setups; raise to 4000 ms if your Mac is slow
        // or under memory pressure (observed gap can stretch past 2 s then).
        bluebubbles: 2500,
      },
    },
  },
}

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

# استكشاف أخطاء دمج الإرسال المقسّم وإصلاحها

إذا كانت العلامة مفعلة وما زالت الإرسالات المقسّمة تصل كدورين، فتحقق من كل طبقة:

grep coalesceSameSenderDms ~/.openclaw/openclaw.json

grep -E "Dispatching event to webhook" main.log | tail -20

# بث الكتل

تحكم فيما إذا كانت الردود تُرسل كرسالة واحدة أو تُبث في كتل:

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // enable block streaming (off by default)
    },
  },
}

# الوسائط + الحدود

• تُنزّل المرفقات الواردة وتُخزن في ذاكرة التخزين المؤقت للوسائط.
• حد الوسائط عبر channels.bluebubbles.mediaMaxMb للوسائط الواردة والصادرة (الافتراضي: 8 MB).
• يُقسّم النص الصادر إلى channels.bluebubbles.textChunkLimit (الافتراضي: 4000 حرف).

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

الإعدادات الكاملة: الإعدادات

الخيارات العامة ذات الصلة:

• agents.list[].groupChat.mentionPatterns (أو messages.groupChat.mentionPatterns).
• messages.responsePrefix.

# العنونة / أهداف التسليم

فضّل chat_guid للتوجيه المستقر:

• chat_guid:iMessage;-;+15555550123 (مفضل للمجموعات)
• chat_id:123
• chat_identifier:...
• المعرّفات المباشرة: +15555550123، [email protected]
  • إذا لم يكن لدى المعرّف المباشر دردشة رسائل مباشرة موجودة، فسينشئ OpenClaw واحدة عبر POST /api/v1/chat/new. يتطلب هذا تفعيل BlueBubbles Private API.

# توجيه iMessage مقابل SMS

عندما يكون للمعرّف نفسه دردشة iMessage ودردشة SMS على Mac (على سبيل المثال رقم هاتف مسجّل في iMessage لكنه تلقى أيضاً بدائل الفقاعة الخضراء)، يفضّل OpenClaw دردشة iMessage ولا يخفّض أبداً إلى SMS بصمت. لفرض دردشة SMS، استخدم بادئة هدف صريحة sms: (على سبيل المثال sms:+15555550123). تستمر المعرّفات التي لا تملك دردشة iMessage مطابقة في الإرسال عبر أي دردشة يبلّغ عنها BlueBubbles.

# الأمان

• تتم مصادقة طلبات Webhook بمقارنة معاملات الاستعلام أو الرؤوس guid/password مع channels.bluebubbles.password.
• أبقِ كلمة مرور API ونقطة نهاية Webhook سرّيتين (تعامل معهما كبيانات اعتماد).
• لا يوجد تجاوز للمضيف المحلي لمصادقة BlueBubbles Webhook. إذا كنت تمرّر حركة Webhook عبر وكيل، فأبقِ كلمة مرور BlueBubbles على الطلب من طرف إلى طرف. لا يحل gateway.trustedProxies محل channels.bluebubbles.password هنا. راجع أمان Gateway.
• فعّل HTTPS + قواعد جدار الحماية على خادم BlueBubbles إذا كنت تعرضه خارج شبكتك المحلية.

# استكشاف الأخطاء وإصلاحها

• إذا توقفت أحداث الكتابة/القراءة عن العمل، فتحقق من سجلات BlueBubbles Webhook وتأكد من أن مسار Gateway يطابق channels.bluebubbles.webhookPath.
• تنتهي صلاحية رموز الاقتران بعد ساعة واحدة؛ استخدم openclaw pairing list bluebubbles وopenclaw pairing approve bluebubbles <code>.
• تتطلب التفاعلات BlueBubbles private API (POST /api/v1/message/react)؛ تأكد من أن إصدار الخادم يوفّرها.
• يتطلب التعديل/إلغاء الإرسال macOS 13+ وإصدار خادم BlueBubbles متوافقاً. على macOS 26 (Tahoe)، التعديل معطل حالياً بسبب تغييرات private API.
• قد تكون تحديثات أيقونة المجموعة غير مستقرة على macOS 26 (Tahoe): قد تعيد API نجاحاً لكن الأيقونة الجديدة لا تتم مزامنتها.
• يخفي OpenClaw تلقائياً الإجراءات المعروفة بأنها معطلة بناءً على إصدار macOS في خادم BlueBubbles. إذا ظل التعديل ظاهراً على macOS 26 (Tahoe)، فعطّله يدوياً باستخدام channels.bluebubbles.actions.edit=false.
• تم تفعيل coalesceSameSenderDms لكن الإرسالات المقسّمة (مثل Dump + URL) ما زالت تصل كدورتين: راجع قائمة تحقق استكشاف أخطاء دمج الإرسال المقسّم وإصلاحها - الأسباب الشائعة هي نافذة إزالة ارتداد ضيقة جداً، أو إساءة قراءة الطوابع الزمنية لسجل الجلسة كوقت وصول Webhook، أو إرسال اقتباس رد (الذي يستخدم replyToBody، وليس Webhook ثانياً).
• لمعلومات الحالة/الصحة: openclaw status --all أو openclaw status --deep.

للاطلاع على مرجع عام لسير عمل القنوات، راجع القنوات ودليل Plugins.

# ذات صلة

• توجيه القنوات - توجيه الجلسات للرسائل
• نظرة عامة على القنوات - جميع القنوات المدعومة
• المجموعات - سلوك دردشة المجموعة والتحقق من الإشارات
• الاقتران - مصادقة الرسائل المباشرة وتدفق الاقتران
• الأمان - نموذج الوصول والتقوية