명령어가 안떠요......

디스코드 봇을 만들다 보면 봇은 켜지는데 명령어가 보이지 않거나 응답하지 않는 경우가 있다. 이 글에서는 파이썬으로 만든 봇에서 Cog 파일이 등록되지 않아 명령어가 동작하지 않는 문제를 직접 해결하는 방법을 정리한다.

증상

• 봇 온라인 상태로 보이지만 명령어(!help 등)가 동작하지 않음
• commands.Cog로 작성한 파일을 분리해도 명령어가 등록되지 않음
• 코드 변경 후에도 명령어 목록이 갱신되지 않음

원인

• Cog 파일에 확실한 setup 함수가 없거나 형식이 맞지 않음 → 확장 로드 시 Cog가 추가되지 않음
• 메인 파일에서 해당 Cog를 불러오지 않음 → 분리한 파일이 로드되지 않아 명령어가 등록되지 않음
• 환경변수(Token)를 코드에 직접 두고 공유/호스팅 과정에서 잘못 설정되어 정상적으로 로그인하지 못함
• 파일 경로/모듈 이름이 틀려서 load_extension이 실패함

해결 방법

1단계: Cog 파일에 setup 작성하기

discord.py 버전에 따라 setup 함수 형태가 다르니 사용 중인 버전에 맞춰 작성한다.

• discord.py 1.x (동기형)

# cogs/hello.py
from discord.ext import commands

class HelloCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot

    @commands.command(name='hello')
    async def hello(self, ctx):
        await ctx.send('안녕하세요!')

def setup(bot):
    bot.add_cog(HelloCog(bot))

• discord.py 2.x (비동기형)

# cogs/hello.py
from discord.ext import commands

class HelloCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot

    @commands.command(name='hello')
    async def hello(self, ctx):
        await ctx.send('안녕하세요!')

async def setup(bot):
    await bot.add_cog(HelloCog(bot))

2단계: 메인 파일에서 Cog 불러오기 및 환경변수 사용

• .env 파일과 python-dotenv로 토큰을 관리하고, 메인에서 확장 로드한다.

# main.py
import os
from dotenv import load_dotenv
from discord.ext import commands

load_dotenv()
TOKEN = os.getenv('DISCORD_TOKEN')

bot = commands.Bot(command_prefix='!')

# sync 방식 (1.x)
bot.load_extension('cogs.hello')
bot.run(TOKEN)

• discord.py 2.x 비동기 로딩 예시:

# main_async.py
import os
import asyncio
from dotenv import load_dotenv
from discord.ext import commands

load_dotenv()
TOKEN = os.getenv('DISCORD_TOKEN')

bot = commands.Bot(command_prefix='!')

async def main():
    await bot.load_extension('cogs.hello')
    await bot.start(TOKEN)

asyncio.run(main())

추가 확인 사항:

• 디렉터리 구조가 cogs/hello.py이고 main.py에서 상대 경로로 불러오는지 확인 (cogs.hello)
• 확장 로드 실패 시 터미널 로그 확인 (ImportError, ModuleNotFoundError 등)
• 코드를 공유할 때는 절대 토큰 제거. 토큰은 .env에 두고 배포/호스팅(예: 디스호스트) 환경 변수로 설정

마무리

Cog 파일에 올바른 setup(또는 async setup)을 작성하고 메인에서 확장을 불러오면 명령어가 정상적으로 등록된다. 토큰은 .env 또는 호스팅 환경변수로 관리해 보안과 배포를 안전하게 유지하자.