iMessage

​

Hızlı kurulum

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

​

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.

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

​

imsg özel API’sini etkinleştirme

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

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.

​

Kurulum

1. Messages.app çalıştıran Mac üzerinde imsg yükleyin (veya yükseltin):
   brew install steipete/tap/imsg
   imsg --version
   imsg 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.

​

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

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

​

ACP konuşma bağlamaları

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

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

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

​

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

​

Medya, parçalama ve teslim hedefleri

imsg chats --limit 20

​

Özel API eylemleri

{
  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ı

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

​

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

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

{
  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

​

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

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

​

Operatöre görünen sinyal

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

​

Migrasyon

​

Sorun giderme

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"

​

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