Connect Hermes to QQ with the Official Bot API

The QQ adapter uses the official QQ Bot API v2. It receives C2C, group @-messages, guild messages, and direct messages over QQ's persistent gateway, then sends text or Markdown through the REST API.

Prepare the QQ application

Register a bot at QQ's developer portal, keep its App ID and secret private, and enable only the intents required by the chosen chat types. Sandbox mode is the safest first test because unpublished bots cannot receive arbitrary production traffic.

Run hermes gateway setup and select QQ Bot. Configure DM and group policy separately: open, allowlist, or disabled. For scheduled delivery, set a known home-channel OpenID only after a real message identifies the correct destination.

Voice handling first uses QQ's built-in recognition text when available. A configured OpenAI-compatible speech-to-text provider can serve as fallback; it should not be treated as required for ordinary text operation.

Setup checklist

Create a QQ Bot application and copy credentials securely.
Enable C2C, group, or guild intents only as needed.
Begin in sandbox mode with known testers.
Configure explicit DM and group policies.
Require group @mentions where the platform expects them.
Add fallback speech recognition only after text messaging works.

Pitfalls

An immediate disconnect commonly means bad credentials, missing intents, or a sandbox-only destination. DM and group allowlists use different identifiers. A configured speech model cannot recover voice audio that the adapter failed to download. Cron delivery fails when the home-channel OpenID is absent or copied from the wrong chat type.

Verification steps

Start the gateway and confirm the QQ WebSocket stays connected.
Send one sandbox C2C message and inspect the reply.
Test a group message both with and without the required mention.
Send one image and one voice note; verify the supported content is resolved.
Trigger a harmless notification to the configured home channel.

Use the official QQ Bot guide for current intents, policy keys, endpoints, and speech-to-text options.