iMessage

​

Snelle setup

brew install steipete/tap/imsg
imsg rpc --help
imsg launch
openclaw channels status --probe

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

openclaw gateway

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

#!/usr/bin/env bash
exec 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.

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

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

• 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.

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.

​

Setup

1. Installeer (of upgrade) imsg op de Mac waarop Messages.app draait:
   brew install steipete/tap/imsg
   imsg --version
   imsg 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.

​

Wanneer je SIP niet kunt uitschakelen

• 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: { "*": { "requireMention": true } },
    },
  },
}

{
  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

• 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.

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

{
  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" },
    },
  ],
}

​

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

​

Media, chunking en bezorgdoelen

imsg chats --limit 20

​

Acties voor private API

{
  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

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

​

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

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

{
  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

​

Inbound-herstel na een herstart van bridge of Gateway

• 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.

​

Operator-zichtbaar signaal

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

​

Migratie

​

Probleemoplossing

imsg rpc --help
imsg status --json
openclaw channels status --probe

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

launchctl kickstart -k system/com.apple.apsd
launchctl kickstart -k gui/$(id -u)/com.apple.CommCenter
launchctl kickstart -k gui/$(id -u)/com.apple.identityservicesd
launchctl kickstart -k gui/$(id -u)/com.apple.imagent
imsg launch
openclaw gateway restart

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

openclaw channels status --probe --channel imessage

imsg chats --limit 1
imsg 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