QQ 봇

QQ 공식 봇으로 zqagent에 작업을 요청하고, 작업 완료 시 이메일(SMTP) 로 알림을 받습니다. 개인 채팅, 그룹 채팅(@봇), 채널을 지원하며 승인 / 질문 / 중단 등 완전한 상호작용이 가능합니다.

공식 봇은 아웃바운드 연결만 사용하며 공인 인바운드가 필요 없습니다. 자체/내부 서버에서도 메시지를 받을 수 있습니다.

플랫폼 준비(1회)

QQ 오픈 플랫폼에 등록하고 봇을 만들어 AppID + AppSecret을 받습니다.
GROUP_AND_C2C_EVENT(1<<25) 등의 intents 권한을 신청합니다(개인 채팅+그룹 채팅 메시지 이벤트는 특수 권한으로, 신청하지 않으면 게이트웨이 인증이 거부됩니다). 채널 @와 채널 DM은 각각 PUBLIC_GUILD_MESSAGES(1<<30)와 DIRECT_MESSAGE(1<<12)에 해당합니다.
연동 테스트 단계에서는 샌드박스 환경을 사용합니다(샌드박스 구성원만 테스트 가능). 정식 출시에는 심사가 필요합니다.

구성

방법 1: .env 환경 변수(시작 시 읽음)

bash

# .env
QQ_BOT_APP_ID=내AppID
QQ_BOT_APP_SECRET=내AppSecret
QQ_BOT_SANDBOX=1          # 샌드박스=1. 정식 환경=0 또는 비움

방법 2: 핫 구성(server 실행 중에도 재시작 없이 즉시 재연결 반영)

bash

# 현재 구성 보기(마스킹)
curl -s -H "Authorization: Bearer <테넌트apiKey>" http://localhost:8787/api/v1/qq/config

# 구성 / 업데이트
curl -s -X POST -H "Authorization: Bearer <테넌트apiKey>" -H "Content-Type: application/json" \
  -d '{"appId":"내AppID","appSecret":"내AppSecret","sandbox":true}' \
  http://localhost:8787/api/v1/qq/config

# 구성 삭제(연결 해제)
curl -s -X DELETE -H "Authorization: Bearer <테넌트apiKey>" http://localhost:8787/api/v1/qq/config

설정 후 로그에 QQ 机器人: 已启用가 표시됩니다. 핫 구성은 서버에 저장되어 재시작 후에도 유효합니다(우선순위: 환경 변수 > 저장된 구성).

멀티 테넌트 바인딩

방법 1: 단일 테넌트는 바인딩 불필요(개인 사용 권장)

시스템에 테넌트가 하나만 있을 때(기본 demo 등)는 바인딩 작업이 필요 없습니다. 메시지를 보내면 유일한 테넌트에 자동 바인딩되어 작업이 시작됩니다.

방법 2: 페어링 코드 바인딩(멀티 테넌트)

bash

# 페어링 코드 생성(관리자, REST API)
curl -X POST http://localhost:8787/api/v1/qq/pairing-code \
  -H "Authorization: Bearer <테넌트apiKey>"
# → { "data": { "code": "AB3CD5K7", "expiresIn": 300 } }

사용자는 QQ에서 바인딩합니다:

/bind AB3CD5K7
→ 바인딩 성공 ✅ 테넌트: demo. 이제 메시지를 보내면 작업이 시작됩니다.

페어링 코드는 5분간 유효하며 1회용입니다(apiKey 평문이 채팅 기록에 남는 것을 방지).
QQ 세션마다 하나의 테넌트 + 하나의 zqagent 세션에 대응하며, 첫 작업 전송 시 세션이 자동 생성됩니다.
바인딩 매핑은 {DATA_DIR}/qq/bindings.json에 저장됩니다.

명령 목록

명령	동작
메시지 직접 전송	작업 투입(질문 대기 중이면 답변, 실행 중이면 보충 정보)
`/bind <페어링 코드>`	현재 QQ 세션을 테넌트에 바인딩
`/unbind`	바인딩 해제
`/new`	새 세션을 만들고 바인딩 전환
`/status`	현재 세션 상태 보기
`/list`	세션 목록
`/stop`	현재 작업 중단
`/approve <once\|always_tool\|always_command\|deny>`	승인('동의/모두 동의/거부'를 직접 보내도 됨)
`/answer <내용>`	질문 답변
`/help`	도움말

작업 실행 중에 메시지를 보내면 보충 정보(steering) 로 현재 작업에 주입됩니다. 새 작업을 시작하려면 먼저 /stop하거나 작업이 끝날 때까지 기다리세요.

알림 회신과 승인

실행 중 주요 이벤트는 해당 QQ 세션으로 회신됩니다. 승인 요청에는 도구 이름 + 도구 인수 + 이유가 붙습니다:

승인 필요: write_file
인수:
{
  "path": "/tmp/a.txt",
  "content": "hello"
}
이유: 파일 쓰기가 필요합니다
회신: 동의(이번만) / 모두 동의(항상 허용) / 거부

동의 / 허용 / y → 이번만 허용(once)
모두 동의 / 항상 허용 → 이 세션에서 이 도구 항상 허용(always_tool)
거부 / n → 거부(deny)

⚠️ QQ 공식 봇은 능동 메시지에 엄격한 할당량이 있습니다. 작업 완료는 보통 '수동 응답 5분 창'을 넘기므로, 완료 알림은 이메일을 확실한 경로로 하고 QQ 회신은 최선 노력입니다.

이메일 알림 구성

bash

curl -X POST http://localhost:8787/api/v1/notifications \
  -H "Authorization: Bearer <테넌트apiKey>" -H "Content-Type: application/json" \
  -d '{
    "type": "email",
    "enabled": true,
    "config": {
      "host": "smtp.qq.com",
      "port": "465",
      "secure": "true",
      "user": "you@qq.com",
      "pass": "<QQ 메일 인증 코드>",
      "from": "you@qq.com",
      "to": "you@qq.com"
    },
    "events": { "approval": false, "question": false, "completed": true, "error": true }
  }'

QQ 메일: smtp.qq.com:465(SSL) + 인증 코드(로그인 비밀번호 아님).
163: smtp.163.com:465. Gmail: smtp.gmail.com:587(secure:"false").
pass 등 민감한 필드는 SECRET_KEY로 AES 암호화해 저장됩니다.
events가 트리거 시점을 제어합니다. 위 예시는 '완료/오류'일 때만 메일을 보냅니다.
짧은 작업은 방해하지 않음: minDurationSeconds(기본 60). 작업이 성공하고 실행 시간이 이 기준을 넘지 않으면 메일을 보내지 않습니다.

QQ 봇 ​

플랫폼 준비(1회) ​

구성 ​

멀티 테넌트 바인딩 ​

명령 목록 ​

알림 회신과 승인 ​

이메일 알림 구성 ​

QQ 봇

플랫폼 준비(1회)

구성

멀티 테넌트 바인딩

명령 목록

알림 회신과 승인

이메일 알림 구성