iMessage

Documentation Index

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

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

​

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.
• Full Disk Access ist für den Prozesskontext erforderlich, der OpenClaw/imsg ausführt (Zugriff auf die Messages-Datenbank).
• Eine Automatisierungsberechtigung ist erforderlich, um Nachrichten über Messages.app zu senden.
• Für erweiterte Aktionen (reagieren / bearbeiten / Senden zurücknehmen / Thread-Antwort / Effekte / Gruppenoperationen) muss System Integrity Protection deaktiviert sein — siehe Aktivieren der imsg Private API unten. Einfaches Senden/Empfangen von Text und Medien funktioniert ohne dies.

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

​

Aktivieren der imsg Private API

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

Erweiterte Funktionen wie read, typing, launch, bridge-gestütztes Rich Send, Nachrichtenänderung 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, damit Sie vor dem Start sehen können, was der aktuelle Build unterstützt.
2. Deaktivieren Sie System Integrity Protection. Dies ist macOS-versionsspezifisch, da die zugrunde liegende Apple-Anforderung vom Betriebssystem und der Hardware abhängt:
   • macOS 10.13–10.15 (Sierra–Catalina): Deaktivieren Sie Library Validation über Terminal, starten Sie in den Recovery Mode neu, führen Sie csrutil disable aus und starten Sie neu.
   • macOS 11+ (Big Sur und neuer), Intel: Recovery Mode (oder Internet Recovery), csrutil disable, neu starten.
   • macOS 11+, Apple Silicon: Startsequenz über den Einschaltknopf, um Recovery zu öffnen; halten Sie bei neueren macOS-Versionen die Taste Linke Umschalttaste gedrückt, wenn Sie auf Fortfahren klicken, und führen Sie dann csrutil disable aus. Setups mit virtuellen Maschinen folgen einem separaten Ablauf — erstellen Sie zuerst einen VM-Snapshot.
   • macOS 26 / Tahoe: Library-Validation-Richtlinien und Private-Entitlement-Prüfungen von imagent wurden weiter verschärft; imsg benötigt möglicherweise einen aktualisierten Build, um Schritt zu halten. Wenn imsg launch-Injektion oder bestimmte selectors nach einem großen macOS-Upgrade false zurückgeben, prüfen Sie die Release Notes von imsg, bevor Sie davon ausgehen, dass der SIP-Schritt erfolgreich war.
   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; dies dient daher zugleich als Bestätigung, dass Schritt 2 wirksam war.
4. Prüfen Sie die Bridge über OpenClaw:
   openclaw channels status --probe
   
   Der iMessage-Eintrag sollte works melden, und imsg status --json | jq '.selectors' sollte retractMessagePart: true sowie alle Edit-/Typing-/Read-Selektoren anzeigen, die Ihr macOS-Build bereitstellt. Das Pro-Methode-Gating des OpenClaw-Plugins in actions.ts bewirbt nur Aktionen, deren zugrunde liegender Selektor true ist; die Aktionsoberfläche, die Sie in der Tool-Liste des Agent sehen, spiegelt daher wider, was die Bridge auf diesem Host tatsächlich ausführen kann.

​

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äß dem Pro-Methode-Capability-Gate).
• Sie können einen separaten Nicht-Apple-Silicon-Mac (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 in der Direktnachricht oder im erlaubten Gruppenchat aus.
• Zukünftige Nachrichten in derselben iMessage-Konversation werden an die erzeugte 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.

• normalisiertes Direktnachrichten-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,
      },
    },
  },
}

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

​

Konfigurationsschreibvorgänge

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

​

Zusammenführen aufgeteilter Direktnachrichten-Sendungen (Befehl + URL in einer Eingabe)

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

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

​

Szenarien und was der Agent sieht

​

Nachholen nach Gateway-Ausfallzeit

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

​

Ablauf

​

Cursor- und Retry-Semantik

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

• Der Cursor rückt bei jeder erfolgreichen Auslieferung vor und wird gehalten, wenn die Auslieferung einer Zeile wirft – der nächste Start versucht dieselbe Zeile ab dem gehaltenen Cursor erneut.
• Nach maxFailureRetries aufeinanderfolgenden Throws gegen dieselbe guid protokolliert Catchup ein warn und rückt den Cursor zwangsweise hinter die verklemmte Nachricht vor, damit folgende Starts Fortschritt machen können.
• Bereits aufgegebene GUIDs werden bei späteren Läufen beim Auftauchen übersprungen (kein Auslieferungsversuch) und in der Laufzusammenfassung unter skippedGivenUp gezählt.

​

Für Betreiber sichtbare Signale

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>

​

Wann Sie es deaktiviert lassen sollten

• Das Gateway läuft kontinuierlich mit Watchdog-Autoneustart und Lücken sind immer < ein paar Sekunden – der Standard „aus“ ist in Ordnung.
• Das DM-Volumen ist niedrig und verpasste Nachrichten würden das Agentenverhalten nicht ändern – das anfängliche Fenster firstRunLookbackMinutes kann beim ersten Aktivieren überraschenden alten Kontext ausliefern.

​

Fehlerbehebung

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"

​

Verweise auf die Konfigurationsreferenz

• Konfigurationsreferenz – iMessage
• Gateway-Konfiguration
• Pairing

​

Verwandte Themen

• Channels-Übersicht – alle unterstützten Channels
• BlueBubbles-Entfernung und der imsg-iMessage-Pfad – Ankündigung und Migrationszusammenfassung
• Von BlueBubbles kommend – Tabelle zur Konfigurationsübersetzung und schrittweise Umstellung
• Pairing – DM-Authentifizierung und Pairing-Ablauf
• Gruppen – Gruppenchat-Verhalten und Mention-Gating
• Channel-Routing – Sitzungsrouting für Nachrichten
• Sicherheit – Zugriffsmodell und Härtung