Jiminbox Docs

Hermes Agent Discord 연동

5 min read

Hermes Agent Discord 연동

Hermes Agent의 메시징 게이트웨이와 Discord 플랫폼을 연동하는 전체 과정

절차 개요

  1. Discord Developer Portal에서 봇 생성
  2. Dashboard API로 봇 토큰 등록
  3. Gateway 재시작
  4. 봇을 Discord 서버에 초대
  5. 페어링 승인
  6. (선택) 홈 채널 설정

Step 1: Discord 봇 생성

Discord Developer Portal

  1. New Application → 이름 입력 (예: “Hermes Agent”)
  2. 좌측 Bot 탭 → Add Bot
  3. Reset Token 버튼으로 토큰 발급 → 복사
  4. Privileged Gateway Intents 3가지 모두 활성화:
    • MESSAGE CONTENT INTENT
    • SERVER MEMBERS INTENT
    • PRESENCE INTENT

Step 2: Dashboard API로 토큰 등록

# 세션 토큰 추출
TOKEN=$(curl -s https://gommes.jimin.io/ | grep -o '__HERMES_SESSION_TOKEN__="[^"]*"' | cut -d'"' -f2)
 
# Discord 봇 토큰 등록
curl -X PUT "https://gommes.jimin.io/api/env" \
  -H "x-hermes-session-token: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"key":"DISCORD_BOT_TOKEN","value":"<your-bot-token>"}'
 
# Gateway 재시작
curl -X POST "https://gommes.jimin.io/api/gateway/restart" \
  -H "x-hermes-session-token: ${TOKEN}"

Step 3: Gateway 재시작 및 상태 확인

curl -s https://gommes.jimin.io/api/status | python3 -c "
import sys,json
d=json.load(sys.stdin)
print(f'Gateway running: {d[\"gateway_running\"]}')
print(f'Discord: {d[\"gateway_platforms\"].get(\"discord\",{}).get(\"state\",\"N/A\")}')
"

정상 응답 시:

{
  "gateway_running": true,
  "gateway_platforms": {
    "discord": {
      "state": "connected",
      "error_code": null,
      "error_message": null
    }
  }
}

Step 4: 봇을 Discord 서버에 초대

Discord Developer Portal → OAuth2 → URL Generator:

  • Scopes: bot
  • Bot Permissions: Send Messages, Read Messages/View Channels, Read Message History, Mention Everyone, Use Slash Commands
  • 생성된 URL로 봇 서버 초대

Step 5: 페어링 승인

페어링 시스템

Hermes는 보안을 위해 페어링(Pairing) 시스템을 사용. 낯선 Discord 유저가 처음 봇과 대화하려면 관리자의 승인이 필요.

페어링 코드 발급

Discord 채널에서 봇을 멘션하거나 DM을 보내면 발급:

Hi~ I don't recognize you yet!
Here's your pairing code: C9C7NBKP
Ask the bot owner to run:
hermes pairing approve discord C9C7NBKP

페어링 승인 명령어 (gateway 컨테이너 터미널)

# 방법 1: Dokploy UI → gateway 컨테이너 터미널 열기
# 방법 2: SSH 접속 후 docker exec
docker exec -it hermes-dydp3k-gateway-1 bash
 
# 컨테이너 내부 (hermes가 PATH에 없음):
source /opt/hermes/.venv/bin/activate
hermes pairing approve discord <페어링코드>

PATH에 hermes가 없는 이유

Hermes는 /opt/hermes/.venv/bin/에 Python 가상환경으로 설치되어 있음. 컨테이너 기본 PATH에는 포함되지 않으므로 source로 가상환경 활성화 필수. 또는 /opt/hermes/.venv/bin/hermes 전체 경로로 직접 실행 가능.

Step 6: 홈 채널 설정 (선택)

Discord 연결 후 다음 메시지가 도착할 수 있음:

📬 No home channel is set for Discord. A home channel is where Hermes
delivers cron job results and cross-platform messages.

Type /sethome to make this chat your home channel, or ignore to skip.

해결: 봇이 있는 Discord 채널에서 슬래시 명령어 실행

/sethome
  • 홈 채널 설정 시 Cron 작업 결과와 교차 플랫폼 메시지 전달
  • 무시해도 일반 대화는 정상 작동

발생한 문제 해결

Provider authentication failed

증상: Discord 봇이 메시지에 반응하지만 다음 에러 전송:

⚠️ Provider authentication failed: No inference provider configured.
Run 'hermes model' to choose a provider and model, or set an API key
(OPENROUTER_API_KEY, OPENAI_API_KEY, etc.) in ~/.hermes/.env.

원인: OPENAI_API_KEY가 Docker Compose environment:로만 전달되고, Hermes 내부 .env 파일에는 기록되지 않았음. Gateway가 실제로 읽는 .env 파일에 API 키 없음.

해결: Dashboard API로 .env 파일에 직접 저장 후 Gateway 재시작

TOKEN=$(curl -s https://gommes.jimin.io/ | grep -o '__HERMES_SESSION_TOKEN__="[^"]*"' | cut -d'"' -f2)
 
curl -X PUT "https://gommes.jimin.io/api/env" \
  -H "x-hermes-session-token: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"key":"OPENAI_API_KEY","value":"sk-..."}'
 
curl -X PUT "https://gommes.jimin.io/api/env" \
  -H "x-hermes-session-token: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"key":"OPENAI_BASE_URL","value":"https://api.jiminbox.com/v1"}'
 
curl -X POST "https://gommes.jimin.io/api/gateway/restart" \
  -H "x-hermes-session-token: ${TOKEN}"

문제 4: API 키 미인식 (Compose env vs .env 파일) 참고

최종 확인

{
  "gateway_running": true,
  "gateway_platforms": {
    "discord": {
      "state": "connected",
      "error_code": null,
      "error_message": null
    }
  }
}

그래프 뷰

백링크