QQ 봇

QQ 공식 봇 v2 메시징, Ed25519 웹훅 이벤트 지원. 능동 메시지는 봇당 월 4건으로 제한되므로 수동 응답 방식으로 설계하십시오.

⚠️ 푸시가 아닌 수동 응답을 사용하십시오. QQ는 봇당 능동 메시지를 월 4건으로 제한합니다. 일일 한도: 능동 DM 200건, 채널당 능동 서브채널 메시지 20건. 대부분의 프로덕션 상호작용은 인바운드 사용자 메시지에 응답하는 방식이어야 합니다. 봇은 5초 이내에 응답해야 하며 무료 할당량이 적용됩니다. 능동 푸시는 중요한 알림에만 사용하십시오.

제공 기능

channel 접두사로 라우팅되는 네 가지 전송 경로:
- c2c:<openid> → /v2/users/{openid}/messages (C2C DM)
- group:<openid> → /v2/groups/{openid}/messages (그룹)
- channel:<id> (기본값) → /channels/{channel_id}/messages (공개 길드 채널)
- dm:<guild_id> → /dms/{guild_id}/messages (비공개 길드 DM)
/webhooks/qq 엔드포인트의 인바운드 웹훅, Ed25519 서명 검증.
access_token 캐싱, 7200초 유지, 자동 갱신.
텍스트 전용. 리치 미디어 메시지(이미지, 파일, ARK 카드)는 향후 지원 예정입니다.
텍스트 4000자 제한.

설정

1. 봇 등록

QQ 오픈 플랫폼 봇 콘솔에 로그인합니다.
봇을 생성하고, 봇 상세 페이지에서 AppID와 AppSecret을 확인합니다.
"개발 설정" → "Webhook"에서 URL을 https://<your-host>/webhooks/qq로 설정하고 "Webhook 모드"를 선택합니다.
플랫폼이 일회성 op=13 검증 핸드셰이크를 전송하면, Minara가 자동으로 서명된 plain_token으로 응답합니다.

2. 기본 수신 대상 지정

가장 자주 사용하는 대상을 선택하고 접두사와 함께 인코딩합니다.

시나리오	`QQ_BOT_DEFAULT_CHANNEL_ID`
공개 길드의 DM에 응답	`channel:<channel id>`
그룹으로 푸시	`group:<group openid>`
단일 사용자에게 푸시	`c2c:<user openid>`
비공개 길드 DM에 응답	`dm:<guild id>`

가장 일반적인 경우인 공개 길드 채널은 접두사를 생략할 수 있습니다.

QQ_BOT_DEFAULT_CHANNEL_ID=1234567890

channel:1234567890과 동일합니다.

3. Minara 설정

minara auth messaging add
# `qq`를 선택하고 AppID, AppSecret, 기본 대상을 입력합니다.

또는 환경 변수를 직접 설정합니다.

QQ_BOT_APP_ID=12345678
QQ_BOT_APP_SECRET=<opaque secret>
QQ_BOT_TOKEN=<bot token>
QQ_BOT_DEFAULT_CHANNEL_ID=channel:1234567890

4. 테스트

minara auth messaging test qq

월별 능동 메시지 할당량이 차감됩니다. 이를 고려하여 계획을 수립하십시오.

인바운드 웹훅

QQ는 <timestamp><raw_body>에 Ed25519로 인바운드 본문에 서명합니다. 공개 키는 플랫폼에서 공개하지 않으며, 봇 시크릿으로부터 다음과 같이 파생됩니다.

QQ_BOT_APP_SECRET의 UTF-8 바이트를 가져옵니다.
버퍼가 32바이트에 도달할 때까지 반복합니다.
해당 값을 Ed25519 시드로 사용하여 키 쌍을 파생합니다.

Minara는 이 시드 파생 키 쌍을 내부적으로 처리합니다. 재생 윈도우는 5분으로 설정되며, Discord 및 Slack에서 사용하는 규약과 동일합니다.

검증 핸드셰이크: 플랫폼이 {op: 13, d: {plain_token, event_ts}}를 전송하면, Minara가 파생된 개인 키로 event_ts + plain_token에 서명하고 서명된 hex 값으로 응답합니다. 이 방식으로 플랫폼은 엔드포인트가 시크릿을 보유하고 있음을 검증합니다.

수신되는 이벤트 유형:

AT_MESSAGE_CREATE, 공개 길드 채널에서 봇이 @멘션된 경우
GROUP_AT_MESSAGE_CREATE, 그룹에서 봇이 @멘션된 경우
C2C_MESSAGE_CREATE, 사용자가 보낸 DM

다른 op=0 디스패치 이벤트(채널 업데이트, 반응 등)는 무시됩니다.

제한 사항 및 주의점

능동 메시지 할당량. 월 4건, 일 200건 DM, 서브채널당 일 20건. 할당량 소진 후에는 코드 130_001 오류가 발생합니다. 일정량 이상 푸시한다면 이 오류를 예상된 동작으로 처리하십시오.
수동 응답 패턴이 기본 방식입니다. 사용자가 봇을 @멘션하면 봇은 5초 이내에 응답합니다. 이 응답은 능동 할당량에 포함되지 않습니다.
신규 봇은 웹훅이 필수입니다. WebSocket 샌드박스 모드는 v2에서 더 이상 지원되지 않습니다.

문제 해결

"테스트 메시지에서 errcode 130001 반환"

월별 능동 메시지 할당량이 소진되었습니다. 수동 응답 방식을 사용하십시오.

"인바운드 웹훅에서 401 반환"

가장 흔한 원인: 호스트의 클럭 스큐. 5분 재생 윈도우는 엄격하게 적용됩니다.
드문 원인: App Secret의 일부만 붙여넣은 경우. 짧은 시크릿은 시드 파생 과정에서 반복되지만, 잘못된 시크릿은 잘못된 공개 키를 생성합니다.

"검증 핸드셰이크(op=13) 실패"

부팅 시 QQ_BOT_APP_SECRET이 설정되지 않은 경우입니다. 시드 파생이 실패하면 플랫폼의 바인딩 절차가 완료되지 않습니다.

참조

환경 변수: QQ_BOT_*
아웃바운드: apps/agent/src/messaging/qq.ts
인바운드 명세: apps/agent/src/messaging/inbound/specs/qq.ts
QQ Bot v2 API: bot.q.qq.com / wiki
서명 방식: Authentication / Sign

목차