Hermes Agent 디스코드 봇 연결 방법 완벽 가이드: 설치부터 Gateway 실행까지

AI Agent · Discord Bot · Hermes Gateway

Hermes Agent 디스코드 봇 연결 방법 완벽 가이드

NousResearch의 Hermes Agent를 Discord 봇으로 연결하는 방법을 단계별로 정리했습니다. Discord Developer Portal에서 봇을 만들고, Bot Token을 Hermes에 등록한 뒤, Messaging Gateway를 실행해 서버 채널이나 DM에서 AI Agent와 대화하는 구조까지 설명합니다.

대상: AI Agent 개발자 환경: Linux · macOS · WSL2 핵심: Discord Bot Token + Hermes Gateway

1. Hermes Agent란?

Hermes Agent는 NousResearch에서 공개한 AI Agent 프로젝트입니다. 터미널, 도구 사용, 메모리, 스킬, 자동화, 메시징 플랫폼 연결을 지원하며 Discord, Telegram, Slack 같은 외부 채팅 플랫폼에서도 AI Agent와 대화할 수 있습니다.

일반적인 Discord 챗봇은 사용자의 메시지를 받아 단순 응답을 반환하는 구조가 많습니다. 반면 Hermes Agent는 메시지를 받은 뒤 내부 Agent 파이프라인으로 전달하고, 모델 추론, 도구 실행, 메모리, 세션 기록, 슬래시 명령어까지 함께 처리할 수 있습니다.

핵심 요약

Hermes Agent를 Discord에 연결하려면 Discord 봇을 만든 뒤, Hermes의 gateway 프로세스가 해당 봇 토큰으로 Discord에 접속하도록 설정하면 됩니다.

2. Hermes Agent와 Discord 연결 구조

Hermes Agent의 Discord 연동은 단순 Webhook 방식이 아닙니다. Hermes는 Messaging Gateway라는 백그라운드 프로세스를 실행하고, 이 Gateway가 Discord 메시지를 수신해 Hermes Agent로 전달합니다.

전체 흐름

Discord 사용자 메시지
        ↓
Discord Bot
        ↓
Hermes Messaging Gateway
        ↓
권한 검사 / 멘션 검사 / 세션 조회
        ↓
Hermes Agent 실행
        ↓
LLM 응답 / 도구 실행 / 파일 처리 / 메모리 사용
        ↓
Discord 채널 또는 DM으로 응답

Discord에서 가능한 기능

DM 대화

봇에게 직접 메시지를 보내면 별도 멘션 없이 Hermes가 응답합니다.

서버 채널 응답

기본적으로 서버 채널에서는 봇을 @mention 해야 응답합니다.

스레드 대화

스레드 단위로 대화 세션을 분리할 수 있습니다.

파일·이미지·음성

첨부 파일, 이미지, 음성 메시지, TTS 응답까지 확장할 수 있습니다.

3. 준비물

Hermes Agent를 Discord 봇으로 연결하려면 아래 항목이 필요합니다.

준비물	설명	필수 여부
Discord 계정	Discord Developer Portal에서 애플리케이션과 봇을 생성해야 합니다.	필수
Discord 서버	봇을 초대할 서버가 필요합니다. 서버에 봇을 초대하려면 Manage Server 권한이 필요합니다.	필수
Linux / macOS / WSL2	Hermes Agent는 Linux, macOS, WSL2 환경에서 설치하는 방식이 권장됩니다.	필수
LLM Provider	OpenRouter, OpenAI 호환 엔드포인트, Nous Portal, Anthropic, Hugging Face 등 모델 공급자 설정이 필요합니다.	필수
Bot Token	Discord 봇이 로그인할 때 사용하는 비밀 키입니다.	필수
Discord User ID	누가 봇을 사용할 수 있는지 제한하기 위한 사용자 ID입니다.	강력 권장

보안 주의

Hermes Agent는 도구 실행과 터미널 작업까지 연결될 수 있으므로, Discord 봇을 아무나 사용할 수 있게 열어두면 매우 위험합니다. 반드시 DISCORD_ALLOWED_USERS 또는 DISCORD_ALLOWED_ROLES를 설정하세요.

4. Hermes Agent 설치

Hermes Agent는 공식 설치 스크립트를 통해 설치할 수 있습니다. Linux, macOS, WSL2 환경에서 아래 명령어를 실행합니다.

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

설치가 끝나면 현재 쉘 설정을 다시 불러옵니다.

source ~/.bashrc

# zsh를 사용한다면
source ~/.zshrc

정상 설치 여부를 확인합니다.

hermes --help
hermes doctor

Windows 사용자

Windows 네이티브 환경보다는 WSL2에서 설치하는 방식이 권장됩니다. 먼저 WSL2를 설치한 뒤 Ubuntu 같은 Linux 터미널 안에서 Hermes를 설치하세요.

5. Hermes에서 사용할 LLM 모델 설정

Discord 봇을 연결하기 전에 Hermes CLI에서 먼저 일반 채팅이 정상 작동하는지 확인하는 것이 좋습니다. 모델 설정은 아래 명령어로 진행합니다.

hermes model

여기서 OpenRouter, Nous Portal, Anthropic, OpenAI 호환 엔드포인트, 로컬 vLLM 서버 등 사용할 모델 공급자를 선택합니다.

로컬 vLLM 또는 OpenAI 호환 서버를 쓰는 경우 예시

hermes model
# Provider 선택: Custom Endpoint 또는 OpenAI-compatible endpoint
# Base URL 예시: http://127.0.0.1:8000/v1
# Model 이름 예시: Qwen/Qwen3.6-35B-A3B-FP8

먼저 CLI 채팅 테스트

hermes

Hermes 프롬프트가 열리면 간단히 테스트합니다.

현재 설정된 모델과 사용할 수 있는 도구를 요약해줘.

중요한 순서

Discord Gateway부터 연결하지 말고, 먼저 hermes 명령으로 기본 Agent 응답이 되는지 확인하세요. 기본 채팅이 안 되면 Discord 봇도 정상 응답하지 않습니다.

6. Discord Developer Portal에서 앱 생성

이제 Discord 쪽에서 Hermes Agent가 사용할 봇 계정을 만들어야 합니다.

Step 1. Discord Developer Portal 접속

브라우저에서 Discord Developer Portal에 접속한 뒤 로그인합니다.

Discord Developer Portal 바로가기

Step 2. New Application 클릭

오른쪽 상단의 New Application 버튼을 클릭합니다.
앱 이름을 입력합니다. 예: Hermes Agent
Developer Terms of Service에 동의합니다.
Create를 클릭합니다.

Step 3. Application ID 저장

생성 후 General Information 화면에서 Application ID를 확인할 수 있습니다. 나중에 수동 초대 URL을 만들 때 필요합니다.

7. Discord Bot 생성 및 Bot Token 발급

Hermes Gateway는 Discord Bot Token을 사용해 Discord에 로그인합니다.

왼쪽 메뉴에서 Bot을 클릭합니다.
봇 이름과 아이콘을 설정합니다.
Public Bot은 일반적으로 ON으로 둡니다.
Require OAuth2 Code Grant는 OFF로 둡니다.
Reset Token을 클릭합니다.
2FA가 켜져 있다면 인증 코드를 입력합니다.
표시된 Bot Token을 복사합니다.

Bot Token은 비밀번호와 같습니다

Bot Token을 GitHub, 블로그, Discord 채팅방, 공개 로그에 절대 올리면 안 됩니다. 토큰이 유출되면 다른 사람이 봇을 마음대로 제어할 수 있습니다. 유출되었다면 즉시 Discord Developer Portal에서 토큰을 재발급하세요.

8. Privileged Gateway Intents 설정

Discord 봇이 메시지 내용을 읽으려면 Gateway Intent 설정이 필요합니다. 특히 Hermes Agent Discord 연동에서는 Message Content Intent가 매우 중요합니다.

설정 위치

Discord Developer Portal → 내 Application 선택
왼쪽 메뉴에서 Bot 클릭
Privileged Gateway Intents 섹션으로 이동
Server Members Intent ON
Message Content Intent ON
하단의 Save Changes 클릭

Intent	용도	Hermes Discord 연동에서의 중요도
Presence Intent	사용자 온라인/오프라인 상태 확인	선택
Server Members Intent	서버 멤버 정보와 역할 확인	권장 또는 역할 기반 인증 시 필수
Message Content Intent	사용자가 보낸 메시지 텍스트 읽기	필수

봇이 온라인인데 응답하지 않는 가장 흔한 원인

Message Content Intent가 꺼져 있으면 봇은 메시지 이벤트를 받아도 실제 텍스트 내용을 읽지 못합니다. 이 경우 Hermes Gateway는 실행 중이어도 Discord에서 아무 응답을 하지 않는 것처럼 보일 수 있습니다.

9. Discord 서버에 봇 초대하기

봇을 만든 뒤에는 OAuth2 초대 URL을 통해 Discord 서버에 추가해야 합니다.

방법 A. Installation 탭 사용

Developer Portal에서 Installation 메뉴를 엽니다.
Guild Install을 활성화합니다.
Scopes에 bot, applications.commands를 선택합니다.
필요한 Bot Permissions를 선택합니다.
생성된 Discord Provided Link로 서버에 초대합니다.

방법 B. 수동 초대 URL 사용

Application ID를 알고 있다면 아래 형식으로 초대 URL을 만들 수 있습니다.

https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274878286912

YOUR_APP_ID 부분을 Discord Developer Portal에서 확인한 Application ID로 바꾸면 됩니다.

권장 권한

View Channels
Send Messages
Embed Links
Attach Files
Read Message History
Send Messages in Threads
Add Reactions

권한 숫자 참고

Hermes 공식 문서 기준 권장 Permission Integer는 274878286912입니다. 최소 권한만 줄 경우 117760을 사용할 수 있지만, 파일·스레드·리액션 기능을 고려하면 권장값을 사용하는 편이 편합니다.

10. Discord User ID 확인하기

Hermes Agent는 누가 봇을 사용할 수 있는지 제한하기 위해 Discord User ID를 사용합니다. 이 설정을 하지 않으면 기본적으로 접근이 차단될 수 있습니다.

Developer Mode 켜기

Discord 앱 또는 웹 Discord를 엽니다.
User Settings로 들어갑니다.
Advanced 메뉴를 엽니다.
Developer Mode를 ON으로 변경합니다.

User ID 복사

본인 프로필 또는 메시지에서 사용자 이름을 우클릭합니다.
Copy User ID를 클릭합니다.
복사된 긴 숫자를 저장해 둡니다.

예시:

284102345871466496

11. Hermes Agent에 Discord 봇 정보 등록하기

Hermes Discord 설정은 두 가지 방식으로 할 수 있습니다. 초보자라면 대화형 설정 마법사를 사용하는 것이 가장 안전합니다.

방법 A. 대화형 설정

hermes gateway setup

실행 후 플랫폼 목록에서 Discord를 선택하고, Discord Bot Token과 Discord User ID를 입력합니다.

방법 B. 수동 설정

~/.hermes/.env 파일에 Discord 관련 값을 직접 추가할 수 있습니다.

# ~/.hermes/.env

DISCORD_BOT_TOKEN=your-discord-bot-token
DISCORD_ALLOWED_USERS=284102345871466496

여러 사용자 허용

DISCORD_ALLOWED_USERS=284102345871466496,198765432109876543

역할 기반 허용

서버에서 특정 역할을 가진 사람에게만 사용 권한을 주고 싶다면 DISCORD_ALLOWED_ROLES를 사용할 수 있습니다.

DISCORD_ALLOWED_ROLES=987654321098765432,876543210987654321

절대 권장하지 않는 설정

GATEWAY_ALLOW_ALL_USERS=true

이 설정은 모든 사용자가 봇을 사용할 수 있게 만듭니다. Hermes가 터미널 도구나 파일 도구를 사용할 수 있는 환경이라면 매우 위험합니다. 개인 테스트 서버에서도 가급적 사용하지 마세요.

12. Hermes Gateway 실행하기

Discord 봇을 온라인 상태로 만들려면 Hermes Gateway를 실행해야 합니다.

포그라운드 실행

hermes gateway

정상적으로 실행되면 Discord 서버에서 봇이 온라인으로 표시됩니다. 봇에게 DM을 보내거나, 서버 채널에서 봇을 멘션해 테스트합니다.

테스트 메시지 예시

@Hermes Agent 안녕, 현재 네가 사용할 수 있는 명령어를 알려줘.

서비스로 설치하기

운영 환경에서는 Gateway를 계속 켜두기 위해 서비스로 설치하는 것이 좋습니다.

Linux user service

hermes gateway install
hermes gateway start
hermes gateway status

Linux system service

sudo hermes gateway install --system
sudo hermes gateway start --system
sudo hermes gateway status --system

macOS launchd

hermes gateway install
hermes gateway start
hermes gateway status

로그 확인

# Linux user service
journalctl --user -u hermes-gateway -f

# Linux system service
journalctl -u hermes-gateway -f

# macOS
tail -f ~/.hermes/logs/gateway.log

13. Discord 채널에서 Hermes가 동작하는 방식

Hermes Discord 봇은 DM, 서버 채널, 스레드에서 동작 방식이 조금씩 다릅니다.

위치	기본 동작	설명
DM	모든 메시지에 응답	봇을 멘션할 필요가 없습니다.
서버 일반 채널	@mention이 있을 때만 응답	다른 대화에 봇이 끼어드는 것을 방지합니다.
Free-response 채널	멘션 없이 응답	봇 전용 채널을 만들 때 유용합니다.
스레드	같은 스레드에서 응답	대화 맥락을 스레드 단위로 분리할 수 있습니다.
공유 채널	기본적으로 사용자별 세션 분리	Alice와 Bob이 같은 채널에서 말해도 서로 다른 대화 기록을 가집니다.

멘션 없이 응답하는 채널 만들기

봇 전용 채널에서는 매번 @Hermes를 붙이는 것이 번거로울 수 있습니다. 이 경우 특정 채널 ID를 DISCORD_FREE_RESPONSE_CHANNELS에 등록합니다.

# ~/.hermes/.env

DISCORD_FREE_RESPONSE_CHANNELS=123456789012345678

모든 서버 채널에서 멘션 없이 응답하게 하기

DISCORD_REQUIRE_MENTION=false

주의

DISCORD_REQUIRE_MENTION=false는 모든 채널 메시지에 봇이 반응할 수 있게 만듭니다. 일반 서버에서는 봇 전용 채널만 Free-response로 등록하는 방식이 더 안전합니다.

14. 운영 환경에서 권장하는 보안 설정

Hermes Agent는 일반 챗봇보다 강력합니다. 파일 읽기, 터미널 실행, 도구 호출 등이 가능할 수 있으므로 운영 환경에서는 반드시 보안 설정을 적용해야 합니다.

권장 .env 예시

# ~/.hermes/.env

DISCORD_BOT_TOKEN=your-discord-bot-token
DISCORD_ALLOWED_USERS=284102345871466496
DISCORD_REQUIRE_MENTION=true
DISCORD_REACTIONS=true
DISCORD_ALLOW_MENTION_EVERYONE=false
DISCORD_ALLOW_MENTION_ROLES=false
DISCORD_ALLOW_MENTION_USERS=true
DISCORD_ALLOW_MENTION_REPLIED_USER=true

권장 config.yaml 예시

# ~/.hermes/config.yaml

discord:
  require_mention: true
  free_response_channels:
    - 123456789012345678
  auto_thread: true
  reactions: true
  ignored_channels: []
  no_thread_channels: []
  allow_mentions:
    everyone: false
    roles: false
    users: true
    replied_user: true

group_sessions_per_user: true

display:
  tool_progress: "all"

Docker 격리 권장

Hermes가 터미널 도구를 사용할 수 있다면 로컬 머신 전체를 직접 조작할 수 있는 위험이 있습니다. 가능하면 Docker 백엔드를 사용해 명령어 실행 환경을 격리하세요.

hermes config set terminal.backend docker

항목	권장값	이유
사용자 제한	`DISCORD_ALLOWED_USERS` 또는 `DISCORD_ALLOWED_ROLES`	허용된 사용자만 Agent를 사용할 수 있게 제한
멘션 정책	`DISCORD_REQUIRE_MENTION=true`	일반 채널 대화에 봇이 무단 개입하지 않도록 방지
전체 멘션 차단	`DISCORD_ALLOW_MENTION_EVERYONE=false`	LLM 응답이 실수로 @everyone을 호출하는 문제 방지
세션 분리	`group_sessions_per_user: true`	공유 채널에서도 사용자별 대화 맥락 분리
터미널 격리	`terminal.backend docker`	로컬 파일 시스템과 운영 환경 보호

15. 자주 발생하는 오류 해결

1) 봇은 온라인인데 메시지에 응답하지 않음

원인: Message Content Intent가 꺼져 있을 가능성이 높습니다.

해결:

Discord Developer Portal → Application → Bot으로 이동
Privileged Gateway Intents에서 Message Content Intent ON
Save Changes 클릭
hermes gateway 재시작

2) Disallowed Intents 오류

원인: Hermes가 요청하는 Intent가 Developer Portal에서 활성화되어 있지 않습니다.

해결: Bot 설정에서 필요한 Privileged Gateway Intents를 켜고 Gateway를 재시작합니다.

3) 특정 채널에서만 봇이 응답하지 않음

원인: 봇 역할에 해당 채널을 볼 권한이 없을 수 있습니다.

해결: 채널 권한에서 봇 역할에 View Channel, Send Messages, Read Message History 권한을 부여합니다.

4) 403 Forbidden 오류

원인: 봇에게 필요한 Discord 권한이 부족합니다.

해결: 권장 Permission Integer가 포함된 초대 URL로 다시 초대하거나 서버 역할 권한을 수정합니다.

5) Bot is offline

원인: Hermes Gateway가 실행 중이 아니거나 Bot Token이 잘못되었습니다.

해결:

hermes gateway status
hermes gateway

토큰을 재발급했다면 ~/.hermes/.env의 DISCORD_BOT_TOKEN을 업데이트하세요.

6) User not allowed 또는 봇이 나를 무시함

원인: 내 Discord User ID가 DISCORD_ALLOWED_USERS에 없습니다.

해결:

DISCORD_ALLOWED_USERS=내_DISCORD_USER_ID

수정 후 Gateway를 재시작합니다.

hermes gateway stop
hermes gateway start

16. FAQ

Hermes Agent Discord 봇은 웹훅 방식인가요?

아닙니다. Hermes는 Discord Bot Token으로 Gateway에 연결하고, 들어오는 메시지를 Hermes Agent 파이프라인으로 전달하는 방식입니다. 따라서 세션, 도구, 메모리, 슬래시 명령어 등을 함께 사용할 수 있습니다.

Discord 서버 채널에서 매번 @mention 해야 하나요?

기본값은 그렇습니다. 서버 채널에서는 봇을 멘션해야 응답합니다. 다만 DISCORD_FREE_RESPONSE_CHANNELS에 특정 채널 ID를 등록하면 해당 채널에서는 멘션 없이 응답하게 만들 수 있습니다.

봇을 여러 사람이 함께 사용할 수 있나요?

가능합니다. DISCORD_ALLOWED_USERS에 여러 User ID를 쉼표로 넣거나, DISCORD_ALLOWED_ROLES로 특정 역할을 허용하면 됩니다.

같은 채널에서 여러 사람이 말하면 대화 기록이 섞이나요?

기본 설정인 group_sessions_per_user: true에서는 사용자별로 세션이 분리됩니다. 즉 같은 채널에서 말해도 각 사용자는 별도 대화 기록을 가집니다.

Discord 음성 메시지도 사용할 수 있나요?

Hermes Agent는 Discord 음성 메시지 전사와 TTS 응답을 지원할 수 있습니다. 음성 기능을 사용하려면 STT/TTS 관련 추가 설정이 필요합니다.

운영 서버에 연결해도 안전한가요?

바로 운영 서버에 연결하는 것은 권장하지 않습니다. 먼저 Docker 또는 별도 개발 서버에서 테스트하고, 허용 사용자, 허용 채널, 멘션 제한, 터미널 격리, 로그 관리를 적용한 뒤 운영 환경에 연결하세요.

마무리

Hermes Agent를 Discord 봇으로 연결하는 핵심은 간단합니다. 먼저 Hermes CLI가 정상 작동하도록 모델을 설정하고, Discord Developer Portal에서 봇을 만든 뒤, Bot Token과 허용 사용자 ID를 Hermes Gateway에 등록하면 됩니다.

다만 Hermes는 일반 챗봇보다 강력한 Agent 시스템이므로, 반드시 사용자 허용 목록과 권한 제한을 설정해야 합니다. 개인용 봇이라면 DISCORD_ALLOWED_USERS, 팀용 봇이라면 DISCORD_ALLOWED_ROLES와 채널 제한을 함께 사용하는 것을 추천합니다.

Hermes Agent GitHub 저장소 보기

참고 자료

'AI' 카테고리의 다른 글

HBM 대체 기술 HB3DM/ZAM이 AI 데이터센터를 바꾸는 이유 (1)	2026.05.04
Qwen-Scope란? Qwen3·Qwen3.5 내부를 해석하는 SAE 모델 완벽 가이드 (0)	2026.05.04
Warp 터미널 사용법 완벽 가이드: AI Agent Mode, 설치, GitHub 오픈소스 빌드까지 (1)	2026.04.30
Hermes WebUI 설치 및 사용법 총정리: Hermes Agent를 웹 브라우저와 모바일에서 사용하는 방법 (0)	2026.04.29
UI-TARS란? ByteDance가 공개한 GUI 자동화 AI 에이전트 모델 완벽 분석 (1)	2026.04.25

Hermes Agent 디스코드 봇 연결 방법 완벽 가이드: 설치부터 Bot Token, Gateway 실행, 보안 설정까지

1. Hermes Agent란?

2. Hermes Agent와 Discord 연결 구조

전체 흐름

Discord에서 가능한 기능

3. 준비물

4. Hermes Agent 설치

5. Hermes에서 사용할 LLM 모델 설정

로컬 vLLM 또는 OpenAI 호환 서버를 쓰는 경우 예시

먼저 CLI 채팅 테스트

6. Discord Developer Portal에서 앱 생성

Step 1. Discord Developer Portal 접속

Step 2. New Application 클릭

Step 3. Application ID 저장

7. Discord Bot 생성 및 Bot Token 발급

8. Privileged Gateway Intents 설정

설정 위치

9. Discord 서버에 봇 초대하기

방법 A. Installation 탭 사용

방법 B. 수동 초대 URL 사용

권장 권한

10. Discord User ID 확인하기

Developer Mode 켜기

User ID 복사

11. Hermes Agent에 Discord 봇 정보 등록하기

방법 A. 대화형 설정

방법 B. 수동 설정

여러 사용자 허용

역할 기반 허용

12. Hermes Gateway 실행하기

포그라운드 실행

테스트 메시지 예시

서비스로 설치하기

Linux user service

Linux system service

macOS launchd

로그 확인

13. Discord 채널에서 Hermes가 동작하는 방식

멘션 없이 응답하는 채널 만들기

모든 서버 채널에서 멘션 없이 응답하게 하기

14. 운영 환경에서 권장하는 보안 설정

권장 .env 예시

권장 config.yaml 예시

Docker 격리 권장

15. 자주 발생하는 오류 해결

1) 봇은 온라인인데 메시지에 응답하지 않음

2) Disallowed Intents 오류

3) 특정 채널에서만 봇이 응답하지 않음

4) 403 Forbidden 오류

5) Bot is offline

6) User not allowed 또는 봇이 나를 무시함

16. FAQ

마무리

참고 자료

'AI' 카테고리의 다른 글

'AI' Related Articles

티스토리툴바