Beralih dari BlueBubbles

​

Daftar periksa migrasi

1. Verifikasi imsg secara langsung di Mac yang menjalankan Messages.app (imsg chats, imsg history, imsg send, 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 sudah tidak ada: serverUrl, password, URL webhook, dan penyiapan server BlueBubbles.
4. Jika Gateway tidak berjalan di Mac tempat Messages berada, atur channels.imessage.cliPath ke pembungkus SSH dan atur remoteHost untuk mengambil lampiran jarak jauh.
5. Aktifkan channels.imessage, mulai ulang Gateway, lalu jalankan openclaw channels status --probe --channel imessage.
6. Uji satu pesan langsung, satu grup yang diizinkan, lampiran jika diaktifkan, dan setiap tindakan API privat yang Anda harapkan digunakan oleh agen.
7. Hapus server BlueBubbles dan konfigurasi lama channels.bluebubbles setelah jalur iMessage terverifikasi.

​

Fungsi imsg

• Pembacaan berasal dari ~/Library/Messages/chat.db menggunakan handel SQLite hanya-baca.
• Pesan langsung yang masuk berasal dari imsg watch / watch.subscribe, yang mengikuti peristiwa sistem berkas chat.db dengan polling sebagai cadangan.
• Pengiriman menggunakan otomatisasi Messages.app untuk mengirim teks dan berkas biasa.
• Tindakan lanjutan menggunakan imsg launch untuk menyuntikkan pembantu imsg ke Messages.app. Inilah yang mengaktifkan tanda terima baca, indikator sedang mengetik, pengiriman kaya, pengeditan, pembatalan pengiriman, balasan berutas, tapback, jajak pendapat, dan pengelolaan grup.
• Versi Linux dapat memeriksa salinan chat.db, tetapi tidak dapat mengirim, memantau basis data Mac secara langsung, atau mengendalikan Messages.app. Untuk iMessage OpenClaw, jalankan imsg di Mac yang telah masuk atau melalui pembungkus SSH ke Mac tersebut.

​

Sebelum memulai

1. Instal imsg di Mac yang menjalankan Messages.app:
   brew install steipete/tap/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg chats --limit 3
   
   Untuk penyiapan lokal biasa, penyiapan OpenClaw dapat menawarkan instalasi atau pembaruan Homebrew untuk imsg yang dikonfirmasi pengguna di Mac Messages yang telah masuk. Penyiapan manual dan topologi pembungkus SSH tetap dikelola oleh operator: ulangi pembaruan Homebrew dalam konteks pengguna lokal atau jarak jauh yang sama dengan yang akan menjalankan imsg. Jika imsg chats gagal dengan unable to open database file, keluaran kosong, atau authorization denied, berikan Full Disk Access kepada terminal, editor, proses Node, layanan Gateway, atau proses induk SSH yang meluncurkan imsg, lalu buka kembali proses induk tersebut.
2. Verifikasi permukaan baca, pemantauan, pengiriman, 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 sebenarnya 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 dengan yang akan digunakan OpenClaw. Jika pembacaan berfungsi tetapi pengiriman gagal dengan AppleEvents -1743, periksa apakah Automation diterapkan pada /usr/libexec/sshd-keygen-wrapper; lihat Pengiriman melalui pembungkus SSH gagal dengan AppleEvents -1743.
3. Aktifkan jembatan API privat. Ini sangat dianjurkan untuk iMessage OpenClaw karena balasan, tapback, efek, jajak pendapat, balasan lampiran, dan tindakan grup bergantung padanya:
   imsg launch
   imsg status --json
   
   imsg launch mengharuskan SIP dinonaktifkan (dan pada macOS modern, validasi pustaka dilonggarkan—lihat Mengaktifkan API privat imsg). Pengiriman dasar, riwayat, dan pemantauan berfungsi tanpa imsg launch; seluruh permukaan tindakan iMessage OpenClaw tidak.
4. Setelah Anda mengaktifkan channels.imessage dan memulai Gateway, verifikasi jembatan melalui OpenClaw:
   openclaw channels status --probe
   
   Akun iMessage seharusnya melaporkan works; dengan --json, payload pemeriksaan mencakup privateApi.available: true. Jika melaporkan false, perbaiki itu terlebih dahulu—lihat Deteksi kemampuan. Pemeriksaan memerlukan Gateway yang dapat dijangkau (jika tidak, CLI akan kembali menampilkan keluaran berbasis konfigurasi saja) dan hanya memeriksa akun terkonfigurasi yang diaktifkan.
5. Buat snapshot konfigurasi Anda:
   cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
   

​

Penerjemahan konfigurasi

​

Jebakan registri grup

1. Daftar yang diizinkan untuk pengirim / target obrolan (channels.imessage.groupAllowFrom) — mencocokkan alamat pengirim atau target obrolan (entri chat_id:, chat_guid:, chat_identifier:). Jika groupAllowFrom tidak ditetapkan, gerbang ini kembali menggunakan allowFrom; groupAllowFrom: [] yang eksplisit menonaktifkan mekanisme tersebut dan membuang setiap pesan grup di bawah groupPolicy: "allowlist".
2. Registri grup (channels.imessage.groups) — menggunakan chat_id numerik iMessage sebagai kunci:
   • Tidak ada blok groups (atau blok kosong): grup melewati gerbang ini selama gerbang 1 memiliki daftar efektif pengirim yang diizinkan dan tidak kosong; pemfilteran pengirim mengatur akses dan tidak ada peringatan saat mulai yang menyatakan semua pesan akan dibuang.
   • groups berisi entri tetapi tanpa "*": hanya kunci chat_id yang tercantum yang lolos. Mencantumkan grup apa pun mengubah registri menjadi daftar yang diizinkan, bahkan di bawah groupPolicy: "open".
   • groups: { "*": { ... } }: setiap grup melewati gerbang ini.

• Satu kali per akun saat mulai, ketika groupPolicy: "allowlist" ditetapkan dan daftar efektif pengirim grup yang diizinkan kosong: imessage: groupPolicy="allowlist" for account "<id>" but no group sender allowlist is configured .... Tetapkan groupAllowFrom (atau allowFrom) untuk mengizinkan pengirim; menambahkan groups saja tidak memenuhi gerbang pengirim.
• Satu kali per chat_id saat waktu proses, ketika registri membuang grup: imessage: dropping group message from chat_id=<id> ... not in channels.imessage.groups allowlist, dengan menyebutkan kunci persis yang harus ditambahkan.

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

​

Langkah demi langkah

1. Terjemahkan konfigurasi. Biarkan blok baru dinonaktifkan selama Anda mengedit; blok channels.bluebubbles lama diabaikan oleh OpenClaw saat ini dan dapat dibiarkan berdampingan sebagai referensi:
   {
     channels: {
       imessage: {
         enabled: false, // flip to true when ready to cut over
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // wildcard copies verbatim; re-key per-chat entries by chat_id
         // actions default to enabled; set individual toggles false to disable
       },
     },
   }
   
2. Alihkan dan lakukan pemeriksaan. Atur channels.imessage.enabled: true, mulai ulang Gateway, lalu pastikan kanal dilaporkan dalam kondisi sehat:
   openclaw gateway restart
   openclaw channels status --probe --channel imessage   # expect "works"; --json shows privateApi.available: true
   
   Pemeriksaan memerlukan Gateway yang dapat dijangkau dan hanya memeriksa akun yang telah dikonfigurasi serta diaktifkan. Gunakan perintah langsung imsg di Sebelum memulai untuk memvalidasi Mac itu sendiri.
3. Verifikasi DM. Kirim pesan langsung kepada agen; pastikan balasannya diterima.
4. Verifikasi grup secara terpisah. DM dan grup menggunakan jalur kode yang berbeda — keberhasilan DM tidak membuktikan bahwa perutean grup berfungsi. Kirim pesan di obrolan grup yang diizinkan dan pastikan balasannya diterima. Jika grup tidak memberikan respons (tidak ada balasan agen maupun kesalahan), periksa log Gateway untuk dua baris warn dari “Jebakan registri grup” di atas. Peringatan saat awal proses berarti daftar pengirim yang diizinkan secara efektif kosong; peringatan per-chat_id berarti registri groups yang terisi tidak memuat obrolan tersebut.
5. Verifikasi permukaan tindakan. Dari DM yang telah dipasangkan, minta agen untuk memberikan reaksi, mengedit, membatalkan pengiriman, membalas, mengirim foto, serta (dalam grup) mengganti nama grup atau menambah/menghapus peserta. Setiap tindakan seharusnya diterapkan secara native di Messages.app. Jika ada tindakan yang menghasilkan iMessage <action> requires the imsg private API bridge, jalankan kembali imsg launch, lalu segarkan dengan openclaw channels status --probe.
6. Hapus server BlueBubbles dan blok channels.bluebubbles setelah DM, grup, serta tindakan iMessage selesai diverifikasi. OpenClaw tidak membaca channels.bluebubbles.

​

Sekilas kesetaraan tindakan

​

Pemasangan, sesi, dan pengikatan ACP

• Daftar yang diizinkan dibawa berdasarkan handle. channels.imessage.allowFrom mengenali string +15555550123 / user@example.com yang sama dengan yang digunakan BlueBubbles — salin persis tanpa perubahan.
• Persetujuan penyimpanan pemasangan tidak ditransfer. Penyimpanan pemasangan berlaku per kanal dan tidak ada proses yang memigrasikan penyimpanan BlueBubbles lama. Pengirim yang hanya disetujui melalui pemasangan harus memasangkan kembali satu kali di iMessage, atau Anda dapat menambahkan handle mereka ke allowFrom.
• Sesi tetap dicakup per agen + obrolan. DM digabungkan ke sesi utama agen dengan pengaturan bawaan session.dmScope=main; sesi grup tetap terisolasi per chat_id (agent:<agentId>:imessage:group:<chat_id>). Riwayat percakapan lama dalam kunci sesi BlueBubbles tidak dibawa ke sesi iMessage.
• Pengikatan ACP yang merujuk ke match.channel: "bluebubbles" harus diubah menjadi "imessage". Bentuk match.peer.id (chat_id:, chat_guid:, chat_identifier:, handle tanpa awalan) tetap identik.

​

Tidak ada kanal untuk kembali

​

Terkait

• Penghapusan BlueBubbles dan jalur iMessage imsg — pengumuman singkat dan ringkasan untuk operator.
• iMessage — referensi lengkap kanal iMessage, termasuk penyiapan imsg launch dan deteksi kemampuan.
• /channels/bluebubbles — URL lama yang dialihkan ke panduan migrasi ini.
• Pemasangan — autentikasi DM dan alur pemasangan.
• Perutean Kanal — cara Gateway memilih kanal untuk balasan keluar.