디스코드 봇이 온라인인데 명령어가 안 되거나, 메시지를 못 보내거나, 역할을 못 주는 경우가 많습니다.
원인은 대개 코드보다 권한 구조입니다.
특히 Missing Permissions(50013)과 Missing Access(50001)는 봇을 처음 만들 때 거의 한 번씩 보게 됩니다.
권한 설정은 감으로 맞추면 계속 꼬입니다.
역할 순서, 채널 권한, 봇 초대 권한, 관리자 권한의 차이를 한 번에 이해해야 훨씬 빠릅니다.
1. 먼저 알아둘 것
디스코드 권한은 크게 세 층으로 움직입니다.
- 서버 역할 권한
- 채널별 덮어쓰기 권한
- 역할 순서에 따른 우선순위
봇이 어떤 작업을 하려면 코드만 맞는다고 끝나지 않습니다.
서버에서 해당 권한을 실제로 받아야 하고, 채널에서도 막히지 않아야 하며, 역할 순서도 대상보다 위에 있어야 합니다.
2. 가장 많이 헷갈리는 역할 순서
디스코드에서는 봇 역할이 대상 역할보다 아래에 있으면 역할 지급이나 닉네임 변경 같은 작업을 수행하지 못합니다.
여기서 가장 많이 막힙니다.
예를 들어 아래 순서라면 문제가 생깁니다.
관리자
운영진
멤버
봇이 상태에서 봇이 `멤버` 역할을 주려고 하면 실패할 수 있습니다.
봇 역할을 최소한 `멤버`보다 위로 올려야 합니다.
안전한 예시는 아래와 같습니다.
관리자
운영진
봇
멤버역할 지급, 닉네임 변경, 채널 관리 같은 작업을 시킬 계획이라면 봇 역할 위치부터 먼저 확인합니다.
3. 서버 권한과 채널 권한은 따로 본다
서버 역할에서 Send Messages를 허용해도 특정 채널에서 막혀 있으면 봇은 메시지를 보내지 못합니다.
반대로 서버 권한이 부족하면 채널에서 허용해도 동작하지 않을 수 있습니다.
즉, 아래 둘을 같이 봐야 합니다.
- 봇 역할 자체에 필요한 권한이 들어 있는가
- 해당 채널에서 봇 역할이 차단되어 있지 않은가
로그 채널, 공지 채널, 봇 명령어 채널은 특히 따로 확인해야 합니다.
4. 자주 쓰는 봇 권한
입문용 봇이라면 보통 아래 권한부터 시작합니다.
View Channels
Send Messages
Read Message History
Manage Messages
Embed Links
Attach Files
Use Slash Commands
Manage Roles모든 봇에 `Administrator` 권한을 주는 방식은 추천하지 않습니다.
테스트는 편하지만, 권한 문제가 생겼을 때 어디서 막혔는지 파악하기가 오히려 어려워집니다.
5. 봇 초대 링크에서 권한을 잘못 고르면 생기는 일
봇 초대 링크를 만들 때 필요한 권한을 너무 적게 체크하면 서버에 들어온 뒤 바로 기능이 제한됩니다.
반대로 너무 많이 열면 필요 없는 권한까지 갖게 됩니다.
초대 링크 생성 예시는 아래처럼 잡을 수 있습니다.
기본 응답 봇
- View Channels
- Send Messages
- Read Message History
관리 기능 포함 봇
- Manage Messages
- Manage Roles
- Use Slash Commands관리 기능을 넣을 계획이라면 초대 링크를 새로 만들어 다시 넣는 경우도 많습니다.
처음부터 필요한 범위를 어느 정도 계산해 두면 편합니다.
6. 50013과 50001 차이
둘은 비슷해 보이지만 결이 다릅니다.
Missing Permissions(50013):
작업 자체를 할 권한이 부족한 경우입니다.
예를 들어 메시지 삭제, 역할 지급, 닉네임 변경처럼 행동 권한이 부족할 때 자주 뜹니다.Missing Access(50001):
채널이나 서버 리소스에 접근 자체를 못 하는 경우입니다.
채널 보기 권한이 막혀 있거나 접근 가능한 위치가 아닐 때 많이 뜹니다.
실전에서는 역할 순서와 채널 보기 권한을 같이 확인하면 대부분 빨리 잡힙니다.
7. 점검 순서
권한 문제가 생기면 아래 순서로 보면 빠릅니다.
1. 봇 역할이 서버에 실제로 붙어 있는가
2. 봇 역할에 필요한 서버 권한이 켜져 있는가
3. 채널 덮어쓰기에서 봇 역할이 막혀 있지 않은가
4. 봇 역할이 대상 역할보다 위에 있는가
5. 봇을 초대한 링크에 필요한 권한이 포함되어 있는가이 다섯 개만 보면 웬만한 권한 문제는 정리됩니다.
8. 테스트용 코드로 바로 확인하기
권한이 실제로 통하는지 보려면 아래처럼 간단한 테스트 명령어를 만들어 두면 편합니다.
@bot.command(name="권한확인")
async def check_permissions(ctx):
permissions = ctx.channel.permissions_for(ctx.guild.me)
await ctx.send(
"\n".join(
[
f"send_messages={permissions.send_messages}",
f"manage_messages={permissions.manage_messages}",
f"manage_roles={permissions.manage_roles}",
f"view_channel={permissions.view_channel}",
]
)
)이 명령어를 봇 명령어 채널, 공지 채널, 로그 채널에서 각각 실행해 보면 채널마다 어느 권한이 막혀 있는지 바로 보입니다.
9. 초반에 꼭 기억할 것
권한 문제는 코드 수정으로 해결되지 않는 경우가 더 많습니다.
터미널 에러만 보지 말고 서버 설정 화면도 같이 보는 습관이 필요합니다.
특히 역할 순서와 채널 권한은 처음 한 번만 잘못 잡아도 뒤에서 계속 발목을 잡습니다.
봇 기능을 더 붙이기 전에 여기부터 정리해 둬야 합니다.
10. 다음 단계
기본 봇을 아직 만들지 않았다면 파이썬 디스코드 봇 만들기 처음부터 끝까지부터 보고 와야 합니다.
Message Content Intent 설정이 빠져 있으면 명령어가 아예 읽히지 않을 수 있으니 다음 글에서는 그 부분을 먼저 다루는 흐름이 자연스럽습니다.