iMessage (Legacy: imsg)

Warnung: Für neue iMessage-Deployments verwende BlueBubbles.

Die imsg-Integration ist veraltet und wird möglicherweise in einer zukünftigen Version entfernt.

Status: Legacy-externe-CLI-Integration. Das Gateway startet imsg rpc und kommuniziert über JSON-RPC auf stdio (kein separater Daemon/Port).

• BlueBubbles (empfohlen) — Bevorzugter iMessage-Weg für neue Setups.
• Pairing — iMessage-DMs verwenden standardmäßig Pairing-Modus.
• Konfigurationsreferenz — Vollständige iMessage-Feldreferenz.

Schnelleinrichtung

Lokaler Mac (Schnellweg)

  ### Schritt 1: imsg installieren und prüfen

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

  ### Schritt 2: OpenClaw konfigurieren

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

  ### Schritt 3: Gateway starten

openclaw gateway

  ### Schritt 4: Erstes DM-Pairing genehmigen (Standard-dmPolicy)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

    Pairing-Anfragen verfallen nach 1 Stunde.

Remote-Mac über SSH

OpenClaw erfordert nur einen stdio-kompatiblen `cliPath`, sodass du `cliPath` auf ein Wrapper-Skript zeigen kannst, das per SSH auf einen Remote-Mac zugreift und `imsg` ausführt.

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

Empfohlene Konfiguration bei aktivierten Anhängen:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // für SCP-Anhang-Downloads
      includeAttachments: true,
      // Optional: erlaubte Anhang-Roots überschreiben.
      // Standards beinhalten /Users/*/Library/Messages/Attachments
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

Wenn `remoteHost` nicht gesetzt ist, versucht OpenClaw es automatisch zu erkennen, indem das SSH-Wrapper-Skript geparst wird.
`remoteHost` muss `host` oder `user@host` sein (keine Leerzeichen oder SSH-Optionen).
OpenClaw verwendet strikte Host-Key-Prüfung für SCP, sodass der Relay-Host-Key bereits in `~/.ssh/known_hosts` existieren muss.
Anhangpfade werden gegen erlaubte Roots (`attachmentRoots` / `remoteAttachmentRoots`) validiert.

Voraussetzungen und Berechtigungen (macOS)

• Messages muss auf dem Mac angemeldet sein, auf dem imsg läuft.
• Vollständiger Festplattenzugriff ist für den Prozesskontext erforderlich, der OpenClaw/imsg ausführt (Messages-DB-Zugriff).
• Automation-Berechtigung ist erforderlich, um Nachrichten über Messages.app zu senden.

Tipp: Berechtigungen werden pro Prozesskontext erteilt. Wenn das Gateway headless läuft (LaunchAgent/SSH), führe einen einmaligen interaktiven Befehl im selben Kontext aus, um Eingabeaufforderungen auszulösen:

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

Zugriffssteuerung und Routing

DM-Richtlinie

`channels.imessage.dmPolicy` steuert Direktnachrichten:

- `pairing` (Standard)
- `allowlist`
- `open` (erfordert `allowFrom` mit `"*"`)
- `disabled`

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

Allowlist-Einträge können Handles oder Chat-Ziele sein (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`).

Gruppenrichtlinie + Mentions

`channels.imessage.groupPolicy` steuert die Gruppenbehandlung:

- `allowlist` (Standard wenn konfiguriert)
- `open`
- `disabled`

Gruppen-Absender-Allowlist: `channels.imessage.groupAllowFrom`.

Laufzeit-Fallback: Wenn `groupAllowFrom` nicht gesetzt ist, fallen iMessage-Gruppen-Absenderprüfungen auf `allowFrom` zurück, wenn verfügbar.
Laufzeithinweis: Wenn `channels.imessage` vollständig fehlt, fällt die Laufzeit auf `groupPolicy="allowlist"` zurück und protokolliert eine Warnung (auch wenn `channels.defaults.groupPolicy` gesetzt ist).

Mention-Gating für Gruppen:

- iMessage hat keine nativen Mention-Metadaten
- Mention-Erkennung verwendet Regex-Muster (`agents.list[].groupChat.mentionPatterns`, Fallback `messages.groupChat.mentionPatterns`)
- Ohne konfigurierte Muster kann Mention-Gating nicht durchgesetzt werden

Steuerbefehle von autorisierten Absendern können das Mention-Gating in Gruppen umgehen.

Sessions und deterministische Antworten

- DMs verwenden direktes Routing; Gruppen verwenden Gruppen-Routing.
- Mit Standard `session.dmScope=main` werden iMessage-DMs in die Haupt-Session des Agenten zusammengeführt.
- Gruppen-Sessions sind isoliert (`agent:<agentId>:imessage:group:<chat_id>`).
- Antworten werden über die ursprünglichen Kanal-/Ziel-Metadaten an iMessage zurückgeleitet.

Gruppen-ähnliches Thread-Verhalten:

Einige Mehr-Teilnehmer-iMessage-Threads können mit `is_group=false` ankommen.
Wenn diese `chat_id` explizit unter `channels.imessage.groups` konfiguriert ist, behandelt OpenClaw sie als Gruppenverkehr (Gruppen-Gating + Gruppen-Session-Isolation).

Deployment-Muster

Verwende eine dedizierte Apple ID und einen macOS-Benutzer, damit der Bot-Traffic von deinem persönlichen Messages-Profil isoliert ist.

Typischer Ablauf:

1. Erstelle/melde einen dedizierten macOS-Benutzer an.
2. Melde dich in Messages mit der Bot-Apple-ID in diesem Benutzer an.
3. Installiere `imsg` in diesem Benutzer.
4. Erstelle ein SSH-Wrapper, damit OpenClaw `imsg` in diesem Benutzerkontext ausführen kann.
5. Zeige `channels.imessage.accounts.<id>.cliPath` und `.dbPath` auf dieses Benutzerprofil.

Der erste Durchlauf erfordert möglicherweise GUI-Genehmigungen (Automation + Vollständiger Festplattenzugriff) in dieser Bot-Benutzersitzung.

Übliche Topologie:

- Gateway läuft auf Linux/VM
- iMessage + `imsg` läuft auf einem Mac in deinem Tailnet
- `cliPath`-Wrapper verwendet SSH zum Ausführen von `imsg`
- `remoteHost` ermöglicht SCP-Anhang-Downloads

Beispiel:

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

Verwende SSH-Keys, damit sowohl SSH als auch SCP nicht-interaktiv sind.
Stelle sicher, dass der Host-Key zuerst vertraut ist (zum Beispiel `ssh [email protected]`), damit `known_hosts` befüllt wird.

iMessage unterstützt Pro-Konto-Konfiguration unter `channels.imessage.accounts`.

Jedes Konto kann Felder wie `cliPath`, `dbPath`, `allowFrom`, `groupPolicy`, `mediaMaxMb`, Verlaufseinstellungen und Anhang-Root-Allowlists überschreiben.

Medien, Chunking und Zustellziele

- Eingehende Anhangaufnahme ist optional: `channels.imessage.includeAttachments`
- Remote-Anhangpfade können via SCP abgerufen werden, wenn `remoteHost` gesetzt ist
- Anhangpfade müssen erlaubten Roots entsprechen:
  - `channels.imessage.attachmentRoots` (lokal)
  - `channels.imessage.remoteAttachmentRoots` (Remote-SCP-Modus)
  - Standard-Root-Muster: `/Users/*/Library/Messages/Attachments`
- SCP verwendet strikte Host-Key-Prüfung (`StrictHostKeyChecking=yes`)
- Ausgehende Mediengröße verwendet `channels.imessage.mediaMaxMb` (Standard 16 MB)

- Text-Chunk-Limit: `channels.imessage.textChunkLimit` (Standard 4000)
- Chunk-Modus: `channels.imessage.chunkMode`
  - `length` (Standard)
  - `newline` (Absatz-zuerst-Aufteilung)

Bevorzugte explizite Ziele:

- `chat_id:123` (empfohlen für stabiles Routing)
- `chat_guid:...`
- `chat_identifier:...`

Handle-Ziele werden ebenfalls unterstützt:

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

imsg chats --limit 20

Konfigurationsschreibvorgänge

iMessage erlaubt standardmäßig kanal-initiierte Konfigurationsschreibvorgänge (für /config set|unset wenn commands.config: true).

Deaktivieren:

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

Fehlerbehebung

Binary und RPC-Unterstützung prüfen:

imsg rpc --help
openclaw channels status --probe

Wenn die Probe RPC als nicht unterstützt meldet, aktualisiere `imsg`.

Prüfe:

- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- Pairing-Genehmigungen (`openclaw pairing list imessage`)

Prüfe:

- `channels.imessage.groupPolicy`
- `channels.imessage.groupAllowFrom`
- `channels.imessage.groups` Allowlist-Verhalten
- Mention-Muster-Konfiguration (`agents.list[].groupChat.mentionPatterns`)

Prüfe:

- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- SSH/SCP-Key-Auth vom Gateway-Host
- Host-Key existiert in `~/.ssh/known_hosts` auf dem Gateway-Host
- Lesbarkeit des Remote-Pfads auf dem Mac mit Messages

Führe den Befehl erneut in einem interaktiven GUI-Terminal im selben Benutzer-/Sitzungskontext aus und genehmige die Aufforderungen:

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

Bestätige, dass Vollständiger Festplattenzugriff + Automation für den Prozesskontext erteilt sind, der OpenClaw/`imsg` ausführt.

Konfigurationsreferenz-Verweise

• Configuration reference - iMessage
• Gateway configuration
• Pairing
• BlueBubbles