Hermes Agent를 디스코드에 연결하기

앞 글에서는 Hermes Agent를 Docker로 실행하는 데까지 갔다. ~/hermes-agents/dev을 상태 디렉터리로 만들고, 그 디렉터리를 컨테이너의 /opt/data로 mount했다. Docker Compose 파일은 ~/hermes-agents/docker에 두었다. 이제 Hermes에 입구를 붙일 차례다.

터미널에서만 부를 수 있는 에이전트는 아직 반쪽짜리다. 내가 자리에 앉아 있을 때는 CLI도 괜찮지만, 개인 비서처럼 쓰려면 어디서든 불러낼 수 있어야 한다. Discord는 그 입구로 꽤 괜찮다. 서버 채널, DM, thread가 있고, 파일도 주고받을 수 있고, 무엇보다 공개 포트를 열지 않아도 된다. Hermes gateway가 Discord bot으로 접속해서 메시지를 받아오면 된다.

이 글에서는 앞에서 만든 Docker 기반 Hermes Agent에 Discord bot을 연결한다.

1. Discord bot 만들기

먼저 Discord Developer Portal에 들어간다. 여기서 신규 애플리케이션을 누르면 이름을 짓고 약관에 동의해준다. 개발을 도와줄 에이전트라 이름은 '커밋코기'로 지었다. 바로 옆에 있는 친구는 내가 할 일을 다 짬맞은 에이전트, 짬타이거다.

만들기를 누르고 들어가면 왼쪽 사이드바에 봇메뉴가 있는데, 여기서 필요한 봇 설정을 할 수 있다. 아이콘과 사용자명을 변경하고, Privileged Gateway Intents에서 아래의 두 개를 켜줘야 한다.

Server Members Intent : Hermes는 DISCORD_ALLOWED_USERS나 DISCORD_ALLOWED_ROLES로 누가 bot을 쓸 수 있는지 제한하는데, 사용자나 role을 해석하는 과정에서 이 intent가 필요할 수 있다.
Message Content Intent : 이게 꺼져 있으면 bot은 메시지 이벤트를 받아도 실제 텍스트를 볼 수 없다. 말 그대로 사용자가 뭐라고 썼는지 모르는 상태가 된다.

그리고는 bot token을 복사한다. 처음이라면 Reset Token을 누르면 된다. 이 token은 Discord bot으로 로그인하기 위한 비밀번호다. 절대 Git에 올리면 안 되고, 블로그나 메신저에 그대로 붙여넣어도 안 된다. 잃어버리면 다시 Reset Token을 눌러 새로 발급하면 된다. 대신 이전 token은 더 이상 쓸 수 없게 된다.

2. Bot을 서버에 초대하기

Bot을 만들었다고 서버에 자동으로 들어오는 것은 아니다. OAuth2 invite URL로 서버에 초대해야 한다. OAuth2 URL 재생기에서 bot에 체크하면, 봇의 권한을 설정할 수 있는 영역이 생기게 된다. 내가 주로 체크하는 권한들은 아래와 같다.

권한 체크하고나서 더 아래로 내려가보면 생성된 URL이 있다. 여기서 URL을 복사하고 브라우저에 넣으면 디스코드가 열리면서 디스코드 서버에 봇을 추가할 수 있게 된다.

3. Hermes `.env`에 Discord 설정 넣기

앞 글에서 Hermes 상태 디렉터리를 ~/hermes-agents/dev로 잡았다. Docker 컨테이너 안에서는 이 디렉터리가 /opt/data가 된다. 호스트에서는 아래 파일을 수정한다.

cd ~/hermes-agents/dev

.env에 다음 값을 넣는다. DISCORD_ALLOWED_USERS는 Discord 설정에서 Developer Mode를 켜고 내 프로필이나 메시지의 사용자 이름을 우클릭하면 보이는 Copy User ID 버튼을 통해 알아낼 수 있다. 복사되는 값은 284102345871466496 같은 긴 숫자다.

DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=284102345871466496

여러 명을 허용하고 싶다면 comma로 이어쓴다.

DISCORD_ALLOWED_USERS=284102345871466496,198765432109876543

팀이나 서버 단위로 관리하고 싶다면 DISCORD_ALLOWED_ROLES를 쓸 수도 있다. 이 경우 role ID를 넣는다.

DISCORD_ALLOWED_ROLES=123456789012345678

DISCORD_ALLOWED_USERS와 DISCORD_ALLOWED_ROLES가 둘 다 없으면 gateway는 사용자를 허용하지 않는다. bot은 떠 있는데 아무도 쓸 수 없는 상태가 된다.

cron 결과나 reminder처럼 Hermes가 먼저 메시지를 보내야 하는 경우에는 home channel도 지정할 수 있다. 처음 연결 테스트만 할 거라면 home channel은 나중에 설정해도 된다. 먼저 bot이 응답하는지부터 확인하자.

DISCORD_HOME_CHANNEL=123456789012345678
DISCORD_HOME_CHANNEL_NAME=Home

4. gateway 다시 시작하기

.env를 바꿨다면 gateway를 다시 시작해야 한다. 정확히 말하면 Docker를 새로 띄워야 한다기보다, 이미 떠 있는 Hermes gateway 프로세스가 새 .env를 다시 읽게 해야 한다. 가장 쉽고 편한 방법은 컨테이너를 바로 재시작하는 것이다. 앞 글에서 컨테이너 이름을 hermes-dev로 만들었다면 어디서든 이 명령을 실행할 수 있다.

docker restart hermes-dev

Docker Compose 기준으로 관리하고 싶다면 앞 글에서 만든 ~/hermes-agents/docker 디렉터리로 이동해서 재시작한다.

cd ~/hermes-agents/docker
docker compose restart hermes-dev

아직 컨테이너를 한 번도 띄우지 않았거나, compose 파일 기준으로 새로 만들고 싶다면 그때만 up -d를 쓴다.

cd ~/hermes-agents/docker
docker compose up -d

정리하면 이렇게 보면 된다.

.env만 바꿨다 → docker restart hermes-dev
compose 기준으로 관리하고 싶다 → docker compose restart hermes-dev
컨테이너가 없다 → docker compose up -d

로그는 항상 확인한다.

docker logs -f hermes-dev

Compose 디렉터리에 들어와 있다면 이렇게 봐도 된다.

docker compose logs -f hermes-dev

정상이라면 Discord adapter가 시작되고, bot이 Discord에서 online으로 보이기 시작한다. token 오류가 나면 .env의 DISCORD_BOT_TOKEN을 다시 확인한다. allowed user 관련 오류가 나면 DISCORD_ALLOWED_USERS나 DISCORD_ALLOWED_ROLES를 확인한다.

Discord에서 이미 bot이 정상 동작하고 있다면 /restart로 gateway를 재시작할 수도 있다. 하지만 Discord token이나 allowed user를 처음 넣는 단계에서는 bot이 아직 내 말을 들을 수 없는 상태일 가능성이 높다. 처음 연결할 때는 Docker 쪽에서 재시작하는 편이 확실하다.

5. Discord에서 호출 테스트하기

DM에서는 bot에게 그냥 메시지를 보내면 된다. DM은 mention이 필요 없다.

서버 채널에서는 기본적으로 bot을 mention해야 한다.

TXT

@Hermes Agent 안녕. 짧게 pong이라고 답해줘.

Hermes Discord integration의 기본 동작은 다음과 같다.

DM에서는 모든 메시지에 응답한다.
서버 채널에서는 기본적으로 @mention이 있을 때만 응답한다.
thread에서는 같은 thread 안에 답한다.
기본적으로 shared channel에서도 사용자별 session이 분리된다.

서버 채널에서 매번 mention하기 싫다면 free-response channel을 지정할 수 있다.

DISCORD_FREE_RESPONSE_CHANNELS=123456789012345678

이렇게 하면 해당 channel에서는 mention 없이도 Hermes가 응답한다. 다만 개인용 서버가 아니라 여러 사람이 있는 서버에서는 신중해야 한다. 모든 대화에 bot이 끼어들면 금방 피곤해진다.

반대로 모든 서버 채널에서 mention 없이 응답하게 하려면 다음 설정도 가능하다.

DISCORD_REQUIRE_MENTION=false

하지만 이건 추천하지 않는다. 개인 테스트 서버가 아니라면 특정 free-response channel만 지정하는 편이 낫다.

6. thread와 세션을 어떻게 볼 것인가

Discord에서 Hermes를 쓰다 보면 thread가 꽤 중요하다. Hermes는 server channel에서 mention을 받으면 대화를 thread로 분리해 이어갈 수 있다. 이렇게 하면 채널 전체가 한 대화로 오염되지 않고, 작업 단위별로 맥락을 나눌 수 있다.

기본적으로 Hermes는 shared channel에서 사용자별 session을 분리한다.

YAML

group_sessions_per_user: true

이 기본값은 개인 비서용으로 안전하다. 같은 channel에 여러 사람이 있어도 각자의 대화 이력이 섞이지 않는다.

반대로 한 channel이나 thread를 팀 전체의 공유 대화로 쓰고 싶다면 group_sessions_per_user: false를 고려할 수 있다.

YAML

group_sessions_per_user: false

다만 이 경우 모두가 같은 context를 공유한다. 한 사람이 긴 tool-heavy 작업을 시키면 다른 사람의 대화에도 영향을 줄 수 있다. 처음에는 기본값 그대로 두는 편이 낫다.

마무리

Docker로 Hermes Agent를 띄운 뒤 Discord를 붙이면 사용감이 달라진다. 터미널에서 실행하는 도구가 아니라, 필요할 때 불러낼 수 있는 에이전트가 된다.

핵심은 네 가지다.

Discord Developer Portal에서 bot을 만든다.
Message Content Intent와 Server Members Intent를 켠다.
~/hermes-agents/dev/.env에 DISCORD_BOT_TOKEN과 DISCORD_ALLOWED_USERS를 넣는다.
.env를 바꾼 뒤 docker restart hermes-dev로 gateway를 다시 시작한다.

여기까지 되면 Hermes는 Discord에서 부를 수 있는 상태가 된다. 다음부터는 home channel, free-response channel, thread 정책, 여러 에이전트 분리 같은 운영 문제를 하나씩 다듬으면 된다.