iMessage

Status: native externe CLI-integratie. Gateway start imsg rpc en communiceert via JSON-RPC over stdio (geen afzonderlijke daemon/poort). Geavanceerde acties vereisen imsg launch en een geslaagde private API-probe.

Snelle setup

brew install steipete/tap/imsgimsg rpc --helpimsg launchopenclaw channels status --probe

{channels: {imessage: {enabled: true,cliPath: "/usr/local/bin/imsg",dbPath: "/Users/user/Library/Messages/chat.db",},},}

openclaw gateway

openclaw pairing list imessageopenclaw pairing approve imessage <CODE>

#!/usr/bin/env bashexec ssh -T gateway-host imsg "$@"

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // used for SCP attachment fetches  includeAttachments: true,  // Optional: override allowed attachment roots.  // Defaults include /Users/*/Library/Messages/Attachments  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

Vereisten en machtigingen (macOS)

• Messages moet zijn ingelogd op de Mac waarop imsg draait.
• Full Disk Access is vereist voor de procescontext waarin OpenClaw/imsg draait (toegang tot de Messages-database).
• Automatiseringsmachtiging is vereist om berichten via Messages.app te verzenden.
• Voor geavanceerde acties (reageren / bewerken / verzenden ongedaan maken / antwoord in thread / effecten / peilingen / groepsbewerkingen) moet System Integrity Protection zijn uitgeschakeld — zie De imsg private API inschakelen hieronder. Basisfunctionaliteit voor tekst en media verzenden/ontvangen werkt zonder dit.

Not authorized to send Apple events to Messages. (-1743)

kTCCServiceAppleEvents | /usr/libexec/sshd-keygen-wrapper | auth_value=0 | com.apple.MobileSMS

De imsg private API inschakelen

imsg wordt geleverd in twee operationele modi:

• Basismodus (standaard, geen SIP-wijzigingen nodig): uitgaande tekst en media via send, inkomende watch/history, chatlijst. Dit krijg je direct na een nieuwe brew install steipete/tap/imsg plus de standaard macOS-machtigingen hierboven.
• Private API-modus: imsg injecteert een helper-dylib in Messages.app om interne IMCore-functies aan te roepen. Dit ontgrendelt react, edit, unsend, reply (threaded), sendWithEffect, poll en poll-vote (native Messages-peilingen), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, plus type-indicatoren en leesbevestigingen.

Om het geavanceerde actieoppervlak te bereiken dat deze kanaalpagina documenteert, heb je Private API-modus nodig. De imsg README is expliciet over de vereiste:

Geavanceerde functies zoals read, typing, launch, bridge-backed rijke verzending, berichtmutatie en chatbeheer zijn opt-in. Ze vereisen dat SIP is uitgeschakeld en dat een helper-dylib in Messages.app wordt geïnjecteerd. imsg launch weigert te injecteren wanneer SIP is ingeschakeld.

De helper-injectietechniek gebruikt de eigen dylib van imsg om Messages private APIs te bereiken. Er is geen externe server of BlueBubbles-runtime in het OpenClaw iMessage-pad.

Setup

1. Installeer (of upgrade) imsg op de Mac waarop Messages.app draait:

   brew install steipete/tap/imsgimsg --versionimsg status --json

   De uitvoer van imsg status --json rapporteert bridge_version, rpc_methods en per methode selectors, zodat je kunt zien wat de huidige build ondersteunt voordat je begint.

2. Schakel System Integrity Protection uit, en (op moderne macOS) Library Validation. Het injecteren van een niet-Apple helper-dylib in de door Apple ondertekende Messages.app vereist dat SIP uit staat en dat library validation is versoepeld. De SIP-stap in Recovery-modus is macOS-versiespecifiek:

   • macOS 10.13-10.15 (Sierra-Catalina): schakel Library Validation uit via Terminal, herstart naar Recovery Mode, voer csrutil disable uit, herstart.
   • macOS 11+ (Big Sur en later), Intel: Recovery Mode (of Internet Recovery), csrutil disable, herstart.
   • macOS 11+, Apple Silicon: opstartreeks met de aan/uit-knop om Recovery te openen; houd op recente macOS-versies de Left Shift-toets ingedrukt wanneer je op Continue klikt, daarna csrutil disable. Virtual-machine-setups volgen een aparte flow, dus maak eerst een VM-snapshot.

   Op macOS 11 en later is alleen csrutil disable meestal niet genoeg. Apple handhaaft library validation nog steeds tegen Messages.app als platform binary, waardoor een adhoc-ondertekende helper wordt geweigerd (Library Validation failed: ... platform binary, but mapped file is not), zelfs met SIP uit. Schakel na het uitschakelen van SIP ook library validation uit en herstart:

   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true

   macOS 26 (Tahoe), geverifieerd op 26.5.1: SIP uit plus de bovenstaande DisableLibraryValidation-opdracht is voldoende om de helper te injecteren in 26.0 tot en met 26.5.x. Er zijn geen boot-args vereist. De plist is de doorslaggevende factor en de meest voorkomende ontbrekende stap wanneer injectie mislukt op Tahoe:

   • Met de plist: imsg launch injecteert en imsg status rapporteert advanced_features: true.
   • Zonder de plist (zelfs met SIP uit): imsg launch mislukt met Failed to launch: Timeout waiting for Messages.app to initialize. AMFI weigert de adhoc-helper bij het laden, waardoor de bridge nooit gereed wordt en de launch time-out. Die time-out is het symptoom dat de meeste mensen op Tahoe tegenkomen, en de oplossing is de plist hierboven, niet iets ingrijpenders.

   Dit is bevestigd met een gecontroleerde voor/na-test op macOS 26.5.1 (Apple Silicon): met de plist wordt de dylib in Messages.app gemapt en komt de bridge op; verwijder de plist en herstart, en imsg launch produceert de bovenstaande time-outfout zonder dat de dylib wordt gemapt.

   Als imsg launch-injectie of specifieke selectors na een macOS-upgrade false beginnen terug te geven, is deze gate meestal de oorzaak. Controleer je SIP- en library-validation-status voordat je aanneemt dat de SIP-stap zelf is mislukt. Als die instellingen correct zijn en de bridge nog steeds niet kan injecteren, verzamel dan imsg status --json plus de uitvoer van imsg launch en meld dit aan het imsg-project in plaats van extra systeembrede beveiligingsmaatregelen te verzwakken.

   Volg Apple's Recovery-mode-flow voor je Mac om SIP uit te schakelen voordat je imsg launch uitvoert.

3. Injecteer de helper. Met SIP uitgeschakeld en Messages.app aangemeld:

   imsg launch

   imsg launch weigert te injecteren wanneer SIP nog steeds is ingeschakeld, dus dit dient ook als bevestiging dat stap 2 is gelukt.

4. Verifieer de bridge vanuit OpenClaw:

   openclaw channels status --probe

   De iMessage-vermelding zou works moeten rapporteren, en imsg status --json | jq '{rpc_methods, selectors}' zou de mogelijkheden moeten tonen die door je macOS-build worden blootgesteld. Poll-aanmaak vereist selectors.pollPayloadMessage; stemmen vereist zowel selectors.pollVoteMessage als de poll.vote-RPC-methode. De OpenClaw-Plugin adverteert alleen acties die worden ondersteund door de gecachte probe, terwijl een lege cache optimistisch blijft en bij de eerste dispatch probet.

Als openclaw channels status --probe het kanaal als works rapporteert maar specifieke acties tijdens dispatch "iMessage <action> requires the imsg private API bridge" gooien, voer dan imsg launch opnieuw uit — de helper kan wegvallen (herstart van Messages.app, OS-update, enz.) en de gecachte available: true-status blijft acties adverteren totdat de volgende probe wordt vernieuwd.

Wanneer je SIP niet kunt uitschakelen

Als SIP-uitgeschakeld niet acceptabel is voor je dreigingsmodel:

• imsg valt terug naar basismodus — alleen tekst + media + ontvangen.
• De OpenClaw-Plugin adverteert nog steeds tekst/media verzenden en inkomende monitoring; hij verbergt alleen react, edit, unsend, reply, sendWithEffect en groepsbewerkingen uit het actieoppervlak (volgens de capability-gate per methode).
• Je kunt een aparte niet-Apple-Silicon Mac (of een dedicated bot-Mac) met SIP uit gebruiken voor de iMessage-workload, terwijl SIP op je primaire apparaten ingeschakeld blijft. Zie Dedicated bot macOS user (separate iMessage identity) hieronder.

Toegangscontrole en routering

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "Use British spelling." },        "8421": {          requireMention: true,          systemPrompt: "This is the on-call rotation chat. Keep replies under 3 sentences.",        },        "9907": {          // explicit suppression: the wildcard "Use British spelling." does not apply here          systemPrompt: "",        },      },    },  },}

ACP-gespreksbindingen

Verouderde iMessage-chats kunnen ook aan ACP-sessies worden gebonden.

Snelle operatorflow:

• Voer /acp spawn codex --bind here uit binnen de DM of toegestane groepschat.
• Toekomstige berichten in datzelfde iMessage-gesprek worden naar de gespawnde ACP-sessie gerouteerd.
• /new en /reset resetten dezelfde gebonden ACP-sessie ter plekke.
• /acp close sluit de ACP-sessie en verwijdert de binding.

Geconfigureerde persistente bindingen worden ondersteund via top-level bindings[]-vermeldingen met type: "acp" en match.channel: "imessage".

match.peer.id kan het volgende gebruiken:

• genormaliseerde DM-handle zoals +15555550123 of user@example.com
• chat_id:<id> (aanbevolen voor stabiele groepsbindingen)
• chat_guid:<guid>
• chat_identifier:<identifier>

Voorbeeld:

{  agents: {    list: [      {        id: "codex",        runtime: {          type: "acp",          acp: { agent: "codex", backend: "acpx", mode: "persistent" },        },      },    ],  },  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "imessage",        accountId: "default",        peer: { kind: "group", id: "chat_id:123" },      },      acp: { label: "codex-group" },    },  ],}

Zie ACP-agenten voor gedeeld gedrag van ACP-bindingen.

Deploymentpatronen

{  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 "$@"

Media, chunking en bezorgdoelen

imsg chats --limit 20

Acties voor private API

Wanneer imsg launch actief is en openclaw channels status --probe privateApi.available: true meldt, kan de berichtentool naast normale tekstverzending ook iMessage-native acties gebruiken.

{  channels: {    imessage: {      actions: {        reactions: true,        edit: true,        unsend: true,        reply: true,        sendWithEffect: true,        sendAttachment: true,        renameGroup: true,        setGroupIcon: true,        addParticipant: true,        removeParticipant: true,        leaveGroup: true,        polls: true,      },    },  },}

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

Configuratieschrijfacties

iMessage staat standaard door het kanaal geïnitieerde configuratieschrijfacties toe (voor /config set|unset wanneer commands.config: true).

Uitschakelen:

{  channels: {    imessage: {      configWrites: false,    },  },}

Split-send-DM's samenvoegen (command + URL in één compositie)

Wanneer een gebruiker een command en een URL samen typt — bijvoorbeeld Dump https://example.com/article — splitst Apple's Messages-app de verzending in twee afzonderlijke chat.db-rijen:

1. Een tekstbericht ("Dump").
2. Een URL-previewballon ("https://...") met OG-previewafbeeldingen als bijlagen.

De twee rijen komen op de meeste setups ~0,8-2,0 s na elkaar bij OpenClaw aan. Zonder samenvoeging ontvangt de agent alleen het command in turn 1, antwoordt hij (vaak "stuur me de URL") en ziet hij de URL pas in turn 2 — op dat punt is de commandcontext al verloren. Dit is Apple's verzendpipeline, niet iets wat OpenClaw of imsg introduceert.

channels.imessage.coalesceSameSenderDms laat een DM opeenvolgende rijen van dezelfde afzender bufferen. Wanneer imsg de structurele URL-previewmarkering balloon_bundle_id: "com.apple.messages.URLBalloonProvider" op een van de bronrijen blootlegt, voegt OpenClaw alleen die echte split-send samen en houdt het alle andere gebufferde rijen als afzonderlijke turns. Op oudere imsg-builds die helemaal geen ballonmetadata uitsturen, kan OpenClaw een split-send niet onderscheiden van afzonderlijke verzendingen, dus valt het terug op het samenvoegen van de bucket. Dat behoudt het gedrag van vóór metadata in plaats van Dump <url>-split-sends te laten regresseren naar twee turns. Groepschats blijven per bericht dispatchen zodat de turnstructuur met meerdere gebruikers behouden blijft.

{  channels: {    imessage: {      coalesceSameSenderDms: true, // opt in (default: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 7000 ms covers observed Messages.app URL-preview delays.        imessage: 7000,      },    },  },}

Scenario's en wat de agent ziet

De kolom "Vlag aan" toont gedrag op een imsg-build die balloon_bundle_id uitstuurt. Op oudere imsg-builds die helemaal geen balloon-metadata uitsturen, vallen de rijen hieronder die zijn gemarkeerd als "Twee beurten" / "N beurten" in plaats daarvan terug op een verouderde samenvoeging (één beurt): OpenClaw kan een gesplitste verzending structureel niet onderscheiden van aparte verzendingen, dus behoudt het de samenvoeging van vóór de metadata. Precieze scheiding wordt actief zodra de build balloon-metadata uitstuurt.

Inbound-herstel na een herstart van bridge of Gateway

iMessage herstelt berichten die zijn gemist terwijl de Gateway offline was, en onderdrukt tegelijk de oude "backlogbom" die Apple na een Push-herstel kan doorspoelen. Het standaardgedrag staat altijd aan en is gebouwd op de inbound-dedupe.

• Replay-dedupe. Elk verzonden inbound-bericht wordt met zijn Apple-GUID vastgelegd in persistente Plugin-status (imessage.inbound-dedupe), geclaimd bij ingestie en vastgelegd na verwerking (vrijgegeven bij een tijdelijke fout zodat het opnieuw kan proberen). Alles wat al is verwerkt, wordt weggegooid in plaats van twee keer verzonden. Hierdoor kan herstel agressief opnieuw afspelen zonder administratie per bericht.
• Downtime-herstel. Bij het opstarten onthoudt de monitor de laatst verzonden chat.db-rowid (een persistente cursor per account) en geeft die door aan imsg watch.subscribe als since_rowid, zodat imsg de rijen opnieuw afspeelt die binnenkwamen terwijl de Gateway offline was, en daarna live volgt. Replay is begrensd tot de meest recente rijen en tot berichten van maximaal ~2 uur oud, en de dedupe verwijdert alles wat al is verwerkt.
• Leeftijdsgrens voor oude backlog. Rijen boven de opstartgrens zijn echt live; een rij waarvan de verzenddatum meer dan ~15 minuten ouder is dan de aankomsttijd, is de Push-flush-backlog en wordt onderdrukt. Opnieuw afgespeelde rijen (op of onder de grens) gebruiken in plaats daarvan het bredere herstelvenster, zodat een recent gemist bericht wordt afgeleverd terwijl oude geschiedenis dat niet wordt.

Herstel werkt met zowel lokale als externe cliPath-setups, omdat since_rowid-replay via dezelfde imsg-RPC-verbinding loopt. Het verschil is het venster: wanneer de Gateway chat.db kan lezen (lokaal), verankert deze de opstart-rowid-grens, begrenst de replay-spanne en levert gemiste berichten tot een paar uur oud af. Via een externe SSH-cliPath kan deze de database niet lezen, dus is replay onbeperkt en gebruikt elke rij de live-leeftijdsgrens — het herstelt nog steeds recent gemiste berichten en onderdrukt nog steeds oude backlog, alleen met het smallere livevenster. Voer de Gateway uit op de Messages-Mac voor het bredere herstelvenster.

Operator-zichtbaar signaal

Onderdrukte backlog wordt op het standaardniveau gelogd, nooit stilzwijgend weggegooid (de vlag recovery toont welk venster is toegepast):

imessage: suppressed stale inbound backlog account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; suppressed since start)

Migratie

channels.imessage.catchup.* is verouderd — downtime-herstel is nu automatisch en vereist geen configuratie voor nieuwe setups. Bestaande configuraties met catchup.enabled: true blijven gehonoreerd als compatibiliteitsprofiel voor het herstel-replayvenster. Uitgeschakelde catchup-blokken (enabled: false of geen enabled: true) zijn uitgefaseerd; openclaw doctor --fix verwijdert die.

Probleemoplossing

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

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;"

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

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

openclaw channels status --probe --channel imessage

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

Verwijzingen naar configuratiereferentie

• Configuratiereferentie - iMessage
• Gateway-configuratie
• Koppeling

Gerelateerd

• Kanalenoverzicht — alle ondersteunde kanalen
• BlueBubbles-verwijdering en het imsg iMessage-pad — aankondiging en migratiesamenvatting
• Overstappen vanaf BlueBubbles — configuratievertaaltabel en stapsgewijze overstap
• Koppeling — DM-authenticatie en koppelingsflow
• Groepen — groepschatgedrag en vermeldingspoort
• Kanaalroutering — sessieroutering voor berichten
• Beveiliging — toegangsmodel en hardening