Mainstream messaging

iMessage

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

BlueBubbles (Legacy-Fallback)

Verwenden Sie es weiter für bestehendes BlueBubbles-gestütztes Routing; vermeiden Sie es für neue Setups, wenn imsg passt.

Kopplung

iMessage-DMs verwenden standardmäßig den Kopplungsmodus.

Konfigurationsreferenz

Vollständige iMessage-Feldreferenz.

Schnelle Einrichtung

Lokaler Mac (schneller Weg)

imsg installieren und überprüfen

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

OpenClaw konfigurieren

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

Gateway starten

openclaw gateway

Erste DM-Kopplung genehmigen (standardmäßige dmPolicy)

openclaw pairing list imessage
openclaw pairing approve imessage &lt;CODE&gt;

Kopplungsanfragen laufen nach 1 Stunde ab.

Entfernter Mac über SSH

OpenClaw benötigt nur einen stdio-kompatiblen cliPath, Sie können cliPath also auf ein Wrapper-Skript verweisen lassen, das per SSH eine Verbindung zu einem entfernten Mac herstellt und imsg ausführt.

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

Empfohlene Konfiguration, wenn Anhänge aktiviert sind:

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

Wenn remoteHost nicht festgelegt ist, versucht OpenClaw, ihn durch Parsen des SSH-Wrapper-Skripts automatisch zu erkennen. remoteHost muss host oder user@host sein (keine Leerzeichen oder SSH-Optionen). OpenClaw verwendet für SCP eine strikte Host-Key-Prüfung, daher muss der Relay-Host-Key bereits in ~/.ssh/known_hosts vorhanden sein. Anhangspfade werden gegen erlaubte Roots (attachmentRoots / remoteAttachmentRoots) validiert.

Anforderungen und Berechtigungen (macOS)

Messages muss auf dem Mac angemeldet sein, auf dem imsg ausgeführt wird.
Full Disk Access ist für den Prozesskontext erforderlich, in dem OpenClaw/imsg ausgeführt wird (Zugriff auf die Messages-Datenbank).
Automation-Berechtigung ist erforderlich, um Nachrichten über Messages.app zu senden.

Tip

Berechtigungen werden pro Prozesskontext erteilt. Wenn Gateway headless ausgeführt wird (LaunchAgent/SSH), führen Sie in demselben Kontext einmalig einen interaktiven Befehl aus, um Eingabeaufforderungen auszulösen:

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

Zugriffskontrolle und Routing

DM-Richtlinie

channels.imessage.dmPolicy steuert Direktnachrichten:

pairing (Standard)
allowlist
open (erfordert, dass allowFrom "*" enthält)
disabled

Allowlist-Feld: channels.imessage.allowFrom.

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

Gruppenrichtlinie + Erwähnungen

channels.imessage.groupPolicy steuert die Gruppenbehandlung:

allowlist (Standard, wenn konfiguriert)
open
disabled

Allowlist für Gruppenabsender: channels.imessage.groupAllowFrom.

Laufzeit-Fallback: Wenn groupAllowFrom nicht festgelegt ist, fallen iMessage-Prüfungen für Gruppenabsender auf allowFrom zurück, sofern 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 festgelegt ist).

Erwähnungs-Gating für Gruppen:

iMessage hat keine nativen Metadaten für Erwähnungen
die Erkennung von Erwähnungen verwendet Regex-Muster (agents.list[].groupChat.mentionPatterns, Fallback messages.groupChat.mentionPatterns)
ohne konfigurierte Muster kann Erwähnungs-Gating nicht durchgesetzt werden

Steuerbefehle von autorisierten Absendern können Erwähnungs-Gating in Gruppen umgehen.

Sitzungen und deterministische Antworten

DMs verwenden direktes Routing; Gruppen verwenden Gruppen-Routing.
Mit dem standardmäßigen session.dmScope=main werden iMessage-DMs in der Hauptsitzung des Agents zusammengeführt.
Gruppensitzungen sind isoliert (agent:<agentId>:imessage:group:<chat_id>).
Antworten werden mithilfe der Metadaten des ursprünglichen Channels/Ziels zurück zu iMessage geroutet.

Gruppenähnliches Thread-Verhalten:

Einige iMessage-Threads mit mehreren Teilnehmenden 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 + Gruppensitzungsisolation).

ACP-Unterhaltungsbindungen

Legacy-iMessage-Chats können auch an ACP-Sitzungen gebunden werden.

Schneller Operator-Ablauf:

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

Konfigurierte persistente Bindungen werden über Top-Level-bindings[]-Einträge mit type: "acp" und match.channel: "imessage" unterstützt.

match.peer.id kann Folgendes verwenden:

normalisierten DM-Handle wie +15555550123 oder [email protected]
chat_id:<id> (empfohlen für stabile Gruppenbindungen)
chat_guid:<guid>
chat_identifier:<identifier>

Beispiel:

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

Siehe ACP-Agents für gemeinsames ACP-Bindungsverhalten.

Bereitstellungsmuster

Dedizierter macOS-Bot-Benutzer (separate iMessage-Identität)

Verwenden Sie eine dedizierte Apple-ID und einen dedizierten macOS-Benutzer, damit Bot-Traffic von Ihrem persönlichen Messages-Profil isoliert ist.

Typischer Ablauf:

Erstellen Sie einen dedizierten macOS-Benutzer oder melden Sie ihn an.
Melden Sie sich in diesem Benutzer mit der Bot-Apple-ID bei Messages an.
Installieren Sie imsg in diesem Benutzer.
Erstellen Sie einen SSH-Wrapper, damit OpenClaw imsg im Kontext dieses Benutzers ausführen kann.
Verweisen Sie channels.imessage.accounts.<id>.cliPath und .dbPath auf dieses Benutzerprofil.

Der erste Lauf kann GUI-Genehmigungen (Automation + Full Disk Access) in dieser Bot-Benutzersitzung erfordern.

Entfernter Mac über Tailscale (Beispiel)

Häufige Topologie:

Gateway läuft auf Linux/VM
iMessage + imsg läuft auf einem Mac in Ihrem Tailnet
der cliPath-Wrapper verwendet SSH, um imsg auszuführen
remoteHost aktiviert das Abrufen von Anhängen per SCP

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

Verwenden Sie SSH-Schlüssel, damit sowohl SSH als auch SCP nicht interaktiv sind. Stellen Sie zuerst sicher, dass der Host-Key vertrauenswürdig ist (zum Beispiel ssh [email protected]), damit known_hosts befüllt wird.

Multi-Account-Muster

iMessage unterstützt accountbezogene Konfiguration unter channels.imessage.accounts.

Jeder Account kann Felder wie cliPath, dbPath, allowFrom, groupPolicy, mediaMaxMb, Verlaufseinstellungen und Allowlists für Anhangs-Roots überschreiben.

Medien, Chunking und Zustellungsziele

Anhänge und Medien

eingehende Anhangserfassung ist optional: channels.imessage.includeAttachments
entfernte Anhangspfade können per SCP abgerufen werden, wenn remoteHost festgelegt ist
Anhangspfade müssen erlaubten Roots entsprechen:
- channels.imessage.attachmentRoots (lokal)
- channels.imessage.remoteAttachmentRoots (entfernter SCP-Modus)
- Standard-Root-Muster: /Users/*/Library/Messages/Attachments
SCP verwendet strikte Host-Key-Prüfung (StrictHostKeyChecking=yes)
die Größe ausgehender Medien verwendet channels.imessage.mediaMaxMb (Standard 16 MB)

Ausgehendes Chunking

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

Adressierungsformate

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 vom Channel initiierte Konfigurationsschreibvorgänge (für /config set|unset, wenn commands.config: true).

Deaktivieren:

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

Fehlerbehebung

imsg nicht gefunden oder RPC nicht unterstützt

Validieren Sie das Binary und die RPC-Unterstützung:

imsg rpc --help
openclaw channels status --probe

Wenn die Prüfung meldet, dass RPC nicht unterstützt wird, aktualisieren Sie imsg.

DMs werden ignoriert

Prüfen Sie:

channels.imessage.dmPolicy
channels.imessage.allowFrom
Kopplungsgenehmigungen (openclaw pairing list imessage)

Gruppennachrichten werden ignoriert

Prüfen Sie:

channels.imessage.groupPolicy
channels.imessage.groupAllowFrom
Allowlist-Verhalten von channels.imessage.groups
Konfiguration von Erwähnungsmustern (agents.list[].groupChat.mentionPatterns)

Entfernte Anhänge schlagen fehl

Prüfen Sie:

channels.imessage.remoteHost
channels.imessage.remoteAttachmentRoots
SSH/SCP-Schlüsselauthentifizierung vom Gateway-Host
Host-Key ist in ~/.ssh/known_hosts auf dem Gateway-Host vorhanden
Lesbarkeit des entfernten Pfads auf dem Mac, auf dem Messages läuft

macOS-Berechtigungsaufforderungen wurden verpasst

Führen Sie die Befehle erneut in einem interaktiven GUI-Terminal im selben Benutzer-/Sitzungskontext aus und genehmigen Sie die Aufforderungen:

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

Bestätigen Sie, dass Full Disk Access + Automation für den Prozesskontext gewährt sind, in dem OpenClaw/imsg ausgeführt wird.

iMessage

Schnelle Einrichtung

Lokaler Mac (schneller Weg)

imsg installieren und überprüfen

OpenClaw konfigurieren

Gateway starten

Erste DM-Kopplung genehmigen (standardmäßige dmPolicy)

Entfernter Mac über SSH

Anforderungen und Berechtigungen (macOS)

Zugriffskontrolle und Routing

DM-Richtlinie

Gruppenrichtlinie + Erwähnungen

Sitzungen und deterministische Antworten

ACP-Unterhaltungsbindungen

Bereitstellungsmuster

Medien, Chunking und Zustellungsziele

Konfigurationsschreibvorgänge

Fehlerbehebung

Verweise auf die Konfigurationsreferenz

Verwandte

Ask OpenClaw

# Schnelle Einrichtung

Lokaler Mac (schneller Weg)

imsg installieren und überprüfen

OpenClaw konfigurieren

Gateway starten

Erste DM-Kopplung genehmigen (standardmäßige dmPolicy)

Entfernter Mac über SSH

# Anforderungen und Berechtigungen (macOS)

# Zugriffskontrolle und Routing

DM-Richtlinie

Gruppenrichtlinie + Erwähnungen

Sitzungen und deterministische Antworten

# ACP-Unterhaltungsbindungen

# Bereitstellungsmuster

# Medien, Chunking und Zustellungsziele

# Konfigurationsschreibvorgänge

# Fehlerbehebung

# Verweise auf die Konfigurationsreferenz

# Verwandte

Schnelle Einrichtung

Anforderungen und Berechtigungen (macOS)

Zugriffskontrolle und Routing

ACP-Unterhaltungsbindungen

Bereitstellungsmuster

Medien, Chunking und Zustellungsziele

Konfigurationsschreibvorgänge

Fehlerbehebung

Verweise auf die Konfigurationsreferenz

Verwandte