iMessage

Durum: yerel harici CLI entegrasyonu. Gateway imsg rpc sürecini başlatır ve stdio üzerinden 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çık olmalıdır.
• OpenClaw/imsg çalıştıran süreç bağlamı için Full Disk Access gerekir (Messages DB erişimi).
• Messages.app üzerinden ileti göndermek için Automation izni gerekir.
• Gelişmiş eylemler (tepki / düzenleme / göndermeyi geri alma / iş parçacıklı yanıt / efektler / grup işlemleri) için System Integrity Protection devre dışı olmalıdır — aşağıdaki imsg özel API'sini etkinleştirme bölümüne bakın. Temel metin ve medya gönderme/alma onsuz çalışır.

imsg özel API'sini etkinleştirme

imsg iki işletim 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 ve yukarıdaki standart macOS izinleriyle 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 (iş parçacıklı), sendWithEffect, renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup ve ayrıca yazıyor göstergeleri ile 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 nettir:

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'nin devre dışı olmasını ve Messages.app içine bir yardımcı dylib enjekte edilmesini gerektirirler. SIP etkinken imsg launch enjeksiyonu reddeder.

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

Kurulum

1. Messages.app çalıştıran Mac üzerinde imsg kurun (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. System Integrity Protection'ı devre dışı bırakın. Bu macOS sürümüne özeldir, çünkü alttaki Apple gereksinimi işletim sistemine ve donanıma bağlıdır:

   • macOS 10.13-10.15 (Sierra-Catalina): Terminal üzerinden Library Validation'ı 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ıç dizisi; son macOS sürümlerinde Continue'a tıklarken Left Shift tuşunu basılı tutun, ardından csrutil disable. Sanal makine kurulumları ayrı bir akış izler — önce bir VM anlık görüntüsü alın.
   • macOS 26 / Tahoe: library-validation ilkeleri ve imagent özel yetki denetimleri daha da sıkılaştı; imsg güncel kalmak için güncellenmiş bir derleme gerektirebilir. Büyük bir macOS yükseltmesinden sonra imsg launch enjeksiyonu veya belirli selectors false döndürmeye başlarsa, SIP adımının başarılı olduğunu varsaymadan önce imsg sürüm notlarını kontrol edin.

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

3. Yardımcıyı enjekte edin. SIP devre dışıyken ve Messages.app oturumu açıkken:

   imsg launch

   SIP hâlâ etkinken imsg launch enjeksiyonu reddeder; bu yüzden bu, 2. adımın uygulandığına dair bir onay işlevi de görür.

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

   openclaw channels status --probe

   iMessage girdisi works bildirmelidir ve imsg status --json | jq '.selectors' çıktısı retractMessagePart: true ile macOS derlemenizin sunduğu düzenleme / yazıyor / okundu seçicilerini göstermelidir. actions.ts içindeki OpenClaw Plugin yöntem başına kapılama yalnızca alttaki seçicisi true olan eylemleri duyurur; bu yüzden aracın araç listesinde gördüğünüz eylem yüzeyi, köprünün bu ana makinede gerçekten yapabildiklerini yansıtır.

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ı atıyorsa, imsg launch komutunu yeniden çalıştırın — yardımcı devreden çıkabilir (Messages.app yeniden başlatma, işletim sistemi güncellemesi vb.) ve önbelleğe alınmış available: true durumu, bir sonraki yoklama yenileyene 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 hâlâ duyurur; yalnızca react, edit, unsend, reply, sendWithEffect ve grup işlemlerini eylem yüzeyinden gizler (yöntem başına yetenek kapısına 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ış bot Mac) çalıştırabilirsiniz. Aşağıdaki Ayrılmış bot macOS kullanıcısı (ayrı iMessage kimliği) 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 sohbetinin içinde /acp spawn codex --bind here komutunu çalıştırın.
• Aynı iMessage konuşmasındaki gelecekteki iletiler, 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 [email protected] gibi normalize edilmiş 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 Aracıları bölümüne bakın.

Dağıtım desenleri

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

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

Medya, parçalara ayırma ve teslim hedefleri

imsg chats --limit 20

Özel API eylemleri

imsg launch çalışırken ve openclaw channels status --probe privateApi.available: true bildirirken, ileti aracı normal metin gönderimlerine ek olarak iMessage yerel eylemlerini 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,      },    },  },}

{  channels: {    imessage: {      sendReadReceipts: false,    },  },}

Yapılandırma yazımları

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

Devre dışı bırakma:

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

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

Bir kullanıcı bir komutu ve URL'yi birlikte yazdığında — örn. 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. Ek olarak OG önizleme görselleri içeren bir URL önizleme balonu ("https://...").

İki satır çoğu kurulumda OpenClaw'a ~0.8-2.0 sn arayla ulaşır. Birleştirme olmadan agent 1. turda komutu tek başına alır, yanıt verir (sık sık "bana URL'yi gönder" der) ve URL'yi ancak 2. turda görür; o noktada komut bağlamı zaten kaybolmuştur. Bu, OpenClaw veya imsg tarafından eklenen bir şey değil, Apple'ın gönderme pipeline'ıdır.

channels.imessage.coalesceSameSenderDms, bir DM'i aynı gönderenden art arda gelen satırları tek bir agent turunda birleştirecek şekilde etkinleştirir. Grup sohbetleri, çok kullanıcılı tur yapısının korunması için mesaj başına iletilmeye devam eder.

{  channels: {    imessage: {      coalesceSameSenderDms: true, // opt in (default: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 2500 ms works for most setups; raise to 4000 ms if your Mac is        // slow or under memory pressure (observed gap can stretch past 2 s        // then).        imessage: 2500,      },    },  },}

Senaryolar ve agent'ın gördükleri

Gateway kapalı kaldıktan sonra arayı kapatma

Gateway çevrimdışıyken (çökme, yeniden başlatma, Mac uykusu, makinenin kapalı olması), Gateway tekrar ayağa kalktığında imsg watch mevcut chat.db durumundan devam eder; boşluk sırasında gelen her şey varsayılan olarak asla görülmez. Catchup, bu mesajları bir sonraki başlangıçta yeniden oynatır, böylece agent gelen trafiği sessizce kaçırmaz.

Catchup varsayılan olarak devre dışıdır. Kanal başına etkinleştirin:

channels: {  imessage: {    catchup: {      enabled: true,             // master switch (default: false)      maxAgeMinutes: 120,        // skip rows older than now - 2h (default: 120, clamp 1..720)      perRunLimit: 50,           // max rows replayed per startup (default: 50, clamp 1..500)      firstRunLookbackMinutes: 30, // first run with no cursor: look back 30 min (default: 30)      maxFailureRetries: 10,     // give up on a wedged guid after 10 dispatch failures (default: 10)    },  },}

Nasıl çalışır

monitorIMessageProvider başlangıcı başına bir geçiş, imsg launch hazır → watch.subscribe → performIMessageCatchup → canlı gönderim döngüsü sırasıyla yürütülür. Catchup'ın kendisi, imsg watch tarafından kullanılan aynı JSON-RPC istemcisine karşı chats.list + sohbet başına messages.history kullanır. Catchup geçişi sırasında gelen her şey normal şekilde canlı gönderimden akar; mevcut gelen-dedupe önbelleği, yeniden oynatılan satırlarla olan tüm çakışmaları emer.

Yeniden oynatılan her satır canlı gönderim yolundan (evaluateIMessageInbound + dispatchInboundMessage) geçirilir; bu nedenle allowlist'ler, grup ilkesi, debouncer, echo önbelleği ve okundu bilgileri yeniden oynatılan ve canlı mesajlarda aynı davranır.

İmleç ve yeniden deneme semantiği

Catchup, <openclawStateDir>/imessage/catchup/<account>__<hash>.json konumunda hesap başına bir imleç tutar (OpenClaw durum dizini varsayılan olarak ~/.openclaw olur, OPENCLAW_STATE_DIR ile değiştirilebilir):

{  "lastSeenMs": 1717900800000,  "lastSeenRowid": 482910,  "updatedAt": 1717900801234,  "failureRetries": { "<guid>": 1 }}

• İmleç her başarılı gönderimde ilerler ve bir satırın gönderimi hata fırlattığında tutulur; bir sonraki başlangıç aynı satırı tutulan imleçten yeniden dener.
• Aynı guid için maxFailureRetries ardışık hata fırlatmasından sonra catchup bir warn kaydeder ve sonraki başlangıçların ilerleyebilmesi için imleci takılmış mesajın ötesine zorla ilerletir.
• Zaten vazgeçilmiş guid'ler sonraki çalıştırmalarda görüldüğünde atlanır (gönderim denemesi yapılmaz) ve çalışma özetinde skippedGivenUp altında sayılır.

Operatöre görünen sinyaller

imessage catchup: replayed=N skippedFromMe=… skippedGivenUp=… failed=… givenUp=… fetchedCount=…imessage catchup: giving up on guid=<guid> after &lt;N&gt; failures; advancing cursor past itimessage catchup: fetched &lt;X&gt; rows across chats, capped to perRunLimit=&lt;Y&gt;

Bir WARN ... capped to perRunLimit satırı, tek bir başlangıcın tüm birikmiş işi boşaltmadığı anlamına gelir. Boşluklarınız düzenli olarak varsayılan 50 satırlık geçişi aşıyorsa perRunLimit değerini artırın (maks. 500).

Ne zaman kapalı bırakılmalı

• Gateway watchdog otomatik yeniden başlatma ile sürekli çalışıyorsa ve boşluklar her zaman birkaç saniyeden kısaysa; kapalı varsayılanı uygundur.
• DM hacmi düşükse ve kaçırılan mesajlar agent davranışını değiştirmeyecekse; firstRunLookbackMinutes başlangıç penceresi ilk etkinleştirmede beklenmedik eski bağlamı gönderebilir.

Catchup'ı açtığınızda, imleç olmayan ilk başlangıç yalnızca firstRunLookbackMinutes kadar geriye bakar (varsayılan 30 dk), tam maxAgeMinutes penceresine değil; bu, etkinleştirme öncesi mesajların uzun bir geçmişini yeniden oynatmayı önler.

Sorun giderme

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

#!/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 geçiş özeti
• BlueBubbles'tan geliyorsanız — 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 geçidi
• Kanal Yönlendirme — mesajlar için oturum yönlendirme
• Güvenlik — erişim modeli ve sağlamlaştırma