..

Hermes Agent를 Discord에 연결하기

TOC

  1. Overview
  2. 로컬 Gateway와 Discord 연결 구조
  3. 애플리케이션 설정
  4. 게이트웨이 봇 설정 및 재시작
  5. 정리

Overview

Hermes Agent를 Discord 봇으로 연결하면 Discord DM이나 서버 채널에서 Hermes의 도구 사용, 메모리, 세션 기능을 그대로 사용할 수 있다.

이 글은 가장 작은 구성으로 연결하는 절차만 다룬다. 각 설정은 무엇을 하는지보다 왜 필요한지에 초점을 둔다.

로컬 Gateway와 Discord 연결 구조

Hermes는 로컬에서 Gateway를 실행하는 방식으로 Discord와 연결한다. Gateway가 실행되면 Discord 서버와 연결을 시도하고, 연결이 성립된 뒤에는 그 상태를 유지한다.

로컬 컴퓨터
    │
    │ Hermes Gateway 실행
    │
    ▼
Hermes Gateway ◀──── 연결 유지 ────▶ Discord 서버
    ▲                                  │
    │                                  │ 메시지 전달
    └──────── 모바일 Discord 클라이언트

모바일 Discord 클라이언트에서 메시지를 보내면 Discord 서버가 연결된 로컬 Gateway로 메시지를 전달한다. Gateway는 메시지를 Hermes에 전달하고, 처리 결과를 다시 Discord 서버로 보내 모바일 클라이언트에 표시한다.

핵심은 모바일 클라이언트가 로컬 컴퓨터에 직접 접속하는 것이 아니라, Discord 서버를 중계 지점으로 사용한다는 점이다. 로컬 Gateway와 Discord 서버의 연결이 유지되어야 Discord에서 보낸 요청을 로컬 Hermes가 받을 수 있다.

애플리케이션 설정

Discord Developer Portal에 로그인한 뒤 New Application을 선택한다.

애플리케이션은 봇의 컨테이너다. 먼저 애플리케이션을 만들고, 그 안에서 봇 사용자, 토큰, 권한, Gateway 연결을 설정한다.

애플리케이션 생성

애플리케이션 이름은 Discord에서 봇을 구분하기 위한 표시값이다. 용도를 바로 알 수 있는 이름을 사용하면 여러 봇을 관리하기 쉽다.

New Application을 선택하고 봇을 식별할 이름을 입력한다.

OAuth 설정

OAuth는 Discord 계정의 로그인 정보를 직접 전달하지 않고, 정해진 권한 범위로 봇을 서버에 설치하기 위한 인증·인가 방식이다. 여기서 봇이 요청할 기능과 서버 권한을 선택하면 Discord가 해당 설정을 반영한 초대 URL을 만들어준다.

Scope 설정

Scope는 OAuth 인증 과정에서 봇이 어떤 종류의 설치 권한을 요청할지 결정한다.

  • Scopes: bot, applications.commands

bot은 서버에 봇 사용자를 설치하기 위한 scope다. applications.commands는 Hermes의 slash command를 Discord 명령어로 등록하기 위해 필요하다.

Permission 설정

Permission은 봇이 서버에서 수행할 수 있는 Discord 동작의 범위를 결정한다.

  • View Channels: 봇이 메시지를 받을 채널을 볼 수 있어야 한다.
  • Send Messages: 답변을 보낼 수 있어야 한다.
  • Read Message History: 대화 맥락을 복원할 수 있어야 한다.
  • Embed Links: 링크와 결과를 Discord 형식으로 표시할 수 있다.
  • Attach Files: 이미지, 오디오, 파일 결과를 보낼 수 있다.
  • Send Messages in Threads: 자동 생성된 스레드에서 답변할 수 있다.
  • Add Reactions: 처리 중인 메시지에 확인 반응을 남길 수 있다.

필요한 권한만 선택하는 이유는 봇이 침해되었을 때 피해 범위를 줄이기 위해서다. 서버 전체 관리자 권한을 부여할 필요는 없다.

  • Permissions: View Channels, Send Messages, Embed Links, Attach Files, Read Message History
  • 권장: Send Messages in Threads, Add Reactions
초대

앞에서 Scope와 Permission을 순서대로 설정했다면 Discord가 봇 초대 URL을 자동으로 만들어준다. 이 URL을 브라우저에 복사해 붙여넣으면 설정된 봇을 내 서버에 초대할 수 있다.

봇을 초대할 서버는 사전에 구성되어 있어야 하며, 초대하는 계정에는 해당 서버를 관리할 권한이 필요하다.

Bot 설정

봇은 Discord 서버와 실제로 통신하는 주체다. 애플리케이션만 만들고 봇을 설정하지 않으면 Hermes Gateway가 로그인할 대상이 없다.

왼쪽 메뉴에서 Bot으로 이동한다. Discord 애플리케이션에는 봇 사용자가 자동으로 생성된다.

Bot Token 발급

Token에서 Reset Token을 눌러 토큰을 발급하고 즉시 안전한 곳에 복사한다.

Privileged Gateway Intents 설정

Gateway Intent는 Discord가 봇에게 전달할 이벤트의 범위를 결정한다. Hermes가 메시지와 발신자 정보를 처리하려면 다음 두 Intent가 필요하다.

  • Server Members Intent
  • Message Content Intent

Message Content Intent는 봇이 실제 메시지 내용을 읽기 위해 필요하다. 이 설정이 꺼져 있으면 봇은 메시지 이벤트를 받아도 사용자가 입력한 텍스트를 볼 수 없다.

Server Members Intent는 사용자와 멤버 정보를 확인하기 위해 필요하다. Hermes는 허용된 Discord 사용자 ID를 기준으로 접근을 제한하므로, 누가 메시지를 보냈는지 식별할 수 있어야 한다.

Presence Intent는 온라인 상태를 확인하는 기능이며 기본적인 대화에는 필요하지 않다.

위 두 Intent를 켜고 Save Changes를 누른다.

게이트웨이 봇 설정 및 재시작

앞에서 Discord 서버에 애플리케이션과 봇에 대한 설정을 진행했다면, 이제 로컬에서 실행할 Hermes Gateway에 해당 봇의 인증 정보와 접근 정책을 설정한다. 설정이 끝나면 Gateway를 실행해 Discord와의 연결을 시작한다.

사용자 ID 확인하기

Hermes는 허용된 Discord 사용자만 봇을 사용할 수 있도록 사용자 ID를 확인한다.

Discord에서 Settings → Advanced → Developer Mode를 켠 뒤 자신의 사용자 이름을 우클릭하고 Copy User ID를 선택한다.

Hermes Gateway 설정

대화방식

대화형 설정을 실행하고 Discord 봇 토큰과 사용자 ID를 입력한다. (숫자형태)

hermes gateway setup
수동방식

수동 설정이 필요하면 ~/.hermes/.env에 다음 값을 추가한다.

DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=your-discord-user-id

토큰은 외부에 노출되지 않도록 .env에 저장한다. 여러 사용자는 쉼표로 구분한다.

DISCORD_ALLOWED_USERS=12938129...,192381923

Gateway 실행 및 재시작

설정을 저장한 뒤 Gateway를 실행한다. 이미 Gateway가 실행 중이었다면 변경된 봇 설정을 읽도록 재시작해야 한다.

hermes gateway

Gateway를 재시작하려면 실행 중인 프로세스를 종료한 뒤 다시 실행한다.

정리