hermes_qq

What hermes_qq does

hermes_qq is a standalone bridge that connects QQ to Hermes Agent through NapCat and the OneBot v11 WebSocket protocol. It is a separate Node.js service, so it does not modify Hermes core and does not depend on the OpenClaw plugin system. QQ login stays with NapCat. The README presents it as a first stable layer that is to be extended toward production use.

The bridge turns QQ messages into Hermes or OpenAI-compatible /v1/responses requests, keeps session continuity with the X-Hermes-Session-Id header, and lists models from /v1/models so the /model command can switch them. It supports group triggers by @, reply or keyword, group and user whitelists, admin limits and a user blacklist, cleans Markdown into QQ-friendly plain text and splits long messages. Basic commands are /ping, /help, /model, /new and /reset, and a health endpoint runs on port 8303.

Key features

• OneBot v11 WebSocket connection compatible with NapCat
• Calls Hermes or any OpenAI-compatible /v1/responses endpoint
• Session continuity through the X-Hermes-Session-Id header
• Group triggers by @, reply or keyword
• Group and user whitelists, admin restriction and blacklist
• Markdown cleanup and long message splitting for QQ

When to use it

• Putting a Hermes Agent assistant into a QQ group with controlled access
• Switching models from chat with the /model command
• Starting a fresh conversation with /new or /reset

Who it is for: Hermes Agent users who want a QQ bot front end and already run NapCat.

How it fits with Hermes Agent

It is built for Hermes Agent and talks to its OpenAI-compatible API from outside, leaving Hermes core untouched.

How to install hermes_qq

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

cp .env.example .env
npm install
npm start

Requirements: Node.js and npm, a NapCat instance for QQ login, and a reachable Hermes or OpenAI-compatible API

FAQ