iMessage

​

Penyiapan cepat

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

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

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

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

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

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.

​

Penyiapan

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

​

Ketika Anda tidak dapat menonaktifkan SIP

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

{
  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

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

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

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

​

Media, pemotongan, 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 split-send (perintah + URL dalam satu komposisi)

1. Pesan teks ("Dump").
2. Gelembung 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 inbound setelah bridge atau gateway dimulai ulang

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

​

Sinyal yang terlihat operator

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

​

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"

​

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