디스코드 봇 만들기 시리즈 총정리 - #1부터 #24까지 순서대로 보는 로드맵! (파이썬 discord.py) 🗺️

안녕하세요! Mojangcam입니다 😎

첫 편을 올린 게 2025년 4월이었는데, 디스코드 봇 만들기 시리즈가 어느새 24편이 됐어요. 그러다 보니 이런 메시지를 종종 받습니다.

"어디부터 봐야 해요? 글이 너무 많아서 길을 잃었어요 😵"

그래서 오늘은 새 기능을 만드는 대신 지도 한 장을 그려드릴게요. 이 글 하나만 즐겨찾기 해두면 필요한 편으로 바로 점프할 수 있어요 🗺️

이 글에서 얻어갈 것

• 24편 전체를 어떤 순서로 읽어야 하는지 (단계별 로드맵)
• "나는 이게 만들고 싶은데?" → 목적별로 바로 찾아가기
• 처음 오신 분을 위한 3분 만에 봇 띄우는 최소 코드
• 막혔을 때 볼 에러 해결 글 모음

⭐ 요즘 제일 많이 찾는 글 TOP 5

급하신 분들을 위해 검색으로 가장 많이 들어오시는 글부터 모아뒀어요.

1. 디스코드 봇 만들기 #18 - 투표(Poll) 기능 만들기! 다수결로 정하는 서버 규칙 — 이모지 반응 세지 마세요! discord.Poll 로 네이티브 투표 올리기
2. 디스코드 봇 24시간 무료 호스팅 총정리 (2026) - 아직 되는 곳 vs 이제 안 되는 곳 — "컴퓨터 끄면 봇도 죽어요" 해결편
3. 디스코드 임베드(Embed) 완전정복 - 메시지 꾸미기 메서드·제한값 총정리 — 글자수 제한까지 한 장에 정리한 레퍼런스
4. 디스코드 봇 오류 해결 총정리 - intents·token 에러부터 봇이 반응 없을 때까지 — 막혔을 때 제일 먼저 열어보는 글
5. 디스코드 봇 만들기 #24 - 채널 난독화(Channel Obfuscation) 대응하기! — ⚠️ 2026년 11월 16일부터 적용되는 변경, 미리 대비해두세요

📌 준비물 (처음 오셨다면 여기부터)

• Python 3.8 이상 — discord.py 2.7.1 기준 최소 3.8이에요 (3.11 이상 권장)
• discord.py 2.7.1 — 작성일 기준 최신 버전
• python-dotenv 1.2.3 — 봇 토큰을 코드 밖으로 빼기 위해 꼭 필요해요
• 디스코드 개발자 포털 계정 — 봇 생성 + 토큰 발급용

pip install discord.py python-dotenv

설치가 끝났으면 버전을 한 번 확인해 볼게요.

python -c "import discord; print(discord.__version__)"
# 2.7.1

📌 3분 만에 봇 띄우기 (복붙 OK)

시리즈를 처음 보신다면, 일단 이 코드로 봇이 살아있는 것부터 확인하고 시작하세요. 슬래시 명령어 /핑 하나만 있는 최소 봇이에요.

먼저 스크립트와 같은 폴더에 .env 파일을 만들어요.

DISCORD_TOKEN=여기에_봇_토큰을_붙여넣기

그리고 .gitignore 에 반드시 추가하세요.

.env
__pycache__/

# bot.py
# discord.py 2.7.1 / python-dotenv 1.2.3 / Python 3.8+
import os

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

load_dotenv()                       # .env 파일을 읽어 환경변수로 등록
TOKEN = os.getenv("DISCORD_TOKEN")  # 토큰은 코드에 남기지 않아요

intents = discord.Intents.default()
bot = commands.Bot(command_prefix="!", intents=intents)

@bot.event
async def on_ready():
    await bot.tree.sync()           # 슬래시 명령어를 디스코드에 등록
    print(f"로그인 완료: {bot.user}")

@bot.tree.command(name="핑", description="봇이 살아있는지 확인해요")
async def ping(interaction: discord.Interaction):
    await interaction.response.send_message(
        f"퐁! 🏓 지연시간 {round(bot.latency * 1000)}ms"
    )

if __name__ == "__main__":
    if not TOKEN:
        raise SystemExit("❌ .env 파일에 DISCORD_TOKEN이 없어요!")
    bot.run(TOKEN)

하나씩 뜯어볼게요 💡

• load_dotenv() : 같은 폴더의 .env 를 읽어 환경변수로 올려줘요. 이 한 줄 덕분에 코드에 토큰을 적을 일이 없어집니다.
• os.getenv("DISCORD_TOKEN") : 토큰을 환경변수에서 꺼내옵니다. 코드에 토큰을 박아두고 깃허브에 올리면 디스코드가 자동으로 감지해서 토큰을 폐기해버려요 😱
• Intents.default() : 봇이 받아볼 이벤트 묶음이에요. 메시지 내용을 읽거나 멤버 목록이 필요하면 개발자 포털에서 특권 인텐트(Privileged Intent) 를 따로 켜야 해요.
• bot.tree.sync() : 슬래시 명령어를 디스코드 서버에 등록합니다. 글로벌 동기화는 반영까지 시간이 걸릴 수 있어서, 테스트할 땐 특정 서버에만 동기화하는 게 훨씬 빨라요.
• if not TOKEN : 토큰을 안 넣었을 때 조용히 실패하지 않고 바로 알려주게 만든 안전장치예요.

여기까지 됐다면 준비 끝! 이제 아래 지도를 따라가면 됩니다 🙌

📌 1단계 - 슬래시 명령어 기초 (#1~#4)

봇의 입과 귀를 만드는 구간이에요. 여기 4편은 순서대로 보시는 걸 권합니다.

📌 2단계 - 눌러서 쓰는 UI (#5~#8)

명령어만으로는 심심하죠. 사용자가 클릭하고 입력하는 봇으로 업그레이드하는 구간이에요.

📌 3단계 - 기능 붙이기 (#9~#18)

여기서부터는 필요한 편만 골라 봐도 괜찮아요. 서로 독립적인 기능들이거든요.

📌 4단계 - 실전 구조와 운영 (#19~#24)

기능이 쌓이면 구조가 문제가 됩니다. 여기부터는 "돌아가는 봇"을 "오래 가는 봇"으로 만드는 구간이에요 🏗️

🧩 목적별로 골라 읽기 (디스코드 봇 명령어 모음 지도)

"나는 이게 만들고 싶은데?" 하시는 분들을 위한 지름길이에요.

• 서버 규칙·일정을 투표로 정하고 싶어요 → #18
• 문의·신청 양식을 받고 싶어요 → #7 (모달) + #4 (임베드)
• AI가 대답하는 봇을 만들고 싶어요 → #9 → #17 (RAG로 확장)
• 새 멤버를 자동으로 맞이하고 싶어요 → #20
• 욕설·광고를 자동으로 지우고 싶어요 → #21 → #22 (금지어를 명령어로 관리)
• 봇이 재시작하면 데이터가 사라져요 → #14 (개념) → #23 (실전 DB 설계)
• 코드가 너무 길어졌어요 → #19 (Cog 구조)
• 24시간 켜두고 싶어요 → 아래 번외편 3개를 순서대로 보세요

💡 번외편 - 시리즈 밖이지만 꼭 필요한 글

• 디스코드 봇 24시간 무료 호스팅 총정리 (2026) — 무료로 버틸 수 있는 선택지 비교
• 파이썬 VPS 배포 입문 (Ubuntu + systemd) — 매달 몇천 원으로 안정적으로 돌리기
• 라즈베리파이로 디스코드 봇 24시간 돌리기 🍓 — 한 번 사두면 월세가 안 나가요
• 디스코드 임베드(Embed) 완전정복 — 옆에 띄워두고 보는 레퍼런스
• 파이썬 업무 자동화 #4 - 디스코드 웹훅(Webhook)으로 알림 보내기 — 봇 없이 알림만 필요할 때

📌 자주 나는 에러 (시리즈 전체 공통)

1. discord.errors.LoginFailure: Improper token has been passed

• 원인: 토큰이 잘못됐거나 .env 를 못 읽은 경우예요. 특히 토큰을 깃허브에 올렸다가 자동 폐기된 경우가 많아요.
• 해결: 개발자 포털에서 토큰을 재발급하고 .env 에 넣으세요. print(os.getenv("DISCORD_TOKEN")) 로 값이 None 인지 먼저 확인!

2. .env 를 만들었는데 값이 None 이에요

• 원인: load_dotenv() 를 os.getenv() 뒤에 호출했거나, .env 가 다른 폴더에 있어요.
• 해결: load_dotenv() 는 항상 파일 상단, os.getenv() 보다 먼저 실행되게 하세요. 실행 위치가 헷갈리면 load_dotenv(override=True) 로 확인해보셔도 좋아요.

3. 슬래시 명령어가 디스코드에 안 떠요

• 원인: bot.tree.sync() 를 호출하지 않았거나, 글로벌 동기화 반영을 기다리는 중이에요.
• 해결: 테스트 서버 하나만 지정해 동기화하면 즉시 반영돼요. 봇 초대 시 applications.commands 스코프를 체크했는지도 확인하세요.

4. PrivilegedIntentsRequired 에러가 나요

• 원인: 메시지 내용·멤버 목록처럼 특권 인텐트가 필요한 기능을 켰는데, 개발자 포털에서 허용을 안 한 상태예요.
• 해결: Developer Portal → Bot → Privileged Gateway Intents 에서 필요한 항목을 켜주세요.

더 많은 사례는 디스코드 봇 오류 해결 총정리 편에 모아뒀어요!

💬 마무리

오늘은 코드 대신 지도를 그렸어요. 정리하면요 👇

• #1~#4 슬래시 명령어로 봇의 기본기 만들기 (순서대로 보기)
• #5~#8 버튼·드롭다운·모달·임베드로 UI 붙이기
• #9~#18 필요한 기능만 골라서 붙이기
• #19~#24 Cog·DB·정책 대응으로 오래 가는 봇 만들기
• 토큰은 언제나 .env 로! 코드에 박아두지 않기 🔐

24편을 다 따라오셨다면 이제 커뮤니티 통합 관리 봇 한 대가 손에 남아 있을 거예요. 정말 고생 많으셨어요 🙌

다음 편에서는 시리즈를 잠깐 쉬고, 요즘 쏟아지는 새 AI 코딩 툴들을 직접 써본 체험기를 들고 올게요. 기대해주세요!

📚 디스코드 봇 만들기 시리즈

• #1~#24 전체 목록 보기 (카테고리)
• 시리즈 총정리 (로드맵) ← 지금 이 글!