머리말
최근 NapCatQQ의 WebUI가 완성되어 초보자가 시작하기에 매우 적합하다는 것을 알게 되어 이 글을 작성합니다.
이 글은 기본적인 사용 방법만 다루며, 고급 기능은 빠져 있을 수 있습니다. 하지만 동시에 명령줄, HTTP 프로토콜, Docker, Python과 같은 기초 지식이 필요하며 완전히 초보자용은 아닙니다. (Webhook을 사용한 알림만 원하거나 기존 NoneBot 플러그인을 사용하려는 경우 Python 프로그래밍은 필요하지 않습니다.)
사용하는 도구는 NapCatQQ와 NoneBot입니다. 전자는 QQ를 실행하고 OneBot11 등의 프로토콜에 연결하며, 후자는 Python으로 프로토콜을 호출하여 구현한 프레임워크입니다. 문제가 발생하면 공식 문서를 참조하세요. (Webhook 알림만 사용하려면 NapCatQQ만 구축하면 됩니다.)
준비 작업
- 서버 한 대, 내부망/외부망 관계없음.
- QQ 봇으로 사용할 QQ 계정, 주 계정 사용은 권장하지 않음.
QQ는 플러그인 사용 여부를 감지할 수 있으며, 계정에 다음과 같은 문제가 발생할 수 있습니다: 강제 로그아웃, 로그인 제한, 동결.
각자 실제 상황에 따라 계속 사용할지 여부를 스스로 판단하시기 바라며, 저자는 이 글을 참고하여 봇을 구축함으로써 발생하는 어떠한 결과에도 책임을 지지 않습니다.
NapCatQQ
설치
NapCatQQ의 설치 방법은 여러 가지가 있지만, 서비스로 사용할 것이므로 Docker를 이용한 Shell 버전 설치를 권장합니다: https://napneko.github.io/guide/boot/Shell#napcat-docker-linux容器化部署
Docker 컨테이너에는 NTQQ 본체가 포함되어 있어 해당 버전의 QQ를 별도로 설치할 필요가 없습니다.
이제 http://[IP]:6099/webui 에 접속하면 NTQQ 웹 페이지를 볼 수 있으며, 로그인 및 설정이 가능합니다. 로그인 비밀번호는 로그 파일에서 확인할 수 있으며(기본값: napcat), 로그인 후 변경하는 것이 좋습니다.
또는 docker logs napcat으로 로그를 확인하고 QR 코드로 QQ에 로그인할 수도 있습니다.
QR 코드 로그인 시 이후 휴대폰 인증이 필요 없도록 체크하는 것이 좋습니다.
HTTP 프로토콜 활성화
WebUI에서 네트워크 설정->새로 만들기->HTTP 서버를 찾아 이름, Host, 포트는 임의로 설정하고, 메시지 형식은 Array를 선택하는 것이 좋습니다. 실제 테스트 결과 String과 호환되며 텍스트와 이미지 혼합 메시지를 보낼 수 있습니다. 또한 악의적인 요청을 방지하기 위해 Token을 반드시 입력하는 것이 좋습니다.
활성화 후 인터페이스 디버그->HTTP나 익숙한 API 테스트 도구에서 테스트할 수 있습니다. API 참조: https://napcat.apifox.cn/
Token 사용 방법은 두 가지입니다:
- 요청 헤더에
Authorization: [Token]을 추가합니다.
- URL에
?access_token=[Token]을 추가합니다.
Webhook을 사용한 알림
여기서 가장 중요한 인터페이스는 당연히 개인 메시지 보내기와 그룹 메시지 보내기입니다. 인터페이스 디버그->HTTP에서 해당 API를 찾을 수 있으며, 메시지 구성 기능도 있어 매우 간단합니다.
개인 메시지 보내기 예시입니다:

일부 애플리케이션은 Webhook 구현으로 shoutrrr를 사용하며, 다음 설정을 참고할 수 있습니다:
일부 애플리케이션은 자체적으로 OneBot11 프로토콜을 지원할 수 있으며, 이 경우 http://[IP]:3000, Token, 대상 QQ 번호를 입력하면 됩니다.
nginx 리버스 프록시
도메인이 있다면 다음 NapCatQQ의 nginx 설정 예시를 참고할 수 있습니다:
NoneBot
문서가 이미 잘 정리되어 있으므로 여기서 자세히 설명하지 않겠습니다.