AstrBot 배포 실전: QQ/Telegram/Lark 전 플랫폼 봇 구축

30분 만에 여러 메시지 플랫폼을 지원하는 AI 채팅 봇을 빠르게 구축하세요. Telegram, Lark(Feishu), QQ 등 주요 메신저를 지원합니다.

대상 독자: 자신만의 AI 채팅 봇을 빠르게 만들고 싶은 1-3년 차 백엔드 개발자

핵심 의존성: Python 3.10+, uv 패키지 매니저, 메시지 플랫폼 개발자 계정

학습 목표: AstrBot 배포의 전체 프로세스를 마스터하고 멀티 플랫폼 AI 어시스턴트를 구축할 수 있습니다.

---

1. 프로젝트 소개 및 아키텍처

AstrBot은 Python으로 개발된 오픈 소스 AI Agent 채팅 봇 플랫폼으로, 다양한 인스턴트 메시징 소프트웨어 연동을 지원합니다. 설계 이념은 「동반자 관계와 능력은 대립되는 것이 아니다」로, 정서적 교감 능력과 신뢰할 수 있는 업무 수행 능력을 동시에 갖추는 것을 목표로 합니다.

1.1 지원 메시지 플랫폼

1.2 핵심 기능

• 멀티 모델 지원: OpenAI, Claude, Gemini, DeepSeek 등
• Agent 능력: MCP 프로토콜 지원, 외부 도구 호출 가능
• 페르소나 설정: 내장된 Persona 시스템으로 AI 성격 맞춤 설정 가능
• 지식베이스: RAG 지원, 문서 임포트를 통한 AI 전문 지식 강화
• WebUI: 시각적 콘솔을 통한 직관적인 설정

---

2. 환경 준비

2.1 uv 설치

AstrBot은 pip보다 10배 이상 빠른 차세대 Python 패키지 매니저인 uv를 사용한 설치를 권장합니다.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

설치 완료 후 확인:

uv --version
# 출력 예시: uv 0.5.0

2.2 AstrBot 설치

명령어 한 줄로 설치를 완료합니다:

uv tool install astrbot

2.3 프로젝트 초기화

astrbot init

이 명령어는 다음과 같은 프로젝트 디렉토리 구조를 생성합니다:

.
├── data/              # 데이터 디렉토리
│   ├── cmd_config.json  # 메인 설정 파일
│   └── config/         # 다중 설정 파일 디렉토리
├── logs/              # 로그 디렉토리
└── plugins/           # 플러그인 디렉토리

프로젝트 디렉토리로 이동:

cd astrbot

---

3. 메시지 플랫폼 어댑터 설정

AstrBot은 다양한 메시지 플랫폼을 지원합니다. 여기서는 세 가지 주요 플랫폼의 설정 방법을 설명합니다.

3.1 Telegram 봇 설정

Telegram은 설정이 가장 간단하며, Bot Token만 있으면 됩니다.

3.1.1 봇 생성

1. Telegram에서 @BotFather 검색
2. /newbot 전송하여 새 봇 생성
3. 안내에 따라 이름과 사용자 이름 설정
4. Bot Token 복사 (예: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

3.1.2 설정 파일

data/cmd_config.json을 열고 platform 배열에 다음을 추가합니다:

{
    "platform": [
        {
            "type": "telegram",
            "enable": true,
            "token": "귀하의BotToken"
        }
    ]
}

3.1.3 Chat ID 확인

봇을 실행한 후 봇에게 메시지를 보낸 다음, 아래 주소에 접속하세요:

https://api.telegram.org/bot<TOKEN>/getUpdates

반환된 JSON에서 "chat":{"id":123456789}를 찾으세요. 이것이 귀하의 Chat ID입니다.

3.2 Lark (飞书) 봇 설정

Lark는 기업에서 자주 사용하는 협업 플랫폼으로, 설정이 조금 더 복잡합니다.

3.2.1 앱 생성

1. Lark 오픈 플랫폼 접속
2. 기업용 앱 생성
3. 「권한 관리」에서 다음 권한 추가:
   • im:chat:readonly - 그룹 정보 읽기
   • im:message:send_as_bot - 봇 신분으로 메시지 전송
   • im:message:receive - 메시지 수신

3.2.2 봇 생성

1. 앱 내에 「봇」 기능 추가
2. App ID와 App Secret 복사

3.2.3 설정 파일

{
    "platform": [
        {
            "type": "lark",
            "enable": true,
            "app_id": "귀하의AppID",
            "app_secret": "귀하의AppSecret",
            "verification_token": "귀하의VerificationToken"
        }
    ]
}

3.3 QQ 봇 설정 (OneBot)

QQ 봇은 NapCat 또는 LLOneBot과 함께 사용해야 합니다.

3.3.1 NapCat 설치

QQ 클라이언트로 NapCat 사용을 권장합니다:

# 방법 1: Docker 배포 (권장)
docker pull napneko/napcat:latest

# 방법 2: 직접 설치
# 참고: https://napneko.github.io/

3.3.2 설정 파일

{
    "platform": [
        {
            "type": "onebot",
            "enable": true,
            "ws_host": "127.0.0.1",
            "ws_port": 3001,
            "http_port": 3000
        }
    ]
}

3.3.3 NapCat 실행

docker run -d \
  --name napcat \
  -p 3000:3000 \
  -p 3001:3001 \
  -v ./data:/app/data \
  napneko/napcat:latest

---

4. 대규모 언어 모델(LLM) 설정

대형 모델이 없다면 봇은 단순한 앵무새에 불과합니다. 이 단계가 매우 중요합니다.

4.1 Defapi 사용 (권장)

Defapi는 AI 모델 통합 플랫폼으로, 공식 가격의 절반 수준이며 국내 접속 속도가 빠릅니다.

4.1.1 Defapi 가입

1. Defapi 접속 및 계정 등록
2. 콘솔에서 API Key 확인

4.1.2 설정 파일

cmd_config.json에 provider 설정을 추가합니다:

{
    "provider": [
        {
            "id": "defapi",
            "type": "openai_chat_completion",
            "model": "claude-sonnet-4-20250514",
            "key": ["귀하의Defapi-API-Key"],
            "api_base": "https://api.defapi.org/v1",
            "enable": true
        }
    ],
    "provider_settings": {
        "default_provider_id": "defapi",
        "enable": true
    }
}

4.2 OpenAI 공식 API 사용

OpenAI API Key가 있는 경우:

{
    "provider": [
        {
            "id": "openai",
            "type": "openai_chat_completion",
            "model": "gpt-4o",
            "key": ["sk-xxx"],
            "api_base": "https://api.openai.com/v1",
            "proxy": "http://127.0.0.1:7890",
            "enable": true
        }
    ]
}

4.3 DeepSeek 사용

가성비가 뛰어난 DeepSeek 사용을 권장합니다:

{
    "provider": [
        {
            "id": "deepseek",
            "type": "openai_chat_completion",
            "model": "deepseek-chat",
            "key": ["sk-xxx"],
            "api_base": "https://api.deepseek.com/v1",
            "enable": true
        }
    ]
}

---

5. 실행 및 검증

5.1 서비스 실행

astrbot

다음과 같은 출력이 표시됩니다:

INFO - AstrBot 시작 중...
INFO - WebUI: http://localhost:6185
INFO - 플랫폼 어댑터 로드 완료: telegram, lark, onebot
INFO - Provider 로드 완료: defapi
INFO - AstrBot 시작 완료!

5.2 콘솔 접속

브라우저에서 http://localhost:6185에 접속하세요. 기본 계정 정보:

• 사용자 이름: astrbot
• 비밀번호: astrbot

5.3 대화 테스트

해당 메시지 플랫폼에서 봇에게 메시지를 보내보세요:

안녕! 너는 누구니?

모든 설정이 정상이라면 봇이 설정된 대형 모델을 사용하여 응답합니다.

---

6. 자주 발생하는 문제 해결

6.1 봇 실행 실패

문제: ModuleNotFoundError: No module named 'astrbot'

해결:

# 재설치
uv tool uninstall astrbot
uv tool install astrbot

6.2 메시지 수신 불가

문제: 봇에게 메시지를 보냈으나 응답이 없음

확인 단계:

1. 플랫폼 어댑터 활성화 여부 확인:

astrbot -p

1. 로그 확인:

tail -f logs/astrbot.log

1. 플랫폼 설정 및 Token/키가 올바른지 확인

6.3 모델 호출 실패

문제: Error: API request failed

확인 단계:

1. API Key가 올바른지 확인
2. 네트워크 연결 확인 (국내의 경우 프록시 필요)
3. 모델 이름이 올바른지 확인
4. 계정 잔액이 충분한지 확인

6.4 속도 제한 (Rate Limit)

문제: 429 Too Many Requests

해결: 여러 개의 API Key를 설정하여 부하 분산 구현:

{
    "provider": [
        {
            "id": "openai-multi",
            "type": "openai_chat_completion",
            "model": "gpt-4o",
            "key": ["key1", "key2", "key3"],
            "api_base": "https://api.openai.com/v1",
            "enable": true
        }
    ]
}

6.5 Telegram 봇 1:1 채팅 불가

문제: 그룹 채팅은 되는데 1:1 채팅은 반응이 없음

해결: BotFather와 대화하여 /start를 보내 봇을 활성화한 후 1:1 채팅이 가능해집니다.

6.6 Lark 봇 메시지 수신 불가

문제: 설정을 마쳤으나 메시지를 받지 못함

해결:

1. 앱이 게시(Publish)되었는지 확인
2. 봇이 그룹에 추가되었거나 1:1 채팅이 활성화되었는지 확인
3. 공인 네트워크 접속이 원활한지 확인

---

7. 심화 확장

7.1 플러그인 개발

AstrBot은 플러그인 확장을 지원합니다. plugins/my_plugin/main.py를 생성하세요:

from astrbot.api.event import filter, EventMessage

@filter()
async def handle_hello(event: EventMessage):
    if event.message_str == "hello":
        await event.reply("Hello! I'm your AI assistant!")

7.2 페르소나 설정

콘솔의 「페르소나」 페이지에서 persona를 생성하고 시스템 프롬프트를 설정하세요:

당신은 친절한 AI 어시스턴트이며, 간결한 언어로 질문에 답하는 것을 좋아합니다.

7.3 MCP 통합

AstrBot은 MCP 프로토콜을 지원하여 외부 도구를 호출할 수 있습니다. 콘솔의 「스킬」 페이지에서 MCP 서비스를 설정하세요.

7.4 지식베이스 RAG

콘솔에서 지식베이스를 생성하고 문서를 업로드하여 AI가 특정 분야의 지식을 갖도록 하세요.

---

추가 자료

• AstrBot 공식 문서
• AstrBot GitHub
• NapCat QQ 배포 가이드
• Lark 오픈 플랫폼 문서
• OneBot 프로토콜 사양