본문으로 건너뛰기

QQ Bot

Hermes를 Official QQ Bot API (v2) 통해 QQ 연결 — private (), group @-mentions, guild, direct messages 지원, 음성 transcription 포함.

Overview​

QQ Bot adapter는 Official QQ Bot API 사용:

  • QQ Gateway에 persistent WebSocket connection으로 메시지 수신
  • REST API 통해 text 및 markdown 응답 전송
  • 이미지, 음성 메시지, 파일 첨부 다운로드 및 처리
  • Tencent 내장 ASR 또는 설정 가능한 STT provider로 음성 메시지 transcribe

Prerequisites​

  1. QQ Bot Application — q.qq.com에서 등록:

    • 새 application 생성, App ID및App Secret 기록
    • 필요한 intents 활성화: messages, Group @-messages, Guild messages
    • 테스트용 sandbox mode 설정, production용 publish

  2. Dependencies — Adapter는 aiohttp 및 httpx 필요:

    pip install aiohttp httpx

Configuration​

Interactive setup​

hermes gateway setup

플랫폼 목록에서 QQ Bot 선택, 프롬프트 따라 진행.

Manual configuration​

~/.hermes/.env에 필수 환경 변수 설정:

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

Environment Variables​

VariableDescriptionDefault
QQ_APP_IDQQ Bot App ID (필수)—
QQ_CLIENT_SECRETQQ Bot App Secret (필수)—
QQBOT_HOME_CHANNELcron/notification 전달용 OpenID—
QQBOT_HOME_CHANNEL_NAMEhome channel 표시 이름Home
QQ_ALLOWED_USERSDM 접근용 user OpenID 콤마 구분 목록open (모든 사용자)
QQ_GROUP_ALLOWED_USERSgroup 접근용 group OpenID 콤마 구분 목록—
QQ_ALLOW_ALL_USERS모든 DM 허용하려면 true로 설정false
QQ_PORTAL_HOSTQQ portal host override (sandbox routing은 sandbox.q.qq.com로 설정)q.qq.com
QQ_STT_API_KEYvoice-to-text provider용 API key—
QQ_STT_BASE_URL(직접 읽지 않음 — config.yaml에 platforms.qqbot.extra.stt.baseUrl 설정)n/a
QQ_STT_MODELSTT 모델 이름glm-asr

Advanced Configuration​

세밀한 제어용으로 ~/.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"

Voice Messages (STT)​

음성 transcription은 2단계 작동:

  1. QQ 내장 ASR (무료, 항상 먼저 시도) — QQ가 음성 메시지 첨부에 asr_refer_text 제공, Tencent 자체 speech recognition 사용

  2. 설정된 STT provider (fallback) — QQ ASR이 텍스트 반환 안 하면 adapter가 OpenAI 호환 STT API 호출:

    • Zhipu/GLM (zai): 기본 provider, glm-asr 모델 사용
    • OpenAI Whisper: QQ_STT_BASE_URL 및 QQ_STT_MODEL 설정
    • OpenAI 호환 STT endpoint 모두 가능

Troubleshooting​

Bot 즉시 disconnect (quick disconnect)​

보통 원인:

  • 잘못된 App ID / Secret — q.qq.com에서 credentials 재확인
  • 권한 누락 — bot에 필수 intents 활성화 확인
  • Sandbox 전용 bot — bot이 sandbox mode면 QQ sandbox 테스트 채널 메시지만 수신 가능

음성 메시지 transcribe 안 됨​

  1. 첨부 데이터에 QQ 내장 asr_refer_text 존재 여부 확인
  2. custom STT provider 사용 시 QQ_STT_API_KEY 정확히 설정됐는지 확인
  3. STT 에러 메시지는 gateway 로그 확인

메시지 전달 안 됨​

  • q.qq.com에서 bot intents 활성화 확인
  • DM 접근 제한 시 QQ_ALLOWED_USERS 확인
  • group 메시지는 bot @mention 필수 (group policy가 allowlist 요구할 수 있음)
  • cron/notification 전달은 QQBOT_HOME_CHANNEL 확인

연결 에러​

  • aiohttp 및 httpx 설치 확인: pip install aiohttp httpx
  • api.sgroup.qq.com 및 WebSocket gateway 네트워크 연결 확인
  • 상세 에러 메시지 및 재접속 동작은 gateway 로그 확인