iMessage

Gebruik een speciale Apple ID en macOS-gebruiker, zodat botverkeer gescheiden blijft van je persoonlijke Messages-profiel.

Gebruikelijke procedure:

1. Maak/meld je aan bij een speciale macOS-gebruiker.
2. Meld je in Berichten aan met de Apple ID van de bot voor die gebruiker.
3. Installeer imsg voor die gebruiker.
4. Maak een SSH-wrapper zodat OpenClaw imsg in de context van die gebruiker kan uitvoeren.
5. Laat channels.imessage.accounts.<id>.cliPath en .dbPath naar dat gebruikersprofiel verwijzen.

Voor de eerste uitvoering zijn mogelijk GUI-goedkeuringen (Automation + Full Disk Access) vereist in de gebruikerssessie van die bot.

Gebruikelijke topologie:

• Gateway draait op Linux/VM
• iMessage + imsg draait op een Mac in je tailnet
• cliPath-wrapper gebruikt SSH om imsg uit te voeren
• remoteHost maakt het ophalen van bijlagen via SCP mogelijk

Voorbeeld:

{  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 bashexec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

Gebruik SSH-sleutels zodat zowel SSH als SCP niet-interactief zijn. Zorg eerst dat de hostsleutel wordt vertrouwd (bijvoorbeeld ssh bot@mac-mini.tailnet-1234.ts.net), zodat known_hosts wordt gevuld.

iMessage ondersteunt configuratie per account onder channels.imessage.accounts.

Elk account kan velden overschrijven zoals cliPath, dbPath, allowFrom, groupPolicy, mediaMaxMb, geschiedenisinstellingen en allowlists voor hoofdlocaties van bijlagen.

Stel channels.imessage.dmHistoryLimit in om nieuwe sessies voor privéberichten te voorzien van recente gedecodeerde imsg-geschiedenis voor dat gesprek. Gebruik channels.imessage.dms["<sender>"].historyLimit voor overschrijvingen per afzender, waaronder 0 om geschiedenis voor een afzender uit te schakelen.

De geschiedenis van iMessage-privéberichten wordt op aanvraag opgehaald uit imsg. Als dmHistoryLimit niet is ingesteld, wordt het globaal vooraf vullen van de geschiedenis van privéberichten uitgeschakeld, maar een positieve channels.imessage.dms["<sender>"].historyLimit per afzender schakelt het vooraf vullen voor die afzender nog steeds in.

• het verwerken van inkomende bijlagen is standaard uitgeschakeld — stel channels.imessage.includeAttachments: true in om foto's, spraakmemo's, video's en andere bijlagen naar de agent door te sturen. Als dit is uitgeschakeld, worden iMessages die alleen een bijlage bevatten verwijderd voordat ze de agent bereiken en leveren ze mogelijk helemaal geen Inbound message-logregel op.
• externe bijlagepaden kunnen via SCP worden opgehaald wanneer remoteHost is ingesteld
• bijlagepaden moeten overeenkomen met toegestane hoofdlocaties:
  • channels.imessage.attachmentRoots (lokaal)
  • channels.imessage.remoteAttachmentRoots (externe SCP-modus)
  • geconfigureerde hoofdlocaties breiden het standaardpatroon voor hoofdlocaties /Users/*/Library/Messages/Attachments uit (samengevoegd, niet vervangen)
• SCP gebruikt strikte controle van hostsleutels (StrictHostKeyChecking=yes)
• de grootte van uitgaande media gebruikt channels.imessage.mediaMaxMb (standaard 16 MB)

• limiet voor tekstblokken: channels.imessage.textChunkLimit (standaard 4000)
• modus voor opsplitsing: channels.imessage.streaming.chunkMode
  • length (standaard)
  • newline (eerst opsplitsen op alinea's)
• uitgaande Markdown voor vet/cursief/onderstrepen/doorhalen wordt omgezet in tekst met systeemeigen opmaak (ontvangers met macOS 15+ geven de opmaak weer; oudere ontvangers zien platte tekst zonder de markeringen); Markdown-tabellen worden omgezet volgens de Markdown-tabelmodus van het kanaal
• channels.imessage.sendTransport (auto standaard, bridge, applescript) bepaalt hoe imsg verzendingen aflevert

Expliciete voorkeursdoelen:

• chat_id:123 (aanbevolen voor stabiele routering)
• chat_guid:...
• chat_identifier:...

Handledoelen worden ook ondersteund:

• imessage:+1555...
• sms:+1555...
• user@example.com

imsg chats --limit 20

• react: Voeg iMessage-tapbacks toe of verwijder ze (messageId, emoji, remove). Ondersteunde tapbacks worden gekoppeld aan liefde, leuk, niet leuk, lachen, benadrukken en vraag. Verwijderen zonder emoji wist de ingestelde tapback.
• reply: Stuur een antwoord in een thread naar een bestaand bericht (messageId, text of message, plus chatGuid, chatId, chatIdentifier of to). Voor antwoorden met een bijlage is daarnaast een imsg-build nodig waarvan send-rich --file ondersteunt.
• sendWithEffect: Stuur tekst met een iMessage-effect (text of message, effect of effectId). Korte namen: slam, loud, gentle, invisibleink, confetti, lasers, fireworks, balloon, heart, echo, happybirthday, shootingstar, sparkles, spotlight.
• edit: Bewerk een verzonden bericht op ondersteunde versies van macOS/de privé-API (messageId, text of newText). Alleen berichten die de Gateway zelf heeft verzonden, kunnen worden bewerkt.
• unsend: Trek een verzonden bericht in op ondersteunde versies van macOS/de privé-API (messageId). Alleen berichten die de Gateway zelf heeft verzonden, kunnen worden ingetrokken.
• upload-file: Stuur media/bestanden (buffer als base64 of een gehydrateerde media/path/filePath, filename, optioneel asVoice). Verouderde alias: sendAttachment.
• renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup: Beheer groepschats wanneer het huidige doel een groepsgesprek is. Deze wijzigen de Berichten-identiteit van de host en vereisen daarom een eigenaar als afzender of een operator.admin Gateway-client.
• poll: Maak een systeemeigen peiling in Apple Berichten (pollQuestion, pollOption 2 tot 12 keer herhaald, plus chatGuid, chatId, chatIdentifier of to). Ontvangers met iOS/iPadOS/macOS 26+ zien de peiling en kunnen er systeemeigen op stemmen; oudere OS-versies krijgen als terugval de tekst "Er is een peiling verzonden". Vereist selectors.pollPayloadMessage.
• poll-vote: Stem op een bestaande peiling (pollId of messageId, plus precies één van pollOptionIndex, pollOptionId of pollOptionText). Vereist selectors.pollVoteMessage en de RPC-methode poll.vote.

Geaccepteerde inkomende peilingen worden voor de agent weergegeven met de vraag, genummerde optielabels, aantallen stemmen en de bericht-ID van de peiling die poll-vote nodig heeft.

Inkomende iMessage-context bevat zowel korte MessageSid-waarden als volledige bericht-GUID's (MessageSidFull) wanneer die beschikbaar zijn. Korte ID's zijn beperkt tot de recente, door SQLite ondersteunde antwoordcache en worden vóór gebruik gecontroleerd aan de hand van de huidige chat. Als een korte ID verloopt, probeer het opnieuw met de bijbehorende MessageSidFull en richt je op het gesprek dat deze heeft geleverd. Volledige ID's omzeilen de binding aan het gesprek of account niet; vervang daarom een ID uit een andere chat door een ID uit het huidige doel. Extern gedelegeerde aanroepen kunnen verouderde volledige ID's weigeren wanneer bewijs voor het huidige gesprek niet beschikbaar is.

OpenClaw verbergt acties van de privé-API alleen wanneer de gecachete probestatus aangeeft dat de bridge niet beschikbaar is. Als de status onbekend is, blijven acties zichtbaar en worden probes bij verzending uitgesteld uitgevoerd, zodat de eerste actie na imsg launch kan slagen zonder afzonderlijke handmatige statusvernieuwing.

Wanneer de bridge van de privé-API actief is, worden geaccepteerde inkomende chats als gelezen gemarkeerd en tonen privéchats een typindicator zodra de beurt is geaccepteerd, terwijl de agent context voorbereidt en genereert. Schakel markeren als gelezen uit met:

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

Oudere imsg-builds van vóór de lijst met mogelijkheden per methode schakelen typen/lezen stilzwijgend uit; OpenClaw registreert per herstart een eenmalige waarschuwing, zodat de ontbrekende bevestiging kan worden herleid.

OpenClaw abonneert zich op iMessage-tapbacks en routeert geaccepteerde reacties als systeemgebeurtenissen in plaats van normale berichttekst, zodat een tapback van een gebruiker geen gewone antwoordlus activeert.

De meldingsmodus wordt geregeld door channels.imessage.reactionNotifications:

• "own" (standaard): meld alleen wanneer gebruikers reageren op berichten die door de bot zijn geschreven.
• "all": meld alle inkomende tapbacks van geautoriseerde afzenders.
• "off": negeer inkomende tapbacks.

Overschrijvingen per account gebruiken channels.imessage.accounts.<id>.reactionNotifications.

Wanneer approvals.exec.enabled of approvals.plugin.enabled waar is en het verzoek naar iMessage wordt gerouteerd, levert de Gateway systeemeigen een goedkeuringsprompt af en accepteert deze een tapback om het verzoek af te handelen:

• 👍 (Like-tapback) → allow-once
• 👎 (Dislike-tapback) → deny
• allow-always blijft een handmatige terugval: stuur /approve <id> allow-always als een normaal antwoord.

Voor de verwerking van reacties moet de handle van de reagerende gebruiker een expliciete goedkeurder zijn. De lijst met goedkeurders wordt gelezen uit channels.imessage.allowFrom (of channels.imessage.accounts.<id>.allowFrom); voeg het telefoonnummer van de gebruiker in E.164-indeling of het e-mailadres van diens Apple ID toe (chatdoelen zoals chat_id:* zijn geen geldige vermeldingen voor goedkeurders). De jokertekenvermelding "*" wordt gehonoreerd, maar staat elke afzender toe goed te keuren; een lege lijst met goedkeurders schakelt de reactiesnelkoppeling volledig uit. De reactiesnelkoppeling omzeilt bewust reactionNotifications, dmPolicy en groupAllowFrom, omdat de expliciete allowlist met goedkeurders de enige controle is die van belang is voor het afhandelen van goedkeuringen.

Autorisatie voor de tekstuele opdracht /approve volgt dezelfde lijst: wanneer channels.imessage.allowFrom niet leeg is, wordt /approve <id> <decision> geautoriseerd aan de hand van die lijst met goedkeurders (niet de bredere allowlist voor privéberichten), en afzenders die wel op de allowlist voor privéberichten staan maar niet in allowFrom, krijgen een expliciete weigering. Wanneer allowFrom leeg is, blijft de terugval naar dezelfde chat van kracht en autoriseert /approve iedereen die door de allowlist voor privéberichten wordt toegestaan. Voeg elke operator die goedkeuringen moet kunnen geven — via /approve of via reacties — toe aan allowFrom.

Operatornotities:

• De reactiekoppeling wordt zowel in het geheugen als in de permanente opslag met sleutels van de Gateway bewaard (waarbij de TTL overeenkomt met de vervaldatum van de goedkeuring), en de Gateway controleert openstaande prompts ook op tapbacks, zodat een tapback die kort na een herstart van de Gateway binnenkomt de goedkeuring alsnog afhandelt.
• De is_from_me=true-tapback van de operator zelf (bijvoorbeeld vanaf een gekoppeld Apple-apparaat) handelt de goedkeuring af wanneer die handle expliciet als goedkeurder is ingesteld.
• Goedkeuringsprompts worden alleen naar een groepsgesprek gerouteerd wanneer expliciete goedkeurders zijn geconfigureerd; anders zou elk groepslid kunnen goedkeuren.
• Oudere tapbacks in tekstvorm (Liked "…" platte tekst van zeer oude Apple-clients) kunnen geen goedkeuringen afhandelen omdat ze geen bericht-GUID bevatten; voor reactieafhandeling zijn de gestructureerde tapbackmetagegevens vereist die huidige macOS-/iOS-clients versturen.

Voor een ask_user-prompt met één niet-geheime vraag met één selecteerbare optie en één tot vier opties voegt OpenClaw genummerde emojikeuzes toe. Reageer op de afgeleverde prompt met het overeenkomstige nummer om de vraag te beantwoorden. De reactie moet de stabiele GUID van het door de bot opgestelde bericht bevatten; OpenClaw wijst het nummer vervolgens via de Gateway toe aan de canonieke optie. Verouderde of dubbele tikken worden genegeerd.

Prompts met meerdere vragen, meerdere selecties of vrije tekst kunnen alleen via een tekstantwoord worden beantwoord. Vraagreacties volgen de normale toelatingsregels voor iMessage-DM's en -groepen. Ze worden ook herkend wanneer algemene reactionNotifications "off" is, zonder niet-gerelateerde reacties om te zetten in agentgebeurtenissen.

Valideer het binaire bestand en de RPC-ondersteuning:

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

Als de probe meldt dat RPC niet wordt ondersteund, werk je imsg bij. Als acties via de privé-API niet beschikbaar zijn, voer je imsg launch uit in de aangemelde macOS-gebruikerssessie en voer je de probe opnieuw uit. Als de Gateway niet op macOS wordt uitgevoerd, gebruik je de bovenstaande configuratie voor een externe Mac via SSH in plaats van het standaard lokale imsg-pad.

Stel eerst vast of het bericht de lokale Mac heeft bereikt. Als chat.db niet verandert, kan OpenClaw het bericht niet ontvangen, zelfs wanneer imsg status --json een gezonde bridge rapporteert.

imsg chats --limit 10 --jsonimsg watch --chat-id <chat-id> --jsonsqlite3 ~/Library/Messages/chat.db \"select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

Als vanaf de telefoon verzonden berichten geen nieuwe rijen maken, herstel je de macOS-lagen voor Berichten en Apple Push voordat je de OpenClaw-configuratie wijzigt. Een eenmalige vernieuwing van de services is vaak voldoende:

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

Stuur een nieuw iMessage vanaf de telefoon en bevestig een nieuwe chat.db-rij of imsg watch-gebeurtenis voordat je fouten in OpenClaw-sessies opspoort. Voer dit niet uit als periodieke herstartlus voor de bridge; herhaalde imsg launch plus herstarts van de Gateway tijdens actief werk kunnen afleveringen onderbreken en actieve kanaaluitvoeringen laten vastlopen.

De standaard cliPath: "imsg" moet worden uitgevoerd op de Mac die bij Berichten is aangemeld. Stel op Linux of Windows channels.imessage.cliPath in op een wrapperscript dat via SSH verbinding maakt met die Mac en imsg "$@" uitvoert.

#!/usr/bin/env bashexec ssh -T messages-mac imsg "$@"

Voer vervolgens uit:

openclaw channels status --probe --channel imessage

Controleer:

• channels.imessage.dmPolicy
• channels.imessage.allowFrom
• koppelingsgoedkeuringen (openclaw pairing list imessage)

Controleer:

• channels.imessage.groupPolicy
• channels.imessage.groupAllowFrom
• gedrag van de toelatingslijst voor channels.imessage.groups
• configuratie van vermeldingspatronen (agents.entries.*.groupChat.mentionPatterns)

Controleer:

• channels.imessage.remoteHost
• channels.imessage.remoteAttachmentRoots
• SSH-/SCP-sleutelauthenticatie vanaf de Gateway-host
• of de hostsleutel op de Gateway-host aanwezig is in ~/.ssh/known_hosts
• of het externe pad leesbaar is op de Mac waarop Berichten wordt uitgevoerd

Voer de opdrachten opnieuw uit in een interactieve GUI-terminal binnen dezelfde gebruikers-/sessiecontext en keur de prompts goed:

imsg chats --limit 1imsg send <handle> "test"

Bevestig dat Volledige schijftoegang + Automatisering zijn verleend voor de procescontext waarin OpenClaw/imsg wordt uitgevoerd.