iMessage

​

Schnelle Einrichtung

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

​

Anforderungen 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 (Zugriff auf die Messages-Datenbank).
• Die Automatisierungsberechtigung ist erforderlich, um Nachrichten über Messages.app zu senden.
• Für erweiterte Aktionen (Reagieren / Bearbeiten / Zurückrufen / Thread-Antwort / Effekte / Umfragen / Gruppenoperationen) muss System Integrity Protection deaktiviert sein — siehe unten Die private imsg-API aktivieren. Einfaches Senden/Empfangen von Text und Medien funktioniert ohne diese Änderung.

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

​

Die private imsg-API aktivieren

• Basismodus (Standard, keine SIP-Änderungen erforderlich): ausgehender Text und Medien über send, eingehendes Watch/History, Chatliste. Das erhalten Sie direkt nach einem frischen brew install steipete/tap/imsg plus den oben genannten Standardberechtigungen von macOS.
• Modus mit privater API: imsg injiziert eine Hilfs-dylib in Messages.app, um interne IMCore-Funktionen aufzurufen. Dadurch werden react, edit, unsend, reply (Thread-Antwort), sendWithEffect, poll und poll-vote (native Messages-Umfragen), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup sowie Tippindikatoren und Lesebestätigungen freigeschaltet.

Erweiterte Funktionen wie read, typing, launch, Bridge-gestütztes Rich Send, Nachrichtenmutation und Chatverwaltung sind optional. Sie erfordern, dass SIP deaktiviert ist und eine Hilfs-dylib in Messages.app injiziert wird. imsg launch verweigert die Injektion, wenn SIP aktiviert ist.

​

Einrichtung

1. Installieren (oder aktualisieren) Sie imsg auf dem Mac, auf dem Messages.app läuft:
   brew install steipete/tap/imsg
   imsg --version
   imsg status --json
   
   Die Ausgabe von imsg status --json meldet bridge_version, rpc_methods und pro Methode selectors, sodass Sie sehen können, was der aktuelle Build unterstützt, bevor Sie beginnen.
2. Deaktivieren Sie System Integrity Protection und (auf modernem macOS) Library Validation. Das Injizieren einer nicht von Apple stammenden Hilfs-dylib in die von Apple signierte Messages.app erfordert deaktiviertes SIP und gelockerte Library Validation. Der SIP-Schritt im Wiederherstellungsmodus ist macOS-versionsspezifisch:
   • macOS 10.13-10.15 (Sierra-Catalina): Deaktivieren Sie Library Validation über Terminal, starten Sie in den Wiederherstellungsmodus, führen Sie csrutil disable aus, starten Sie neu.
   • macOS 11+ (Big Sur und neuer), Intel: Wiederherstellungsmodus (oder Internet Recovery), csrutil disable, Neustart.
   • macOS 11+, Apple Silicon: Startsequenz über die Einschalttaste, um Recovery aufzurufen; halten Sie auf neueren macOS-Versionen die linke Umschalttaste gedrückt, wenn Sie auf Fortfahren klicken, dann csrutil disable. Setups mit virtuellen Maschinen folgen einem separaten Ablauf, erstellen Sie daher zuerst einen VM-Snapshot.
   Unter macOS 11 und neuer reicht csrutil disable allein normalerweise nicht aus. Apple erzwingt Library Validation weiterhin gegen Messages.app als Platform Binary, sodass eine ad-hoc-signierte Hilfsbibliothek abgelehnt wird (Library Validation failed: ... platform binary, but mapped file is not), selbst wenn SIP deaktiviert ist. Deaktivieren Sie nach dem Deaktivieren von SIP auch Library Validation und starten Sie neu:
   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true
   
   macOS 26 (Tahoe), verifiziert auf 26.5.1: Deaktiviertes SIP plus der oben genannte DisableLibraryValidation-Befehl reicht aus, um die Hilfsbibliothek über 26.0 bis 26.5.x hinweg zu injizieren. Es sind keine boot-args erforderlich. Die plist ist der entscheidende Faktor und der häufigste fehlende Schritt, wenn die Injektion auf Tahoe fehlschlägt:
   • Mit der plist: imsg launch injiziert, und imsg status meldet advanced_features: true.
   • Ohne die plist (auch bei deaktiviertem SIP): imsg launch schlägt mit Failed to launch: Timeout waiting for Messages.app to initialize fehl. AMFI lehnt den ad-hoc-Helper beim Laden ab, daher wird die Bridge nie bereit und der Start läuft in einen Timeout. Dieser Timeout ist das Symptom, auf das die meisten unter Tahoe stoßen, und die Lösung ist die obige plist, nicht etwas Drastischeres.
   Dies wurde mit einem kontrollierten Vorher/Nachher unter macOS 26.5.1 (Apple Silicon) bestätigt: Mit der plist wird die dylib in Messages.app gemappt und die Bridge startet; entfernen Sie die plist und starten Sie neu, dann erzeugt imsg launch den oben genannten Timeout-Fehler, wobei die dylib nicht gemappt ist. Wenn die imsg launch-Injektion oder bestimmte selectors nach einem macOS-Upgrade false zurückgeben, ist diese Prüfung meist die Ursache. Prüfen Sie Ihren SIP- und Library-Validation-Status, bevor Sie annehmen, dass der SIP-Schritt selbst fehlgeschlagen ist. Wenn diese Einstellungen korrekt sind und die Bridge weiterhin nicht injizieren kann, erfassen Sie imsg status --json sowie die Ausgabe von imsg launch und melden Sie dies dem imsg-Projekt, statt zusätzliche systemweite Sicherheitskontrollen abzuschwächen. Folgen Sie Apples Recovery-Mode-Ablauf für Ihren Mac, um SIP zu deaktivieren, bevor Sie imsg launch ausführen.
3. Injizieren Sie den Helper. Mit deaktiviertem SIP und angemeldeter Messages.app:
   imsg launch
   
   imsg launch verweigert die Injektion, wenn SIP noch aktiviert ist, sodass dies zugleich bestätigt, dass Schritt 2 wirksam war.
4. Überprüfen Sie die Bridge aus OpenClaw:
   openclaw channels status --probe
   
   Der iMessage-Eintrag sollte works melden, und imsg status --json | jq '{rpc_methods, selectors}' sollte die von Ihrem macOS-Build bereitgestellten Funktionen anzeigen. Die Erstellung von Umfragen erfordert selectors.pollPayloadMessage; Abstimmungen erfordern sowohl selectors.pollVoteMessage als auch die RPC-Methode poll.vote. Das OpenClaw Plugin bewirbt nur Aktionen, die vom zwischengespeicherten Probe unterstützt werden, während ein leerer Cache optimistisch bleibt und beim ersten Dispatch prüft.

​

Wenn Sie SIP nicht deaktivieren können

• imsg fällt auf den Basismodus zurück — nur Text + Medien + Empfang.
• Das OpenClaw Plugin bewirbt weiterhin Text-/Medienversand und eingehende Überwachung; es blendet lediglich react, edit, unsend, reply, sendWithEffect und Gruppenoperationen aus der Aktionsoberfläche aus (gemäß der funktionsbezogenen Capability-Prüfung).
• Sie können einen separaten Mac ohne Apple Silicon (oder einen dedizierten Bot-Mac) mit deaktiviertem SIP für die iMessage-Workload betreiben, während SIP auf Ihren primären Geräten aktiviert bleibt. Siehe Dedizierter macOS-Bot-Benutzer (separate iMessage-Identität) unten.

​

Zugriffskontrolle und 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-Konversationsbindungen

• Führen Sie /acp spawn codex --bind here innerhalb der DM oder des erlaubten Gruppenchats aus.
• Zukünftige Nachrichten in derselben iMessage-Konversation werden zur erzeugten ACP-Session geroutet.
• /new und /reset setzen dieselbe gebundene ACP-Session an Ort und Stelle zurück.
• /acp close schließt die ACP-Session und entfernt die Bindung.

• normalisierten DM-Handle wie +15555550123 oder user@example.com
• chat_id:<id> (empfohlen für stabile Gruppenbindungen)
• 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" },
    },
  ],
}

​

Bereitstellungsmuster

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

​

Medien, Chunking und Zustellziele

imsg chats --limit 20

​

Private-API-Aktionen

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

​

Konfigurationsschreibvorgänge

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

​

Zusammenführen von Split-Send-DMs (Befehl + URL in einer Komposition)

1. Eine Textnachricht ("Dump").
2. Eine URL-Vorschau-Sprechblase ("https://...") mit OG-Vorschaubildern als Anhänge.

{
  channels: {
    imessage: {
      coalesceSameSenderDms: true, // opt in (default: false)
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 7000 ms covers observed Messages.app URL-preview delays.
        imessage: 7000,
      },
    },
  },
}

​

Szenarien und was der Agent sieht

​

Eingehende Wiederherstellung nach einem Neustart von Bridge oder Gateway

• Replay-Deduplizierung. Jede zugestellte eingehende Nachricht wird anhand ihrer Apple-GUID im persistenten Plugin-Zustand (imessage.inbound-dedupe) erfasst, bei der Aufnahme beansprucht und nach der Verarbeitung committet (bei einem vorübergehenden Fehler freigegeben, damit sie erneut versucht werden kann). Alles, was bereits verarbeitet wurde, wird verworfen, statt zweimal zugestellt zu werden. Dadurch kann Recovery aggressiv wiederholen, ohne Buchhaltung pro Nachricht.
• Downtime-Recovery. Beim Start merkt sich der Monitor die zuletzt zugestellte chat.db-rowid (ein persistenter Cursor pro Konto) und übergibt sie als since_rowid an imsg watch.subscribe, sodass imsg die Zeilen wiederholt, die eingegangen sind, während das Gateway ausgefallen war, und danach live weiterläuft. Replay ist auf die neuesten Zeilen und auf Nachrichten bis zu ~2 Stunden Alter begrenzt, und die Deduplizierung verwirft alles, was bereits verarbeitet wurde.
• Altersgrenze für veralteten Backlog. Zeilen oberhalb der Startgrenze sind tatsächlich live; eine Zeile, deren Sendedatum mehr als ~15 Minuten älter ist als ihre Ankunft, ist der Push-Flush-Backlog und wird unterdrückt. Wiederholte Zeilen (an oder unterhalb der Grenze) verwenden stattdessen das breitere Recovery-Fenster, sodass eine kürzlich verpasste Nachricht zugestellt wird, während uralte Historie nicht zugestellt wird.

​

Für Operator sichtbares Signal

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

​

Migration

​

Fehlerbehebung

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"

​

Verweise zur Konfigurationsreferenz

• Konfigurationsreferenz - iMessage
• Gateway-Konfiguration
• Pairing

​

Verwandt

• Kanalübersicht — alle unterstützten Kanäle
• Entfernung von BlueBubbles und der imsg-iMessage-Pfad — Ankündigung und Migrationszusammenfassung
• Von BlueBubbles kommend — Konfigurationsübersetzungstabelle und schrittweise Umstellung
• Pairing — DM-Authentifizierung und Pairing-Ablauf
• Gruppen — Gruppenchat-Verhalten und Erwähnungs-Gating
• Kanal-Routing — Sitzungs-Routing für Nachrichten
• Sicherheit — Zugriffsmodell und Härtung