---
title: AI 에이전트 디스코드 봇 연동 가이드, 직접 삽질하며 배운 주의점
date: 2026-10-01
model: hermes-agent
category: setups
summary: Hermes 에이전트를 디스코드 봇에 연동하며 실제로 겪은 등록·권한 설정과 실수 포인트를 정리했다.
tags: discord, bot, hermes, setup, permissions
author_type: human
---

텔레그램에 이어서 디스코드로도 Hermes 에이전트를 붙여 봤다. 텔레그램은 BotFather에서 토큰 하나면 끝이지만, 디스코드는 봇 초대와 권한(permission) 세팅이 있어서 그 부분에서 더 오래 걸렸다. 직접 겪은 순서대로 정리한다. (운영자 환경 측정 기준)

## 1. 봇 만들기: Developer Portal

텔레그램의 BotFather 같은 단일 봇 대신, 디스코드는 프로젝트 단위로 관리한다.

1. [Discord Developer Portal](https://discord.com/developers/applications) 접속
2. 우측 상단 `New Application` 클릭 → 이름 입력 (예: `Hermes Agent`)
3. 좌측 메뉴에서 `Bot` 선택 → `Reset Token` 클릭 → 토큰 발급
4. 같은 화면에서 `MESSAGE CONTENT INTENT`를 **ON**으로 켠다

발급된 토큰 형식은 텔레그램과 비슷하다.

```text
MTIzNDU2Nzg5MDEyMzQ1Njc4.GaBcDe.thisIsAFakeTokenExample
```

### 주의점 1: MESSAGE CONTENT INTENT를 안 켜면 메시지를 못 읽는다

이 스위치가 꺼져 있으면 봇이 채널 메시지 내용을 접근하지 못해서, 아무리 권한을 다 세팅해도 응답이 없다. 토큰 발급만 하고 지나가기 쉽다. 포털의 `Bot` 화면에서 켜는지 반드시 확인하자.

## 2. 서버에 봇 초대

1. 왼쪽 메뉴 `OAuth2` → `URL Generator` 선택
2. Scopes에 `bot` 체크, `applications.commands` 체크
3. Bot Permissions에서 `View Channels`, `Send Messages`, `Read Message History`, `Attach Files` 체크
4. 생성된 URL을 브라우저로 열고 서버 선택 후 초대

### 주의점 2: 권한 부족 증상은 조용한 무응답이다

디스코드는 권한이 없으면 에러를 던지지 않고 메시지를 그냥 무시한다. 봇이 온라인인데 답이 없으면, 권한 문제일 확률이 가장 높다. 서버 설정 → `Integrations` → 봇 이름 → 권한 탭에서 위 4개가 켜져 있는지 확인한다.

## 3. 내 Discord 사용자 ID 확인

화이트리스트를 거려면 숫자 ID가 필요하다. 사용자 설정 → 고급설정 → 개발자 모드 ON → 아무 사용자 우클릭 → `사용자 ID 복사`.

```text
123456789012345678
```

### 주의점 3: 닉네임이 아니라 사용자 ID를 넣는다

`@myid` 같은 형태로 넣으면 필터가 동작하지 않는다. 숫자 ID를 그대로 넣어야 한다.

## 4. .env 설정

```env
# 디스코드 봇 토큰 (필수)
DISCORD_BOT_TOKEN=MTIzNDU2Nzg5MDEyMzQ1Njc4.GaBcDe.thisIsAFakeTokenExample

# 허용 사용자 (숫자 ID만, 필수 권장)
DISCORD_ALLOWED_USERS=123456789012345678

# 접두어: 멘션 없이 부르려면 다른 문자 사용
DISCORD_MESSAGE_PREFIX=!
```

### 주의점 4: 접두어를 안 두면 채널 대화가 전부 요청이 된다

디스코드는 채널의 모든 메시지를 봇에게 전달한다. 접두어 설정이 없으면 채널의 잡담까지 전부 LLM으로 들어가고, 그만큼 요금이 쌓인다. 나는 처음에 접두어 개념을 몰라서 잠깐 채널 대화를 통째로 먹인 적이 있다. 반드시 `DISCORD_MESSAGE_PREFIX`를 정하고, 그 문자로 시작하는 메시지만 처리하게 한다.

### 주의점 5: 토큰에 따옴표를 붙이지 않는다

```env
DISCORD_BOT_TOKEN="MTIzNDU2..."
```

따옴표까지 토큰으로 읽혀서 `401: Unauthorized`가 난다. 텔레그램 설정과 같은 함정이다. 값은 있는 그대로 적는다.

## 5. 실행

```bash
hermes gateway start
```

### 주의점 6: 게이트웨이를 두 곳에서 동시에 띄우지 않는다

텔레그램은 polling이라 `409 Conflict`가 명확히 떴지만, 디스코드는 웹소켓 재연결을 조용히 반복한다. 로그에 연결은 되는데 메시지가 안 오면, 다른 곳에서 같은 토큰으로 게이트웨이를 띄우고 있는지 먼저 본다.

## 6. 슬래시 명령 등록

디스코드는 `/` 입력 시 메뉴가 자동으로 뜬다. 텔레그램의 BotFather `/setcommands`에 해당하는 등록 단계가 필요 없다. 다만 명령 목록을 사용자에게 안내하려면 README나 채널 고정 메시지로 따로 적어둔다.

## 7. 텔레그램과 비교

| 항목 | 텔레그램 | 디스코드 |
| --- | --- | --- |
| 봇 생성 | BotFather에서 즉시 | Developer Portal에서 프로젝트 생성 후 초기화 |
| 필수 스위치 | 없음 | MESSAGE CONTENT INTENT ON |
| 권한 | Allowed Users로 충분 | 채널 권한 4개 + Allowed Users |
| 중복 실행 | 409 Conflict로 드러남 | 조용히 재연결 반복 |
| 비용 통제 | 세션별 메시지 수 | 반드시 메시지 접두어 설정 |

## 정리

1. Developer Portal → Application 생성 → Bot에서 토큰 발급, `MESSAGE CONTENT INTENT` ON
2. OAuth2 URL Generator로 `bot` + `applications.commands` 스코프로 서버 초대, 채널 권한 4개 확인
3. 개발자 모드로 내 숫자 사용자 ID 확인 → `DISCORD_ALLOWED_USERS` 등록
4. `.env`에 따옴표 없이 토큰 작성, `DISCORD_MESSAGE_PREFIX`로 잡담 차단
5. `hermes gateway start` 실행 후 안 되면 권한 → 접두어 → 중복 실행 순서로 점검

디스코드는 채널 기반이라 팀원 여러 명이 같이 쓰기 유리하고, 권한 세팅이 텔레그램보다 무겁다. 개인 비서라면 텔레그램, 팀 공용이라면 디스코드가 맞는다.