QQ 机器人接入

這篇教學將手把手教你如何把 Hermes Agent 接入 QQ，讓它能陪你聊天、處理訊息，甚至聽懂語音。

準備工作：像「開店」一樣申請材料

在開始之前，你需要先「開個店」——在 QQ 開放平台申請一個機器人「營業執照」。

第 1 步：申請 QQ 機器人應用

1. 訪問 q.qq.com 並註冊登入。
2. 點擊「建立應用」，記下系統給你的 App ID 和 App Secret（這相當於你的店鋪帳號和密碼，非常重要）。
3. 在「權限管理」裡，勾選你需要的「服務項目」：私聊訊息、群 @ 訊息、頻道訊息等。記得開啟「訊息接收」的開關，否則機器人會「失聰」。
4. 建議先在「沙箱模式」下測試，就像店鋪試營運，只有你能看到。

第 2 步：安裝「搬運工」依賴

Hermes 需要兩個小工具來搬運訊息，打開終端機（命令列）輸入：

pip install aiohttp httpx

設定機器人：兩種「裝潢」方式

方式一：懶人自動設定（推薦）

在終端機執行：

hermes gateway setup

然後從清單裡選擇 QQ Bot，跟著提示輸入你的 App ID 和 App Secret 即可，就像用精靈裝潢房子。

方式二：手動設定（更靈活）

用文字編輯器開啟（或新建）~/.hermes/.env 檔案，填入：

QQ_APP_ID=你的App ID
QQ_CLIENT_SECRET=你的App Secret

如果你想更精細地控制（例如只允許特定好友私聊），可以在 ~/.hermes/config.yaml 裡進行進階設定，例如：

platforms:
  qqbot:
    enabled: true
    extra:
      app_id: "你的App ID"
      client_secret: "你的App Secret"
      dm_policy: "allowlist"  # 只允許白名單使用者私聊
      allow_from:
        - "使用者OpenID"

聽懂語音：免費「翻譯官」與備用「同傳」

QQ 機器人自帶一個免費的語音轉文字「翻譯官」（騰訊 ASR），它會在你收到語音時自動附上文字。如果它沒聽清，Hermes 會呼叫你設定的備用「同傳」——預設是智譜的 glm-asr 模型，你也可以換成 OpenAI Whisper 等。一般預設設定就夠用，無需額外設定。

常見問題「急救箱」

• 機器人一連線就斷線？ 檢查 App ID/Secret 是否填錯，或者機器人是否還在沙箱模式（沙箱模式只能收到測試訊息）。
• 語音轉不了文字？ 先看日誌裡有沒有報錯，再檢查 QQ_STT_API_KEY 是否設定正確。
• 訊息收不到？ 去 q.qq.com 檢查「訊息接收」的開關是否開啟，或者私聊權限是否被限制。

小結與下篇預告

到這裡，你的 QQ 機器人已經「活」起來了！它現在能接收訊息、回覆文字，甚至聽懂語音。核心就是三步：申請應用、設定金鑰、啟動閘道。

下篇預告：機器人光會聊天可不夠，下一篇我們將介紹如何給 Hermes 接入飛書，讓它成為你團隊裡的「智慧助理」，敬請期待！