hermes-napcat: messaging bridge for Hermes Agent

QQ adapter for Hermes Agent using NapCat's OneBot 11 reverse WebSocket, with group management tools

What hermes-napcat does

The adapter connects Hermes to QQ through NapCat's OneBot 11 reverse WebSocket. In groups the agent responds to an @mention, and in private chats to a direct message. Group sessions are shared, so the whole group has one context and sender names are prefixed automatically, and quoted messages carry their content into the prompt. Media support covers images, voice converted to WAV through ffmpeg, video and file upload and download.

It adds 48 QQ tools for messaging, group management, files, OCR and reactions. An admin list restricts management commands such as muting, kicking and setting admins to configured QQ numbers, and destructive operations require confirmation. If the admin list is empty, every user can call any tool. The hermes-napcat setup wizard patches Hermes Agent, writes the NapCat config, updates ~/.hermes/config.yaml and asks for your QQ number and admins, and the --with-napcat flag also downloads NapCat. The README is available in English and Chinese.

Key features

Group chats with @mention and private direct messages
Shared group sessions with sender names prefixed automatically
48 QQ tools for messaging, group management, files, OCR and reactions
Admin list that restricts management commands, with confirmation for destructive actions
Image, voice, video and file support
Interactive setup wizard, with an option to install NapCat

When to use it

Running a Hermes assistant inside a QQ group
Moderating a QQ group through an agent with admin-only controls
Letting the agent read quoted messages and images in QQ conversations

Who it is for: QQ users who want to talk to a Hermes agent from their QQ app.

How it fits with Hermes Agent

A platform adapter for the Hermes gateway that registers a napcat platform in ~/.hermes/config.yaml, with its own toolset alongside hermes-cli.

How to install hermes-napcat

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

pip install hermes-napcat
hermes-napcat setup

Requirements: Python 3.11+, Hermes Agent (source install), NapCat with HTTP API and reverse WebSocket enabled, aiohttp 3.9 or newer, and optionally ffmpeg for voice transcription

Note: The setup wizard patches Hermes Agent, which must be a source install, and the repository has no license file.

FAQ

What is hermes-napcat?

hermes-napcat is an adapter that connects Hermes Agent to QQ through NapCat's OneBot 11 reverse WebSocket. It supports groups, direct messages, media and 48 QQ tools.

How do I install hermes-napcat?

Run pip install hermes-napcat, then hermes-napcat setup. The wizard patches Hermes Agent, writes the NapCat config and updates ~/.hermes/config.yaml.

What do I need to run hermes-napcat?

You need Python 3.11+, a source install of Hermes Agent, NapCat with its HTTP API and reverse WebSocket enabled, and aiohttp 3.9 or newer. ffmpeg is optional and used for voice.