iMessage

Durum: yerel harici CLI entegrasyonu. Gateway imsg rpc sürecini başlatır ve stdio üzerinde JSON-RPC ile iletişim kurar (ayrı daemon/port yoktur). Gelişmiş eylemler imsg launch ve başarılı bir özel API yoklaması gerektirir.

Hızlı kurulum

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

Gereksinimler ve izinler (macOS)

• imsg çalıştıran Mac üzerinde Messages oturumu açılmış olmalıdır.
• OpenClaw/imsg çalıştıran süreç bağlamı için Tam Disk Erişimi gereklidir (Messages DB erişimi).
• Messages.app üzerinden ileti göndermek için Otomasyon izni gereklidir.
• Gelişmiş eylemler için (tepki / düzenleme / göndermeyi geri alma / konu içinde yanıt / efektler / anketler / grup işlemleri), Sistem Bütünlüğü Koruması devre dışı bırakılmalıdır — aşağıdaki imsg özel API'sini etkinleştirme bölümüne bakın. Temel metin ve medya gönderme/alma bunun olmadan çalışır.

Not authorized to send Apple events to Messages. (-1743)

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

imsg özel API'sini etkinleştirme

imsg iki çalışma moduyla gelir:

• Temel mod (varsayılan, SIP değişikliği gerekmez): send üzerinden giden metin ve medya, gelen izleme/geçmiş, sohbet listesi. Yeni bir brew install steipete/tap/imsg kurulumundan ve yukarıdaki standart macOS izinlerinden sonra kutudan çıktığı gibi elde ettiğiniz budur.
• Özel API modu: imsg, dahili IMCore işlevlerini çağırmak için Messages.app içine bir yardımcı dylib enjekte eder. Bu, react, edit, unsend, reply (konu içinde), sendWithEffect, poll ve poll-vote (yerel Messages anketleri), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup ile yazıyor göstergelerini ve okundu bilgilerini açar.

Bu kanal sayfasının belgelediği gelişmiş eylem yüzeyine ulaşmak için Özel API modu gerekir. imsg README gereksinim konusunda açıktır:

read, typing, launch, köprü destekli zengin gönderim, ileti mutasyonu ve sohbet yönetimi gibi gelişmiş özellikler isteğe bağlıdır. SIP'in devre dışı bırakılmasını ve Messages.app içine bir yardımcı dylib enjekte edilmesini gerektirir. SIP etkin olduğunda imsg launch enjeksiyonu reddeder.

Yardımcı enjeksiyon tekniği, Messages özel API'lerine erişmek için imsg'nin kendi dylib'ini kullanır. OpenClaw iMessage yolunda üçüncü taraf sunucu veya BlueBubbles çalışma zamanı yoktur.

Kurulum

1. Messages.app çalıştıran Mac üzerinde imsg yükleyin (veya yükseltin):

   brew install steipete/tap/imsgimsg --versionimsg status --json

   imsg status --json çıktısı bridge_version, rpc_methods ve yöntem başına selectors bildirir; böylece başlamadan önce geçerli derlemenin neyi desteklediğini görebilirsiniz.

2. Sistem Bütünlüğü Koruması'nı ve (modern macOS'ta) Kitaplık Doğrulamasını devre dışı bırakın. Apple imzalı Messages.app içine Apple olmayan bir yardımcı dylib enjekte etmek için SIP'in kapalı olması ve kitaplık doğrulamasının gevşetilmesi gerekir. Recovery-mode SIP adımı macOS sürümüne özeldir:

   • macOS 10.13-10.15 (Sierra-Catalina): Kitaplık Doğrulamasını Terminal üzerinden devre dışı bırakın, Recovery Mode'a yeniden başlatın, csrutil disable çalıştırın, yeniden başlatın.
   • macOS 11+ (Big Sur ve sonrası), Intel: Recovery Mode (veya Internet Recovery), csrutil disable, yeniden başlatın.
   • macOS 11+, Apple Silicon: Recovery'ye girmek için güç düğmesi başlangıç dizisini kullanın; son macOS sürümlerinde Continue'a tıklarken Left Shift tuşunu basılı tutun, ardından csrutil disable çalıştırın. Sanal makine kurulumları ayrı bir akış izler; bu nedenle önce bir VM anlık görüntüsü alın.

   macOS 11 ve sonrasında, yalnızca csrutil disable genellikle yeterli değildir. Apple, Messages.app bir platform ikilisi olduğundan kitaplık doğrulamasını hâlâ uygular; bu nedenle adhoc imzalı bir yardımcı, SIP kapalı olsa bile reddedilir (Library Validation failed: ... platform binary, but mapped file is not). SIP'i devre dışı bıraktıktan sonra kitaplık doğrulamasını da devre dışı bırakın ve yeniden başlatın:

   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true

   macOS 26 (Tahoe), 26.5.1 üzerinde doğrulandı: SIP kapalı artı yukarıdaki DisableLibraryValidation komutu, yardımcının 26.0'dan 26.5.x'e kadar enjekte edilmesi için yeterlidir. boot-args gerekmez. plist belirleyici etkendir ve Tahoe'da enjeksiyon başarısız olduğunda en sık eksik olan adımdır:

   • plist ile: imsg launch enjekte eder ve imsg status, advanced_features: true bildirir.
   • plist olmadan (SIP kapalı olsa bile): imsg launch, Failed to launch: Timeout waiting for Messages.app to initialize ile başarısız olur. AMFI, adhoc yardımcıyı yükleme sırasında reddeder; bu nedenle köprü hiçbir zaman hazır olmaz ve başlatma zaman aşımına uğrar. Tahoe'da çoğu kişinin karşılaştığı belirti bu zaman aşımıdır ve düzeltme yukarıdaki plist'tir, daha sert bir şey değil.

   Bu, macOS 26.5.1 (Apple Silicon) üzerinde kontrollü bir önce/sonra ile doğrulandı: plist varken dylib Messages.app içine eşlenir ve köprü çalışır; plist'i kaldırıp yeniden başlatınca imsg launch, dylib eşlenmeden yukarıdaki zaman aşımı hatasını üretir.

   If imsg launch enjeksiyonu veya belirli selectors değerleri bir macOS yükseltmesinden sonra false döndürmeye başlarsa, olağan neden bu geçittir. SIP ve library-validation durumunuzu, SIP adımının kendisinin başarısız olduğunu varsaymadan önce kontrol edin. Bu ayarlar doğruysa ve köprü hâlâ enjekte edemiyorsa, imsg status --json ile imsg launch çıktısını toplayın ve ek sistem genelindeki güvenlik denetimlerini zayıflatmak yerine bunu imsg projesine bildirin.

   imsg launch çalıştırmadan önce SIP'yi devre dışı bırakmak için Apple'ın Mac'inize yönelik Recovery-mode akışını izleyin.

3. Yardımcıyı enjekte edin. SIP devre dışıyken ve Messages.app oturum açmış durumdayken:

   imsg launch

   imsg launch, SIP hâlâ etkin olduğunda enjeksiyonu reddeder; bu nedenle bu, 2. adımın uygulandığına dair bir doğrulama işlevi de görür.

4. Köprüyü OpenClaw'dan doğrulayın:

   openclaw channels status --probe

   iMessage girdisi works bildirmeli ve imsg status --json | jq '{rpc_methods, selectors}' macOS derlemenizin sunduğu yetenekleri göstermelidir. Anket oluşturma selectors.pollPayloadMessage gerektirir; oy verme hem selectors.pollVoteMessage hem de poll.vote RPC yöntemini gerektirir. OpenClaw Plugin yalnızca önbelleğe alınmış yoklamanın desteklediği eylemleri duyurur; boş bir önbellek ise iyimser kalır ve ilk gönderimde yoklama yapar.

openclaw channels status --probe kanalı works olarak bildiriyor ancak belirli eylemler gönderim sırasında "iMessage <action> requires the imsg private API bridge" hatası veriyorsa, imsg launch komutunu yeniden çalıştırın — yardımcı devreden çıkabilir (Messages.app yeniden başlatması, işletim sistemi güncellemesi vb.) ve önbelleğe alınmış available: true durumu, bir sonraki yoklama yenilenene kadar eylemleri duyurmaya devam eder.

SIP'yi devre dışı bırakamadığınızda

SIP'nin devre dışı olması tehdit modeliniz için kabul edilebilir değilse:

• imsg temel moda geri döner — yalnızca metin + medya + alma.
• OpenClaw Plugin, metin/medya gönderimini ve gelen izlemeyi duyurmaya devam eder; yalnızca react, edit, unsend, reply, sendWithEffect ve grup işlemlerini eylem yüzeyinden gizler (yöntem başına yetenek geçidine göre).
• Birincil cihazlarınızda SIP'yi etkin tutarken, iMessage iş yükü için SIP kapalı ayrı bir Apple Silicon olmayan Mac (veya ayrılmış bir bot Mac) çalıştırabilirsiniz. Aşağıdaki Dedicated bot macOS user (separate iMessage identity) bölümüne bakın.

Erişim denetimi ve yönlendirme

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

ACP konuşma bağlamaları

Eski iMessage sohbetleri ACP oturumlarına da bağlanabilir.

Hızlı operatör akışı:

• DM veya izin verilen grup sohbeti içinde /acp spawn codex --bind here çalıştırın.
• Aynı iMessage konuşmasındaki gelecekteki mesajlar, oluşturulan ACP oturumuna yönlendirilir.
• /new ve /reset aynı bağlı ACP oturumunu yerinde sıfırlar.
• /acp close ACP oturumunu kapatır ve bağlamayı kaldırır.

Yapılandırılmış kalıcı bağlamalar, type: "acp" ve match.channel: "imessage" içeren üst düzey bindings[] girdileri aracılığıyla desteklenir.

match.peer.id şunları kullanabilir:

• +15555550123 veya user@example.com gibi normalleştirilmiş DM tanıtıcısı
• chat_id:<id> (kararlı grup bağlamaları için önerilir)
• chat_guid:<guid>
• chat_identifier:<identifier>

Örnek:

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

Paylaşılan ACP bağlama davranışı için ACP Agents bölümüne bakın.

Dağıtım kalıpları

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

Medya, parçalama ve teslim hedefleri

imsg chats --limit 20

Özel API eylemleri

imsg launch çalışırken ve openclaw channels status --probe çıktısı privateApi.available: true bildirirken, ileti aracı normal metin göndermelerine ek olarak iMessage'a özgü eylemleri kullanabilir.

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

Yapılandırma yazmaları

iMessage, kanal tarafından başlatılan yapılandırma yazmalarına varsayılan olarak izin verir (commands.config: true olduğunda /config set|unset için).

Devre dışı bırakma:

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

Bölünmüş gönderimli DM'leri birleştirme (tek kompozisyonda komut + URL)

Bir kullanıcı bir komut ve URL'yi birlikte yazdığında — ör. Dump https://example.com/article — Apple'ın Messages uygulaması gönderimi iki ayrı chat.db satırına böler:

1. Bir metin iletisi ("Dump").
2. OG önizleme görsellerinin ek olarak bulunduğu bir URL önizleme balonu ("https://...").

İki satır çoğu kurulumda OpenClaw'a yaklaşık 0.8-2.0 sn arayla ulaşır. Birleştirme olmadan, ajan 1. turda yalnızca komutu alır, yanıt verir (çoğu zaman "URL'yi bana gönder" der) ve URL'yi ancak 2. turda görür — o noktada komut bağlamı zaten kaybolmuştur. Bu, Apple'ın gönderim işlem hattıdır; OpenClaw veya imsg tarafından eklenen bir şey değildir.

channels.imessage.coalesceSameSenderDms, bir DM'yi aynı gönderenden gelen ardışık satırları arabelleğe almaya dahil eder. imsg, kaynak satırlardan birinde yapısal URL önizleme işaretçisi balloon_bundle_id: "com.apple.messages.URLBalloonProvider" değerini sunduğunda, OpenClaw yalnızca bu gerçek bölünmüş gönderimi birleştirir ve arabelleğe alınmış diğer satırları ayrı turlar olarak tutar. Hiç balon meta verisi yaymayan daha eski imsg derlemelerinde OpenClaw, bölünmüş gönderimi ayrı gönderimlerden ayırt edemez; bu yüzden kovayı birleştirmeye geri döner. Bu, Dump <url> bölünmüş gönderimlerini iki tura geriletmek yerine meta veri öncesi davranışı korur. Grup sohbetleri, çok kullanıcılı tur yapısının korunması için ileti başına gönderilmeye devam eder.

{  channels: {    imessage: {      coalesceSameSenderDms: true, // dahil ol (varsayılan: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 7000 ms, gözlemlenen Messages.app URL önizleme gecikmelerini kapsar.        imessage: 7000,      },    },  },}

Senaryolar ve aracının gördükleri

"Bayrak açık" sütunu, balloon_bundle_id yayan bir imsg derlemesindeki davranışı gösterir. Hiç balon metaverisi yaymayan eski imsg derlemelerinde, aşağıda "İki tur" / "N tur" olarak işaretlenen satırlar bunun yerine eski bir birleştirmeye (tek tur) geri döner: OpenClaw, bölünmüş gönderimi ayrı gönderimlerden yapısal olarak ayırt edemez, bu yüzden metaveri öncesi birleştirmeyi korur. Kesin ayırma, derleme balon metaverisi yaymaya başladığında etkinleşir.

Köprü veya Gateway yeniden başlatıldıktan sonra gelen ileti kurtarma

iMessage, Gateway kapalıyken kaçırılan iletileri kurtarır ve aynı anda Apple'ın bir Push kurtarmasından sonra boşaltabileceği bayat "birikmiş işler bombası"nı bastırır. Varsayılan davranış her zaman açıktır ve gelen tekilleştirme üzerine kuruludur.

• Yeniden oynatma tekilleştirmesi. Gönderilen her gelen ileti, Apple GUID'iyle kalıcı Plugin durumuna (imessage.inbound-dedupe) kaydedilir; alım sırasında sahiplenilir ve işlendikten sonra işlenmiş olarak kaydedilir (geçici hatada yeniden deneyebilmesi için serbest bırakılır). Zaten işlenmiş olan her şey, iki kez gönderilmek yerine düşürülür. Kurtarmanın ileti başına defter tutmadan agresif biçimde yeniden oynatabilmesini sağlayan şey budur.
• Kesinti süresi kurtarması. Başlangıçta izleyici, son gönderilen chat.db rowid değerini (hesap başına kalıcı imleç) hatırlar ve bunu since_rowid olarak imsg watch.subscribe öğesine geçirir; böylece imsg, Gateway kapalıyken gelen satırları yeniden oynatır ve ardından canlı kuyruğu izler. Yeniden oynatma en son satırlarla ve yaklaşık 2 saate kadar eski iletilerle sınırlıdır; tekilleştirme de zaten işlenmiş olan her şeyi düşürür.
• Bayat birikmiş işler yaş sınırı. Başlangıç sınırının üzerindeki satırlar gerçekten canlıdır; gönderim tarihi varışından yaklaşık 15 dakikadan daha eski olanlar Push boşaltma birikmiş işleridir ve bastırılır. Yeniden oynatılan satırlar (sınırda veya altında olanlar) bunun yerine daha geniş kurtarma penceresini kullanır; böylece yakın zamanda kaçırılan bir ileti teslim edilirken kadim geçmiş teslim edilmez.

Kurtarma hem yerel hem uzak cliPath kurulumlarında çalışır, çünkü since_rowid yeniden oynatması aynı imsg RPC bağlantısı üzerinden yürür. Fark pencerededir: Gateway chat.db okuyabildiğinde (yerel), başlangıç rowid sınırını sabitler, yeniden oynatma aralığını sınırlar ve birkaç saate kadar eski kaçırılmış iletileri teslim eder. Uzak SSH cliPath üzerinden veritabanını okuyamaz; bu yüzden yeniden oynatma sınırsızdır ve her satır canlı yaş sınırını kullanır — yakın zamanda kaçırılan iletileri yine kurtarır ve eski birikmiş işleri yine bastırır, yalnızca daha dar canlı pencereyle. Daha geniş kurtarma penceresi için Gateway'i Messages Mac üzerinde çalıştırın.

Operatöre görünen sinyal

Bastırılan birikmiş işler varsayılan düzeyde günlüklenir, asla sessizce düşürülmez (recovery bayrağı hangi pencerenin uygulandığını gösterir):

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

Migrasyon

channels.imessage.catchup.* kullanımdan kaldırıldı — kesinti süresi kurtarması artık otomatiktir ve yeni kurulumlar için yapılandırma gerektirmez. catchup.enabled: true içeren mevcut yapılandırmalar, kurtarma yeniden oynatma penceresi için uyumluluk profili olarak desteklenmeye devam eder. Devre dışı catchup blokları (enabled: false veya enabled: true olmayanlar) emekliye ayrıldı; openclaw doctor --fix bunları kaldırır.

Sorun giderme

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

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

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

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

openclaw channels status --probe --channel imessage

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

Yapılandırma referansı işaretçileri

• Yapılandırma referansı - iMessage
• Gateway yapılandırması
• Eşleştirme

İlgili

• Kanallara Genel Bakış — desteklenen tüm kanallar
• BlueBubbles'ın kaldırılması ve imsg iMessage yolu — duyuru ve migrasyon özeti
• BlueBubbles'tan geçiş — yapılandırma çeviri tablosu ve adım adım geçiş
• Eşleştirme — DM kimlik doğrulaması ve eşleştirme akışı
• Gruplar — grup sohbeti davranışı ve bahsetme kapısı
• Kanal Yönlendirme — iletiler için oturum yönlendirme
• Güvenlik — erişim modeli ve sıkılaştırma