iMessage

Status: integrasi CLI eksternal native. Gateway menjalankan imsg rpc dan berkomunikasi melalui JSON-RPC pada stdio (tanpa daemon/port terpisah). Tindakan lanjutan memerlukan imsg launch dan probe API privat 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 / threaded reply / effects / group ops), System Integrity Protection harus dinonaktifkan — lihat Mengaktifkan API privat imsg di bawah. Kirim/terima teks dan media dasar berfungsi tanpanya.

Mengaktifkan API privat imsg

imsg hadir 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 API privat: imsg menyuntikkan dylib helper ke Messages.app untuk memanggil fungsi internal IMCore. Ini yang membuka react, edit, unsend, reply (berutas), sendWithEffect, renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, plus indikator mengetik dan tanda dibaca.

Untuk mencapai permukaan tindakan lanjutan yang didokumentasikan halaman channel ini, Anda memerlukan mode API privat. README imsg menyatakan persyaratan tersebut dengan jelas:

Fitur lanjutan seperti read, typing, launch, rich send yang didukung bridge, mutasi pesan, dan manajemen chat bersifat opt-in. Fitur tersebut memerlukan SIP dinonaktifkan dan dylib helper disuntikkan ke Messages.app. imsg launch menolak melakukan injeksi saat SIP aktif.

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

Penyiapan

1. Instal (atau tingkatkan) imsg pada 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 mulai.

2. Nonaktifkan System Integrity Protection. Ini spesifik versi macOS karena persyaratan Apple yang mendasarinya bergantung pada OS dan perangkat keras:

   • macOS 10.13–10.15 (Sierra–Catalina): nonaktifkan Library Validation melalui Terminal, reboot ke Recovery Mode, jalankan csrutil disable, restart.
   • macOS 11+ (Big Sur dan lebih baru), Intel: Recovery Mode (atau Internet Recovery), csrutil disable, restart.
   • macOS 11+, Apple Silicon: urutan startup tombol daya untuk masuk Recovery; pada versi macOS terbaru tahan tombol Left Shift saat Anda mengeklik Continue, lalu csrutil disable. Penyiapan mesin virtual mengikuti alur terpisah — ambil snapshot VM terlebih dahulu.
   • macOS 26 / Tahoe: kebijakan library-validation dan pemeriksaan private-entitlement imagent makin diperketat; imsg mungkin memerlukan build yang diperbarui untuk mengikutinya. Jika injeksi imsg launch atau selectors tertentu mulai mengembalikan false setelah upgrade mayor macOS, periksa catatan rilis imsg sebelum mengasumsikan langkah SIP berhasil.

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

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

   imsg launch

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

4. Verifikasi bridge dari OpenClaw:

   openclaw channels status --probe

   Entri iMessage harus melaporkan works, dan imsg status --json | jq '.selectors' harus menampilkan retractMessagePart: true plus selector edit / typing / read apa pun yang diekspos build macOS Anda. Gating per metode Plugin OpenClaw di actions.ts hanya mengiklankan tindakan yang selector dasarnya bernilai true, sehingga permukaan tindakan yang Anda lihat di daftar alat agent mencerminkan apa yang benar-benar dapat dilakukan bridge pada host ini.

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

Saat Anda tidak dapat menonaktifkan SIP

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

• imsg fallback ke mode dasar — hanya teks + media + terima.
• Plugin OpenClaw tetap mengiklankan kirim teks/media dan pemantauan masuk; Plugin hanya menyembunyikan react, edit, unsend, reply, sendWithEffect, dan operasi grup dari permukaan tindakan (sesuai gate kemampuan 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 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: "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 legacy 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 ternormalisasi seperti +15555550123 atau [email protected]
• 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: "[email protected]",      includeAttachments: true,      dbPath: "/Users/bot/Library/Messages/chat.db",    },  },}

#!/usr/bin/env bashexec ssh -T [email protected] imsg "$@"

Media, chunking, dan target pengiriman

imsg chats --limit 20

Aksi API privat

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

{  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,      },    },  },}

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

Penulisan konfigurasi

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

Nonaktifkan:

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

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

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

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

Dua baris tiba di OpenClaw dengan selisih sekitar 0,8-2,0 dtk pada sebagian besar penyiapan. Tanpa penggabungan, agen menerima perintah saja pada giliran 1, membalas (sering kali "kirim URL-nya"), dan baru melihat URL pada giliran 2 — pada titik itu konteks perintah sudah hilang. Ini adalah alur pengiriman Apple, bukan sesuatu yang diperkenalkan oleh OpenClaw atau imsg.

channels.imessage.coalesceSameSenderDms mengikutsertakan DM untuk menggabungkan baris berurutan dari pengirim yang sama menjadi satu giliran agen. Obrolan grup tetap dikirim per pesan agar struktur giliran multi-pengguna tetap dipertahankan.

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

{  messages: {    inbound: {      byChannel: {        // 2500 ms works for most setups; raise to 4000 ms if your Mac is        // slow or under memory pressure (observed gap can stretch past 2 s        // then).        imessage: 2500,      },    },  },}

Skenario dan apa yang dilihat agen

Mengejar ketertinggalan setelah Gateway tidak aktif

Ketika Gateway offline (crash, restart, Mac sleep, mesin mati), imsg watch melanjutkan dari status chat.db saat ini setelah Gateway kembali aktif — apa pun yang tiba selama jeda, secara default, tidak pernah terlihat. Catchup memutar ulang pesan-pesan tersebut pada startup berikutnya sehingga agen tidak diam-diam melewatkan lalu lintas masuk.

Catchup dinonaktifkan secara default. Aktifkan per kanal:

channels: {  imessage: {    catchup: {      enabled: true,             // master switch (default: false)      maxAgeMinutes: 120,        // skip rows older than now - 2h (default: 120, clamp 1..720)      perRunLimit: 50,           // max rows replayed per startup (default: 50, clamp 1..500)      firstRunLookbackMinutes: 30, // first run with no cursor: look back 30 min (default: 30)      maxFailureRetries: 10,     // give up on a wedged guid after 10 dispatch failures (default: 10)    },  },}

Cara kerjanya

Satu lintasan per startup monitorIMessageProvider, diurutkan sebagai imsg launch siap → watch.subscribe → performIMessageCatchup → loop pengiriman langsung. Catchup sendiri menggunakan chats.list + messages.history per obrolan terhadap klien JSON-RPC yang sama dengan yang digunakan oleh imsg watch. Apa pun yang tiba selama lintasan catchup mengalir melalui pengiriman langsung secara normal; cache dedupe masuk yang ada menyerap tumpang tindih apa pun dengan baris yang diputar ulang.

Setiap baris yang diputar ulang dimasukkan melalui jalur pengiriman langsung (evaluateIMessageInbound + dispatchInboundMessage), sehingga daftar izin, kebijakan grup, debouncer, cache echo, dan tanda dibaca berperilaku identik pada pesan yang diputar ulang dan pesan langsung.

Semantik kursor dan percobaan ulang

Catchup menyimpan kursor per akun di <openclawStateDir>/imessage/catchup/<account>__<hash>.json (direktori status OpenClaw default ke ~/.openclaw, dapat ditimpa dengan OPENCLAW_STATE_DIR):

{  "lastSeenMs": 1717900800000,  "lastSeenRowid": 482910,  "updatedAt": 1717900801234,  "failureRetries": { "<guid>": 1 }}

• Kursor maju pada setiap pengiriman yang berhasil dan ditahan ketika pengiriman sebuah baris melempar error — startup berikutnya mencoba ulang baris yang sama dari kursor yang ditahan.
• Setelah maxFailureRetries lemparan berturut-turut terhadap guid yang sama, catchup mencatat warn dan memaksa kursor maju melewati pesan yang macet sehingga startup berikutnya dapat terus berjalan.
• GUID yang sudah diserahkan dilewati saat terlihat (tanpa percobaan pengiriman) pada run berikutnya dan dihitung di bawah skippedGivenUp dalam ringkasan run.

Sinyal yang terlihat operator

imessage catchup: replayed=N skippedFromMe=… skippedGivenUp=… failed=… givenUp=… fetchedCount=…imessage catchup: giving up on guid=<guid> after &lt;N&gt; failures; advancing cursor past itimessage catchup: fetched &lt;X&gt; rows across chats, capped to perRunLimit=&lt;Y&gt;

Baris WARN ... capped to perRunLimit berarti satu startup tidak mengosongkan seluruh backlog. Naikkan perRunLimit (maks 500) jika jeda Anda secara rutin melebihi lintasan default 50 baris.

Kapan membiarkannya nonaktif

• Gateway berjalan terus-menerus dengan restart otomatis watchdog dan jeda selalu < beberapa detik — default nonaktif sudah cukup.
• Volume DM rendah dan pesan yang terlewat tidak akan mengubah perilaku agen — jendela awal firstRunLookbackMinutes dapat mengirim konteks lama yang mengejutkan saat pertama kali diaktifkan.

Ketika Anda mengaktifkan catchup, startup pertama tanpa kursor hanya melihat mundur sejauh firstRunLookbackMinutes (default 30 mnt), bukan seluruh jendela maxAgeMinutes — ini menghindari pemutaran ulang riwayat panjang pesan sebelum fitur diaktifkan.

Pemecahan masalah

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

#!/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

• Ikhtisar 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