feat: add QQ Bot integration with Official API v2 and voice STT#7268
Closed
topcheer wants to merge 1 commit into
Closed
feat: add QQ Bot integration with Official API v2 and voice STT#7268topcheer wants to merge 1 commit into
topcheer wants to merge 1 commit into
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new QQ Bot messaging integration and wires it into the gateway/CLI tooling, including voice transcription support configuration, plus updates to toolset registration and platform routing.
Changes:
- Introduces
QQAdapterfor Official QQ Bot API v2 (WebSocket gateway inbound + REST outbound), with attachment handling and optional STT fallback. - Registers QQ across CLI setup/config/status, toolsets, scheduler delivery, channel directory, and
send_messagerouting. - Modifies gateway runner behavior around model/provider handling and command processing (notably
/yolo,/usage, and model routing plumbing).
Reviewed changes
Copilot reviewed 15 out of 16 changed files in this pull request and generated 20 comments.
Show a summary per file
| File | Description |
|---|---|
gateway/platforms/qq.py |
New QQ platform adapter implementation (gateway + REST + attachment/STT logic). |
gateway/run.py |
Registers QQ adapter and adjusts gateway runner command/model behavior. |
gateway/config.py |
Adds Platform.QQ and environment overrides for QQ credentials/home channel. |
gateway/platforms/__init__.py |
Exports QQAdapter alongside other adapters. |
hermes_cli/setup.py |
Adds interactive QQ setup flow (credentials + allowlist + STT prompts). |
hermes_cli/gateway.py |
Adds QQ platform entry and documents required env vars for gateway runner UI. |
hermes_cli/config.py |
Adds QQ env vars to known env key set used by config/.env tooling. |
hermes_cli/status.py |
Displays QQ status fields (App ID + home channel). |
hermes_cli/tools_config.py |
Adds QQ toolset mapping and platform enablement detection. |
tools/send_message_tool.py |
Adds QQ as a send_message target and implements _send_qq(). |
toolsets.py |
Adds hermes-qq toolset and includes it in hermes-gateway. |
cron/scheduler.py |
Adds QQ to cron delivery platform map. |
gateway/channel_directory.py |
Adds QQ to session-derived channel directory population. |
agent/prompt_builder.py |
Adds QQ-specific system prompt guidance for media sending. |
.gitignore |
Ignores .ggcode/. |
tests/gateway/test_qq.py |
Adds QQ tests (currently appear mismatched to the new adapter). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Implement QQ Bot adapter using Official QQ Bot API v2 (WebSocket Gateway + REST API) - Voice processing: prioritize QQ's built-in asr_refer_text, then voice_wav_url, then configurable STT - Unified attachment processing (images, voice, files) for all message types (C2C/group/guild/DM) - Configurable STT backend via config.yaml or QQ_STT_* environment variables - Add QQ to hermes setup gateway, hermes gateway menu, config, status, and toolsets - Add QQ platform integration: scheduler, channel directory, send_message_tool, cron support - Add tests for QQ adapter
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do?
Adds complete QQ Bot integration using the Official QQ Bot API v2. The adapter connects to QQ's WebSocket Gateway for inbound events and uses the REST API (
api.sgroup.qq.com) for outbound messages and media uploads.The implementation follows the same architecture as the OpenClaw qqbot plugin (
@openclaw/qqbot), the most battle-tested QQ Bot adapter in the ecosystem.Related Issue
N/A (new platform integration)
Type of Change
Changes Made
Core adapter
gateway/platforms/qq.py— NewQQAdapter(~1785 lines) using Official QQ Bot API v2gateway/platforms/__init__.py— QQAdapter import/exportgateway/config.py—Platform.QQenum + env override for Official API v2 credentialsgateway/run.py— QQ adapter registration in_get_adapter_for_platform()Voice STT
_process_attachments()— unified attachment processing for all message types (C2C/group/guild/DM)_stt_voice_attachment()— 3-tier fallback: QQasr_refer_text→voice_wav_url→ configurable STT_resolve_stt_config()/_call_stt()— configurable STT backend (OpenAI-compatible API)Platform integration
hermes_cli/setup.py— new_setup_qq()+_GATEWAY_PLATFORMSregistration +any_messaging+missing_homehermes_cli/gateway.py— QQ_PLATFORMSentry with STT configuration varshermes_cli/config.py—QQ_STT_*/QQ_ALLOWED_USERS/QQ_HOME_CHANNELenv varshermes_cli/status.py— QQ status displayhermes_cli/tools_config.py— QQ toolset configtools/send_message_tool.py— QQ send_message supporttoolsets.py—hermes-gatewayincludeshermes-qqcron/scheduler.py— QQ platform mapgateway/channel_directory.py— channel directory QQ supportagent/prompt_builder.py— QQ system promptTests
tests/gateway/test_qq.py— 27 unit testsDocumentation
website/docs/user-guide/messaging/qq.md— new QQ Bot setup guidewebsite/docs/user-guide/messaging/index.md— QQ added to comparison table, architecture diagram, toolsets table, nav linkswebsite/docs/reference/environment-variables.md— QQ env vars documentedcli-config.yaml.example— QQ added to supported platform keys and defaultsAGENTS.md— QQ added to platforms listHow to Test
hermes setup gateway— select QQ, enter App ID + App Secret from q.qq.comhermes gateway runpython -m pytest tests/gateway/test_qq.py -q— 27 tests passChecklist
Code
feat: add QQ Bot integration with Official API v2 and voice STT)pytest tests/gateway/test_qq.py -qand all tests pass (27 passed)Documentation & Housekeeping
docs/, docstrings)website/docs/user-guide/messaging/qq.md— new setup guidewebsite/docs/user-guide/messaging/index.md— comparison table, architecture, toolsets, navwebsite/docs/reference/environment-variables.md— QQ env varscli-config.yaml.example— QQ added to supported platform keys and defaultsAGENTS.md— QQ added to platforms list~/.hermessend_message)For New Skills
N/A (platform adapter, not a skill)