QQ Bot

概要
事前に必要なもの
設定
対話式のセットアップ
手作業での設定
環境変数
細かい設定
音声メッセージ（音声認識）
困ったときは
ボットがすぐ切断される
音声メッセージが書き起こされない
メッセージが届かない
接続のエラー

Hermes を QQ 公式ボット API（v2） 経由で QQ につなぎます。個人チャット（C2C）、グループでの @ メンション、ギルド、ダイレクトメッセージに対応し、音声の書き起こしも使えます。

概要

QQ Bot アダプターは QQ 公式ボット API を使って次のことを行います。

QQ のゲートウェイへ WebSocket で常時接続し、メッセージを受け取る
REST API でテキストや Markdown の返信を送る
画像、音声メッセージ、添付ファイルをダウンロードして処理する
テンセント内蔵の ASR、または設定した音声認識サービスで音声メッセージを書き起こす

事前に必要なもの

QQ ボットのアプリケーション — q.qq.com で登録します。

新しいアプリケーションを作り、App ID と App Secret を控えます
必要なインテントを有効にします: 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`	DM を許可するユーザーの OpenID をカンマ区切りで	open（すべてのユーザー）
`QQ_GROUP_ALLOWED_USERS`	グループでの利用を許可するグループの OpenID をカンマ区切りで	—
`QQ_ALLOW_ALL_USERS`	`true` にするとすべての DM を許可します	`false`
`QQ_PORTAL_HOST`	QQ のポータルのホストを上書きします（サンドボックスへ向けるなら `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_MODEL`	音声認識のモデル名	`glm-asr`

細かい設定

もっと細かく制御したい場合は、~/.hermes/config.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"

音声メッセージ（音声認識）

音声の書き起こしは 2 段階で行われます。

QQ 内蔵の ASR（無料。必ず最初に試されます） — QQ は音声メッセージの添付に asr_refer_text を付けてきます。これはテンセント自身の音声認識によるものです
設定した音声認識サービス（うまくいかないときの受け皿） — QQ の ASR がテキストを返さなかった場合、アダプターは OpenAI 互換の音声認識 API を呼びます。

Zhipu/GLM（zai）: 既定のサービス。glm-asr モデルを使います
OpenAI Whisper: QQ_STT_BASE_URL と QQ_STT_MODEL を設定します
そのほか OpenAI 互換の音声認識エンドポイントなら何でも

困ったときは

ボットがすぐ切断される

たいていは次のどれかです。

App ID / Secret が違う — q.qq.com で認証情報を見直してください
権限が足りない — ボットに必要なインテントが有効になっているか確認してください
サンドボックス専用のボット — サンドボックスモードのボットは、QQ のサンドボックスのテスト用チャンネルからしかメッセージを受け取れません

音声メッセージが書き起こされない

添付のデータに QQ 内蔵の asr_refer_text が入っているか確認します
独自の音声認識サービスを使っている場合、QQ_STT_API_KEY が正しく設定されているか確認します
ゲートウェイのログに音声認識のエラーが出ていないか確認します

メッセージが届かない

ボットの インテント が q.qq.com で有効になっているか確認します
DM を制限しているなら QQ_ALLOWED_USERS を確認します
グループのメッセージでは、ボットが @ メンションされている ことを確認します（グループの方針によっては許可リストへの追加も必要です）
定期実行や通知の送り先については QQBOT_HOME_CHANNEL を確認します

接続のエラー

aiohttp と httpx が入っているか確認します: pip install aiohttp httpx
api.sgroup.qq.com と WebSocket ゲートウェイへのネットワーク接続を確認します
ゲートウェイのログで、詳しいエラーや再接続の様子を確認します