QQ bot

​

Bundled plugin

​

Setup

1. Go to the QQ Open Platform and scan the QR code with your phone QQ to register / log in.
2. Click Create Bot to create a new QQ bot.
3. Find AppID and AppSecret on the bot’s settings page and copy them.

AppSecret is not stored in plaintext — if you leave the page without saving it, you’ll have to regenerate a new one.

4. Add the channel:

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

5. Restart the Gateway.

fluffbuzz channels add
fluffbuzz configure --section channels

​

Configure

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

• Env fallback applies to the default QQ Bot account only.
• fluffbuzz channels add --channel qqbot --token-file ... provides the AppSecret only; the AppID must already be set in config or QQBOT_APP_ID.
• clientSecret also accepts SecretRef input, not just a plaintext string.

​

Multi-account setup

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

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

​

Voice (STT / TTS)

{
  channels: {
    qqbot: {
      stt: {
        provider: "your-provider",
        model: "your-stt-model",
      },
      tts: {
        provider: "your-provider",
        model: "your-tts-model",
        voice: "your-voice",
      },
    },
  },
}

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

​

Target formats

Each bot has its own set of user OpenIDs. An OpenID received by Bot A cannot be used to send messages via Bot B.

​

Slash commands

​

Engine architecture

• Each account owns an isolated resource stack (WebSocket connection, API client, token cache, media storage root) keyed by appId. Accounts never share inbound/outbound state.
• The multi-account logger tags log lines with the owning account so diagnostics stay separable when you run several bots under one gateway.
• Inbound, outbound, and gateway bridge paths share a single media payload root under ~/.fluffbuzz/media, so uploads, downloads, and transcode caches land under one guarded directory instead of a per-subsystem tree.
• Credentials can be backed up and restored as part of standard FluffBuzz credential snapshots; the engine re-attaches each account’s resource stack on restore without requiring a fresh QR-code pair.

​

QR-code onboarding

1. Run the QQ Bot setup path (for example fluffbuzz channels add --channel qqbot) and pick the QR-code flow when prompted.
2. Scan the generated QR code with the phone app tied to the target QQ Bot.
3. Approve the pairing on the phone. FluffBuzz persists the returned credentials into credentials/ under the right account scope.

​

Troubleshooting

• Bot replies “gone to Mars”: credentials not configured or Gateway not started.
• No inbound messages: verify appId and clientSecret are correct, and the bot is enabled on the QQ Open Platform.
• Setup with --token-file still shows unconfigured: --token-file only sets the AppSecret. You still need appId in config or QQBOT_APP_ID.
• Proactive messages not arriving: QQ may intercept bot-initiated messages if the user hasn’t interacted recently.
• Voice not transcribed: ensure STT is configured and the provider is reachable.

​

Related

• Pairing
• Groups
• Channel troubleshooting