QQ Bot — AI in QQ

Imagine your favorite group chat suddenly has a super-smart friend who can answer questions, summarize voice messages, and even send formatted replies — that’s exactly what Hermes Agent brings to QQ.

What Is This?

Hermes Agent is an open-source framework that lets you connect AI assistants to messaging platforms. The QQ Bot adapter is the bridge between Hermes and QQ’s official bot API. It listens for messages (private chats, group @-mentions, guild channels) and responds automatically — no coding required beyond setup.

How It Works (in Plain Terms)

Think of it like setting up a new phone:

1. Get a bot identity – You register your bot at q.qq.com and receive an App ID and App Secret (like a username and password for your bot).
2. Connect the wires – Hermes opens a persistent WebSocket connection to QQ’s gateway, so it hears messages instantly.
3. Teach it to listen – You decide which conversations it can join: private DMs, group mentions, or guild channels.
4. Let it talk back – When someone sends a message, Hermes processes it and replies with text or rich markdown.

Step-by-Step Setup

1. Install the dependencies

pip install aiohttp httpx

2. Configure your bot (easiest way)

hermes gateway setup

Select QQ Bot and follow the prompts. It will ask for your App ID and Secret.

3. Manual configuration (if you prefer)

Create or edit ~/.hermes/.env:

QQ_APP_ID=your-app-id
QQ_CLIENT_SECRET=your-app-secret

That’s the minimum. For more control, edit ~/.hermes/config.yaml:

platforms:
  qqbot:
    enabled: true
    extra:
      markdown_support: true
      dm_policy: "open"   # open | allowlist | disabled
      group_policy: "open"

Cool Feature: Voice Messages

QQ gives you free transcription (Tencent’s ASR) for every voice message. If that fails, Hermes can fall back to a custom STT provider like GLM-ASR or OpenAI Whisper. This means your bot can “hear” voice notes and reply with text summaries.

Security Settings You Should Know

• QQ_ALLOWED_USERS – restrict DMs to specific OpenIDs (default: everyone)
• QQ_GROUP_ALLOWED_USERS – restrict group access to specific group OpenIDs
• dm_policy / group_policy – set to "allowlist" for strict control, or "disabled" to turn off that channel entirely

Summary & Practical Tip

Connecting Hermes to QQ is like giving your group chat a personal assistant — it takes about 10 minutes of setup, and then you can customize everything from who can talk to it, to whether it supports markdown or voice transcription.

My tip for beginners: Start in sandbox mode (set QQ_PORTAL_HOST=sandbox.q.qq.com). Test with your own account first, then gradually open it up to friends. And always set QQ_ALLOWED_USERS to your own OpenID before going public — you don’t want strangers chatting with your bot on day one.

Once it’s live, try asking your bot to summarize a long voice message or format a quick announcement — that’s where the magic really shows.