iMessage

​

Snelle configuratie

brew install steipete/tap/imsg
brew update && brew upgrade 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>

ssh messages-mac 'brew install steipete/tap/imsg && brew update && brew upgrade imsg'

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

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // gebruikt om bijlagen via SCP op te halen
      includeAttachments: true,
      // Optioneel: extra toegestane hoofdlocaties voor bijlagen (samengevoegd met de standaardlocatie
      // /Users/*/Library/Messages/Attachments).
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

​

Vereisten en machtigingen (macOS)

• Berichten moet zijn aangemeld op de Mac waarop imsg wordt uitgevoerd.
• Volledige schijftoegang is vereist voor de procescontext waarin OpenClaw/imsg wordt uitgevoerd (voor toegang tot de Berichten-database).
• Automatiseringsmachtiging is vereist om berichten via Messages.app te verzenden.
• Voor geavanceerde acties (reageren / bewerken / verzending ongedaan maken / antwoord in thread / effecten / peilingen / groepsbewerkingen) moet System Integrity Protection zijn uitgeschakeld — zie De Private API van imsg inschakelen. Het verzenden en ontvangen van gewone tekst en media werkt zonder deze wijziging.

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

Niet gemachtigd om Apple-events naar Berichten te sturen. (-1743)

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

​

De Private API van imsg inschakelen

• Basismodus (standaard, geen SIP-wijzigingen nodig): uitgaande tekst en media via send, bewaking/geschiedenis van inkomende berichten en de chatlijst. Dit krijg je direct met een nieuwe brew install steipete/tap/imsg en de standaard macOS-machtigingen hierboven.
• Private API-modus: imsg injecteert een hulp-dylib in Messages.app om interne IMCore-functies aan te roepen. Hiermee worden react, edit, unsend, reply (in threads), sendWithEffect, poll en poll-vote (systeemeigen peilingen van Berichten), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, plus typindicatoren en leesbevestigingen beschikbaar.

Geavanceerde functies zoals read, typing, launch, uitgebreide verzending via de bridge, berichtmutatie en chatbeheer zijn optioneel. Hiervoor moet SIP zijn uitgeschakeld en moet een hulp-dylib in Messages.app worden geïnjecteerd. imsg launch weigert te injecteren wanneer SIP is ingeschakeld.

​

Configuratie

1. Installeer (of upgrade) imsg op de Mac waarop Messages.app wordt uitgevoerd:
   brew install steipete/tap/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg status --json
   
   De uitvoer van imsg status --json vermeldt bridge_version, rpc_methods en selectors per methode, zodat je vóór de start kunt zien wat de huidige build ondersteunt.
2. Schakel System Integrity Protection en (op moderne macOS-versies) Library Validation uit. Voor het injecteren van een niet van Apple afkomstige hulp-dylib in de door Apple ondertekende Messages.app moet SIP uitgeschakeld zijn en Library Validation versoepeld zijn. De SIP-stap in de herstelmodus verschilt per macOS-versie:
   • macOS 10.13-10.15 (Sierra-Catalina): schakel Library Validation uit via Terminal, start opnieuw op in de herstelmodus, voer csrutil disable uit en start opnieuw op.
   • macOS 11+ (Big Sur en later), Intel: herstelmodus (of Internet Recovery), csrutil disable, opnieuw opstarten.
   • macOS 11+, Apple Silicon: gebruik de opstartprocedure met de aan/uit-knop om de herstelmodus te openen; houd bij recente macOS-versies de toets Left Shift ingedrukt wanneer je op Continue klikt en voer vervolgens csrutil disable uit. Voor virtuele machines geldt een afzonderlijke procedure, dus maak eerst een VM-momentopname.
   Op macOS 11 en later is alleen csrutil disable meestal niet voldoende. Apple dwingt Library Validation nog steeds af voor Messages.app als platformbinair bestand, waardoor een ad-hoc ondertekende helper wordt geweigerd (Library Validation failed: ... platform binary, but mapped file is not), zelfs als SIP uitstaat. Schakel na SIP ook Library Validation uit en start opnieuw op:
   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true
   
   macOS 26 (Tahoe), geverifieerd op 26.5.1: uitgeschakelde SIP plus de bovenstaande opdracht DisableLibraryValidation volstaat om de helper te injecteren in versies 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 op Tahoe mislukt:
   • Met de plist: imsg launch injecteert en imsg status meldt advanced_features: true.
   • Zonder de plist (zelfs als SIP uitstaat): imsg launch mislukt met Failed to launch: Timeout waiting for Messages.app to initialize. AMFI weigert de ad-hoc helper bij het laden, waardoor de bridge nooit gereed wordt en het starten een time-out bereikt. Die time-out is het symptoom dat de meeste mensen op Tahoe tegenkomen; de oplossing is de bovenstaande plist, niet iets ingrijpenders.
   Als de injectie van imsg launch of specifieke selectors na een macOS-upgrade false beginnen te retourneren, is deze beveiligingspoort doorgaans de oorzaak. Controleer de status van SIP en Library Validation 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 bij het project imsg, in plaats van aanvullende systeembrede beveiligingsmaatregelen te verzwakken.
3. Injecteer de helper. Met SIP uitgeschakeld en aangemeld bij Messages.app:
   imsg launch
   
   imsg launch weigert te injecteren wanneer SIP nog is ingeschakeld, dus dit dient ook als bevestiging dat stap 2 is uitgevoerd.
4. Verifieer de bridge vanuit OpenClaw:
   openclaw channels status --probe
   
   De iMessage-vermelding moet works melden en imsg status --json | jq '{rpc_methods, selectors}' moet de mogelijkheden tonen die je macOS-build beschikbaar stelt. Voor het maken van peilingen is selectors.pollPayloadMessage vereist; voor stemmen zijn zowel selectors.pollVoteMessage als de RPC-methode poll.vote vereist. De OpenClaw-plugin kondigt alleen acties aan die door de gecachte probe worden ondersteund, terwijl bij een lege cache optimistisch wordt uitgegaan van ondersteuning en bij de eerste verzending een probe wordt uitgevoerd.

​

Wanneer SIP ingeschakeld blijft

• imsg valt terug op de basismodus — alleen tekst + media + ontvangen.
• De OpenClaw-plugin kondigt nog steeds het verzenden van tekst/media en het bewaken van inkomende berichten aan; react, edit, unsend, reply, sendWithEffect en groepsbewerkingen worden verborgen uit het actieoppervlak (volgens de mogelijkhedenpoort per methode).
• Je kunt een afzonderlijke Mac zonder Apple Silicon (of een speciale bot-Mac) met uitgeschakelde SIP gebruiken voor de iMessage-werklast, terwijl SIP op je primaire apparaten ingeschakeld blijft. Zie hieronder Speciale macOS-gebruiker voor de bot (afzonderlijke iMessage-identiteit).

​

Toegangsbeheer en routering

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: { "*": { "requireMention": true } },
    },
  },
}

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { systemPrompt: "Gebruik de Britse spelling." },
        "8421": {
          requireMention: true,
          systemPrompt: "Dit is de chat voor de wachtdienst. Houd antwoorden korter dan 3 zinnen.",
        },
        "9907": {
          // expliciete onderdrukking: het jokerteken "Gebruik de Britse spelling." is hier niet van toepassing
          systemPrompt: "",
        },
      },
    },
  },
}

​

ACP-gesprekskoppelingen

• Voer /acp spawn codex --bind here uit in de DM of toegestane groepschat.
• Toekomstige berichten in datzelfde iMessage-gesprek worden naar de gestarte ACP-sessie gerouteerd.
• /new en /reset stellen dezelfde gekoppelde ACP-sessie ter plaatse opnieuw in.
• /acp close sluit de ACP-sessie en verwijdert de koppeling.

• genormaliseerde DM-handle, zoals +15555550123 of user@example.com
• chat_id:<id> (aanbevolen voor stabiele groepskoppelingen)
• 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" },
    },
  ],
}

​

Implementatiepatronen

{
  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, opsplitsing en afleveringsdoelen

imsg chats --limit 20

​

Acties van de privé-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,
    },
  },
}

​

Configuratieschrijfbewerkingen

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

​

Gesplitst verzonden DM’s samenvoegen (opdracht + URL in één compositie)

brew update && brew upgrade imsg

​

Herstel van inkomende berichten na een herstart van de bridge of Gateway

• Duurzame bescherming tegen herhaling. Voordat de herstelcursor wordt vooruitgeschoven, registreert OpenClaw elke onbewerkte rij in de gedeelde SQLite-invoerwachtrij, met de Apple-GUID als gebeurtenis-ID. Een voltooide rij laat ongeveer 4 uur lang een tombstone achter, met een maximum van 10.000 vermeldingen, zodat een herhaling met dezelfde GUID zelfs na een herstart wordt verwijderd. Een openstaande rij blijft herstelbaar totdat de verzending deze overneemt.
• Herstel na uitvaltijd. Bij het opstarten onthoudt de monitor de rowid van de laatst duurzaam toegelaten chat.db-rij (een permanente cursor per account) en geeft deze als since_rowid door aan imsg watch.subscribe, zodat imsg rijen herhaalt die nog niet waren geregistreerd en daarna live blijft volgen. Rijen die vóór een crash zijn geregistreerd, worden vanuit SQLite hervat. De herhaling is beperkt tot de meest recente 500 rijen en tot berichten van maximaal ~2 uur oud, en GUID-tombstones verwijderen alles wat al is verwerkt.
• Leeftijdsgrens voor verouderde backlog. Rijen boven de opstartgrens zijn daadwerkelijk live; een rij waarvan de verzenddatum meer dan ~15 minuten vóór de aankomsttijd ligt, behoort tot de doorgestroomde Push-backlog en wordt onderdrukt. Herhaalde rijen (op of onder de grens) gebruiken in plaats daarvan het ruimere herstelvenster, zodat een recent gemist bericht wordt afgeleverd maar oude geschiedenis niet.

​

Voor de operator zichtbaar signaal

imessage: verouderde inkomende backlog onderdrukt account=<id> verzonden=<iso> herstel=<bool> (<N> onderdrukt sinds de start)

​

Migratie

​

Problemen oplossen

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 de configuratiereferentie

• Configuratiereferentie - iMessage
• Gateway-configuratie
• Koppelen

​

Gerelateerd

• Overzicht van kanalen — alle ondersteunde kanalen
• Verwijdering van BlueBubbles en het imsg-pad voor iMessage — aankondiging en migratiesamenvatting
• Overstappen vanaf BlueBubbles — tabel voor configuratievertaling en stapsgewijze overstap
• Koppelen — DM-authenticatie en koppelingsflow
• Groepen — gedrag van groepschats en toelating op basis van vermeldingen
• Kanaalroutering — sessieroutering voor berichten
• Beveiliging — toegangsmodel en beveiliging aanscherpen