H繁中版
文件user-guideqqbot
<!-- Source: https://hermesbible.com/docs/user-guide/messaging/qqbot -->

Section: Messaging Platforms · URL: https://hermesbible.com/docs/user-guide/messaging/qqbot

QQ Bot

透過官方 QQ Bot API (v2) 將 Hermes 連接到 QQ — 支援私人訊息 (C2C)、群組 @提及、頻道及私訊，並提供語音轉文字功能。

概覽

QQ Bot 適配器使用官方 QQ Bot API 來：

  • 透過持久化 WebSocket 連線從 QQ 閘道器接收訊息
  • 透過 REST API 傳送文字和 Markdown 回覆
  • 下載並處理圖片、語音訊息和檔案附件
  • 使用騰訊內建的 ASR 或可設定的 STT 供應商轉錄語音訊息

前置需求

  1. QQ Bot 應用程式 — 在 q.qq.com 註冊：

    • 建立新應用程式並記下你的 App ID 和 App Secret
    • 啟用所需的 intents：C2C 訊息、群組 @訊息、頻道訊息
    • 在沙箱模式下設定你的機器人進行測試，或發佈至正式環境

  2. 相依套件 — 適配器需要 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_IDQQ Bot App ID（必填）—
QQ_CLIENT_SECRETQQ Bot App Secret（必填）—
QQBOT_HOME_CHANNEL用於定時任務/通知傳送的 OpenID—
QQBOT_HOME_CHANNEL_NAME主頻道的顯示名稱Home
QQ_ALLOWED_USERS以逗號分隔的使用者 OpenID，用於私訊存取開放（所有使用者）
QQ_GROUP_ALLOWED_USERS以逗號分隔的群組 OpenID，用於群組存取—
QQ_ALLOW_ALL_USERS設為 true 以允許所有私訊false
QQ_PORTAL_HOST覆蓋 QQ portal 主機（沙箱路由設為 sandbox.q.qq.com）q.qq.com
QQ_STT_API_KEY語音轉文字供應商的 API 金鑰—
QQ_STT_BASE_URL（非直接讀取 — 請在 config.yaml 中設定 platforms.qqbot.extra.stt.baseUrl）n/a
QQ_STT_MODELSTT 模型名稱glm-asr

進階設定

如需更精細的控制，請在 ~/.hermes/config.yaml 中加入平台設定：

platforms:
  qqbot:
    enabled: true
    extra:
      app_id: "your-app-id"
      client_secret: "your-secret"
      markdown_support: true       # 啟用 QQ markdown (msg_type 2)。僅限設定檔；無對應的環境變數。
      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) 等
        baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4"
        apiKey: "your-stt-key"
        model: "glm-asr"

語音訊息 (STT)

語音轉錄分為兩個階段運作：

  1. QQ 內建 ASR（免費，始終優先嘗試）— QQ 在語音訊息附件中提供 asr_refer_text，使用騰訊自家的語音辨識技術

  2. 設定的 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 的沙箱測試頻道接收訊息

語音訊息未轉錄

  1. 檢查附件資料中是否存在 QQ 內建的 asr_refer_text
  2. 如果使用自訂 STT 供應商，請確認 QQ_STT_API_KEY 已正確設定
  3. 檢查閘道器日誌中的 STT 錯誤訊息

訊息未送達

  • 確認機器人的 intents 已在 q.qq.com 啟用
  • 如果私訊存取受限，請檢查 QQ_ALLOWED_USERS
  • 對於群組訊息，請確保機器人已被 @提及（群組策略可能需要加入允許清單）
  • 檢查 QQBOT_HOME_CHANNEL 用於定時任務/通知傳送

連線錯誤

  • 確認已安裝 aiohttp 和 httpx：pip install aiohttp httpx
  • 檢查到 api.sgroup.qq.com 和 WebSocket 閘道器的網路連線
  • 檢視閘道器日誌以取得詳細的錯誤訊息和重新連線行為

SimpleX Chat

photonsignal