슬래시 명령어 디스코드 봇 만드는 법, 파이썬 discord.py app_commands 입문

discord.py로 슬래시 명령어를 붙이려는데 /핑조차 안 뜨거나 app_commands 구조가 헷갈리면 여기서 많이 막힙니다.

이 글에서는 discord.py의 app_commands 기준으로 /핑, /서버정보, /청소 세 개를 바로 테스트할 수 있는 형태까지 한 번에 정리합니다.

즉 이 글 하나로 슬래시 명령어 등록, 서버 단위 sync, 기본 권한 체크 흐름까지 바로 잡을 수 있습니다.

1. 먼저 준비할 것

기본 파이썬 봇 구조와 토큰 분리는 이미 끝났다고 가정합니다.

아직 이 단계가 안 됐다면 파이썬 디스코드 봇 만들기 처음부터 끝까지와 .env 환경변수로 디스코드 토큰 숨기기, 하드코딩 없이 안전하게 관리하는 법부터 먼저 봐야 합니다.

2. 초대 링크에서 applications.commands를 체크한다

슬래시 명령어는 일반 bot 스코프만으로는 부족할 수 있습니다.

초대 링크를 만들 때 applications.commands도 같이 체크합니다.

기본적으로 아래 스코프 조합을 씁니다.

bot
applications.commands

이 단계가 빠지면 코드가 맞아도 슬래시 명령어가 보이지 않을 수 있습니다.

3. 설치

프로젝트 폴더에서 아래 명령어를 실행합니다.

pip install -U discord.py python-dotenv

기본 봇을 만든 상태라면 이미 설치되어 있을 가능성이 큽니다.
버전이 애매하면 `-U` 옵션으로 한 번 더 올려야 합니다.

4. .env 파일 예시

DISCORD_TOKEN=여기에_봇_토큰
GUILD_ID=테스트할_서버_ID

처음에는 글로벌 명령어보다 특정 서버에만 등록하는 방식이 훨씬 빠릅니다.
`GUILD_ID`를 넣어 두면 명령어 반영 속도가 빠릅니다.

5. main.py 전체 코드

아래 코드를 그대로 넣으면 됩니다.

import os

import discord
from discord import app_commands
from dotenv import load_dotenv

load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")
GUILD_ID = int(os.getenv("GUILD_ID"))

intents = discord.Intents.default()
client = discord.Client(intents=intents)
tree = app_commands.CommandTree(client)
guild = discord.Object(id=GUILD_ID)


@client.event
async def on_ready():
    await tree.sync(guild=guild)
    print(f"로그인 성공: {client.user}")
    print("슬래시 명령어 동기화 완료")


@tree.command(name="핑", description="봇 응답 속도를 확인합니다.", guild=guild)
async def ping(interaction: discord.Interaction):
    latency_ms = round(client.latency * 1000)
    await interaction.response.send_message(f"퐁, 현재 지연 시간은 {latency_ms}ms 입니다.")


@tree.command(name="서버정보", description="현재 서버 정보를 보여줍니다.", guild=guild)
async def server_info(interaction: discord.Interaction):
    current_guild = interaction.guild

    if current_guild is None:
        await interaction.response.send_message("이 명령어는 서버에서만 사용할 수 있습니다.", ephemeral=True)
        return

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

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

    await interaction.response.send_message(embed=embed)


@tree.command(name="청소", description="최근 메시지를 정리합니다.", guild=guild)
@app_commands.describe(amount="삭제할 메시지 개수")
async def clear_messages(interaction: discord.Interaction, amount: int):
    if not interaction.user.guild_permissions.manage_messages:
        await interaction.response.send_message(
            "메시지 관리 권한이 있는 사용자만 사용할 수 있습니다.",
            ephemeral=True,
        )
        return

    if amount < 1 or amount > 100:
        await interaction.response.send_message(
            "삭제 개수는 1 이상 100 이하로 입력하세요.",
            ephemeral=True,
        )
        return

    await interaction.response.defer(ephemeral=True)
    deleted = await interaction.channel.purge(limit=amount)
    await interaction.followup.send(f"메시지 {len(deleted)}개를 삭제했습니다.", ephemeral=True)


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

client.run(TOKEN)

슬래시 명령어 구조에서는 `commands.Bot` 대신 `CommandTree`를 중심으로 생각하면 됩니다.
명령어를 등록한 뒤 `tree.sync()`를 호출해야 실제 서버에 반영됩니다.

6. 서버 ID 확인 방법

디스코드 앱에서 사용자 설정 -> 고급 -> 개발자 모드를 켭니다.

그다음 서버 아이콘을 우클릭해서 ID 복사를 누르면 됩니다.

처음에는 글로벌 배포보다 서버 단위 테스트가 훨씬 빠릅니다.

명령어가 1시간씩 안 보이는 상황을 피하기 좋습니다.

7. 테스트하기

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

python main.py

디스코드 채팅창에서 `/`를 입력하면 명령어 목록에 `/핑`, `/서버정보`, `/청소`가 보여야 합니다.
안 보이면 아래 구간을 먼저 봅니다.

• 초대 링크에 applications.commands가 들어갔는가
• tree.sync(guild=guild)가 실제로 호출되는가
• GUILD_ID가 맞는가
• 봇을 재시작했는가

8. 자주 막히는 문제

• 명령어가 안 보이는 경우: 서버 ID가 틀렸거나 sync가 안 된 경우가 많습니다.
• This interaction failed가 뜨는 경우: 응답 시간을 넘겼거나, interaction.response를 제대로 처리하지 않은 경우가 많습니다.
• /청소가 실패하는 경우: 사용자 권한이나 봇 권한 둘 중 하나가 부족할 수 있습니다.

슬래시 명령어 쪽은 코드보다 sync와 권한에서 많이 막힙니다.

9. 메시지 명령어와 같이 써도 된다

처음부터 완전히 갈아탈 필요는 없습니다.

메시지 명령어 봇을 먼저 만든 뒤 슬래시 명령어를 일부 기능부터 옮겨 가는 방식도 흔합니다.

입문 단계에서는 이 흐름이 더 편합니다.

10. 다음 단계

슬래시 명령어 기본형이 붙었다면 다음에는 초대 링크와 토큰 관리 쪽을 같이 맞춰야 막힘이 적습니다.

바로 이어서 볼 글은 디스코드 봇 권한 설정법, 디스코드 봇 초대 링크 생성법, 권한이 꼬이지 않게 링크 만드는 방법, .env 환경변수로 디스코드 토큰 숨기기, 하드코딩 없이 안전하게 관리하는 법입니다.