Afkomstig van BlueBubbles

​

Migratiechecklist

1. Verifieer imsg rechtstreeks op de Mac waarop Messages.app draait (imsg chats, imsg history, imsg send, imsg rpc --help).
2. Kopieer gedragssleutels van channels.bluebubbles naar channels.imessage: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, includeAttachments, attachmentRoots, mediaMaxMb, textChunkLimit 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 op afstand ophalen van bijlagen.
5. Schakel channels.imessage in, start de Gateway opnieuw en voer vervolgens openclaw channels status --probe --channel imessage uit.
6. Test één privébericht, één toegestane groep, bijlagen als die zijn ingeschakeld en elke private API-actie die de agent naar verwachting zal gebruiken.
7. Verwijder de BlueBubbles-server en de oude channels.bluebubbles-configuratie nadat het iMessage-pad is geverifieerd.

​

Wat imsg doet

• Leesbewerkingen komen uit ~/Library/Messages/chat.db via een alleen-lezen SQLite-handle.
• Live binnenkomende berichten komen uit imsg watch / watch.subscribe, dat chat.db-bestandssysteemgebeurtenissen volgt met polling als terugvaloptie.
• Voor normale tekst- en bestandsverzending wordt automatisering van Messages.app gebruikt.
• Geavanceerde acties gebruiken imsg launch om de imsg-helper in Messages.app te injecteren. Dit maakt leesbevestigingen, typindicatoren, uitgebreide verzendingen, bewerken, verzenden ongedaan maken, antwoorden in threads, tapbacks, peilingen en groepsbeheer mogelijk.
• Linux-builds kunnen een gekopieerde chat.db inspecteren, maar kunnen niet verzenden, de live Mac-database bewaken 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
   brew update && brew upgrade imsg
   imsg --version
   imsg chats --limit 3
   
   Voor de gebruikelijke lokale configuratie kan de OpenClaw-configuratie na bevestiging door de gebruiker aanbieden om imsg via Homebrew te installeren of bij te werken op de aangemelde Messages-Mac. Handmatige configuraties en topologieën met een SSH-wrapper blijven onder beheer van de operator: herhaal de Homebrew-update in dezelfde lokale of externe gebruikerscontext waarin imsg wordt uitgevoerd. Als imsg chats mislukt met unable to open database file, lege uitvoer of authorization denied, verleen je volledige schijftoegang aan de terminal, editor, het Node-proces, de Gateway-service of het bovenliggende SSH-proces dat imsg start. Open dat bovenliggende proces daarna opnieuw.
2. Verifieer de oppervlakken voor lezen, bewaken, verzenden en RPC 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. Voor verzenden is automatiseringsmachtiging voor Messages.app vereist. Als OpenClaw via SSH wordt uitgevoerd, voer je deze opdrachten uit via dezelfde SSH-wrapper of gebruikerscontext die OpenClaw zal gebruiken. Als lezen werkt maar verzenden mislukt met AppleEvents -1743, controleer je of de automatiseringsmachtiging aan /usr/libexec/sshd-keygen-wrapper is verleend; zie Verzenden via een SSH-wrapper mislukt met AppleEvents -1743.
3. Schakel de private API-bridge in. Dit wordt sterk aanbevolen voor OpenClaw iMessage, omdat antwoorden, tapbacks, effecten, peilingen, antwoorden op bijlagen en groepsacties ervan afhankelijk zijn:
   imsg launch
   imsg status --json
   
   Voor imsg launch moet SIP zijn uitgeschakeld (en op moderne macOS-versies moet bibliotheekvalidatie zijn versoepeld — zie De private API van imsg inschakelen). Basisfuncties voor verzenden, geschiedenis en bewaken werken zonder imsg launch; het volledige iMessage-actieoppervlak van OpenClaw niet.
4. Nadat je channels.imessage hebt ingeschakeld en de Gateway hebt gestart, verifieer je de bridge via OpenClaw:
   openclaw channels status --probe
   
   Het iMessage-account moet works rapporteren; met --json bevat de testpayload privateApi.available: true. Als het false rapporteert, los je dat eerst op — zie Detectie van mogelijkheden. Voor testen is een bereikbare Gateway nodig (anders valt de CLI terug op uitvoer die alleen op de configuratie is gebaseerd) en alleen geconfigureerde, ingeschakelde accounts worden getest.
5. Maak een momentopname van je configuratie:
   cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
   

​

Configuratievertaling

​

Valkuil bij het groepsregister

1. Toegestane afzenders/chatdoelen (channels.imessage.groupAllowFrom) — komt overeen met de afzenderhandle of het chatdoel (vermeldingen chat_id:, chat_guid:, chat_identifier:). Wanneer groupAllowFrom niet is ingesteld, valt deze controle terug op allowFrom; een expliciete groupAllowFrom: [] schakelt die terugval uit en verwijdert elk groepsbericht onder groupPolicy: "allowlist".
2. Groepsregister (channels.imessage.groups) — gebruikt de numerieke iMessage-chat_id als sleutel:
   • Geen groups-blok (of een leeg blok): groepen doorstaan deze controle zolang controle 1 een effectieve, niet-lege lijst met toegestane afzenders heeft; afzenderfiltering bepaalt de toegang en er verschijnt bij het opstarten geen waarschuwing dat alles wordt verwijderd.
   • groups met vermeldingen maar zonder "*": alleen de vermelde chat_id-sleutels worden doorgelaten. Zodra een groep wordt vermeld, verandert het register in een lijst met toegestane groepen, zelfs onder groupPolicy: "open".
   • groups: { "*": { ... } }: elke groep doorstaat deze controle.

• Eenmaal per account bij het opstarten, wanneer groupPolicy: "allowlist" is ingesteld en de effectieve lijst met toegestane groepsafzenders leeg is: imessage: groupPolicy="allowlist" for account "<id>" but no group sender allowlist is configured .... Stel groupAllowFrom (of allowFrom) in om afzenders toe te laten; alleen groups toevoegen voldoet niet aan de afzendercontrole.
• Eenmaal per chat_id tijdens runtime, wanneer het register een groep verwijdert: imessage: dropping group message from chat_id=<id> ... not in channels.imessage.groups allowlist, met de exacte sleutel die moet worden toegevoegd.

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

​

Stap voor stap

1. Zet de configuratie om. Houd het nieuwe blok uitgeschakeld tijdens het bewerken; het oude channels.bluebubbles-blok wordt door de huidige OpenClaw genegeerd en kan ernaast blijven staan als referentie:
   {
     channels: {
       imessage: {
         enabled: false, // zet op true wanneer je klaar bent om over te schakelen
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // kopieer uit bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // kopieer uit bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // jokerteken wordt letterlijk gekopieerd; geef vermeldingen per chat nieuwe sleutels op basis van chat_id
         // acties zijn standaard ingeschakeld; stel afzonderlijke schakelaars in op false om ze uit te schakelen
       },
     },
   }
   
2. Schakel over en voer een controle uit. Stel channels.imessage.enabled: true in, start de Gateway opnieuw en controleer of het kanaal een gezonde status meldt:
   openclaw gateway restart
   openclaw channels status --probe --channel imessage   # verwacht "works"; --json toont privateApi.available: true
   
   De probe vereist een bereikbare Gateway en controleert alleen geconfigureerde, ingeschakelde accounts. Gebruik de directe imsg-opdrachten in Voordat je begint om de Mac zelf te valideren.
3. Controleer DM’s. Stuur de agent een direct bericht en bevestig dat het antwoord aankomt.
4. Controleer groepen afzonderlijk. DM’s en groepen gebruiken verschillende codepaden — een geslaagde DM bewijst niet dat groepen correct worden gerouteerd. Stuur een bericht in een toegestane groepschat en bevestig dat het antwoord aankomt. Als de groep stil blijft (geen antwoord van de agent, geen fout), controleer dan het Gateway-logboek op de twee warn-regels uit ‘Group registry footgun’ hierboven. De opstartwaarschuwing betekent dat de effectieve afzenderstoestaanlijst leeg is; een waarschuwing per chat_id betekent dat een gevulde groups-registratie die chat niet bevat.
5. Controleer de beschikbare acties. Vraag de agent vanuit een gekoppelde DM om een reactie toe te voegen, een bericht te bewerken, het verzenden ongedaan te maken, te antwoorden, een foto te sturen en (in een groep) de groep te hernoemen of een deelnemer toe te voegen of te verwijderen. Elke actie moet als systeemeigen actie in Messages.app aankomen. Als een actie iMessage <action> requires the imsg private API bridge oplevert, voer je imsg launch opnieuw uit en vernieuw je met openclaw channels status --probe.
6. Verwijder de BlueBubbles-server en het channels.bluebubbles-blok zodra iMessage-DM’s, groepen en acties zijn gecontroleerd. OpenClaw leest channels.bluebubbles niet.

​

Actiepariteit in één oogopslag

​

Koppeling, sessies en ACP-bindingen

• Toestaanlijsten worden per handle overgenomen. channels.imessage.allowFrom herkent dezelfde +15555550123- / user@example.com-tekenreeksen die BlueBubbles gebruikte — kopieer ze letterlijk.
• Goedkeuringen uit de koppelingsopslag worden niet overgedragen. De koppelingsopslag is per kanaal en niets migreert de oude BlueBubbles-opslag. Afzenders die uitsluitend via koppeling waren goedgekeurd, moeten nogmaals onder iMessage koppelen, of je voegt hun handles toe aan allowFrom.
• Sessies blijven beperkt tot één agent en chat. DM’s worden met de standaardwaarde session.dmScope=main samengevoegd in de hoofdsessie van de agent; groepssessies blijven afzonderlijk per chat_id (agent:<agentId>:imessage:group:<chat_id>). Oude gespreksgeschiedenis onder BlueBubbles-sessiesleutels wordt niet overgenomen in iMessage-sessies.
• ACP-bindingen die naar match.channel: "bluebubbles" verwijzen, moeten worden gewijzigd in "imessage". De match.peer.id-vormen (chat_id:, chat_guid:, chat_identifier:, alleen de handle) zijn identiek.

​

Geen kanaal om terug te draaien

​

Gerelateerd

• Verwijdering van BlueBubbles en het imsg-pad voor iMessage — korte aankondiging en samenvatting voor beheerders.
• iMessage — volledige naslag voor het iMessage-kanaal, inclusief configuratie van imsg launch en detectie van mogelijkheden.
• /channels/bluebubbles — verouderde URL die doorverwijst naar deze migratiehandleiding.
• Koppeling — DM-authenticatie en koppelingsproces.
• Kanaalroutering — hoe de Gateway een kanaal kiest voor uitgaande antwoorden.