Beralih dari BlueBubbles

​

Daftar periksa migrasi

1. Verifikasi imsg langsung di Mac yang menjalankan Messages.app (imsg chats, imsg history, imsg send, dan imsg rpc --help).
2. Salin kunci perilaku dari channels.bluebubbles ke channels.imessage: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, includeAttachments, attachmentRoots, mediaMaxMb, textChunkLimit, coalesceSameSenderDms, dan actions.
3. Hapus kunci transport yang tidak lagi ada: serverUrl, password, URL webhook, dan penyiapan server BlueBubbles.
4. Jika Gateway tidak berjalan di Mac Messages, atur channels.imessage.cliPath ke pembungkus SSH dan atur remoteHost untuk pengambilan lampiran jarak jauh.
5. Dengan Gateway dihentikan, aktifkan channels.imessage, lalu jalankan openclaw channels status --probe --channel imessage.
6. Uji satu DM, satu grup yang diizinkan, lampiran jika diaktifkan, dan setiap tindakan API privat yang Anda harapkan akan digunakan agen.
7. Hapus server BlueBubbles dan konfigurasi channels.bluebubbles lama setelah jalur iMessage diverifikasi.

​

Kapan migrasi ini masuk akal

• Anda sudah menjalankan imsg di Mac yang sama (atau yang dapat dijangkau melalui SSH) tempat Messages.app sudah masuk.
• Anda menginginkan satu komponen bergerak lebih sedikit — tanpa server BlueBubbles terpisah, tanpa endpoint REST untuk diautentikasi, tanpa perpipaan webhook. Satu biner CLI, bukan server + aplikasi klien + helper.
• Anda menggunakan build macOS / imsg yang didukung tempat probe API privat melaporkan available: true.

​

Apa yang dilakukan imsg

• Pembacaan berasal dari ~/Library/Messages/chat.db menggunakan handle SQLite baca-saja.
• Pesan masuk langsung berasal dari imsg watch / watch.subscribe, yang mengikuti kejadian sistem berkas chat.db dengan fallback polling.
• Pengiriman menggunakan otomatisasi Messages.app untuk teks normal dan pengiriman file.
• Tindakan lanjutan menggunakan imsg launch untuk menyuntikkan helper imsg ke Messages.app. Inilah yang membuka tanda terima baca, indikator mengetik, pengiriman kaya, edit, batal kirim, balasan berutas, tapback, dan manajemen grup.
• Build Linux dapat memeriksa salinan chat.db, tetapi tidak dapat mengirim, mengawasi database Mac langsung, atau mengendalikan Messages.app. Untuk OpenClaw iMessage, jalankan imsg di Mac yang sudah masuk atau melalui pembungkus SSH ke Mac tersebut.

​

Sebelum Anda mulai

1. Instal imsg di Mac yang menjalankan Messages.app:
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   Jika imsg chats gagal dengan unable to open database file, output kosong, atau authorization denied, berikan Akses Disk Penuh ke terminal, editor, proses Node, layanan Gateway, atau proses induk SSH yang meluncurkan imsg, lalu buka ulang proses induk tersebut.
2. Verifikasi permukaan baca, awasi, kirim, dan RPC sebelum mengubah konfigurasi 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
   
   Ganti 42 dengan id obrolan nyata dari imsg chats. Pengiriman memerlukan izin Automation untuk Messages.app. Jika OpenClaw akan berjalan melalui SSH, jalankan perintah ini melalui pembungkus SSH atau konteks pengguna yang sama yang akan digunakan OpenClaw. Jika pembacaan/probe berfungsi tetapi pengiriman gagal dengan AppleEvents -1743, periksa apakah Automation mendarat di /usr/libexec/sshd-keygen-wrapper; lihat Pengiriman pembungkus SSH gagal dengan AppleEvents -1743.
3. Aktifkan bridge API privat ketika Anda membutuhkan tindakan lanjutan:
   imsg launch
   imsg status --json
   
   imsg launch memerlukan SIP dinonaktifkan. Pengiriman dasar, riwayat, dan pengawasan berfungsi tanpa imsg launch; tindakan lanjutan tidak.
4. Setelah Anda menambahkan konfigurasi channels.imessage yang diaktifkan, verifikasi bridge melalui OpenClaw:
   openclaw channels status --probe
   
   Yang Anda inginkan adalah imessage.privateApi.available: true. Jika melaporkan false, perbaiki itu terlebih dahulu — lihat Deteksi kemampuan. channels status --probe hanya mem-probe akun yang dikonfigurasi dan diaktifkan.
5. Snapshot konfigurasi Anda:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

Terjemahan konfigurasi

​

Jebakan registri grup

1. Allowlist pengirim / target obrolan (channels.imessage.groupAllowFrom) — diperiksa oleh isAllowedIMessageSender. Mencocokkan pesan masuk berdasarkan handle pengirim, chat_guid, chat_identifier, atau chat_id. Bentuk yang sama seperti BlueBubbles.
2. Registri grup (channels.imessage.groups) — diperiksa oleh resolveChannelGroupPolicy dari inbound-processing.ts:199. Dengan groupPolicy: "allowlist", gate ini memerlukan salah satu dari:
   • entri wildcard groups: { "*": { ... } } (menetapkan allowAll = true), atau
   • entri eksplisit per-chat_id di bawah groups.

• warn startup satu kali per akun saat groupPolicy: "allowlist" diatur tetapi channels.imessage.groups kosong (tidak ada wildcard "*", tidak ada entri per-chat_id) — dipicu sebelum pesan apa pun masuk.
• warn satu kali per-chat_id saat pertama kali grup tertentu dibuang saat runtime, menyebutkan chat_id dan key persis yang harus ditambahkan ke groups untuk mengizinkannya.

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123", "chat_guid:any;-;..."],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

​

Langkah demi langkah

1. Tambahkan blok iMessage berdampingan dengan blok BlueBubbles yang ada. Biarkan nonaktif selama Gateway masih merutekan traffic BlueBubbles:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false,
         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. Uji sebelum traffic penting — hentikan Gateway, aktifkan sementara blok iMessage, dan pastikan iMessage melaporkan kondisi sehat dari CLI:
   openclaw gateway stop
   # edit config: channels.imessage.enabled = true
   openclaw channels status --probe --channel imessage   # expect imessage.privateApi.available: true
   
   channels status --probe hanya menguji akun yang dikonfigurasi dan diaktifkan. Jangan mulai ulang Gateway dengan BlueBubbles dan iMessage sama-sama aktif kecuali Anda memang ingin kedua pemantau channel berjalan. Jika Anda tidak langsung melakukan cutover, setel kembali channels.imessage.enabled ke false sebelum memulai ulang Gateway. Gunakan perintah langsung imsg di Sebelum memulai untuk memvalidasi Mac sebelum mengaktifkan traffic OpenClaw.
3. Lakukan cutover. Setelah akun iMessage yang diaktifkan melaporkan kondisi sehat, hapus konfigurasi BlueBubbles dan biarkan iMessage aktif:
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   Mulai ulang gateway. Traffic iMessage masuk sekarang mengalir melalui Plugin bawaan.
4. Verifikasi DM. Kirim pesan langsung ke agen; pastikan balasannya masuk.
5. Verifikasi grup secara terpisah. DM dan grup memakai jalur kode yang berbeda — keberhasilan DM tidak membuktikan grup sudah dirutekan. Kirim pesan ke agen dalam chat grup yang sudah dipasangkan dan pastikan balasannya masuk. Jika grup menjadi senyap (tidak ada balasan agen, tidak ada error), periksa log gateway untuk imessage: dropping group message from chat_id=<id> atau baris startup imessage: groupPolicy="allowlist" but channels.imessage.groups is empty — keduanya muncul pada level log default. Jika salah satu muncul, blok groups Anda hilang atau kosong — lihat “Jebakan registry grup” di atas.
6. Verifikasi permukaan aksi — dari DM yang sudah dipasangkan, minta agen untuk bereaksi, mengedit, membatalkan pengiriman, membalas, mengirim foto, dan (dalam grup) mengganti nama grup / menambah atau menghapus peserta. Setiap aksi harus masuk secara native di Messages.app. Jika ada yang melempar “iMessage <action> requires the imsg private API bridge”, jalankan imsg launch lagi dan segarkan channels status --probe.
7. Hapus server dan konfigurasi BlueBubbles setelah DM, grup, dan aksi iMessage terverifikasi. OpenClaw tidak akan memakai channels.bluebubbles.

​

Ringkasan paritas aksi

​

Pairing, sesi, dan binding ACP

• Persetujuan pairing terbawa berdasarkan handle. Anda tidak perlu menyetujui ulang pengirim yang sudah dikenal — channels.imessage.allowFrom mengenali string +15555550123 / user@example.com yang sama dengan yang digunakan BlueBubbles.
• Sesi tetap dibatasi per agen + chat. DM digabungkan ke sesi utama agen di bawah default session.dmScope=main; sesi grup tetap terisolasi per chat_id. Kunci sesi berbeda (agent:<id>:imessage:group:<chat_id> vs padanan BlueBubbles) — riwayat percakapan lama di bawah kunci sesi BlueBubbles tidak terbawa ke sesi iMessage.
• Binding ACP yang merujuk ke match.channel: "bluebubbles" perlu diperbarui menjadi "imessage". Bentuk match.peer.id (chat_id:, chat_guid:, chat_identifier:, handle polos) identik.

​

Tidak ada channel rollback

​

Terkait

• Penghapusan BlueBubbles dan jalur iMessage imsg — pengumuman singkat dan ringkasan operator.
• iMessage — referensi lengkap channel iMessage, termasuk setup imsg launch dan deteksi kapabilitas.
• /channels/bluebubbles — URL lama yang mengalihkan ke panduan migrasi ini.
• Pairing — autentikasi DM dan alur pairing.
• Perutean Channel — cara gateway memilih channel untuk balasan keluar.