파이썬 디스코드 봇 만들기 처음부터 끝까지, discord.py 입문 가이드

파이썬으로 디스코드 봇을 처음 만들 때 가장 많이 막히는 구간은 코드보다 세팅 쪽입니다.

Developer Portal에서 봇 생성, 토큰 보관, 권한과 인텐트 설정, 서버 초대까지 흐름을 한 번에 잡아야 곧바로 실행으로 넘어갈 수 있습니다.

디스코드 봇 개발의 전 과정을 한 번에 끝내는 입문 가이드입니다.

discord.py 라이브러리로 기본 명령어가 동작하는 파이썬 디스코드 봇 하나를 바로 만들어 보겠습니다.

!핑, !서버정보, !청소 명령어까지 넣어 두었기 때문에 파일만 만들고 실행하면 즉시 테스트 가능합니다.

기본 구조를 익힌 뒤에는 AI 기능 붙이기, 권한 구조 정리, 슬래시 명령어 전환 순서로 넓혀 가면 됩니다.

1. 먼저 준비할 것

작업 전에 파이썬 3.10 이상, 디스코드 계정, 코드를 작성할 폴더 하나를 준비합니다.

운영체제가 macOS든 Windows든 흐름은 거의 같습니다.

결과물 구조는 아래와 같습니다.

my-discord-bot/
├─ .env
└─ main.py

`.env`는 토큰을 숨기는 파일, `main.py`는 실제 봇 코드가 들어가는 파일입니다.
토큰을 코드에 그대로 적으면 나중에 깃허브 업로드나 화면 공유 중에 유출될 수 있으니 처음부터 분리하는 편이 안전합니다.

2. Discord Developer Portal에서 봇 만들기

브라우저에서 Discord Developer Portal에 접속합니다.

오른쪽 위의 New Application 버튼을 누르고 봇 이름을 입력한 뒤 애플리케이션을 생성합니다.

생성을 마쳤다면 왼쪽 메뉴에서 Bot 탭으로 이동합니다.

여기서 Reset Token 또는 Copy 버튼으로 봇 토큰을 발급받을 수 있습니다.

토큰은 봇의 통제권을 가진 비밀번호입니다.

깃허브 업로드, 화면 공유, 메신저 전송 과정에서 실수로 노출되지 않게 주의해야 합니다.

유출이 의심되면 바로 Reset Token을 눌러 기존 토큰을 폐기합니다.

같은 화면에서 Message Content Intent를 켜 둡니다.

지금 단계에서는 !핑, !청소 같은 메시지 기반 명령어를 사용하므로 이 설정이 꺼져 있으면 봇이 명령어를 읽지 못합니다.

이 단계에서 빠뜨리는 경우가 매우 많습니다.

3. 봇을 서버에 초대할 링크 만들기

왼쪽 메뉴에서 OAuth2 -> URL Generator로 이동합니다.

SCOPES에서는 bot을 체크합니다.

지금 단계에서는 슬래시 명령어를 사용하지 않으므로 applications.commands는 필수가 아닙니다.

아래 BOT PERMISSIONS에서는 최소한 다음 권한을 체크합니다.

• View Channels
• Send Messages
• Read Message History
• Manage Messages

Manage Messages는 !청소 명령어를 테스트할 때 필요합니다.

이 권한이 없으면 봇이 온라인 상태여도 메시지 삭제는 수행하지 못합니다.

화면 아래쪽에 생성된 URL을 복사해서 브라우저에 붙여넣고, 봇을 추가할 서버를 선택합니다.

초대까지 마치면 서버 멤버 목록에서 봇을 확인할 수 있습니다.

4. 프로젝트 폴더 만들고 패키지 설치하기

VS Code에서 새 폴더를 열고 터미널을 실행합니다.

가상환경까지 같이 만드는 흐름으로 잡아 두면 나중에 패키지 충돌이 적습니다.

mkdir my-discord-bot
cd my-discord-bot
python3 -m venv .venv
source .venv/bin/activate
pip install -U discord.py python-dotenv

Windows에서는 가상환경 활성화 명령어만 다릅니다.

python -m venv .venv
.venv\Scripts\activate
pip install -U discord.py python-dotenv

`discord.py`는 디스코드 API와 통신하는 핵심 라이브러리입니다.
`python-dotenv`는 `.env` 파일에 저장한 토큰을 코드에서 읽어오는 용도입니다.

5. .env 파일에 토큰 보관하기

프로젝트 폴더 안에 .env 파일을 만들고 아래처럼 작성합니다.

DISCORD_TOKEN=여기에_Developer_Portal_토큰_붙여넣기
PREFIX=!

`PREFIX`는 명령어 앞에 붙는 문자입니다.
`!핑`, `!청소`처럼 느낌표 기반 명령어를 사용할 계획이므로 `!`로 설정합니다.

.env를 제대로 읽지 못하면 Improper token has been passed나 로그인 실패가 발생할 수 있습니다.

공백이 같이 들어갔는지, 큰따옴표를 썼는지, 토큰 앞뒤에 줄바꿈이 붙었는지부터 확인하면 됩니다.

6. main.py 전체 코드 작성하기

main.py 파일을 만들고 아래 코드를 그대로 넣습니다.

주석까지 포함한 완성본이라 바로 실행해도 됩니다.

import os

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

# .env 파일에서 토큰과 접두사를 읽어옵니다.
load_dotenv()
TOKEN = os.getenv("DISCORD_TOKEN")
PREFIX = os.getenv("PREFIX", "!")

# 메시지 기반 명령어를 읽으려면 message_content 인텐트가 필요합니다.
intents = discord.Intents.default()
intents.message_content = True

# commands.Bot은 명령어 처리 기능이 포함된 봇 클래스입니다.
bot = commands.Bot(command_prefix=PREFIX, intents=intents, help_command=None)


@bot.event
async def on_ready():
    print(f"로그인 성공: {bot.user} (ID: {bot.user.id})")
    print("봇이 정상적으로 켜졌습니다.")


@bot.command(name="핑")
async def ping(ctx: commands.Context):
    latency_ms = round(bot.latency * 1000)
    await ctx.send(f"퐁, 현재 지연 시간은 {latency_ms}ms 입니다.")


@bot.command(name="도움")
async def help_command(ctx: commands.Context):
    help_text = (
        "사용 가능한 명령어\n"
        f"{PREFIX}핑 - 봇 응답 속도 확인\n"
        f"{PREFIX}서버정보 - 현재 서버 정보 확인\n"
        f"{PREFIX}청소 숫자 - 최근 메시지 정리\n"
    )
    await ctx.send(f"```\n{help_text}```")


@bot.command(name="서버정보")
async def server_info(ctx: commands.Context):
    guild = ctx.guild

    if guild is None:
        await ctx.send("이 명령어는 서버 채널에서만 사용할 수 있습니다.")
        return

    embed = discord.Embed(
        title="서버 정보",
        color=discord.Color.blue(),
    )
    embed.add_field(name="서버 이름", value=guild.name, inline=False)
    embed.add_field(name="멤버 수", value=str(guild.member_count), inline=True)
    embed.add_field(name="채널 수", value=str(len(guild.channels)), inline=True)
    embed.add_field(name="서버장", value=str(guild.owner), inline=False)

    if guild.icon:
        embed.set_thumbnail(url=guild.icon.url)

    await ctx.send(embed=embed)


@bot.command(name="청소")
@commands.has_permissions(manage_messages=True)
async def clear_messages(ctx: commands.Context, amount: int = 5):
    if amount < 1 or amount > 100:
        await ctx.send("청소 개수는 1 이상 100 이하로 입력하세요.")
        return

    deleted = await ctx.channel.purge(limit=amount + 1)
    notice = await ctx.send(f"메시지 {len(deleted) - 1}개를 삭제했습니다.")
    await notice.delete(delay=3)


@clear_messages.error
async def clear_messages_error(ctx: commands.Context, error: Exception):
    if isinstance(error, commands.MissingPermissions):
        await ctx.send("이 명령어는 메시지 관리 권한이 있는 사용자만 사용할 수 있습니다.")
        return

    if isinstance(error, commands.BadArgument):
        await ctx.send(f"사용 예시: {PREFIX}청소 10")
        return

    raise error


if not TOKEN:
    raise ValueError("DISCORD_TOKEN 값이 .env 파일에 없습니다.")

bot.run(TOKEN)

핵심은 `commands.Bot`입니다.
일반 `discord.Client`보다 명령어를 다루기 쉬워 입문 단계에서는 이 구조가 더 직관적입니다.
`@bot.command()` 데코레이터를 붙이면 `!핑`, `!서버정보` 같은 명령어를 빠르게 추가할 수 있습니다.

!청소 명령어에는 @commands.has_permissions(manage_messages=True)를 붙였습니다.

아무나 메시지를 지우지 못하게 막는 권한 조건입니다.

봇 기능을 만들 때는 동작 자체보다 권한 조건을 같이 설계하는 습관이 중요합니다.

7. 봇 실행하기

터미널에서 아래 명령어를 실행합니다.

python main.py

macOS나 일부 환경에서는 아래 명령어가 더 잘 맞을 수 있습니다.

python3 main.py

정상 실행되면 터미널에 `로그인 성공` 문구가 출력됩니다.
디스코드 서버 채널로 이동해서 아래 명령어를 하나씩 입력해 봅니다.

!핑
!도움
!서버정보
!청소 3

`!청소 3`은 최근 메시지 3개를 삭제합니다.
테스트는 일반 채널보다 별도 테스트 채널에서 진행하는 편이 안전합니다.

8. 자주 막히는 구간

처음 만들 때는 아래 구간에서 많이 멈춥니다.

• Message Content Intent 활성화 누락:
  
  Bot 탭에서 이 설정을 켜지 않으면 봇이 온라인으로 보여도 !핑 같은 메시지 명령어에는 반응하지 않습니다.
  
  코드는 멀쩡한데 봇이 조용하면 가장 먼저 여기부터 확인하면 됩니다.
• 봇 권한 부족:
  
  특히 !청소 명령어는 봇에게 Manage Messages 권한이 있어야 하고, 명령어를 실행하는 사용자도 메시지 관리 권한이 있어야 합니다.
  
  권한 구조가 헷갈리면 봇 역할보다 위에 관리자 역할을 올려 두지 않았는지도 같이 확인합니다.
• 토큰 복사 오류:
  
  토큰 앞뒤 공백, 잘못 복사한 문자열, 재발급 후 예전 토큰을 그대로 둔 경우가 많습니다.
  
  .env 값을 다시 붙여넣고 필요하면 포털에서 토큰을 재발급한 뒤 다시 테스트합니다.

9. 여기서 다음으로 이어갈 만한 글

기본 봇 세팅은 끝났습니다.

다음 단계에서는 AI 답변 기능을 붙이거나, 슬래시 명령어 구조로 바꾸거나, 서버 권한 구조를 정리하는 쪽으로 확장하면 됩니다.

10. 24시간 호스팅으로 실제 운영하기

지금 만든 봇은 내 컴퓨터에서 터미널을 켠 동안만 돌아갑니다.

노트북을 닫거나 전원을 끄면 봇도 같이 멈춥니다.

서버 유저들이 하루 종일 봇을 쓰게 하려면 별도 서버에 올려서 24시간 실행해야 합니다.

배포 단계까지 바로 이어서 진행하려면 24시간 디스코드 봇 무료 호스팅, 디스호스트 글을 참고해서 방금 만든 main.py와 .env를 서버에 올리면 됩니다.