Mainstream messaging

iMessage

Status: integrasi CLI eksternal native. Gateway menjalankan imsg rpc dan berkomunikasi melalui JSON-RPC pada stdio (tanpa daemon/port terpisah).

BlueBubbles (fallback legacy)

Tetap gunakan ini untuk routing yang sudah ada berbasis BlueBubbles; hindari untuk setup baru saat imsg sesuai.

Pairing

DM iMessage secara default menggunakan mode pairing.

Referensi konfigurasi

Referensi lengkap field iMessage.

Setup cepat

Mac lokal (jalur cepat)

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/user/Library/Messages/chat.db",
},
},
}

Mulai gateway

openclaw gateway

Setujui pairing DM pertama (dmPolicy default)

openclaw pairing list imessage
openclaw pairing approve imessage &lt;CODE&gt;

Permintaan pairing kedaluwarsa setelah 1 jam.

Mac jarak jauh melalui SSH

OpenClaw hanya memerlukan cliPath yang kompatibel dengan stdio, sehingga Anda dapat mengarahkan cliPath ke skrip wrapper 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", // 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"],
},
},
}

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

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.

Tip

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

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

Kontrol akses dan routing

Kebijakan DM

channels.imessage.dmPolicy mengontrol pesan langsung:

pairing (default)
allowlist
open (memerlukan allowFrom untuk menyertakan "*")
disabled

Field allowlist: channels.imessage.allowFrom.

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

Kebijakan grup + sebutan

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 bila tersedia. Catatan runtime: jika channels.imessage sepenuhnya tidak ada, runtime akan fallback ke groupPolicy="allowlist" dan mencatat peringatan (meskipun channels.defaults.groupPolicy diatur).

Pembatasan sebutan untuk grup:

iMessage tidak memiliki metadata sebutan native
deteksi sebutan menggunakan pola regex (agents.list[].groupChat.mentionPatterns, fallback messages.groupChat.mentionPatterns)
tanpa pola yang dikonfigurasi, pembatasan sebutan tidak dapat diterapkan

Perintah kontrol dari pengirim yang berwenang dapat melewati pembatasan sebutan dalam grup.

Sesi dan balasan deterministik

DM menggunakan routing langsung; grup menggunakan routing 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 dengan banyak peserta dapat tiba dengan is_group=false. Jika chat_id tersebut dikonfigurasi secara eksplisit di bawah channels.imessage.groups, OpenClaw memperlakukannya sebagai traffic grup (pembatasan grup + isolasi sesi grup).

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

Pengguna macOS bot khusus (identitas iMessage terpisah)

Gunakan Apple ID dan pengguna macOS khusus agar traffic bot diisolasi dari profil Messages pribadi Anda.

Alur umum:

Buat/masuk sebagai pengguna macOS khusus.
Masuk ke Messages dengan Apple ID bot dalam pengguna tersebut.
Instal imsg dalam pengguna tersebut.
Buat wrapper 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) dalam 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
wrapper cliPath menggunakan SSH untuk menjalankan imsg
remoteHost mengaktifkan pengambilan lampiran SCP

Contoh:

{
channels: {
imessage: {
  enabled: true,
  cliPath: "~/.openclaw/scripts/imsg-ssh",
  remoteHost: "[email protected]",
  includeAttachments: true,
  dbPath: "/Users/bot/Library/Messages/chat.db",
},
},
}

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

Gunakan kunci SSH agar SSH dan SCP sama-sama non-interaktif. Pastikan kunci host dipercaya terlebih dahulu (misalnya ssh [email protected]) agar known_hosts terisi.

Pola multi-akun

iMessage mendukung konfigurasi per akun di bawah channels.imessage.accounts.

Setiap akun dapat mengganti field seperti cliPath, dbPath, allowFrom, groupPolicy, mediaMaxMb, pengaturan riwayat, dan allowlist root lampiran.

Media, chunking, dan target pengiriman

Lampiran dan media

ingest lampiran masuk bersifat opsional: channels.imessage.includeAttachments
jalur lampiran jarak jauh dapat diambil melalui SCP saat remoteHost diatur
jalur 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)

Chunking keluar

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

Format pengalamatan

Target eksplisit yang direkomendasikan:

chat_id:123 (direkomendasikan untuk routing stabil)
chat_guid:...
chat_identifier:...

Target handle juga didukung:

imessage:+1555...
sms:+1555...
[email protected]

imsg chats --limit 20

Penulisan konfigurasi

iMessage mengizinkan penulisan konfigurasi yang dimulai oleh 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 binary 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 sebutan (agents.list[].groupChat.mentionPatterns)

Lampiran jarak jauh gagal

Periksa:

channels.imessage.remoteHost
channels.imessage.remoteAttachmentRoots
autentikasi kunci SSH/SCP dari host gateway
kunci host ada di ~/.ssh/known_hosts pada host gateway
keterbacaan jalur 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"

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

Pointer referensi konfigurasi

Terkait

Ikhtisar Saluran — semua saluran yang didukung
Penyandingan — autentikasi DM dan alur penyandingan
Grup — perilaku chat grup dan pembatasan penyebutan
Perutean Saluran — perutean sesi untuk pesan
Keamanan — model akses dan penguatan keamanan

# Setup cepat

Mac lokal (jalur cepat)

Instal dan verifikasi imsg

Konfigurasikan OpenClaw

Mulai gateway

Setujui pairing DM pertama (dmPolicy default)

Mac jarak jauh melalui SSH

# Persyaratan dan izin (macOS)

# Kontrol akses dan routing

Kebijakan DM

Kebijakan grup + sebutan

Sesi dan balasan deterministik

# Binding percakapan ACP

# Pola deployment

# Media, chunking, dan target pengiriman

# Penulisan konfigurasi

# Pemecahan masalah

# Pointer referensi konfigurasi

# Terkait

Setup cepat

Persyaratan dan izin (macOS)

Kontrol akses dan routing

Binding percakapan ACP

Pola deployment

Media, chunking, dan target pengiriman

Penulisan konfigurasi

Pemecahan masalah

Pointer referensi konfigurasi

Terkait