디스코드

anchor alias

anchor alias

anchor alias

anchor alias

디스코드 설정

Hermes 에이전트는 디스코드와 봇으로 통합되어 사용자가 직접 메시지나 서버 채널을 통해 AI 어시스턴트와 대화할 수 있습니다. 이 봇은 사용자의 메시지를 수신하고, Hermes 에이전트 파이프라인(도구 사용, 메모리, 추론 포함)을 통해 처리한 후 실시간으로 응답합니다. 텍스트, 음성 메시지, 파일 첨부, 슬래시 명령어를 지원합니다.

설정 전에, 대부분의 사람들이 가장 궁금해하는 부분은 Hermes가 서버에 들어가면 어떻게 행동하는지입니다.

Hermes의 행동

상황	행동
DMs	Hermes는 모든 메시지에 응답합니다. @mention가 필요 없습니다. 각 DM은 자체 세션을 가집니다.
서버 채널	기본적으로, Hermes는 당신이 @mention 할 때만 응답합니다. 언급하지 않고 채널에 글을 올리면 Hermes는 메시지를 무시합니다.
자유 응답 채널	DISCORD_FREE_RESPONSE_CHANNELS를 사용하여 특정 채널에서 멘션을 없앨 수 있으며, DISCORD_REQUIRE_MENTION=false를 사용하여 멘션을 전체적으로 비활성화할 수 있습니다. 이러한 채널의 메시지는 인라인으로 답변되며 — 자동 스레딩이 건너뛰어 채널을 가벼운 채팅 상태로 유지합니다.
스레드	Hermes는 같은 스레드에서 답장합니다. 해당 스레드나 상위 채널이 자유 응답으로 설정되지 않는 한 언급 규칙은 계속 적용됩니다. 스레드는 세션 기록을 위해 상위 채널과 분리되어 유지됩니다.
여러 사용자와 공유된 채널	기본적으로 Hermes는 안전성과 명확성을 위해 채널 내에서 사용자별로 세션 기록을 분리합니다. 같은 채널에서 두 사람이 대화하더라도 이를 명시적으로 비활성화하지 않는 한 하나의 기록을 공유하지 않습니다.
다른 사용자를 언급한 메시지	DISCORD_IGNORE_NO_MENTION가 true일 때(기본값), Hermes는 메시지가 다른 사용자를 @멘션하지만 봇이 언급되지 않으면 침묵을 유지합니다. 이는 봇이 다른 사람을 대상으로 한 대화에 끼어드는 것을 방지합니다. 누구를 멘션했는지에 상관없이 봇이 모든 메시지에 응답하게 하려면 false로 설정하세요. 이는 DM이 아닌 서버 채널에만 적용됩니다.

팁

일반적인 봇 도움 채널을 원해서 사람들이 매번 태그하지 않고 Hermes와 대화할 수 있게 하고 싶다면, 그 채널을 DISCORD_FREE_RESPONSE_CHANNELS에 추가하세요.

디스코드 게이트웨이 모델

Discord에서 Hermes는 상태를 유지하지 않고 응답하는 웹훅이 아닙니다. 이는 전체 메시징 게이트웨이를 통해 실행된다는 것을 의미하며, 각 들어오는 메시지는 다음 과정을 거칩니다:

1. 인증 (DISCORD_ALLOWED_USERS)
2. 언급 / 자유 응답 확인
3. 세션 조회
4. 세션 기록 불러오는 중
5. 일반 Hermes 에이전트 실행, 도구, 메모리, 슬래시 명령 포함
6. 응답을 Discord로 전달

그것은 중요합니다. 왜냐하면 바쁜 서버에서의 행동은 Discord 라우팅과 Hermes 세션 정책 모두에 달려 있기 때문입니다.

디스코드의 세션 모델

기본적으로:

• 각 DM마다 자체 세션을 갖습니다
• 각 서버 스레드는 자체 세션 네임스페이스를 갖습니다
• 공유 채널의 각 사용자는 해당 채널 안에서 자신의 세션을 갖습니다

그래서 앨리스와 밥이 둘 다 #research에서 헤르메스와 대화하더라도, 같은 공개 디스코드 채널을 사용하더라도 헤르메스는 기본적으로 이를 별도의 대화로 취급합니다.

이것은 config.yaml에 의해 제어됩니다:

group_sessions_per_user: true

전체 방에 대해 하나의 공유 대화를 명시적으로 원할 경우에만 false으로 설정하세요:

group_sessions_per_user: false

공유 세션은 협업용 공간에서 유용할 수 있지만, 다음을 의미하기도 합니다:

• 사용자들은 컨텍스트 성장과 토큰 비용을 공유합니다
• 한 사람의 길고 도구 중심적인 작업이 다른 사람들의 상황을 부풀릴 수 있다
• 한 사람의 비행 중 실행이 같은 방에서 다른 사람의 후속 작업을 방해할 수 있습니다

인터럽트와 동시성

Hermes는 세션 키로 실행 중인 에이전트를 추적합니다.

기본 group_sessions_per_user: true로:

• 앨리스가 자신의 비행 중 요청을 중단하는 것은 해당 채널에서 앨리스의 세션에만 영향을 미칩니다
• 밥은 앨리스의 기록을 이어받거나 앨리스의 실행을 방해하지 않고 같은 채널에서 계속 이야기할 수 있습니다

group_sessions_per_user: false와 함께:

• 전체 방이 해당 채널/스레드에 대해 하나의 실행 에이전트 슬롯을 공유합니다
• 다른 사람들의 후속 메시지는 서로를 방해하거나 대기열에 쌓일 수 있습니다

이 가이드는 Discord 개발자 포털에서 봇을 만드는 것부터 첫 메시지를 보내는 것까지 전체 설정 과정을 안내합니다.

1단계: 디스코드 애플리케이션 만들기

1. Discord 개발자 포털로 이동하여 Discord 계정으로 로그인하세요.
2. 오른쪽 상단의 새 애플리케이션을 클릭하세요.
3. 응용 프로그램 이름을 입력하세요(예: "Hermes Agent") 그리고 개발자 서비스 약관에 동의하세요.
4. 만들기를 클릭하세요.

일반 정보페이지에 도착하게 됩니다. 나중에 초대 URL을 만들 때 필요하므로애플리케이션 ID를 기록해 두세요.

2단계: 봇 만들기

1. 왼쪽 사이드바에서 봇을 클릭하세요.
2. Discord는 사용자의 애플리케이션을 위해 자동으로 봇 사용자를 생성합니다. 사용자는 봇의 사용자 이름을 보게 되며, 이를 맞춤 설정할 수 있습니다.
3. 권한 부여 흐름 아래:
   • 공용 봇을 ON으로 설정 — Discord에서 제공한 초대 링크를 사용하려면 필요합니다(권장). 이렇게 하면 설치 탭에서 기본 인증 URL을 생성할 수 있습니다.
   • Require OAuth2 Code Grant를 OFF로 유지하세요.

팁

이 페이지에서 봇의 맞춤 아바타와 배너를 설정할 수 있습니다. 이것이 사용자가 Discord에서 보게 될 모습입니다.

Private Bot Alternative

봇을 비공개로 유지하려면 (공개 봇 = OFF), 설치 탭 대신 5단계에서 수동 URL 방법을 사용해야 합니다. Discord에서 제공하는 링크를 사용하려면 공개 봇이 활성화되어 있어야 합니다.

단계 3: 권한 있는 게이트웨이 인텐트 활성화

이것은 전체 설정에서 가장 중요한 단계입니다. 올바른 인텐트가 활성화되지 않으면, 봇은 Discord에 연결될 수 있지만 메시지 내용을 읽을 수 없습니다.

Bot페이지에서 아래로 스크롤하여Privileged Gateway Intents를 찾으세요. 세 가지 토글이 보일 것입니다:

의도	목적	필수인가요?
프레즌스 인텐트	사용자의 온라인/오프라인 상태 보기	선택 사항
서버 멤버 인텐트	회원 목록에 접근하고, 사용자 이름을 확인하세요	필수
메시지 내용 의도	메시지의 텍스트 내용을 읽다	필수

**서버 멤버 인텐트(Server Members Intent)**와 **메시지 내용 인텐트(Message Content Intent)**를 **켜기(ON)**로 전환하여 활성화하세요.

• **메시지 내용 의도(Message Content Intent)**가 없으면, 봇은 메시지 이벤트를 받지만 메시지 텍스트가 비어 있습니다 — 봇은 당신이 입력한 내용을 문자 그대로 볼 수 없습니다.
• 서버 회원 의도(Server Members Intent) 없이, 봇은 허용된 사용자 목록의 사용자 이름을 확인할 수 없으며 누가 메시지를 보내는지 식별하지 못할 수 있습니다.

This is the #1 reason Discord bots don't work

봇이 온라인 상태이지만 메시지에 전혀 응답하지 않는다면, **메시지 내용 인텐트(Message Content Intent)**가 거의 확실히 비활성화되어 있습니다. 개발자 포털(Developer Portal)로 돌아가서, 애플리케이션 → 봇 → 권한 있는 게이트웨이 인텐트(Privileged Gateway Intents)를 선택하고 **메시지 내용 인텐트(Message Content Intent)**가 켜져 있는지 확인하세요. **변경 사항 저장(Save Changes)**을 클릭하세요.

서버 수에 관하여:

• 만약 당신의 봇이 100개 미만의 서버에 있다면, 인텐트를 자유롭게 켜고 끌 수 있습니다.
• 만약 당신의 봇이 100개 이상의 서버에 있다면, Discord는 권한 있는 인텐트를 사용하기 위해 인증 신청서를 제출할 것을 요구합니다. 개인적인 사용의 경우, 이것은 걱정할 필요가 없습니다.

페이지 하단에서 변경 사항 저장을 클릭하세요.

4단계: 봇 토큰 받기

봇 토큰은 Hermès 에이전트가 사용자의 봇으로 로그인할 때 사용하는 자격 증명입니다. 여전히 봇 페이지에 있습니다:

1. 토큰섹션에서토큰 재설정을 클릭합니다.
2. Discord 계정에서 2단계 인증이 활성화되어 있다면, 코드를 입력하세요.
3. Discord가 새 토큰을 표시합니다. 바로 복사하세요.

Token shown only once

토큰은 한 번만 표시됩니다. 잃어버리면 재설정하고 새로 생성해야 합니다. 토큰을 공개적으로 공유하거나 Git에 커밋하지 마세요 — 이 토큰을 가진 사람은 누구나 당신의 봇을 완전히 제어할 수 있습니다.

토큰을 안전한 곳에 보관하세요(예: 비밀번호 관리자). 8단계에서 필요합니다.

5단계: 초대 URL 생성

봇을 서버에 초대하려면 OAuth2 URL이 필요합니다. 이를 수행하는 방법은 두 가지가 있습니다:

옵션 A: 설치 탭 사용(추천)

:::note[Requires Public Bot] {#option-a-using-the-installation-tab-recommended} 이 방법은 2단계에서 **공개 봇(Public Bot)**을 ON으로 설정해야 합니다. 공개 봇을 OFF로 설정한 경우에는 대신 아래의 수동 URL 방법을 사용하세요.

:::

1. 왼쪽 사이드바에서 설치를 클릭합니다.
2. 설치 환경에서 길드 설치를 활성화하세요.
3. 설치 링크의 경우, Discord 제공 링크를 선택하세요.
4. 길드 설치의 기본 설치 설정에서:
   • 범위: bot와 applications.commands 선택
   • 권한: 아래에 나열된 권한을 선택하세요.

옵션 B: 수동 URL

다음 형식을 사용하여 초대 URL을 직접 만들 수 있습니다:

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

1단계에서 얻은 애플리케이션 ID로 YOUR_APP_ID을 교체하세요.

필수 권한

이것들은 봇이 필요로 하는 최소 권한입니다:

• 채널 보기 — 접근할 수 있는 채널을 확인하세요
• 메시지 보내기 — 메시지에 응답하기
• 링크 삽입 — 풍부한 형식의 응답
• 파일 첨부 — 이미지, 오디오 및 파일 출력 전송
• 메시지 기록 읽기 — 대화 맥락 유지

권장 추가 권한

• 스레드에서 메시지 보내기 — 스레드 대화에서 응답하기
• 반응 추가 — 메시지에 반응하여 확인 표시

권한 정수

레벨	권한 정수	포함된 내용
최소한의	117760	채널 보기, 메시지 보내기, 메시지 기록 읽기, 파일 첨부
추천	274878286912	위의 모든 것과 링크 삽입, 스레드에 메시지 보내기, 반응 추가

6단계: 서버에 초대하기

1. 브라우저에서 초대 URL을 열어보세요 (설치 탭에서 또는 직접 만든 URL에서).
2. 서버에 추가 드롭다운에서 서버를 선택하세요.
3. 계속을 클릭한 다음, 승인을 클릭하세요.
4. 요청되면 CAPTCHA를 완료하세요.

정보

봇을 초대하려면 Discord 서버에서 서버 관리 권한이 필요합니다. 드롭다운에서 서버가 보이지 않는다면 서버 관리자에게 초대 링크를 사용하도록 요청하세요.

승인 후, 봇이 서버의 멤버 목록에 표시됩니다(에르메스 게이트웨이를 시작할 때까지 오프라인 상태로 표시됩니다).

단계 7: 자신의 디스코드 사용자 ID 찾기

Hermes 에이전트는 Discord 사용자 ID를 사용하여 누가 봇과 상호작용할 수 있는지 제어합니다. 찾는 방법은 다음과 같습니다:

1. 디스코드를 엽니다 (데스크톱 또는 웹 앱).
2. 설정→고급→개발자 모드를 켜기로 전환하세요.
3. 설정을 닫습니다.
4. 자신의 사용자 이름(메시지, 멤버 목록 또는 프로필에서)을 마우스 오른쪽 버튼으로 클릭 → 사용자 ID 복사.

사용자 ID는 284102345871466496 같은 긴 숫자입니다.

팁

개발자 모드에서는 채널 ID와 서버 ID도 같은 방식으로 복사할 수 있습니다 — 채널이나 서버 이름을 오른쪽 클릭하고 'ID 복사'를 선택하세요. 홈 채널을 수동으로 설정하려면 채널 ID가 필요합니다.

8단계: Hermes 에이전트 구성

옵션 A: 대화형 설정 (권장)

안내 설정 명령을 실행하세요:

hermes gateway setup

프롬프트가 나타나면 Discord를 선택한 다음, 요청 시 봇 토큰과 사용자 ID를 붙여넣으세요.

옵션 B: 수동 설정

다음 내용을 ~/.hermes/.env 파일에 추가하세요:

# Required
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=284102345871466496

# Multiple allowed users (comma-separated)
# DISCORD_ALLOWED_USERS=284102345871466496,198765432109876543

그런 다음 게이트웨이를 시작하세요:

hermes gateway

봇은 몇 초 내에 Discord에서 온라인 상태가 되어야 합니다. 메시지를 보내 테스트해보세요 — DM 또는 봇이 볼 수 있는 채널에서 보낼 수 있습니다.

팁

지속적인 운영을 위해 hermes gateway를 백그라운드에서 실행하거나 systemd 서비스로 실행할 수 있습니다. 자세한 내용은 배포 문서를 참조하세요.

구성 참조

Discord 동작은 두 파일을 통해 제어됩니다: 자격 증명과 환경 수준 토글을 위한 ~/.hermes/.env, 구조화된 설정을 위한 ~/.hermes/config.yaml. 환경 변수는 둘 다 설정되어 있는 경우 항상 config.yaml 값보다 우선합니다.

환경 변수 (.env)

변수	필수	기본값	설명
DISCORD_BOT_TOKEN	예	—	Discord 개발자 포털에서 봇 토큰.
DISCORD_ALLOWED_USERS	예	—	봇과 상호작용할 수 있는 쉼표로 구분된 Discord 사용자 ID입니다. 이것이 없으면또는 DISCORD_ALLOWED_ROLES 없이 게이트웨이는 모든 사용자를 거부합니다.
DISCORD_ALLOWED_ROLES	No	—	쉼표로 구분된 Discord 역할 ID. 이 역할 중 하나를 가진 모든 회원은 권한이 부여됩니다 — DISCORD_ALLOWED_USERS와 OR 논리입니다. 연결 시 **서버 멤버 의도(Server Members Intent)**를 자동으로 활성화합니다. 관리팀이 바뀔 때 유용합니다: 새 모더레이터는 역할이 부여되는 즉시 접근 권한을 얻으며, 설정 푸시가 필요하지 않습니다.
DISCORD_HOME_CHANNEL	No	—	봇이 능동적으로 메시지를 보내는 채널 ID (크론 출력, 알림, 공지).
DISCORD_HOME_CHANNEL_NAME	No	"Home"	로그 및 상태 출력에서 홈 채널의 표시 이름.
DISCORD_COMMAND_SYNC_POLICY	No	"safe"	네이티브 슬래시 커맨드 시작 동기화를 제어합니다. "safe"는 기존 글로벌 커맨드의 차이를 비교하고 변경된 내용만 업데이트하며, Discord 메타데이터 변경을 패치로 적용할 수 없을 때 커맨드를 재생성합니다. "bulk"은 기존 tree.sync() 동작을 유지합니다. "off"은 시작 동기화를 완전히 건너뜁니다.
DISCORD_REQUIRE_MENTION	No	true	봇은 true일 때, @mentioned일 경우 서버 채널에서만 응답합니다. 모든 채널의 모든 메시지에 응답하려면 false로 설정하세요.
DISCORD_THREAD_REQUIRE_MENTION	No	false	true일 때, 스레드 내 언급 바로가기 기능이 비활성화됩니다 — 스레드는 채널과 동일하게 제한되며, 봇이 이미 참여했더라도 @mention이 필요합니다. 여러 봇이 하나의 스레드를 공유하고 각 봇이 명시적인 @mention에만 반응하게 하려면 이것을 사용하세요.
DISCORD_FREE_RESPONSE_CHANNELS	No	—	봇이 @mention를 요구하지 않고 응답하는 쉼표로 구분된 채널 ID, DISCORD_REQUIRE_MENTION가 true일 때도 마찬가지입니다.
DISCORD_IGNORE_NO_MENTION	No	true	true 할 때, 메시지가 다른 사용자에게 @mentions 하지만 봇을 언급하지 않는 경우 봇은 조용히 있습니다. 다른 사람을 대상으로 한 대화에 봇이 끼어드는 것을 방지합니다. 서버 채널에만 적용되며 DM에는 적용되지 않습니다.
DISCORD_AUTO_THREAD	No	true	true일 때, 텍스트 채널의 각 @mention마다 자동으로 새 스레드를 생성하므로 각 대화가 독립적으로 이루어집니다(슬랙 동작과 유사). 이미 스레드 안에 있거나 DM에 있는 메시지는 영향을 받지 않습니다.
DISCORD_ALLOW_BOTS	No	"none"	다른 Discord 봇의 메시지를 봇이 처리하는 방식을 제어합니다. "none" — 다른 모든 봇을 무시합니다. "mentions" — @mention Hermes인 봇의 메시지만 수락합니다. "all" — 모든 봇 메시지를 수락합니다.
DISCORD_REACTIONS	No	true	true일 때, 봇은 처리 중 메시지에 이모지 반응을 추가합니다(시작 시 👀, 성공 시 ✅, 오류 시 ❌). 반응을 완전히 비활성화하려면 false로 설정하세요.
DISCORD_IGNORED_CHANNELS	No	—	봇이 @mentioned일 때조차 절대 응답하지 않는 쉼표로 구분된 채널 ID. 다른 모든 채널 설정보다 우선합니다.
DISCORD_ALLOWED_CHANNELS	No	—	콤마로 구분된 채널 ID입니다. 설정하면 봇은 이 채널들에서만 응답합니다(허용되는 경우 DM도 포함). config.yamldiscord.allowed_channels를 무시합니다. 허용/거부 규칙을 표현하려면 DISCORD_IGNORED_CHANNELS와 결합하세요.
DISCORD_NO_THREAD_CHANNELS	No	—	봇이 스레드를 생성하지 않고 채널에서 직접 응답하는 쉼표로 구분된 채널 ID. DISCORD_AUTO_THREAD가 true일 때만 관련이 있습니다.
DISCORD_HISTORY_BACKFILL	No	true	true일 때, 봇이 언급되면 최근 채널 스크롤백(봇의 마지막 응답 이후)을 사용자 메시지 앞에 붙입니다. require_mention을 통해 봇이 놓칠 수 있는 context를 복원합니다. DM과 자유 응답 채널에서는 건너뜁니다. 비활성화하려면 false로 설정합니다.
DISCORD_HISTORY_BACKFILL_LIMIT	No	50	백필 블록을 구성할 때 거슬러 확인할 최대 메시지 수. 실제로 스캔은 보통 그보다 일찍 중지되며 — 대개 채널에서 봇 자신의 마지막 메시지에서 중지됩니다.
DISCORD_REPLY_TO_MODE	No	"first"	응답 참조 동작 제어: "off" — 원본 메시지에 절대 응답하지 않음, "first" — 첫 번째 메시지 조각에만 참조 응답 (기본값), "all" — 모든 조각에 참조 응답.
DISCORD_ALLOW_MENTION_EVERYONE	No	false	false일 때, 봇은 응답에 해당 토큰이 포함되어 있어도 @everyone 또는 @here를 언급할 수 없습니다. 다시 참여하려면 true로 설정하세요. 아래 언급 제어를 참조하세요.
DISCORD_ALLOW_MENTION_ROLES	No	false	false (기본값)일 때, 봇은 @role 멘션을 핑할 수 없습니다. 허용하려면 true로 설정하세요.
DISCORD_ALLOW_MENTION_USERS	No	true	true (기본값)일 때, 봇은 ID로 개별 사용자를 핑할 수 있습니다.
DISCORD_ALLOW_MENTION_REPLIED_USER	No	true	true(기본값)인 경우, 메시지에 답장하면 원래 작성자에게 알림이 갑니다.
DISCORD_PROXY	No	—	Discord 연결(HTTP, WebSocket, REST)을 위한 프록시 URL입니다. HTTPS_PROXY/ALL_PROXY를 override합니다. http://, https://, 및 socks5:// 스킴을 지원합니다.
HERMES_DISCORD_TEXT_BATCH_DELAY_SECONDS	No	0.6	어댑터가 대기 중인 텍스트 청크를 비우기 전에 기다리는 그레이스 윈도우. 스트리밍된 출력을 부드럽게 만드는 데 유용합니다.
HERMES_DISCORD_TEXT_BATCH_SPLIT_DELAY_SECONDS	No	2.0	단일 메시지가 Discord의 길이 제한을 초과할 때 분할된 조각 사이의 지연 시간.

설정 파일 (config.yaml)

~/.hermes/config.yaml의 discord 섹션은 위의 환경 변수를 반영합니다. Config.yaml 설정은 기본값으로 적용되며 — 해당 환경 변수가 이미 설정되어 있으면, 환경 변수가 우선합니다.

# Discord-specific settings
discord:
  require_mention: true           # Require @mention in server channels
  thread_require_mention: false   # If true, require @mention in threads too (multi-bot threads)
  free_response_channels: ""      # Comma-separated channel IDs (or YAML list)
  auto_thread: true               # Auto-create threads on @mention
  reactions: true                 # Add emoji reactions during processing
  ignored_channels:             # Channel IDs where bot never responds
  no_thread_channels:           # Channel IDs where bot responds without threading
  history_backfill: true          # Prepend recent channel scrollback on mention (default: true)
  history_backfill_limit: 50      # Max messages to scan backwards (default: 50)
  channel_prompts: {}             # Per-channel ephemeral system prompts
  allow_mentions:                 # What the bot is allowed to ping (safe defaults)
    everyone: false               # @everyone / @here pings (default: false)
    roles: false                  # @role pings (default: false)
    users: true                   # @user pings (default: true)
    replied_user: true            # reply-reference pings the author (default: true)

# Session isolation (applies to all gateway platforms, not just Discord)
group_sessions_per_user: true     # Isolate sessions per user in shared channels

discord.require_mention

**유형:**불리언 —기본값: true

활성화되면, 봇은 서버 채널에서 직접 @mentioned 되었을 때만 응답합니다. DMs는 이 설정과 관계없이 항상 응답을 받습니다.

discord.thread_require_mention

**유형:**불리언 —기본값: false

기본적으로, 봇이 스레드에 참여한 후(@mention에서 자동 생성되었거나 한 번이라도 답글을 남긴 경우), 다시 @mentioned될 필요 없이 해당 스레드의 모든 이후 메시지에 계속 응답합니다. 1:1 대화에 대한 올바른 기본 설정입니다.

사용자가 한 번에 한 봇만 호출하는 멀티 봇 스레드에서는, 이 기본 설정이 함정이 됩니다 — 스레드의 다른 모든 봇도 모든 메시지에 반응하여 크레딧이 소모되고 채널이 스팸으로 가득 찹니다. thread_require_mention: true을 설정하면 스레드 내 단축 호출을 비활성화하고 채널이 제한되는 것과 동일하게 스레드 제한을 적용할 수 있습니다. 명시적인 @mentions는 이전과 동일하게 작동합니다.

discord:
  require_mention: true
  thread_require_mention: true    # multi-bot setup

discord.free_response_channels

**유형:**문자열 또는 목록 —기본값: ""

봇이 @mention 없이 모든 메시지에 응답하는 채널 ID. 쉼표로 구분된 문자열 또는 YAML 목록을 허용:

# String format
discord:
  free_response_channels: "1234567890,9876543210"

# List format
discord:
  free_response_channels:
    - 1234567890
    - 9876543210

스레드의 상위 채널이 이 목록에 있으면 스레드도 언급이 없는 상태가 됩니다.

자유 응답 채널은 자동 스레딩을 건너뜁니다 — 봇이 각 메시지마다 새로운 스레드를 만드는 대신 인라인으로 답변합니다. 이렇게 하면 채널을 가벼운 채팅 공간으로 사용할 수 있습니다. 스레딩 기능을 원하면 채널을 자유 응답으로 지정하지 마세요(대신 일반 @mention 흐름을 사용하세요).

discord.auto_thread

**유형:**불리언 —기본값: true

활성화되면 일반 텍스트 채널에서 모든 @mention가 자동으로 대화를 위한 새로운 스레드를 생성합니다. 이것은 메인 채널을 깔끔하게 유지하고 각 대화에 자체 격리된 세션 기록을 제공합니다. 스레드가 생성되면 해당 스레드의 이후 메시지에는 @mention가 필요하지 않습니다 — 봇은 이미 참여하고 있음을 알고 있습니다. 다중 봇 설정에서 이 스레드 내 단축 기능을 비활성화하려면 thread_require_mention를 true으로 설정하세요.

기존 스레드나 DM에서 보낸 메시지는 이 설정의 영향을 받지 않습니다. discord.free_response_channels 또는 discord.no_thread_channels에 나열된 채널도 자동 스레딩을 우회하며 대신 인라인 답글을 받습니다.

discord.reactions

**형식:**불리언 —기본값: true

봇이 시각적 피드백으로 메시지에 이모지 반응을 추가할지 여부를 제어합니다:

• 👀 봇이 메시지 처리를 시작할 때 추가됨
• ✅ 응답이 성공적으로 전달되었을 때 추가됨
• ❌ 처리를 진행하는 동안 오류가 발생하면 추가됨

반응이 산만하게 느껴지거나 봇 역할에 반응 추가 권한이 없다면 이 옵션을 비활성화하세요.

discord.ignored_channels

**유형:**문자열 또는 리스트 —기본값: ``

봇이 절대 응답하지 않는 채널 ID, 직접 @mentioned 호출 시에도 마찬가지입니다. 이것이 가장 높은 우선순위를 가집니다 — 만약 채널이 이 목록에 있으면, 봇은 require_mention, free_response_channels 또는 다른 설정과 관계없이 그곳의 모든 메시지를 조용히 무시합니다.

# String format
discord:
  ignored_channels: "1234567890,9876543210"

# List format
discord:
  ignored_channels:
    - 1234567890
    - 9876543210

만약 스레드의 상위 채널이 이 목록에 있다면, 해당 스레드의 메시지도 무시됩니다.

discord.no_thread_channels

**유형:**문자열 또는 리스트 —기본값: ``

봇이 자동으로 스레드를 생성하는 대신 채널에서 직접 응답하는 채널 ID입니다. 이는 auto_thread가 true(기본값)일 때만 적용됩니다. 이러한 채널에서는 봇이 새 스레드를 생성하는 대신 일반 메시지처럼 인라인으로 응답합니다.

discord:
  no_thread_channels:
    - 1234567890  # Bot responds inline here

스레드가 불필요한 잡음을 추가할 수 있는 봇 상호작용 전용 채널에 유용합니다.

discord.channel_prompts

**유형:**매핑 —기본값: {}

각 Discord 채널 또는 스레드의 매 턴에 주입되지만 기록 이력에는 저장되지 않는 채널별 일시적 시스템 프롬프트.

discord:
  channel_prompts:
    "1234567890": |
      This channel is for research tasks. Prefer deep comparisons,
      citations, and concise synthesis.
    "9876543210": |
      This forum is for therapy-style support. Be warm, grounded,
      and non-judgmental.

행동:

• 정확한 스레드/채널 ID 일치가 승리합니다.
• 메시지가 스레드나 포럼 게시물 안에 도착했지만 해당 스레드에 명시적인 항목이 없는 경우, Hermes는 상위 채널/포럼 ID로 대체됩니다.
• 프롬프트는 실행 시간에 일시적으로 적용되므로, 이를 변경하면 과거 세션 기록을 다시 작성하지 않고도 이후 턴에 즉시 영향을 미칩니다.

discord.history_backfill

**형식:**불리언 —기본값: true

활성화되면, 봇은 각 @mention에서 놓친 채널 메시지를 복구합니다. require_mention: true에서는, 봇이 직접 태그된 메시지만 처리하며 — 채널의 다른 모든 것은 세션 기록에서 보이지 않습니다. 히스토리 백필은 트리거될 때 최근 채널 기록을 거꾸로 스캔하여, 봇의 마지막 응답과 현재 언급 사이의 메시지를 수집하고 이를 맥락으로 포함합니다.

표면별 행동:

• 서버 채널 (require_mention: true 포함): 백필(backfill)은 봇이 마지막으로 응답한 이후 채널을 스캔합니다. 봇이 직접 언급되지 않았을 때 다른 참가자들이 게시물을 올린 경우 유용합니다.
• 스레드: 백필(backfill)은 스레드만 스캔합니다 — Discord에서 스레드에 대한 channel.history()는 해당 스레드의 메시지만 반환하며, 상위 채널은 반환하지 않습니다. 스레드는 일반적으로 자체적인 대화로 구성되기 때문에 이 범위가 적절합니다.
• DMs: 건너뜀. 모든 DM 메시지는 봇을 작동시키므로, 세션 대화 기록은 이미 완전하며 — 채워야 할 언급 공백이 없다.
• 자유 응답 채널과 봇이 자체적으로 만든 스레드: 동일한 이유로 생략됨 — 언급 제한이 없으면 간극이 없음.

사용자별 세션(group_sessions_per_user: true, 기본값)도 이점을 누립니다: 사용자의 세션에는 다른 채널 참가자가 게시한 컨텍스트와 사용자가 봇을 태그하기 전에 보낸 자신의 메시지가 누락되어 있습니다. 백필은 두 가지 공백을 모두 채웁니다.

discord:
  history_backfill: true   # default

끄려면:

discord:
  history_backfill: false

참고: 봇이 처리 중일 때(트리거와 응답 사이)에 도착한 메시지는 캡처되지 않습니다. 이는 허용된 단순화이며 — 사용자가 메시지를 다시 보내거나 다시 태그할 수 있습니다.

discord.history_backfill_limit

**유형:**정수 —기본값: 50

채널 컨텍스트를 복구할 때 뒤로 스캔할 최대 메시지 수입니다. 실제로 스캔은 보통 훨씬 이전에 중단되며, 일반적으로 채널에서 봇이 마지막으로 보낸 메시지에서 멈추는데, 이는 턴 간의 자연스러운 경계입니다. 이 제한은 최근 기록에 이전 봇 메시지가 없는 콜드 스타트나 긴 공백 상황에서 안전 장치 역할을 합니다.

discord:
  history_backfill: true
  history_backfill_limit: 50

group_sessions_per_user

**형식:**불리언 —기본값: true

이것은 사용자가 동일한 채널에 있을 때 세션 기록이 분리되는지를 제어하는 전역 게이트웨이 설정(Discord 전용 아님)입니다.

true일 때: Alice와 Bob이 #research에서 이야기할 때, 각자 Hermes와 별도의 대화를 나눕니다. false일 때: 전체 채널이 하나의 대화 기록과 하나의 실행 에이전트 슬롯을 공유합니다.

group_sessions_per_user: true

위의 세션 모델 섹션을 참조하여 각 모드의 전체 의미를 확인하세요.

display.tool_progress

**유형:**문자열 —기본값:"all" —값: off, new, all, verbose

봇이 처리 중에 채팅에서 진행 메시지를 보내는지 여부를 제어합니다(예: "파일 읽는 중...", "터미널 명령 실행 중..."). 이는 모든 플랫폼에 적용되는 전역 게이트웨이 설정입니다.

display:
  tool_progress: "all"    # off | new | all | verbose

• off — 진행 상태 메시지 없음
• new — 턴마다 첫 번째 도구 호출만 표시
• all — 모든 도구 호출 표시(게이트웨이 메시지에서는 40자로 잘림)
• verbose — 전체 도구 호출 자세히 보기 표시 (긴 메시지를 생성할 수 있음)

display.tool_progress_command

**형식:**불리언 —기본값: false

활성화하면 게이트웨이에서 /verbose 슬래시 명령을 사용할 수 있어 config.yaml을 편집하지 않고도 도구 진행 모드(off → new → all → verbose → off)를 전환할 수 있습니다.

display:
  tool_progress_command: true

슬래시 명령어 접근 제어

기본적으로, 허용된 모든 사용자는 모든 슬래시 명령어를 실행할 수 있습니다. 허용 목록을 관리자(모든 슬래시 명령어 접근 가능)와 일반 사용자(사용자가 명시적으로 활성화한 명령어만)로 나누려면, allow_admin_from와 user_allowed_commands를 Discord 플랫폼의 extra 블록에 추가하세요:

gateway:
  platforms:
    discord:
      extra:
        # Existing user allowlist (unchanged)
        allow_from:
          - "123456789012345678"  # admin user ID
          - "999888777666555444"  # regular user ID

        # NEW — admins get all slash commands (built-in + plugin)
        allow_admin_from:
          - "123456789012345678"

        # NEW — non-admin allowed users can only run these slash commands.
        # /help and /whoami are always allowed so users can see their access.
        user_allowed_commands:
          - status
          - model
          - history

        # Optional: separate admin / command lists for server channels
        group_allow_admin_from:
          - "123456789012345678"
        group_user_allowed_commands:
          - status

행동:

• allow_admin_from의 사용자는 범위(DM 또는 서버 채널)에 관계없이 실시간 명령 레지스트리를 통해 내장 및 플러그인 등록을 포함한 모든 등록된 슬래시 명령어를 실행할 수 있습니다.
• allow_admin_from에 속하지 않은 사용자는 user_allowed_commands에 나열된 명령과 항상 허용되는 플로어: /help 및 /whoami만 실행할 수 있습니다.
• 일반 채팅(슬래시가 없는 메시지)은 영향을 받지 않습니다. 관리자 권한이 없는 사용자도 여전히 에이전트와 정상적으로 대화할 수 있으며, 단지 임의의 명령을 실행할 수 없을 뿐입니다.
• 하위 호환성: 특정 범위에 대해 allow_admin_from 가 설정되지 않은 경우, 해당 범위의 슬래시 명령 제한이 비활성화됩니다. 기존 설치는 변경 없이 계속 작동합니다.
• DM 관리자 상태는 서버 채널 관리자 상태를 의미하지 않습니다. 각 범위에는 자체 관리자 목록이 있습니다.

/whoami를 사용하여 활성 범위, 사용자의 등급(관리자 / 사용자 / 제한 없음), 실행할 수 있는 슬래시 명령을 확인하세요.

인터랙티브 모델 선택기

Discord 채널에서 /model를 인수 없이 보내면 드롭다운 기반 모델 선택기를 열 수 있습니다:

1. 제공자 선택 — 사용 가능한 제공자를 보여주는 선택 드롭다운(최대 25개).
2. 모델 선택 — 선택한 제공업체의 모델을 위한 두 번째 드롭다운 (최대 25개).

픽커는 120초 후에 시간 초과됩니다. 허가된 사용자(즉, DISCORD_ALLOWED_USERS에 있는 사용자)만 상호작용할 수 있습니다. 모델 이름을 알고 있다면 /model <name>를 직접 입력하세요.

스킬을 위한 네이티브 슬래시 명령어

Hermes는 설치된 스킬을 네이티브 Discord 애플리케이션 명령어로 자동 등록합니다. 이는 스킬이 Discord의 자동 완성 / 메뉴에 내장 명령어와 함께 표시된다는 것을 의미합니다.

• 각 스킬은 디스코드 슬래시 명령어가 됩니다 (예: /code-review, /ascii-art)
• 스킬은 선택적 args 문자열 매개변수를 허용합니다
• Discord는 봇당 100개의 애플리케이션 명령어 제한이 있습니다 — 사용 가능한 슬롯보다 스킬이 많으면, 추가 스킬은 로그에 경고와 함께 건너뛰어집니다
• 스킬은 /model, /reset, /background와 같은 내장 명령어와 함께 봇 시작 시 등록됩니다.

추가 구성은 필요하지 않습니다 — hermes skills install를 통해 설치된 모든 스킬은 다음 게이트웨이 재시작 시 자동으로 Discord 슬래시 명령으로 등록됩니다.

슬래시 명령 등록 비활성화

만약 동일한 Discord 애플리케이션에 대해 여러 Hermes 게이트웨이를 실행한다면(예: 스테이징 + 프로덕션), 글로벌 슬래시 명령어 등록은 그중 하나만 소유해야 합니다 — 그렇지 않으면 마지막으로 시작된 게이트웨이가 승리하고 등록이 뒤죽박죽이 됩니다. "팔로워" 게이트웨이에서는 슬래시 등록을 끄세요:

gateway:
  platforms:
    discord:
      extra:
        slash_commands: false   # default: true

이를 'primary' 게이트웨이의 true에 두면 기본 동작이 유지됩니다 — 내장 및 설치된 스킬에 대한 전역 /-메뉴 명령어가 작동합니다.

미디어 전송 (send_message + MEDIA: 태그)

디스코드 어댑터는 에이전트가 생성한 send_message 도구와 인라인 MEDIA:/path/to/file 태그를 통해 모든 일반 미디어 유형에 대해 네이티브 파일 업로드를 지원합니다:

유형	어떻게 전달되는지
이미지 (PNG/JPG/WebP)	인라인 미리보기가 있는 네이티브 디스코드 이미지 첨부
애니메이션 GIF	send_animation를 animation.gif로 업로드하면 Discord가 인라인으로 재생합니다 (정적 썸네일로 재생되지 않음)
비디오 (MP4/MOV)	send_video — 기본 동영상 플레이어
오디오 / 음성	send_voice — 가능할 때는 음성 메시지, 그렇지 않으면 파일 첨부
문서 (PDF/ZIP/docx 등)	send_document — 다운로드 버튼이 있는 기본 첨부 파일

디스코드의 파일 업로드당 크기 제한은 서버의 부스트 등급에 따라 달라집니다(무료, 최대 ). Hermes가 HTTP 413을 받으면 어댑터는 조용히 실패하는 대신 로컬 캐시 경로를 가리키는 링크로 대체됩니다.

홈 채널

봇이 사전 알림 메시지(예: 크론 작업 출력, 알림 및 공지)를 보내는 '홈 채널'을 지정할 수 있습니다. 설정하는 방법은 두 가지가 있습니다:

슬래시 명령어 사용하기

봇이 있는 아무 디스코드 채널에 /sethome을 입력하세요. 그 채널이 홈 채널이 됩니다.

수동 설정

이것들을 당신의 ~/.hermes/.env에 추가하세요:

DISCORD_HOME_CHANNEL=123456789012345678
DISCORD_HOME_CHANNEL_NAME="#bot-updates"

ID를 실제 채널 ID로 교체하세요(개발자 모드가 켜진 상태에서 오른쪽 클릭 → 채널 ID 복사).

음성 메시지

Hermes Agent는 Discord 음성 메시지를 지원합니다:

• 수신 음성 메시지는 구성된 STT 제공자를 사용하여 자동으로 전사됩니다: 로컬 faster-whisper (키 없음), Groq Whisper (GROQ_API_KEY), 또는 OpenAI Whisper (VOICE_TOOLS_OPENAI_KEY).
• 음성 합성: 봇이 텍스트 답변과 함께 음성 오디오 응답을 보내도록 /voice tts을 사용하세요.
• 디스코드 음성 채널: 헤르메스는 음성 채널에 들어가 사용자가 말하는 것을 듣고, 채널에서 다시 말할 수도 있습니다.

전체 설치 및 운영 가이드는 다음을 참조하세요:

• 음성 모드
• Hermes와 함께 음성 모드 사용하기

포럼 채널

디스코드 포럼 채널(타입 15)은 직접 메시지를 받을 수 없습니다 — 포럼의 모든 게시물은 스레드여야 합니다. Hermes는 포럼 채널을 자동으로 감지하고 해당 채널에 메시지를 보내야 할 때 새로운 스레드 게시물을 생성하므로 send_message, TTS, 이미지, 음성 메시지, 파일 첨부가 에이전트의 특별한 처리 없이도 모두 작동합니다.

• 스레드 이름은 메시지의 첫 번째 줄에서 파생됩니다(마크다운 제목 접두사 제거, 100자까지 제한). 메시지가 첨부 파일만 있는 경우, 파일명이 대체 스레드 이름으로 사용됩니다.
• 첨부파일은 새 스레드의 시작 메시지에 함께 전송됩니다 — 별도의 업로드 단계 없이, 부분 전송도 없습니다.
• 한 번의 호출, 한 개의 스레드: 각 포럼 전송은 새로운 스레드를 생성합니다. 같은 포럼에 연속적으로 전송하면 별도의 스레드가 생성됩니다.
• 탐지는 세 겹으로 이루어져 있습니다: 첫째는 채널 디렉토리 캐시, 둘째는 프로세스 로컬 프로브 캐시, 그리고 마지막 수단으로 라이브 GET /channels/{id} 프로브(그 결과는 프로세스가 살아 있는 동안 메모이제이션됨)입니다.

디렉토리(/channels refresh를 공개하는 플랫폼에서 또는 게이트웨이 재시작)를 새로 고치면 봇이 시작된 후 생성된 모든 포럼 채널로 캐시가 채워집니다.

문제 해결

봇은 온라인이지만 메시지에 응답하지 않습니다

원인: 메시지 내용 의도가 비활성화되어 있습니다.

수정: 개발자 포털 → 당신의 앱 → 봇 → 권한 있는 게이트웨이 인텐트 → 메시지 내용 인텐트 활성화 → 변경 사항 저장. 게이트웨이를 재시작하세요.

시작 시 '허용되지 않은 의도(Disallowed Intents)' 오류

원인: 사용자의 코드가 개발자 포털에서 활성화되지 않은 인텐트를 요청합니다.

수정: 봇 설정에서 세 가지 권한 게이트웨이 인텐트(출석, 서버 회원, 메시지 내용)를 모두 활성화한 후 재시작하세요.

봇은 특정 채널의 메시지를 볼 수 없습니다

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

수정: Discord에서, 채널 설정 → 권한 → 봇의 역할 추가 후 채널 보기및메시지 기록 읽기 활성화.

403 금지 오류

원인: 봇에게 필요한 권한이 없습니다.

수정: 5단계에서 제공된 URL을 사용하여 올바른 권한으로 봇을 다시 초대하거나, 서버 설정 → 역할에서 봇의 역할 권한을 수동으로 조정하세요.

봇이 오프라인입니다

원인: Hermes 게이트웨이가 실행 중이 아니거나 토큰이 올바르지 않습니다.

수정: hermes gateway이 실행 중인지 확인하세요. DISCORD_BOT_TOKEN을 .env 파일에서 확인하세요. 최근에 토큰을 재설정한 경우, 이를 업데이트하세요.

"사용자 허용 안 됨" / 봇이 무시함

원인: 사용자의 ID가 DISCORD_ALLOWED_USERS에 없습니다.

수정: 게이트웨이를 재시작하기 위해 ~/.hermes/.env에서 DISCORD_ALLOWED_USERS에 사용자 ID를 추가하세요.

같은 채널에 있는 사람들이 예상치 못하게 컨텍스트를 공유하고 있습니다

원인: group_sessions_per_user가 비활성화되었거나, 해당 컨텍스트의 메시지에 대해 플랫폼에서 사용자 ID를 제공할 수 없습니다.

수정: ~/.hermes/config.yaml에 이것을 설정하고 게이트웨이를 재시작하세요:

group_sessions_per_user: true

공유 방 대화를 의도적으로 원한다면 꺼두세요 — 단지 공유된 대화 기록과 공유된 중단 행동을 예상하세요.

보안

{#security}

봇과 상호작용할 수 있는 사람을 제한하기 위해 항상 DISCORD_ALLOWED_USERS (또는 DISCORD_ALLOWED_ROLES)를 설정하세요. 둘 중 어느 것도 없으면 안전 조치로서 게이트웨이는 기본적으로 모든 사용자를 거부합니다. 신뢰하는 사람만 권한을 부여하세요 — 권한이 있는 사용자는 도구 사용 및 시스템 접근을 포함한 에이전트의 모든 기능에 완전히 접근할 수 있습니다.

역할 기반 접근 제어

개별 사용자 목록 대신 역할로 액세스를 관리하는 서버(모더레이터 팀, 지원 직원, 내부 도구)의 경우 DISCORD_ALLOWED_ROLES를 사용하세요 — 쉼표로 구분된 역할 ID 목록입니다. 해당 역할 중 하나를 가진 모든 구성원이 권한을 가집니다.

# ~/.hermes/.env — works alongside or instead of DISCORD_ALLOWED_USERS
DISCORD_ALLOWED_ROLES=987654321098765432,876543210987654321

의미론:

• 사용자 허용 목록과 OR.사용자는 ID가 DISCORD_ALLOWED_USERS에 있거나또는 DISCORD_ALLOWED_ROLES에서 어떤 역할을 가지고 있으면 권한이 부여됩니다.
• 서버 멤버 인텐트 자동 활성화. DISCORD_ALLOWED_ROLES가 설정되면, 봇은 연결 시 멤버 인텐트를 활성화합니다 — 이는 Discord가 멤버 기록과 함께 역할 정보를 보내기 위해 필요합니다.
• **역할 ID, 이름이 아님.**Discord에서 가져오기:사용자 설정 → 고급 → 개발자 모드 켜기, 그런 다음 아무 역할이나 오른쪽 클릭 → 역할 ID 복사.
• DM 대체 경로. DM에서 역할 확인은 공통 길드를 검사합니다. 공유 서버 중 하나에서 허용된 역할을 가진 사용자는 DM에서도 권한이 부여됩니다.

관리팀이 바뀔 때 선호되는 패턴은 새로운 관리자가 역할이 부여되는 순간 액세스 권한을 얻는 것입니다. .env 편집이나 게이트웨이 재시작은 필요하지 않습니다.

언급 제어

기본적으로, Hermes는 봇이 @everyone, @here 및 역할 멘션을 핑하는 것을 차단합니다. 이는 봇의 답변에 해당 토큰이 포함되어 있더라도 마찬가지입니다. 이는 부적절하게 작성된 프롬프트나 사용자의 반복된 내용이 서버 전체에 스팸을 보내는 것을 방지합니다. 개별 @user 핑과 답변 참조 핑(작은 '…에게 답장 중' 칩)은 여전히 활성화되어 있어 일반적인 대화에는 영향을 주지 않습니다.

이 기본값들은 환경 변수나 config.yaml을 통해 조정할 수 있습니다:

# ~/.hermes/config.yaml
discord:
  allow_mentions:
    everyone: false      # allow the bot to ping @everyone / @here
    roles: false         # allow the bot to ping @role mentions
    users: true          # allow the bot to ping individual @users
    replied_user: true   # ping the author when replying to their message
````bash
# ~/.hermes/.env — env vars win over config.yaml
DISCORD_ALLOW_MENTION_EVERYONE=false
DISCORD_ALLOW_MENTION_ROLES=false
DISCORD_ALLOW_MENTION_USERS=true
DISCORD_ALLOW_MENTION_REPLIED_USER=true

팁

everyone와 roles을 false에 두세요, 정확히 왜 필요한지 알지 못하는 한. LLM이 정상적으로 보이는 응답 안에 @everyone 문자열을 생성하는 것은 매우 쉽습니다; 이 보호 장치 없이는, 그것이 서버의 모든 회원에게 알림을 보낼 수 있습니다.

Hermes 에이전트 배포 보안을 강화하는 방법에 대한 자세한 내용은 보안 가이드를 참조하십시오.