iMessage (lama: imsg)

Untuk deployment iMessage baru, gunakan BlueBubbles.Integrasi imsg adalah versi lama dan mungkin akan dihapus pada rilis mendatang.

Status: integrasi CLI eksternal versi lama. Gateway memunculkan imsg rpc dan berkomunikasi melalui JSON-RPC di stdio (tanpa daemon/port terpisah).

BlueBubbles (direkomendasikan)

Jalur iMessage yang diprioritaskan untuk penyiapan baru.

Pairing

DM iMessage secara default menggunakan mode pairing.

Referensi konfigurasi

Referensi lengkap field iMessage.

Penyiapan cepat

Mac lokal (jalur cepat)
Mac jarak jauh melalui SSH

Instal dan verifikasi imsg

brew install steipete/tap/imsg
imsg rpc --help

Konfigurasikan OpenClaw

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

Mulai gateway

openclaw gateway

Setujui pairing DM pertama (dmPolicy default)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

Permintaan pairing kedaluwarsa setelah 1 jam.

OpenClaw hanya memerlukan cliPath yang kompatibel dengan stdio, jadi Anda dapat mengarahkan cliPath ke skrip pembungkus yang melakukan SSH ke Mac jarak jauh dan menjalankan imsg.

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

Konfigurasi yang direkomendasikan saat lampiran diaktifkan:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // digunakan untuk pengambilan lampiran melalui SCP
      includeAttachments: true,
      // Opsional: timpa root lampiran yang diizinkan.
      // Default mencakup /Users/*/Library/Messages/Attachments
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

Jika remoteHost tidak diatur, OpenClaw mencoba mendeteksinya secara otomatis dengan mem-parsing skrip pembungkus SSH. remoteHost harus berupa host atau user@host (tanpa spasi atau opsi SSH). OpenClaw menggunakan pemeriksaan host-key ketat untuk SCP, jadi host key relay harus sudah ada di ~/.ssh/known_hosts. Path lampiran divalidasi terhadap root yang diizinkan (attachmentRoots / remoteAttachmentRoots).

Persyaratan dan izin (macOS)

Messages harus sudah login 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.

Izin diberikan per konteks proses. Jika gateway berjalan headless (LaunchAgent/SSH), jalankan satu perintah interaktif sekali dalam konteks yang sama untuk memicu prompt:

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

Kontrol akses dan perutean

Kebijakan DM
Kebijakan grup + mention
Sesi dan balasan deterministik

channels.imessage.dmPolicy mengontrol pesan langsung:

pairing (default)
allowlist
open (mengharuskan allowFrom menyertakan "*")
disabled

Field allowlist: channels.imessage.allowFrom.Entri allowlist dapat berupa handle atau target chat (chat_id:*, chat_guid:*, chat_identifier:*).

channels.imessage.groupPolicy mengontrol penanganan grup:

allowlist (default saat dikonfigurasi)
open
disabled

Allowlist pengirim grup: channels.imessage.groupAllowFrom.Fallback runtime: jika groupAllowFrom tidak diatur, pemeriksaan pengirim grup iMessage akan fallback ke allowFrom jika tersedia. Catatan runtime: jika channels.imessage sama sekali tidak ada, runtime fallback ke groupPolicy="allowlist" dan mencatat peringatan (bahkan jika channels.defaults.groupPolicy diatur).Penyaringan mention untuk grup:

iMessage tidak memiliki metadata mention bawaan
deteksi mention menggunakan pola regex (agents.list[].groupChat.mentionPatterns, fallback messages.groupChat.mentionPatterns)
tanpa pola yang dikonfigurasi, penyaringan mention tidak dapat diberlakukan

Perintah kontrol dari pengirim yang diotorisasi dapat melewati penyaringan mention di grup.

DM menggunakan perutean langsung; grup menggunakan perutean grup.
Dengan default session.dmScope=main, DM iMessage digabungkan ke sesi utama agen.
Sesi grup diisolasi (agent:<agentId>:imessage:group:<chat_id>).
Balasan dirutekan kembali ke iMessage menggunakan metadata channel/target asal.

Perilaku thread mirip grup:Beberapa thread iMessage multi-peserta dapat datang dengan is_group=false. Jika chat_id tersebut dikonfigurasi secara eksplisit di bawah channels.imessage.groups, OpenClaw memperlakukannya sebagai lalu lintas grup (penyaringan grup + isolasi sesi grup).

Binding percakapan ACP

Chat iMessage versi 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 di percakapan iMessage yang sama akan dirutekan ke sesi ACP yang dimunculkan.
/new dan /reset mengatur ulang 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 ACP Agents untuk perilaku binding ACP bersama.

Pola deployment

Pengguna bot macOS khusus (identitas iMessage terpisah)

Gunakan Apple ID dan pengguna macOS khusus agar lalu lintas bot terisolasi dari profil Messages pribadi Anda.Alur umum:

Buat/login pengguna macOS khusus.
Login ke Messages dengan Apple ID bot pada pengguna tersebut.
Instal imsg pada pengguna tersebut.
Buat pembungkus SSH agar OpenClaw dapat menjalankan imsg dalam konteks pengguna tersebut.
Arahkan channels.imessage.accounts.<id>.cliPath dan .dbPath ke profil pengguna tersebut.

Eksekusi pertama mungkin memerlukan persetujuan GUI (Automation + Full Disk Access) pada sesi pengguna bot tersebut.

Mac jarak jauh melalui Tailscale (contoh)

Topologi umum:

gateway berjalan di Linux/VM
iMessage + imsg berjalan di Mac dalam tailnet Anda
pembungkus cliPath menggunakan SSH untuk menjalankan imsg
remoteHost mengaktifkan pengambilan lampiran melalui SCP

Contoh:

{
  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 "$@"

Gunakan SSH key agar SSH dan SCP sama-sama non-interaktif. Pastikan host key sudah dipercaya terlebih dahulu (misalnya ssh bot@mac-mini.tailnet-1234.ts.net) agar known_hosts terisi.

Pola multi-akun

iMessage mendukung konfigurasi per akun di bawah channels.imessage.accounts.Setiap akun dapat menimpa field seperti cliPath, dbPath, allowFrom, groupPolicy, mediaMaxMb, pengaturan riwayat, dan allowlist root lampiran.

Media, pemotongan, dan target pengiriman

Lampiran dan media

ingest lampiran masuk bersifat opsional: channels.imessage.includeAttachments
path lampiran jarak jauh dapat diambil melalui SCP saat remoteHost diatur
path lampiran harus cocok dengan root yang diizinkan:
- channels.imessage.attachmentRoots (lokal)
- channels.imessage.remoteAttachmentRoots (mode SCP jarak jauh)
- pola root default: /Users/*/Library/Messages/Attachments
SCP menggunakan pemeriksaan host-key ketat (StrictHostKeyChecking=yes)
ukuran media keluar menggunakan channels.imessage.mediaMaxMb (default 16 MB)

Pemotongan keluar

batas potongan teks: channels.imessage.textChunkLimit (default 4000)
mode potongan: channels.imessage.chunkMode
- length (default)
- newline (pemisahan dengan paragraf terlebih dahulu)

Format pengalamatan

Target eksplisit yang direkomendasikan:

chat_id:123 (direkomendasikan untuk perutean yang stabil)
chat_guid:...
chat_identifier:...

Target handle juga didukung:

imessage:+1555...
sms:+1555...
user@example.com

imsg chats --limit 20

Penulisan konfigurasi

iMessage mengizinkan penulisan konfigurasi yang dimulai dari channel secara default (untuk /config set|unset saat commands.config: true). Nonaktifkan:

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

Pemecahan masalah

imsg tidak ditemukan atau RPC tidak didukung

Validasi biner dan dukungan RPC:

imsg rpc --help
openclaw channels status --probe

Jika probe melaporkan RPC tidak didukung, perbarui imsg.

DM diabaikan

Periksa:

channels.imessage.dmPolicy
channels.imessage.allowFrom
persetujuan pairing (openclaw pairing list imessage)

Pesan grup diabaikan

Periksa:

channels.imessage.groupPolicy
channels.imessage.groupAllowFrom
perilaku allowlist channels.imessage.groups
konfigurasi pola mention (agents.list[].groupChat.mentionPatterns)

Lampiran jarak jauh gagal

Periksa:

channels.imessage.remoteHost
channels.imessage.remoteAttachmentRoots
autentikasi key SSH/SCP dari host gateway
host key ada di ~/.ssh/known_hosts pada host gateway
keterbacaan path jarak jauh pada Mac yang menjalankan Messages

Prompt izin macOS terlewat

Jalankan ulang di terminal GUI interaktif dalam konteks pengguna/sesi yang sama dan setujui prompt:

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

Pastikan Full Disk Access + Automation telah diberikan untuk konteks proses yang menjalankan OpenClaw/imsg.

Penunjuk referensi konfigurasi

Terkait

Ikhtisar Channel — semua channel yang didukung
Pairing — autentikasi DM dan alur pairing
Grup — perilaku chat grup dan penyaringan mention
Perutean Channel — perutean sesi untuk pesan
Keamanan — model akses dan hardening

Overview

Messaging platforms

Configuration

iMessage

iMessage (lama: imsg)

BlueBubbles (direkomendasikan)

Pairing

Referensi konfigurasi

Penyiapan cepat

Persyaratan dan izin (macOS)

Kontrol akses dan perutean

Binding percakapan ACP

Pola deployment

Media, pemotongan, dan target pengiriman

Penulisan konfigurasi

Pemecahan masalah

Penunjuk referensi konfigurasi

Terkait

Overview

Messaging platforms

Configuration

​iMessage (lama: imsg)

BlueBubbles (direkomendasikan)

Pairing

Referensi konfigurasi

​Penyiapan cepat

​Persyaratan dan izin (macOS)

​Kontrol akses dan perutean

​Binding percakapan ACP

​Pola deployment

​Media, pemotongan, dan target pengiriman

​Penulisan konfigurasi

​Pemecahan masalah

​Penunjuk referensi konfigurasi

​Terkait

iMessage (lama: imsg)

Penyiapan cepat

Persyaratan dan izin (macOS)

Kontrol akses dan perutean

Binding percakapan ACP

Pola deployment

Media, pemotongan, dan target pengiriman

Penulisan konfigurasi

Pemecahan masalah

Penunjuk referensi konfigurasi

Terkait