봇은 서버에 정상적으로 추가되었는데 / 명령어가 보이지 않거나 호출할 수 없을 때 원인과 해결 절차를 정리한다. 디스코드 봇 개발·배포 과정에서 흔히 발생하는 설정 누락과 등록 지연을 점검하는 방법을 소개한다.
증상
- 봇이 길드(서버)에 정상적으로 보이고 온라인 상태일 수 있지만 슬래시 명령어 목록에 아무 명령어도 뜨지 않음.
/입력 시 명령어 자동완성에 등록된 커맨드가 전혀 나타나지 않음.- 명령어 등록을 시도했으나 반영되지 않거나, 일부 길드에서만 보이는 현상.
원인
- OAuth2로 봇을 초대할 때
applications.commands스코프를 포함하지 않음. 이 스코프가 없으면 슬래시 명령어가 등록되어도 클라이언트에 노출되지 않음. - 명령어를 글로벌(Global)로 등록했을 경우 전파 지연. 글로벌 명령은 캐시 전파 때문에 최대 1시간 이상 반영 지연 발생.
- 명령어를 잘못된 애플리케이션 또는 잘못된 길드 ID로 등록함. 여러 봇을 운영할 때 흔함.
- 실제 명령어 등록 코드(또는 REST 호출)가 실행되지 않거나 에러가 발생해 등록이 실패함.
- 서버 권한 설정에서 멤버가 애플리케이션 명령어 사용(Use Application Commands) 권한이 제한되어 명령어가 표시되지 않음.
- 호스팅(예: 디스호스트)에서 봇 프로세스가 정상적으로 가동하지 않거나 재배포 후 등록 스크립트 미실행.
해결 방법
1단계: 빠른 점검 (5분 내)
-
초대한 URL에
applications.commands스코프 포함 여부 확인. 초대 링크 예:https://discord.com/oauth2/authorize?client_id=CLIENT_ID&scope=bot%20applications.commands&permissions=PERMISSIONS_INTEGER필요하면 봇을 제거 후 위 스코프를 포함해 다시 초대.
-
명령어를 길드 단위로 다시 등록해 즉시 반영 여부 확인. 길드 등록은 즉각 적용되므로 문제 원인 추적에 유용.
-
봇이 실제로 실행 중인지 확인. 호스팅을 디스호스트에서 사용 중이면 배포 로그와 프로세스 상태를 확인하고 재시작.
2단계: 명령어 등록 확인 및 재등록
- 명령어 등록 스크립트를 확인하여 올바른 CLIENT_ID와 GUILD_ID를 사용했는지 확인. 예시(Node.js, discord.js REST):
// javascript
const { REST, Routes } = require('discord.js');
const commands = [{ name: 'ping', description: 'pong' }];
const rest = new REST({ version: '10' }).setToken(process.env.BOT_TOKEN);
(async () => {
try {
await rest.put(
Routes.applicationGuildCommands(process.env.CLIENT_ID, process.env.GUILD_ID),
{ body: commands }
);
console.log('길드 명령어 등록 완료');
} catch (error) {
console.error('명령어 등록 실패:', error);
}
})();
-
글로벌 등록 대신 우선
applicationGuildCommands로 등록해 즉시 테스트. 글로벌 등록은 아래 경로 사용:Routes.applicationCommands(CLIENT_ID) -
등록 시 에러 로그(권한 에러, 401/403 등)를 확인. 토큰이 잘못됐거나 권한 부족이면 등록 실패.
3단계: 권한 및 서버 설정 점검
-
서버의 역할 설정에서 애플리케이션 명령어 사용 권한이 특정 역할에 제한되어 있는지 확인. 제한되어 있으면 해당 역할에 권한 부여 또는 테스트용 계정으로 권한 제거 후 재확인.
-
봇이 올바른 애플리케이션(Developer Portal의 앱)이 맞는지 확인. 앱 ID와 봇 토큰이 일치하지 않으면 명령어가 엉뚱한 앱에 등록될 수 있음.
4단계: 추가 점검 항목
- 디스코드 클라이언트 캐시 문제 가능성: 모바일/웹/데스크톱 간 차이가 있을 수 있으니 다른 클라이언트에서 확인.
- 명령어가 특정 조건(권한, 옵션)에 의해 숨겨지는지 확인.
default_member_permissions나dm_permission설정 때문에 표시되지 않을 수 있음. - 배포 자동화 파이프라인이 있다면 명령어 등록 단계가 배포 뒤 실행되는지 확인하고, 실패 시 재시도 로직 추가.
마무리
슬래시 명령어가 보이지 않을 때는 초대 스코프(applications.commands)와 명령어 등록 대상(guild vs global), 등록 스크립트의 애플리케이션/길드 ID가 핵심이다. 디스코드 봇을 디스호스트에 호스팅한다면 배포 로그와 프로세스 상태, 등록 스크립트 실행 여부를 먼저 점검하면 대부분 문제를 빠르게 해결할 수 있다.