Mattermost Hermes Agent — 자체 호스팅 팀 채팅

팀에서 Mattermost를 운영하고 있다면 그 매력을 이미 잘 알고 계실 겁니다. 겉모습과 사용감은 Slack과 비슷하지만, 서버와 데이터는 우리 인프라 안에 그대로 남아 있습니다. Hermes Agent는 봇으로서 여기에 연결됩니다. Mattermost의 REST API(v4)와 실시간 이벤트용 WebSocket을 통해 연결되므로, 네트워크 밖으로 아무것도 나가지 않고도 DM과 팀 채널에서 어시스턴트가 답변할 수 있습니다.

추가로 설치할 라이브러리는 없습니다. 어댑터는 Hermes에 이미 포함된 aiohttp를 사용합니다. Mattermost Team Edition(무료)과 Enterprise Edition 모두에서 작동합니다.

Mattermost에서 Hermes의 동작 방식

대화하는 위치	동작
DM	Hermes가 모든 메시지에 답변합니다. `@mention`이 필요 없습니다. 각 DM은 자체 세션을 가집니다.
채널	`@mention`할 때 Hermes가 답변합니다. 멘션이 없으면 메시지를 무시합니다.
스레드	`MATTERMOST_REPLY_MODE=thread`로 설정하면 답변이 원래 메시지 아래에 중첩되고 상위 채널과 분리됩니다.
공유 채널	기본적으로 세션 기록이 사용자별로 분리되므로, 한 채널의 두 사람이 대화 기록을 공유하지 않습니다.

마지막 동작은 config.yaml의 group_sessions_per_user로 제어합니다:

group_sessions_per_user: true   # each person keeps their own context

채널 전체가 하나의 대화를 공유하도록 의도한 경우에만 false로 설정하세요. 공유 세션은 모든 사람이 컨텍스트 증가와 토큰 비용을 함께 부담한다는 뜻이며, 한 사람의 도구를 많이 쓰는 긴 작업이 다른 사람의 실행을 부풀리거나 방해할 수 있습니다.

1단계: 봇 계정 활성화 (관리자 측)

봇 계정을 만들기 전에 서버에서 봇 계정 기능을 켜야 합니다:

System Admin으로 Mattermost에 로그인합니다.
System Console → Integrations → Bot Accounts로 이동합니다.
Enable Bot Account Creation을 true로 설정한 뒤 Save를 클릭합니다.

관리자 권한이 없나요? Mattermost 관리자에게 봇 계정을 활성화하고 봇을 만들어 달라고 요청하세요.

2단계: 봇 계정 만들기

☰ 메뉴(왼쪽 상단) → Integrations → Bot Accounts → Add Bot Account를 클릭합니다.
세부 정보를 입력합니다. Username은 hermes처럼, Display Name은 Hermes Agent처럼, 그리고 Role은 Member면 충분합니다.
Create Bot Account를 클릭한 뒤 토큰을 즉시 복사하세요. 토큰은 한 번만 표시됩니다. 잃어버리면 봇 계정 설정에서 다시 생성해야 합니다.

⚠️ 토큰을 공유하거나 Git에 커밋하지 마세요. 토큰을 가진 사람은 누구나 봇을 완전히 제어할 수 있습니다.

에이전트가 별도 봇이 아니라 본인 사용자로 게시하길 원하나요? Profile → Security → Personal Access Tokens → Create Token에서 personal access token을 만드세요.

3단계: 봇을 채널에 초대하기

봇은 자신이 속한 채널에서만 응답합니다:

채널을 열고 → 채널 이름을 클릭 → Add Members를 선택합니다.
봇 사용자 이름(예: hermes)을 검색해서 추가합니다.

DM의 경우 봇과의 다이렉트 메시지를 열기만 하면 됩니다. 초대는 필요 없습니다.

4단계: Mattermost 사용자 ID 찾기

Hermes는 누가 봇과 대화할 수 있는지 결정할 때 사용자 이름이 아니라 User ID를 사용합니다:

아바타(왼쪽 상단 모서리)를 클릭 → Profile로 이동합니다.
대화 상자에 User ID가 표시됩니다. 3uo8dkh1p7g1mfk49ear5fzs5c처럼 26자 영숫자 문자열입니다. 클릭하면 복사됩니다.

API에서 읽을 수도 있습니다:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-mattermost-server/api/v4/users/me | jq .id

User ID는 메시지에서 보이는 @username이 아닙니다. 사용자 이름을 붙여 넣는 것이 봇이 조용히 있는 가장 흔한 이유입니다.

5단계: Hermes 구성하기

안내식 설정을 실행하고 메시지가 나오면 Mattermost를 선택하세요. 서버 URL, 봇 토큰, User ID를 묻습니다:

hermes gateway setup

또는 ~/.hermes/.env에서 직접 설정할 수 있습니다:

# Required
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=your-bot-token
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

# Multiple allowed users (comma-separated)
# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e

# Optional: reply in a thread instead of flat messages (default: off)
# MATTERMOST_REPLY_MODE=thread

# Optional: respond without an @mention (default: true = mention required)
# MATTERMOST_REQUIRE_MENTION=false

# Optional: channels where no @mention is needed (comma-separated channel IDs)
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2

그런 다음 게이트웨이를 시작합니다:

hermes gateway

봇은 몇 초 안에 Mattermost 서버에 연결됩니다. DM을 보내거나, 봇이 추가된 채널에서 @mention해서 테스트해 보세요.

6단계: 선택적 동작 전환

설정	기능
`MATTERMOST_REPLY_MODE`	`off`(기본값)는 일반 메시지로 게시하고, `thread`는 답변을 원래 메시지 아래에 중첩해 바쁜 채널을 깔끔하게 유지합니다.
`MATTERMOST_REQUIRE_MENTION`	기본값은 `true`입니다. `false`로 설정하면 모든 채널 메시지에 응답합니다(DM은 항상 작동).
`MATTERMOST_FREE_RESPONSE_CHANNELS`	멘션이 필요한 경우에도 멘션 요구를 건너뛰는 채널 ID입니다.
`MATTERMOST_HOME_CHANNEL`	능동적 메시지가 가는 곳입니다. cron 출력, 알림, 알림 메시지 등입니다. 또는 채널에서 `/sethome`을 입력하세요.
`mattermost.allowed_channels`	봇을 채널 ID 목록으로 제한합니다. 다른 곳에서 온 메시지는 버려집니다. DM은 예외입니다.
`mattermost.channel_prompts`	채널별로 임시 시스템 프롬프트를 주입합니다. 매 턴마다 적용되며 대화 기록에 저장되지 않습니다.

봇이 @mentioned되면 처리 전에 메시지에서 멘션이 제거되므로, @hermes summarize this thread는 깔끔한 지시로 도착합니다.

문제 해결

증상	가능한 원인	해결
봇이 채널에서 무시함	봇이 채널에 없거나, User ID가 `MATTERMOST_ALLOWED_USERS`에 없음	봇을 채널에 추가하고, 26자 User ID를 확인한 뒤 게이트웨이 재시작
봇이 게시할 수 없음	잘못된 토큰이거나, 봇이 해당 채널에서 권한이 없음	`MATTERMOST_TOKEN`을 확인하고, 계정이 활성 상태이며 채널 멤버인지 확인
계속 연결이 끊김	WebSocket 끊김, 서버 재시작, 또는 프록시/방화벽 문제	어댑터는 지수 백오프(2초 → 60초)로 재연결합니다. nginx라면 WebSocket 업그레이드 헤더가 설정되어 있는지 확인하세요
아무 일도 일어나지 않음	게이트웨이가 실행 중이 아니거나 URL/토큰이 잘못됨	`hermes gateway` 출력을 확인하고, `MATTERMOST_URL`에 `https://`가 포함되어 있고 끝에 슬래시가 없는지 확인

토큰을 직접 테스트하려면:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-server/api/v4/users/me

봇 보안

항상 MATTERMOST_ALLOWED_USERS를 설정하세요. 설정하지 않으면 게이트웨이가 안전 조치로 기본적으로 모든 사용자를 거부합니다. 그리고 허용된 사용자는 도구 사용과 시스템 접근을 포함해 에이전트 기능에 완전히 접근할 수 있으므로 목록을 최소한으로 유지하세요. 배포 강화에 대한 더 넓은 내용은 공식 보안 지침을 참고하세요.

다음 단계

게이트웨이가 실행되면 Mattermost는 다른 Hermes 채널과 똑같이 동작합니다. 슬래시 명령, 파일 업로드, 음성 메모, 홈 채널로 전달되는 cron 출력까지, 모두 우리가 제어하는 인프라에서 이루어집니다. 호스팅 옵션을 선호한다면 Slack 통합에서 Socket Mode 방식을 다루고, 여러 머신에서 게이트웨이를 운영한다면 Hermes Relay가 이들을 연결합니다.