iMessage (legacy: imsg)

Waarschuwing: Gebruik voor nieuwe iMessage-installaties BlueBubbles.

De imsg-integratie is verouderd en kan in een toekomstige versie worden verwijderd.

Status: verouderde externe CLI-integratie. De gateway start imsg rpc en communiceert via JSON-RPC over stdio (geen aparte daemon/poort).

• BlueBubbles (aanbevolen) — Voorkeurspad voor iMessage bij nieuwe installaties.
• Koppeling — iMessage-DM’s staan standaard op koppelingsmodus.
• Configuratiereferentie — Volledige iMessage-veldreferentie.

Snelle installatie

Lokale Mac (snel pad)

  ### Stap 1: Installeer en verifieer imsg

brew install steipete/tap/imsg
imsg rpc --help

  ### Stap 2: Configureer OpenClaw

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

  ### Stap 3: Start de gateway

openclaw gateway

  ### Stap 4: Keur eerste DM-koppeling goed (standaard dmPolicy)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

    Koppelingverzoeken verlopen na 1 uur.

Externe Mac via SSH

OpenClaw heeft alleen een stdio-compatibel `cliPath` nodig, dus je kunt `cliPath` wijzen naar een wrapper-script dat via SSH naar een externe Mac gaat en `imsg` uitvoert.

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

Aanbevolen configuratie wanneer bijlagen zijn ingeschakeld:

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

Als `remoteHost` niet is ingesteld, probeert OpenClaw het automatisch te detecteren door het SSH-wrapper-script te parsen.
`remoteHost` moet `host` of `user@host` zijn (geen spaties of SSH-opties).
OpenClaw gebruikt strikte hostsleutelcontrole voor SCP, dus de relay-hostsleutel moet al bestaan in `~/.ssh/known_hosts`.
Bijlagepaden worden gevalideerd tegen toegestane roots (`attachmentRoots` / `remoteAttachmentRoots`).

Vereisten en machtigingen (macOS)

• Berichten moet zijn ingelogd op de Mac die imsg draait.
• Volledige schijftoegang is vereist voor de procescontext die OpenClaw/imsg draait (toegang tot de Berichten-database).
• Automatiseringsmachtiging is vereist om berichten via Berichten.app te versturen.

Tip: Machtigingen worden per procescontext verleend. Als de gateway headless draait (LaunchAgent/SSH), voer dan een eenmalig interactief commando uit in diezelfde context om de prompts te activeren:

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

Toegangscontrole en routering

DM-beleid

`channels.imessage.dmPolicy` beheert directe berichten:

- `pairing` (standaard)
- `allowlist`
- `open` (vereist dat `allowFrom` `"*"` bevat)
- `disabled`

Allowlist-veld: `channels.imessage.allowFrom`.

Allowlist-vermeldingen kunnen handles of chatdoelen zijn (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`).

Groepsbeleid + vermeldingen

`channels.imessage.groupPolicy` beheert groepsafhandeling:

- `allowlist` (standaard wanneer geconfigureerd)
- `open`
- `disabled`

Groepsafzender-allowlist: `channels.imessage.groupAllowFrom`.

Runtime-terugval: als `groupAllowFrom` niet is ingesteld, vallen iMessage-groepsafzendercontroles terug op `allowFrom` wanneer beschikbaar.
Runtime-opmerking: als `channels.imessage` volledig ontbreekt, valt de runtime terug op `groupPolicy="allowlist"` en logt een waarschuwing (zelfs als `channels.defaults.groupPolicy` is ingesteld).

Mention-gating voor groepen:

- iMessage heeft geen native mention-metadata
- Mention-detectie gebruikt regex-patronen (`agents.list[].groupChat.mentionPatterns`, terugval `messages.groupChat.mentionPatterns`)
- Zonder geconfigureerde patronen kan mention-gating niet worden afgedwongen

Besturingscommando's van geautoriseerde afzenders kunnen mention-gating in groepen omzeilen.

Sessies en deterministische antwoorden

- DM's gebruiken directe routering; groepen gebruiken groepsroutering.
- Met standaard `session.dmScope=main` worden iMessage-DM's samengevoegd in de agent-hoofdsessie.
- Groepssessies zijn geïsoleerd (`agent:<agentId>:imessage:group:<chat_id>`).
- Antwoorden worden teruggerouteerd naar iMessage via oorspronkelijke kanaal-/doelmetadata.

Groepsachtig threadgedrag:

Sommige multi-deelnemer iMessage-threads kunnen aankomen met `is_group=false`.
Als die `chat_id` expliciet is geconfigureerd onder `channels.imessage.groups`, behandelt OpenClaw het als groepsverkeer (groepsgating + groepssessie-isolatie).

Implementatiepatronen

Gebruik een toegewijd Apple ID en macOS-gebruiker zodat botverkeer is geïsoleerd van je persoonlijke Berichten-profiel.

Typische flow:

1. Maak een toegewijde macOS-gebruiker aan/log in.
2. Log in bij Berichten met het bot-Apple ID in die gebruiker.
3. Installeer `imsg` in die gebruiker.
4. Maak een SSH-wrapper zodat OpenClaw `imsg` kan uitvoeren in die gebruikerscontext.
5. Wijs `channels.imessage.accounts.<id>.cliPath` en `.dbPath` naar dat gebruikersprofiel.

De eerste keer kan GUI-goedkeuringen vereisen (Automatisering + Volledige schijftoegang) in die bot-gebruikerssessie.

Veelvoorkomende 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 SCP-bijlage-ophaling mogelijk

Voorbeeld:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "[email protected]",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T [email protected] imsg "$@"

Gebruik SSH-sleutels zodat zowel SSH als SCP niet-interactief zijn.
Zorg ervoor dat de hostsleutel eerst is vertrouwd (bijv. `ssh [email protected]`) zodat `known_hosts` is ingevuld.

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

Elk account kan velden overschrijven zoals `cliPath`, `dbPath`, `allowFrom`, `groupPolicy`, `mediaMaxMb`, geschiedenisinstellingen en bijlageroot-allowlists.

Media, opsplitsing en afleveringsdoelen

- Inkomende bijlage-ingestie is optioneel: `channels.imessage.includeAttachments`
- Externe bijlagepaden kunnen via SCP worden opgehaald wanneer `remoteHost` is ingesteld
- Bijlagepaden moeten overeenkomen met toegestane roots:
  - `channels.imessage.attachmentRoots` (lokaal)
  - `channels.imessage.remoteAttachmentRoots` (externe SCP-modus)
  - Standaard rootpatroon: `/Users/*/Library/Messages/Attachments`
- SCP gebruikt strikte hostsleutelcontrole (`StrictHostKeyChecking=yes`)
- Uitgaande mediagrootte gebruikt `channels.imessage.mediaMaxMb` (standaard 16 MB)

- Tekstchunklimiet: `channels.imessage.textChunkLimit` (standaard 4000)
- Chunkmodus: `channels.imessage.chunkMode`
  - `length` (standaard)
  - `newline` (alinea-eerst opsplitsing)

Voorkeur expliciete doelen:

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

Handle-doelen worden ook ondersteund:

- `imessage:+1555...`
- `sms:+1555...`
- `[email protected]`

imsg chats --limit 20

Configschrijfacties

iMessage staat standaard kanaalgeïnitieerde configschrijfacties toe (voor /config set|unset wanneer commands.config: true).

Uitschakelen:

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

Probleemoplossing

Valideer de binary en RPC-ondersteuning:

imsg rpc --help
openclaw channels status --probe

Als probe meldt dat RPC niet wordt ondersteund, werk `imsg` bij.

Controleer:

- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- Koppelings-goedkeuringen (`openclaw pairing list imessage`)

Controleer:

- `channels.imessage.groupPolicy`
- `channels.imessage.groupAllowFrom`
- `channels.imessage.groups` allowlist-gedrag
- Mention-patroonconfiguratie (`agents.list[].groupChat.mentionPatterns`)

Controleer:

- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- SSH/SCP-sleutelauthenticatie vanaf de gatewayhost
- Hostsleutel bestaat in `~/.ssh/known_hosts` op de gatewayhost
- Leesbaarheid van het externe pad op de Mac die Berichten draait

Voer opnieuw uit in een interactieve GUI-terminal in dezelfde gebruiker/sessiecontext en keur prompts goed:

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

Bevestig dat Volledige schijftoegang + Automatisering zijn verleend voor de procescontext die OpenClaw/`imsg` draait.

Configuratiereferentie-verwijzingen

• Configuratiereferentie - iMessage
• Gateway-configuratie
• Koppeling
• BlueBubbles