Discord 설정 가이드
이 가이드는 Discord 봇을 처음부터 생성하고 권한을 설정한 후 Elftia에 연결하여, AI Agent가 Discord 서버 내에서 작동하도록 하는 전체 과정을 안내합니다.
사전 준비
- Discord 계정
- 관리자 권한이 있는 Discord 서버 (또는 새 테스트 서버 생성)
- Elftia 설치 및 LLM 공급자 최소 하나 이상 설정 완료
1단계: Discord 애플리케이션 생성
- Discord Developer Portal 열기
- 오른쪽 상단의 New Application 클릭
- 애플리케이션 이름 입력 (예:
Elftia Bot) 후 Create 클릭 - 왼쪽 메뉴에서 Bot 클릭
- 페이지에 표시된 봇 사용자 이름 확인
2단계: 봇 토큰 얻기
- Bot 페이지에서 Token 섹션 찾기
- Reset Token 클릭 (처음 생성하는 경우 토큰이 바로 표시됨)
- 토큰을 복사하고 안전하게 보관
:::danger 보안 경고 봇 토큰은 봇의 비밀번호와 동일합니다. 절대 공개적으로 공유하거나 저장소에 커밋하지 마세요. 토큰이 유출된 경우 Developer Portal에서 즉시 재설정하세요. :::
3단계: 봇 권한 설정
Bot 페이지에서 Privileged Gateway Intents 섹션을 찾아 다음 두 가지 옵션을 활성화합니다:
- MESSAGE CONTENT INTENT — 봇이 메시지 내용을 읽을 수 있도록 허용 (반드시 활성화)
- SERVER MEMBERS INTENT — 서버 멤버 정보 조회 허용 (권장)
페이지 하단의 Save Changes를 클릭해 저장합니다.
:::info 메시지 콘텐츠 Intent가 필요한 이유 2022년부터 Discord는 모든 봇이 메시지 내용을 읽으려면 Message Content Intent를 명시적으로 활성화하도록 요구합니다. 활성화하지 않으면 봇이 빈 메시지만 수신합니다. :::
4단계: 초대 링크 생성
- 왼쪽 메뉴에서 OAuth2 → URL Generator 클릭
- SCOPES에서
bot체크 - BOT PERMISSIONS에서 다음 권한 체크:
| 권한 | 설명 |
|---|---|
| Send Messages | 메시지 전송 |
| Read Message History | 메시지 기록 읽기 |
| View Channels | 채널 보기 |
| Embed Links | 임베드 링크 전송 |
| Attach Files | 파일 첨부 전송 |
| Add Reactions | 이모지 반응 추가 |
| Use External Emojis | 외부 이모지 사용 |
- 페이지 하단의 GENERATED URL 복사
5단계: 서버에 봇 초대
- 이전 단계에서 복사한 초대 링크를 브라우저에서 열기
- 대상 서버 선택 (해당 서버에서 서버 관리 권한이 있어야 함)
- 권한 목록 검토
- 승인을 클릭하고 CAPTCHA 완료
초대에 성공하면 서버의 멤버 목록에서 봇을 확인할 수 있습니다 (아직 연결되지 않아 오프라인으로 표시됨).
6단계: Elftia에서 설정
- Elftia를 열고 설정 → Channel 이동
- 채널 추가 클릭
- Discord 선택 (플러그인이 설치되지 않은 경우 Marketplace에서 자동으로 다운로드됨)
- 설정 폼 작성:
| 필드 | 값 |
|---|---|
| 표시 이름 | 이 인스턴스의 이름 (예: 내 Discord 봇) |
| 봇 토큰 | 2단계에서 얻은 토큰 붙여넣기 |
- 연결 테스트를 클릭해 토큰이 유효한지 확인
- 저장을 클릭해 Channel 인스턴스 생성
7단계: 트리거 규칙 설정
인스턴스를 생성한 후 적절한 트리거 규칙을 설정하는 것을 권장합니다:
| 모드 | 권장 상황 | 설정 |
|---|---|---|
mention | 다중 사용자 서버 | @멘션 시에만 Agent 응답. mentionName을 봇의 사용자 이름으로 설정 |
all | 전용/테스트 서버 | 모든 메시지에 Agent 응답; 개인 사용에 적합 |
keyword | 특정 주제 채널 | 트리거 키워드 목록 설정; 대소문자 구분 없음 |
dm_only | 공개 서버 | 다이렉트 메시지에만 Agent 응답; 그룹에서는 완전히 침묵 |
Channel 설정에서 트리거 모드를 선택하고 해당 파라미터를 설정합니다.
8단계: 연결 시작
- Channel 페이지에서 방금 생성한 Discord 인스턴스 찾기
- 연결 버튼 클릭 (또는 자동 연결 활성화)
- 상태가 연결됨 (녹색 표시기)으로 변할 때까지 기다리기
- Discord에서 봇에게 메시지를 보내 테스트
mention 모드를 사용하는 경우 메시지에 봇을 @멘션하는 것을 잊지 마세요:
@Elftia Bot 안녕하세요, 자기소개를 해주세요
Discord 플랫폼 기능
| 기능 | 지원 여부 |
|---|---|
| 그룹 채팅 | 지원 |
| 다이렉트 메시지 (DM) | 지원 |
| 첨부 파일/파일 전송 | 지원 |
| 타이핑 표시기 | 지원 |
| 이모지 반응 | 지원 |
| 스레드/포럼 | 부분 지원 |
| 메시지 길이 제한 | 2,000자 |
Agent의 응답이 2,000자를 초과하면 시스템이 자동으로 여러 메시지로 분할합니다. 분할은 줄바꿈 우선, 그 다음 공백, 마지막으로 강제 절단 순으로 이루어집니다.
자주 묻는 질문
봇이 오프라인으로 표시됨
- Elftia의 Channel 인스턴스 상태가 "연결됨"으로 표시되는지 확인
- 봇 토큰이 올바른지 확인
- Elftia 앱이 실행 중인지 확인 (Channel 플러그인은 메인 프로세스에서 실행되므로 앱을 종료하면 봇도 오프라인 상태가 됨)
봇이 온라인이지만 응답하지 않음
- 트리거 규칙 설정이 올바른지 확인.
mention모드를 사용하는 경우mentionName이 봇의 실제 사용자 이름과 일치하는지 확인 - Developer Portal에서 MESSAGE CONTENT INTENT가 활성화되어 있는지 확인
- Elftia 로그에서 보안 파이프라인 차단 기록(RateLimiter, PromptGuardian 등) 확인
- Agent에 LLM 공급자와 모델이 올바르게 설정되어 있는지 확인
메시지가 잘림
Discord의 단일 메시지 제한은 2,000자입니다. Agent의 응답이 너무 길면 시스템이 자동으로 분할해 여러 메시지로 전송합니다. 응답이 불완전하게 보이면 후속 메시지를 확인하세요.
권한 오류 (Missing Permissions)
- 봇이 대상 채널에서 Send Messages 및 View Channel 권한을 가지고 있는지 확인
- 서버 역할 설정의 재정의 규칙이 봇의 권한을 제한하고 있는지 확인
- Developer Portal에서 초대 링크를 재생성하고 필요한 모든 권한이 체크되어 있는지 확인
여러 Discord 인스턴스
Elftia에서 여러 Discord Channel 인스턴스를 생성할 수 있으며, 각 인스턴스는 서로 다른 봇 토큰을 사용하고 서로 다른 서버에 연결할 수 있습니다. 각 인스턴스는 독립적인 트리거 규칙과 보안 정책을 가질 수 있습니다.
다음 단계
- 트리거 규칙 및 보안 — 트리거 모드와 보안 파이프라인 설정에 대해 자세히 알아보기
- 다중 플랫폼 채널 개요 — 지원되는 다른 플랫폼 살펴보기