[인공지능/Hermes] 슬랙 연동하기

헤르메스 에이전트와 슬랙을 연동하는 방법을 알아보기 전에, 굳이 슬랙을 선택한 이유는 간단하다.

메신저 공식 비교 테이블를(혹은 아래 사진 참고) 보면 모든 기능을 지원하는 메신저 중 쓸만한게(최소 내가 써본것들이) 슬랙(및 디스코드)였기 때문이다.

Hermes Agent Slack 연동 가이드

한 줄 요약

Hermes Agent는 Slack App의 Socket Mode를 사용해서 Slack과 연결할 수 있다.

Slack 사용자
   ↓
Slack App / Bot
   ↓
Socket Mode WebSocket
   ↓
Hermes Messaging Gateway
   ↓
Hermes Agent

공식 문서 기준으로 Hermes Slack 연동은 slack-bolt / slack_sdk 기반 Socket Mode를 사용하고, 필요한 토큰은 Bot Token인 xoxb-와 App-Level Token인 xapp- 두 가지다.

Slack 연동 방식

Socket Mode란 무엇인가

Slack Bot을 외부 서비스와 연결하려면 일반적으로 Slack이 이벤트를 보낼 수 있는 공개 (Hook) URL이 필요하다.

하지만 Socket Mode를 사용하면 공개 URL이 필요 없다.

Hermes Gateway가 Slack 쪽으로 WebSocket 연결을 열고, 그 연결을 통해 이벤트를 받는 구조다.

일반 이벤트 방식:
Slack → 공개 HTTP URL → 내 서버

Socket Mode:
내 Hermes Gateway → Slack WebSocket 연결
Slack → 열린 WebSocket으로 이벤트 전달

이 방식의 장점은 다음과 같다.

내 PC에서 바로 테스트할 수 있다.
ngrok, ssh tunneling 같은 터널링 도구가 필요 없다.
방화벽 뒤 서버에서도 사용할 수 있다. ( 기업 환경에서는 꽤나 편리함 )
외부에 공개 엔드포인트를 열지 않아도 된다. ( 기업 환경에서는 꽤나 편리함 )

필요한 토큰

Slack 연동에는 토큰이 2개 필요하다.

토큰	형식	용도
Bot Token	`xoxb-...`	봇이 메시지를 읽고 보내는 데 사용한다
App-Level Token	`xapp-...`	Socket Mode WebSocket 연결에 사용한다

Hermes에서는 이 토큰을 보통 다음 환경변수로 설정한다.

SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_APP_TOKEN=xapp-your-app-token-here

Slack App 생성

Slack App 만들기

먼저 Slack API 페이지에서 새 앱을 만든다.

https://api.slack.com/apps

진행 순서는 다음과 같다.

Create an App을 클릭한다.
From scratch를 선택한다.
앱 이름을 입력한다.
연결할 Slack workspace를 선택한다. ( 최소 1개의 워크스페이스가 미리 생성되어 있어야 한다 )
Create App을 클릭한다.

앱 이름은 예를 들어 다음처럼 정하면 된다.

Hermes Agent

생성 후에는 Slack App의 Basic Information 페이지로 이동하게 된다.

Bot Token Scopes 설정

Slack App 설정 화면에서 다음 메뉴로 이동한다.

Features → OAuth & Permissions

그리고 Scopes(범위) → Bot Token Scopes(봇 토큰 범위) 항목에 필요한 권한을 추가하면 된다.

주요 Scope 추가

Hermes Slack Bot에 필요한 주요 Bot Token Scope는 다음과 같다.

Scope	용도
`chat:write`	봇이 메시지를 보낼 수 있게 한다
`app_mentions:read`	채널에서 봇이 멘션된 것을 감지한다
`channels:history`	봇이 들어간 공개 채널의 메시지를 읽는다
`channels:read`	공개 채널 목록과 정보를 읽는다
`groups:history`	봇이 초대된 비공개 채널 메시지를 읽는다
`im:history`	DM 메시지 기록을 읽는다
`im:read`	DM 기본 정보를 읽는다
`im:write`	DM을 열고 관리한다
`users:read`	사용자 정보를 조회한다
`files:read`	첨부파일, 음성 파일, 오디오 파일을 읽는다
`files:write`	이미지, 오디오, 문서 파일을 업로드한다

비공개 채널 정보까지 포함하고 싶으면 다음 Scope도 추가한다.

Scope	용도
`groups:read`	비공개 채널 목록과 정보를 읽는다

자주 빠뜨리는 Scope

채널에서 봇이 응답하지 않는 가장 흔한 원인은 다음 Scope 누락이다.

channels:history
groups:history

channels:history가 없으면 공개 채널 메시지를 제대로 받지 못할 수 있다.

groups:history가 없으면 비공개 채널 메시지를 제대로 받지 못할 수 있다.

DM만 동작하고 채널에서 동작하지 않는다면 이 Scope부터 확인하면 된다.

Socket Mode 활성화

Socket Mode 켜기

Slack App 설정에서 다음 메뉴로 이동한다.

Settings → Socket Mode

그리고 Enable Socket Mode를 켠다.

Socket Mode를 켜면 App-Level Token 생성을 요구한다.

App-Level Token 생성

App-Level Token 생성 시 다음처럼 설정하면 된다.

Token name: 원하는 값으로
Scope: connections:write

생성된 토큰은 xapp-로 시작한다. ( 나중에 써야 하니 복사해두자. )

이 토큰이 Hermes의 SLACK_APP_TOKEN이 된다.

SLACK_APP_TOKEN=xapp-your-app-token-here

App-Level Token은 나중에 다음 메뉴에서도 확인하거나 재생성할 수 있다.

Settings → Basic Information → App-Level Tokens

Event Subscriptions 설정

이벤트 구독 켜기

* 중요한 단계이다, 봇이 읽을 수 있는 메시지의 종류가 여기에서 결정 된다.

Slack App 설정에서 다음 메뉴로 이동한다.

Features → Event Subscriptions

그리고 Enable Events를 켠다.

그 다음 Subscribe to bot events 항목에 이벤트를 추가한다.

필요한 Bot Event

Hermes Slack Bot에 필요한 이벤트는 다음과 같다.

Event	필수 여부	용도
`message.im`	필수	봇이 DM을 받는다
`message.channels`	필수	봇이 들어간 공개 채널 메시지를 받는다
`message.groups`	권장	봇이 초대된 비공개 채널 메시지를 받는다
`app_mention`	필수	채널에서 봇이 멘션된 것을 처리한다

이벤트를 추가한 뒤에는 반드시 페이지 하단의 Save Changes를 눌러야 한다.

가장 흔한 설정 실수

Slack Bot이 DM에서는 잘 동작하는데 채널에서 응답하지 않는다면 대부분 다음 둘 중 하나다.

message.channels 누락
message.groups 누락

공개 채널에서 응답하지 않으면 message.channels를 확인하면 된다.

비공개 채널에서 응답하지 않으면 message.groups를 확인하면 된다.

Messages Tab 활성화

App Home 설정

DM으로 Hermes Bot에게 메시지를 보내려면 Messages Tab을 켜야 한다.

Slack App 설정에서 다음 메뉴로 이동한다.

Features → App Home

그리고 Show Tabs 섹션에서 다음을 설정한다.

Messages Tab을 ON으로 켠다.
Allow users to send Slash commands and messages from the messages tab을 체크한다.

이 단계를 하지 않으면 DM에서 다음과 같은 메시지를 볼 수 있다.

Sending messages to this app has been turned off

이 문제는 Hermes 설정 문제가 아니라 Slack App 설정 문제라고 보면 된다.

Workspace에 App 설치

Install App 실행

Slack App 설정에서 다음 메뉴로 이동한다.

Settings → Install App

그리고 다음 순서로 진행한다.

Install to {워크스페이스명}를 클릭한다.
권한 목록을 확인한다.
Allow를 클릭한다.
설치 후 Bot User OAuth Token을 복사한다.

Bot User OAuth Token은 xoxb-로 시작한다.

이 값이 Hermes의 SLACK_BOT_TOKEN이다.

SLACK_BOT_TOKEN=xoxb-your-bot-token-here

Scope 변경 후 재설치 필요

중요한 점이 있다.

Slack App의 Scope나 Event Subscription을 나중에 변경했다면 App을 workspace에 다시 설치해야 한다.

그렇지 않으면 새 권한이 실제 봇에 적용되지 않을 수 있다.

즉 아래 중 하나의 행위라도 했으면 반드시 재설치해야 한다.

Bot Token Scope 추가
Event Subscription 추가
Socket Mode 관련 설정 변경

Allowlist용 Slack Member ID 찾기

Member ID가 필요한 이유

Hermes Gateway는 허용된 사용자만 메시지를 처리하도록 설정하는 것이 기본이다.

Slack에서는 사용자 이름이나 표시 이름이 아니라 Member ID를 사용한다.

Member ID는 보통 다음처럼 생겼다.

U01ABC2DEF3

Hermes 설정에서는 이 값을 SLACK_ALLOWED_USERS에 넣는다.

SLACK_ALLOWED_USERS=U01ABC2DEF3

Member ID 찾는 방법

Slack에서 Member ID를 찾는 방법은 다음과 같다.

Slack에서 사용자 이름이나 아바타를 클릭한다.
View full profile을 클릭한다.
⋮ 버튼을 클릭한다.
Copy member ID를 선택한다.

최소한 자신의 Member ID는 반드시 등록하는 게 좋다.

Hermes 환경변수 설정

.env 파일 수정

Hermes 설정 파일은 기본적으로 다음 위치를 사용한다.

~/.hermes/.env

여기에 Slack 설정을 추가하면 된다.

# Required
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_APP_TOKEN=xapp-your-app-token-here
SLACK_ALLOWED_USERS=U01ABC2DEF3

# Optional
SLACK_HOME_CHANNEL=C01234567890
SLACK_HOME_CHANNEL_NAME=general

각 값의 의미는 다음과 같다.

환경변수	필수 여부	의미
`SLACK_BOT_TOKEN`	필수	Slack Bot User OAuth Token
`SLACK_APP_TOKEN`	필수	Socket Mode용 App-Level Token
`SLACK_ALLOWED_USERS`	필수 권장	Hermes를 사용할 수 있는 Slack Member ID 목록
`SLACK_HOME_CHANNEL`	선택	cron, scheduled message를 보낼 기본 채널 ID
`SLACK_HOME_CHANNEL_NAME`	선택	사람이 읽기 쉬운 기본 채널 이름

여러 사용자를 허용하려면 쉼표로 구분하면 된다.

SLACK_ALLOWED_USERS=U01ABC2DEF3,U04XYZ9AAAA

Interactive Setup 사용

직접 .env를 수정하지 않고 대화형 설정을 사용할 수도 있다.

hermes gateway setup

실행 후 Slack을 선택하고 토큰과 사용자 ID를 입력하면 된다.

Gateway 실행

Foreground 실행

처음 테스트할 때는 foreground로 실행하는 게 좋다.

hermes gateway

이 방식은 터미널에 로그가 바로 나오기 때문에 문제를 확인하기 쉽다.

User Service로 설치

개인 개발 머신이나 일반 사용자 환경에서는 user service로 설치하면 된다.

hermes gateway install
hermes gateway start
hermes gateway status

중지하려면 다음 명령을 사용한다.

hermes gateway stop

Linux System Service로 설치

VPS나 서버에서 부팅 시 자동 실행하고 싶다면 system service로 설치할 수 있다.

sudo hermes gateway install --system
sudo hermes gateway start --system
sudo hermes gateway status --system

일반 개발 머신에서는 user service가 더 적합하고, 서버에서는 system service가 적합하다고 보면 된다.

Bot을 채널에 초대

채널 초대

Gateway를 실행한 뒤에는 Hermes Bot을 사용할 Slack 채널에 초대해야 한다.

채널에서 다음 명령을 입력하면 된다.

/invite @봇이름
/invite @Hermes

봇은 자동으로 모든 채널에 들어가지 않는다.

사용할 채널마다 직접 초대해야 한다.

비공개 채널 주의

비공개 채널에서 사용하려면 다음 조건이 필요하다.

groups:history Scope가 있어야 한다.
message.groups Event Subscription이 있어야 한다.
App을 재설치해야 한다.
해당 비공개 채널에 봇을 초대해야 한다.

이 중 하나라도 빠지면 비공개 채널에서 응답하지 않을 수 있다.

Hermes Bot 응답 방식

DM에서의 동작

DM에서는 봇이 모든 메시지에 응답한다.

즉 별도로 @Hermes Agent를 멘션하지 않아도 된다.

사용자: 오늘 할 일 정리해줘.
Hermes: ...

채널에서의 동작

채널에서는 기본적으로 @mention이 필요하다.

@Hermes 이 에러 로그 원인 분석해줘.

채널에서 Hermes는 보통 해당 메시지의 thread에 답변한다.

이 방식은 다른 메시지랑 섞일 수 있는 채널에서 봇 응답이 메인 채널을 어지럽히지 않도록 하기 위한 구조라고 보면 된다.

Thread에서의 동작

이미 Hermes가 활성화된 thread 안에서는 이후 답글에 매번 멘션하지 않아도 대화를 이어갈 수 있다.

흐름은 다음과 같다.

채널:
@Hermes 이 로그 분석해줘.

Thread:
Hermes: 원인은 kubelet 설정 문제로 보인다.

사용자:
해결 명령어만 정리해줘.

Hermes:
앞서 분석한 kubelet 문제 기준으로 명령어를 정리하면...

즉 채널에서 대화를 시작할 때는 멘션하고, thread 안에서는 자연스럽게 이어가면 된다.

Slack 동작 설정

Thread 응답 설정

Slack Bot의 thread 응답 방식은 ~/.hermes/config.yaml에서 조정할 수 있다.

platforms:
  slack:
    reply_to_mode: "first"
    extra:
      reply_in_thread: true
      reply_broadcast: false

각 설정의 의미는 다음과 같다.

설정	기본값	의미
`platforms.slack.reply_to_mode`	`"first"`	여러개의 메시지가 있을 때 thread 처리 방식
`platforms.slack.extra.reply_in_thread`	`true`	채널 메시지에 thread로 답할지 여부
`platforms.slack.extra.reply_broadcast`	`false`	thread 답변을 메인 채널에도 보낼지 여부

reply_to_mode는 다음 값 중 하나를 사용할 수 있다.

값	의미
`off`	원본 메시지에 thread로 묶지 않는다
`first`	첫 번째 응답 조각만 원본 메시지에 thread로 묶는다
`all`	모든 응답 조각을 원본 메시지에 thread로 묶는다

사용자별 세션 분리

공유 채널에서는 사용자별로 대화 세션을 분리하는 게 기본값이다.

group_sessions_per_user: true

이 값이 true이면 같은 채널에서 여러 사람이 Hermes에게 말을 걸어도 각자의 대화 맥락이 분리된다.

예를 들면 다음과 같다.

#general 안에서

A 사용자 → Hermes와 Kubernetes 문제 상담
B 사용자 → Hermes와 블로그 글 작성 상담

두 대화의 컨텍스트는 서로 섞이지 않음

반대로 협업 모드처럼 채널 전체가 하나의 대화 세션을 공유하게 하려면 다음처럼 설정할 수 있다.

group_sessions_per_user: false

다만 이 경우에는 주의가 필요하다.

여러 사용자의 대화 맥락이 섞일 수 있다.
토큰 사용량이 늘어날 수 있다.
한 사용자의 /reset이 전체 채널 세션을 초기화할 수 있다.

멘션 트리거 설정

Slack 채널에서는 기본적으로 멘션이 필요하다.

명시적으로 설정하려면 다음처럼 할 수 있다.

slack:
  require_mention: true
  mention_patterns:
    - "hey hermes"
    - "hermes,"
  reply_prefix: ""

mention_patterns를 사용하면 @mention 외에도 특정 문구로 봇을 호출할 수 있다.

예를 들면 다음 문구도 트리거로 만들 수 있다.

hey hermes
hermes,

특정 채널에서 자유 응답 허용

Slack은 기본적으로 채널에서 @mention이 필요하지만, 특정 채널은 멘션이 필요 없는 자유 응답 채로 설정할 수 있다.

환경변수 방식은 다음과 같다.

SLACK_FREE_RESPONSE_CHANNELS=C01234567890,C09876543210

또는 config.yaml에서 설정할 수 있다.

slack:
  free_response_channels:
    - C01234567890
    - C09876543210

이 기능은 전용 봇 채널처럼 Hermes가 모든 메시지를 읽고 응답해도 되는 채널에서만 사용하는 게 좋다.

Home Channel 설정

Home Channel 용도

SLACK_HOME_CHANNEL은 Hermes가 예약 메시지, cron 결과, proactive notification을 보낼 기본 Slack 채널이다.

예를 들면 다음과 같은 작업 결과를 받을 수 있다.

매일 아침 서버 상태 점검 결과
예약된 리포트 생성 결과
백그라운드 작업 완료 알림

설정 예시는 다음과 같다.

SLACK_HOME_CHANNEL=C01234567890
SLACK_HOME_CHANNEL_NAME=general

Channel ID 찾는 방법

Slack Channel ID는 다음 방법으로 찾을 수 있다.

Slack에서 채널 이름을 우클릭한다.
View channel details를 클릭한다.
하단으로 스크롤한다.
Channel ID를 확인한다.

주의할 점은 SLACK_HOME_CHANNEL에는 채널 이름이 아니라 채널 ID를 넣어야 한다는 것이다.

또한 Hermes Bot이 해당 채널에 초대되어 있어야 한다.

/invite @Hermes Agent

채널별 Prompt 설정

Per-Channel Prompt란 무엇인가

슬랙 채널별로 임시 시스템 프롬프트를 지정할 수 있다.

이 프롬프트는 매 응답마다 주입되지만 대화 기록에는 저장되지 않는다.

즉 설정을 바꾸면 즉시 반영되고, 대화 기록 자체에는 남지 않는다.

문서 예시는 다음과 같다.

slack:
  channel_prompts:
    "C01RESEARCH": |
      너는 연구원을 보조하는 역할이야. 학술적인 부분에 집중해.
    "C02ENGINEERING": |
      코드 리뷰 모드. 엣지 케이스와 퍼포먼스 영향도 주의.

멀티 워크스페이스 설정

여러 Slack Workspace 연결

Hermes는 하나의 Gateway 인스턴스로 여러 Slack workspace에 연결할 수 있다.

여러 Bot Token을 쉼표로 구분해서 넣으면 된다.

SLACK_BOT_TOKEN=xoxb-workspace1-token,xoxb-workspace2-token,xoxb-workspace3-token
SLACK_APP_TOKEN=xapp-your-app-token

또는 config.yaml에 넣을 수 있다.

platforms:
  slack:
    token: "xoxb-workspace1-token,xoxb-workspace2-token"

OAuth Token File 사용

토큰 파일을 사용할 수도 있다.

파일 위치는 다음과 같다.

~/.hermes/slack_tokens.json

형식은 다음과 같다.

{
  "T01ABC2DEF3": {
    "token": "xoxb-workspace-token-here",
    "team_name": "My Workspace"
  }
}

이 파일의 토큰은 SLACK_BOT_TOKEN으로 지정한 토큰과 병합된다.

중복 토큰은 자동으로 deduplicate 된다.

멀티 워크스페이스 동작 방식

동작 방식은 다음과 같다.

첫 번째 Bot Token이 primary token이 된다.
각 token은 시작 시 auth.test로 검증된다.
Hermes는 team_id별로 WebClient와 bot_user_id를 매핑한다.
메시지가 들어오면 해당 workspace에 맞는 client로 응답한다.

일반적인 개인 사용에서는 멀티 워크스페이스가 필요하지 않다.

회사 workspace와 개인 workspace를 하나의 Hermes Gateway에서 함께 관리하고 싶을 때 고려하면 된다.

저작자표시 비영리 변경금지 (새창열림)

'인공지능 > Hermes' 카테고리의 다른 글

[인공지능/Hermes] 헤르메스 메시징 게이트웨이 이해하기 (0)	2026.04.25
[인공지능/Hermes] 헤르메스 메모리 시스템 이해하기 (0)	2026.04.25
[인공지능/Hermes] 헤르메스 리눅스에 설치하기 (0)	2026.04.25
[인공지능/Hermes] 헤르메스란 ( feat. 오픈클로와의 차이 ) (0)	2026.04.15

Hermes Agent Slack 연동 가이드

한 줄 요약

Slack 연동 방식

Socket Mode란 무엇인가

필요한 토큰

Slack App 생성

Slack App 만들기

Bot Token Scopes 설정

주요 Scope 추가

자주 빠뜨리는 Scope

Socket Mode 활성화

Socket Mode 켜기

App-Level Token 생성

Event Subscriptions 설정

이벤트 구독 켜기

필요한 Bot Event

가장 흔한 설정 실수

Messages Tab 활성화

App Home 설정

Workspace에 App 설치

Install App 실행

Scope 변경 후 재설치 필요

Allowlist용 Slack Member ID 찾기

Member ID가 필요한 이유

Member ID 찾는 방법

Hermes 환경변수 설정

.env 파일 수정

Interactive Setup 사용

Gateway 실행

Foreground 실행

User Service로 설치

Linux System Service로 설치

Bot을 채널에 초대

채널 초대

비공개 채널 주의

Hermes Bot 응답 방식

DM에서의 동작

채널에서의 동작

Thread에서의 동작

Slack 동작 설정

Thread 응답 설정

사용자별 세션 분리

멘션 트리거 설정

특정 채널에서 자유 응답 허용

Home Channel 설정

Home Channel 용도

Channel ID 찾는 방법

채널별 Prompt 설정

Per-Channel Prompt란 무엇인가

멀티 워크스페이스 설정

여러 Slack Workspace 연결

OAuth Token File 사용

멀티 워크스페이스 동작 방식

'인공지능 > Hermes' 카테고리의 다른 글

티스토리툴바