QQ 機器人

通過 官方 QQ 機器人 API (v2) 將 Hermes 連接到 QQ —— 支持私聊 (C2C)、群聊 @提及、頻道消息以及帶有語音轉文字的直連消息。

概述

通過與 QQ 網關的持久 WebSocket 連接接收消息
通過 REST API 發送文本和 Markdown 回覆
下載並處理圖片、語音消息和文件附件
使用騰訊內置的 ASR 或可配置的 STT 提供商轉錄語音消息

前提條件

QQ 機器人應用 — 在 q.qq.com 註冊：
- 創建新應用並記錄您的 App ID 和 App Secret
- 啟用所需的意圖（Intents）：C2C 消息、群聊 @消息、頻道消息
- 在沙盒模式中配置機器人以進行測試，或發佈用於生產環境
依賴項 — 適配器需要 aiohttp 和 httpx：

   pip install aiohttp httpx

配置

交互式設置

hermes gateway setup

從平臺列表中選擇 QQ Bot 並按照提示操作。

手動配置

在 ~/.hermes/.env 中設置所需的環境變量：

QQ_APP_ID=your-app-id
QQ_CLIENT_SECRET=your-app-secret

環境變量

變量	描述	默認值
`QQ_APP_ID`	QQ 機器人 App ID（必填）	—
`QQ_CLIENT_SECRET`	QQ 機器人 App Secret（必填）	—
`QQBOT_HOME_CHANNEL`	用於定時任務/通知投遞的 OpenID	—
`QQBOT_HOME_CHANNEL_NAME`	主頁頻道的顯示名稱	`Home`
`QQ_ALLOWED_USERS`	允許訪問私聊的用戶 OpenID，以逗號分隔	open（所有用戶）
`QQ_ALLOW_ALL_USERS`	設置為 `true` 以允許所有私聊消息	`false`
`QQ_SANDBOX`	將請求路由到 QQ 沙盒網關以進行開發測試	`false`
`QQ_STT_API_KEY`	語音轉文本提供商的 API 密鑰	—
`QQ_STT_BASE_URL`	STT 提供商的基礎 URL	`https://open.bigmodel.cn/api/coding/paas/v4`
`QQ_STT_MODEL`	STT 模型名稱	`glm-asr`

高級配置

如需更精細的控制，請將平臺設置添加到 ~/.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"

語音消息 (STT)

語音轉錄分為兩個階段：

QQ 內置 ASR（免費，始終優先嚐試）— QQ 在語音消息附件中提供 asr_refer_text，使用的是騰訊自家的語音識別服務
配置的 STT 提供商（回退方案）— 如果 QQ 的 ASR 未返回文本，適配器將調用兼容 OpenAI 的 STT API：
- 智譜/GLM (zai)：默認提供商，使用 glm-asr 模型
- OpenAI Whisper：設置 QQ_STT_BASE_URL 和 QQ_STT_MODEL
- 任何兼容 OpenAI 的 STT 端點

故障排除

機器人立即斷開連接（快速斷開）

這通常意味著：

無效的 App ID / Secret — 請在 q.qq.com 仔細檢查您的憑據
缺少權限 — 確保已啟用機器人所需的意圖（Intents）
僅限沙盒的機器人 — 如果機器人處於沙盒模式，它只能接收來自 QQ 沙盒測試頻道的消息

語音消息未轉錄

檢查附件數據中是否存在 QQ 內置的 asr_refer_text
如果使用自定義 STT 提供商，請驗證 QQ_STT_API_KEY 是否設置正確
檢查網關日誌中是否有 STT 錯誤消息

消息未送達

驗證是否在 q.qq.com 啟用了機器人的 意圖（Intents）
如果限制了私聊訪問，請檢查 QQ_ALLOWED_USERS
對於群消息，確保機器人被 @提及（群策略可能需要白名單）
檢查 QQBOT_HOME_CHANNEL 以確認定時任務/通知的投遞

連接錯誤

確保已安裝 aiohttp 和 httpx：pip install aiohttp httpx
檢查到 api.sgroup.qq.com 和 WebSocket 網關的網絡連通性
查看網關日誌以獲取詳細的錯誤消息和重連行為

概述​

前提條件​

配置​

交互式設置​

手動配置​

環境變量​

高級配置​

語音消息 (STT)​

故障排除​

機器人立即斷開連接（快速斷開）​

語音消息未轉錄​

消息未送達​

連接錯誤​

概述