Beralih dari BlueBubbles

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Kapan migrasi ini masuk akal

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

​

Apa yang dilakukan imsg

• Pembacaan berasal dari ~/Library/Messages/chat.db menggunakan handle SQLite hanya-baca.
• Pesan masuk langsung berasal dari imsg watch / watch.subscribe, yang mengikuti event sistem file chat.db dengan fallback polling.
• Pengiriman menggunakan otomasi Messages.app untuk teks normal dan pengiriman file.
• Tindakan lanjutan menggunakan imsg launch untuk menyuntikkan helper imsg ke Messages.app. Itulah yang membuka tanda terima baca, indikator mengetik, pengiriman kaya, edit, urung kirim, balasan berutas, tapback, dan pengelolaan grup.
• Build Linux dapat memeriksa salinan chat.db, tetapi tidak dapat mengirim, memantau database Mac langsung, atau menjalankan Messages.app. Untuk iMessage OpenClaw, jalankan imsg pada Mac yang sudah masuk atau melalui wrapper SSH ke Mac tersebut.

​

Sebelum Anda mulai

1. Pasang imsg pada 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 Full Disk Access ke terminal, editor, proses Node, layanan Gateway, atau proses induk SSH yang meluncurkan imsg, lalu buka ulang proses induk tersebut.
2. Verifikasi permukaan baca, pantau, 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 chat nyata dari imsg chats. Pengiriman memerlukan izin Automation untuk Messages.app. Jika OpenClaw akan berjalan melalui SSH, jalankan perintah ini melalui wrapper SSH atau konteks pengguna yang sama yang akan digunakan OpenClaw.
3. Aktifkan bridge API privat ketika Anda memerlukan tindakan lanjutan:
   imsg launch
   imsg status --json
   
   imsg launch mengharuskan SIP dinonaktifkan. Kirim dasar, riwayat, dan pemantauan berfungsi tanpa imsg launch; tindakan lanjutan tidak.
4. Verifikasi bridge melalui OpenClaw:
   openclaw channels status --probe
   
   Anda menginginkan imessage.privateApi.available: true. Jika melaporkan false, perbaiki itu terlebih dahulu — lihat Deteksi kemampuan.
5. Ambil snapshot konfigurasi Anda:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

Penerjemahan konfigurasi

​

Jebakan registry grup

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

• warn startup satu kali per akun ketika groupPolicy: "allowlist" disetel 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 pada runtime, menyebutkan chat_id dan kunci persis yang perlu ditambahkan ke groups untuk mengizinkannya.

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

​

Langkah demi langkah

1. Tambahkan blok iMessage di samping blok BlueBubbles yang ada. Simpan blok lama hanya sebagai sumber salinan sampai jalur baru diverifikasi:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false, // turn on after the dry run below
         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. Probe dry-run — jalankan Gateway dan pastikan iMessage melaporkan status sehat:
   openclaw gateway
   openclaw channels status
   openclaw channels status --probe   # expect imessage.privateApi.available: true
   
   Karena imessage.enabled masih false, belum ada traffic iMessage masuk yang dirutekan — tetapi --probe menguji bridge sehingga Anda dapat menemukan masalah izin/instalasi sebelum cutover.
3. Cut over. Hapus konfigurasi BlueBubbles dan aktifkan iMessage dalam satu edit konfigurasi:
   {
     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 menggunakan jalur kode yang berbeda — keberhasilan DM tidak membuktikan bahwa grup sudah dirutekan. Kirim pesan ke agen dalam obrolan 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 satunya 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 memberi reaksi, mengedit, membatalkan pengiriman, membalas, mengirim foto, dan (dalam grup) mengganti nama grup / menambah atau menghapus peserta. Setiap aksi seharusnya 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 menggunakan channels.bluebubbles.

​

Sekilas paritas aksi

​

Pairing, sesi, dan binding ACP

• Persetujuan Pairing berpindah 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 + obrolan. DM digabungkan ke sesi utama agen di bawah session.dmScope=main default; 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 mereferensikan 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

• iMessage — referensi lengkap channel iMessage, termasuk penyiapan imsg launch dan deteksi kapabilitas.
• /channels/bluebubbles — URL legacy yang dialihkan ke panduan migrasi ini.
• Pairing — autentikasi DM dan alur Pairing.
• Perutean Channel — cara Gateway memilih channel untuk balasan keluar.