Bot QQ

​

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 pada halaman pengaturan bot lalu salin keduanya.

4. Tambahkan kanal:

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

5. Mulai ulang Gateway.

​

Ketahanan pesan masuk

openclaw channels add

​

Konfigurasi

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

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

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

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

• 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 file (clientSecretFile), atau objek SecretRef terstruktur.
• String penanda lama secretref:... / secretref-env:... ditolak untuk clientSecret; gunakan objek SecretRef terstruktur sebagai gantinya.

​

Streaming

{
  channels: {
    qqbot: {
      streaming: {
        mode: "partial", // streaming blok: "partial" (default) atau "off"
        nativeTransport: true, // gunakan API stream_messages C2C resmi QQ untuk DM
      },
    },
  },
}

• streaming.mode: "off" menonaktifkan streaming blok untuk akun.
• streaming.nativeTransport: true melakukan streaming balasan C2C (DM) melalui API resmi stream_messages milik QQ; target grup/kanal tidak terpengaruh.
• Skalar lama streaming: true|false dan kunci streaming.c2cStreamApi dimigrasikan ke bentuk ini melalui openclaw doctor --fix.
• /bot-streaming on|off mengaktifkan atau menonaktifkan konfigurasi yang sama dari DM.

​

Kebijakan akses

• allowFrom / groupAllowFrom membatasi siapa yang dapat mengobrol dengan bot dalam konteks C2C / grup. dmPolicy / groupPolicy (open | allowlist | disabled) mengontrol mode penerapan. dmPolicy ditetapkan secara default ke allowlist setelah allowFrom memiliki entri konkret (bukan wildcard), jika tidak maka open. groupPolicy ditetapkan secara default ke allowlist setelah groupAllowFrom atau allowFrom memiliki entri konkret, jika tidak maka open.
• Perintah garis miring “Auth: allowlist” memerlukan entri eksplisit bukan wildcard dalam allowFrom (atau groupAllowFrom untuk pemanggilan grup), terlepas dari dmPolicy / groupPolicy — lihat Perintah garis miring.

​

Penyiapan multiakun

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

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

​

Chat grup

{
  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: "Buat balasan tetap singkat dan operasional.",
        },
      },
    },
  },
}

​

Suara (STT / TTS)

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

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

​

Format target

​

Perintah garis miring

​

Media dan penyimpanan

• Media masuk, keluar, dan jembatan Gateway berbagi satu root payload di bawah ~/.openclaw/media/qqbot (mengikuti OPENCLAW_HOME jika ditetapkan), sehingga unggahan, unduhan, dan cache transkode tetap berada di dalam satu direktori yang terlindungi.
• Pengiriman media kaya untuk target C2C dan grup melewati satu jalur sendMedia. Berkas lokal dan buffer dalam memori sebesar 5 MiB atau lebih menggunakan endpoint unggahan bertahap QQ; payload yang lebih kecil serta sumber URL jarak jauh/Base64 menggunakan API unggahan sekali jalan.
• Jika peningkatan langsung menginterupsi Gateway sebelum selesai menulis openclaw.json, plugin memulihkan appId / clientSecret terakhir yang diketahui untuk akun tersebut dari snapshot internal saat dimulai 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 dan 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 menunjukkan belum dikonfigurasi: --token-file hanya menetapkan AppSecret. appId tetap harus ditetapkan dalam konfigurasi atau QQBOT_APP_ID.
• Balasan grup bertubi-tubi bertabrakan: antrean masuk mengeluarkan pesan yang dibuat bot sebelum pesan manusia ketika antrean rekan penuh, dan menggabungkan rentetan pesan grup normal (bukan perintah) menjadi satu giliran dengan atribusi, sehingga banjir percakapan bot tidak akan menghambat pesan manusia.
• Pesan proaktif tidak diterima: QQ mungkin memblokir pesan yang dimulai bot jika pengguna tidak berinteraksi baru-baru ini.
• Suara tidak ditranskripsikan: pastikan STT dikonfigurasi dan penyedia dapat dijangkau.

​

Terkait

• Pemasangan
• Grup
• Pemecahan masalah saluran