iMessage

Status: integrasi CLI eksternal native. Gateway menjalankan imsg rpc dan berkomunikasi melalui JSON-RPC di stdio (tanpa daemon/port terpisah). Tindakan lanjutan memerlukan imsg launch dan probe private API yang berhasil.

Penyiapan cepat

brew install steipete/tap/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>

#!/usr/bin/env bashexec ssh -T gateway-host imsg "$@"

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // used for SCP attachment fetches  includeAttachments: true,  // Optional: override allowed attachment roots.  // Defaults include /Users/*/Library/Messages/Attachments  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

Persyaratan dan izin (macOS)

• Messages harus sudah 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 (react / edit / unsend / balasan berutas / efek / polling / operasi grup), System Integrity Protection harus dinonaktifkan — lihat Mengaktifkan private API imsg di bawah. Pengiriman/penerimaan teks dan media dasar berfungsi tanpanya.

Not authorized to send Apple events to Messages. (-1743)

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

Mengaktifkan private API imsg

imsg dikirim dalam dua mode operasional:

• Mode dasar (default, tidak perlu perubahan SIP): teks dan media keluar melalui send, watch/history masuk, daftar chat. Ini yang Anda dapatkan langsung dari brew install steipete/tap/imsg baru ditambah izin macOS standar di atas.
• Mode private API: imsg menyuntikkan helper dylib ke Messages.app untuk memanggil fungsi internal IMCore. Ini membuka react, edit, unsend, reply (berutas), sendWithEffect, poll dan poll-vote (polling Messages native), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, plus indikator mengetik dan tanda dibaca.

Untuk mencapai permukaan tindakan lanjutan yang didokumentasikan halaman saluran ini, Anda memerlukan mode Private API. README imsg tegas tentang persyaratan ini:

Fitur lanjutan seperti read, typing, launch, pengiriman kaya berbasis bridge, mutasi pesan, dan manajemen chat bersifat opt-in. Fitur tersebut memerlukan SIP dinonaktifkan dan helper dylib disuntikkan ke Messages.app. imsg launch menolak menyuntikkan saat SIP diaktifkan.

Teknik injeksi helper menggunakan dylib milik imsg sendiri untuk menjangkau private API Messages. Tidak ada server pihak ketiga atau runtime BlueBubbles di jalur iMessage OpenClaw.

Penyiapan

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

   brew install steipete/tap/imsgimsg --versionimsg status --json

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

2. Nonaktifkan System Integrity Protection, dan (pada macOS modern) Library Validation. Menyuntikkan helper dylib non-Apple ke Messages.app yang ditandatangani Apple memerlukan SIP dimatikan dan validasi library dilonggarkan. Langkah SIP mode Recovery spesifik untuk versi macOS:

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

   Pada macOS 11 dan yang lebih baru, csrutil disable saja biasanya tidak cukup. Apple masih menerapkan validasi library terhadap Messages.app sebagai binary platform, sehingga helper yang ditandatangani adhoc ditolak (Library Validation failed: ... platform binary, but mapped file is not) bahkan dengan SIP dimatikan. Setelah menonaktifkan SIP, nonaktifkan juga validasi library dan reboot:

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

   macOS 26 (Tahoe), diverifikasi pada 26.5.1: SIP dimatikan plus perintah DisableLibraryValidation di atas sudah cukup untuk menyuntikkan helper di seluruh 26.0 hingga 26.5.x. Tidak diperlukan boot-args. Plist adalah faktor penentu dan langkah yang paling umum terlewat saat injeksi gagal di Tahoe:

   • Dengan plist: imsg launch menyuntikkan dan imsg status melaporkan advanced_features: true.
   • Tanpa plist (bahkan dengan SIP dimatikan): imsg launch gagal dengan Failed to launch: Timeout waiting for Messages.app to initialize. AMFI menolak helper adhoc saat dimuat, sehingga bridge tidak pernah siap dan launch timeout. Timeout tersebut adalah gejala yang paling sering ditemui di Tahoe, dan perbaikannya adalah plist di atas, bukan tindakan yang lebih drastis.

   Ini dikonfirmasi dengan before/after terkontrol pada macOS 26.5.1 (Apple Silicon): dengan plist, dylib dipetakan ke Messages.app dan bridge aktif; hapus plist dan reboot, lalu imsg launch menghasilkan kegagalan timeout di atas dengan dylib tidak dipetakan.

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

   Ikuti alur mode Recovery Apple untuk Mac Anda guna menonaktifkan SIP sebelum menjalankan imsg launch.

3. Injeksikan helper. Dengan SIP dinonaktifkan dan Messages.app sudah masuk:

   imsg launch

   imsg launch menolak melakukan injeksi ketika SIP masih aktif, jadi ini juga berfungsi sebagai konfirmasi bahwa langkah 2 berhasil.

4. Verifikasi bridge dari OpenClaw:

   openclaw channels status --probe

   Entri iMessage seharusnya melaporkan works, dan imsg status --json | jq '{rpc_methods, selectors}' seharusnya menampilkan kapabilitas yang diekspos oleh build macOS Anda. Pembuatan polling memerlukan selectors.pollPayloadMessage; voting memerlukan selectors.pollVoteMessage dan metode RPC poll.vote. Plugin OpenClaw hanya mengiklankan tindakan yang didukung oleh probe yang di-cache, sementara cache kosong tetap optimistis dan melakukan probe pada pengiriman pertama.

Jika openclaw channels status --probe melaporkan channel sebagai works tetapi tindakan tertentu melempar "iMessage <action> requires the imsg private API bridge" saat pengiriman, jalankan imsg launch lagi — helper dapat terlepas (restart Messages.app, pembaruan OS, dll.) dan status available: true yang di-cache akan terus mengiklankan tindakan sampai probe berikutnya menyegarkan status.

Ketika Anda tidak dapat menonaktifkan SIP

Jika SIP yang dinonaktifkan tidak dapat diterima untuk model ancaman Anda:

• imsg kembali ke mode dasar — teks + media + hanya menerima.
• Plugin OpenClaw masih mengiklankan pengiriman teks/media dan pemantauan masuk; Plugin hanya menyembunyikan react, edit, unsend, reply, sendWithEffect, dan operasi grup dari permukaan tindakan (sesuai gate kapabilitas per metode).
• Anda dapat menjalankan Mac non-Apple-Silicon terpisah (atau Mac bot khusus) dengan SIP mati untuk beban kerja iMessage, sambil tetap mengaktifkan SIP di perangkat utama Anda. Lihat Dedicated bot macOS user (separate iMessage identity) di bawah.

Kontrol akses dan routing

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "Use British spelling." },        "8421": {          requireMention: true,          systemPrompt: "This is the on-call rotation chat. Keep replies under 3 sentences.",        },        "9907": {          // explicit suppression: the wildcard "Use British spelling." does not apply here          systemPrompt: "",        },      },    },  },}

Binding percakapan ACP

Chat iMessage lama juga dapat diikat ke sesi ACP.

Alur operator cepat:

• Jalankan /acp spawn codex --bind here di dalam DM atau chat grup yang diizinkan.
• Pesan berikutnya dalam percakapan iMessage 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 yang dikonfigurasi didukung melalui 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> (direkomendasikan untuk binding 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 binding ACP bersama.

Pola deployment

{  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, pemotongan, dan target pengiriman

imsg chats --limit 20

Tindakan API privat

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

{  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 mengizinkan penulisan konfigurasi yang dimulai channel secara default (untuk /config set|unset saat commands.config: true).

Nonaktifkan:

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

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

Saat pengguna mengetik perintah dan URL bersama-sama — misalnya Dump https://example.com/article — aplikasi Messages Apple memecah pengiriman menjadi dua baris chat.db terpisah:

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

Kedua baris tiba di OpenClaw dengan selang ~0,8-2,0 d pada sebagian besar penyiapan. Tanpa penggabungan, agen menerima perintah saja pada giliran 1, membalas (sering kali "send me the URL"), dan baru melihat URL pada giliran 2 — saat konteks perintah sudah hilang. Ini adalah pipeline pengiriman Apple, bukan sesuatu yang diperkenalkan OpenClaw atau imsg.

channels.imessage.coalesceSameSenderDms membuat DM menggunakan buffering baris berurutan dari pengirim yang sama. Saat imsg mengekspos penanda struktural pratinjau URL balloon_bundle_id: "com.apple.messages.URLBalloonProvider" pada salah satu baris sumber, OpenClaw hanya menggabungkan split-send nyata tersebut dan mempertahankan baris buffer lain sebagai giliran terpisah. Pada build imsg lama yang sama sekali tidak memancarkan metadata gelembung, OpenClaw tidak dapat membedakan split-send dari pengiriman terpisah, sehingga fallback ke penggabungan bucket. Itu mempertahankan perilaku pra-metadata alih-alih meregresikan split-send Dump <url> menjadi dua giliran. Obrolan grup terus melakukan dispatch per pesan sehingga struktur giliran multi-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 kembali ke penggabungan lama (satu giliran): OpenClaw tidak dapat membedakan secara struktural split-send dari pengiriman terpisah, sehingga mempertahankan penggabungan pra-metadata. Pemisahan presisi aktif setelah build memancarkan metadata balon.

Pemulihan inbound setelah bridge atau gateway dimulai ulang

iMessage memulihkan pesan yang terlewat saat gateway mati, dan pada saat yang sama menekan "bom backlog" usang yang dapat digelontorkan Apple setelah pemulihan Push. Perilaku default selalu aktif, dibangun di atas dedupe inbound.

• Dedupe replay. Setiap pesan inbound yang dikirim dicatat berdasarkan GUID Apple-nya dalam status Plugin persisten (imessage.inbound-dedupe), diklaim saat ingestion dan dikomit setelah penanganan (dilepas pada kegagalan sementara agar dapat dicoba ulang). Apa pun yang sudah ditangani akan dijatuhkan, bukan dikirim dua kali. Inilah yang memungkinkan replay pemulihan berjalan agresif tanpa pembukuan per pesan.
• Pemulihan downtime. Saat startup, monitor mengingat chat.db rowid terakhir yang dikirim (kursor per akun yang dipersistenkan) dan meneruskannya ke imsg watch.subscribe sebagai since_rowid, sehingga imsg memutar ulang baris yang masuk saat gateway mati, lalu mengikuti live. Replay dibatasi ke baris terbaru dan ke pesan hingga usia ~2 jam, dan dedupe menjatuhkan apa pun yang sudah ditangani.
• Pagar usia backlog usang. Baris di atas batas startup benar-benar live; baris yang tanggal kirimnya lebih dari ~15 menit lebih lama daripada waktu kedatangannya adalah backlog Push-flush dan ditekan. Baris yang diputar ulang (di atau di bawah batas) menggunakan jendela pemulihan yang lebih lebar, sehingga pesan yang baru saja terlewat dikirim sementara riwayat kuno tidak.

Pemulihan bekerja pada setup cliPath lokal maupun jarak jauh, karena replay since_rowid berjalan melalui koneksi RPC imsg yang sama. Perbedaannya ada pada jendela: saat gateway dapat membaca chat.db (lokal), gateway menambatkan batas rowid startup, membatasi rentang replay, dan mengirim pesan yang terlewat hingga sekitar beberapa jam. Melalui cliPath SSH jarak jauh, gateway tidak dapat membaca basis data, sehingga replay tidak dibatasi dan setiap baris menggunakan pagar usia live — tetap memulihkan pesan yang baru saja terlewat dan tetap menekan backlog lama, hanya dengan jendela live yang lebih sempit. Jalankan gateway di Mac Messages untuk jendela pemulihan yang lebih lebar.

Sinyal yang terlihat operator

Backlog yang ditekan dicatat pada level default, tidak pernah dijatuhkan diam-diam (flag recovery menunjukkan jendela mana yang diterapkan):

imessage: suppressed stale inbound backlog account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; suppressed since start)

Migrasi

channels.imessage.catchup.* tidak digunakan lagi — pemulihan downtime sekarang otomatis dan tidak memerlukan konfigurasi untuk setup baru. Konfigurasi yang sudah ada dengan catchup.enabled: true tetap dihormati sebagai profil kompatibilitas untuk jendela replay pemulihan. Blok catchup yang dinonaktifkan (enabled: false atau tanpa enabled: true) sudah dipensiunkan; 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"

Penunjuk referensi konfigurasi

• Referensi konfigurasi - iMessage
• Konfigurasi Gateway
• Pairing

Terkait

• Ringkasan Kanal — semua kanal yang didukung
• Penghapusan BlueBubbles dan jalur imsg iMessage — pengumuman dan ringkasan migrasi
• Beralih dari BlueBubbles — tabel terjemahan konfigurasi dan cutover langkah demi langkah
• Pairing — autentikasi DM dan alur pairing
• Grup — perilaku obrolan grup dan gating mention
• Perutean Kanal — perutean sesi untuk pesan
• Keamanan — model akses dan hardening