Skip to Content
👋 Willkommen bei HowToUseOpenClaw Schnellstart
KanäleiMessage

iMessage (imsg)

Status: externe CLI-Integration. Gateway erzeugt “imsg rpc” (JSON-RPC über stdio).

Schnelle Einrichtung (Anfänger)

  1. Stellen Sie sicher, dass Messages 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 das Gateway und bestätigen Sie alle Aufforderungen von macOS (Automation + Full Disk Access).

Minimale Konfiguration:

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

Was es ist

  • iMessage-Kanal, der von imsg unter macOS unterstützt wird.
  • Deterministische Weiterleitung: Antworten gehen immer zurück an iMessage.
  • DMs teilen sich die Hauptsitzung des Agenten; Gruppen sind isoliert (agent:<agentId>:imessage:group:<chat_id>).
  • Wenn ein Thread mit mehreren Teilnehmern mit is_group=false ankommt, können Sie ihn immer noch nach chat_id isolieren, indem Sie channels.imessage.groups verwenden (siehe “Gruppenartige Threads” unten).

Konfig schreibt

Standardmäßig ist es iMessage erlaubt, Konfigurationsaktualisierungen zu schreiben, die durch /config set|unset ausgelöst werden (erfordert commands.config: true):

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

Anforderungen

  • macOS mit Messages angemeldet.
  • Voller Festplattenzugriff für OpenClaw + imsg (Messages DB Zugriff).
  • Automatisierungserlaubnis beim Senden.
  • channels.imessage.cliPathkann auf jeden Befehl verweisen, der stdin/stdout proxyt (z.B. ein Wrapper-Skript, das sich per SSH mit einem anderen Mac verbindet undimsg rpc` ausführt).

Setup (schneller Pfad)

  1. Stellen Sie sicher, dass Messages auf diesem Mac angemeldet ist.
  2. Konfigurieren Sie iMessage und starten Sie das Gateway.

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

Wenn Sie möchten, dass der Bot von einer separaten iMessage-Identität sendet (und Ihre persönlichen Nachrichten sauber hält), verwenden Sie eine dedizierte Apple ID + einen dedizierten macOS-Benutzer.

  1. Erstellen Sie eine dedizierte Apple ID (Beispiel: my-cool-bot@icloud.com).

    • Apple kann eine Telefonnummer zur Verifizierung / 2FA verlangen.

  2. Erstellen Sie einen macOS-Benutzer (Beispiel: clawdshome) und melden Sie sich bei diesem an.

  3. Öffnen Sie Messages in diesem macOS-Benutzer und melden Sie sich bei iMessage mit der Bot Apple ID an.

  4. Aktivieren Sie die Fernanmeldung (Systemeinstellungen → Allgemein → Freigabe → Fernanmeldung).

  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. Richten Sie channels.imessage.accounts.bot.cliPath auf einen SSH-Wrapper, der imsg als Bot-Benutzer ausführt.

Hinweis für den ersten Durchlauf: Senden/Empfangen kann GUI-Genehmigungen (Automation + Full Disk Access) im bot macOS user erfordern. Wenn imsg rpc stecken bleibt oder sich auflöst, loggen Sie sich in diesen Benutzer ein (Bildschirmfreigabe hilft), führen Sie einmalig imsg chats --limit 1 / imsg send ... aus, genehmigen Sie die Eingabeaufforderungen und versuchen Sie es dann erneut. Ersetzen Sie <bot-macos-user> mit Ihrem tatsächlichen macOS-Benutzernamen:

#!/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" "$@"

Beispielkonfiguration:

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

Für Einzelkonten-Setups verwenden Sie flache Optionen (channels.imessage.cliPath, channels.imessage.dbPath) anstelle der accounts-Map.

Remote/SSH-Variante (optional)

Wenn Sie iMessage auf einem anderen Mac nutzen wollen, setzen Sie channels.imessage.cliPath auf einen Wrapper, der imsg auf dem entfernten macOS-Host über SSH ausführt. OpenClaw braucht nur einen stdio.Example Wrapper:

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

Ferne Anhänge: Wenn cliPath über SSH auf einen entfernten Host zeigt, verweisen die Pfade der Anhänge in der Nachrichtendatenbank auf Dateien auf dem entfernten Rechner. OpenClaw kann diese automatisch über SCP abrufen, indem es channels.imessage.remoteHost setzt:

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

Wenn remoteHost nicht gesetzt ist, versucht OpenClaw, es automatisch zu erkennen, indem es den SSH-Befehl in Ihrem Wrapper-Skript analysiert. Eine explizite Konfiguration wird für die Zuverlässigkeit empfohlen.

Entfernter Mac über Tailscale (Beispiel)

Wenn der Gateway auf einem Linux-Host/VM läuft, iMessage aber auf einem Mac laufen muss, ist Tailscale die einfachste Brücke: der Gateway spricht mit dem Mac über das Tailnet, führt imsg über SSH aus und SCPs Anhänge zurück.Architektur:

┌──────────────────────────────┐          SSH (imsg rpc)          ┌──────────────────────────┐
│ Gateway host (Linux/VM)      │──────────────────────────────────▶│ Mac with Messages + imsg │
│ - openclaw gateway           │          SCP (attachments)        │ - Messages signed in     │
│ - channels.imessage.cliPath  │◀──────────────────────────────────│ - Remote Login enabled   │
└──────────────────────────────┘                                   └──────────────────────────┘
              ▲
              │ Tailscale tailnet (hostname or 100.x.y.z)
              ▼
        user@gateway-host

Konkretes Konfigurationsbeispiel (Tailscale-Hostname):

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.clawdbot/scripts/imsg-ssh",
      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db"
    }
  }
}

Beispiel-Wrapper (~/.clawdbot/scripts/imsg-ssh):

#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

Anmerkungen:

  • Stellen Sie sicher, dass der Mac bei Messages angemeldet ist und die Fernanmeldung aktiviert ist.
  • Verwenden Sie SSH-Schlüssel, damit ssh bot@mac-mini.tailnet-1234.ts.net ohne Eingabeaufforderung funktioniert.
  • remoteHost sollte mit dem SSH-Ziel übereinstimmen, damit SCP Anhänge abrufen kann.

Unterstützung für mehrere Konten: Verwenden Sie channels.imessage.accounts mit der Konfiguration pro Konto und optionalem Name. Siehe gateway/configuration für das gemeinsame Muster. Übertragen Sie nicht ~/.clawdbot/openclaw.json (es enthält oft Token).

Zugriffskontrolle (DMs + Gruppen)

DMs:

  • Standard: channels.imessage.dmPolicy = "pairing".
  • Unbekannte Absender erhalten einen Pairing-Code; Nachrichten werden bis zur Genehmigung ignoriert (Codes verfallen nach 1 Stunde).
  • Freigeben über:
    • openclaw pairing list imessage
    • openclaw pairing approve imessage <CODE>
  • Pairing ist der Standard-Token-Austausch für iMessage-DMs. Details: Pairing

Gruppen:

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

Wie es funktioniert (Verhalten)

  • imsg streamt Nachrichtenereignisse; das Gateway normalisiert sie in den gemeinsamen Kanalumschlag.
  • Antworten werden immer an dieselbe Chat-ID oder dasselbe Handle zurück geleitet.

Gruppen-ähnliche Threads (is_group=false)

Einige iMessage-Threads können mehrere Teilnehmer haben, aber trotzdem mit is_group=false ankommen, je nachdem, wie Messages die Chat-Kennung speichert. Wenn Sie explizit eine chat_id unter channels.imessage.groups konfigurieren, behandelt OpenClaw diesen Thread als eine “Gruppe” für:

  • Sitzungsisolierung (separater Sitzungsschlüssel agent:<agentId>:imessage:group:<chat_id>)
  • Gruppenzulassung / Erwähnung von Gating-Verhalten

Beispiel:

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

Dies ist nützlich, wenn Sie eine isolierte Persönlichkeit/ein isoliertes Modell für einen bestimmten Thread wünschen (siehe Multi-Agent-Routing). Für die Isolierung des Dateisystems siehe Sandboxing.

Medien + Grenzen

  • Optionale Aufnahme von Anhängen über channels.imessage.includeAttachments.
  • Medienobergrenze über channels.imessage.mediaMaxMb.

Beschränkungen

  • Ausgehender Text wird auf channels.imessage.textChunkLimit (Standardwert 4000) gechunked.
  • Optionales Chunking mit Zeilenumbrüchen: Setzen Sie channels.imessage.chunkMode="newline", um Leerzeilen (Absatzgrenzen) vor dem Chunking aufzuteilen.
  • Medien-Uploads werden durch channels.imessage.mediaMaxMb begrenzt (Standardwert 16).

Adressierung/Zustellungsziele

Bevorzuge chat_id für stabiles Routing:

  • chat_id:123 (bevorzugt)
  • chat_guid:...
  • Chat_Identifier:...
  • direkte Handles: imessage:+1555 / sms:+1555 / user@example.com

Chats auflisten:

imsg chats --limit 20

Referenz zur Konfiguration (iMessage)

Vollständige Konfiguration: Konfiguration. Provider-Optionen:

  • channels.imessage.enabled: Aktivierung/Deaktivierung des Kanalstarts.
  • channels.imessage.cliPath: Pfad zu imsg.
  • channels.imessage.dbPath: Nachrichten DB Pfad.
  • channels.imessage.remoteHost: SSH-Host für die Übertragung von SCP-Anhängen, wenn cliPath auf einen entfernten Mac zeigt (z.B. user@gateway-host). Wird automatisch vom SSH-Wrapper erkannt, wenn er nicht gesetzt ist.
  • channels.imessage.service: imessage | sms | auto.
  • channels.imessage.region: SMS-Region.
  • channels.imessage.dmPolicy: Paarung | allowlist | open | disabled (Standard: Paarung).
  • 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: Gruppe Absender Erlaubnisliste.
  • channels.imessage.historyLimit / channels.imessage.accounts.*.historyLimit: maximale Anzahl von Gruppennachrichten, die als Kontext einbezogen werden sollen (0 deaktiviert).
  • channels.imessage.dmHistoryLimit: DM-History-Limit in Benutzer-Turns. Überschreibungen pro Benutzer: channels.imessage.dms["<handle>"].historyLimit.
  • channels.imessage.groups: Voreinstellungen pro Gruppe + allowlist (verwenden Sie "*" für globale Voreinstellungen).
  • channels.imessage.includeAttachments: Anhänge in den Kontext aufnehmen.
  • channels.imessage.mediaMaxMb: Obergrenze für eingehende/ausgehende Medien (MB).
  • channels.imessage.textChunkLimit: Größe der ausgehenden Chunks (Zeichen).
  • channels.imessage.chunkMode: length (Voreinstellung) oder newline, um an Leerzeilen (Absatzgrenzen) vor dem Längen-Chunking zu trennen.

Verwandte globale Optionen:

  • agents.list[].groupChat.mentionPatterns (oder messages.groupChat.mentionPatterns).
  • messages.responsePrefix.
Zuletzt aktualisiert am:
GrammyÜberblick