Hermes-QQ-OneBot: messaging bridge for Hermes Agent

QQ platform adapter for Hermes Agent using OneBot v11, NapCat, Lagrange and LLOneBot

What Hermes-QQ-OneBot does

Hermes-QQ-OneBot is a Hermes Agent plugin that adds QQ as a messaging platform through the OneBot v11 protocol. The adapter runs a reverse WebSocket server, and a OneBot implementation such as NapCat connects to it, so no public IP or open port is required. The listed implementations are NapCat (preferred), Lagrange.OneBot and LLOneBot, with go-cqhttp marked as working but no longer maintained.

It handles private and group chats, @ mention detection, quoted replies and regex keyword triggers that wake the agent without an @. Long group replies can be merged into a forwarded message, and media is downloaded only when the agent is triggered, with a default 10MB limit per type. The agent can write CQ codes such as [CQ:image,file=...] in its replies, and two LLM tools, napcat_send_message and napcat_call_action, let it send messages and call OneBot APIs while the gateway runs. Configuration lives under platforms.napcat in ~/.hermes/config.yaml.

Key features

Reverse WebSocket connection from NapCat, Lagrange, LLOneBot or go-cqhttp
Private and group chat with @ mention detection and quoted replies
Regex keyword triggers that respond without an @
Merged forwarding for long group replies
On-demand media download with configurable size limits
napcat_send_message and napcat_call_action tools for the agent

When to use it

Chatting with Hermes Agent inside QQ groups and private chats
Letting the agent send images, files and voice messages to QQ using CQ codes
Having the agent read group history or recall messages through OneBot API calls

Who it is for: Hermes Agent users in the QQ ecosystem who run NapCat or another OneBot v11 implementation.

How it fits with Hermes Agent

It is built as a pure Hermes plugin that registers a platform adapter, installed with the Hermes plugin command and requiring no change to Hermes source code.

How to install Hermes-QQ-OneBot

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

hermes plugins install landamao/hermes-qq-onebot --enable

Requirements: A OneBot v11 implementation such as NapCat; the websockets package for a manual install

FAQ

What is Hermes-QQ-OneBot?

Hermes-QQ-OneBot is a plugin that connects Hermes Agent to QQ over the OneBot v11 protocol. It supports private and group chat, keyword triggers, media and agent-callable QQ tools.

How do I install Hermes-QQ-OneBot?

Run hermes plugins install landamao/hermes-qq-onebot --enable, then configure NapCat to connect to the adapter's reverse WebSocket. A manual route clones the repository into ~/.hermes/plugins/napcat and runs hermes gateway restart.

Which OneBot implementations does Hermes-QQ-OneBot support?

NapCat is preferred, and Lagrange.OneBot and LLOneBot are listed as compatible. go-cqhttp works but is marked as no longer maintained.