QQ-Bot

QQ Bot verbindet sich über die offizielle QQ Bot API (WebSocket-Gateway) mit OpenClaw. Das Plugin unterstützt privaten C2C-Chat, Gruppen-@Nachrichten und Guild-Kanalnachrichten mit Rich Media (Bilder, Sprache, Video, Dateien).

Status: herunterladbares Plugin. Direktnachrichten, Gruppenchats, Guild-Kanäle und Medien werden unterstützt. Reaktionen und Threads werden nicht unterstützt.

Installieren

Installieren Sie QQ Bot vor der Einrichtung:

openclaw plugins install @openclaw/qqbot

Einrichtung

1. Gehen Sie zur QQ Open Platform und scannen Sie den QR-Code mit Ihrem QQ auf dem Smartphone, um sich zu registrieren / anzumelden.
2. Klicken Sie auf Create Bot, um einen neuen QQ Bot zu erstellen.
3. Suchen Sie AppID und AppSecret auf der Einstellungsseite des Bots und kopieren Sie sie.

AppSecret wird nicht im Klartext gespeichert — wenn Sie die Seite verlassen, ohne es zu speichern, müssen Sie ein neues generieren.

4. Fügen Sie den Kanal hinzu:

openclaw channels add --channel qqbot --token "AppID:AppSecret"

5. Starten Sie den Gateway neu.

Interaktive Einrichtungspfade:

openclaw channels addopenclaw configure --section channels

Konfigurieren

Minimale Konfiguration:

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecret: "YOUR_APP_SECRET",    },  },}

Env-Variablen für das Standardkonto:

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

Dateigestütztes AppSecret:

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecretFile: "/path/to/qqbot-secret.txt",    },  },}

Env-SecretRef-AppSecret:

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecret: { source: "env", provider: "default", id: "QQBOT_CLIENT_SECRET" },    },  },}

Hinweise:

• Der Env-Fallback gilt nur für das Standardkonto von QQ Bot.
• openclaw channels add --channel qqbot --token-file ... stellt nur das AppSecret bereit; die AppID muss bereits in der Konfiguration oder in QQBOT_APP_ID gesetzt sein.
• clientSecret akzeptiert auch SecretRef-Eingaben, nicht nur eine Klartextzeichenfolge.
• Legacy-Markierungszeichenfolgen secretref:/... sind keine gültigen clientSecret-Werte; verwenden Sie strukturierte SecretRef-Objekte wie im obigen Beispiel.

Einrichtung mehrerer Konten

Führen Sie mehrere QQ Bots unter einer einzelnen OpenClaw-Instanz aus:

{  channels: {    qqbot: {      enabled: true,      appId: "111111111",      clientSecret: "secret-of-bot-1",      accounts: {        bot2: {          enabled: true,          appId: "222222222",          clientSecret: "secret-of-bot-2",        },      },    },  },}

Jedes Konto startet seine eigene WebSocket-Verbindung und verwaltet einen unabhängigen Token-Cache (isoliert nach appId).

Fügen Sie per CLI einen zweiten Bot hinzu:

openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"

Gruppenchats

Die Unterstützung von QQ Bot für Gruppenchats verwendet QQ-Gruppen-OpenIDs, nicht Anzeigenamen. Fügen Sie den Bot einer Gruppe hinzu und erwähnen Sie ihn dann oder konfigurieren Sie die Gruppe so, dass sie ohne Erwähnung ausgeführt wird.

{  channels: {    qqbot: {      groupPolicy: "allowlist",      groupAllowFrom: ["member_openid"],      groups: {        "*": {          requireMention: true,          commandLevel: "all",          historyLimit: 50,          tools: { deny: ["exec", "read", "write"] },        },        GROUP_OPENID: {          name: "Release room",          requireMention: false,          ignoreOtherMentions: true,          commandLevel: "safety",          historyLimit: 20,          prompt: "Keep replies short and operational.",        },      },    },  },}

groups["*"] legt Standardwerte für jede Gruppe fest, und ein konkreter Eintrag groups.GROUP_OPENID überschreibt diese Standardwerte für eine Gruppe. Gruppeneinstellungen umfassen:

• requireMention: erfordert eine @Erwähnung, bevor der Bot antwortet. Standard: true.
• commandLevel: steuert, welche integrierten Slash-Befehle in Gruppen ausgeführt werden können. Standard: all, wodurch das zuvor bestehende QQBot-Gruppenverhalten beibehalten wird, wenn die Einstellung ausgelassen wird.
• ignoreOtherMentions: verwirft Nachrichten, die jemand anderen erwähnen, aber nicht den Bot.
• historyLimit: behält aktuelle Gruppen-Nachrichten ohne Erwähnung als Kontext für den nächsten erwähnten Turn. Setzen Sie 0, um dies zu deaktivieren.
• tools: erlaubt/verweigert Tools für die gesamte Gruppe.
• toolsBySender: gruppenbezogene Tool-Überschreibungen pro Absender; siehe Gruppen.
• name: lesbare Bezeichnung, die in Logs und im Gruppenkontext verwendet wird.
• prompt: gruppenspezifischer Verhaltens-Prompt, der an den Agent-Kontext angehängt wird.

commandLevel akzeptiert:

• all: hält erkannte integrierte Befehle wie bisher verfügbar. Einige Befehle können in Menüs verborgen bleiben, aber autorisierte Benutzer können sie weiterhin in der Gruppe ausführen.
• safety: erlaubt gängige Befehle für Zusammenarbeit wie /help, /btw und /stop; fordert Benutzer auf, sensible Befehle wie /config, /tools und /bash im privaten Chat auszuführen.
• strict: erlaubt nur die Gruppen-Sitzungssteuerungen, die für einen strikten Gruppenbetrieb benötigt werden. /stop bleibt weiterhin dringend, damit ein autorisierter Absender einen aktiven Lauf unterbrechen kann.

Alte QQBot-toolPolicy-Einträge sind außer Betrieb genommen. Führen Sie openclaw doctor --fix aus, um sie zu tools zu migrieren.

Aktivierungsmodi sind mention und always. requireMention: true wird mention zugeordnet; requireMention: false wird always zugeordnet. Eine Aktivierungsüberschreibung auf Sitzungsebene hat Vorrang vor der Konfiguration, wenn sie vorhanden ist.

Die eingehende Warteschlange ist pro Peer. Gruppen-Peers erhalten eine größere Warteschlangengrenze, halten menschliche Nachrichten bei voller Warteschlange vor von Bots verfasstem Rauschen und fassen Bursts normaler Gruppennachrichten zu einem zugeordneten Turn zusammen. Slash-Befehle werden weiterhin einzeln ausgeführt.

Sprache (STT / TTS)

STT und TTS unterstützen eine zweistufige Konfiguration mit priorisiertem Fallback:

{  channels: {    qqbot: {      stt: {        provider: "your-provider",        model: "your-stt-model",      },      tts: {        provider: "your-provider",        model: "your-tts-model",        voice: "your-voice",      },      accounts: {        "qq-main": {          tts: {            providers: {              openai: { voice: "shimmer" },            },          },        },      },    },  },}

Setzen Sie bei beiden enabled: false, um sie zu deaktivieren. TTS-Überschreibungen auf Kontoebene verwenden dieselbe Form wie messages.tts und werden tief über die Kanal-/globale TTS-Konfiguration gemergt.

Eingehende QQ-Sprachanhänge werden Agents als Audio-Medienmetadaten bereitgestellt, während die Roh-Sprachdateien aus generischen MediaPaths herausgehalten werden. Klartextantworten mit [[audio_as_voice]] synthetisieren TTS und senden eine native QQ-Sprachnachricht, wenn TTS konfiguriert ist.

Das Verhalten für ausgehende Audio-Uploads/Transcodierung kann außerdem mit channels.qqbot.audioFormatPolicy angepasst werden:

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

Zielformate

Jeder Bot hat seinen eigenen Satz von Benutzer-OpenIDs. Eine von Bot A empfangene OpenID kann nicht verwendet werden, um Nachrichten über Bot B zu senden.

Slash-Befehle

Integrierte Befehle, die vor der KI-Warteschlange abgefangen werden:

Hängen Sie ? an einen beliebigen Befehl an, um Nutzungshilfe zu erhalten (zum Beispiel /bot-upgrade ?).

Admin-Befehle (/bot-me, /bot-upgrade, /bot-logs, /bot-clear-storage, /bot-streaming, /bot-approve) sind nur für Direktnachrichten verfügbar und erfordern die openid des Absenders in einer expliziten allowFrom-Liste ohne Wildcard. Ein Wildcard-Eintrag allowFrom: ["*"] erlaubt Chat, gewährt aber keinen Zugriff auf Admin-Befehle. Gruppennachrichten werden zuerst gegen groupAllowFrom abgeglichen und fallen dann auf allowFrom zurück. Wenn ein Admin-Befehl in einer Gruppe ausgeführt wird, wird ein Hinweis zurückgegeben, statt ihn stillschweigend zu verwerfen.

Wenn QQ Bot-Ausführungsgenehmigungen den standardmäßigen Same-Chat-Fallback verwenden, folgen Klicks auf native Genehmigungsbuttons derselben expliziten Befehls-Allowlist ohne Wildcard. Um nur Genehmigungszugriff ohne breiteren Befehlszugriff zu gewähren, konfigurieren Sie channels.qqbot.execApprovals.approvers.

Engine-Architektur

QQ Bot wird als eigenständige Engine innerhalb des Plugins ausgeliefert:

• Jedes Konto besitzt einen isolierten Ressourcen-Stack (WebSocket-Verbindung, API-Client, Token-Cache, Medienspeicher-Root), der über appId geschlüsselt ist. Konten teilen niemals eingehenden/ausgehenden Zustand.
• Der Multi-Konto-Logger markiert Logzeilen mit dem zugehörigen Konto, damit Diagnosen getrennt bleiben, wenn Sie mehrere Bots unter einem Gateway ausführen.
• Eingehende, ausgehende und Gateway-Bridge-Pfade teilen sich einen einzelnen Medien-Payload-Root unter ~/.openclaw/media, sodass Uploads, Downloads und Transcode-Caches in einem geschützten Verzeichnis landen, statt in einem Baum pro Subsystem.
• Die Rich-Media-Zustellung läuft über einen einzigen sendMedia-Pfad für C2C- und Gruppenziele. Lokale Dateien und Puffer oberhalb des Schwellenwerts für große Dateien verwenden die Chunked-Upload-Endpunkte von QQ, während kleinere Payloads die One-Shot-Medien-API verwenden.
• Anmeldedaten können als Teil der standardmäßigen OpenClaw-Anmeldedaten-Snapshots gesichert und wiederhergestellt werden; die Engine hängt den Ressourcen-Stack jedes Kontos bei der Wiederherstellung erneut ein, ohne ein frisches QR-Code-Paar zu erfordern.

QR-Code-Onboarding

Als Alternative zum manuellen Einfügen von AppID:AppSecret unterstützt die Engine einen QR-Code-Onboarding-Ablauf zum Verknüpfen eines QQ Bot mit OpenClaw:

1. Führen Sie den Einrichtungspfad für QQ Bot aus (zum Beispiel openclaw channels add --channel qqbot) und wählen Sie den QR-Code-Ablauf, wenn Sie dazu aufgefordert werden.
2. Scannen Sie den generierten QR-Code mit der Smartphone-App, die mit dem Ziel-QQ Bot verknüpft ist.
3. Genehmigen Sie die Kopplung auf dem Smartphone. OpenClaw speichert die zurückgegebenen Anmeldedaten unter dem richtigen Kontoumfang in credentials/.

Genehmigungs-Prompts, die vom Bot selbst erzeugt werden (zum Beispiel „Diese Aktion zulassen?“-Abläufe, die von der QQ Bot API bereitgestellt werden), erscheinen als native OpenClaw-Prompts, die Sie mit /bot-approve akzeptieren können, statt über den rohen QQ-Client zu antworten.

Fehlerbehebung

• Bot antwortet „zum Mars verschwunden“: Zugangsdaten sind nicht konfiguriert oder der Gateway wurde nicht gestartet.
• Keine eingehenden Nachrichten: Prüfen Sie, ob appId und clientSecret korrekt sind und der Bot auf der QQ Open Platform aktiviert ist.
• Wiederholte Selbstantworten: OpenClaw zeichnet ausgehende QQ-Referenzindizes als vom Bot verfasst auf und ignoriert eingehende Ereignisse, deren aktueller msgIdx mit demselben Bot-Konto übereinstimmt. Dadurch werden Plattform-Echo-Schleifen verhindert, während Benutzer weiterhin frühere Bot-Nachrichten zitieren oder darauf antworten können.
• Einrichtung mit --token-file wird weiterhin als nicht konfiguriert angezeigt: --token-file legt nur das AppSecret fest. Sie benötigen weiterhin appId in der Konfiguration oder QQBOT_APP_ID.
• Proaktive Nachrichten kommen nicht an: QQ kann vom Bot initiierte Nachrichten abfangen, wenn der Benutzer kürzlich nicht interagiert hat.
• Sprache wird nicht transkribiert: Stellen Sie sicher, dass STT konfiguriert und der Provider erreichbar ist.

Verwandte Themen

• Kopplung
• Gruppen
• Fehlerbehebung für Kanäle