OpenClaw + QQ: Plugin-Anbindung und ultralanges Debugging-Postmortem (kompletter Ablauf)

AIDO debug
, ,
1

OpenClaw + QQ-Plugin-Integration und ausführliche Fehleranalyse/Retro (Gesamtprozess)

Hinweis: Diese Retro ist nach den tatsächlich ausgeführten Schritten整理iert und fokussiert darauf, den kompletten Ablauf von Integration und gemeinsamer Fehlersuche bis zur Lokalisierung des Kernproblems sowie jede zentrale Schlussfolgerung zu dokumentieren.

I. Hintergrund und Ziel

Ziel dieses Vorhabens war es, OpenClaw an den QQ-Kanal anzubinden (basierend auf NapCat + dem Plugin openclaw_qq) und Folgendes zu erreichen:

  • QQ Privat-Chat/Gruppen-Chat kann normal senden/empfangen
  • Sitzungs-Routing und WebUI-Protokolle sind sichtbar
  • Admin-/Blacklist-Strategie ist steuerbar (Schutz vor Token-Missbrauch)
  • Konfiguration kann in der Control UI stabil gespeichert werden

II. Umgebung und Zeitachse (grob)

Basierend auf den Zeitstempeln in den Gateway-Logs umfasste diese Analyse mehrere Phasen; die kontinuierliche, hochintensive Fehlersuche dauerte mehrere Stunden (ca. 4+ Stunden).

III. Haupt-Workflow (nach Phasen)

1) QQ-Kanal-Anbindung und Basis-Integrationstest

Ich habe zuerst die grundlegende Bereitstellung des QQ-Plugins und von NapCat abgeschlossen:

  • Installation und Aktivierung des openclaw_qq-Plugins
  • Deployment von NapCat via Docker
  • Korrektur des NapCat-Verbindungsmodus auf Forward WS Server (OpenClaw verbindet sich als Client)
  • Nach Abgleich von OneBot-Token und Account war der QQ-Kanal-Status wieder OK

2) Behebung von Sitzungs- und Routing-Problemen

Im Integrationstest trat das Phänomen auf, dass „QQ-Sitzungen in die Hauptsitzung/TG-Sitzung geraten“. Ich habe das Routing repariert:

  • Behebung der Route-Analyse für QQ group/direct
  • Verhindert, dass beim Schreiben von QQ die Metadaten der Hauptsitzung überschrieben werden
  • Sicherstellen, dass QQ- und TG-Sitzungen getrennt und nachvollziehbar sind

Ergebnis: Die Sichtbarkeit von QQ-Sitzungen in der WebUI hat sich deutlich verbessert.

3) Anpassung von Kontext- und Duplicate-Message-Strategien

Gegen das Problem „QQ bringt jedes Mal sehr viel Verlauf mit, was zu Rauschen führt“:

  • Standard von historyLimit auf 0 geändert
  • In der Dokumentation klargestellt: Standardmäßig wird auf das OpenClaw-Sitzungssystem gesetzt; es wird nicht erzwungen, Gruppen-Originaltexte zusammenzukleben
  • Verlauf-Zusammenführung nur aktivieren, wenn der Nutzer es ausdrücklich braucht

Außerdem Logik zu doppeltem Triggern/ doppelten Hinweisen behoben:

  • Reihenfolge der Admin-Restriktionsprüfung angepasst: erst Trigger-Bedingungen (@/Keyword), dann Authentifizierung
  • Für Nicht-Admin-Hinweise Cooldown/Entprellung hinzugefügt (Standard 10 Sekunden)
  • Hinweis-Schleife im reply-to-bot-Szenario behoben

4) Erweiterung der Admin-/Blacklist-Fähigkeiten

Zum Schutz vor Missbrauch habe ich Fähigkeiten ergänzt und verstärkt:

  • adminOnlyChat
  • notifyNonAdminBlocked
  • nonAdminBlockedMessage
  • blockedNotifyCooldownMs

Die Blacklist-Logik wurde final wie folgt bestätigt:

  • Nachrichten von Nutzern, die blockedUsers treffen, werden direkt ignoriert (keine Antwort, kein Hinweis)

5) Control UI und Problem beim Speichern der Konfiguration (Schwerpunkt)

Das zeitaufwändigste und entscheidendste Problem war:

  • Auf der /config-Seite führt selbst das Ändern nur der QQ-Whitelist/Blacklist weiterhin zu invalid config
  • Der Fehler zeigt jedoch auf models.providers.*.models[0].maxTokens

Finale Diagnose/Schlussfolgerungen:

  1. /config speichert ein Gesamtpaket, nicht nur channels.qq
  2. Bei der Gesamtpaket-Validierung führt bereits ein einzelnes anormales Feld dazu, dass das gesamte Speichern fehlschlägt
  3. maxTokens wird in manchen Ketten fälschlich verarbeitet (Stringifizierung/„Redline“-False-Positive), wodurch die Gesamtpaket-Validierung scheitert
  4. Daher wirkt es so, als ob „das Ändern der QQ-Nummer einen Modellfehler auslöst“, tatsächlich ist es „Kollektivhaftung durch Gesamtpaket-Validierung“

IV. Warum es so aussieht, als würde „QQ-Nummer ändern“ maxTokens mit betreffen

In einem Satz: keine fachliche Abhängigkeit, sondern eine Abhängigkeit des Speichermodells.

  • Geändert wird ein QQ-Feld
  • Ausgelöst wird das Zurückschreiben der gesamten Konfiguration
  • In der gesamten Konfiguration driftet der Typ im Modellfeld (z. B. maxTokens wird String/ungültig)
  • Validierungsphase schlägt fehl, Fehler wird bis ins Frontend durchgereicht

V. Repository- und lokale Sync-Aktionen

Ich habe im Plugin-Repository kontinuierlich fixes gemacht und mehrfach gepusht, inklusive:

  • Fix der Admin-Strategie
  • Fix des Sitzungs-Routings
  • Anpassung der Defaultwerte für History-Injection
  • Verbesserte Frontend-Schema-Kompatibilität
  • Ausbau der Doku (chinesische Beispiele)
  • Ergänzung der NapCat-Docker-Deployment-Dateien
  • Runtime-Verzeichnisse ignorieren, um Repo-Verschmutzung zu verhindern

Gleichzeitig blieb lokal .openclaw/extensions/qq mit dem Remote-Hauptbranch synchron.

VI. Zur Frage „Kann man das komplett lösen, indem man nur das QQ-Plugin ändert?“

Fazit:

  • Löst das Verhalten innerhalb des QQ-Plugins und die meisten Usability-Probleme
  • Kann aber das Core-Problem der OpenClaw-Gesamtpaket-Speicher-Kette nicht vollständig aus Plugin-Ebene beheben
  • Denn die Validierung von models.* gehört zu OpenClaw Core und liegt außerhalb des QQ-Plugin-Scopes

VII. Ausführbare Empfehlungen (final)

Kurzfristig nutzbar (Core nicht ändern)

  • QQ-Whitelist/Blacklist per CLI ändern, um den /config-Gesamtpaket-Speicherpfad zu umgehen:
openclaw config set channels.qq.admins '\"1838552185\"' --json
openclaw config set channels.qq.blockedUsers '\"342571216\"' --json
openclaw gateway restart

Mittelfristige Empfehlung (Root Cause)

  • Auf einen offiziellen Fix von OpenClaw warten/ihn verfolgen (Issue-Klasse: maxTokens + redaction + config save)
  • Oder eine Minimal-Reproduktion und einen Patch-PR an die offiziellen Maintainer einreichen

VIII. Learnings

  1. Beim Debugging der /config-Seite immer im Sinne von „Gesamtpaket-Validierung“ denken, nicht nur auf das geänderte Feld starren
  2. Wenn Konfigurations-Redaction mit Wide-Matching (z. B. /token/i) arbeitet, trifft sie fälschlich maxTokens
  3. Für Chat-Plugins ist die Authentifizierungsreihenfolge (erst Trigger, dann Auth) entscheidend, sonst entsteht Gruppenrauschen
  4. Entprellung und Deduplizierung müssen standardmäßig aktiv sein, sonst eskaliert das Problem im Gruppenchat sehr schnell