디스코드 봇을 처음 만들려고 하면 대게 제일 먼저 코드부터 보게 됩니다.
어떤 라이브러리를 써야 하는지, 슬래시 명령어는 어떻게 등록하는지, 이벤트는 어떤 이름으로 받아야 하는지, 토큰은 어디에 넣어야 하는지 이런 것 부터 찾게 되죠
물론 이상한 순서는 아닙니다.
결국 봇은 코드로 움직이니까요
그런데 실제로 더 빨리 꼬이는 구간은 그 전인 경우가 많습니다.
디스코드 개발자 포털에서 애플리케이션을 만들고, 봇을 붙이고, 초대 링크를 만들고, 권한을 고르고, Intents를 켜는 이 과정이 겉으로 보기엔 전부 비슷한 설정처럼 보이는데요 실제로는 성격이 전부 다릅니다.
어떤 것은 봇을 만드는 단계이고, 어떤 것은 서버에 넣는 단계이며, 어떤 것은 디스코드가 이벤트를 보내줄지 말지를 정하는 단계이고, 어떤 것은 나중에 보안 사고로 바로 이어질 수 있는 단계이기도 합니다.
많은 분들이 여기서 같은 실수를 하곤 합니다.
전부 그냥 봇 설정이라고 묶어서 보는 것 입니다.
하지만 개발자 포털은 하나의 메뉴가 아닙니다.
겉으로는 메뉴 몇 개 누르는 일처럼 보여도 실제로는 생성, 초대, 권한, 이벤트 수신, 보안 관리라는 서로 다른 문제들이 한 화면 안에 겹쳐 있는 구조에 더 가깝습니다.
이걸 나눠서 보지 않으면 봇을 만들기 전부터 계속 이상하게 막히게 됩니다.
서버에는 들어왔는데 반응이 없고, 링크는 만든 것 같은데 명령어가 안 뜨고, 토큰은 넣었는데 왜 안 움직이는지 모르겠고, 분명 설정을 했는데 무엇을 잘못한건지 감이 안 오는 상황이 반복되는 것이죠
이건 꽤 흔합니다.
이번 글에서는 디스코드 개발자 포털을 메뉴 설명서처럼 보지 않고, 봇 만들기 전에 어떤 기준으로 나눠서 봐야 덜 꼬이는지부터 먼저 정리해보겠습니다.
디스코드 봇 만들기는 왜 코드보다 포털 설정에서 먼저 꼬이게 되는가
디스코드 봇이 안 된다고 느끼는 상황을 떠올려보면 대게 비슷합니다.
서버에는 들어왔는데 아무 말도 하지 않습니다.
슬래시 명령어를 넣었는데 화면에 안 뜹니다.
메세지를 읽어야 하는데 못 읽습니다.
초대 링크는 만들었는데 누르면 뭔가 이상한 화면이 보이기도 합니다.
그러면 보통은 코드부터 의심하게 되겠죠
이벤트 이름이 틀렸나, 라이브러리 버전이 다른가, 권한 에러가 뜨는건가, 비동기 처리가 꼬였나 이런 식으로 말입니다.
그런데 실제로는 코드 이전에 이미 방향이 틀어져 있는 경우가 굉장히 많습니다.
애플리케이션만 만들어두고 봇은 아직 안 붙여둔 경우도 있고, 봇은 붙였는데 초대 링크 스코프가 비어 있는 경우도 있고, 링크는 맞는데 권한이 너무 좁거나 반대로 너무 넓어서 뭐가 문제인지 감이 안 오는 경우도 있고, 권한은 얼추 맞는데 Intents가 꺼져 있어서 디스코드가 필요한 이벤트를 안 보내주고 있는 경우도 있습니다.
겉으로 보기엔 전부 봇이 안 됨으로 보이겠죠
하지만 실제로는 전혀 다른 문제입니다.
이 부분을 한 번 잘못 묶어버리면 시간이 길게 샙니다.
왜냐하면 문제를 잘못 잡으면 고치는 방향도 계속 틀어질 수밖에 없기 때문입니다.
메세지를 못 읽는 문제를 코드 문제로 보고 하루 종일 이벤트 핸들러만 바꾸고 있을 수도 있고, 초대 링크 문제를 권한 문제로 착각해서 퍼미션 값만 계속 바꾸고 있을 수도 있고, 토큰 관리 문제인데 실행 환경만 계속 재설정하고 있을 수도 있습니다.
그래서 개발자 포털은 그냥 거쳐가는 단계가 아닙니다.
부가 설정 메뉴도 아닙니다.
앞으로 이 봇이 어떤 방식으로 동작할지를 처음부터 구조화 하는 곳에 더 가깝습니다.
이걸 메뉴 순서대로 보기 시작하면 오히려 더 흐려집니다.
반대로 이건 생성 문제다, 이건 초대 문제다, 이건 이벤트 수신 문제다, 이건 보안 문제다 이렇게 나눠서 보면 갑자기 훨씬 덜 복잡하게 보이기 시작합니다.
여기서 차이가 아주 크게 벌어집니다.
이건 제일 먼저 정확하게 잡고 가야 합니다.
디스코드 개발자 포털에 들어가서 New Application을 누르면 많은 분들이 그 순간 봇이 만들어졌다고 생각합니다.
하지만 실제로는 그렇지 않습니다.
애플리케이션은 말 그대로 하나의 앱 단위를 만드는 것에 가깝습니다.
이름, 아이콘, 설명, 식별 정보, OAuth2 설정, 공개키, 앱 자체의 기본 정보가 여기에 붙습니다.
그리고 봇은 그 애플리케이션 안에 따로 붙는 사용자 입니다.
즉 애플리케이션을 만들었다고 해서 아직 우리가 흔히 말하는 디스코드 봇까지 바로 생기는 것은 아닙니다.
Bot 탭에 들어가 실제 봇 사용자를 추가해야 그때부터 토큰도 보고, 프로필도 보고, Intents도 만지고, 우리가 익숙하게 생각하는 봇 설정이 시작됩니다.
이건 굉장히 기본적인 이야기처럼 보입니다.
그런데 이런 기본적인 부분이 제일 늦게 보입니다.
왜냐하면 초보자 입장에서는 개발자 포털 안의 모든 것이 그냥 봇 관련 설정처럼 보이기 때문입니다.
그러다 보니 애플리케이션만 만든 상태에서 왜 토큰이 안 보이는지부터 찾게 되고, 왜 서버 초대가 안 되는지 보게 되고, 슬래시 명령어 등록을 먼저 붙잡다가 순서가 자꾸 엇나가게 됩니다.
겉으로 보기엔 같은 것 같죠
하지만 실제로는 다릅니다.
애플리케이션은 껍데기이자 식별 단위이고, 봇은 그 안에 붙는 실제 동작 사용자 입니다.
이 차이를 분리해서 보는 순간부터 개발자 포털이 조금 덜 지저분하게 보이기 시작합니다.
아주 기본적인 부분 입니다.
그런데 이런 기본적인 부분을 놓치면 그 뒤 메뉴들도 전부 같이 흐려집니다.
개발자 포털에 들어가면 메뉴가 생각보다 많습니다.
General Information, Bot, OAuth2, Installation, App Directory, Rich Presence 같이 처음 보면 어디서 뭘 건드려야 하는지 감이 잘 안 오는 메뉴들이 같이 보이죠
그럴 때 제일 안 좋은 방식은 전부 한 번에 이해하려는 것입니다.
오히려 그렇게 보면 더 헷갈립니다.
처음에는 세 가지만 먼저 나눠서 보면 됩니다.
General Information
이 메뉴는 앱의 신분증 같은 곳이라고 보면 됩니다.
이름, 아이콘, 설명, Application ID, Public Key 같이 애플리케이션 자체를 식별하는 값들이 여기에 모여 있습니다.
초반에는 이름 정하고 아이콘 하나 넣고 넘어가게 되겠죠
그럴 수 있습니다.
하지만 나중에 슬래시 명령어 등록을 하거나, 외부 인터랙션 검증을 붙이거나, 앱 식별값이 필요한 작업을 하게 되면 여기 값을 다시 보게 되는 경우가 많습니다.
지금 당장 안 쓴다고 해서 의미 없는 메뉴는 아니라는 뜻입니다.
Bot 탭
여기서부터가 진짜 시작입니다.
봇 추가, 토큰 발급, 봇 프로필, 공개 여부, Intents 활성화 같이 실제 봇 동작과 직접 연결되는 것들이 여기 모여 있습니다.
디스코드 개발자 포털 전체를 통틀어 가장 자주 다시 오게 되는 메뉴라고 봐도 됩니다.
특히 여기서 제일 많이 막히는 것이 토큰과 Intents 입니다.
토큰은 열쇠이고, Intents는 디스코드가 무엇을 보내줄지 정하는 문 같은 것 입니다.
이 둘을 대충 보고 넘어가면 나중에 정말 오래 헤매게 됩니다.
OAuth2
많은 분들이 이 메뉴를 그냥 초대 링크 만드는 곳 정도로 봅니다.
틀린 말은 아닙니다.
하지만 그렇게만 보면 자꾸 이상하게 꼬이게 됩니다.
OAuth2는 단순 링크 생성기가 아니라, 이 애플리케이션이 어떤 흐름으로 디스코드와 연결될지를 정하는 공간에 더 가깝습니다.
봇 초대도 여기서 하고, 어떤 스코프를 요청할지도 여기서 고르고, 권한도 여기서 붙이고, 나중에는 로그인이나 인증 Redirect 흐름까지 이어질 수 있습니다.
즉 링크 한 줄 만드는 메뉴라고만 보면 실제보다 너무 좁게 보는 것 입니다.
왜 다 같은 설정처럼 보이는데 실제로는 전부 다른 문제인가
여기부터가 핵심입니다.
디스코드 개발자 포털이 처음 어려운 이유는 메뉴가 많아서가 아닙니다.
많아 보이는 메뉴들이 겉으로 너무 비슷하게 보이기 때문입니다.
전부 설정 화면이고, 전부 토글이 있고, 전부 뭔가를 선택하고 저장하는 흐름이라서 초보자 입장에서는 같은 종류의 설정처럼 느껴지게 됩니다.
하지만 실제로는 전혀 다릅니다.
애플리케이션 생성은 존재를 만드는 문제입니다.
Bot 탭 설정은 봇 계정을 붙이는 문제입니다.
OAuth2는 서버에 넣는 문제입니다.
권한은 그 봇이 들어간 뒤 무엇을 할 수 있는지의 문제입니다.
Intents는 디스코드가 무엇을 보내줄지의 문제입니다.
토큰 관리는 보안과 실행 환경의 문제입니다.
겉으로 보면 전부 체크박스고 버튼이고 값 입력하는 것 같죠
하지만 안쪽 성격은 전혀 다릅니다.
이걸 한 덩어리로 보면 왜 문제가 어려워지느냐
증상은 하나처럼 보이는데 원인은 다섯 갈래, 여섯 갈래로 흩어져 있기 때문입니다.
예를 들어 서버에는 들어왔는데 슬래시 명령어가 안 뜬다고 해보겠습니다.
이걸 보고 그냥 봇이 이상하다고 생각하면 답이 안 나옵니다.
초대 링크 스코프 문제일 수도 있고, 명령어 등록 범위 문제일 수도 있고, 애플리케이션 설정 문제일 수도 있고, 실제로는 전파 시간이 필요한 상황일 수도 있습니다.
반대로 메세지 읽기 반응이 안 된다고 해보겠습니다.
겉으로는 코드 문제처럼 보이겠죠
하지만 실제로는 Message Content Intent가 꺼져 있을 수도 있습니다.
그리고 또 어떤 경우는 권한이 아예 없어서 채널 메세지를 못 보는 것일 수도 있습니다.
이렇게 되면 같은 증상처럼 보이는 것 안에 전혀 다른 문제가 섞여 있는 셈입니다.
이것이 개발자 포털이 사람을 가장 헷갈리게 만드는 지점입니다.
겉으로는 같은 설정인데 실제로는 다른 층위의 문제를 다루고 있다는 점 말이죠
이 기준 없이 포털을 보면 메뉴를 많이 알아도 소용이 없습니다.
왜 안 되는지 나눠서 보지 못하기 때문입니다.
그래서 개발자 포털을 볼 때는 메뉴 이름을 외우기보다 지금 내가 보고 있는 것이 무엇을 정하는 화면인지를 먼저 물어봐야 합니다.
이건 존재를 만드는 메뉴인가
서버에 넣는 메뉴인가
권한을 여는 메뉴인가
이벤트를 받는 메뉴인가
보안을 관리하는 메뉴인가
이렇게 나누는 것이 훨씬 중요합니다.
이걸 하기 시작하면 갑자기 문제가 덜 무섭게 보입니다.
왜냐하면 봇이 안 된다는 막연한 상태가 아니라, 초대는 됐고 권한도 괜찮은데 이벤트 수신이 안 되는 것 같다 같은 식으로 좁혀서 볼 수 있게 되기 때문입니다.
보통은 여기서부터 개발 속도가 달라집니다.
코드를 잘 짜는 것과 별개로, 어디서 왜 막혔는지 찾는 속도가 달라지기 때문입니다.
OAuth2 초대 링크는 간단해 보이는데 왜 자꾸 꼬이게 되는가
봇을 만들고 나면 누구나 빨리 테스트 서버에 넣어보고 싶어집니다.
그런데 이상하게도 여기서부터 막히는 경우가 많습니다.
초대 링크는 겉으로 보면 단순합니다.
스코프 고르고 URL 만들면 끝인 것 같죠
하지만 실제로는 그렇지 않습니다.
bot과 applications.commands
이 둘을 처음에 정말 많이 헷갈립니다.
bot은 말 그대로 봇 사용자를 서버에 넣기 위한 스코프 입니다.
반면 applications.commands는 슬래시 명령어 관련 흐름과 이어지는 스코프 입니다.
슬래시 명령어 기반 봇을 만들고 있으면서 bot만 넣는 경우도 있고, 반대로 왜 필요한지 모르면서 둘 다 그냥 체크하고 넘어가는 경우도 있습니다.
물론 처음엔 그럴 수 있습니다.
그런데 감으로 체크하고 넘어가면 나중에 명령어가 안 보일 때 원인을 분리해서 보기 어려워집니다.
겉으론 같은 초대 링크 같지만 실제로는 다릅니다.
링크는 하나여도, 그 링크가 디스코드에 요청하는 성격은 서로 다른 것이죠
권한은 넓게 주면 편할 것 같지만 오히려 더 흐려집니다
처음 테스트할 때 Administrator 권한을 통째로 주는 경우가 많습니다.
사실 많이들 그렇게 합니다.
빨리 확인해보고 싶으니까요
그런데 이게 습관이 되면 나중에 자꾸 문제를 가리게 됩니다.
메세지를 읽는 권한이 필요한건지, 역할을 관리해야 하는건지, 채널을 봐야 하는건지, 파일 첨부를 해야 하는건지, 명령어 응답만 있으면 되는건지 이런 세부 권한이 전부 관리자 권한 안에 묻혀버리기 때문입니다.
초반 테스트에서는 편할 수 있습니다.
하지만 실제 운영 서버에 넣을 때는 결국 다시 나눠서 보게 됩니다.
그렇기에 처음부터 너무 넓게 여는 것이 정답이라기보다, 왜 이 봇이 이 권한을 필요로 하는지 한 번은 생각해보는 것이 더 중요합니다.
이 부분도 은근히 큽니다.
Redirect URL은 안 쓰는 것 같아도 나중에 갑자기 중요해집니다
일반적인 봇 초대만 다룰 때는 Redirect URL을 거의 안 건드릴 수도 있습니다.
그래서 별 의미 없는 값처럼 느껴지기도 합니다.
그런데 웹 로그인, 외부 인증, 대시보드 연동 같은 흐름을 붙이기 시작하면 여기서 갑자기 막히게 됩니다.
특히 로컬 환경, 테스트 도메인, 운영 도메인이 섞일 때 더 그렇습니다.
URL이 한 글자만 달라도 인증이 안 되는 경우가 생기기 때문입니다.
지금 당장 안 쓰더라도 이 메뉴가 나중에 왜 중요한지 정도는 알고 있는 편이 좋습니다.
그래야 나중에 또 처음부터 헤매지 않게 됩니다.
Intents는 코드 문제가 아닌데 코드 문제처럼 보이게 만드는 구간입니다
여기서부터는 정말 자주 오해합니다.
봇은 켜져 있습니다.
서버에도 들어와 있습니다.
그런데 메세지를 못 읽고, 멤버 이벤트를 못 받고, 기대한 반응을 하지 않습니다.
이때 많은 분들이 코드만 계속 고칩니다.
이벤트 리스너를 바꾸고, 콘솔만 다시 보고, 라이브러리 문서만 계속 뒤집어보게 되죠
그런데 실제로는 개발자 포털의 Intents 설정이 막고 있는 경우가 있습니다.
메세지를 못 읽는다고 무조건 코드 문제는 아닙니다
특히 Message Content Intent는 많이 놓칩니다.
봇이 메세지 내용을 기반으로 반응해야 하는 구조인데, 포털에서 해당 Intent가 꺼져 있으면 기대했던 대로 동작하지 않을 수 있습니다.
이건 코드가 이상해서라기보다 디스코드가 필요한 정보를 충분히 보내주고 있지 않았던 것에 더 가깝습니다.
겉으로 보기엔 그냥 반응이 없는 것처럼 보입니다.
그래서 더 헷갈립니다.
이런 것 처럼 Intents 문제는 꼭 기억해야 합니다.
증상이 너무 코드 에러처럼 보이기 때문입니다.
멤버 관련 기능은 Member Intent를 같이 봐야 합니다
자동 역할 부여, 입장과 퇴장 추적, 멤버 기반 인증, 멤버 상태를 읽는 기능을 붙이기 시작하면 이 부분도 중요해집니다.
처음엔 단순 명령어 봇만 만들 생각이었는데 나중에 기능이 조금씩 붙으면서 멤버 관련 이벤트가 필요해지는 경우가 많습니다.
그런데 그때 가서 왜 안 되는지 찾기 시작하면 다시 포털로 돌아오게 됩니다.
그래서 지금 만들 봇이 어떤 이벤트를 정말 필요로 하는지 미리 생각해두는 것이 좋습니다.
그냥 다 켜는 것 보다 훨씬 낫습니다.
많이 켜는게 정답은 아닙니다
이 부분도 같이 봐야 합니다.
처음에는 그냥 다 켜버리면 편해 보일 수 있습니다.
하지만 좋은 방향은 아닙니다.
권한과 Intents는 넓게 열수록 좋아지는 것이 아니라, 필요한 것만 정확하게 이해하고 켜는 쪽이 더 낫습니다.
그래야 나중에 어디서 왜 막히고 있는지 판단하기도 쉬워집니다.
토큰은 그냥 복사해서 넣는 문자열이 아닙니다
이 부분은 정말 가볍게 보면 안 됩니다.
토큰은 봇을 실행시키는 값이기도 하지만, 동시에 봇 계정을 증명하는 열쇠이기도 합니다.
그렇기에 한번 노출되면 단순 실수가 아니라 보안 문제로 바로 넘어가게 됩니다.
공개 저장소에 토큰을 올리면 안 됩니다
너무 기본적인 말 같지만 실제로는 정말 자주 벌어집니다.
테스트용이라 괜찮겠지 하고 코드에 그대로 넣고 깃허브에 올리거나, .env 파일을 같이 커밋하거나, 스크린샷을 찍다가 토큰이 보이는 경우도 있습니다.
이건 정말 허무하게 사고가 납니다.
그리고 더 중요한 점은, 한번 공개된 토큰은 다시 안전한 토큰으로 볼 수 없다는 것 입니다.
삭제했다고 끝나는 문제가 아닙니다.
이 경우는 빨리 재발급하고 기존 토큰을 폐기하는 것이 낫습니다.
시간이 지나면 괜찮아지는 성격의 문제가 아니기 때문입니다.
테스트 환경과 운영 환경을 섞으면 나중에 본인이 헷갈립니다
처음에는 봇 하나로 다 해보고 싶어집니다.
그럴 수 있습니다.
하지만 테스트 서버, 운영 서버, 토큰, 권한, Redirect URL, 환경 변수까지 전부 한 덩어리로 관리하기 시작하면 어느 순간부터 본인이 만든 구조를 본인이 이해 못 하는 상황이 생깁니다.
이건 꽤 자주 생깁니다.
그래서 가능하다면 최소한 환경 변수는 분리하고, 어떤 토큰이 어떤 용도인지부터 스스로 헷갈리지 않게 정리해두는 편이 좋습니다.
토큰은 나중에 다시 보기 어렵다는 것도 기억해야 합니다
이 부분도 의외로 많이 놓칩니다.
발급받을 때 제대로 안전하게 저장해두지 않으면 나중에 다시 원문 그대로 보기 어렵고, 결국 재발급 흐름으로 가야 하는 경우가 생깁니다.
그러니 처음부터 비공개 환경 변수나 안전한 저장 방식을 쓰는 것이 좋습니다.
저장만 하지 말고
어디에 저장했는지도 알아야 합니다.
테스트 서버에 초대하기 전에 마지막으로 다시 봐야 하는 것들
여기까지 오면 빨리 넣어보고 싶어집니다.
당연한 흐름입니다.
하지만 여기서 한 번만 더 정리하고 들어가면 생각보다 많은 시행착오를 줄일 수 있습니다.
가장 먼저, 지금 만든 것이 애플리케이션인지 봇인지 다시 보세요.
애플리케이션만 만들고 봇은 아직 안 붙어 있는 경우도 있습니다.
그 다음에는 Bot 탭에서 실제 토큰이 발급되었는지 보는 것이 좋습니다.
그리고 OAuth2 링크에 필요한 스코프가 들어갔는지 확인해야 합니다.
슬래시 명령어를 쓸 계획이라면 applications.commands를 빠뜨리고 있진 않은지도 같이 봐야 합니다.
그 다음은 권한입니다.
지금 이 봇이 실제로 무슨 일을 해야 하는지에 비해 너무 넓거나 너무 좁게 권한을 준 것은 아닌지 봐야 합니다.
그리고 마지막은 Intents 입니다.
메세지를 읽어야 하는지, 멤버 이벤트가 필요한지, 그냥 슬래시 명령어만 쓰는 구조인지 먼저 나눠서 봐야 합니다.
이 순서를 건너뛰면 테스트는 할 수 있어도 원인을 찾는 속도가 굉장히 느려집니다.
마무리
다시 정리하면 디스코드 봇 만들기는 코드부터 시작하는 작업처럼 보이지만 실제로는 그 전부터 이미 갈림길이 시작됩니다.
애플리케이션과 봇의 차이, OAuth2 초대 링크, 권한 설정, Intents, 토큰 관리 같은 것들은 겉으로 보면 전부 비슷한 설정처럼 보일 수 있습니다.
하지만 실제로는 성격이 전부 다르기 때문에 하나로 묶어서 보면 더 꼬이게 됩니다.
그렇기에 디스코드 개발자 포털은 그냥 봇 하나 등록하는 곳이 아니라, 앞으로 이 봇이 어떤 방식으로 동작할지를 구조적으로 정리하는 공간이라고 보는 것이 맞습니다.
많은 분들이 봇이 안 된다고 느낄 때 코드를 먼저 의심합니다.
하지만 앞에서 말씀드린 순서대로 보다 보면 의외로 포털 설정 단계에서 막혀 있던 경우가 꽤 많습니다.
디스코드 개발자 포털은 복잡해 보일 수 있습니다.
하지만 생성, 초대, 권한, 이벤트 수신, 보안 관리라는 다섯 가지 성격으로 나눠서 보기 시작하면 훨씬 덜 헷갈리게 될 것 입니다.
해당 가이드 내용이 디스코드 개발자 포털 설정을 보다 체계적으로 이해하는 데 조금이라도 도움이 되길 바랍니다.
디코모아 운영팀
디코모아 플랫폼에서 디스코드 커뮤니티 인사이트를 공유합니다.