Bot QQ

QQ Bot łączy się z OpenClaw za pośrednictwem oficjalnego API QQ Bot (Gateway WebSocket). Podstawowymi typami czatu są prywatne rozmowy C2C oraz wzmianki @ w grupach, z obsługą multimediów (obrazów, wiadomości głosowych, filmów i plików). Wiadomości w kanałach gildii obsługują wyłącznie tekst i obrazy ze zdalnych adresów URL; wiadomości głosowe, filmy, przesyłanie plików oraz obrazy lokalne/Base64 nie są dostępne w kanałach gildii. Reakcje i wątki nie są nigdzie obsługiwane.

Status: oficjalny Plugin do pobrania.

Instalacja

openclaw plugins install @openclaw/qqbot

Konfiguracja początkowa

1. Przejdź do QQ Open Platform i zeskanuj kod QR za pomocą aplikacji QQ na telefonie, aby się zarejestrować lub zalogować.
2. Kliknij Create Bot, aby utworzyć nowego bota QQ.
3. Znajdź AppID i AppSecret na stronie ustawień bota, a następnie je skopiuj.

4. Dodaj kanał:

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

5. Uruchom ponownie Gateway.

Konfiguracja interaktywna:

openclaw channels add

Kreator umożliwia również powiązanie za pomocą kodu QR zamiast ręcznego wpisywania AppID/AppSecret: zeskanuj kod aplikacją na telefonie powiązaną z docelowym QQ Bot, aby ukończyć powiązanie. OpenClaw zapisuje zwrócone dane uwierzytelniające w zakresie konfiguracji konta.

Konfiguracja

Konfiguracja minimalna:

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

Zmienne środowiskowe konta domyślnego (tylko konto najwyższego poziomu):

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

AppSecret przechowywany w pliku:

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

AppSecret jako SecretRef ze zmiennej środowiskowej:

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

Uwagi:

• openclaw channels add --channel qqbot --token-file ... ustawia wyłącznie AppSecret; appId musi być już ustawiony w konfiguracji lub w QQBOT_APP_ID.
• clientSecret przyjmuje ciąg tekstowy w postaci jawnej, ścieżkę do pliku (clientSecretFile) albo strukturalny obiekt SecretRef.
• Starsze ciągi znaczników secretref:... / secretref-env:... są odrzucane dla clientSecret; zamiast nich użyj strukturalnego obiektu SecretRef.

Zasady dostępu

• allowFrom / groupAllowFrom określają, kto może rozmawiać z botem w kontekście C2C / grupowym. dmPolicy / groupPolicy (open | allowlist | disabled) sterują trybem egzekwowania zasad. Domyślną wartością dmPolicy staje się allowlist, gdy allowFrom zawiera konkretny wpis (bez symbolu wieloznacznego); w przeciwnym razie jest nią open. Domyślną wartością groupPolicy staje się allowlist, gdy groupAllowFrom lub allowFrom zawiera konkretny wpis; w przeciwnym razie jest nią open.
• Polecenia z ukośnikiem wymagające „Uwierzytelniania: lista dozwolonych” wymagają jawnego wpisu bez symbolu wieloznacznego w allowFrom (lub groupAllowFrom w przypadku wywołań grupowych), niezależnie od dmPolicy / groupPolicy — zobacz Polecenia z ukośnikiem.

Konfiguracja wielu kont

Uruchom wiele botów QQ w jednej instancji OpenClaw:

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

Każde konto ma odizolowane połączenie WebSocket, klienta API i pamięć podręczną tokenów, identyfikowane przez appId. Wiersze dziennika są oznaczane identyfikatorem konta właściciela, dzięki czemu diagnostyka pozostaje rozdzielona podczas uruchamiania kilku botów w jednym Gateway.

Dodaj drugiego bota za pomocą CLI:

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

Czaty grupowe

Obsługa grup korzysta z identyfikatorów OpenID grup QQ, a nie z nazw wyświetlanych. Dodaj bota do grupy, a następnie wspomnij o nim lub skonfiguruj grupę tak, aby działała bez wzmianki.

{  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["*"] ustawia wartości domyślne dla każdej grupy; konkretny wpis groups.GROUP_OPENID zastępuje te wartości domyślne dla jednej grupy. Ustawienia grup:

commandLevel przyjmuje następujące wartości:

Stare wpisy QQBot toolPolicy zostały wycofane. Uruchom openclaw doctor --fix, aby przenieść je do tools.

Tryby aktywacji to mention i always. requireMention: true odpowiada mention, a requireMention: false odpowiada always. Nadpisanie aktywacji na poziomie sesji, jeśli istnieje, ma pierwszeństwo przed konfiguracją.

Kolejka przychodząca jest oddzielna dla każdego uczestnika. Uczestnicy grupowi mają większy limit kolejki (50 zamiast 20 dla uczestników bezpośrednich); po zapełnieniu wiadomości autorstwa bota są usuwane przed wiadomościami ludzi, a serie zwykłych wiadomości grupowych są scalane w jedną turę z przypisanym autorstwem. Polecenia z ukośnikiem są wykonywane pojedynczo, niezależnie od wszelkich partii scalania.

Głos (STT / TTS)

STT i TTS obsługują konfigurację dwupoziomową z priorytetowym mechanizmem rezerwowym:

{  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" },            },          },        },      },    },  },}

Ustaw enabled: false dla dowolnej z tych funkcji, aby ją wyłączyć. Nadpisania TTS na poziomie konta mają ten sam kształt co messages.tts i są głęboko scalane z konfiguracją TTS kanału/globalną.

Domyślnie żądania STT przekraczają limit czasu po 60 sekundach. STT specyficzne dla Pluginu korzysta z nadpisania models.providers.<id>.timeoutSeconds wybranego dostawcy. STT audio frameworka korzysta kolejno z tools.media.audio.models[0].timeoutSeconds, tools.media.audio.timeoutSeconds, a następnie z nadpisania wybranego dostawcy.

Przychodzące załączniki głosowe QQ są udostępniane agentom jako metadane multimediów audio, natomiast surowe pliki głosowe nie trafiają do ogólnego MediaPaths. [[audio_as_voice]] w odpowiedzi w postaci zwykłego tekstu syntetyzuje TTS i wysyła natywną wiadomość głosową QQ, gdy TTS jest skonfigurowane.

Zachowanie przesyłania/transkodowania wychodzącego dźwięku można także dostosować za pomocą channels.qqbot.audioFormatPolicy:

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

Formaty docelowe

Polecenia z ukośnikiem

Wbudowane polecenia przechwytywane przed kolejką AI:

Dodaj ? do dowolnego polecenia, aby uzyskać pomoc dotyczącą użycia (na przykład /bot-upgrade ?).

Polecenia wymagające „Uwierzytelniania: lista dozwolonych” dodatkowo wymagają, aby openid nadawcy znajdował się na jawnej liście allowFrom bez symbolu wieloznacznego (groupAllowFrom ma pierwszeństwo dla poleceń wydawanych w grupie, a w razie braku wpisu używane jest allowFrom). Symbol wieloznaczny allowFrom: ["*"] zezwala na czat, ale nie na te polecenia. Uruchomienie jednego z nich poza prywatnym czatem lub bez upoważnienia zwraca wskazówkę zamiast po cichu odrzucać wiadomość.

/bot-me, /bot-version i /bot-upgrade są dostępne tylko w czatach prywatnych, ale nie wymagają listy dozwolonych — może je uruchomić każdy nadawca C2C.

Gdy zatwierdzenia wykonania QQ Bot korzystają z domyślnego mechanizmu rezerwowego w tym samym czacie, kliknięcia natywnych przycisków zatwierdzania podlegają tej samej jawnej liście dozwolonych poleceń bez symboli wieloznacznych. Aby przyznać dostęp wyłącznie do zatwierdzania bez szerszego dostępu do poleceń, skonfiguruj channels.qqbot.execApprovals.approvers. Natywne zatwierdzenia wykonania są domyślnie włączone.

Multimedia i pamięć masowa

• Przychodzące i wychodzące multimedia oraz multimedia mostu Gateway współdzielą jeden katalog główny danych w ~/.openclaw/media/qqbot (z uwzględnieniem OPENCLAW_HOME, gdy jest ustawiona), dzięki czemu wysyłane i pobierane pliki oraz pamięci podręczne transkodowania pozostają w jednym chronionym katalogu.
• Dostarczanie multimediów rozszerzonych do odbiorców C2C i grupowych odbywa się jedną ścieżką sendMedia. Pliki lokalne i bufory w pamięci o rozmiarze co najmniej 5 MiB korzystają z punktów końcowych QQ do przesyłania fragmentami; mniejsze dane oraz źródła w postaci zdalnych adresów URL lub Base64 korzystają z interfejsu API jednorazowego przesyłania.
• Jeśli aktualizacja na gorąco przerwie działanie Gateway przed zakończeniem zapisu openclaw.json, przy następnym uruchomieniu Plugin przywróci ostatnie znane wartości appId / clientSecret tego konta z wewnętrznej migawki (nigdy nie nadpisując celowej zmiany konfiguracji), dzięki czemu ponowne skanowanie kodu QR nie jest wymagane.

Rozwiązywanie problemów

• Gateway nie uruchamia się / brak wiadomości przychodzących: sprawdź, czy appId i clientSecret są poprawne oraz czy bot jest włączony na platformie QQ Open Platform. Brakujące dane uwierzytelniające powodują wyświetlenie komunikatu „QQBot nie jest skonfigurowany (brak appId lub clientSecret)”.
• Konfiguracja z --token-file nadal jest wyświetlana jako nieskonfigurowana: --token-file ustawia wyłącznie AppSecret. appId nadal musi być ustawione w konfiguracji lub w QQBOT_APP_ID.
• Serie odpowiedzi grupowych kolidują ze sobą: gdy kolejka danego uczestnika się zapełnia, kolejka przychodząca usuwa wiadomości utworzone przez boty przed wiadomościami od ludzi oraz scala serie zwykłych wiadomości grupowych (niebędących poleceniami) w jedną turę z przypisanym autorstwem, dzięki czemu zalew komunikatów botów nie powinien blokować wiadomości od ludzi.
• Wiadomości proaktywne nie docierają: QQ może blokować wiadomości inicjowane przez bota, jeśli użytkownik nie wchodził ostatnio z nim w interakcję.
• Głos nie jest transkrybowany: upewnij się, że STT jest skonfigurowane, a dostawca jest osiągalny.

Powiązane

• Parowanie
• Grupy
• Rozwiązywanie problemów z kanałami