BlueBubbles

Durum: HTTP üzerinden BlueBubbles macOS sunucusuyla konuşan paketli eski Plugin. Mevcut BlueBubbles kurulumları çalışmaya devam eder, ancak yeni OpenClaw iMessage dağıtımları, gereksinimleri ana makinenize uyduğunda yerel iMessage Plugin'ini tercih etmelidir.

# Genel bakış

• BlueBubbles yardımcı uygulaması (bluebubbles.app) üzerinden macOS'ta çalışır.
• Zaten BlueBubbles kanal kimliklerine, webhook durumuna, grup hedeflerine, cron teslimine veya çalışma alanı yönlendirmesine dayanan kurulumlar için eski yedek.
• Önerilen/test edilen: macOS Sequoia (15). macOS Tahoe (26) çalışır; düzenleme şu anda Tahoe'da bozuk ve grup simgesi güncellemeleri başarılı görünebilir ancak eşitlenmeyebilir.
• OpenClaw onunla REST API'si üzerinden konuşur (GET /api/v1/ping, POST /message/text, POST /chat/:id/*).
• Gelen mesajlar webhooks üzerinden gelir; giden yanıtlar, yazıyor göstergeleri, okundu bilgileri ve tapback'ler REST çağrılarıdır.
• Ekler ve çıkartmalar gelen medya olarak alınır (ve mümkün olduğunda ajana gösterilir).
• MP3 veya CAF ses sentezleyen otomatik TTS yanıtları, düz dosya ekleri yerine iMessage sesli not baloncukları olarak teslim edilir.
• Eşleştirme/izin listesi diğer kanallarla aynı şekilde çalışır (/channels/pairing vb.) ve channels.bluebubbles.allowFrom + eşleştirme kodlarını kullanır.
• Tepkiler Slack/Telegram'da olduğu gibi sistem olayları olarak gösterilir, böylece ajanlar yanıtlamadan önce bunlardan "bahsedebilir".
• Gelişmiş özellikler: düzenleme, göndermeyi geri alma, yanıt iş parçacıkları, mesaj efektleri, grup yönetimi.

# Hızlı başlangıç

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

# Messages.app'i canlı tutma (VM / başsız kurulumlar)

Bazı macOS VM / her zaman açık kurulumlarda Messages.app "boşta" kalabilir (uygulama açılana/ön plana alınana kadar gelen olaylar durur). Basit bir geçici çözüm, AppleScript + LaunchAgent kullanarak her 5 dakikada bir Messages'ı dürtmektir.

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

# İlk kurulum

BlueBubbles etkileşimli ilk kurulumda kullanılabilir:

openclaw onboard

Sihirbaz şunları ister:

BlueBubbles'ı CLI ile de ekleyebilirsiniz:

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

# Erişim denetimi (DM'ler + gruplar)

# Kişi adı zenginleştirme (macOS, isteğe bağlı)

BlueBubbles grup webhooks'u genellikle yalnızca ham katılımcı adreslerini içerir. GroupMembers bağlamının bunun yerine yerel kişi adlarını göstermesini istiyorsanız macOS'ta yerel Kişiler zenginleştirmesine katılabilirsiniz:

• channels.bluebubbles.enrichGroupParticipantsFromContacts = true aramayı etkinleştirir. Varsayılan: false.
• Aramalar yalnızca grup erişimi, komut yetkilendirmesi ve bahsetme kapısı mesajın geçmesine izin verdikten sonra çalışır.
• Yalnızca adı olmayan telefon katılımcıları zenginleştirilir.
• Yerel eşleşme bulunmadığında ham telefon numaraları yedek olarak kalır.

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

# Bahsetme kapısı (gruplar)

BlueBubbles, iMessage/WhatsApp davranışıyla eşleşen grup sohbetleri için bahsetme kapısını destekler:

• Bahsetmeleri algılamak için agents.list[].groupChat.mentionPatterns (veya messages.groupChat.mentionPatterns) kullanır.
• Bir grup için requireMention etkinleştirildiğinde, ajan yalnızca kendisinden bahsedildiğinde yanıt verir.
• Yetkili gönderenlerden gelen denetim komutları bahsetme kapısını atlar.

Grup başına yapılandırma:

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

# Komut kapısı

• Denetim komutları (örn. /config, /model) yetkilendirme gerektirir.
• Komut yetkilendirmesini belirlemek için allowFrom ve groupAllowFrom kullanır.
• Yetkili gönderenler, gruplarda bahsetmeden bile denetim komutlarını çalıştırabilir.

# Grup başına sistem istemi

channels.bluebubbles.groups.* altındaki her giriş isteğe bağlı bir systemPrompt dizesi kabul eder. Değer, o gruptaki bir mesajı işleyen her turda ajanın sistem istemine enjekte edilir; böylece ajan istemlerini düzenlemeden grup başına persona veya davranış kuralları ayarlayabilirsiniz:

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

Anahtar, BlueBubbles'ın grup için chatGuid / chatIdentifier / sayısal chatId olarak bildirdiği değerle eşleşir ve "*" joker karakter girişi, tam eşleşmesi olmayan her grup için varsayılan sağlar (requireMention ve grup başına araç politikaları tarafından kullanılan aynı kalıp). Tam eşleşmeler her zaman joker karaktere üstün gelir. DM'ler bu alanı yok sayar; bunun yerine ajan düzeyinde veya hesap düzeyinde istem özelleştirmesi kullanın.

# Çalışılmış örnek: iş parçacıklı yanıtlar ve tapback tepkileri (Private API)

BlueBubbles Private API etkinleştirildiğinde, gelen mesajlar kısa mesaj kimlikleriyle gelir (örneğin [[reply_to:5]]) ve ajan belirli bir mesaja iş parçacığı oluşturmak için action=reply veya bir tapback bırakmak için action=react çağırabilir. Grup başına bir systemPrompt, ajanın doğru aracı seçmesini sağlamanın güvenilir bir yoludur:

{
  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 tepkileri ve iş parçacıklı yanıtların ikisi de BlueBubbles Private API gerektirir; temel mekanikler için Gelişmiş eylemler ve Mesaj kimlikleri bölümlerine bakın.

# ACP konuşma bağlamaları

BlueBubbles sohbetleri, taşıma katmanı değiştirilmeden dayanıklı ACP çalışma alanlarına dönüştürülebilir.

Hızlı operatör akışı:

• DM veya izin verilen grup sohbetinin içinde /acp spawn codex --bind here çalıştırın.
• Aynı BlueBubbles konuşmasındaki gelecekteki mesajlar, oluşturulan ACP oturumuna yönlendirilir.
• /new ve /reset, aynı bağlı ACP oturumunu yerinde sıfırlar.
• /acp close, ACP oturumunu kapatır ve bağlamayı kaldırır.

Yapılandırılmış kalıcı bağlamalar da type: "acp" ve match.channel: "bluebubbles" ile üst düzey bindings[] girişleri üzerinden desteklenir.

match.peer.id desteklenen herhangi bir BlueBubbles hedef biçimini kullanabilir:

• +15555550123 veya [email protected] gibi normalize edilmiş DM tanıtıcısı
• chat_id:<id>
• chat_guid:<guid>
• chat_identifier:<identifier>

Kararlı grup bağlamaları için chat_id:* veya chat_identifier:* tercih edin.

Örnek:

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

Paylaşılan ACP bağlama davranışı için ACP aracıları bölümüne bakın.

# Yazıyor göstergeleri + okundu bilgileri

• Yazıyor göstergeleri: Yanıt üretiminden önce ve üretim sırasında otomatik olarak gönderilir.
• Okundu bilgileri: channels.bluebubbles.sendReadReceipts tarafından denetlenir (varsayılan: true).
• Yazıyor göstergeleri: OpenClaw yazıyor başlangıç olayları gönderir; BlueBubbles gönderimde veya zaman aşımında yazıyor durumunu otomatik olarak temizler (DELETE ile elle durdurma güvenilir değildir).

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

# Gelişmiş eylemler

BlueBubbles, yapılandırmada etkinleştirildiğinde gelişmiş ileti eylemlerini destekler:

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

# İleti kimlikleri (kısa ve tam)

OpenClaw, token tasarrufu için kısa ileti kimlikleri (ör. 1, 2) gösterebilir.

• MessageSid / ReplyToId kısa kimlikler olabilir.
• MessageSidFull / ReplyToIdFull sağlayıcı tam kimliklerini içerir.
• Kısa kimlikler bellek içindedir; yeniden başlatmada veya önbellek çıkarımında süreleri dolabilir.
• Eylemler kısa veya tam messageId kabul eder, ancak kısa kimlikler artık kullanılamıyorsa hata verir.

Kalıcı otomasyonlar ve depolama için tam kimlikleri kullanın:

• Şablonlar: {{MessageSidFull}}, {{ReplyToIdFull}}
• Bağlam: gelen yüklerde MessageSidFull / ReplyToIdFull

Şablon değişkenleri için Yapılandırma bölümüne bakın.

# Bölünmüş gönderimli DM'leri birleştirme (tek kompozisyonda komut + URL)

Bir kullanıcı iMessage içinde bir komutu ve URL'yi birlikte yazdığında - ör. Dump https://example.com/article - Apple gönderimi iki ayrı Webhook teslimatına böler:

1. Bir metin iletisi ("Dump").
2. Ek olarak OG önizleme görselleriyle bir URL önizleme balonu ("https://...").

İki Webhook çoğu kurulumda OpenClaw'a yaklaşık 0,8-2,0 sn arayla ulaşır. Birleştirme olmadan aracı 1. turda yalnızca komutu alır, yanıt verir (çoğunlukla "bana URL'yi gönder") ve URL'yi yalnızca 2. turda görür; o noktada komut bağlamı zaten kaybolmuştur.

channels.bluebubbles.coalesceSameSenderDms, bir DM'yi aynı gönderenin ardışık Webhook'larını tek bir aracı turunda birleştirecek şekilde etkinleştirir. Grup sohbetleri, çok kullanıcılı tur yapısı korunsun diye ileti başına anahtarlanmaya devam eder.

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

# Senaryolar ve aracının gördükleri

# Bölünmüş gönderim birleştirme sorun giderme

Bayrak açıksa ve bölünmüş gönderimler yine de iki tur olarak geliyorsa her katmanı denetleyin:

grep coalesceSameSenderDms ~/.openclaw/openclaw.json

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

# Blok akışı

Yanıtların tek bir ileti olarak mı yoksa bloklar halinde akışla mı gönderileceğini denetleyin:

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

# Medya + sınırlar

• Gelen ekler indirilir ve medya önbelleğinde saklanır.
• Gelen ve giden medya için channels.bluebubbles.mediaMaxMb üzerinden medya sınırı (varsayılan: 8 MB).
• Giden metin channels.bluebubbles.textChunkLimit değerine göre parçalara ayrılır (varsayılan: 4000 karakter).

# Yapılandırma referansı

Tam yapılandırma: Yapılandırma

İlgili genel seçenekler:

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

# Adresleme / teslim hedefleri

Kararlı yönlendirme için chat_guid tercih edin:

• chat_guid:iMessage;-;+15555550123 (gruplar için tercih edilir)
• chat_id:123
• chat_identifier:...
• Doğrudan tanıtıcılar: +15555550123, [email protected]
  • Doğrudan bir tanıtıcının mevcut bir DM sohbeti yoksa OpenClaw, POST /api/v1/chat/new aracılığıyla bir tane oluşturur. Bu, BlueBubbles Private API'nin etkin olmasını gerektirir.

# iMessage ve SMS yönlendirmesi

Aynı tanıtıcının Mac'te hem iMessage hem de SMS sohbeti olduğunda (örneğin iMessage'a kayıtlı olan ancak yeşil balonlu yedekleri de almış bir telefon numarası), OpenClaw iMessage sohbetini tercih eder ve asla sessizce SMS'e düşmez. SMS sohbetini zorlamak için açık bir sms: hedef öneki kullanın (örneğin sms:+15555550123). Eşleşen iMessage sohbeti olmayan tanıtıcılar yine BlueBubbles'ın bildirdiği sohbet üzerinden gönderilir.

# Güvenlik

• Webhook isteklerinin kimliği, guid/password sorgu parametreleri veya başlıkları channels.bluebubbles.password ile karşılaştırılarak doğrulanır.
• API parolasını ve webhook uç noktasını gizli tutun (bunları kimlik bilgileri gibi ele alın).
• BlueBubbles webhook kimlik doğrulaması için localhost atlaması yoktur. Webhook trafiğini proxy'liyorsanız BlueBubbles parolasını istekte uçtan uca koruyun. gateway.trustedProxies burada channels.bluebubbles.password yerine geçmez. Bkz. Gateway güvenliği.
• BlueBubbles sunucusunu LAN dışına açıyorsanız HTTPS + güvenlik duvarı kurallarını etkinleştirin.

# Sorun giderme

• Yazma/okundu olayları çalışmayı durdurursa BlueBubbles webhook günlüklerini kontrol edin ve Gateway yolunun channels.bluebubbles.webhookPath ile eşleştiğini doğrulayın.
• Eşleştirme kodlarının süresi bir saat sonra dolar; openclaw pairing list bluebubbles ve openclaw pairing approve bluebubbles <code> kullanın.
• Tepkiler BlueBubbles private API'sini gerektirir (POST /api/v1/message/react); sunucu sürümünün bunu sunduğundan emin olun.
• Düzenleme/göndermeyi geri alma için macOS 13+ ve uyumlu bir BlueBubbles sunucu sürümü gerekir. macOS 26'da (Tahoe), private API değişiklikleri nedeniyle düzenleme şu anda bozuk.
• Grup simgesi güncellemeleri macOS 26'da (Tahoe) güvenilmez olabilir: API başarı döndürebilir ancak yeni simge eşitlenmeyebilir.
• OpenClaw, BlueBubbles sunucusunun macOS sürümüne göre bozuk olduğu bilinen eylemleri otomatik olarak gizler. Düzenleme macOS 26'da (Tahoe) hâlâ görünüyorsa channels.bluebubbles.actions.edit=false ile el ile devre dışı bırakın.
• coalesceSameSenderDms etkin ama bölünmüş gönderimler (örn. Dump + URL) hâlâ iki tur olarak geliyorsa: bölünmüş gönderim birleştirme sorun giderme kontrol listesine bakın - yaygın nedenler çok dar debounce penceresi, oturum günlüğü zaman damgalarının webhook geliş zamanı olarak yanlış okunması veya bir yanıt alıntısı gönderimidir (replyToBody kullanır, ikinci bir webhook değil).
• Durum/sağlık bilgisi için: openclaw status --all veya openclaw status --deep.

Genel kanal iş akışı başvurusu için Kanallar ve Plugins kılavuzuna bakın.

# İlgili

• Kanal Yönlendirme - iletiler için oturum yönlendirmesi
• Kanallara Genel Bakış - desteklenen tüm kanallar
• Gruplar - grup sohbeti davranışı ve bahsetme kapı denetimi
• Eşleştirme - DM kimlik doğrulaması ve eşleştirme akışı
• Güvenlik - erişim modeli ve sıkılaştırma