iMessage

Status: integrasi CLI eksternal native. Gateway menjalankan imsg rpc dan berkomunikasi menggunakan JSON-RPC melalui stdio — tanpa daemon atau port terpisah. Mode API privat sangat disarankan untuk kanal iMessage yang lengkap; balasan, tapback, efek, jajak pendapat, balasan lampiran, dan tindakan grup memerlukan imsg launch serta pemeriksaan API privat yang berhasil.

Untuk penyiapan lokal yang umum, penyiapan OpenClaw dapat menawarkan instalasi atau pembaruan Homebrew yang dikonfirmasi pengguna untuk imsg di Mac Messages yang telah masuk. Penyiapan manual dan topologi pembungkus SSH tetap dikelola operator: instal atau perbarui imsg dalam konteks pengguna yang sama dengan yang akan menjalankan Gateway atau pembungkus.

Penyiapan cepat

brew install steipete/tap/imsgbrew update && brew upgrade imsgimsg rpc --helpimsg launchopenclaw channels status --probe

{channels: {imessage: {enabled: true,cliPath: "/usr/local/bin/imsg",dbPath: "/Users/user/Library/Messages/chat.db",},},}

openclaw gateway

openclaw pairing list imessageopenclaw pairing approve imessage <CODE>

ssh messages-mac 'brew install steipete/tap/imsg && brew update && brew upgrade imsg'

#!/usr/bin/env bashexec ssh -T messages-mac imsg "$@"

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // digunakan untuk mengambil lampiran melalui SCP  includeAttachments: true,  // Opsional: root lampiran tambahan yang diizinkan (digabungkan dengan  // /Users/*/Library/Messages/Attachments default).  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

Persyaratan dan izin (macOS)

• Messages harus dalam keadaan masuk di Mac yang menjalankan imsg.
• Full Disk Access diperlukan untuk konteks proses yang menjalankan OpenClaw/imsg (akses DB Messages).
• Izin Automation diperlukan untuk mengirim pesan melalui Messages.app.
• Untuk tindakan lanjutan (bereaksi / mengedit / membatalkan pengiriman / balasan berutas / efek / jajak pendapat / operasi grup), System Integrity Protection harus dinonaktifkan — lihat Mengaktifkan API privat imsg. Pengiriman dan penerimaan teks serta media dasar berfungsi tanpanya.

Tidak diizinkan mengirim peristiwa Apple ke Messages. (-1743)

kTCCServiceAppleEvents | /usr/libexec/sshd-keygen-wrapper | auth_value=0 | com.apple.MobileSMS

Mengaktifkan API privat imsg

imsg disertakan dalam dua mode operasional. Untuk OpenClaw, mode API Privat merupakan penyiapan yang disarankan karena memberikan kanal tindakan native iMessage yang diharapkan pengguna. Mode dasar tetap berguna untuk instalasi berisiko rendah, verifikasi awal, atau host tempat SIP tidak dapat dinonaktifkan.

• Mode dasar (default, tidak memerlukan perubahan SIP): teks dan media keluar melalui send, pemantauan/riwayat pesan masuk, dan daftar obrolan. Inilah yang langsung tersedia dari brew install steipete/tap/imsg baru beserta izin macOS standar di atas.
• Mode API privat: imsg menyuntikkan dylib pembantu ke dalam Messages.app untuk memanggil fungsi internal IMCore. Ini membuka react, edit, unsend, reply (berutas), sendWithEffect, poll dan poll-vote (jajak pendapat native Messages), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, serta indikator pengetikan dan tanda terima baca.

Permukaan tindakan yang disarankan pada halaman ini memerlukan mode API Privat. README imsg menyatakan persyaratan tersebut secara eksplisit:

Fitur lanjutan seperti read, typing, launch, pengiriman kaya yang didukung bridge, mutasi pesan, dan pengelolaan obrolan bersifat opsional. Fitur tersebut memerlukan SIP dinonaktifkan dan dylib pembantu disuntikkan ke dalam Messages.app. imsg launch menolak melakukan penyuntikan ketika SIP diaktifkan.

Teknik penyuntikan pembantu menggunakan dylib milik imsg sendiri untuk mengakses API privat Messages. Tidak ada server pihak ketiga atau runtime BlueBubbles dalam jalur iMessage OpenClaw.

Penyiapan

1. Instal (atau tingkatkan) imsg di Mac yang menjalankan Messages.app:

   brew install steipete/tap/imsgbrew update && brew upgrade imsgimsg --versionimsg status --json

   Output imsg status --json melaporkan bridge_version, rpc_methods, dan selectors per metode agar Anda dapat melihat apa yang didukung build saat ini sebelum memulai.

2. Nonaktifkan System Integrity Protection, dan (pada macOS modern) Library Validation. Menginjeksikan dylib pembantu non-Apple ke dalam Messages.app yang ditandatangani Apple mengharuskan SIP dinonaktifkan dan validasi pustaka dilonggarkan. Langkah SIP dalam mode Pemulihan bergantung pada versi macOS:

   • macOS 10.13-10.15 (Sierra-Catalina): nonaktifkan Library Validation melalui Terminal, mulai ulang ke Mode Pemulihan, jalankan csrutil disable, lalu mulai ulang.
   • macOS 11+ (Big Sur dan yang lebih baru), Intel: masuk ke Mode Pemulihan (atau Pemulihan Internet), jalankan csrutil disable, lalu mulai ulang.
   • macOS 11+, Apple Silicon: gunakan urutan penyalaan dengan tombol daya untuk masuk ke Pemulihan; pada versi macOS terbaru, tahan tombol Left Shift saat mengeklik Continue, lalu jalankan csrutil disable. Penyiapan mesin virtual mengikuti alur terpisah, jadi buat snapshot VM terlebih dahulu.

   Pada macOS 11 dan yang lebih baru, csrutil disable saja biasanya tidak cukup. Apple masih memberlakukan validasi pustaka terhadap Messages.app sebagai biner platform, sehingga pembantu yang ditandatangani secara ad hoc ditolak (Library Validation failed: ... platform binary, but mapped file is not) meskipun SIP dinonaktifkan. Setelah menonaktifkan SIP, nonaktifkan juga validasi pustaka dan mulai ulang:

   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true

   macOS 26 (Tahoe), diverifikasi pada 26.5.1: SIP yang dinonaktifkan ditambah perintah DisableLibraryValidation di atas sudah cukup untuk menginjeksikan pembantu pada versi 26.0 hingga 26.5.x. Tidak diperlukan boot-args. Plist tersebut merupakan faktor penentu dan langkah yang paling sering terlewat saat injeksi gagal di Tahoe:

   • Dengan plist: imsg launch melakukan injeksi dan imsg status melaporkan advanced_features: true.
   • Tanpa plist (meskipun SIP dinonaktifkan): imsg launch gagal dengan Failed to launch: Timeout waiting for Messages.app to initialize. AMFI menolak pembantu ad hoc saat pemuatan, sehingga bridge tidak pernah siap dan peluncuran kehabisan waktu. Kehabisan waktu tersebut adalah gejala yang paling sering ditemui di Tahoe; solusinya adalah plist di atas, bukan tindakan yang lebih drastis.

   Jika injeksi imsg launch atau selectors tertentu mulai mengembalikan false setelah peningkatan macOS, pemeriksaan ini biasanya menjadi penyebabnya. Periksa status SIP dan validasi pustaka sebelum menganggap langkah SIP itu sendiri gagal. Jika pengaturan tersebut sudah benar dan bridge masih tidak dapat melakukan injeksi, kumpulkan imsg status --json beserta keluaran imsg launch dan laporkan ke proyek imsg, alih-alih melemahkan kontrol keamanan tambahan di seluruh sistem.

3. Injeksikan pembantu. Dengan SIP dinonaktifkan dan Messages.app telah masuk:

   imsg launch

   imsg launch menolak melakukan injeksi saat SIP masih diaktifkan, sehingga tindakan ini juga berfungsi sebagai konfirmasi bahwa langkah 2 telah diterapkan.

4. Verifikasi bridge dari OpenClaw:

   openclaw channels status --probe

   Entri iMessage seharusnya melaporkan works, dan imsg status --json | jq '{rpc_methods, selectors}' seharusnya menampilkan kemampuan yang disediakan oleh build macOS Anda. Pembuatan jajak pendapat memerlukan selectors.pollPayloadMessage; pemungutan suara memerlukan selectors.pollVoteMessage dan metode RPC poll.vote. Plugin OpenClaw hanya mengiklankan tindakan yang didukung oleh pemeriksaan tersimpan dalam cache, sedangkan cache kosong tetap optimistis dan melakukan pemeriksaan pada pengiriman pertama.

Jika openclaw channels status --probe melaporkan kanal sebagai works, tetapi tindakan tertentu memunculkan "iMessage <action> requires the imsg private API bridge" saat dikirim, jalankan kembali imsg launch — pembantu dapat terlepas (Messages.app dimulai ulang, pembaruan OS, dan sebagainya) dan status available: true yang tersimpan dalam cache akan terus mengiklankan tindakan hingga pemeriksaan berikutnya memperbaruinya.

Saat SIP tetap diaktifkan

Jika menonaktifkan SIP tidak dapat diterima untuk model ancaman Anda:

• imsg kembali ke mode dasar — hanya teks + media + penerimaan.
• Plugin OpenClaw tetap mengiklankan pengiriman teks/media dan pemantauan pesan masuk; Plugin menyembunyikan react, edit, unsend, reply, sendWithEffect, dan operasi grup dari permukaan tindakan (sesuai pemeriksaan kemampuan per metode).
• Anda dapat menjalankan Mac non-Apple-Silicon terpisah (atau Mac bot khusus) dengan SIP dinonaktifkan untuk beban kerja iMessage, sambil tetap mengaktifkan SIP pada perangkat utama Anda. Lihat Pengguna macOS bot khusus (identitas iMessage terpisah) di bawah.

Kontrol akses dan perutean

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "Gunakan ejaan Britania." },        "8421": {          requireMention: true,          systemPrompt: "Ini adalah percakapan rotasi petugas siaga. Batasi balasan hingga kurang dari 3 kalimat.",        },        "9907": {          // penekanan eksplisit: wildcard "Gunakan ejaan Britania." tidak berlaku di sini          systemPrompt: "",        },      },    },  },}

Pengikatan percakapan ACP

Percakapan iMessage dapat diikat ke sesi ACP.

Alur cepat operator:

• Jalankan /acp spawn codex --bind here di dalam DM atau percakapan grup yang diizinkan.
• Pesan berikutnya dalam percakapan iMessage yang sama dirutekan ke sesi ACP yang dibuat.
• /new dan /reset mengatur ulang sesi ACP terikat yang sama tanpa menggantinya.
• /acp close menutup sesi ACP dan menghapus pengikatannya.

Pengikatan persisten yang dikonfigurasi menggunakan entri bindings[] tingkat atas dengan type: "acp" dan match.channel: "imessage".

match.peer.id dapat menggunakan:

• handle DM yang dinormalisasi seperti +15555550123 atau user@example.com
• chat_id:<id> (disarankan untuk pengikatan grup yang stabil)
• chat_guid:<guid>
• chat_identifier:<identifier>

Contoh:

{  agents: {    list: [      {        id: "codex",        runtime: {          type: "acp",          acp: { agent: "codex", backend: "acpx", mode: "persistent" },        },      },    ],  },  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "imessage",        accountId: "default",        peer: { kind: "group", id: "chat_id:123" },      },      acp: { label: "codex-group" },    },  ],}

Lihat Agen ACP untuk perilaku pengikatan ACP bersama.

Pola penerapan

{  channels: {    imessage: {      enabled: true,      cliPath: "~/.openclaw/scripts/imsg-ssh",      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",      includeAttachments: true,      dbPath: "/Users/bot/Library/Messages/chat.db",    },  },}

#!/usr/bin/env bashexec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

Media, pemenggalan, dan target pengiriman

imsg chats --limit 20

Tindakan API privat

Ketika imsg launch berjalan dan openclaw channels status --probe melaporkan privateApi.available: true, alat pesan dapat menggunakan tindakan native iMessage selain pengiriman teks biasa.

Semua tindakan diaktifkan secara default; gunakan channels.imessage.actions untuk menonaktifkan tindakan tertentu:

{  channels: {    imessage: {      actions: {        reactions: true,        edit: true,        unsend: true,        reply: true,        sendWithEffect: true,        sendAttachment: true,        renameGroup: true,        setGroupIcon: true,        addParticipant: true,        removeParticipant: true,        leaveGroup: true,        polls: true,      },    },  },}

{  channels: {    imessage: {      sendReadReceipts: false,    },  },}

Penulisan konfigurasi

iMessage secara default mengizinkan penulisan konfigurasi yang dimulai oleh saluran (untuk /config set|unset ketika commands.config: true).

Nonaktifkan:

{  channels: {    imessage: {      configWrites: false,    },  },}

Menggabungkan DM yang terkirim terpisah (perintah + URL dalam satu komposisi)

Ketika pengguna mengetik perintah dan URL secara bersamaan — misalnya Dump https://example.com/article — aplikasi Messages milik Apple membagi pengiriman menjadi dua baris chat.db yang terpisah:

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

Pada sebagian besar konfigurasi, kedua baris tiba di OpenClaw dengan selang ~0.8-2.0 dtk. Tanpa penggabungan, agen menerima perintah saja pada giliran 1 (dan sering membalas "kirimkan URL kepada saya") sebelum URL tiba pada giliran 2. Ini merupakan pipeline pengiriman Apple, bukan sesuatu yang diperkenalkan oleh OpenClaw atau imsg.

channels.imessage.coalesceSameSenderDms mengikutsertakan DM dalam penyanggaan baris berurutan dari pengirim yang sama. Ketika imsg mengekspos penanda struktural pratinjau URL balloon_bundle_id: "com.apple.messages.URLBalloonProvider" pada salah satu baris sumber, OpenClaw hanya menggabungkan pengiriman terpisah yang sebenarnya dan mempertahankan baris lain yang disangga sebagai giliran terpisah. Pada build imsg lama yang sama sekali tidak memancarkan metadata balon, OpenClaw tidak dapat membedakan pengiriman terpisah dari pengiriman yang berbeda, sehingga kembali menggabungkan kumpulan tersebut. Hal ini mempertahankan perilaku sebelum adanya metadata, alih-alih meregresikan pengiriman terpisah Dump <url> menjadi dua giliran. Obrolan grup tetap dikirim per pesan agar struktur giliran beberapa pengguna tetap dipertahankan.

{  channels: {    imessage: {      coalesceSameSenderDms: true, // opt in (default: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 7000 ms covers observed Messages.app URL-preview delays.        imessage: 7000,      },    },  },}

Skenario dan apa yang dilihat agen

Kolom "Flag aktif" menunjukkan perilaku pada build imsg yang memancarkan balloon_bundle_id. Pada build imsg lama yang sama sekali tidak memancarkan metadata balon, baris di bawah yang ditandai "Dua giliran" / "N giliran" akan beralih ke penggabungan lama (satu giliran): OpenClaw secara struktural tidak dapat membedakan pengiriman terpisah dari pengiriman yang berbeda, sehingga mempertahankan penggabungan sebelum adanya metadata. Pemisahan yang presisi diaktifkan setelah build memancarkan metadata balon.

Pemulihan masuk setelah bridge atau Gateway dimulai ulang

iMessage memulihkan pesan yang terlewat saat Gateway tidak aktif, sekaligus mencegah "bom backlog" usang yang dapat dikirim Apple setelah pemulihan Push. Perilaku default ini selalu aktif dan dibangun berdasarkan ingress tahan lama serta pembatas usia.

• Perlindungan replay tahan lama. Sebelum memajukan kursor pemulihan, OpenClaw mencatat setiap baris mentah dalam antrean ingress SQLite bersama menggunakan GUID Apple-nya sebagai ID peristiwa. Baris yang selesai meninggalkan tombstone selama sekitar 4 jam, dengan batas 10,000 entri, sehingga replay dengan GUID yang sama dibuang bahkan setelah proses dimulai ulang. Baris yang tertunda tetap dapat dipulihkan hingga pengiriman mengadopsinya.
• Pemulihan waktu henti. Saat dimulai, monitor mengingat rowid baris chat.db terakhir yang diterima secara tahan lama (kursor per akun yang dipersistenkan) dan meneruskannya ke imsg watch.subscribe sebagai since_rowid, sehingga imsg memutar ulang baris yang belum dicatat lalu mengikuti data langsung. Baris yang dicatat sebelum crash dilanjutkan dari SQLite. Replay dibatasi pada 500 baris terbaru dan pesan yang berusia hingga ~2 jam, sedangkan tombstone GUID membuang segala sesuatu yang telah ditangani.
• Pembatas usia backlog usang. Baris di atas batas awal benar-benar langsung; baris dengan tanggal pengiriman lebih dari ~15 menit sebelum waktu kedatangannya dianggap sebagai backlog hasil flush Push dan dicegah. Baris yang diputar ulang (pada atau di bawah batas) menggunakan jendela pemulihan yang lebih lebar, sehingga pesan yang baru saja terlewat dikirimkan sedangkan riwayat lama tidak.

Pemulihan berfungsi pada konfigurasi cliPath lokal maupun jarak jauh karena replay since_rowid berjalan melalui koneksi RPC imsg yang sama. Perbedaannya terletak pada jendela: ketika Gateway dapat membaca chat.db (lokal), Gateway menetapkan batas rowid awal, membatasi rentang replay, dan mengirimkan pesan yang terlewat hingga sekitar beberapa jam sebelumnya. Melalui cliPath SSH jarak jauh, Gateway tidak dapat membaca basis data, sehingga replay tidak dibatasi dan setiap baris menggunakan pembatas usia langsung — pesan yang baru saja terlewat tetap dipulihkan dan backlog lama tetap dicegah, hanya saja dengan jendela langsung yang lebih sempit. Jalankan Gateway pada Mac yang menjalankan Messages untuk mendapatkan jendela pemulihan yang lebih lebar.

Sinyal yang terlihat oleh operator

Backlog yang dicegah dicatat pada level default dan tidak pernah dibuang secara diam-diam (flag recovery menunjukkan jendela yang diterapkan):

imessage: backlog masuk usang dicegah account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; dicegah sejak mulai)

Migrasi

channels.imessage.catchup.* tidak digunakan lagi — pemulihan waktu henti berjalan otomatis dan tidak memerlukan konfigurasi untuk penyiapan baru. Konfigurasi yang sudah ada dengan catchup.enabled: true tetap dipatuhi sebagai profil kompatibilitas untuk jendela replay pemulihan. Blok catchup yang dinonaktifkan (enabled: false atau tanpa enabled: true) dihentikan; openclaw doctor --fix menghapusnya.

Pemecahan masalah

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

imsg chats --limit 10 --jsonimsg watch --chat-id <chat-id> --jsonsqlite3 ~/Library/Messages/chat.db \"select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

#!/usr/bin/env bashexec ssh -T messages-mac imsg "$@"

openclaw channels status --probe --channel imessage

imsg chats --limit 1imsg send <handle> "test"

Referensi konfigurasi

• Referensi konfigurasi - iMessage
• Konfigurasi Gateway
• Pairing

Terkait

• Ikhtisar Kanal — semua kanal yang didukung
• Penghapusan BlueBubbles dan jalur iMessage imsg — pengumuman dan ringkasan migrasi
• Beralih dari BlueBubbles — tabel penerjemahan konfigurasi dan peralihan langkah demi langkah
• Pairing — autentikasi DM dan alur pairing
• Grup — perilaku obrolan grup dan pembatasan berdasarkan penyebutan
• Perutean Kanal — perutean sesi untuk pesan
• Keamanan — model akses dan penguatan