디스코드 봇 슬래시 커맨드가 안 보일 때 해결법

/핑까지 다 만들었는데 채팅창에 명령어 목록이 아예 안 뜨면, 그때는 권한보다 등록과 초대 흐름을 먼저 의심해야 합니다.

이 상태에서 코드를 계속 뜯어봐도 허탕인 경우가 많습니다.

지금 글은 슬래시 명령어가 "실행 실패"가 아니라 "목록에 아예 안 보이는" 상황만 빠르게 좁히는 글입니다.

기본 슬래시 명령어 구조를 아직 안 만들었다면 슬래시 명령어 디스코드 봇 만드는 법, 파이썬 discord.py app_commands 입문부터 먼저 맞춰 둬야 합니다.

1. 목록에 안 뜨면 등록 경로부터 본다

가장 먼저 확인할 항목입니다.

이 스코프가 빠지면 서버에 봇은 들어와 있어도 슬래시 명령어가 등록되지 않거나 보이지 않을 수 있습니다.

초대 링크에서 아래 둘을 같이 체크합니다.

bot
applications.commands

초대 링크를 잘못 만들었다면 새 링크로 다시 승인하면 빠릅니다.

2. 서버 단위 sync인지 글로벌 sync인지 구분한다

입문 단계에서 가장 많이 헷갈리는 부분입니다.

서버 단위 sync는 반영이 빠릅니다.

글로벌 sync는 시간이 꽤 걸릴 수 있습니다.

테스트 단계라면 보통 아래처럼 서버 ID를 넣고 동기화합니다.

guild = discord.Object(id=GUILD_ID)

@client.event
async def on_ready():
    await tree.sync(guild=guild)
    print("sync 완료")

코드는 맞는데 안 뜨는 경우, 실제로는 글로벌 반영을 기다리느라 시간을 버리는 사례가 많습니다.

3. 봇을 재초대할 필요가 있는 경우도 있다

예전에 bot 스코프만으로 초대해 둔 봇이라면 이후 코드만 바꿔도 명령어가 안 뜰 수 있습니다.

이때는 새 권한과 스코프로 다시 초대해야 빠릅니다.

기존 봇을 그냥 두고 코드만 다시 실행해도 해결되지 않는 경우가 여기서 자주 나옵니다.

4. GUILD_ID가 실제 테스트 서버와 맞는지 확인한다

서버 단위 sync를 쓰면서 다른 서버 ID를 넣어 두는 실수가 흔합니다.

특히 테스트 서버와 운영 서버를 둘 다 갖고 있으면 자주 꼬입니다.

Developer Mode를 켠 뒤 서버 ID를 다시 복사해서 .env와 비교합니다.

한 자리만 달라도 명령어는 엉뚱한 서버에 등록됩니다.

5. on_ready는 떴는데 sync 로그가 없는 경우

on_ready는 찍히는데 실제 sync가 실패하는 경우도 있습니다.

이럴 때는 sync 직후 로그를 명확히 남겨 둬야 합니다.

@client.event
async def on_ready():
    synced = await tree.sync(guild=guild)
    print(f"동기화된 명령어 수: {len(synced)}")

로그가 없으면 어디서 끊겼는지 파악이 늦어집니다.

6. 코드 파일은 바꿨는데 실행 중인 프로세스는 예전 것일 수 있다

VS Code에서 코드를 수정했어도 터미널에 떠 있는 봇 프로세스를 재시작하지 않으면 예전 코드가 계속 도는 경우가 있습니다.

슬래시 명령어 쪽은 이 실수가 꽤 자주 나옵니다.

터미널을 끄고 다시 실행해서 sync 로그를 다시 봐야 가장 확실합니다.

7. 체크 순서

아래 순서대로 보면 웬만한 경우는 금방 잡힙니다.

1. applications.commands 스코프 확인
2. GUILD_ID 확인
3. tree.sync() 호출 여부 확인
4. 봇 재시작
5. 새 초대 링크로 재승인
6. 글로벌 sync인지 서버 sync인지 확인

처음에는 보통 1번, 2번, 3번에서 끝납니다.

8. 권한 문제와 등록 문제를 섞지 말 것

명령어가 아예 안 보이는 것은 등록 문제 쪽입니다.

명령어는 보이는데 실행이 실패하는 것은 권한 문제일 가능성이 큽니다.

둘을 섞어 보면 계속 엉뚱한 곳만 고치게 됩니다.

실행 권한까지 같이 정리하려면 디스코드 슬래시 명령어 권한 설정법을 이어서 보면 됩니다.

9. 안 보이는 문제와 보이는데 실패하는 문제를 분리한다

명령어 목록이 아예 안 뜬다면 이 글처럼 등록 경로를 끝까지 보는 게 맞습니다.

초대 링크, 기본 구조, 권한 설계는 디스코드 봇 초대 링크 생성법, 권한이 꼬이지 않게 링크 만드는 방법, 슬래시 명령어 디스코드 봇 만드는 법, 파이썬 discord.py app_commands 입문, 디스코드 슬래시 명령어 권한 설정법을 순서대로 보면 끊기지 않습니다.