mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-04-25 00:51:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
hermes-agent/website/docs/user-guide/messaging/qqbot.md
Teknium 54e0eb24c0
docs: correctness audit — fix wrong values, add missing coverage (#11972) 
Comprehensive audit of every reference/messaging/feature doc page against the
live code registries (PROVIDER_REGISTRY, OPTIONAL_ENV_VARS, COMMAND_REGISTRY,
TOOLSETS, tool registry, on-disk skills). Every fix was verified against code
before writing.

### Wrong values fixed (users would paste-and-fail)

- reference/environment-variables.md:
  - DASHSCOPE_BASE_URL default was `coding-intl.dashscope.aliyuncs.com/v1` \u2192
    actual `dashscope-intl.aliyuncs.com/compatible-mode/v1`.
  - MINIMAX_BASE_URL and MINIMAX_CN_BASE_URL defaults were `/v1` \u2192 actual
    `/anthropic` (Hermes calls MiniMax via its Anthropic Messages endpoint).
- reference/toolsets-reference.md MCP example used the non-existent nested
  `mcp: servers:` key \u2192 real key is the flat `mcp_servers:`.
- reference/skills-catalog.md listed ~20 bundled skills that no longer exist
  on disk (all moved to `optional-skills/`). Regenerated the whole bundled
  section from `skills/**/SKILL.md` \u2014 79 skills, accurate paths and names.
- messaging/slack.md ":::info" callout claimed Slack has no
  `free_response_channels` equivalent; both the env var and the yaml key are
  in fact read.
- messaging/qqbot.md documented `QQ_MARKDOWN_SUPPORT` as an env var, but the
  adapter only reads `extra.markdown_support` from config.yaml. Removed the
  env var row and noted config-only nature.
- messaging/qqbot.md `hermes setup gateway` \u2192 `hermes gateway setup`.

### Missing coverage added

- Providers: AWS Bedrock and Qwen Portal (qwen-oauth) \u2014 both in
  PROVIDER_REGISTRY but undocumented everywhere. Added sections to
  integrations/providers.md, rows to quickstart.md and fallback-providers.md.
- integrations/providers.md "Fallback Model" provider list now includes
  gemini, google-gemini-cli, qwen-oauth, xai, nvidia, ollama-cloud, bedrock.
- reference/cli-commands.md `--provider` enum and HERMES_INFERENCE_PROVIDER
  enum in env-vars now include the same set.
- reference/slash-commands.md: added `/agents` (alias `/tasks`) and `/copy`.
  Removed duplicate rows for `/snapshot`, `/fast` (\u00d72), `/debug`.
- reference/tools-reference.md: fixed "47 built-in tools" \u2192 52. Added
  `feishu_doc` and `feishu_drive` toolset sections.
- reference/toolsets-reference.md: added `feishu_doc` / `feishu_drive` core
  rows + all missing `hermes-<platform>` toolsets in the platform table
  (bluebubbles, dingtalk, feishu, qqbot, wecom, wecom-callback, weixin,
  homeassistant, webhook, gateway). Fixed the `debugging` composite to
  describe the actual `includes=[...]` mechanism.
- reference/optional-skills-catalog.md: added `fitness-nutrition`.
- reference/environment-variables.md: added NOUS_BASE_URL,
  NOUS_INFERENCE_BASE_URL, NVIDIA_API_KEY/BASE_URL, OLLAMA_API_KEY/BASE_URL,
  XAI_API_KEY/BASE_URL, MISTRAL_API_KEY, AWS_REGION/AWS_PROFILE,
  BEDROCK_BASE_URL, HERMES_QWEN_BASE_URL, DISCORD_ALLOWED_CHANNELS,
  DISCORD_PROXY, TELEGRAM_REPLY_TO_MODE, MATRIX_DEVICE_ID, MATRIX_REACTIONS,
  QQBOT_HOME_CHANNEL_NAME, QQ_SANDBOX.
- messaging/discord.md: documented DISCORD_ALLOWED_CHANNELS, DISCORD_PROXY,
  HERMES_DISCORD_TEXT_BATCH_DELAY_SECONDS and HERMES_DISCORD_TEXT_BATCH_SPLIT
  _DELAY_SECONDS (all actively read by the adapter).
- messaging/matrix.md: documented MATRIX_REACTIONS (default true).
- messaging/telegram.md: removed the redundant second Webhook Mode section
  that invented a `telegram.webhook_mode: true` yaml key the adapter does
  not read.
- user-guide/features/hooks.md: added `on_session_finalize` and
  `on_session_reset` (both emitted via invoke_hook but undocumented).
- user-guide/features/api-server.md: documented GET /health/detailed, the
  `/api/jobs/*` CRUD surface, POST /v1/runs, and GET /v1/runs/{id}/events
  (10 routes that were live but undocumented).
- user-guide/features/fallback-providers.md: added `approval` and
  `title_generation` auxiliary-task rows; added gemini, bedrock, qwen-oauth
  to the supported-providers table.
- user-guide/features/tts.md: "seven providers" \u2192 "eight" (post-xAI add
  oversight in #11942).
- user-guide/configuration.md: TTS provider enum gains `xai` and `gemini`;
  yaml example block gains `mistral:`, `gemini:`, `xai:` subsections.
  Auxiliary-provider enum now enumerates all real registry entries.
- reference/faq.md: stale AIAgent/config examples bumped from
  `nous/hermes-3-llama-3.1-70b` and `claude-sonnet-4.6` to
  `claude-opus-4.7`.

### Docs-site integrity

- guides/build-a-hermes-plugin.md referenced two nonexistent hooks
  (`pre_api_request`, `post_api_request`). Replaced with the real
  `on_session_finalize` / `on_session_reset` entries.
- messaging/open-webui.md and features/api-server.md had pre-existing
  broken links to `/docs/user-guide/features/profiles` (actual path is
  `/docs/user-guide/profiles`). Fixed.
- reference/skills-catalog.md had one `<1%` literal that MDX parsed as a
  JSX tag. Escaped to `&lt;1%`.

### False positives filtered out (not changed, verified correct)

- `/set-home` is a registered alias of `/sethome` \u2014 docs were fine.
- `hermes setup gateway` is valid syntax (`hermes setup \<section\>`);
  changed in qqbot.md for cross-doc consistency, not as a bug fix.
- Telegram reactions "disabled by default" matches code (default `"false"`).
- Matrix encryption "opt-in" matches code (empty env default \u2192 disabled).
- `pre_api_request` / `post_api_request` hooks do NOT exist in current code;
  documented instead the real `on_session_finalize` / `on_session_reset`.
- SIGNAL_IGNORE_STORIES is already in env-vars.md (subagent missed it).

Validation:
- `docusaurus build` \u2014 passes (only pre-existing nix-setup anchor warning).
- `ascii-guard lint docs` \u2014 124 files, 0 errors.
- 22 files changed, +317 / \u2212158.
2026-04-18 01:45:48 -07:00

4.4 KiB
Raw Blame History

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 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:

    • 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:

    pip install aiohttp httpx

Configuration

Interactive setup

hermes gateway setup

Select QQ Bot from the platform list and follow the prompts.

Manual configuration

Set the required environment variables in ~/.hermes/.env:

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_ALLOW_ALL_USERS Set to true to allow all DMs false
QQ_SANDBOX Route requests to the QQ sandbox gateway for development testing false
QQ_STT_API_KEY API key for voice-to-text provider —
QQ_STT_BASE_URL Base URL for STT provider https://open.bigmodel.cn/api/coding/paas/v4
QQ_STT_MODEL STT model name glm-asr

Advanced Configuration

For fine-grained control, add platform settings to ~/.hermes/config.yaml:

platforms:
  qq:
    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