Mattermost 설정

Hermes 에이전트는 Mattermost와 봇으로 통합되어, 개인 메시지나 팀 채널을 통해 AI 어시스턴트와 대화할 수 있습니다. Mattermost는 자체 호스팅 가능한 오픈 소스 Slack 대안으로, 자체 인프라에서 실행하여 데이터에 대한 완전한 제어권을 유지할 수 있습니다. 봇은 Mattermost의 REST API(v4)와 실시간 이벤트를 위한 WebSocket을 통해 연결되며, Hermes 에이전트 파이프라인(툴 사용, 메모리, 추론 포함)을 통해 메시지를 처리하고 실시간으로 응답합니다. 텍스트, 파일 첨부, 이미지, 슬래시 명령어를 지원합니다.

외부 Mattermost 라이브러리는 필요하지 않으며, 어댑터는 이미 Hermes 의존성인 aiohttp 을 사용합니다.

설치 전에, 대부분의 사람들이 가장 궁금해하는 부분은 다음과 같습니다: Hermes가 여러분의 Mattermost 인스턴스에 들어간 후 어떻게 작동하는지입니다.

헤르메스의 행동 방식

문맥	행동
다이렉트 메시지(디엠)	Hermes는 모든 메시지에 응답합니다. @mention가 필요 없습니다. 각 DM은 자체 세션을 가집니다.
공개/비공개 채널	Hermes는 당신이 @mention 할 때 반응합니다. 언급이 없으면 Hermes는 메시지를 무시합니다.
스레드	만약 MATTERMOST_REPLY_MODE=thread이면, Hermes는 당신의 메시지 아래 스레드에서 답변합니다. 스레드의 맥락은 상위 채널과 분리되어 유지됩니다.
여러 사용자와 공유된 채널	기본적으로 Hermes는 채널 내에서 사용자별로 세션 기록을 분리합니다. 같은 채널에서 두 사람이 대화하더라도 명시적으로 이를 비활성화하지 않는 한 대화 기록을 공유하지 않습니다.

팁

만약 Hermes가 스레드 대화(원본 메시지 아래에 중첩됨)로 응답하기를 원하면 MATTERMOST_REPLY_MODE=thread을 설정하세요. 기본값은 off이며, 채널에 플랫 메시지를 보냅니다.

매터모스트의 세션 모델

기본적으로:

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

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

group_sessions_per_user: true

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

group_sessions_per_user: false

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

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

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

1단계: 봇 계정 활성화

Bot 계정은 생성하기 전에 Mattermost 서버에서 활성화되어 있어야 합니다.

1. 시스템 관리자로 Mattermost에 로그인하세요.
2. 시스템 콘솔→통합→봇 계정으로 이동하세요.
3. 봇 계정 생성 활성화를 true로 설정하세요.
4. 저장을 클릭하세요.

정보

시스템 관리자 권한이 없는 경우, Mattermost 관리자에게 봇 계정을 활성화하고 하나 만들어 달라고 요청하세요.

2단계: 봇 계정 만들기

1. Mattermost에서 **☰**메뉴(좌상단)를 클릭 →Integrations→Bot Accounts를 클릭하세요.
2. 봇 계정 추가를 클릭하세요.
3. 세부 정보를 입력하세요:
   • 사용자 이름: 예: hermes
   • 표시 이름: 예: Hermes Agent
   • 설명: 선택 사항
   • 역할: Member이면 충분합니다
4. 봇 계정 만들기를 클릭하세요.
5. Mattermost는 봇 토큰을 표시합니다. 즉시 복사하세요.

Token shown only once

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

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

팁

봇 계정 대신 개인 액세스 토큰을 사용할 수도 있습니다. 프로필→보안→개인 액세스 토큰→토큰 생성으로 이동하세요. 이는 별도의 봇 사용자 대신 사용자가 직접 Hermes로 게시하고자 할 때 유용합니다.

3단계: 봇을 채널에 추가하기

봇이 응답하길 원하는 모든 채널의 구성원이어야 합니다:

1. 봇을 원하시는 채널을 열세요.
2. 채널 이름을 클릭 → 멤버 추가.
3. 봇 사용자 이름(예: hermes)을 검색하고 추가하세요.

DM의 경우, 봇과 직접 메시지를 열기만 하면 즉시 응답할 수 있습니다.

단계 4: 당신의 Mattermost 사용자 ID 찾기

Hermes 에이전트는 당신의 Mattermost 사용자 ID를 사용하여 누가 봇과 상호작용할 수 있는지 제어합니다. 확인하는 방법:

1. 왼쪽 상단의 아바타를 클릭 → 프로필.
2. 사용자 ID는 프로필 대화 상자에 표시됩니다 — 클릭하면 복사됩니다.

사용자의 사용자 ID는 3uo8dkh1p7g1mfk49ear5fzs5c와 같은 26자리 알파벳 숫자 문자열입니다.

경고

사용자의 사용자 ID는 사용자 이름이 아닙니다. 사용자 이름은 @ 이후에 나타나는 것입니다(예: @alice). 사용자 ID는 Mattermost가 내부적으로 사용하는 길고 알파벳과 숫자가 혼합된 식별자입니다.

대안: API를 통해서도 사용자 ID를 얻을 수 있습니다:

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

팁

채널 ID를 얻으려면: 채널 이름을 클릭 → 정보 보기. 채널 ID는 정보 패널에 표시됩니다. 홈 채널을 수동으로 설정하려면 이 ID가 필요합니다.

5단계: Hermes 에이전트 구성

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

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

hermes gateway setup

프롬프트가 표시되면 Mattermost를 선택한 후, 요청 시 서버 URL, 봇 토큰, 사용자 ID를 붙여넣으세요.

옵션 B: 수동 설정

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

# Required
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=***
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

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

# Optional: reply mode (thread or off, default: off)
# MATTERMOST_REPLY_MODE=thread

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

# Optional: channels where bot responds without @mention (comma-separated channel IDs)
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2
``~/.hermes/config.yaml`의 선택적 동작 설정:

```yaml
group_sessions_per_user: true

• group_sessions_per_user: true는 각 참가자의 컨텍스트를 공유 채널과 스레드 안에서 격리 상태로 유지합니다

게이트웨이를 시작하세요

설정을 마쳤으면 Mattermost 게이트웨이를 시작하십시오:

hermes gateway

봇은 몇 초 내에 귀하의 Mattermost 서버에 연결되어야 합니다. 테스트를 위해 메시지를 보내세요 — DM이든 봇이 추가된 채널이든 상관없습니다.

팁

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

홈 채널

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

슬래시 명령어 사용하기

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

수동 설정

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

MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn

ID를 실제 채널 ID로 교체하세요 (채널 이름 클릭 → 정보 보기 → ID 복사).

답장 모드

MATTERMOST_REPLY_MODE 설정은 Hermes가 응답을 게시하는 방식을 제어합니다:

모드	행동
off (기본)	에르메스는 일반 사용자처럼 채널에 평범한 메시지를 게시합니다.
thread	Hermes는 원래 메시지 아래 스레드에서 답장을 합니다. 많은 주고받기가 있을 때 채널을 깔끔하게 유지합니다.

~/.hermes/.env에 설정하세요:

MATTERMOST_REPLY_MODE=thread

행동 언급

기본적으로, 봇은 @mentioned일 때만 채널에서 응답합니다. 이를 변경할 수 있습니다:

변수	기본값	설명
MATTERMOST_REQUIRE_MENTION	true	모든 채널의 메시지에 응답하려면 false로 설정하세요(개인 메시지는 항상 작동합니다).
MATTERMOST_FREE_RESPONSE_CHANNELS	(없음)	봇이 require_mention이 true일 때에도 @mention 없이 응답하는 콤마로 구분된 채널 ID.

Mattermost에서 채널 ID를 찾으려면: 채널을 열고, 채널 이름 헤더를 클릭한 다음, URL이나 채널 세부정보에서 ID를 확인하세요.

봇이 @mentioned일 때, 멘션은 처리하기 전에 메시지에서 자동으로 제거됩니다.

문제 해결

봇이 메시지에 응답하지 않습니다

원인: 봇이 채널의 회원이 아니거나 MATTERMOST_ALLOWED_USERS에 귀하의 사용자 ID가 포함되어 있지 않습니다.

수정: 봇을 채널에 추가하십시오 (채널 이름 → 구성원 추가 → 봇 검색). 사용자 ID가 MATTERMOST_ALLOWED_USERS에 있는지 확인하십시오. 게이트웨이를 다시 시작하십시오.

403 금지 오류

원인: 봇 토큰이 유효하지 않거나, 봇이 채널에 게시할 권한이 없습니다.

수정: .env 파일에 있는 MATTERMOST_TOKEN가 정확한지 확인하세요. 봇 계정이 비활성화되지 않았는지 확인하세요. 봇이 채널에 추가되었는지 확인하세요. 개인 액세스 토큰을 사용하는 경우, 계정에 필요한 권한이 있는지 확인하세요.

웹소켓 연결 끊김 / 재연결 루프

원인: 네트워크 불안정, Mattermost 서버 재시작, 또는 WebSocket 연결과 관련된 방화벽/프록시 문제.

수정: 어댑터가 지수 백오프(2초 → 60초)로 자동 재연결합니다. 서버의 WebSocket 구성을 확인하세요 — 리버스 프록시(nginx, Apache)는 WebSocket 업그레이드 헤더를 구성해야 합니다. 방화벽이 Mattermost 서버의 WebSocket 연결을 차단하지 않는지 확인하세요.

nginx의 경우, 설정에 다음을 포함해야 합니다:

location /api/v4/websocket {
    proxy_pass http://mattermost-backend;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 600s;
}

시작 시 '인증 실패'

원인: 토큰 또는 서버 URL이 올바르지 않습니다.

수정: MATTERMOST_URL가 당신의 Mattermost 서버를 가리키는지 확인하세요 (https:// 포함, 끝에 슬래시 금지). MATTERMOST_TOKEN가 유효한지 확인하세요 — curl로 시도해 보세요:

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

이것이 당신의 봇 사용자 정보를 반환하면, 토큰이 유효한 것입니다. 오류가 반환되면 토큰을 다시 생성하세요.

봇이 오프라인입니다

원인: Hermes 게이트웨이가 실행되지 않거나 연결에 실패했습니다.

수정: hermes gateway가 실행 중인지 확인하세요. 오류 메시지는 터미널 출력에서 확인할 수 있습니다. 일반적인 문제: 잘못된 URL, 만료된 토큰, 접근할 수 없는 Mattermost 서버.

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

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

수정: 게이트웨이를 재시작하기 전에 ~/.hermes/.env의 MATTERMOST_ALLOWED_USERS에 사용자 ID를 추가하세요. 기억하세요: 사용자 ID는 26자리의 영숫자 문자열이며, 귀하의 @username가 아닙니다.

채널별 프롬프트

일시적인 시스템 프롬프트를 특정 Mattermost 채널에 할당합니다. 이 프롬프트는 실행 시 매 번 주입되며 — 대화 기록에 저장되지 않으므로 — 변경 사항이 즉시 적용됩니다.

mattermost:
  channel_prompts:
    "channel_id_abc123": |
      You are a research assistant. Focus on academic sources,
      citations, and concise synthesis.
    "channel_id_def456": |
      Code review mode. Be precise about edge cases and
      performance implications.

키는 Mattermost 채널 ID입니다(채널 URL에서 찾거나 API를 통해 찾을 수 있습니다). 일치하는 채널의 모든 메시지에 일시적인 시스템 명령으로 프롬프트가 주입됩니다.

보안

경고

항상 MATTERMOST_ALLOWED_USERS를 설정하여 누가 봇과 상호작용할 수 있는지 제한하세요. 이를 설정하지 않으면, 안전 조치로 게이트웨이는 기본적으로 모든 사용자를 거부합니다. 신뢰하는 사람들의 사용자 ID만 추가하세요 — 인증된 사용자는 도구 사용 및 시스템 접근을 포함한 에이전트의 모든 기능에 완전히 접근할 수 있습니다.

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

노트

• 자체 호스팅 친화적: 모든 자체 호스팅된 Mattermost 인스턴스에서 작동합니다. Mattermost Cloud 계정이나 구독이 필요하지 않습니다.
• 추가 종속성 없음: 이 어댑터는 HTTP 및 WebSocket에 aiohttp를 사용하며, 이는 이미 Hermes Agent에 포함되어 있습니다.
• 팀 에디션 호환: Mattermost 팀 에디션(무료)과 엔터프라이즈 에디션 모두에서 작동합니다.