BlueBubbles'tan geçiş

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.

​

Bu taşıma ne zaman mantıklıdır?

• Messages.app oturumunun açık olduğu aynı Mac üzerinde (veya SSH üzerinden erişilebilen bir Mac üzerinde) zaten imsg çalıştırıyorsunuz.
• Daha az hareketli parça istiyorsunuz — ayrı BlueBubbles sunucusu yok, kimlik doğrulaması yapılacak REST uç noktası yok, webhook tesisatı yok. Sunucu + istemci uygulaması + yardımcı yerine tek bir CLI ikilisi.
• Özel API yoklamasının available: true bildirdiği desteklenen bir macOS / imsg derlemesindesiniz.

​

imsg ne yapar?

• Okumalar, salt okunur bir SQLite tanıtıcısı kullanılarak ~/Library/Messages/chat.db dosyasından gelir.
• Canlı gelen iletiler, yoklama geri dönüşüyle birlikte chat.db dosya sistemi olaylarını izleyen imsg watch / watch.subscribe üzerinden gelir.
• Gönderimler, normal metin ve dosya gönderimleri için Messages.app otomasyonunu kullanır.
• Gelişmiş eylemler, imsg yardımcısını Messages.app içine enjekte etmek için imsg launch kullanır. Okundu bilgilerini, yazıyor göstergelerini, zengin gönderimleri, düzenlemeyi, göndermeyi geri almayı, konuya yanıtı, tapback’leri ve grup yönetimini açan budur.
• Linux derlemeleri kopyalanmış bir chat.db dosyasını inceleyebilir, ancak gönderim yapamaz, canlı Mac veritabanını izleyemez veya Messages.app’i çalıştıramaz. OpenClaw iMessage için imsgyi oturum açılmış Mac üzerinde veya o Mac’e giden bir SSH sarmalayıcısı üzerinden çalıştırın.

​

Başlamadan önce

1. Messages.app çalıştıran Mac’e imsg yükleyin:
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   imsg chats komutu unable to open database file, boş çıktı veya authorization denied ile başarısız olursa imsgyi başlatan terminale, düzenleyiciye, Node sürecine, Gateway hizmetine veya SSH üst sürecine Full Disk Access verin, ardından bu üst süreci yeniden açın.
2. OpenClaw yapılandırmasını değiştirmeden önce okuma, izleme, gönderme ve RPC yüzeylerini doğrulayın:
   imsg chats --limit 10 --json | jq -s
   imsg history --chat-id 42 --limit 10 --attachments --json | jq -s
   imsg watch --chat-id 42 --reactions --json
   imsg send --chat-id 42 --text "OpenClaw imsg test"
   imsg rpc --help
   
   42 değerini imsg chats çıktısından gerçek bir sohbet kimliğiyle değiştirin. Gönderim, Messages.app için Automation izni gerektirir. OpenClaw SSH üzerinden çalışacaksa bu komutları OpenClaw’ın kullanacağı aynı SSH sarmalayıcısı veya kullanıcı bağlamı üzerinden çalıştırın.
3. Gelişmiş eylemlere ihtiyacınız olduğunda özel API köprüsünü etkinleştirin:
   imsg launch
   imsg status --json
   
   imsg launch, SIP’nin devre dışı bırakılmasını gerektirir. Temel gönderim, geçmiş ve izleme imsg launch olmadan çalışır; gelişmiş eylemler çalışmaz.
4. Köprüyü OpenClaw üzerinden doğrulayın:
   openclaw channels status --probe
   
   imessage.privateApi.available: true görmelisiniz. false bildirirse önce bunu düzeltin — bkz. Yetenek algılama.
5. Yapılandırmanızın anlık görüntüsünü alın:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

Yapılandırma çevirisi

​

Grup kayıt defteri tuzağı

1. Gönderen / sohbet hedefi izin listesi (channels.imessage.groupAllowFrom) — isAllowedIMessageSender tarafından denetlenir. Gelen mesajları gönderen handle’ı, chat_guid, chat_identifier veya chat_id ile eşleştirir. BlueBubbles ile aynı biçimdedir.
2. Grup kayıt defteri (channels.imessage.groups) — inbound-processing.ts:199 içinden resolveChannelGroupPolicy tarafından denetlenir. groupPolicy: "allowlist" ile bu kapı şunlardan birini gerektirir:
   • bir groups: { "*": { ... } } joker girdisi (allowAll = true ayarlar), veya
   • groups altında açık bir chat_id bazlı girdi.

• groupPolicy: "allowlist" ayarlanmış ancak channels.imessage.groups boş olduğunda hesap başına bir kerelik başlangıç warn sinyali ("*" jokeri yok, chat_id bazlı girdi yok); herhangi bir mesaj gelmeden önce tetiklenir.
• Belirli bir grup çalışma zamanında ilk kez düşürüldüğünde chat_id başına bir kerelik warn sinyali; chat_id’yi ve izin vermek için groups bölümüne eklenecek tam anahtarı belirtir.

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123", "chat_guid:any;-;..."],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

​

Adım adım

1. Mevcut BlueBubbles bloğunun yanına bir iMessage bloğu ekleyin. Eski bloğu yalnızca yeni yol doğrulanana kadar kopyalama kaynağı olarak tutun:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false, // turn on after the dry run below
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // copy from bluebubbles.groups — silently drops groups if missing, see "Group registry footgun" above
         actions: {
           reactions: true,
           edit: true,
           unsend: true,
           reply: true,
           sendWithEffect: true,
           sendAttachment: true,
         },
       },
     },
   }
   
2. Deneme çalıştırması yoklaması — Gateway’i başlatın ve iMessage’ın sağlıklı raporladığını doğrulayın:
   openclaw gateway
   openclaw channels status
   openclaw channels status --probe   # expect imessage.privateApi.available: true
   
   imessage.enabled hâlâ false olduğu için henüz hiçbir gelen iMessage trafiği yönlendirilmez — ancak --probe köprüyü çalıştırır, böylece geçişten önce izin/kurulum sorunlarını yakalarsınız.
3. Geçiş yapın. BlueBubbles yapılandırmasını kaldırın ve tek bir yapılandırma düzenlemesiyle iMessage’ı etkinleştirin:
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   Gateway’i yeniden başlatın. Gelen iMessage trafiği artık paketlenmiş Plugin üzerinden akar.
4. DM’leri doğrulayın. Aracıya doğrudan mesaj gönderin; yanıtın ulaştığını doğrulayın.
5. Grupları ayrı doğrulayın. DM’ler ve gruplar farklı kod yollarını kullanır — DM başarısı grupların yönlendirildiğini kanıtlamaz. Aracıya eşleştirilmiş bir grup sohbetinde mesaj gönderin ve yanıtın ulaştığını doğrulayın. Grup sessiz kalırsa (aracı yanıtı yok, hata yok), Gateway günlüğünde imessage: dropping group message from chat_id=<id> ya da başlangıçta imessage: groupPolicy="allowlist" but channels.imessage.groups is empty satırını kontrol edin — ikisi de varsayılan günlük düzeyinde tetiklenir. Bunlardan biri görünürse, groups bloğunuz eksik ya da boştur — yukarıdaki “Grup kaydı tuzağı” bölümüne bakın.
6. Eylem yüzeyini doğrulayın — eşleştirilmiş bir DM’den aracıdan tepki vermesini, düzenlemesini, göndermeyi geri almasını, yanıtlamasını, fotoğraf göndermesini ve (bir grupta) grubu yeniden adlandırmasını / katılımcı eklemesini ya da kaldırmasını isteyin. Her eylem Messages.app içinde yerel olarak gerçekleşmelidir. Herhangi biri “iMessage <action> requires the imsg private API bridge” hatasını verirse, imsg launch komutunu yeniden çalıştırın ve channels status --probe sonucunu yenileyin.
7. iMessage DM’leri, grupları ve eylemleri doğrulandıktan sonra BlueBubbles sunucusunu ve yapılandırmasını kaldırın. OpenClaw channels.bluebubbles kullanmayacaktır.

​

Bir bakışta eylem eşdeğerliği

​

Eşleştirme, oturumlar ve ACP bağlamaları

• Eşleştirme onayları handle üzerinden taşınır. Bilinen gönderenleri yeniden onaylamanız gerekmez — channels.imessage.allowFrom, BlueBubbles’ın kullandığı aynı +15555550123 / user@example.com dizelerini tanır.
• Oturumlar aracı + sohbet başına kapsamlanmış kalır. DM’ler varsayılan session.dmScope=main altında aracının ana oturumunda birleşir; grup oturumları chat_id başına izole kalır. Oturum anahtarları farklıdır (agent:<id>:imessage:group:<chat_id> ile BlueBubbles eşdeğeri) — BlueBubbles oturum anahtarları altındaki eski konuşma geçmişi iMessage oturumlarına taşınmaz.
• match.channel: "bluebubbles" referansı veren ACP bağlamaları "imessage" olarak güncellenmelidir. match.peer.id biçimleri (chat_id:, chat_guid:, chat_identifier:, yalın handle) aynıdır.

​

Geri dönüş kanalı yok

​

İlgili

• iMessage — imsg launch kurulumu ve yetenek algılama dahil tam iMessage kanal başvurusu.
• /channels/bluebubbles — bu geçiş kılavuzuna yönlendiren eski URL.
• Eşleştirme — DM kimlik doğrulaması ve eşleştirme akışı.
• Kanal Yönlendirme — Gateway’in giden yanıtlar için kanalı nasıl seçtiği.