커뮤니티 솔루션

ZimaOS에서 Hermes Slack을 설정하고 게이트웨이 오류 해결하기

A ZimaOS user configured a new Hermes Slack app with Socket Mode but hit a permission error on /opt/data/gateway.lock and then received no response to channel mentions.

Hermes Agent는 현재 Slack 통합에서 Socket Mode를 사용하므로 공개 웹훅 엔드포인트를 노출하지 않고도 Slack에 연결할 수 있습니다. 이 페이지의 기반이 된 커뮤니티 보고서는 대부분의 설정을 성공적으로 완료했습니다. 사용자는 새 Slack 앱을 만들고 앱 수준 토큰을 발급받았습니다. xoxb- 봇 토큰과 다음 토큰을 가져왔습니다. xapp- 앱 수준 토큰을 가져온 후 다음을 실행했습니다. hermes gateway setup ZimaOS Hermes 컨테이너 내부에서 봇을 Slack 채널에 초대했습니다.

Hermes가 게이트웨이를 다시 시작하려고 할 때 문제가 발생했습니다. CLI에서 다음 오류가 반환되었습니다. PermissionError: [Errno 13] Permission denied: '/opt/data/gateway.lock'그리고 앱이 Slack에 표시되었지만, @Hermes 멘션해도 응답이 없었습니다. 현재 ZimaSpace 문서에서는 다음을 명시적으로 식별합니다. /opt/data Hermes 게이트웨이 작업을 이전에 root로 실행한 뒤 발생할 수 있는 소유권 문제로 권한 오류를 해석했습니다. 현재 Hermes Slack 문서에는 범위를 수동으로 추측하는 것보다 안전하게 확인할 수 있는 몇 가지 추가 설정 요구 사항도 안내되어 있습니다.

ZimaOS Hermes Slack 보고서에서 발생한 일

2026년 5월 커뮤니티 게시물에서는 새 Slack 워크스페이스에 깨끗하게 설치된 ZimaOS Hermes를 사용했습니다. 사용자는 Socket Mode가 활성화된 Slack 앱을 만들고 필요한 두 가지 토큰을 모두 복사한 다음 Hermes 게이트웨이 마법사를 통해 Slack을 구성했습니다.

핵심 순서는 다음과 같습니다.

  1. Slack 앱을 생성하고 Socket Mode를 활성화하세요.
  2. 로 시작하는 봇 사용자 OAuth 토큰을 가져오세요. xoxb-.
  3. 로 시작하는 앱 수준 토큰을 가져오세요. xapp-.
  4. 다음을 실행하세요. hermes gateway setup Hermes 컨테이너 내부에서.
  5. Slack을 선택하고 두 토큰을 입력하세요.
  6. 게이트웨이를 다시 시작하라는 메시지가 표시되면 확인을 선택하세요.

다시 시작에 실패한 오류는 다음과 같습니다.

PermissionError: [Errno 13] Permission denied: '/opt/data/gateway.lock'

이후 사용자는 Hermes Web UI에서 게이트웨이를 다시 시작하고 @Hermes Slack 채널에 입력하자 Slack에서 앱이 추가되었다는 확인 메시지가 표시되었습니다. 그러나 채널에서 멘션해도 여전히 응답이 없었습니다. 즉, 문제를 해결하려면 ZimaOS 측 게이트웨이 프로세스와 Slack 측 이벤트 구성이라는 두 계층을 점검해야 할 가능성이 있었습니다.

커뮤니티 Slack 문제 해결 게시물에서 공유된 ZimaOS Hermes 설정 참고 자료
커뮤니티 보고서는 Slack 설정을 시도하기 전에 ZimaSpace Hermes 구성 가이드에서 시작했습니다.

모든 범위를 수동으로 다시 구성하는 대신 현재 Hermes Slack 매니페스트 사용

현재 Hermes 문서에서는 Slack 앱 매니페스트를 생성할 것을 권장합니다. 이는 모든 OAuth 범위, 슬래시 명령어, 이벤트 구독 및 Socket Mode 설정을 기억에 의존해 수동으로 다시 만드는 것보다 안전합니다.

현재 Hermes 환경에서 다음 명령으로 매니페스트를 생성하세요.

hermes slack manifest --agent-view --write

생성된 파일은 다음 위치에 기록됩니다.

~/.hermes/slack-manifest.json

그런 다음 Slack 앱 관리 인터페이스에서 해당 매니페스트를 사용해 새 Slack 앱을 만드세요. 현재 Hermes 문서에서는 매니페스트가 기본 제공 명령, 필수 범위, 이벤트 구독 및 Socket Mode 구성을 한 번에 선언한다고 설명합니다.

현재 업스트림 절차는 Hermes Agent Slack 설정 가이드를 참조하세요.

Hermes에 필요한 두 Slack 토큰

Hermes는 서로 다른 두 개의 Slack 자격 증명을 사용하며, 서로 바꿔 사용할 수 없습니다.

  • 봇 토큰: xoxb-으로 시작하며 SLACK_BOT_TOKEN이 됩니다.
  • 앱 수준 토큰: xapp-으로 시작하며 Socket Mode를 지원해야 하고 SLACK_APP_TOKEN이 됩니다.

현재 Hermes 환경 파일에는 다음과 같은 항목이 포함될 수 있습니다.

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

SLACK_ALLOWED_USERS 표시 이름이 아닌 Slack Member ID를 사용합니다. 토큰이 올바르더라도 요청한 사용자가 허용되지 않은 경우 Hermes가 연결된 것처럼 보이면서 해당 사용자의 메시지 처리를 거부할 수 있습니다.

실제 값을 절대 게시하지 마세요 xoxb- 또는 xapp- 커뮤니티 게시물, 스크린샷, Git 저장소 또는 지원 로그에 실제 값을 게시하지 마세요. 토큰이 노출되었다면 폐기하고 새로 생성하세요.

채널 멘션에는 올바른 Slack 이벤트가 필요합니다

봇이 채널에 표시된다고 해서 Slack이 Hermes에 메시지 이벤트를 전달하고 있다는 의미는 아닙니다. 현재 Hermes 문서에서는 이벤트 구독을 일반적인 문제 원인으로 지적합니다.

수동으로 구성한 Slack 앱에서는 현재 Hermes 버전에 필요한 이벤트를 확인하세요. 현재 문서에는 다음과 같은 이벤트가 포함되어 있습니다.

  • app_mention 다이렉트 메시지의 경우 @Hermes 멘션.
  • message.channels 봇이 멤버로 참여한 공개 채널의 메시지에 대해.
  • message.groups 비공개 채널 지원이 필요한 경우.
  • message.im 다이렉트 메시지의 경우.

Slack 앱을 설치한 후 범위나 이벤트 구독을 변경했다면 Slack에서 안내할 때 앱을 워크스페이스에 다시 설치하세요. 그렇지 않으면 표시된 설정과 설치된 봇에 실제로 부여된 권한이 서로 다를 수 있습니다.

테스트 전에 Hermes를 채널에 초대하세요

Hermes는 모든 Slack 채널에 자동으로 참여하지 않습니다. 명시적으로 초대하세요.

/invite @Hermes

그런 다음 Member ID가 Hermes 허용 목록에 포함된 Slack 사용자가 간단한 멘션을 보내도록 테스트하세요. 다이렉트 메시지는 작동하지만 공개 채널 멘션이 작동하지 않는다면 다음을 중점적으로 확인하세요. app_mention, message.channelsZimaOS 네트워크 구성을 변경하기 전에 채널 멤버십과 설치된 앱 권한을 확인하세요.

/opt/data/gateway.lock에서 권한 거부가 발생하는 이유

현재 ZimaSpace Hermes 에이전트 가이드에는 이제 /opt/data 권한 문제가 문서화되어 있습니다. 이 문제는 일반적으로 이전에 Hermes 게이트웨이를 루트로 실행하여 $HERMES_HOME 내에 루트 소유 파일이 남아 발생한다고 설명합니다.

ZimaSpace에서 문서화한 컨테이너 작업 방식은 전용 사용자로 컨테이너에 들어가는 것입니다. hermes 사용자:

docker exec -it -u hermes hermes bash

그런 다음 Hermes 가상 환경을 활성화합니다.

source /opt/hermes/.venv/bin/activate

메시징 설정은 다음 명령으로 열 수 있습니다.

hermes gateway setup

게이트웨이가 다음 명령에서 즉시 실패한다면 /opt/data/gateway.lock, 게이트웨이 전체를 루트로 반복 실행하지 마세요. 먼저 관련 사용자와 소유권을 확인하세요.

id
ls -ld /opt/data
ls -l /opt/data/gateway.lock 2>/dev/null

현재 ZimaSpace 가이드에서는 ZimaOS 대시보드에서 Hermes 로그를 확인하고 파일 소유권을 수정해야 할 때만 일시적으로 루트 셸을 사용하도록 권장합니다. 소유권을 무분별하게 재귀적으로 변경하지 마세요. /opt/data Hermes에 속한 파일과 설치된 ZimaOS 패키지가 요구하는 사용자/그룹을 확인한 경우가 아니라면요.

Hermes가 런타임 파일을 쓸 수 있을 때까지 게이트웨이를 다시 시작하지 마세요

커뮤니티 보고서에서는 웹 UI의 게이트웨이 다시 시작을 클릭하는 것만으로 게이트웨이의 정상 작동을 입증하기에는 부족했습니다. 기본 프로세스가 잠금 파일을 생성하거나 업데이트할 수 없다면 UI 작업 후에도 Slack 통합을 사용할 수 없을 수 있습니다.

실제 소유권 문제를 해결한 후에는 다음 사용자로 컨테이너에 들어갑니다. hermes 사용자로 컨테이너에 들어가 환경을 활성화한 다음, 설치된 Hermes 버전에서 지원하는 명령을 사용해 게이트웨이를 실행하거나 다시 시작하세요. 테스트 Slack 메시지를 보내면서 ZimaOS Hermes 로그를 확인하세요.

유용한 문제 해결 기준은 다음과 같습니다.

  • 게이트웨이가 시작되지 않음: /opt/data 권한과 Hermes 로그를 확인하세요.
  • 게이트웨이는 실행 중이지만 Slack 연결이 없음: xapp- 토큰과 Socket Mode를 확인하세요.
  • Slack 연결은 존재하지만 채널 멘션에 응답이 없음: 앱 이벤트, 채널 멤버십, 재설치 상태 및 SLACK_ALLOWED_USERS를 확인하세요.
  • DM은 작동하지만 채널은 작동하지 않음: 모델 제공업체보다는 채널 이벤트와 권한을 확인하세요.

상태 확인에는 Hermes 웹 대시보드를 사용하되, 유일한 상태 점검 수단으로 사용하지 마세요

ZimaSpace 가이드에는 다음 위치에서 Hermes 웹 대시보드에 액세스하는 방법이 나와 있습니다.

http://ZIMAOS_LAN_IP:9119

대시보드에서는 실행 상태, 세션 및 모델 설정을 확인할 수 있습니다. 게이트웨이를 다시 시작하고 모니터링하는 데 유용하지만, 프로세스 수준의 권한 오류가 발생하면 로그도 함께 확인하세요.

ZimaOS 커뮤니티 사용자가 공유한 Hermes Slack 문제 해결 스크린샷
커뮤니티 보고서에 따르면 Slack 통합이 사용자에게는 표시되었지만 아직 채널 멘션에 답변하지 못했습니다.

ZimaOS의 Hermes Slack 문제 해결 체크리스트

  1. Slack을 추가하기 전에 Hermes 모델 구성 자체가 정상적으로 작동하는지 확인하세요.
  2. ZimaOS 컨테이너에 다음 사용자로 진입하세요: hermes 일반적인 게이트웨이 작업에는 root가 아닌 user로 실행하세요.
  3. 가능하면 권한 범위를 수동으로 추측하는 대신 현재 Hermes Slack 매니페스트를 사용하세요.
  4. 다음을 확인하세요: xoxb- 봇 토큰과 xapp- 앱 토큰이 동일한 Slack 앱에 속하는지 확인하세요.
  5. Socket Mode가 활성화되어 있는지 확인하세요.
  6. Slack Member ID가 다음 항목에 포함되어 있는지 확인하세요: SLACK_ALLOWED_USERS.
  7. 테스트 중인 채널에 Hermes를 초대하세요.
  8. 확인하세요. app_mention 필수 메시지 이벤트가 구독되어 있는지
  9. Slack에서 요청하면 권한 범위나 이벤트 구독을 변경한 후 Slack 앱을 다시 설치하세요.
  10. 다음과 같은 경우: /opt/data/gateway.lock 실패하면 다시 재시작하기 전에 소유권과 ZimaOS Hermes 로그를 확인하세요.
  11. 게이트웨이가 정상 상태가 되면 DM과 채널 멘션 하나를 각각 따로 테스트하세요.

ZimaOS의 Hermes Slack FAQ

gateway.lock 권한 오류는 무엇을 의미하나요?

이는 Hermes 프로세스가 예상된 위치의 런타임 잠금 파일에 접근할 수 없다는 뜻입니다. 현재 ZimaSpace 문서에서는 /opt/data 권한 오류는 대개 Hermes Gateway를 root로 실행한 후 파일 소유자가 root로 남아 있을 때 발생합니다.

문제를 해결하기 위해 Hermes Gateway를 root로 실행해야 하나요?

일반적인 해결 방법은 아닙니다. ZimaSpace 문서에서는 컨테이너에 진입할 때 다음을 사용하도록 안내합니다: hermes 일반적인 Hermes 작업에는 user로 사용하세요. 소유권을 복구해야 한다는 점을 확인한 경우에만 일시적으로 root 셸을 사용해야 합니다.

Slack에서 Hermes 봇은 보이는데 답장하지 않는 이유는 무엇인가요?

앱이 설치되고 초대되었다는 사실만으로는 Slack이 앱을 인식하고 있다는 것만 확인할 수 있습니다. Hermes에는 여전히 정상적인 게이트웨이, 유효한 Socket Mode 연결, 올바른 이벤트 구독, 적절한 워크스페이스 권한, 허용된 Slack Member ID가 필요합니다.

Hermes Slack에 공개 웹훅 URL이 필요한가요?

아니요. 현재 Hermes Slack 통합은 WebSocket을 통한 Socket Mode를 사용하므로, Hermes 인스턴스가 방화벽 뒤에 있어도 외부에서 Slack이 접근할 수 있는 웹훅 엔드포인트를 공개할 필요가 없습니다.

현재 Slack 앱을 구성하는 가장 좋은 방법은 무엇인가요?

설치된 Hermes 릴리스에서 지원하는 경우, 현재 Hermes에서 생성한 Slack 매니페스트를 사용하세요. 누락된 권한 범위, 이벤트 구독 또는 슬래시 명령 정의로 인한 오류를 줄일 수 있습니다.