Communitygithub.com

lroolle/wxclawbot-cli

Weixin ClawBot CLI – aktive Nachrichtenübermittlung für OpenClaw-Agenten

Was ist wxclawbot-cli?

Dieses Skill ermöglicht es KI-Agenten, aktiv Nachrichten über WeChat zu versenden, was mit dem standardmäßigen iLink Bot nicht möglich ist, da dieser nur passiv auf Nutzernachrichten reagieren kann. Der Agent kann so proaktive Szenarien wie zeitgesteuerte Erinnerungen, Alarmmeldungen und Berichtszustellungen realisieren. Das CLI-Tool `wxclawbot` unterstützt den Versand von Text, Bildern, Videos und Dateien und kann mit Cron-Jobs für zeitgesteuerte Aufgaben kombiniert werden. Das Skill ist für Agentenplattformen wie Claude Code, Cursor oder Codex geeignet und bietet eine JSON-Schnittstelle für die programmatische Integration, sodass der Agent die Ergebnisse einfach parsen und weiterverarbeiten kann. Eine Besonderheit ist die automatische Handhabung des `context_token`, der für die aktive Zustellung von Nachrichten erforderlich ist, sowie eine umfassende Fehlerbehandlung mit strukturierten Fehlerarten für zuverlässige Automatisierung.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add lroolle/wxclawbot-cli

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

wxclawbot-send

Welches Problem löst dieses Skill?

Der WeChat-Roboter (iLink Bot) kann nur passiv auf Benutzernachrichten antworten, aber keine aktiven Unterhaltungen starten. Das bedeutet, dass Agenten keine Szenarien wie zeitgesteuerte Erinnerungen, Alarmmeldungen oder Berichtszustellungen realisieren können.

Dieses Skill ermöglicht es dem Agenten, über das wxclawbot CLI aktiv Nachrichten an WeChat-Benutzer zu senden, darunter Text, Bilder, Videos und Dateien. In Kombination mit Cron können zeitgesteuerte Aufgaben realisiert werden.

Voraussetzungen

  • Node.js >= 20
  • npm install -g @claw-lab/wxclawbot-cli
  • openclaw-weixin muss angemeldet sein (Anmeldeinformationen in ~/.openclaw/openclaw-weixin/accounts/)

Überprüfung: wxclawbot accounts --json

Schnellstart

wxclawbot send --text "Nachrichteninhalt" --json
wxclawbot send --file ./photo.jpg --json
wxclawbot send --file ./report.pdf --text "Bitte entgegennehmen" --json

Wann verwende ich was?

Aktiv Textnachrichten senden  → wxclawbot send --text "msg" --json
Aktiv Dateien/Bilder senden    → wxclawbot send --file ./pfad --json
Kontostatus prüfen             → wxclawbot accounts --json
Programmatischer Aufruf        → siehe references/programmatic-api.md

Befehlsreferenz

send

wxclawbot send --text "Nachricht" --json
wxclawbot send --to "[email protected]" --text "Hallo" --json
wxclawbot send --file ./photo.jpg --json
wxclawbot send --file ./report.pdf --text "Bitte entgegennehmen" --json
wxclawbot send --file "https://example.com/img.png" --json
echo "Tagesbericht erstellt" | wxclawbot send --json
wxclawbot send --text "test" --dry-run
ParameterBeschreibung
--text <msg>Nachrichtentext. "-" liest explizit von stdin
--file <pfad>Lokale Datei oder URL (Bild/Video/Datei)
--to <userId>Zielbenutzer-ID. Standard: an das Konto gebundener Benutzer
--account <id>Konto angeben. Standard: erstes verfügbares
--jsonJSON-Ausgabe. Bei programmatischem Aufruf erforderlich
--dry-runVorschau, kein Versand

Medientypen werden automatisch anhand der Dateierweiterung erkannt:

  • Bilder: .png .jpg .jpeg .gif .webp .bmp
  • Videos: .mp4 .mov .webm .mkv .avi
  • Dateien: alle anderen

accounts

wxclawbot accounts --json

Rückgabe: [{"id":"<botId>-im-bot","configured":true,"baseUrl":"..."}]

Mechanismus zur Kontofindung

Das CLI findet Konten automatisch in ~/.openclaw/openclaw-weixin/accounts/*.json. Jede Datei enthält token, baseUrl, userId (Standardziel für --to).

  • Die Bot-ID wird zur Laufzeit aus dem Token extrahiert (nicht fest codiert)
  • Die Konto-ID kann sich nach einem Upgrade oder einer Neuregistrierung von openclaw-weixin ändern
  • --to verwendet standardmäßig den userId aus der Kontodatei (gebundener Benutzer)
  • Wenn die Umgebungsvariable WXCLAW_TOKEN gesetzt ist, überschreibt sie die Dateisuche

Context-Token (entscheidend für aktive Push-Nachrichten)

WeChat erfordert einen context_token, um Nachrichten aktiv zustellen zu können. Ohne diesen verbleiben Nachrichten auf dem Server, bis der Benutzer das Chatfenster aktiv öffnet – das wäre keine "aktive Zustellung" mehr.

Das CLI liest automatisch {accountId}.context-tokens.json (im selben Verzeichnis wie die Kontodatei). Diese Datei wird von openclaw-weixin verwaltet und enthält eine Zuordnung von userId zu contextToken. Keine manuelle Konfiguration erforderlich – openclaw-weixin speichert den Token automatisch, sobald der Benutzer dem Roboter eine Nachricht gesendet hat.

Fehlt der context_token (neuer Benutzer, Token abgelaufen), wird die Nachricht trotzdem erfolgreich gesendet (ok:true), aber es erfolgt keine aktive Push-Benachrichtigung.

Nach einem Upgrade von openclaw-weixin unbedingt mit wxclawbot accounts --json überprüfen.

Agentenintegration

Bei programmatischem Aufruf muss --json verwendet werden. Das JSON-Ergebnis gibt Aufschluss über den Erfolg.

ergebnis=$(wxclawbot send --text "Aufgabe erledigt" --json)
ergebnis=$(wxclawbot send --file ./chart.png --text "Tägliche Kennzahlen" --json)
  • Erfolg: {"ok":true,"to":"[email protected]","clientId":"..."}
  • Fehler: {"ok":false,"error":"..."}
  • Exit-Code: 0 = CLI-Ausführung erfolgreich, 1 = Fehlgeschlagen

Hinweis: Exit 0 bedeutet nur, dass das CLI ausgeführt wurde, nicht dass die Nachricht zugestellt wurde. Auf das ok-Feld achten.

Fehlerbehandlung

FehlerBedeutungBehandlung
ret=-2Ratenbegrenzung (ca. 7 Nachrichten pro Bot alle 5 Minuten, von allen Clients geteilt)60-120 Sekunden warten, dann wiederholen; keine engen Schleifen
ret=-14Sitzung abgelaufenÜber openclaw erneut anmelden
Kein Konto gefundenAnmeldeinformationen fehlenwxclawbot accounts zur Fehlersuche ausführen
CDN-Upload-FehlerDatei-Upload fehlgeschlagenDateigröße/-format prüfen und wiederholen
Request-TimeoutNetzwerkproblem (15 Sekunden Timeout)Wiederholen

Die Ratenbegrenzung erfolgt serverseitig und wird von allen Clients unter demselben Bot-Token geteilt.

Strukturierte Übertragungsfehler (v0.5.1+)

Im --json-Modus enthalten Übertragungsfehler zusätzliche Felder:

{"ok":false,"error":"send failed: ...","errorKind":"timeout","retryable":true}
errorKindBedeutungretryable
timeoutAnfrage über 15 Sekundentrue
dnsDNS-Auflösung fehlgeschlagentrue
connectionVerbindung zurückgesetzt / Socket-Hang-Uptrue
networkVerbindung abgelehnt / Host nicht erreichbar / Fetch fehlgeschlagentrue
tlsZertifikats- oder TLS-Fehlerfalse
unknownNicht klassifizierter Fehlerfalse

Das Feld retryable gibt an, ob ein erneuter Versuch sinnvoll ist oder der Fehler als endgültig betrachtet werden sollte.

Häufige Fallstricke

  • --json muss verwendet werden – ohne diese Option erfolgt die Ausgabe in menschenlesbarem Format, das nicht parsbar ist
  • Auf das ok-Feld achten – Exit 0 bedeutet nur, dass das CLI ausgeführt wurde, nicht dass die Nachricht zugestellt ist
  • Keine engen Schleifen bei ret=-2 – mindestens 5-10 Sekunden warten
  • Große Texte über stdin – echo "..." | wxclawbot send --json, um Probleme mit Shell-Anführungszeichen zu vermeiden
  • Dateien werden verschlüsselt in die WeChat-CDN hochgeladen – große Dateien benötigen möglicherweise etwas Zeit

Umgebungsvariablen

VariableVerwendung
WXCLAW_TOKENÜberschreibt den Bot-Token ([email protected]:dein-token)
WXCLAW_BASE_URLÜberschreibt den API-Endpunkt (Standard: https://ilinkai.weixin.qq.com)

Die programmatische Schnittstelle ist unter references/programmatic-api.md beschrieben.

Verwandte Skills