Overstappen van BlueBubbles

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.

​

Wanneer deze migratie zinvol is

• Je gebruikt imsg al op dezelfde Mac (of een Mac die via SSH bereikbaar is) waarop Messages.app is aangemeld.
• Je wilt een bewegend onderdeel minder — geen aparte BlueBubbles-server, geen REST-eindpunt om te authenticeren, geen Webhook-bedrading. Een enkele CLI-binary in plaats van een server + client-app + helper.
• Je gebruikt een ondersteunde macOS- / imsg-build waarbij de private API-probe available: true rapporteert.

​

Wat imsg doet

• Leesbewerkingen komen uit ~/Library/Messages/chat.db via een read-only SQLite-handle.
• Live inkomende berichten komen uit imsg watch / watch.subscribe, dat chat.db-bestandssysteemgebeurtenissen volgt met een polling-fallback.
• Verzenden gebruikt Messages.app-automatisering voor normale tekst- en bestandsverzendingen.
• Geavanceerde acties gebruiken imsg launch om de imsg-helper in Messages.app te injecteren. Dat ontgrendelt leesbevestigingen, type-indicatoren, rijke verzendbewerkingen, bewerken, verzenden ongedaan maken, reply in threads, tapbacks en groepsbeheer.
• Linux-builds kunnen een gekopieerde chat.db inspecteren, maar kunnen niet verzenden, de live Mac-database volgen of Messages.app aansturen. Voor OpenClaw iMessage voer je imsg uit op de aangemelde Mac of via een SSH-wrapper naar die Mac.

​

Voordat je begint

1. Installeer imsg op de Mac waarop Messages.app draait:
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   Als imsg chats mislukt met unable to open database file, lege uitvoer of authorization denied, geef dan Volledige schijftoegang aan de terminal, editor, het Node-proces, de Gateway-service of het SSH-ouderproces dat imsg start, en open dat ouderproces daarna opnieuw.
2. Controleer de lees-, watch-, verzend- en RPC-oppervlakken voordat je de OpenClaw-config wijzigt:
   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
   
   Vervang 42 door een echte chat-id uit imsg chats. Verzenden vereist Automation-toestemming voor Messages.app. Als OpenClaw via SSH zal draaien, voer deze opdrachten dan uit via dezelfde SSH-wrapper of gebruikerscontext die OpenClaw zal gebruiken.
3. Schakel de private API-brug in wanneer je geavanceerde acties nodig hebt:
   imsg launch
   imsg status --json
   
   imsg launch vereist dat SIP is uitgeschakeld. Basisverzending, geschiedenis en watch werken zonder imsg launch; geavanceerde acties niet.
4. Controleer de brug via OpenClaw:
   openclaw channels status --probe
   
   Je wilt imessage.privateApi.available: true. Als dit false rapporteert, los dat dan eerst op — zie Mogelijkhedendetectie.
5. Maak een snapshot van je config:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

Configvertaling

​

Valkuil met groepsregister

1. Allowlist voor afzender / chatdoel (channels.imessage.groupAllowFrom) — gecontroleerd door isAllowedIMessageSender. Matcht inkomende berichten op afzenderhandle, chat_guid, chat_identifier of chat_id. Dezelfde vorm als BlueBubbles.
2. Groepsregister (channels.imessage.groups) — gecontroleerd door resolveChannelGroupPolicy uit inbound-processing.ts:199. Met groupPolicy: "allowlist" vereist deze poort een van beide:
   • een wildcardvermelding groups: { "*": { ... } } (stelt allowAll = true in), of
   • een expliciete per-chat_id-vermelding onder groups.

• Een eenmalige warn bij het opstarten per account wanneer groupPolicy: "allowlist" is ingesteld maar channels.imessage.groups leeg is (geen wildcard "*", geen per-chat_id-vermeldingen) — afgevuurd voordat er berichten binnenkomen.
• Een eenmalige warn per chat_id wanneer een specifieke groep voor het eerst tijdens runtime wordt weggelaten, met de chat_id en de exacte sleutel die aan groups moet worden toegevoegd om deze toe te staan.

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

​

Stap voor stap

1. Voeg een iMessage-blok toe naast het bestaande BlueBubbles-blok. Bewaar het oude blok alleen als kopieerbron totdat het nieuwe pad is geverifieerd:
   {
     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. Dry-run-probe — start de Gateway en bevestig dat iMessage als gezond wordt gerapporteerd:
   openclaw gateway
   openclaw channels status
   openclaw channels status --probe   # expect imessage.privateApi.available: true
   
   Omdat imessage.enabled nog steeds false is, wordt er nog geen inkomend iMessage-verkeer gerouteerd — maar --probe test de bridge zodat je permissie- of installatieproblemen ontdekt vóór de overgang.
3. Schakel over. Verwijder de BlueBubbles-configuratie en schakel iMessage in met één configuratiebewerking:
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   Herstart de Gateway. Inkomend iMessage-verkeer loopt nu via de gebundelde Plugin.
4. Verifieer DM’s. Stuur de agent een direct message; bevestig dat het antwoord aankomt.
5. Verifieer groepen afzonderlijk. DM’s en groepen gebruiken verschillende codepaden — een succesvolle DM bewijst niet dat groepen worden gerouteerd. Stuur de agent een bericht in een gekoppelde groepschat en bevestig dat het antwoord aankomt. Als de groep stilvalt (geen agentantwoord, geen fout), controleer dan het Gateway-logboek op imessage: dropping group message from chat_id=<id> of de opstartregel imessage: groupPolicy="allowlist" but channels.imessage.groups is empty — beide worden op het standaard logniveau weergegeven. Als een van beide verschijnt, ontbreekt je groups-blok of is het leeg — zie “Group registry footgun” hierboven.
6. Verifieer het actie-oppervlak — vraag de agent vanuit een gekoppelde DM om te reageren, te bewerken, te verwijderen, te antwoorden, een foto te sturen en (in een groep) de groep te hernoemen / een deelnemer toe te voegen of te verwijderen. Elke actie moet native aankomen in Messages.app. Als een actie “iMessage <action> requires the imsg private API bridge” gooit, voer dan opnieuw imsg launch uit en vernieuw channels status --probe.
7. Verwijder de BlueBubbles-server en -configuratie zodra iMessage-DM’s, groepen en acties zijn geverifieerd. OpenClaw gebruikt channels.bluebubbles niet.

​

Actiepariteit in één oogopslag

​

Koppeling, sessies en ACP-bindingen

• Koppelingsgoedkeuringen worden per handle overgenomen. Je hoeft bekende afzenders niet opnieuw goed te keuren — channels.imessage.allowFrom herkent dezelfde +15555550123 / user@example.com-strings die BlueBubbles gebruikte.
• Sessies blijven gescopeerd per agent + chat. DM’s worden samengevoegd in de hoofdsessie van de agent onder de standaard session.dmScope=main; groepssessies blijven geïsoleerd per chat_id. De sessiesleutels verschillen (agent:<id>:imessage:group:<chat_id> versus het BlueBubbles-equivalent) — oude gespreksgeschiedenis onder BlueBubbles-sessiesleutels wordt niet meegenomen naar iMessage-sessies.
• ACP-bindingen die verwijzen naar match.channel: "bluebubbles" moeten worden bijgewerkt naar "imessage". De vormen van match.peer.id (chat_id:, chat_guid:, chat_identifier:, kale handle) zijn identiek.

​

Geen rollbackkanaal

​

Gerelateerd

• iMessage — volledige iMessage-kanaalreferentie, inclusief imsg launch-setup en capaciteitsdetectie.
• /channels/bluebubbles — legacy-URL die doorverwijst naar deze migratiegids.
• Koppeling — DM-authenticatie en koppelingsflow.
• Kanaalroutering — hoe de Gateway een kanaal kiest voor uitgaande antwoorden.