BlueBubbles

Status: Plugin warisan bawaan yang berkomunikasi dengan server macOS BlueBubbles melalui HTTP. Setup BlueBubbles yang sudah ada tetap berfungsi, tetapi deployment OpenClaw iMessage baru sebaiknya memilih Plugin iMessage native ketika persyaratannya sesuai dengan host Anda.

# Gambaran umum

• Berjalan di macOS melalui aplikasi helper BlueBubbles (bluebubbles.app).
• Fallback warisan untuk instalasi yang sudah bergantung pada ID channel BlueBubbles, status webhook, target grup, pengiriman cron, atau perutean workspace.
• Direkomendasikan/diuji: macOS Sequoia (15). macOS Tahoe (26) berfungsi; edit saat ini rusak di Tahoe, dan pembaruan ikon grup mungkin melaporkan sukses tetapi tidak tersinkron.
• OpenClaw berkomunikasi dengannya melalui REST API (GET /api/v1/ping, POST /message/text, POST /chat/:id/*).
• Pesan masuk tiba melalui webhook; balasan keluar, indikator mengetik, tanda dibaca, dan tapback adalah panggilan REST.
• Lampiran dan stiker diserap sebagai media masuk (dan ditampilkan ke agent bila memungkinkan).
• Balasan Auto-TTS yang mensintesis audio MP3 atau CAF dikirim sebagai gelembung voice memo iMessage, bukan lampiran file biasa.
• Pairing/allowlist bekerja dengan cara yang sama seperti channel lain (/channels/pairing dll.) dengan channels.bluebubbles.allowFrom + kode pairing.
• Reaksi ditampilkan sebagai event sistem seperti Slack/Telegram sehingga agent dapat "menyebutnya" sebelum membalas.
• Fitur lanjutan: edit, unsend, reply threading, efek pesan, manajemen grup.

# Mulai cepat

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

# Menjaga Messages.app tetap aktif (setup VM / headless)

Beberapa setup VM macOS / selalu aktif dapat membuat Messages.app menjadi "idle" (event masuk berhenti hingga aplikasi dibuka/dibawa ke depan). Solusi sederhana adalah menyentuh Messages setiap 5 menit menggunakan 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

# Onboarding

BlueBubbles tersedia dalam onboarding interaktif:

openclaw onboard

Wizard meminta:

Anda juga dapat menambahkan BlueBubbles melalui CLI:

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

# Kontrol akses (DM + grup)

# Pengayaan nama kontak (macOS, opsional)

Webhook grup BlueBubbles sering kali hanya menyertakan alamat peserta mentah. Jika Anda ingin konteks GroupMembers menampilkan nama kontak lokal, Anda dapat mengaktifkan pengayaan Contacts lokal di macOS:

• channels.bluebubbles.enrichGroupParticipantsFromContacts = true mengaktifkan pencarian. Default: false.
• Pencarian hanya berjalan setelah akses grup, otorisasi perintah, dan mention gating mengizinkan pesan lewat.
• Hanya peserta telepon tanpa nama yang diperkaya.
• Nomor telepon mentah tetap menjadi fallback ketika tidak ada kecocokan lokal yang ditemukan.

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

# Mention gating (grup)

BlueBubbles mendukung mention gating untuk chat grup, sesuai perilaku iMessage/WhatsApp:

• Menggunakan agents.list[].groupChat.mentionPatterns (atau messages.groupChat.mentionPatterns) untuk mendeteksi mention.
• Ketika requireMention diaktifkan untuk sebuah grup, agent hanya merespons saat disebut.
• Perintah kontrol dari pengirim berwenang melewati mention gating.

Konfigurasi per grup:

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

# Command gating

• Perintah kontrol (misalnya, /config, /model) memerlukan otorisasi.
• Menggunakan allowFrom dan groupAllowFrom untuk menentukan otorisasi perintah.
• Pengirim berwenang dapat menjalankan perintah kontrol bahkan tanpa mention di grup.

# System prompt per grup

Setiap entri di bawah channels.bluebubbles.groups.* menerima string systemPrompt opsional. Nilai tersebut disuntikkan ke system prompt agent pada setiap turn yang menangani pesan di grup tersebut, sehingga Anda dapat menetapkan persona atau aturan perilaku per grup tanpa mengedit prompt agent:

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

Kunci cocok dengan apa pun yang dilaporkan BlueBubbles sebagai chatGuid / chatIdentifier / chatId numerik untuk grup tersebut, dan entri wildcard "*" menyediakan default untuk setiap grup tanpa kecocokan persis (pola yang sama digunakan oleh requireMention dan kebijakan tool per grup). Kecocokan persis selalu menang atas wildcard. DM mengabaikan field ini; gunakan kustomisasi prompt tingkat agent atau tingkat akun sebagai gantinya.

# Contoh lengkap: balasan berutas dan reaksi tapback (Private API)

Dengan BlueBubbles Private API diaktifkan, pesan masuk tiba dengan ID pesan pendek (misalnya [[reply_to:5]]) dan agent dapat memanggil action=reply untuk membuat thread ke pesan tertentu atau action=react untuk mengirim tapback. systemPrompt per grup adalah cara yang andal agar agent memilih tool yang tepat:

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

Reaksi tapback dan balasan berutas sama-sama memerlukan BlueBubbles Private API; lihat Tindakan lanjutan dan ID pesan untuk mekanisme dasarnya.

# Binding percakapan ACP

Chat BlueBubbles dapat diubah menjadi workspace ACP yang tahan lama tanpa mengubah lapisan transport.

Alur operator cepat:

• Jalankan /acp spawn codex --bind here di dalam DM atau chat grup yang diizinkan.
• Pesan berikutnya dalam percakapan BlueBubbles yang sama dirutekan ke sesi ACP yang dibuat.
• /new dan /reset mereset sesi ACP terikat yang sama di tempat.
• /acp close menutup sesi ACP dan menghapus binding.

Binding persisten terkonfigurasi juga didukung melalui entri bindings[] tingkat atas dengan type: "acp" dan match.channel: "bluebubbles".

match.peer.id dapat menggunakan bentuk target BlueBubbles apa pun yang didukung:

• handle DM ternormalisasi seperti +15555550123 atau [email protected]
• chat_id:<id>
• chat_guid:<guid>
• chat_identifier:<identifier>

Untuk binding grup yang stabil, utamakan chat_id:* atau chat_identifier:*.

Contoh:

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

Lihat Agen ACP untuk perilaku binding ACP bersama.

# Pengetikan + tanda terima dibaca

• Indikator pengetikan: Dikirim otomatis sebelum dan selama pembuatan respons.
• Tanda terima dibaca: Dikontrol oleh channels.bluebubbles.sendReadReceipts (default: true).
• Indikator pengetikan: OpenClaw mengirim peristiwa mulai mengetik; BlueBubbles menghapus status mengetik secara otomatis saat pesan dikirim atau waktu habis (penghentian manual lewat DELETE tidak andal).

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

# Tindakan lanjutan

BlueBubbles mendukung tindakan pesan lanjutan saat diaktifkan dalam config:

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

# ID pesan (pendek vs lengkap)

OpenClaw dapat menampilkan ID pesan pendek (misalnya, 1, 2) untuk menghemat token.

• MessageSid / ReplyToId dapat berupa ID pendek.
• MessageSidFull / ReplyToIdFull berisi ID lengkap provider.
• ID pendek berada dalam memori; ID tersebut dapat kedaluwarsa saat restart atau eviksi cache.
• Tindakan menerima messageId pendek atau lengkap, tetapi ID pendek akan error jika sudah tidak tersedia.

Gunakan ID lengkap untuk otomatisasi dan penyimpanan yang tahan lama:

• Template: {{MessageSidFull}}, {{ReplyToIdFull}}
• Konteks: MessageSidFull / ReplyToIdFull dalam payload masuk

Lihat Konfigurasi untuk variabel template.

# Menggabungkan DM split-send (perintah + URL dalam satu komposisi)

Saat pengguna mengetik perintah dan URL bersama di iMessage - misalnya Dump https://example.com/article - Apple membagi pengiriman menjadi dua pengiriman webhook terpisah:

1. Pesan teks ("Dump").
2. Balon pratinjau URL ("https://...") dengan gambar pratinjau OG sebagai lampiran.

Kedua webhook tiba di OpenClaw dengan jeda ~0,8-2,0 dtk pada sebagian besar setup. Tanpa penggabungan, agen menerima perintah saja pada giliran 1, membalas (sering kali "kirimkan URL-nya"), dan baru melihat URL pada giliran 2 - ketika konteks perintah sudah hilang.

channels.bluebubbles.coalesceSameSenderDms memilih DM untuk menggabungkan webhook berurutan dari pengirim yang sama ke dalam satu giliran agen. Chat grup tetap dikunci per pesan sehingga struktur giliran multi-pengguna dipertahankan.

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

# Skenario dan apa yang dilihat agen

# Pemecahan masalah penggabungan split-send

Jika flag aktif dan split-send masih tiba sebagai dua giliran, periksa tiap lapisan:

grep coalesceSameSenderDms ~/.openclaw/openclaw.json

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

# Streaming blok

Kontrol apakah respons dikirim sebagai satu pesan atau distream dalam blok:

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

# Media + batas

• Lampiran masuk diunduh dan disimpan di cache media.
• Batas media melalui channels.bluebubbles.mediaMaxMb untuk media masuk dan keluar (default: 8 MB).
• Teks keluar dipecah menjadi chunk ke channels.bluebubbles.textChunkLimit (default: 4000 karakter).

# Referensi konfigurasi

Konfigurasi lengkap: Konfigurasi

Opsi global terkait:

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

# Pengalamatan / target pengiriman

Utamakan chat_guid untuk perutean yang stabil:

• chat_guid:iMessage;-;+15555550123 (diutamakan untuk grup)
• chat_id:123
• chat_identifier:...
• Handle langsung: +15555550123, [email protected]
  • Jika handle langsung tidak memiliki chat DM yang sudah ada, OpenClaw akan membuatnya melalui POST /api/v1/chat/new. Ini memerlukan BlueBubbles Private API diaktifkan.

# Perutean iMessage vs SMS

Saat handle yang sama memiliki chat iMessage dan SMS di Mac (misalnya nomor telepon yang terdaftar di iMessage tetapi juga pernah menerima fallback gelembung hijau), OpenClaw mengutamakan chat iMessage dan tidak pernah diam-diam menurunkan ke SMS. Untuk memaksa chat SMS, gunakan prefiks target sms: eksplisit (misalnya sms:+15555550123). Handle tanpa chat iMessage yang cocok tetap dikirim melalui chat apa pun yang dilaporkan BlueBubbles.

# Keamanan

• Permintaan Webhook diautentikasi dengan membandingkan parameter query atau header guid/password terhadap channels.bluebubbles.password.
• Jaga kata sandi API dan endpoint Webhook tetap rahasia (perlakukan seperti kredensial).
• Tidak ada bypass localhost untuk autentikasi Webhook BlueBubbles. Jika Anda mem-proxy traffic Webhook, pertahankan kata sandi BlueBubbles pada permintaan dari ujung ke ujung. gateway.trustedProxies tidak menggantikan channels.bluebubbles.password di sini. Lihat Keamanan Gateway.
• Aktifkan aturan HTTPS + firewall pada server BlueBubbles jika mengeksposnya di luar LAN Anda.

# Pemecahan masalah

• Jika event mengetik/dibaca berhenti berfungsi, periksa log Webhook BlueBubbles dan verifikasi path Gateway cocok dengan channels.bluebubbles.webhookPath.
• Kode pairing kedaluwarsa setelah satu jam; gunakan openclaw pairing list bluebubbles dan openclaw pairing approve bluebubbles <code>.
• Reaksi memerlukan private API BlueBubbles (POST /api/v1/message/react); pastikan versi server mengeksposnya.
• Edit/unsend memerlukan macOS 13+ dan versi server BlueBubbles yang kompatibel. Di macOS 26 (Tahoe), edit saat ini rusak karena perubahan private API.
• Pembaruan ikon grup bisa tidak stabil di macOS 26 (Tahoe): API dapat mengembalikan sukses tetapi ikon baru tidak disinkronkan.
• OpenClaw otomatis menyembunyikan tindakan yang diketahui rusak berdasarkan versi macOS server BlueBubbles. Jika edit masih muncul di macOS 26 (Tahoe), nonaktifkan secara manual dengan channels.bluebubbles.actions.edit=false.
• coalesceSameSenderDms diaktifkan tetapi split-send (mis. Dump + URL) masih tiba sebagai dua giliran: lihat checklist pemecahan masalah penggabungan split-send - penyebab umum adalah window debounce terlalu ketat, timestamp log sesi disalahartikan sebagai kedatangan Webhook, atau pengiriman kutipan balasan (yang menggunakan replyToBody, bukan Webhook kedua).
• Untuk info status/kesehatan: openclaw status --all atau openclaw status --deep.

Untuk referensi alur kerja channel umum, lihat Channel dan panduan Plugins.

# Terkait

• Perutean Channel - perutean sesi untuk pesan
• Ikhtisar Channel - semua channel yang didukung
• Grup - perilaku chat grup dan gating mention
• Pairing - autentikasi DM dan alur pairing
• Keamanan - model akses dan hardening