iMessage

​

Penyiapan cepat

brew install steipete/tap/imsg
brew update && brew upgrade imsg
imsg rpc --help
imsg launch
openclaw channels status --probe

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

openclaw gateway

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

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

#!/usr/bin/env bash
exec 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.

imsg chats --limit 1
# atau
imsg send <handle> "uji"

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

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

​

Mengaktifkan API privat imsg

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

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.

​

Penyiapan

1. Instal (atau tingkatkan) imsg di Mac yang menjalankan Messages.app:
   brew install steipete/tap/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg 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.

​

Saat SIP tetap diaktifkan

• 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: { "*": { "requireMention": true } },
    },
  },
}

{
  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

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

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

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

​

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 bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

​

Media, pemenggalan, dan target pengiriman

imsg chats --limit 20

​

Tindakan API privat

{
  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

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

​

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

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

{
  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

​

Pemulihan masuk setelah bridge atau Gateway dimulai ulang

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

​

Sinyal yang terlihat oleh operator

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

​

Migrasi

​

Pemecahan masalah

imsg rpc --help
imsg status --json
openclaw channels status --probe

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

launchctl kickstart -k system/com.apple.apsd
launchctl kickstart -k gui/$(id -u)/com.apple.CommCenter
launchctl kickstart -k gui/$(id -u)/com.apple.identityservicesd
launchctl kickstart -k gui/$(id -u)/com.apple.imagent
imsg launch
openclaw gateway restart

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

openclaw channels status --probe --channel imessage

imsg chats --limit 1
imsg 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