Discord 연동
기준일: 2026-07-26
난이도: 중급
공식 기준: Discord
개요
Hermes를 Discord 봇으로 연결합니다. 서버·DM에서 멘션/명령으로 에이전트를 호출하고, 미디어·음성·포럼 등 Discord 특성을 지원합니다.
핵심 개념
| 항목 | 내용 |
|---|---|
| 라이브러리 | Discord.py 계열 gateway 어댑터 |
| 필수 | Bot Token + Message Content Intent 등 Privileged Intents |
| 식별 | Discord User snowflake ID |
| 채널 동작 | 서버는 멘션/설정 기반, DM은 직접 응답 |
| 보안 | DISCORD_ALLOWED_USERS allowlist 기본 권장 |
상세
설정 단계 (요약)
- Discord Developer Portal에서 Application 생성
- Bot 생성, 토큰 복사 (
DISCORD_BOT_TOKEN) - Privileged Gateway Intents: Message Content Intent 필수. 서버 멤버/프레즌스가 필요하면 해당 Intent
- OAuth2 URL Generator로
bot+ 필요 스코프 초대 - 서버에 초대 후 본인 User ID 확인 (개발자 모드 → 프로필 복사 ID)
hermes gateway setup에서 Discord 선택, 또는.env수동 설정
DISCORD_BOT_TOKEN=...
DISCORD_ALLOWED_USERS=123456789012345678
# DISCORD_ALLOW_ALL_USERS=true # 비권장
DISCORD_HOME_CHANNEL=... # cron/알림 기본 채널
hermes gateway
hermes gateway install
동작
- DM: 멘션 없이 응답 (allowlist/pairing 통과 시)
- 서버 채널: 기본적으로 멘션·슬래시·설정한 free-response 규칙
- 스레드/포럼: 채널·스레드 키로 세션 격리 (공유 컨텍스트에 유리)
슬래시·스킬·모델 피커
네이티브 슬래시로 Hermes 명령·스킬 등록. 인터랙티브 모델 피커·clarify 버튼 등 UI 요소는 원문 Configuration / Interactive 절 참고. 스킬 슬래시 동기화 후 Discord 명령 메뉴 갱신에 시간이 걸릴 수 있습니다.
미디어·음성
- 수신: 이미지·첨부 → 비전/파일 도구
- 송신: 응답의
MEDIA:경로 - Voice: 플랫폼 음성 메시지·(설정 시) 음성 채널 연동 — Voice Mode 가이드
트러블슈팅
| 문제 | 확인 |
|---|---|
| 응답 없음 | Intent, 초대 권한, allowlist, gateway 로그 |
| 내용 못 읽음 | Message Content Intent + 재초대 |
| 슬래시 없음 | 명령 동기화·권한·캐시 |
| 권한 오류 | 채널 읽기/쓰기/임베드/파일 권한 |
보안
토큰 유출 금지, allowlist 필수에 가깝게, 공개 서버에서 ALLOW_ALL 금지, 터미널 툴 활성 시 특히 주의.
체크리스트
- 공식 원문과 명령·설정 키를 대조했다
- 로컬/
config.yaml/.env에서 재현 경로를 확인했다 - 권한·allowlist·시크릿 노출을 점검했다
- 실패 시 롤백·비활성화 방법을 알고 있다
다음 단계
- 공식 문서: Discord
- 메시징 게이트웨이
- Hermes Agent 소개
기준일: 2026-07-26 — 공식 문서 동기화 코퍼스