QQ Bot — QQ에서의 AI | Easy Understand Hermes Agent

여러분이 즐겨 쓰는 단체 채팅방에 갑자기 질문에 답하고, 음성 메시지를 요약하고, 심지어 예쁘게 서식된 답변까지 보내주는 초똑똑한 친구가 생긴다면 어떨까요? 바로 그게 Hermes Agent가 QQ에 가져다주는 것입니다.

이게 뭔가요?

Hermes Agent는 AI 어시스턴트를 메시징 플랫폼에 연결할 수 있게 해주는 오픈소스 프레임워크입니다. QQ 봇 어댑터는 Hermes와 QQ 공식 봇 API 사이의 다리 역할을 하죠. (1:1 채팅, 그룹 @멘션, 길드 채널의) 메시지를 듣고 자동으로 응답합니다. 설정 외에 별도 코딩은 필요 없어요.

어떻게 동작하나요? (쉽게 풀어서)

새 전화기를 설정하는 것과 비슷하다고 생각하면 됩니다.

봇 신원을 만든다 – q.qq.com에서 봇을 등록하고 App ID와 App Secret을 받습니다. (봇의 아이디와 비밀번호라고 생각하면 됩니다.)
선을 연결한다 – Hermes가 QQ 게이트웨이에 지속적인 WebSocket 연결을 열어 메시지를 실시간으로 수신합니다.
듣도록 가르친다 – 봇이 참여할 대화 범위(1:1 메시지, 그룹 멘션, 길드 채널)를 결정합니다.
말하게 한다 – 누군가 메시지를 보내면 Hermes가 처리하고 텍스트나 리치 마크다운 형식으로 답변합니다.

단계별 설정 가이드

1. 의존성 설치하기

pip install aiohttp httpx

2. 봇 설정하기 (가장 쉬운 방법)

hermes gateway setup

QQ Bot을 선택하고 안내에 따르세요. App ID와 Secret을 입력하라는 메시지가 표시됩니다.

3. 수동 설정 (원하는 경우)

~/.hermes/.env 파일을 생성하거나 편집합니다.

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

이것이 최소 설정입니다. 더 세밀한 제어가 필요하다면 ~/.hermes/config.yaml 파일을 편집하세요.

platforms:
  qqbot:
    enabled: true
    extra:
      markdown_support: true
      dm_policy: "open"   # open | allowlist | disabled
      group_policy: "open"

멋진 기능: 음성 메시지

QQ는 모든 음성 메시지에 대해 무료 전사(텐센트 ASR) 기능을 제공합니다. 만약 이 기능이 실패하면, Hermes는 GLM-ASR이나 OpenAI Whisper 같은 커스텀 STT 제공자로 대체할 수 있습니다. 즉, 봇이 음성 메모를 “듣고” 텍스트 요약으로 답변할 수 있다는 뜻이죠.

알아두면 좋은 보안 설정

QQ_ALLOWED_USERS – 1:1 메시지를 특정 OpenID로 제한합니다. (기본값: 모두 허용)
QQ_GROUP_ALLOWED_USERS – 그룹 접근을 특정 그룹 OpenID로 제한합니다.
dm_policy / group_policy – 엄격한 제어를 위해 "allowlist"로 설정하거나, 해당 채널을 완전히 끄려면 "disabled"로 설정합니다.

요약 및 실용적인 팁

Hermes를 QQ에 연결하는 것은 단체 채팅방에 개인 비서를 하나 두는 것과 같습니다. 설정하는 데 약 10분 정도 걸리며, 이후에는 누가 봇과 대화할 수 있는지부터 마크다운 지원 여부, 음성 전사 지원 여부까지 모든 것을 맞춤 설정할 수 있습니다.

초보자를 위한 팁: 샌드박스 모드(QQ_PORTAL_HOST=sandbox.q.qq.com 설정)에서 시작하세요. 먼저 자신의 계정으로 테스트하고, 점차 친구들에게 공개하세요. 그리고 공개하기 전에 항상 QQ_ALLOWED_USERS에 자신의 OpenID를 설정하세요. 첫날부터 낯선 사람이 봇과 대화하게 두고 싶지는 않을 테니까요.

봇이 활성화되면, 긴 음성 메시지를 요약하거나 빠른 공지사항을 예쁘게 포맷해 달라고 요청해 보세요. 바로 그때 마법이 일어납니다.