bot QQ

QQ Bot terhubung ke OpenClaw melalui API QQ Bot resmi (Gateway WebSocket). Chat privat C2C dan sebutan @ dalam grup merupakan jenis chat utama, dengan media kaya (gambar, suara, video, berkas). Pesan saluran guild hanya mendukung teks dan gambar dari URL jarak jauh; suara, video, unggahan berkas, serta gambar lokal/Base64 tidak tersedia di saluran guild. Reaksi dan utas tidak didukung di mana pun.

Status: plugin resmi yang dapat diunduh.

Instalasi

openclaw plugins install @openclaw/qqbot

Penyiapan

1. Buka QQ Open Platform dan pindai kode QR dengan QQ di ponsel Anda untuk mendaftar / masuk.
2. Klik Create Bot untuk membuat bot QQ baru.
3. Temukan AppID dan AppSecret di halaman pengaturan bot, lalu salin keduanya.

4. Tambahkan saluran:

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

5. Mulai ulang Gateway.

Penyiapan interaktif:

openclaw channels add

Wizard juga menawarkan pengaitan melalui kode QR sebagai alternatif untuk mengetik AppID/AppSecret secara manual: pindai kode dengan aplikasi ponsel yang terhubung ke QQ Bot target untuk menyelesaikan pengaitan. OpenClaw menyimpan kredensial yang dikembalikan dalam cakupan konfigurasi akun.

Konfigurasi

Konfigurasi minimal:

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

Variabel lingkungan akun default (khusus akun tingkat teratas):

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

AppSecret berbasis berkas:

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

AppSecret SecretRef dari lingkungan:

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

Catatan:

• openclaw channels add --channel qqbot --token-file ... hanya menetapkan AppSecret; appId harus sudah ditetapkan dalam konfigurasi atau QQBOT_APP_ID.
• clientSecret menerima string teks biasa, jalur berkas (clientSecretFile), atau objek SecretRef terstruktur.
• String penanda lama secretref:... / secretref-env:... ditolak untuk clientSecret; gunakan objek SecretRef terstruktur sebagai gantinya.

Kebijakan akses

• allowFrom / groupAllowFrom membatasi siapa yang dapat mengobrol dengan bot dalam konteks C2C / grup. dmPolicy / groupPolicy (open | allowlist | disabled) mengendalikan mode penerapan. dmPolicy secara default menjadi allowlist setelah allowFrom memiliki entri konkret (bukan wildcard); jika tidak, nilainya open. groupPolicy secara default menjadi allowlist setelah groupAllowFrom atau allowFrom memiliki entri konkret; jika tidak, nilainya open.
• Perintah garis miring dengan "Autorisasi: daftar izin" memerlukan entri eksplisit bukan wildcard dalam allowFrom (atau groupAllowFrom untuk pemanggilan dari grup), terlepas dari dmPolicy / groupPolicy — lihat Perintah garis miring.

Penyiapan multiakun

Jalankan beberapa bot QQ dalam satu instans OpenClaw:

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

Setiap akun memiliki koneksi WebSocket, klien API, dan cache token yang terisolasi, dengan kunci appId. Baris log diberi tag ID akun pemilik agar diagnostik tetap dapat dipisahkan saat Anda menjalankan beberapa bot dalam satu Gateway.

Tambahkan bot kedua melalui CLI:

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

Chat grup

Dukungan grup menggunakan OpenID grup QQ, bukan nama tampilan. Tambahkan bot ke grup, lalu sebut bot tersebut atau konfigurasikan grup agar berjalan tanpa sebutan.

{  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["*"] menetapkan nilai default untuk setiap grup; entri konkret groups.GROUP_OPENID menimpa nilai default tersebut untuk satu grup. Pengaturan grup:

commandLevel menerima:

Entri toolPolicy QQBot lama telah dihentikan. Jalankan openclaw doctor --fix untuk memigrasikannya ke tools.

Mode aktivasi adalah mention dan always. requireMention: true dipetakan ke mention; requireMention: false dipetakan ke always. Penimpaan aktivasi tingkat sesi, jika ada, lebih diprioritaskan daripada konfigurasi.

Antrean masuk dibuat per rekan. Rekan grup mendapatkan batas antrean yang lebih besar (50 dibandingkan 20 untuk rekan langsung), mengeluarkan pesan buatan bot sebelum pesan manusia ketika penuh, dan menggabungkan rangkaian pesan grup biasa menjadi satu giliran dengan atribusi. Perintah garis miring dijalankan satu per satu, terpisah dari kelompok penggabungan apa pun.

Suara (STT / TTS)

STT dan TTS mendukung konfigurasi dua tingkat dengan fallback berdasarkan prioritas:

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

Tetapkan enabled: false pada salah satunya untuk menonaktifkannya. Penimpaan TTS tingkat akun menggunakan bentuk yang sama dengan messages.tts dan digabungkan secara mendalam di atas konfigurasi TTS saluran/global.

Permintaan STT secara default mengalami batas waktu setelah 60 detik. STT khusus Plugin menggunakan penimpaan models.providers.<id>.timeoutSeconds yang dipilih. STT audio kerangka kerja menggunakan tools.media.audio.models[0].timeoutSeconds, lalu tools.media.audio.timeoutSeconds, kemudian penimpaan penyedia yang dipilih.

Lampiran suara QQ yang masuk diekspos kepada agen sebagai metadata media audio, sementara berkas suara mentah tidak dimasukkan ke dalam MediaPaths generik. [[audio_as_voice]] dalam balasan teks biasa menyintesis TTS dan mengirim pesan suara QQ asli ketika TTS dikonfigurasi.

Perilaku unggah/transkode audio keluar juga dapat disesuaikan dengan channels.qqbot.audioFormatPolicy:

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

Format target

Perintah garis miring

Perintah bawaan yang dicegat sebelum antrean AI:

Tambahkan ? ke perintah apa pun untuk mendapatkan bantuan penggunaan (misalnya /bot-upgrade ?).

Perintah dengan "Autorisasi: daftar izin" juga mengharuskan openid pengirim tercantum dalam daftar allowFrom eksplisit bukan wildcard (groupAllowFrom lebih diprioritaskan untuk perintah yang dikeluarkan dari grup, dengan fallback ke allowFrom). Wildcard allowFrom: ["*"] mengizinkan chat, tetapi tidak mengizinkan perintah-perintah ini. Menjalankan salah satunya di luar chat privat atau tanpa otorisasi akan mengembalikan petunjuk, bukan mengabaikan pesan secara diam-diam.

/bot-me, /bot-version, dan /bot-upgrade hanya tersedia untuk percakapan privat, tetapi tidak memerlukan daftar izin — pengirim C2C mana pun dapat menjalankannya.

Saat persetujuan eksekusi QQ Bot menggunakan fallback percakapan yang sama secara default, klik tombol persetujuan native mengikuti daftar izin perintah eksplisit tanpa wildcard yang sama. Untuk memberikan akses khusus persetujuan tanpa akses perintah yang lebih luas, konfigurasikan channels.qqbot.execApprovals.approvers. Persetujuan eksekusi native diaktifkan secara default.

Media dan penyimpanan

• Media masuk, keluar, dan jembatan Gateway menggunakan satu direktori akar payload bersama di bawah ~/.openclaw/media/qqbot (mengikuti OPENCLAW_HOME jika ditetapkan), sehingga unggahan, unduhan, dan cache transkode tetap berada dalam satu direktori yang terlindungi.
• Pengiriman media kaya untuk target C2C dan grup melewati satu jalur sendMedia. Berkas lokal dan buffer dalam memori berukuran 5 MiB atau lebih menggunakan endpoint unggahan bertahap QQ; payload yang lebih kecil dan sumber URL jarak jauh/Base64 menggunakan API unggahan sekali jalan.
• Jika pemutakhiran langsung menginterupsi Gateway sebelum selesai menulis openclaw.json, Plugin memulihkan appId / clientSecret terakhir yang diketahui untuk akun tersebut dari snapshot internal pada proses mulai berikutnya (tanpa pernah menimpa perubahan konfigurasi yang disengaja), sehingga pemindaian ulang kode QR tidak diperlukan.

Pemecahan masalah

• Gateway tidak dimulai / tidak ada pesan masuk: pastikan appId dan clientSecret sudah benar serta bot diaktifkan di QQ Open Platform. Kredensial yang tidak ada ditampilkan sebagai "QQBot belum dikonfigurasi (appId atau clientSecret tidak ada)".
• Penyiapan dengan --token-file masih ditampilkan sebagai belum dikonfigurasi: --token-file hanya menetapkan AppSecret. appId tetap harus ditetapkan dalam konfigurasi atau QQBOT_APP_ID.
• Balasan grup beruntun saling bertabrakan: antrean masuk mengeluarkan pesan yang dibuat bot sebelum pesan manusia ketika antrean rekan penuh, serta menggabungkan rentetan pesan grup normal (bukan perintah) menjadi satu giliran yang disertai atribusi, sehingga banjir percakapan bot tidak akan menghambat pesan manusia.
• Pesan proaktif tidak diterima: QQ dapat memblokir pesan yang dimulai oleh bot jika pengguna belum berinteraksi baru-baru ini.
• Suara tidak ditranskripsikan: pastikan STT telah dikonfigurasi dan penyedianya dapat dijangkau.

Terkait

• Pemasangan
• Grup
• Pemecahan masalah saluran