​

iMessage (Legacy: imsg)

Empfohlen: Verwenden Sie BlueBubbles für neue iMessage-Setups. Der Kanal imsg ist eine Legacy-Integration über eine externe CLI und kann in einer zukünftigen Version entfernt werden.

​

Schnellsetup (Einsteiger)

1. Stellen Sie sicher, dass „Nachrichten“ auf diesem Mac angemeldet ist.
2. Installieren Sie imsg:
   • brew install steipete/tap/imsg
3. Konfigurieren Sie OpenClaw mit channels.imessage.cliPath und channels.imessage.dbPath.
4. Starten Sie den Gateway und genehmigen Sie alle macOS-Abfragen (Automation + Vollzugriff auf die Festplatte).

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

​

Was es ist

• iMessage-Kanal auf Basis von imsg unter macOS.
• Deterministisches Routing: Antworten gehen immer zurück zu iMessage.
• Direktnachrichten teilen die Hauptsitzung des Agenten; Gruppen sind isoliert (agent:<agentId>:imessage:group:<chat_id>).
• Wenn ein Thread mit mehreren Teilnehmern mit is_group=false eingeht, können Sie ihn dennoch isolieren, indem Sie chat_id unter Verwendung von channels.imessage.groups konfigurieren (siehe „Gruppenähnliche Threads“ unten).

​

Konfigurationsschreibzugriffe

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

​

Anforderungen

• macOS mit angemeldeter Nachrichten-App.
• Vollzugriff auf die Festplatte für OpenClaw + imsg (Zugriff auf die Nachrichten-Datenbank).
• Automationsberechtigung beim Senden.
• channels.imessage.cliPath kann auf jeden Befehl zeigen, der stdin/stdout weiterleitet (z. B. ein Wrapper-Skript, das per SSH zu einem anderen Mac verbindet und imsg rpc ausführt).

​

Fehlerbehebung macOS Datenschutz und Sicherheit (TCC)

• Vollzugriff auf die Festplatte: Erlauben Sie Zugriff für den Prozess, der OpenClaw ausführt (und für jeden Shell-/SSH-Wrapper, der imsg ausführt). Dies ist erforderlich, um die Nachrichten-Datenbank zu lesen (chat.db).
• Automation → Nachrichten: Erlauben Sie dem Prozess, der OpenClaw ausführt (und/oder Ihrem Terminal), Messages.app für ausgehende Sendungen zu steuern.
• imsg CLI-Gesundheit: Verifizieren Sie, dass imsg installiert ist und RPC unterstützt (imsg rpc --help).

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

​

Setup (schneller Pfad)

1. Stellen Sie sicher, dass „Nachrichten“ auf diesem Mac angemeldet ist.
2. Konfigurieren Sie iMessage und starten Sie den Gateway.

​

Dedizierter Bot-macOS-Benutzer (für isolierte Identität)

1. Erstellen Sie eine dedizierte Apple-ID (Beispiel: [email protected]).
   • Apple kann für die Verifizierung / 2FA eine Telefonnummer verlangen.
2. Erstellen Sie einen macOS-Benutzer (Beispiel: openclawhome) und melden Sie sich an.
3. Öffnen Sie „Nachrichten“ in diesem macOS-Benutzer und melden Sie sich mit der Bot-Apple-ID bei iMessage an.
4. Aktivieren Sie „Remote Login“ (Systemeinstellungen → Allgemein → Freigabe → Remote Login).
5. Installieren Sie imsg:
   • brew install steipete/tap/imsg
6. Richten Sie SSH so ein, dass ssh <bot-macos-user>@localhost true ohne Passwort funktioniert.
7. Verweisen Sie channels.imessage.accounts.bot.cliPath auf einen SSH-Wrapper, der imsg als Bot-Benutzer ausführt.

#!/usr/bin/env bash
set -euo pipefail

# Run an interactive SSH once first to accept host keys:
#   ssh <bot-macos-user>@localhost true
exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@localhost \
  "/usr/local/bin/imsg" "$@"

{
  channels: {
    imessage: {
      enabled: true,
      accounts: {
        bot: {
          name: "Bot",
          enabled: true,
          cliPath: "/path/to/imsg-bot",
          dbPath: "/Users/<bot-macos-user>/Library/Messages/chat.db",
        },
      },
    },
  },
}

​

Remote/SSH-Variante (optional)

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

{
  channels: {
    imessage: {
      cliPath: "~/imsg-ssh", // SSH wrapper to remote Mac
      remoteHost: "user@gateway-host", // for SCP file transfer
      includeAttachments: true,
    },
  },
}

​

Remote-Mac über Tailscale (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 "$@"

• Stellen Sie sicher, dass der Mac bei „Nachrichten“ angemeldet ist und „Remote Login“ aktiviert ist.
• Verwenden Sie SSH-Schlüssel, damit ssh [email protected] ohne Abfragen funktioniert.
• remoteHost sollte dem SSH-Ziel entsprechen, damit SCP Anhänge abrufen kann.

​

Zugriffskontrolle (Direktnachrichten + Gruppen)

• Standard: channels.imessage.dmPolicy = "pairing".
• Unbekannte Absender erhalten einen Kopplungscode; Nachrichten werden ignoriert, bis sie genehmigt sind (Codes laufen nach 1 Stunde ab).
• Genehmigung über:
  • openclaw pairing list imessage
  • openclaw pairing approve imessage <CODE>
• Kopplung ist der Standard-Token-Austausch für iMessage-Direktnachrichten. Details: Kopplung

• channels.imessage.groupPolicy = open | allowlist | disabled.
• channels.imessage.groupAllowFrom steuert, wer in Gruppen auslösen darf, wenn allowlist gesetzt ist.
• Mention-Gating verwendet agents.list[].groupChat.mentionPatterns (oder messages.groupChat.mentionPatterns), da iMessage keine nativen Mention-Metadaten hat.
• Multi-Agent-Override: Setzen Sie pro Agent Muster auf agents.list[].groupChat.mentionPatterns.

​

Funktionsweise (Verhalten)

• imsg streamt Nachrichtenereignisse; der Gateway normalisiert sie in den gemeinsamen Kanal-Umschlag.
• Antworten werden immer an dieselbe Chat-ID oder denselben Handle zurückgeroutet.

​

Gruppenähnliche Threads (is_group=false)

• Sitzungsisolation (separater agent:<agentId>:imessage:group:<chat_id>-Sitzungsschlüssel)
• Gruppen-Allowlisting / Mention-Gating-Verhalten

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

​

Medien + Limits

• Optionale Anhangsaufnahme über channels.imessage.includeAttachments.
• Medienlimit über channels.imessage.mediaMaxMb.

​

Limits

• Ausgehender Text wird auf channels.imessage.textChunkLimit segmentiert (Standard 4000).
• Optionale Zeilenumbruch-Segmentierung: Setzen Sie channels.imessage.chunkMode="newline", um an Leerzeilen (Absatzgrenzen) vor der Längensegmentierung zu trennen.
• Medien-Uploads sind durch channels.imessage.mediaMaxMb begrenzt (Standard 16).

​

Adressierung / Zustellziele

• chat_id:123 (bevorzugt)
• chat_guid:...
• chat_identifier:...
• direkte Handles: imessage:+1555 / sms:+1555 / [email protected]

imsg chats --limit 20

​

Konfigurationsreferenz (iMessage)

• channels.imessage.enabled: Kanalstart aktivieren/deaktivieren.
• channels.imessage.cliPath: Pfad zu imsg.
• channels.imessage.dbPath: Pfad zur Nachrichten-Datenbank.
• channels.imessage.remoteHost: SSH-Host für SCP-Anhangsübertragung, wenn cliPath auf einen Remote-Mac zeigt (z. B. user@gateway-host). Automatisch aus dem SSH-Wrapper erkannt, falls nicht gesetzt.
• channels.imessage.service: imessage | sms | auto.
• channels.imessage.region: SMS-Region.
• channels.imessage.dmPolicy: pairing | allowlist | open | disabled (Standard: Kopplung).
• channels.imessage.allowFrom: DM-Allowlist (Handles, E-Mails, E.164-Nummern oder chat_id:*). open erfordert "*". iMessage hat keine Benutzernamen; verwenden Sie Handles oder Chat-Ziele.
• channels.imessage.groupPolicy: open | allowlist | disabled (Standard: Allowlist).
• channels.imessage.groupAllowFrom: Gruppen-Absender-Allowlist.
• channels.imessage.historyLimit / channels.imessage.accounts.*.historyLimit: Maximale Anzahl an Gruppennachrichten, die als Kontext einbezogen werden (0 deaktiviert).
• channels.imessage.dmHistoryLimit: DM-Historienlimit in Benutzerzügen. Pro-Benutzer-Overrides: channels.imessage.dms["<handle>"].historyLimit.
• channels.imessage.groups: Pro-Gruppen-Standards + Allowlist (verwenden Sie "*" für globale Standards).
• channels.imessage.includeAttachments: Anhänge in den Kontext aufnehmen.
• channels.imessage.mediaMaxMb: Eingehendes/ausgehendes Medienlimit (MB).
• channels.imessage.textChunkLimit: Größe der ausgehenden Segmente (Zeichen).
• channels.imessage.chunkMode: length (Standard) oder newline, um an Leerzeilen (Absatzgrenzen) vor der Längensegmentierung zu trennen.

• agents.list[].groupChat.mentionPatterns (oder messages.groupChat.mentionPatterns).
• messages.responsePrefix.