Hermes Agent QQ Plugin

What Hermes Agent QQ Plugin does

The plugin is adapted from OpenClaw's official QQ plugin and uses the official QQ Bot API instead of third-party frameworks such as NapCat or go-cqhttp. It supports text, voice, image and file messages in private (C2C) chat and in group chat with an @ mention, and text and images in channels. Voice from OGG, MP3 or WAV is converted to SILK, QQ's native format. Images can come from local files or HTTP URLs, files can be any format, and messages over 5000 characters are split automatically.

install.sh copies qq.py into Hermes's platform adapter directory, installs qq-botpy and pysilk into the Hermes virtual environment and patches the Hermes core files it needs. The patches are idempotent, so rerunning the script after a Hermes update is safe. You then set QQ_APP_ID and QQ_APP_SECRET in ~/.hermes/.env, enable the qq platform in config.yaml and restart the gateway. QQ_ALLOWED_USERS and QQ_ALLOW_ALL_USERS control who can talk to the bot, and QQ_HOME_CHANNEL sets where cron results and cross-platform messages go.

Key features

• Text, voice, image and file messages in QQ private and group chats
• Automatic OGG, MP3 and WAV to SILK voice conversion
• Long-message splitting above 5000 characters
• Allow-list or open access through QQ_ALLOWED_USERS and QQ_ALLOW_ALL_USERS
• Idempotent install script that can be rerun after Hermes updates

When to use it

• Chatting with Hermes Agent from QQ on a phone
• Sending Hermes documents and images in a QQ group conversation
• Receiving scheduled cron job results in a QQ chat

Who it is for: Hermes Agent users in China or elsewhere who use QQ and want it as a gateway platform.

How it fits with Hermes Agent

A messaging platform adapter built for the Hermes Agent gateway, which adds QQ next to the built-in platforms.

How to install Hermes Agent QQ Plugin

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

git clone https://github.com/shynloc/Hermes-Agent-QQ-Plugin.git
cd Hermes-Agent-QQ-Plugin
bash install.sh

Requirements: Hermes Agent v0.8.0+, Python 3.11+, ffmpeg, qq-botpy 1.2.1+, pysilk, and a QQ Bot Open Platform account with an AppID and AppSecret

Note: The installer patches Hermes core files, so run bash install.sh again after each Hermes update.

FAQ