iMessage

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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çı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 chats --limit 1
# or
imsg send <handle> "test"

​

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

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.

​

Kurulum

1. Messages.app çalıştıran Mac üzerinde imsg kurun (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. 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.

​

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 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: { "*": { "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 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.

• +15555550123 veya user@example.com gibi normalize edilmiş 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 desenleri

{
  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çalara ayırma 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,
      },
    },
  },
}

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

​

Yapılandırma yazımları

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

​

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

1. Bir metin iletisi ("Dump").
2. Ek olarak OG önizleme görselleri içeren bir URL önizleme balonu ("https://...").

{
  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

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

​

İmleç ve yeniden deneme semantiği

{
  "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 <N> failures; advancing cursor past it
imessage catchup: fetched <X> rows across chats, capped to perRunLimit=<Y>

​

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.

​

Sorun giderme

imsg rpc --help
imsg status --json
openclaw channels status --probe

#!/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 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