디스코드 봇 에러 원인과 해결책 총정리: 역할과 권한 문제 완벽 가이드
디스코드 서버를 운영하다 보면 서버 관리나 유저 편의를 위해 다양한 자동화 봇을 추가하게 됩니다. 환영 메시지를 뿌려주는 봇부터 서버 보안을 책임지는 관리 봇까지 그 종류가 무척 다양한데요.
하지만 정작 봇을 서버에 추가한 뒤 명령어를 쳤을 때 봇 프로필에는 초록색 온라인 불이 켜져 있으면서도 묵묵부답으로 일관하는 오류를 자주 접하게 됩니다. 코딩 에러나 서버 다운이 아닌데도 봇이 응답하지 않으면 관리자 입장에서는 무척 답답하기 마련입니다.
봇이 정상적으로 작동하지 않을 때 운영자가 가장 먼저 확인해봐야 할 대표적인 권한 장애 요인과 해결 방법을 상세히 정리했습니다.
Q1. 봇 초대 링크 생성 시 부여하는 권한 숫자는 어떤 의미인가요?
봇을 내 서버로 참가시킬 때 사용하는 URL을 살펴보면 주소 끝부분에 permissions=8 혹은 permissions=2147483647과 같은 숫자가 붙어 있는 것을 볼 수 있습니다.
Permission Integer 작동 원리
이 숫자는 봇이 내 서버에 진입하는 즉시 자동으로 가지게 될 권한 목록을 컴퓨터가 읽을 수 있도록 비트 연산(Bitwise Operations)으로 합산해 둔 권한 정수입니다. 디스코드는 각 권한마다 고유한 16진수 비트 값을 부여하고 있으며, 이를 모두 더한 최종 10진수 값이 주소에 표시되는 것인데요.
- 초대 창에서의 권한 해제 리스크: 봇을 초대하는 화면에서 "메시지 보내기"나 "채널 보기" 등 봇이 정상 구동되는 데 필수적인 체크박스를 임의로 해제하고 가입시키는 경우가 있습니다. 이 경우 봇은 해당 기능에 접근할 수 없는 반쪽짜리 권한을 부여받아 오작동을 일으킵니다.
- 권장하는 해결책: 초대 시 요구하는 기본 권한 체크박스는 가급적 수정하지 않고 그대로 승인하는 것이 좋습니다. 봇의 권한을 제어하고 싶다면, 일단 모든 권한을 가진 상태로 초대한 후 서버 설정 내 역할 메뉴에서 안전하게 제어하는 편이 관리상 훨씬 수월합니다.
권한 계산 같은 경우, 디스호스트 툴을 통해 간편하게 계산할 수 있습니다.
Q2. 경고나 강퇴 봇이 작동은 하는데, 특정 유저를 제재하려 하면 권한 에러를 뿜습니다. 이유가 무엇인가요?
이 문제는 디스코드의 핵심 대원칙인 '역할 계층 우선권' 계통을 지키지 않아 발생하는 전형적인 계정 권한 오류입니다.
역할 순서와 계층의 작동 방식
디스코드는 [서버 설정 - 역할] 탭에 나열된 순서를 기준으로 권한의 상하 관계를 판정합니다. 이 목록의 가장 위에 있는 역할이 가장 높은 우선순위를 갖게 되는데요.
- 관리 행동의 물리적 제약: 특정 유저가 가진 최고 역할의 정렬 위치가 내 봇에게 부여된 역할보다 더 높은 계층에 있거나 동등한 위치에 있다면, 봇에게 서버 전체의 '멤버 강퇴하기'나 '멤버 차단하기' 권한이 켜져 있더라도 디스코드 시스템은 봇의 제재 행동을 강제로 거부합니다.
- 역할 부여의 한계: 봇은 자신보다 높은 순위의 역할을 다른 유저에게 부여하거나 닉네임을 강제로 바꿀 수도 없습니다.
봇 역할 계층 재조정 순서
서버 설정 - 역할메뉴로 들어갑니다.- 역할 정렬 목록에서 내 봇 이름으로 만들어진 고유 역할을 찾습니다.
- 봇의 역할을 마우스로 길게 클릭한 뒤, 일반 회원 및 모더레이터가 제어해야 할 일반 등급 역할들보다 더 위로 드래그하여 정렬 순서를 높여 줍니다.
- 설정을 저장하면 봇이 하위 역할 등급을 가진 유저들을 물리적으로 강퇴하거나 경고할 수 있는 상태로 즉시 갱신됩니다.
Q3. 봇의 계층 순서도 올바르게 정렬했는데 여전히 채널에 대답이 없습니다. 놓친 부분이 있을까요?
최근 디스코드의 데이터 프라이버시 정책 패치로 인해 개발자 설정 단계에서 게이트웨이 인텐트 승인이 끊겼을 확률이 높습니다.
Message Content Intent의 누락 원인
과거에는 봇을 추가하기만 하면 채널 내의 텍스트 메시지를 자유롭게 읽어 들여 리액션할 수 있었습니다. 하지만 보안 위협과 데이터 무단 수집을 차단하기 위해 디스코드는 'Message Content Intent'라는 게이트웨이 권한을 별도로 분류하여 관리자가 명시적으로 허용해야만 작동하도록 제한했습니다. 이 스위치가 꺼져 있으면 봇 소스 코드의 on_message 이벤트에 들어오는 유저의 메시지 텍스트 데이터가 항상 빈 값("")으로 치환되어 전달되기 때문에 봇은 명령어를 전혀 인식할 수 없게 됩니다.
개발자 포털 내 활성화 방법
- 웹 브라우저로 디스코드 개발자 포털(Discord Developer Portal)에 접속해 로그인합니다.
- 구동 중인 봇 어플리케이션을 선택하고 왼쪽 메뉴의 Bot 메뉴를 누릅니다.
- 화면 중간 아래에 위치한 Privileged Gateway Intents 탭을 찾습니다.
Message Content Intent토글 스위치를 활성화하고 Save Changes 버튼을 눌러 변경 사항을 적용합니다.
Q4. 카테고리 권한 설정과 채널 상속(동기화)은 어떻게 조율해야 하나요?
서버 규모가 커져 채널이 수십 개로 늘어나면, 개별 채널의 권한을 하나씩 만지는 방식은 사고로 이어지기 쉽습니다. 상위 카테고리 권한 설정을 채널이 그대로 이어받는 상속 개념을 설계해 두어야 합니다.
채널 권한 덮어쓰기의 우선순위
디스코드는 서버 전체 역할 설정보다 카테고리 및 개별 채널의 권한 설정을 최우선으로 처리합니다. 이때의 세부 판정 순서는 다음과 같이 작동합니다.
우선순위 계통: 서버 전체 역할의 거부(Deny) ➡️ 서버 전체 역할의 허용(Allow) ➡️ 채널 내 역할별 거부 ➡️ 채널 내 역할별 허용 ➡️ 채널 내 특정 멤버별 거부 ➡️ 채널 내 특정 멤버별 허용
즉, 서버 설정에서 봇에게 최고 관리자 권한을 주었더라도, 비공개로 설정한 스태프 채널 등에서 @everyone이나 봇 역할의 채널 보기 권한을 거부(빨간색 X) 상태로 덮어씌워 버리면 봇은 해당 채널에 접근조차 하지 못합니다.
권한 상속 동기화 셋업 절차
- 카테고리를 마우스 우클릭하여
카테고리 편집 - 권한으로 진입합니다. - 봇 역할을 목록에 추가하고, 봇이 스태프 채널이나 관리용 채널의 메시지를 읽고 쓸 수 있도록
채널 보기와메시지 보내기를 허용(초록색 체크)으로 지정합니다. - 개별적으로 설정을 바꾸다 상속이 끊겨 비동기화 경고가 뜨는 채널이 있다면, 해당 채널의
채널 편집 - 권한으로 들어가지금 동기화버튼을 눌러 카테고리 권한 체계와 즉시 묶어 줍니다.