imsg

Was macht imsg?

Verwende imsg, wenn ein OpenClaw-Agent über das lokale macOS Messages.app-Konto des Benutzers handeln muss: iMessage/SMS-Verlauf einsehen, den richtigen DM oder die richtige Gruppe auswählen, Nachrichten/Dateien senden, antworten, reagieren, an Umfragen teilnehmen oder private iMessage-API-Funktionen nutzen.

Verwende diese Fähigkeit nicht für Telegram, Signal, WhatsApp, Discord, Slack oder für Antworten innerhalb der aktuellen OpenClaw-Konversation, wenn der konfigurierte Kanal die Antwort bereits weiterleitet.

Agentenablauf

1. Ermittele zuerst die Unterhaltung.
2. Wähle DM, bestehende Gruppe oder neue Gruppe.
3. Wähle den Befehl mit der niedrigsten Kapazität, der die angeforderte Aktion ausführen kann.
4. Bestätige jede Sendung oder sichtbare Zustandsänderung, es sei denn, der Benutzer hat bereits genauen Empfänger, Inhalt und Aktion angegeben.
5. Führe mit stabilen Identifikatoren aus: bevorzuge --chat-id für normale Sendungen/Überwachung/Verlauf und --chat Chat-GUID für Bridge-Aktionen.

Leite einen Empfänger niemals allein aus einem beiläufigen Namen ab, wenn mehrere Chats oder Kontakte zutreffen könnten. Zeige den passenden Anzeigenamen, die Kontakt(e), die Gruppenteilnehmer und den Nachrichtentext/die Aktion an, bevor du sendest.

Host-Anforderungen

• macOS 14+ mit angemeldeter Messages.app für Sende/Reaktions/Bridge-Aktionen.
• Vollzugriff auf die Festplatte für den Prozesskontext, der imsg oder OpenClaw ausführt; Lesevorgänge schlagen ohne Messages-DB-Zugriff fehl.
• Automatisierungsberechtigung für Messages.app bei Verwendung von öffentlichem send.
• Barrierefreiheitsberechtigung für den Prozesskontext, der öffentliches imsg react ausführt; es verwendet System Events UI-Automatisierung. Bridge tapback verwendet stattdessen die private API.
• Optional Kontakteberechtigung für die Kontaktnamen-Auflösung.
• SMS-Sendungen erfordern die Textnachrichtenweiterleitung vom iPhone des Benutzers zu diesem Mac.
• Linux liest nur eine kopierte chat.db; es kann nicht senden, reagieren, Messages.app starten, als gelesen markieren oder tippen.

Ziele ermitteln

Verwende --json-Lesevorgänge. Die Ausgabe erfolgt als zeilenweise getrenntes JSON; verwende jq -s, wenn jq verfügbar ist, oder verarbeite ein Objekt pro Zeile direkt.

imsg chats --limit 25 --json | jq -s
imsg search --query "Abendessen" --match contains --json | jq -s
imsg history --chat-id 42 --limit 20 --attachments --json | jq -s
imsg group --chat-id 42 --json

Zielregeln:

• DM an eine Telefonnummer/E-Mail: verwende imsg send --to, wenn der Benutzer einen genauen Kontakt angegeben hat, oder nach einer eindeutigen Chat-Übereinstimmung.
• Bestehender DM-Thread: imsg send --chat-id <id> ist sicherer als die erneute Auflösung eines Namens.
• Bestehende Gruppe: überprüfe mit imsg group --chat-id <id> --json; sende mit --chat-id, Bridge mit der Chat-GUID von group.
• Neue Gruppe: verwende chat-create nur, wenn der Benutzer ausdrücklich die Erstellung einer Gruppe verlangt hat oder keine bestehende Gruppe übereinstimmt.
• Mehrdeutige Gruppennamen: bestätige Teilnehmer, nicht nur den Anzeigenamen.
• SMS: verwende --service sms nur, wenn angefragt oder wenn ein iMessage-Fallback nicht erwünscht ist. SMS-Relay erfordert Textnachrichtenweiterleitung.

Mache jq nicht zu einer harten Voraussetzung für diese Fähigkeit; es ist nur ein praktischer Formatierer für Beispiele.

Funktionsauswahl

Verwende öffentliche Messages-Automatisierung, wenn ausreichend:

• Lesen/Liste/Suche/Überwachung: chats, group, history, search, watch
• Einfaches Senden von Text/Dateien: send
• Standard-Tapback auf die letzte eingehende Nachricht in einem Chat: react

Verwende die private API-Brücke nur für Funktionen, die die öffentliche Automatisierung nicht ausführen kann:

• Umfangreiche Antworten, Textformatierung, Effekte, Betreffzeilen, Mehrteilsendungen
• Native Apple-Polls und Umfragestimmen
• Tapback nach Nachrichten-GUID oder Tapback-Entfernung
• Bearbeiten, Rückgängig machen, Löschen, Trotzdem benachrichtigen
• Lesebestätigungen, Tipp-Anzeigen, Überwachung von Bridge-Ereignissen
• Gruppe erstellen/umbenennen/Foto/Mitglied/verlassen/löschen/markieren Aktionen
• Konto, Who Is, Spitznamen-Prüfungen

Überprüfe vor Bridge-Aktionen:

imsg status --json

Wenn der Host Bridge-Aktionen unterstützt, Messages aber noch nicht injiziert ist, frage, bevor du imsg launch ausführst. Es beendet und startet Messages.app neu, um die Bridge zu injizieren. Behandle dies daher als sichtbare Zustandsänderung:

imsg launch
imsg status --json

Wenn SIP, Bibliotheksvalidierung, private Berechtigungsprüfungen oder fehlende Selektoren die Funktionalität noch blockieren, bitte den Benutzer nicht, SIP leichtfertig zu deaktivieren. Erkläre, dass die angeforderte private API-Aktion auf diesem Host nicht verfügbar ist, und biete die nächstgelegene Nicht-Bridge-Aktion an, falls eine existiert.

DM-Szenarien

Exakter Kontakt, einfaches Senden:

imsg send --to "+14155551212" --text "Bin unterwegs" --service auto

Bekannter DM-Thread:

imsg send --chat-id 42 --text "Bin unterwegs"
imsg send --chat-id 42 --file /pfad/zu/foto.jpg

Kanal nur erzwingen, wenn der Benutzer danach fragt:

imsg send --to "+14155551212" --text "grüne Blase" --service sms
imsg send --to "+14155551212" --text "Nur iMessage" --service imessage --no-sms-fallback

Thread-Antwort, Formatierung, Effekte oder Anhangsantwort:

imsg send-rich --chat 'iMessage;-;+15551234567' \
  --reply-to <nachrichten-guid> --text "Antworttext"
imsg send-rich --chat 'iMessage;-;+15551234567' --text 'hallo welt' \
  --format '[{"start":0,"length":5,"styles":["bold"]}]'
imsg send-rich --chat 'iMessage;-;+15551234567' --text "knall" --effect impact
imsg send-attachment --chat 'iMessage;-;+15551234567' \
  --reply-to <nachrichten-guid> --file /pfad/zu/datei.jpg

Formatierungsbereiche sind UTF-16-Positionen. Unterstützte Stile umfassen bold, italic, underline und strikethrough; verwende --format-file für generiertes JSON.

Gruppen-Szenarien

Vor dem Handeln prüfen:

imsg group --chat-id 42 --json
imsg history --chat-id 42 --limit 20 --json | jq -s

An eine bestehende Gruppe senden:

imsg send --chat-id 42 --text "Passt für mich"

Bridge-Antwort oder Umfrage in einer bestehenden Gruppe:

imsg send-rich --chat 'iMessage;+;chat0000' \
  --reply-to <nachrichten-guid> --text "Antwort im Thread"
imsg poll send --chat 'iMessage;+;chat0000' \
  --question "Abendessen?" --option "Pizza" --option "Sushi"

Gruppen nur auf explizite Anfrage erstellen oder ändern:

imsg chat-create --addresses '+15551111111,+15552222222' --name 'Crew' --text 'gm'
imsg chat-name --chat 'iMessage;+;chat0000' --name 'Umbenannt'
imsg chat-photo --chat 'iMessage;+;chat0000' --file /pfad/zu/gruppe.jpg
imsg chat-add-member --chat 'iMessage;+;chat0000' --address +15553333333
imsg chat-remove-member --chat 'iMessage;+;chat0000' --address +15553333333
imsg chat-leave --chat 'iMessage;+;chat0000'
imsg chat-delete --chat 'iMessage;+;chat0000'
imsg chat-mark --chat 'iMessage;+;chat0000' --read

Gruppenänderungen sind sehr sichtbar. Bestätige die genaue Gruppe und Teilnehmerliste, bevor du die Mitgliedschaft, den Namen, das Foto, den Lesestatus änderst, die Gruppe verlässt oder löscht.

Reaktionen und Antworten

Öffentliches react ist eingeschränkt: Es reagiert auf die letzte eingehende Nachricht im Chat.

imsg react --chat-id 42 --reaction like
imsg react --chat-id 42 --reaction love
imsg react --chat-id 42 --reaction dislike
imsg react --chat-id 42 --reaction laugh
imsg react --chat-id 42 --reaction emphasis
imsg react --chat-id 42 --reaction question

Für eine bestimmte Nachrichten-GUID oder Entfernung verwende die Bridge tapback:

imsg tapback --chat 'iMessage;-;+15551234567' --message <nachrichten-guid> --kind love
imsg tapback --chat 'iMessage;-;+15551234567' --message <nachrichten-guid> --kind love --remove

Verwende send-rich --reply-to <nachrichten-guid> für Thread-Antworten. Bestätige die referenzierte Nachricht, wenn der Benutzer "das" oder "die vorherige" sagt.

Umfragen

Native Apple-Polls benötigen die Bridge. Die Erstellung benötigt mindestens zwei --option-Werte. Die Abstimmung erfordert entweder --option-id, --option-index oder --option.

Messages rendert nur die Optionen auf einem Poll-Ballon; der --question-Titel wird den Empfängern nicht angezeigt. Setze --question (erforderlich) plus mindestens zwei --option-Werte.

imsg poll send --chat 'iMessage;-;+15551234567' \
  --question "Abendessen?" --option "Pizza" --option "Sushi"
imsg poll send --chat 'iMessage;+;chat0000' --reply-to <nachrichten-guid> \
  --question "Zustimmen?" --option "Ja" --option "Nein"
imsg poll vote --chat 'iMessage;+;chat0000' \
  --poll <umfragen-nachrichten-guid> --option-id <options-id>

Finde Umfrage-IDs und Optionen mit:

imsg history --chat-id 42 --limit 20 --json | jq -s '.[] | select(.poll != null) | {guid, poll}'

Zeilen für Umfragestimmen sind poll-Ereignisse, keine Tapbacks; watch --reactions wird nicht benötigt, um sie zu sehen.

Überwachung und langlebige Agenten

Für ein kurzes einmaliges Warten verwende watch:

imsg watch --chat-id 42 --since-rowid 9000 --json
imsg watch --chat-id 42 --attachments --convert-attachments --json
imsg watch --chat-id 42 --reactions --json
imsg watch --chat-id 42 --bb-events --json

--since-rowid ist exklusiv. Ohne es startet watch bei der neuesten Zeile. watch verwendet Dateisystemereignisse plus einen niederfrequenten Polling-Fallback, sodass es nach verpassten SQLite-Seitenwagen-Ereignissen aufholen kann. Poll-Objekte erscheinen ohne --reactions.

Für einen Daemon oder eine Multi-Chat-Integration verwende imsg rpc. Es spricht JSON-RPC 2.0 über stdin/stdout. Überprüfe imsg status --json auf rpc_methods, bevor du neuere Bridge- oder Poll-Methoden verwendest.

Sicherheitsregeln

• Bestätige Empfänger, Chat und Inhalt vor jeder Sendung, es sei denn, die Anfrage des Benutzers enthält bereits genaue Werte.
• Bestätige sichtbare Zustandsänderungen: Lesebestätigungen, Tipp-Anzeigen, Bearbeitungen, Rückgängigmachungen, Löschungen, Umfragestimmen, Tapbacks, Gruppenmitgliedschaft, Gruppenname/Foto, Verlassen/Löschen von Chats.
• Sende niemals an unbekannte Nummern oder mehrdeutige Kontaktnamen-Übereinstimmungen ohne Zustimmung.
• Bestätige, dass Anhänge existieren und die beabsichtigten Dateien sind.
• Bevorzuge Telefonnummern im E.164-Format; verwende --region US oder eine andere Region nur, wenn es für lokale Formate nötig ist.
• Verwende Bridge-Aktionen nicht nur, weil sie verfügbar sind; verwende sie nur, wenn das angeforderte Verhalten sie benötigt.