QQ-Bot

QQ Bot verbindet sich über die offizielle QQ Bot API (WebSocket-Gateway) mit OpenClaw. Private C2C-Chats und @-Erwähnungen in Gruppen sind die primären Chattypen und unterstützen Rich Media (Bilder, Sprachnachrichten, Videos und Dateien). Nachrichten in Guild-Kanälen unterstützen nur Text und Bilder über Remote-URLs; Sprachnachrichten, Videos, Datei-Uploads und lokale/Base64- Bilder sind in Guild-Kanälen nicht verfügbar. Reaktionen und Threads werden nirgends unterstützt.

Status: offizielles herunterladbares Plugin.

Installation

openclaw plugins install @openclaw/qqbot

Einrichtung

1. Rufen Sie die QQ Open Platform auf und scannen Sie den QR-Code mit QQ auf Ihrem Mobiltelefon, um sich zu registrieren bzw. anzumelden.
2. Klicken Sie auf Create Bot, um einen neuen QQ-Bot zu erstellen.
3. Suchen Sie auf der Einstellungsseite des Bots nach AppID und AppSecret und kopieren Sie beide Werte.

4. Fügen Sie den Kanal hinzu:

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

5. Starten Sie den Gateway neu.

Interaktive Einrichtung:

openclaw channels add

Der Assistent bietet alternativ zur manuellen Eingabe von AppID/AppSecret auch eine QR-Code-Verknüpfung an: Scannen Sie den Code mit der Mobiltelefon-App, die mit dem gewünschten QQ Bot verknüpft ist, um die Verknüpfung abzuschließen. OpenClaw speichert die zurückgegebenen Anmeldedaten im Konfigurationsbereich des Kontos.

Konfiguration

Minimale Konfiguration:

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

Umgebungsvariablen für das Standardkonto (nur Konto auf oberster Ebene):

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

Dateibasiertes AppSecret:

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

AppSecret als SecretRef aus einer Umgebungsvariable:

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

Hinweise:

• openclaw channels add --channel qqbot --token-file ... setzt nur das AppSecret; appId muss bereits in der Konfiguration oder in QQBOT_APP_ID festgelegt sein.
• clientSecret akzeptiert eine Klartextzeichenfolge, einen Dateipfad (clientSecretFile) oder ein strukturiertes SecretRef-Objekt.
• Veraltete Markierungszeichenfolgen vom Typ secretref:... / secretref-env:... werden für clientSecret abgelehnt; verwenden Sie stattdessen ein strukturiertes SecretRef-Objekt.

Zugriffsrichtlinie

• allowFrom / groupAllowFrom bestimmen, wer in C2C- bzw. Gruppenkontexten mit dem Bot chatten darf. dmPolicy / groupPolicy (open | allowlist | disabled) steuern den Durchsetzungsmodus. dmPolicy verwendet standardmäßig allowlist, sobald allowFrom einen konkreten Eintrag ohne Platzhalter enthält, andernfalls open. groupPolicy verwendet standardmäßig allowlist, sobald entweder groupAllowFrom oder allowFrom einen konkreten Eintrag enthält, andernfalls open.
• Slash-Befehle mit „Authentifizierung: Zulassungsliste“ erfordern unabhängig von dmPolicy / groupPolicy einen expliziten Eintrag ohne Platzhalter in allowFrom (bzw. in groupAllowFrom bei Aufrufen aus Gruppen) – siehe Slash-Befehle.

Einrichtung mehrerer Konten

Führen Sie mehrere QQ-Bots in einer einzigen 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 besitzt eine isolierte WebSocket-Verbindung, einen eigenen API-Client und einen eigenen Token-Cache, jeweils nach appId indiziert. Protokollzeilen werden mit der ID des zugehörigen Kontos gekennzeichnet, damit die Diagnose beim Betrieb mehrerer Bots über einen Gateway getrennt bleibt.

Fügen Sie über die CLI einen zweiten Bot hinzu:

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

Gruppenchats

Die Gruppenunterstützung verwendet QQ-Gruppen-OpenIDs, nicht die Anzeigenamen. Fügen Sie den Bot einer Gruppe hinzu und erwähnen Sie ihn anschließend oder konfigurieren Sie die Gruppe für den Betrieb ohne Erwähnung.

{  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 alle Gruppen fest; ein konkreter Eintrag groups.GROUP_OPENID überschreibt diese Standardwerte für eine einzelne Gruppe. Gruppeneinstellungen:

commandLevel akzeptiert:

Alte QQBot-Einträge für toolPolicy werden nicht mehr verwendet. Führen Sie openclaw doctor --fix aus, um sie zu tools zu migrieren.

Die Aktivierungsmodi sind mention und always. requireMention: true entspricht mention; requireMention: false entspricht always. Eine Aktivierungsüberschreibung auf Sitzungsebene hat, sofern vorhanden, Vorrang vor der Konfiguration.

Die Eingangswarteschlange wird pro Kommunikationspartner verwaltet. Gruppenpartner erhalten eine größere Warteschlangenkapazität (50 gegenüber 20 bei direkten Partnern). Bei voller Warteschlange werden vom Bot verfasste Nachrichten vor menschlichen Nachrichten entfernt, und Serien normaler Gruppennachrichten werden zu einem zugeordneten Turn zusammengeführt. Slash-Befehle werden unabhängig von zusammengeführten Stapeln einzeln nacheinander ausgeführt.

Sprache (STT / TTS)

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

{  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 jeweils enabled: false, um die Funktion zu deaktivieren. TTS-Überschreibungen auf Kontoebene verwenden dieselbe Struktur wie messages.tts und werden rekursiv mit der kanalweiten/globalen TTS-Konfiguration zusammengeführt, wobei sie deren Werte überschreiben.

STT-Anfragen haben standardmäßig nach 60 Sekunden ein Zeitlimit. Plugin-spezifisches STT verwendet die ausgewählte Überschreibung models.providers.<id>.timeoutSeconds. Das Audio-STT des Frameworks verwendet zunächst tools.media.audio.models[0].timeoutSeconds, dann tools.media.audio.timeoutSeconds und anschließend die Überschreibung des ausgewählten Providers.

Eingehende QQ-Sprachanhänge werden Agenten als Metadaten für Audiomedien bereitgestellt, während die unverarbeiteten Sprachdateien aus den generischen MediaPaths herausgehalten werden. [[audio_as_voice]] in einer Klartextantwort synthetisiert TTS und sendet eine native QQ-Sprachnachricht, wenn TTS konfiguriert ist.

Das Verhalten beim Hochladen und Transkodieren ausgehender Audiodaten kann außerdem mit channels.qqbot.audioFormatPolicy angepasst werden:

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

Zielformate

Slash-Befehle

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

Hängen Sie für Verwendungshinweise ? an einen beliebigen Befehl an (zum Beispiel /bot-upgrade ?).

Befehle mit „Authentifizierung: Zulassungsliste“ erfordern zusätzlich die OpenID des Absenders in einer expliziten allowFrom-Liste ohne Platzhalter (groupAllowFrom hat bei aus Gruppen ausgeführten Befehlen Vorrang; andernfalls wird auf allowFrom zurückgegriffen). Der Platzhalter allowFrom: ["*"] erlaubt Chats, jedoch nicht diese Befehle. Wird einer dieser Befehle außerhalb eines privaten Chats oder ohne Autorisierung ausgeführt, wird ein Hinweis zurückgegeben, anstatt die Nachricht stillschweigend zu verwerfen.

/bot-me, /bot-version und /bot-upgrade sind ausschließlich für private Chats vorgesehen, erfordern jedoch keine Zulassungsliste – jeder C2C-Absender kann sie ausführen.

Wenn Ausführungsgenehmigungen für QQ Bot den standardmäßigen Rückgriff auf denselben Chat verwenden, unterliegen Klicks auf native Genehmigungsschaltflächen derselben expliziten Befehlszulassungsliste ohne Platzhalter. Um ausschließlich Zugriff auf Genehmigungen ohne weitergehenden Befehlszugriff zu gewähren, konfigurieren Sie channels.qqbot.execApprovals.approvers. Native Ausführungsgenehmigungen sind standardmäßig aktiviert.

Medien und Speicher

• Eingehende und ausgehende Medien sowie Medien der Gateway-Bridge verwenden gemeinsam ein Nutzdaten-Stammverzeichnis unter ~/.openclaw/media/qqbot (OPENCLAW_HOME wird berücksichtigt, wenn es gesetzt ist), sodass Uploads, Downloads und Transcodierungs-Caches in einem einzigen geschützten Verzeichnis verbleiben.
• Die Übermittlung von Rich Media an C2C- und Gruppenziele erfolgt über einen gemeinsamen sendMedia-Pfad. Lokale Dateien und speicherinterne Puffer ab 5 MiB verwenden die Endpunkte von QQ für segmentierte Uploads; kleinere Nutzdaten sowie Remote-URL-/Base64-Quellen verwenden die API für einmalige Uploads.
• Wenn ein Hot-Upgrade das Gateway unterbricht, bevor das Schreiben von openclaw.json abgeschlossen ist, stellt das Plugin beim nächsten Start die zuletzt bekannten Werte für appId / clientSecret dieses Kontos aus einem internen Snapshot wieder her (ohne jemals eine beabsichtigte Konfigurationsänderung zu überschreiben), sodass der QR-Code nicht erneut gescannt werden muss.

Fehlerbehebung

• Gateway startet nicht / keine eingehenden Nachrichten: Überprüfen Sie, ob appId und clientSecret korrekt sind und der Bot auf der QQ Open Platform aktiviert ist. Fehlende Anmeldedaten werden als „QQBot nicht konfiguriert (appId oder clientSecret fehlt)“ angezeigt.
• Einrichtung mit --token-file wird weiterhin als nicht konfiguriert angezeigt: --token-file legt nur das AppSecret fest. appId muss weiterhin in der Konfiguration oder über QQBOT_APP_ID festgelegt werden.
• Antwortserien in Gruppen kollidieren: Wenn sich die Warteschlange eines Kommunikationspartners füllt, entfernt die Warteschlange für eingehende Nachrichten von Bots verfasste Nachrichten vor menschlichen Nachrichten und führt Serien normaler Gruppennachrichten (keine Befehle) zu einem einzelnen, zugeordneten Durchlauf zusammen, sodass eine Flut von Bot-Nachrichten menschliche Nachrichten nicht verdrängen sollte.
• Proaktive Nachrichten kommen nicht an: QQ kann vom Bot initiierte Nachrichten blockieren, wenn der Benutzer in letzter Zeit nicht interagiert hat.
• Sprachnachricht wird nicht transkribiert: Stellen Sie sicher, dass STT konfiguriert und der Provider erreichbar ist.

Verwandte Themen

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