강의 1.14 영상 촬영 이후 슬랙의 앱 만들기 화면과 헤르메스 명령이 여러 곳 바뀌었습니다.
이 문서는 지금 화면 그대로 따라 하실 수 있도록 연동 전체 과정을 최신 기준으로 다시 정리한 것입니다.
재촬영본도 빠르게 업로드 하도록 하겠으며, 현재는 이 문서를 기준으로 진행해 주세요.
(전체 단계는 영상 때보다 오히려 줄었습니다.)
💡 사전 요구사항: 헤르메스 설치(1.12)가 끝나 있고, 슬랙 워크스페이스와 채널(
사무실등)이 만들어져 있어야 합니다. 워크스페이스 개설과 채널 만들기는 영상 앞부분(처음부터 6분경까지)과 동일하니 그대로 따라 하시면 됩니다.
영상과 달라진 핵심 3가지
먼저 그대로 따라 하면 막히는 세 곳입니다.
- 매니페스트 명령에
--agent-view옵션이 필요합니다. 영상의 명령에는 이 옵션이 없습니다. - 앱 만들기 첫 화면이 바뀌었습니다. AI agent 템플릿이 미리 선택되어 있는데, 우리가 쓸 것이 아닙니다.
- 앱 토큰은 이미 만들어져 있습니다. 영상처럼 직접 만들지 않고 복사만 하면 됩니다.
아래 단계 순서대로 진행하시면 세 곳 모두 자연스럽게 지나갑니다.
1단계. 매니페스트 파일 생성
터미널에서 아래 명령을 실행합니다. 영상과 달리 --agent-view 옵션이 붙는다는 점에 주의하세요. 새로 앱을 만들 때는 이 옵션이 필수입니다.
hermes slack manifest --agent-view --write
실행하면 매니페스트 파일이 저장된 경로가 출력되고, 이어서 Next steps:라는 영문 안내 네 줄이 따라 나옵니다. 이 영문 안내는 기존 앱을 갱신할 때의 순서라서 지금 처음 만드는 우리와는 순서가 다릅니다. 읽지 말고 이 문서의 순서대로 진행해 주세요.
출력된 경로의 파일 내용을 클립보드에 복사합니다. 환경별로 편한 방법을 쓰시면 됩니다.
# Mac (경로 자리는 위에서 출력된 본인 경로로 교체)
cat 매니페스트_파일_경로 | pbcopy
# Windows PowerShell
Get-Content 매니페스트_파일_경로 | Set-Clipboard
# VPS 등 원격 터미널
cat 매니페스트_파일_경로 (출력 내용을 마우스로 드래그해 복사)
2단계. 슬랙 앱 만들기 (첫 화면이 바뀌었습니다)
브라우저에서 api.slack.com/apps에 접속해 Create New App을 누릅니다.
영상에서는 선택지가 두 개뿐이었지만, 지금은 화면 위쪽에 AI agent와 Starter app 템플릿이 보이고 AI agent가 미리 선택되어 있습니다.
⚠️ AI agent 템플릿은 우리가 쓸 것이 아닙니다. 화면 아래 Or start your own way 영역의 From a manifest를 선택하고 Continue를 눌러주세요.
3단계. 워크스페이스 선택과 매니페스트 붙여넣기 (한 화면으로 합쳐졌습니다)
영상에서는 워크스페이스 선택이 별도 단계(Step 2 of 3)였지만, 지금은 Step 1 of 2 한 화면에서 워크스페이스 선택과 매니페스트 입력을 함께 합니다.
- 위쪽에서 헤르메스를 연결할 워크스페이스를 선택합니다.
- 아래 매니페스트 입력란에는
Demo App이라는 예시 내용이 미리 들어 있습니다. 입력란 전체를 선택해서 지운 자리에 1단계에서 복사한 내용을 붙여넣습니다. 예시 위에 그냥 붙여넣으면 JSON이 깨져서 다음 단계로 넘어가지 못합니다.
⚠️ 여기서 고른 워크스페이스는 나중에 바꿀 수 없습니다. 잘못 고르면 앱을 지우고 처음부터 다시 만들어야 하니, 넘어가기 전에 한 번 확인해 주세요.
4단계. Review 확인 후 Create and Install
다음 화면(Step 2 of 2)은 Review your app입니다. How it works 설명과 함께 Configured for you 영역에 권한과 기능 개수(17개, 9개 형태의 숫자)가 표시되면 매니페스트가 제대로 읽힌 것입니다.
Create and Install 버튼을 누릅니다. 영상에서는 앱 생성 후 설치를 따로 했지만, 지금은 이 버튼 하나로 앱 생성과 워크스페이스 설치가 한 번에 끝납니다.
설치가 끝나면 Hermes is ready! 확인창이 뜹니다.
⚠️ 확인창 아래에 Install Slack CLI라는 4단계 안내(Node.js 프로젝트 생성 등)가 보이는데, 이것은 슬랙 개발자용 안내로 우리 과정과 무관합니다. 따라 하지 마시고
Go to App Settings를 눌러 앱 설정 화면으로 이동해 주세요.
5단계. 토큰 두 개 챙기기 (앱 토큰은 이미 만들어져 있습니다)
챙길 토큰은 영상과 같이 두 개입니다.
| 토큰 | 시작 글자 | 어디서 받나 |
|---|---|---|
| 앱 레벨 토큰 | xapp- | Basic Information의 App-Level Tokens |
| 봇 토큰 | xoxb- | Install App (또는 OAuth 화면) |
앱 레벨 토큰. 영상에서는 App-Level Tokens 목록이 비어 있어서 이름을 입력하고 스코프를 추가해 직접 만들었지만, 지금은 앱을 만들면 Default Hermes App Token이 이미 들어 있습니다. 새로 만들 필요 없이 이름을 클릭해 값을 Copy 하면 됩니다. Scope에 connections:write가 적혀 있는지만 확인해 주세요.
봇 토큰. 4단계에서 설치까지 끝났기 때문에, 왼쪽 메뉴 Install App에 들어가면 xoxb-로 시작하는 봇 토큰이 이미 발급되어 있습니다. 복사만 하면 됩니다.
> ⚠️ Basic Information 맨 위의 App Credentials 영역(Client Secret, Signing Secret 등)은 이름이 비슷하지만 우리가 쓸 토큰이 아닙니다. 위 두 개만 챙기시면 됩니다.
💡 영상에서는 Socket Mode 페이지에 들어가 Enabled를 확인했지만, 매니페스트가 이미 켜 두기 때문에 지금은 방문하지 않으셔도 됩니다.
DM 준비 확인 (여기서 한 번 보고 넘어가세요). 왼쪽 메뉴 Features의 App Home에서 페이지를 아래로 내리면 Show Tabs 영역이 나옵니다. Messages Tab 토글이 켜져 있고, 그 아래 Allow users to send Slash commands and messages from the messages tab 체크박스도 체크되어 있으면 됩니다. 매니페스트가 켜 주긴 하지만, 꺼져 있으면 나중에 DM이 아예 안 되니 눈으로 한 번 확인해 두시면 헤맬 일이 없습니다.
6단계. 채널 초대와 ID 두 개 확인
토큰과 함께 게이트웨이 설정에 넣을 값 두 개를 확인합니다.
채널에 앱 초대. 헤르메스를 쓸 채널에서 /invite @앱이름을 실행합니다. 초대하지 않으면 채널에서 멘션해도 응답이 없습니다. 앱이 채널에 추가되었다는 시스템 메시지가 남으면 성공입니다.
채널 ID (C로 시작하는 11자리). 왼쪽 사이드바에서 채널 이름을 우클릭하고 링크 복사를 누른 뒤, 복사된 주소의 마지막 C로 시작하는 부분이 채널 ID입니다. 영상처럼 채널 세부 정보 화면 맨 아래에서 확인하셔도 됩니다.
멤버 ID (U로 시작). 화면 왼쪽 아래 내 아이콘을 눌러 프로필을 열고, 오른쪽 패널의 점 세 개 메뉴에서 멤버 ID 복사를 누릅니다.
7단계. 게이트웨이 설정 마법사
터미널로 돌아와 설정 마법사를 실행합니다.
hermes setup gateway
마법사에서 봇 토큰(xoxb-), 앱 레벨 토큰(xapp-), 그리고 아래 두 값을 입력합니다.
⚠️ Allowed user IDs는 반드시 채워주세요. 비워 두면 누구나 쓸 수 있게 되는 것이 아니라, 거꾸로 아무도 쓸 수 없게 됩니다. 본인 멤버 ID(
U로 시작)를 꼭 넣어주세요. 슬랙에서 봇이 아무 반응이 없을 때 가장 흔한 원인입니다.
💡 Home channel ID는 비워 두셔도 됩니다. 나중에 슬랙에서
/set-home명령으로 지정할 수 있습니다. 지금 넣으시려면 6단계에서 복사한 채널 ID(C로 시작)를 입력하세요.
마법사 마지막에 Restart the gateway to pick up changes? [Y/n] 물음이 나오면 Y를 입력합니다. 영상에서는 재시작을 수동으로 했지만 지금은 마법사가 대신 해 줍니다.
수동으로 재시작할 일이 생기면 아래 명령 하나면 됩니다. 영상의 sudo systemctl restart 명령 대신 Mac, Windows, Linux 어디서든 동일하게 동작합니다.
hermes gateway restart
💡 참고로
hermes setup gateway진행 중에Slack app manifest written to:라는 줄이 지나가는데, 이때 저장되는 매니페스트에는--agent-view설정이 빠져 있습니다. 나중에 매니페스트 파일을 다시 쓸 일이 있으면 1단계 명령을 다시 실행해서 새로 만들어 주세요.
8단계. 연결 확인
여기까지 되었으면 확인합니다.
hermes gateway list
PID가 잡혀 있고 상태가 active로 보이면 성공입니다. 슬랙에서 봇이 온라인으로 표시되는지도 함께 확인해 주세요.
- DM: 사이드바 다이렉트 메시지 영역의 앱을 눌러 메시지를 보내면 응답합니다. 답은 내 메시지 아래 스레드(댓글)로 접혀 들어오니, 댓글 줄을 눌러 확인하세요.
- 채널: 그냥 말하면 반응이 없습니다. 고장이 아니라, 채널에서는
@앱이름으로 이름을 불러야 전달됩니다. 답은 역시 스레드로 달립니다. - DM에서 슬래시 명령:
/로 시작하면 슬랙이 먼저 가로챕니다. 한 칸 띄고/skills처럼 입력하시면 게이트웨이로 전달됩니다.
자주 만나는 문제
봇이 아무 반응이 없습니다. 1순위 원인은 Allowed user IDs가 비어 있는 경우입니다(7단계). 그다음은 채널에 앱을 초대하지 않은 경우입니다(6단계).
DM을 보낼 수 없다고 나옵니다. Sending messages to this app has been turned off가 보이면 앱 설정의 App Home에서 Messages Tab이 꺼져 있는 것입니다. 켠 뒤에는 반드시 워크스페이스에 Reinstall 해야 적용됩니다.
invalid_auth 오류가 납니다. 토큰 두 개가 서로 바뀌어 들어간 경우가 가장 흔합니다. xoxb-가 봇 토큰 자리, xapp-가 앱 레벨 토큰 자리인지 앞글자를 확인해 주세요. 매니페스트를 고친 뒤에는 워크스페이스 재설치까지 해야 권한이 갱신됩니다.
로그로 원인 찾기. 막히시면 처음부터 다시 하지 마시고 로그부터 확인하세요.
# macOS
hermes gateway logs
# Linux / WSL
journalctl --user -u hermes-gateway.service -n 200 --no-pager
여기까지 해도 안 되시면 로그 마지막 20줄을 그대로 복사해서 Q&A에 남겨주세요. 로그가 있으면 원인을 바로 짚어드릴 수 있습니다.
마무리
연결이 끝나면 DM과 채널 어디서든 헤르메스를 부를 수 있는 업무 메신저 환경이 완성됩니다.
이 슬랙 연결은 이후 섹션에서 멀티 에이전트를 채널별로 운영할 때 그대로 토대가 되니, 여기서 한 번 탄탄하게 잡아 두시면 뒤가 편해집니다.