Afkomstig van BlueBubbles

​

Migratiechecklist

1. Verifieer imsg rechtstreeks op de Mac waarop Messages.app draait (imsg chats, imsg history, imsg send en imsg rpc --help).
2. Kopieer gedragssleutels van channels.bluebubbles naar channels.imessage: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, includeAttachments, attachmentRoots, mediaMaxMb, textChunkLimit, coalesceSameSenderDms en actions.
3. Verwijder transportsleutels die niet meer bestaan: serverUrl, password, Webhook-URL’s en de BlueBubbles-serverconfiguratie.
4. Als de Gateway niet op de Messages-Mac draait, stel je channels.imessage.cliPath in op een SSH-wrapper en stel je remoteHost in voor het ophalen van externe bijlagen.
5. Schakel channels.imessage in terwijl de Gateway is gestopt, en voer daarna openclaw channels status --probe --channel imessage uit.
6. Test een DM, een toegestane groep, bijlagen indien ingeschakeld, en elke privé-API-actie waarvan je verwacht dat de agent die gebruikt.
7. Verwijder de BlueBubbles-server en de oude channels.bluebubbles-configuratie nadat het iMessage-pad is geverifieerd.

​

Wanneer deze migratie zinvol is

• Je gebruikt imsg al op dezelfde Mac (of een Mac die via SSH bereikbaar is) waarop Messages.app is ingelogd.
• 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 privé-API-probe available: true rapporteert.

​

Wat imsg doet

• Leesbewerkingen komen uit ~/Library/Messages/chat.db met een alleen-lezen 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 verzendingen, bewerken, verzenden ongedaan maken, threaded replies, tapbacks en groepsbeheer.
• Linux-builds kunnen een gekopieerde chat.db inspecteren, maar kunnen niet verzenden, de live Mac-database bekijken of Messages.app aansturen. Voer voor OpenClaw iMessage imsg uit op de ingelogde 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 faalt met unable to open database file, lege uitvoer of authorization denied, verleen dan Full Disk Access aan de terminal, editor, het Node-proces, de Gateway-service of het SSH-ouderproces dat imsg start, en open dat ouderproces daarna opnieuw.
2. Verifieer de lees-, watch-, verzend- en RPC-oppervlakken voordat je de OpenClaw-configuratie 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 draait, voer deze opdrachten dan uit via dezelfde SSH-wrapper of gebruikerscontext die OpenClaw zal gebruiken. Als leesbewerkingen/probes werken maar verzenden faalt met AppleEvents -1743, controleer dan of Automation op /usr/libexec/sshd-keygen-wrapper is terechtgekomen; zie SSH-wrapper-verzendingen falen met AppleEvents -1743.
3. Schakel de privé-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. Nadat je een ingeschakelde channels.imessage-configuratie hebt toegevoegd, verifieer je de brug via OpenClaw:
   openclaw channels status --probe
   
   Je wilt imessage.privateApi.available: true. Als dit false rapporteert, los dat dan eerst op: zie Capability-detectie. channels status --probe voert alleen probes uit op geconfigureerde, ingeschakelde accounts.
5. Maak een momentopname van je configuratie:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

Configuratievertaling

​

Valkuil in groepsregister

1. Allowlist voor afzender / chatdoel (channels.imessage.groupAllowFrom) — gecontroleerd door isAllowedIMessageSender. Matcht inkomende berichten op afzenderhandle, chat_guid, chat_identifier of chat_id. Zelfde 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 per account bij het opstarten wanneer groupPolicy: "allowlist" is ingesteld maar channels.imessage.groups leeg is (geen wildcard "*", geen per-chat_id-vermeldingen) — uitgevoerd voordat er berichten binnenkomen.
• Een eenmalige warn per chat_id wanneer een specifieke groep voor het eerst tijdens runtime wordt genegeerd, met vermelding van 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. Houd het uitgeschakeld zolang de Gateway nog BlueBubbles-verkeer routeert:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false,
         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. Probe voordat verkeer belangrijk wordt — stop de Gateway, schakel het iMessage-blok tijdelijk in en bevestig via de CLI dat iMessage gezond rapporteert:
   openclaw gateway stop
   # edit config: channels.imessage.enabled = true
   openclaw channels status --probe --channel imessage   # expect imessage.privateApi.available: true
   
   channels status --probe probet alleen geconfigureerde, ingeschakelde accounts. Herstart de Gateway niet met zowel BlueBubbles als iMessage ingeschakeld, tenzij je bewust beide kanaalmonitors wilt laten draaien. Als je niet onmiddellijk overschakelt, zet channels.imessage.enabled dan terug op false voordat je de Gateway herstart. Gebruik de directe imsg-commando’s in Voordat je begint om de Mac te valideren voordat je OpenClaw-verkeer inschakelt.
3. Schakel over. Zodra het ingeschakelde iMessage-account gezond rapporteert, verwijder je de BlueBubbles-configuratie en houd je iMessage ingeschakeld:
   {
     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 bericht; bevestig dat het antwoord aankomt.
5. Verifieer groepen apart. DM’s en groepen nemen verschillende codepaden — succes met DM’s 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 gatewaylog op imessage: dropping group message from chat_id=<id> of de opstartregel imessage: groupPolicy="allowlist" but channels.imessage.groups is empty — beide verschijnen op het standaard logniveau. Als een van beide verschijnt, ontbreekt je groups-blok of is het leeg — zie “Group registry footgun” hierboven.
6. Verifieer het actieoppervlak — vraag de agent vanuit een gekoppelde DM om te reageren, te bewerken, ongedaan te maken, 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 in Messages.app aankomen. Als een actie “iMessage <action> requires the imsg private API bridge” oplevert, 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

​

Koppelen, 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 gescoped per agent + chat. DM’s vallen samen 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 rollback-kanaal

​

Gerelateerd

• BlueBubbles-verwijdering en het imsg iMessage-pad — korte aankondiging en operatorsamenvatting.
• iMessage — volledige iMessage-kanaalreferentie, inclusief imsg launch-setup en detectie van capabilities.
• /channels/bluebubbles — verouderde URL die omleidt naar deze migratiegids.
• Koppelen — DM-authenticatie en koppelingsflow.
• Kanaalroutering — hoe de gateway een kanaal kiest voor uitgaande antwoorden.