iMessage

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Snelle installatie

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 aangemeld 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 / groepsbewerkingen) moet System Integrity Protection zijn uitgeschakeld — zie De imsg private API inschakelen hieronder. Basis verzenden/ontvangen van tekst en media werkt zonder.

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

​

De imsg private API inschakelen

• Basismodus (standaard, geen SIP-wijzigingen nodig): uitgaande tekst en media via send, inkomende watch/geschiedenis, 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. Hiermee worden react, edit, unsend, reply (threaded), sendWithEffect, renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, plus typindicatoren en leesbevestigingen ontgrendeld.

Geavanceerde functies zoals read, typing, launch, bridge-backed rich send, 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.

​

Installatie

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. Dit is macOS-versiespecifiek omdat de onderliggende Apple-vereiste afhangt van het OS en de hardware:
   • 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: opstartprocedure met de aan/uit-knop om Recovery te openen; houd op recente macOS-versies de linker Shift-toets ingedrukt wanneer je op Continue klikt, daarna csrutil disable. Virtual-machine-installaties volgen een aparte flow — maak eerst een VM-snapshot.
   • macOS 26 / Tahoe: library-validation-beleid en private-entitlement-controles van imagent zijn verder aangescherpt; imsg heeft mogelijk een bijgewerkte build nodig om bij te blijven. Als imsg launch-injectie of specifieke selectors na een grote macOS-upgrade false beginnen terug te geven, controleer dan de release notes van imsg voordat je aanneemt dat de SIP-stap is geslaagd.
   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 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 moet works rapporteren, en imsg status --json | jq '.selectors' moet retractMessagePart: true tonen plus de edit-/typing-/read-selectors die je macOS-build blootstelt. De per-method gating van de OpenClaw-plugin in actions.ts adverteert alleen acties waarvan de onderliggende selector true is, dus het actieoppervlak dat je in de toollijst van de agent ziet, weerspiegelt wat de bridge daadwerkelijk op deze host kan doen.

​

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 per-method capability gate).
• Je kunt een aparte niet-Apple-Silicon-Mac (of een dedicated bot-Mac) met SIP uit gebruiken voor de iMessage-workload, terwijl je SIP ingeschakeld houdt op je primaire apparaten. Zie Dedicated bot macOS-gebruiker (aparte iMessage-identiteit) hieronder.

​

Toegangscontrole en routing

{
  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 in 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 op zijn plaats.
• /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" },
    },
  ],
}

​

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 bezorgdoelen

imsg chats --limit 20

​

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

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

​

Configuratiewrites

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

​

Gesplitst verzonden DM’s samenvoegen (opdracht + 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: {
        // 2500 ms works for most setups; raise to 4000 ms if your Mac is
        // slow or under memory pressure (observed gap can stretch past 2 s
        // then).
        imessage: 2500,
      },
    },
  },
}

​

Scenario’s en wat de agent ziet

​

Inhalen na Gateway-downtime

channels: {
  imessage: {
    catchup: {
      enabled: true,             // master switch (default: false)
      maxAgeMinutes: 120,        // skip rows older than now - 2h (default: 120, clamp 1..720)
      perRunLimit: 50,           // max rows replayed per startup (default: 50, clamp 1..500)
      firstRunLookbackMinutes: 30, // first run with no cursor: look back 30 min (default: 30)
      maxFailureRetries: 10,     // give up on a wedged guid after 10 dispatch failures (default: 10)
    },
  },
}

​

Hoe het draait

​

Cursor- en retrysemantiek

{
  "lastSeenMs": 1717900800000,
  "lastSeenRowid": 482910,
  "updatedAt": 1717900801234,
  "failureRetries": { "<guid>": 1 }
}

• De cursor schuift op na elke succesvolle dispatch en blijft staan wanneer de dispatch van een rij een exception gooit — de volgende start probeert dezelfde rij opnieuw vanaf de vastgehouden cursor.
• Na maxFailureRetries opeenvolgende exceptions voor dezelfde guid logt catchup een warn en forceert het opschuiven van de cursor voorbij het vastgelopen bericht, zodat latere starts voortgang kunnen maken.
• GUID’s die al zijn opgegeven, worden bij later runs bij zicht overgeslagen (geen dispatch-poging) en meegeteld onder skippedGivenUp in de run-samenvatting.

​

Operator-zichtbare signalen

imessage catchup: replayed=N skippedFromMe=… skippedGivenUp=… failed=… givenUp=… fetchedCount=…
imessage catchup: giving up on guid=<guid> after <N> failures; advancing cursor past it
imessage catchup: fetched <X> rows across chats, capped to perRunLimit=<Y>

​

Wanneer je het uit laat

• Gateway draait continu met watchdog-autoherstart en onderbrekingen zijn altijd < een paar seconden — de standaard uitgeschakelde stand is prima.
• DM-volume is laag en gemiste berichten zouden het gedrag van de agent niet veranderen — het initiële venster firstRunLookbackMinutes kan bij de eerste inschakeling verrassende oude context dispatchen.

​

Probleemoplossing

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

#!/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

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