iMessage

​

Schnelleinrichtung

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", // used for SCP attachment fetches
      includeAttachments: true,
      // Optional: extra allowed attachment roots (merged with the default
      // /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 ausgeführt wird.
• Vollständiger Festplattenzugriff ist für den Prozesskontext erforderlich, in dem OpenClaw/imsg ausgeführt wird (Zugriff auf die Messages-Datenbank).
• Die Automatisierungsberechtigung ist erforderlich, um Nachrichten über Messages.app zu senden.
• Für erweiterte Aktionen (Reaktion / Bearbeiten / Senden rückgängig machen / Antwort im Thread / Effekte / Umfragen / Gruppenoperationen) muss der Systemintegritätsschutz deaktiviert sein — siehe Private API von imsg aktivieren. Das grundlegende Senden und Empfangen von Text und Medien funktioniert ohne diese Deaktivierung.

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

​

Private API von imsg aktivieren

• Basismodus (Standard, keine SIP-Änderungen erforderlich): ausgehender Text und ausgehende Medien über send, Überwachung/Verlauf eingehender Nachrichten, Chatliste. Dies ist der sofort verfügbare Funktionsumfang einer neuen brew install steipete/tap/imsg-Installation mit den oben genannten standardmäßigen macOS-Berechtigungen.
• Modus der privaten API: imsg injiziert eine Hilfsbibliothek vom Typ dylib in Messages.app, um interne IMCore-Funktionen aufzurufen. Dadurch werden react, edit, unsend, reply (in Threads), sendWithEffect, poll und poll-vote (native Messages-Umfragen), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup sowie Tippindikatoren und Lesebestätigungen ermöglicht.

Erweiterte Funktionen wie read, typing, launch, Bridge-gestütztes Senden umfangreicher Inhalte, Nachrichtenänderungen und Chatverwaltung sind optional. Sie erfordern, dass SIP deaktiviert und eine Hilfsbibliothek vom Typ 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 ausgeführt wird:
   brew install steipete/tap/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg status --json
   
   Die Ausgabe von imsg status --json meldet bridge_version, rpc_methods und methodenspezifische selectors, sodass Sie vor dem Start erkennen können, welche Funktionen der aktuelle Build unterstützt.
2. Deaktivieren Sie den Systemintegritätsschutz und (auf modernen macOS-Versionen) die Bibliotheksvalidierung. Das Einschleusen einer nicht von Apple stammenden Hilfs-dylib in die von Apple signierte Messages.app erfordert, dass SIP deaktiviert und die Bibliotheksvalidierung gelockert ist. Der SIP-Schritt im Wiederherstellungsmodus hängt von der macOS-Version ab:
   • macOS 10.13-10.15 (Sierra-Catalina): Deaktivieren Sie die Bibliotheksvalidierung über das Terminal, starten Sie im Wiederherstellungsmodus neu, führen Sie csrutil disable aus und starten Sie erneut.
   • macOS 11+ (Big Sur und neuer), Intel: Starten Sie im Wiederherstellungsmodus (oder über die Internetwiederherstellung), führen Sie csrutil disable aus und starten Sie neu.
   • macOS 11+, Apple Silicon: Verwenden Sie die Startsequenz mit dem Ein-/Ausschalter, um die Wiederherstellung aufzurufen; halten Sie bei aktuellen macOS-Versionen die Taste Left Shift gedrückt, wenn Sie auf Continue klicken, und führen Sie anschließend csrutil disable aus. Für virtuelle Maschinen gilt ein separater Ablauf; erstellen Sie daher zuerst einen VM-Snapshot.
   Unter macOS 11 und neuer reicht csrutil disable allein normalerweise nicht aus. Apple erzwingt weiterhin die Bibliotheksvalidierung für Messages.app als Plattformbinärdatei, sodass eine ad hoc signierte Hilfskomponente selbst bei deaktiviertem SIP abgewiesen wird (Library Validation failed: ... platform binary, but mapped file is not). Deaktivieren Sie nach SIP auch die Bibliotheksvalidierung und starten Sie neu:
   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true
   
   macOS 26 (Tahoe), verifiziert unter 26.5.1: Deaktiviertes SIP zusammen mit dem obigen Befehl DisableLibraryValidation genügt, um die Hilfskomponente unter den Versionen 26.0 bis 26.5.x einzuschleusen. Es sind keine Boot-Argumente erforderlich. Die plist ist der entscheidende Faktor und der am häufigsten fehlende Schritt, wenn das Einschleusen unter Tahoe fehlschlägt:
   • Mit der plist: imsg launch schleust die Hilfskomponente ein und imsg status meldet advanced_features: true.
   • Ohne die plist (selbst bei deaktiviertem SIP): imsg launch schlägt mit Failed to launch: Timeout waiting for Messages.app to initialize fehl. AMFI weist die ad hoc signierte Hilfskomponente beim Laden ab, sodass die Bridge nie bereit wird und der Start wegen einer Zeitüberschreitung abbricht. Diese Zeitüberschreitung ist das Symptom, auf das die meisten Personen unter Tahoe stoßen; die Lösung ist die obige plist und keine drastischere Maßnahme.
   Falls das Einschleusen über imsg launch oder bestimmte selectors nach einem macOS-Upgrade beginnen, false zurückzugeben, ist diese Sperre üblicherweise die Ursache. Prüfen Sie den Status von SIP und der Bibliotheksvalidierung, bevor Sie davon ausgehen, dass der SIP-Schritt selbst fehlgeschlagen ist. Wenn diese Einstellungen korrekt sind und die Bridge weiterhin nichts einschleusen kann, erfassen Sie imsg status --json sowie die Ausgabe von imsg launch und melden Sie dies dem Projekt imsg, statt weitere systemweite Sicherheitskontrollen zu schwächen.
3. Schleusen Sie die Hilfskomponente ein. Bei deaktiviertem SIP und angemeldeter Messages.app:
   imsg launch
   
   imsg launch verweigert das Einschleusen, solange SIP aktiviert ist. Dies dient daher zugleich als Bestätigung, dass Schritt 2 erfolgreich war.
4. Überprüfen Sie die Bridge über 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 Fähigkeiten anzeigen. Das Erstellen von Umfragen erfordert selectors.pollPayloadMessage; Abstimmungen erfordern sowohl selectors.pollVoteMessage als auch die RPC-Methode poll.vote. Das OpenClaw-Plugin bietet nur Aktionen an, die von der zwischengespeicherten Prüfung unterstützt werden, während ein leerer Cache optimistisch bleibt und beim ersten Versand eine Prüfung durchführt.

​

Wenn SIP aktiviert bleibt

• imsg wechselt in den Basismodus zurück — nur Text, Medien und Empfang.
• Das OpenClaw-Plugin bietet weiterhin das Senden von Text und Medien sowie die Überwachung eingehender Nachrichten an; react, edit, unsend, reply, sendWithEffect und Gruppenoperationen werden aus der Aktionsoberfläche ausgeblendet (entsprechend der Fähigkeitssperre pro Methode).
• Sie können für die iMessage-Arbeitslast einen separaten Mac ohne Apple Silicon (oder einen dedizierten Bot-Mac) mit deaktiviertem SIP verwenden, während SIP auf Ihren primären Geräten aktiviert bleibt. Siehe unten Dedizierter macOS-Bot-Benutzer (separate iMessage-Identität).

​

Zugriffskontrolle und Routing

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

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { systemPrompt: "Verwenden Sie britische Rechtschreibung." },
        "8421": {
          requireMention: true,
          systemPrompt: "Dies ist der Chat für die Rufbereitschaft. Begrenzen Sie Antworten auf höchstens 3 Sätze.",
        },
        "9907": {
          // explizite Unterdrückung: Der Platzhalter "Verwenden Sie britische Rechtschreibung." gilt hier nicht
          systemPrompt: "",
        },
      },
    },
  },
}

​

ACP-Konversationsbindungen

• Führen Sie /acp spawn codex --bind here innerhalb der Direktnachricht oder des zulässigen Gruppenchats aus.
• Künftige Nachrichten in derselben iMessage-Konversation werden an die erzeugte ACP-Sitzung weitergeleitet.
• /new und /reset setzen dieselbe gebundene ACP-Sitzung direkt zurück.
• /acp close schließt die ACP-Sitzung und entfernt die Bindung.

• normalisiertes Handle für Direktnachrichten wie +15555550123 oder user@example.com
• chat_id:<id> (für stabile Gruppenbindungen empfohlen)
• 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, Aufteilung und Zustellungsziele

imsg chats --limit 20

​

Aktionen der privaten 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,
    },
  },
}

​

Konfigurationsänderungen

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

​

Zusammenführen aufgeteilt gesendeter Direktnachrichten (Befehl + URL in einer Eingabe)

brew update && brew upgrade imsg

​

Wiederherstellung eingehender Nachrichten nach einem Neustart der Bridge oder des Gateways

• Dauerhafter Schutz vor Wiederholungen. Bevor OpenClaw den Wiederherstellungscursor fortschreibt, protokolliert es jede Rohzeile in der gemeinsamen SQLite-Eingangswarteschlange und verwendet deren Apple-GUID als Ereignis-ID. Eine abgeschlossene Zeile hinterlässt für etwa 4 Stunden einen Tombstone, wobei die Anzahl auf 10.000 Einträge begrenzt ist. Dadurch wird eine Wiederholung mit derselben GUID auch nach einem Neustart verworfen. Eine ausstehende Zeile bleibt wiederherstellbar, bis sie vom Versand übernommen wird.
• Wiederherstellung nach Ausfallzeiten. Beim Start merkt sich der Monitor die Zeilen-ID der letzten dauerhaft angenommenen chat.db-Zeile (einen persistenten Cursor pro Konto) und übergibt sie als since_rowid an imsg watch.subscribe. Dadurch gibt imsg Zeilen erneut wieder, die noch nicht protokolliert wurden, und folgt anschließend den Live-Ereignissen. Vor einem Absturz protokollierte Zeilen werden aus SQLite fortgesetzt. Die Wiederholung ist auf die neuesten 500 Zeilen und auf Nachrichten mit einem Alter von bis zu etwa 2 Stunden begrenzt; GUID-Tombstones verwerfen alle bereits verarbeiteten Einträge.
• Altersgrenze für veraltete Rückstände. Zeilen oberhalb der Startgrenze sind tatsächlich live; liegt das Sendedatum einer solchen Zeile mehr als etwa 15 Minuten vor ihrem Eingang, handelt es sich um den durch Push ausgegebenen Rückstand, der unterdrückt wird. Wiederholte Zeilen (an oder unterhalb der Grenze) verwenden stattdessen das größere Wiederherstellungsfenster. Dadurch wird eine kürzlich verpasste Nachricht zugestellt, während alte Verlaufsdaten nicht zugestellt werden.

​

Für Betreiber sichtbares Signal

imessage: veralteter eingehender Rückstand unterdrückt account=<id> sent=<iso> recovery=<bool> (<N> seit dem Start unterdrückt)

​

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
• Kopplung

​

Verwandte Themen

• Kanalübersicht — alle unterstützten Kanäle
• Entfernung von BlueBubbles und der imsg-iMessage-Pfad — Ankündigung und Zusammenfassung der Migration
• Umstieg von BlueBubbles — Tabelle zur Übertragung der Konfiguration und schrittweise Umstellung
• Kopplung — Authentifizierung von Direktnachrichten und Kopplungsablauf
• Gruppen — Verhalten von Gruppenchats und Erwähnungsbeschränkung
• Kanal-Routing — Sitzungs-Routing für Nachrichten
• Sicherheit — Zugriffsmodell und Härtung