파이썬으로 디스코드 봇 만들기: 개발 환경 구축부터 토큰 보안까지

파이썬을 활용해 나만의 디스코드 봇을 만들고 구동하는 과정은 프로그래밍에 입문하는 개발자에게 매우 흥미로운 주제입니다. 내가 작성한 코드 한 줄로 봇이 서버에 온라인 상태로 들어오고, 멤버들의 메시지에 실시간으로 반응하는 모습을 보면 코딩의 재미를 직접 체감할 수 있기 때문인데요.

하지만 처음 개발 환경을 구축하다 보면 의외로 사소한 에러에 막혀 포기하게 되는 경우가 많습니다. 파이썬 버전 충돌부터 디스코드의 패키지 설치 에러, 인텐트 권한 설정 누락으로 인한 무반응 상태 등 시작 단계에서 넘어야 할 산들이 꽤 많은 편입니다.

저도 처음 파이썬으로 디스코드 봇을 구현했을 때, 라이브러리를 설치하고 개발자 포털 설정을 조율하는 과정에서 원인 모를 접속 실패 메시지만 띄우며 허둥댔던 기억이 있습니다. 당시에는 개발 도구를 다루는 법조차 미숙해서 간단한 소스 코드 하나 실행하는 데에도 며칠의 시간이 필요했었는데요.

이러한 시행착오를 최대한 줄이고, 파이썬 기반의 디스코드 봇을 안전하고 견고하게 구축할 수 있도록 서버 세팅부터 파이썬 및 패키지 설치, 보안 처리까지 한눈에 보기 쉽게 정리했습니다.

1. 디스코드 개발자 포털 등록과 세부 권한 설정

가장 먼저 해야 할 일은 디스코드 플랫폼에 내 봇 계정을 생성하는 작업입니다. 디스코드는 이를 어플리케이션(Application)이라는 단위로 관리합니다.

어플리케이션 생성

디스코드 개발자 포털의 애플리케이션 생성 화면

디스코드 개발자 포털(Discord Developer Portal) 사이트에 접속하여 본인 계정으로 로그인합니다.
화면 오른쪽 상단의 신규 애플리케이션 버튼을 클릭합니다.
봇의 이름을 기재하고 약관에 동의한 뒤 만들기를 누르면 관리 화면으로 전환됩니다.

봇 계정 설정과 인텐트의 이해

생성된 어플리케이션은 봇을 움직이기 위한 일종의 껍데기입니다. 실제 서버에서 활동할 유저 형태의 봇 계정을 추가로 다듬어야 합니다.

디스코드 개발자 포털 봇 메뉴의 토큰 관리 영역

왼쪽 메뉴 목록에서 봇 메뉴를 선택합니다.
봇 이름 아래에 위치한 토큰 초기화 단추를 누르면 영문 대소문자와 숫자가 혼합된 긴 암호 코드가 발급됩니다. 이것이 봇의 유일한 비밀번호인 토큰(Token)입니다. 이 코드는 이 화면에서 단 한 번만 조회할 수 있으므로(분실 시 재생성 가능), 별도의 텍스트 메모장에 복사하여 안전하게 보관해 두어야 합니다.
봇 페이지를 조금 더 아래로 내리면 Privileged Gateway Intents 섹션이 나타납니다. 디스코드 서버 내의 민감한 실시간 정보에 접근할 수 있게 허용하는 장치입니다. 다음 세 가지 항목을 반드시 모두 켜 줍니다.

디스코드 개발자 포털 봇 메뉴의 게이트웨이 인텐트 설정 항목

Presence Intent: 서버 멤버들의 온라인/오프라인 상태와 실행 중인 게임 정보를 수집합니다.
Server Members Intent: 새로운 유저가 가입하거나 탈퇴할 때 발생하는 이벤트를 감지합니다.
Message Content Intent: 사용자가 입력한 메시지의 텍스트 본문을 읽는 권한입니다. 이 옵션을 켜지 않으면 봇 코드가 작동하더라도 메시지 내용이 비어 있는 상태로 수신되어 명령어가 전혀 작동하지 않습니다.

2. 서버 초대 링크(OAuth2) 발급

생성한 봇을 내 디스코드 서버로 참가시키기 위한 전용 인증 주소를 만들어야 합니다.

디스코드 개발자 포털 OAuth2 URL 제너레이터 설정

개발자 포털의 왼쪽 메뉴에서 OAuth2 - URL 재생기 메뉴로 진입합니다.
스코프 선택 창에서 bot 항목과 applications.commands 항목에 체크합니다.
아래에 활성화되는 Bot Permissions 목록에서 봇이 사용해야 할 세부 권한을 체크합니다. 테스트 용이라면 관리자 권한 하나만 체크해도 무방합니다.
맨 아래에 완성된 긴 URL 링크 주소를 복사하여 브라우저 주소창에 붙여넣습니다.
봇을 참가시킬 대상 서버를 선택하고 승인 절차를 마치면, 해당 서버의 멤버 목록에 봇 계정이 오프라인 상태로 추가됩니다.

3. 파이썬 설치와 개발 환경 세팅

디스코드 봇을 작동시키려면 우선 컴퓨터에 파이썬이 설치되어 있어야 합니다. 파이썬 설치부터 봇 구동에 필요한 필수 라이브러리 설치까지 순서대로 진행해 보겠습니다.

파이썬 설치하기

파이썬 공식 웹사이트에 접속해 노란색 다운로드 버튼을 눌러 설치 파일을 받습니다.
설치 파일을 실행합니다. 이때 Windows 사용자는 설치 창 맨 아래에 있는 Add python.exe to PATH 옵션을 반드시 체크해 주어야 합니다. 이 옵션을 켜지 않으면 이후 터미널에서 파이썬 명령어를 인식하지 못합니다.
macOS 사용자는 다운로드한 패키지 파일을 실행하고 안내에 따라 설치를 완료하면 됩니다.

설치 여부 확인하기

설치가 올바르게 되었는지 터미널에서 확인해 봅니다.

Windows: 작업 표시줄 검색창에 cmd(명령 프롬프트)를 입력해 실행합니다.
macOS: Command + Space를 눌러 스포트라이트를 켠 뒤 터미널을 검색해 실행합니다.

검은 창이 뜨면 아래 명령어를 입력하고 엔터를 누릅니다.

Windows:
```
python --version
```
macOS:
```
python3 --version
```

Python 3.12.x와 같이 설치된 버전 정보가 정상적으로 출력된다면 성공입니다.

디스코드 라이브러리 설치하기

파이썬이 준비되었다면 디스코드 봇 개발에 필요한 라이브러리를 설치할 차례입니다. 파이썬 패키지 매니저(pip)를 사용해 터미널에 아래 명령어를 입력합니다.

Windows:
```
pip install discord.py
```
macOS:
```
pip3 install discord.py
```

다운로드가 완료되면 코드를 작성하고 실행할 모든 준비가 끝납니다.

4. 디스코드 봇 구동 소스 코드 작성

파이썬과 라이브러리 설치를 마쳤다면, 이제 실제로 작동하는 봇 코드를 구현해 볼 차례입니다. 텍스트 에디터를 사용하여 bot.py라는 이름으로 파일을 저장하고 아래 코드를 입력합니다.

코드의 원활한 파악을 돕기 위해 주요 동작 지점마다 가독성 높은 한국어 설명을 함께 기재해 두었습니다.

import logging
import discord
from discord.ext import commands

# 봇 작동 로그를 터미널에 실시간으로 기록하기 위한 로깅 기본 설정
logging.basicConfig(level=logging.INFO)

# 봇이 수신해야 하는 보안 인텐트 권한 설정
intents = discord.Intents.default()
intents.message_content = True  # 메시지 내용 파싱 허용

# 명령어 시작 접두사를 느낌표(!)로 지정하여 봇 객체 생성
bot = commands.Bot(command_prefix='!', intents=intents)

@bot.event
async def on_ready():
    # 봇이 디스코드 게이트웨이에 정상 접속하여 로그인이 완료되면 실행됩니다.
    print(f'접속 완료: {bot.user.name} (ID: {bot.user.id})')
    print('------')

@bot.command()
async def ping(ctx):
    # 채팅창에 '!ping'을 입력하면 동작하는 명령어입니다.
    # 명령어가 전송된 채널에 동일하게 'pong'이라는 답장을 발송합니다.
    await ctx.send('pong')

@bot.event
async def on_command_error(ctx, error):
    # 사용자가 등록되지 않은 명령어를 입력하거나 권한이 없을 때 에러 로그를 제어합니다.
    if isinstance(error, commands.CommandNotFound):
        await ctx.send('존재하지 않는 명령어입니다. 접두사나 철자를 다시 확인해 주세요.')
    else:
        print(f'예기치 못한 오류 발생: {error}')

# 발급받은 봇 토큰 값을 이곳에 문자열로 대입합니다.
bot.run('YOUR_BOT_TOKEN_HERE')

코딩이 완료되었다면 터미널 창에 다음 명령어를 입력하여 프로그램을 실행합니다.

python bot.py

접속 완료 로그가 확인되고, 디스코드 서버 내에서 봇 계정이 온라인 상태로 전환되는지 체크합니다. 대화창에 !ping을 입력했을 때 봇이 막힘없이 pong으로 화답한다면 기본적인 골격 세팅이 잘 끝난 셈입니다.

5. 토큰 유출 방지를 위한 환경 변수 세팅

기본 봇 연결에 성공했더라도, 작성한 소스 코드 내부에 토큰 값을 텍스트 형태로 직접 적어 두는 행위는 보안상 대단히 위험합니다. 디스코드 봇 토큰은 그 자체로 봇의 모든 권한을 조종할 수 있는 마스터키이기 때문인데요.

만약 봇의 관리 코드를 깃허브(GitHub) 같은 공개 소스코드 저장소에 부주의하게 올렸다가 토큰이 외부 유출될 경우, 악성 프로그램들이 봇의 제어권을 가져가 서버에 무단 스팸 링크를 뿌리는 등의 큰 금전적/정신적 피해가 발생하기 쉽습니다.

이 같은 사고를 원천 방지하기 위해 프로그램 내 코드가 아닌, 컴퓨터나 로컬 설정 파일에 값을 보관해 불러오는 환경 변수(Environment Variable) 방식으로 관리해야 합니다.

python-dotenv 라이브러리 연동

터미널을 열고 환경 변수 연동 모듈을 추가합니다.

# Windows
pip install python-dotenv

# macOS
pip3 install python-dotenv

bot.py 파일과 같은 폴더 내에 .env라는 이름의 파일을 새로 생성합니다. 확장자 명 없이 오직 .env 자체로만 만들어야 합니다.
.env 파일 내에 봇의 실제 토큰 값을 적고 저장합니다.

DISCORD_TOKEN=발급받은_디스코드_봇_토큰_값

소스 코드 파이썬 파일(bot.py) 상단으로 돌아가 환경 변수 관리 코드로 덮어씌워 줍니다.

import os
import discord
from discord.ext import commands
from dotenv import load_dotenv

# 동일 폴더에 위치한 .env 파일의 변수 로드
load_dotenv()
token = os.getenv('DISCORD_TOKEN')

intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(command_prefix='!', intents=intents)

@bot.event
async def on_ready():
    print(f'{bot.user.name} 봇 구동이 완료되었습니다.')

@bot.command()
async def ping(ctx):
    await ctx.send('pong')

# 외부 파일에서 안전하게 로드한 환경 변수 토큰값으로 구동
bot.run(token)

소스코드 백업 시 주의사항

코드를 GitHub이나 외부 서버에 업로드하여 관리할 때는, 토큰 값이 들어 있는 .env 파일은 절대 전송 대상에 포함하지 말아야 합니다. 프로젝트 최상위 폴더에 .gitignore 파일을 만들고 아래 코드를 기입해 두면 불필요한 정보 유출을 깔끔하게 예방할 수 있습니다.

.env
__pycache__/
*.pyc

6. 오작동 시 대처하는 자가 진단 방법

구동 과정에서 에러 로그가 출력되거나 반응하지 않을 때의 대표적인 디버깅 방식입니다.

LoginFailure: Improper token has been passed.: 대입된 토큰 문자열이 유효하지 않거나 중간에 철자가 틀린 경우입니다. 개발자 포털의 Bot 탭으로 들어가 토큰을 다시 재발급(Reset Token)받아 .env 파일에 갱신해 줍니다.
PrivilegedIntentsRequired: 인텐트 승인 설정이 누락되어 연결이 거부된 상태입니다. 디스코드 개발자 포털의 Bot 메뉴로 이동해 Privileged Gateway Intents 하단의 스위치(특히 Message Content Intent)가 켜져 있는지 확인합니다.
터미널에는 로그가 정상적으로 출력되나 인게임에서 무반응인 경우: 봇이 접속한 채널의 채팅 읽기 권한이나 메시지 쓰기 권한이 봇 역할에 부여되어 있는지 채널 설정의 권한 설정을 확인합니다.

파이썬을 올바르게 설치하고, 디스코드 라이브러리를 활용해 코딩한 뒤, 환경 변수 파일 분리를 통한 안전한 코드로 정비하는 것이 봇 구동의 정석이자 안전한 세팅입니다. 24시간 동안 안정적으로 구동될 파이썬 봇을 위한 밑바탕 세팅을 성공적으로 해두셨기를 기대합니다.

타임스탬프 생성기

웹훅 제너레이터

임베드 빌더

마크다운 에디터

봇 권한 계산기