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
| Parameter | Beschreibung |
|---|---|
--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 |
--json | JSON-Ausgabe. Bei programmatischem Aufruf erforderlich |
--dry-run | Vorschau, 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
--toverwendet standardmäßig denuserIdaus der Kontodatei (gebundener Benutzer)- Wenn die Umgebungsvariable
WXCLAW_TOKENgesetzt 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
| Fehler | Bedeutung | Behandlung |
|---|---|---|
ret=-2 | Ratenbegrenzung (ca. 7 Nachrichten pro Bot alle 5 Minuten, von allen Clients geteilt) | 60-120 Sekunden warten, dann wiederholen; keine engen Schleifen |
ret=-14 | Sitzung abgelaufen | Über openclaw erneut anmelden |
| Kein Konto gefunden | Anmeldeinformationen fehlen | wxclawbot accounts zur Fehlersuche ausführen |
| CDN-Upload-Fehler | Datei-Upload fehlgeschlagen | Dateigröße/-format prüfen und wiederholen |
| Request-Timeout | Netzwerkproblem (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}
errorKind | Bedeutung | retryable |
|---|---|---|
timeout | Anfrage über 15 Sekunden | true |
dns | DNS-Auflösung fehlgeschlagen | true |
connection | Verbindung zurückgesetzt / Socket-Hang-Up | true |
network | Verbindung abgelehnt / Host nicht erreichbar / Fetch fehlgeschlagen | true |
tls | Zertifikats- oder TLS-Fehler | false |
unknown | Nicht klassifizierter Fehler | false |
Das Feld retryable gibt an, ob ein erneuter Versuch sinnvoll ist oder der Fehler als endgültig betrachtet werden sollte.
Häufige Fallstricke
--jsonmuss 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
| Variable | Verwendung |
|---|---|
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.