BlueBubbles

Status: Plugin قدیمیِ همراه‌شده که از طریق HTTP با سرور BlueBubbles در macOS صحبت می‌کند. راه‌اندازی‌های موجود BlueBubbles همچنان کار می‌کنند، اما استقرارهای جدید OpenClaw iMessage باید وقتی الزامات Plugin بومی iMessage با میزبان شما سازگار است، آن را ترجیح دهند.

# نمای کلی

• از طریق اپلیکیشن کمکی BlueBubbles روی macOS اجرا می‌شود (bluebubbles.app).
• جایگزین قدیمی برای نصب‌هایی که از قبل به شناسه‌های کانال BlueBubbles، وضعیت Webhook، اهداف گروهی، تحویل Cron، یا مسیریابی workspace متکی هستند.
• توصیه‌شده/آزمایش‌شده: macOS Sequoia (15). macOS Tahoe (26) کار می‌کند؛ ویرایش در حال حاضر روی Tahoe خراب است، و به‌روزرسانی‌های آیکن گروه ممکن است موفقیت گزارش کنند اما همگام‌سازی نشوند.
• OpenClaw از طریق REST API آن با آن صحبت می‌کند (GET /api/v1/ping، POST /message/text، POST /chat/:id/*).
• پیام‌های ورودی از طریق Webhookها می‌رسند؛ پاسخ‌های خروجی، نشانگرهای تایپ، رسیدهای خواندن، و tapbackها فراخوانی‌های REST هستند.
• پیوست‌ها و برچسب‌ها به‌عنوان رسانه ورودی دریافت می‌شوند (و هرجا ممکن باشد به agent نمایش داده می‌شوند).
• پاسخ‌های Auto-TTS که صدای MP3 یا CAF تولید می‌کنند، به‌جای پیوست فایل ساده، به‌صورت حباب‌های یادداشت صوتی iMessage تحویل داده می‌شوند.
• جفت‌سازی/allowlist مانند کانال‌های دیگر کار می‌کند (/channels/pairing و غیره) با channels.bluebubbles.allowFrom + کدهای جفت‌سازی.
• واکنش‌ها درست مانند Slack/Telegram به‌عنوان رویدادهای سیستمی نمایش داده می‌شوند تا agentها بتوانند پیش از پاسخ دادن به آن‌ها «اشاره» کنند.
• قابلیت‌های پیشرفته: ویرایش، لغو ارسال، thread کردن پاسخ، افکت‌های پیام، مدیریت گروه.

# شروع سریع

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

# زنده نگه داشتن Messages.app (راه‌اندازی‌های VM / بدون نمایشگر)

برخی راه‌اندازی‌های macOS VM / همیشه روشن ممکن است باعث شوند Messages.app «idle» شود (رویدادهای ورودی تا زمان باز شدن/foreground شدن اپلیکیشن متوقف می‌شوند). یک راه‌حل ساده این است که با استفاده از AppleScript + LaunchAgent هر ۵ دقیقه یک‌بار Messages را poke کنید.

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

wizard موارد زیر را درخواست می‌کند:

همچنین می‌توانید BlueBubbles را از طریق CLI اضافه کنید:

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

# کنترل دسترسی (DMها + گروه‌ها)

# غنی‌سازی نام مخاطب (macOS، اختیاری)

Webhookهای گروهی BlueBubbles اغلب فقط نشانی‌های خام شرکت‌کنندگان را شامل می‌شوند. اگر می‌خواهید context مربوط به GroupMembers به‌جای آن نام‌های مخاطبان محلی را نشان دهد، می‌توانید در macOS غنی‌سازی از Contacts محلی را فعال کنید:

• channels.bluebubbles.enrichGroupParticipantsFromContacts = true lookup را فعال می‌کند. پیش‌فرض: false.
• lookupها فقط پس از آن اجرا می‌شوند که دسترسی گروه، مجوز فرمان، و mention gating اجازه عبور پیام را داده باشند.
• فقط شرکت‌کنندگان تلفنی بدون نام غنی‌سازی می‌شوند.
• وقتی تطابق محلی پیدا نشود، شماره‌های تلفن خام به‌عنوان fallback باقی می‌مانند.

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

# Mention gating (گروه‌ها)

BlueBubbles از mention gating برای چت‌های گروهی پشتیبانی می‌کند و با رفتار iMessage/WhatsApp همخوان است:

• از agents.list[].groupChat.mentionPatterns (یا messages.groupChat.mentionPatterns) برای تشخیص mentionها استفاده می‌کند.
• وقتی requireMention برای یک گروه فعال باشد، agent فقط هنگام mention شدن پاسخ می‌دهد.
• فرمان‌های کنترلی از فرستندگان مجاز mention gating را دور می‌زنند.

پیکربندی برای هر گروه:

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

# Command gating

• فرمان‌های کنترلی (مثلاً /config، /model) به مجوز نیاز دارند.
• از allowFrom و groupAllowFrom برای تعیین مجوز فرمان استفاده می‌کند.
• فرستندگان مجاز می‌توانند فرمان‌های کنترلی را حتی بدون mention کردن در گروه‌ها اجرا کنند.

# system prompt برای هر گروه

هر ورودی زیر channels.bluebubbles.groups.* یک رشته اختیاری systemPrompt می‌پذیرد. مقدار آن در هر turn که پیامی را در آن گروه پردازش می‌کند، به system prompt مربوط به agent تزریق می‌شود، بنابراین می‌توانید بدون ویرایش promptهای agent، persona یا قواعد رفتاری مخصوص هر گروه را تنظیم کنید:

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

کلید با هر چیزی که BlueBubbles به‌عنوان chatGuid / chatIdentifier / chatId عددی برای گروه گزارش می‌کند مطابقت دارد، و یک ورودی wildcard با "*" پیش‌فرضی برای هر گروه بدون تطابق دقیق فراهم می‌کند (همان الگویی که توسط requireMention و سیاست‌های ابزار برای هر گروه استفاده می‌شود). تطابق‌های دقیق همیشه بر wildcard اولویت دارند. DMها این فیلد را نادیده می‌گیرند؛ به‌جای آن از سفارشی‌سازی prompt در سطح agent یا حساب استفاده کنید.

# مثال عملی: پاسخ‌های thread شده و واکنش‌های tapback (API خصوصی)

با فعال بودن API خصوصی BlueBubbles، پیام‌های ورودی با شناسه‌های کوتاه پیام می‌رسند (برای مثال [[reply_to:5]]) و agent می‌تواند action=reply را فراخوانی کند تا وارد thread یک پیام مشخص شود یا action=react را برای گذاشتن یک tapback فراخوانی کند. یک systemPrompt برای هر گروه راهی قابل اعتماد برای نگه داشتن agent روی انتخاب ابزار درست است:

{
  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 و پاسخ‌های thread شده هر دو به API خصوصی BlueBubbles نیاز دارند؛ برای سازوکارهای زیرین، اقدام‌های پیشرفته و شناسه‌های پیام را ببینید.

# اتصال‌های گفت‌وگوی ACP

چت‌های BlueBubbles می‌توانند بدون تغییر لایه انتقال به workspaceهای پایدار ACP تبدیل شوند.

جریان سریع operator:

• داخل DM یا چت گروهی مجاز، /acp spawn codex --bind here را اجرا کنید.
• پیام‌های آینده در همان گفت‌وگوی BlueBubbles به نشست ACP ایجادشده route می‌شوند.
• /new و /reset همان نشست ACP متصل را درجا reset می‌کنند.
• /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 در payloadهای ورودی

برای متغیرهای الگو، پیکربندی را ببینید.

# ادغام DMهای split-send (فرمان + URL در یک ترکیب)

وقتی کاربر در iMessage یک فرمان و یک URL را با هم تایپ می‌کند - مثلاً Dump https://example.com/article - Apple ارسال را به دو تحویل Webhook جداگانه تقسیم می‌کند:

1. یک پیام متنی ("Dump").
2. یک حباب پیش‌نمایش URL ("https://...") با تصاویر پیش‌نمایش OG به‌عنوان پیوست.

در بیشتر راه‌اندازی‌ها، دو Webhook با فاصلهٔ حدود 0.8 تا 2.0 ثانیه به OpenClaw می‌رسند. بدون ادغام، عامل در نوبت 1 فقط فرمان را دریافت می‌کند، پاسخ می‌دهد (اغلب «URL را برایم بفرست»)، و URL را فقط در نوبت 2 می‌بیند - در آن نقطه زمینهٔ فرمان از قبل از دست رفته است.

channels.bluebubbles.coalesceSameSenderDms یک DM را وارد ادغام Webhookهای متوالی از همان فرستنده در یک نوبت عامل می‌کند. گفت‌وگوهای گروهی همچنان بر اساس هر پیام کلیدگذاری می‌شوند تا ساختار نوبت چندکاربره حفظ شود.

{
  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,
      },
    },
  },
}

# سناریوها و آنچه عامل می‌بیند

# عیب‌یابی ادغام split-send

اگر پرچم روشن است و split-sendها همچنان به‌صورت دو نوبت می‌رسند، هر لایه را بررسی کنید:

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

وقتی همان شناسه روی Mac هم چت iMessage و هم چت SMS داشته باشد (برای مثال شماره تلفنی که در iMessage ثبت شده اما پیام‌های جایگزین حباب سبز را هم دریافت کرده است)، OpenClaw چت iMessage را ترجیح می‌دهد و هرگز بی‌صدا به SMS تنزل نمی‌دهد. برای اجبار به استفاده از چت SMS، از پیشوند هدف صریح sms: استفاده کنید (برای مثال sms:+15555550123). شناسه‌هایی که چت iMessage منطبق ندارند همچنان از طریق هر چتی که BlueBubbles گزارش می‌کند ارسال می‌شوند.

# امنیت

• درخواست‌های Webhook با مقایسه پارامترهای پرس‌وجوی guid/password یا سرآیندها با channels.bluebubbles.password احراز هویت می‌شوند.
• گذرواژه API و نقطه پایانی Webhook را محرمانه نگه دارید (با آن‌ها مانند اعتبارنامه برخورد کنید).
• برای احراز هویت Webhook در BlueBubbles هیچ میان‌بری برای localhost وجود ندارد. اگر ترافیک Webhook را پراکسی می‌کنید، گذرواژه BlueBubbles را از ابتدا تا انتهای درخواست نگه دارید. gateway.trustedProxies در اینجا جایگزین channels.bluebubbles.password نمی‌شود. امنیت Gateway را ببینید.
• اگر سرور BlueBubbles را بیرون از LAN خود در معرض دسترس قرار می‌دهید، HTTPS و قوانین دیواره آتش را فعال کنید.

# عیب‌یابی

• اگر رویدادهای تایپ/خواندن از کار افتادند، لاگ‌های Webhook در BlueBubbles را بررسی کنید و مطمئن شوید مسیر Gateway با channels.bluebubbles.webhookPath منطبق است.
• کدهای جفت‌سازی پس از یک ساعت منقضی می‌شوند؛ از openclaw pairing list bluebubbles و openclaw pairing approve bluebubbles <code> استفاده کنید.
• واکنش‌ها به API خصوصی BlueBubbles (POST /api/v1/message/react) نیاز دارند؛ مطمئن شوید نسخه سرور آن را ارائه می‌کند.
• ویرایش/لغو ارسال به macOS 13+ و نسخه سازگار سرور BlueBubbles نیاز دارد. در macOS 26 (Tahoe)، ویرایش فعلا به‌دلیل تغییرات 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 را ببینید.

# مرتبط

• مسیریابی کانال - مسیریابی نشست برای پیام‌ها
• نمای کلی کانال‌ها - همه کانال‌های پشتیبانی‌شده
• گروه‌ها - رفتار چت گروهی و دروازه‌گذاری ذکر نام
• جفت‌سازی - احراز هویت پیام مستقیم و جریان جفت‌سازی
• امنیت - مدل دسترسی و مقاوم‌سازی