mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-19 04:52:06 +00:00
fef1a41248
Cross-checked 75 docs pages under user-guide/messaging/, developer-guide/,
guides/, and integrations/ against the live registries and gateway code.
messaging/
- index.md: API Server toolset is hermes-api-server (was 'hermes (default)');
Google Chat slug is hermes-google_chat (underscore — plugin name uses _).
- google_chat.md: drop bogus 'pip install hermes-agent[google_chat]' (no such
extra); list the actual deps (google-cloud-pubsub, google-api-python-client,
google-auth, google-auth-oauthlib).
- qqbot.md: config namespace is platforms.qqbot (was platforms.qq, which is
silently ignored by the adapter); QQ_STT_BASE_URL is not read directly —
baseUrl lives under platforms.qqbot.extra.stt.
- teams-meetings.md: 'hermes teams-pipeline' is plugin-gated (teams_pipeline
plugin must be enabled), not a built-in subcommand.
- sms.md: example log line 0.0.0.0:8080 -> 127.0.0.1:8080 (default
SMS_WEBHOOK_HOST).
- open-webui.md: API_SERVER_* are env vars, not YAML keys — write them to
per-profile .env, not 'hermes config set' (same pattern fixed in
api-server.md last round). Also bumped example ports to 8650+ to dodge the
default webhook (8644)/wecom-callback (8645)/msgraph-webhook (8646)
collision.
developer-guide/
- architecture.md: tool/toolset counts (61/52 -> 70+/~28); LOC stamps for
run_agent.py, cli.py, hermes_cli/main.py, setup.py, mcp_tool.py,
gateway/run.py replaced with 'large file' to stop drifting.
- agent-loop.md: same LOC drift (~13,700 -> 'a large file (15k+ lines)').
- gateway-internals.md: '14+ external messaging platforms' -> '20+'; gateway
platform tree updated (qqbot is a sub-package, not qqbot.py; added
yuanbao.py, feishu_comment.py, msgraph_webhook.py); 'gateway/builtin_hooks/
(always active)' was wrong — it's an empty extension point and
_register_builtin_hooks() is a no-op stub.
- acp-internals.md: drop fictional 'message_callback' from the bridged-
callbacks list; clarify thinking_callback is currently set to None.
- provider-runtime.md: provider list was missing AWS Bedrock, Azure Foundry,
NVIDIA NIM, xAI, Arcee, GMI Cloud, StepFun, Qwen OAuth, Xiaomi, Ollama
Cloud, LM Studio, Tencent TokenHub. Fallback section described only the
legacy single-pair model — corrected to the canonical list-form
fallback_providers chain.
- environments.md: parsers list missing llama4_json and the deepseek_v31
alias; both register via @register_parser.
- browser-supervisor.md: drop reference to scripts/browser_supervisor_e2e.py
which doesn't exist in-repo.
- contributing.md: tinker-atropos is a git submodule — note that
'git submodule update --init' is required if cloning without
--recurse-submodules.
guides/
- operate-teams-meeting-pipeline.md: cron flags were all wrong — schedule is
positional (not --schedule), the script-only flag is --no-agent (not
--script-only), and there's no --command flag. Replaced with a real example
that creates the script under ~/.hermes/scripts/ and uses the actual flags.
Also replaced fictional 'hermes cron show <name>' with 'hermes cron status'.
- automation-templates.md: 'cron create --skills "a,b"' doesn't work —
the flag is --skill (singular, repeatable). Fixed all 5 occurrences via AST
rewrite.
- minimax-oauth.md: 'hermes auth add minimax-oauth --region cn' silently
fails because --region isn't registered on the auth-add argparse spec.
Pointed users at the minimax-cn provider (or MINIMAX_CN_API_KEY env) for
China-region access.
- cron-script-only.md: 'hermes send' is fictional — replaced the comparison-
table mention with a webhook-subscription pointer; also fixed the dead link
to /guides/pipe-script-output (page doesn't exist).
- cron-troubleshooting.md: 'hermes serve' isn't a real subcommand. Pointed
at 'hermes gateway' (foreground) / 'hermes gateway start' (service).
- local-ollama-setup.md: 'agent.api_timeout' is not a config key. The right
knob is the HERMES_API_TIMEOUT env var.
- python-library.md: run_conversation() return dict has only final_response
and messages — task_id is stored on the agent instance, not echoed back.
- use-mcp-with-hermes.md: '--args /c "npx -y …"' wraps the npx command in
one quoted string, so cmd.exe gets a single arg instead of the multi-token
command line it needs. Removed the surrounding quotes — argparse nargs='*'
collects each token correctly.
integrations/
- providers.md: Bedrock guardrail YAML keys were 'id'/'version' (don't exist);
actual keys are guardrail_identifier/guardrail_version (matches DEFAULT_CONFIG
and the run_agent.py reader). GMI default base URL (api.gmi.ai/v1 ->
api.gmi-serving.com/v1) and portal URL (inference.gmi.ai -> www.gmicloud.ai)
refreshed. Fallback section rewritten to lead with the canonical
fallback_providers list form (was leading with the legacy fallback_model
single dict); supported-providers list extended to include azure-foundry,
alibaba-coding-plan, lmstudio.
index.md
- '68 built-in tools' -> '70+'; '15+ platforms' was both inconsistent with
integrations/index.md ('19+') and undercounted — bumped to 20+ and added
Weixin/QQ Bot/Yuanbao/Google Chat to the list.
Validation: 'npm run build' clean (exit 0); broken-link count unchanged at
155 (same as round-1 post-skill-regen baseline). 24 files, +132/-89.
123 lines
4.5 KiB
Markdown
123 lines
4.5 KiB
Markdown
# QQ Bot
|
|
|
|
Connect Hermes to QQ via the **Official QQ Bot API (v2)** — supporting private (C2C), group @-mentions, guild, and direct messages with voice transcription.
|
|
|
|
## Overview
|
|
|
|
The QQ Bot adapter uses the [Official QQ Bot API](https://bot.q.qq.com/wiki/develop/api-v2/) to:
|
|
|
|
- Receive messages via a persistent **WebSocket** connection to the QQ Gateway
|
|
- Send text and markdown replies via the **REST API**
|
|
- Download and process images, voice messages, and file attachments
|
|
- Transcribe voice messages using Tencent's built-in ASR or a configurable STT provider
|
|
|
|
## Prerequisites
|
|
|
|
1. **QQ Bot Application** — Register at [q.qq.com](https://q.qq.com):
|
|
- Create a new application and note your **App ID** and **App Secret**
|
|
- Enable the required intents: C2C messages, Group @-messages, Guild messages
|
|
- Configure your bot in sandbox mode for testing, or publish for production
|
|
|
|
2. **Dependencies** — The adapter requires `aiohttp` and `httpx`:
|
|
```bash
|
|
pip install aiohttp httpx
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Interactive setup
|
|
|
|
```bash
|
|
hermes gateway setup
|
|
```
|
|
|
|
Select **QQ Bot** from the platform list and follow the prompts.
|
|
|
|
### Manual configuration
|
|
|
|
Set the required environment variables in `~/.hermes/.env`:
|
|
|
|
```bash
|
|
QQ_APP_ID=your-app-id
|
|
QQ_CLIENT_SECRET=your-app-secret
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Description | Default |
|
|
|---|---|---|
|
|
| `QQ_APP_ID` | QQ Bot App ID (required) | — |
|
|
| `QQ_CLIENT_SECRET` | QQ Bot App Secret (required) | — |
|
|
| `QQBOT_HOME_CHANNEL` | OpenID for cron/notification delivery | — |
|
|
| `QQBOT_HOME_CHANNEL_NAME` | Display name for home channel | `Home` |
|
|
| `QQ_ALLOWED_USERS` | Comma-separated user OpenIDs for DM access | open (all users) |
|
|
| `QQ_GROUP_ALLOWED_USERS` | Comma-separated group OpenIDs for group access | — |
|
|
| `QQ_ALLOW_ALL_USERS` | Set to `true` to allow all DMs | `false` |
|
|
| `QQ_PORTAL_HOST` | Override the QQ portal host (set to `sandbox.q.qq.com` for sandbox routing) | `q.qq.com` |
|
|
| `QQ_STT_API_KEY` | API key for voice-to-text provider | — |
|
|
| `QQ_STT_BASE_URL` | (Not read directly — set `platforms.qqbot.extra.stt.baseUrl` in `config.yaml` instead) | n/a |
|
|
| `QQ_STT_MODEL` | STT model name | `glm-asr` |
|
|
|
|
## Advanced Configuration
|
|
|
|
For fine-grained control, add platform settings to `~/.hermes/config.yaml`:
|
|
|
|
```yaml
|
|
platforms:
|
|
qqbot:
|
|
enabled: true
|
|
extra:
|
|
app_id: "your-app-id"
|
|
client_secret: "your-secret"
|
|
markdown_support: true # enable QQ markdown (msg_type 2). Config-only; no env-var equivalent.
|
|
dm_policy: "open" # open | allowlist | disabled
|
|
allow_from:
|
|
- "user_openid_1"
|
|
group_policy: "open" # open | allowlist | disabled
|
|
group_allow_from:
|
|
- "group_openid_1"
|
|
stt:
|
|
provider: "zai" # zai (GLM-ASR), openai (Whisper), etc.
|
|
baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4"
|
|
apiKey: "your-stt-key"
|
|
model: "glm-asr"
|
|
```
|
|
|
|
## Voice Messages (STT)
|
|
|
|
Voice transcription works in two stages:
|
|
|
|
1. **QQ built-in ASR** (free, always tried first) — QQ provides `asr_refer_text` in voice message attachments, which uses Tencent's own speech recognition
|
|
2. **Configured STT provider** (fallback) — If QQ's ASR doesn't return text, the adapter calls an OpenAI-compatible STT API:
|
|
|
|
- **Zhipu/GLM (zai)**: Default provider, uses `glm-asr` model
|
|
- **OpenAI Whisper**: Set `QQ_STT_BASE_URL` and `QQ_STT_MODEL`
|
|
- Any OpenAI-compatible STT endpoint
|
|
|
|
## Troubleshooting
|
|
|
|
### Bot disconnects immediately (quick disconnect)
|
|
|
|
This usually means:
|
|
- **Invalid App ID / Secret** — Double-check your credentials at q.qq.com
|
|
- **Missing permissions** — Ensure the bot has the required intents enabled
|
|
- **Sandbox-only bot** — If the bot is in sandbox mode, it can only receive messages from QQ's sandbox test channel
|
|
|
|
### Voice messages not transcribed
|
|
|
|
1. Check if QQ's built-in `asr_refer_text` is present in the attachment data
|
|
2. If using a custom STT provider, verify `QQ_STT_API_KEY` is set correctly
|
|
3. Check gateway logs for STT error messages
|
|
|
|
### Messages not delivered
|
|
|
|
- Verify the bot's **intents** are enabled at q.qq.com
|
|
- Check `QQ_ALLOWED_USERS` if DM access is restricted
|
|
- For group messages, ensure the bot is **@mentioned** (group policy may require allowlisting)
|
|
- Check `QQBOT_HOME_CHANNEL` for cron/notification delivery
|
|
|
|
### Connection errors
|
|
|
|
- Ensure `aiohttp` and `httpx` are installed: `pip install aiohttp httpx`
|
|
- Check network connectivity to `api.sgroup.qq.com` and the WebSocket gateway
|
|
- Review gateway logs for detailed error messages and reconnect behavior
|