hermes-agent-workshop

name	hermes-agent-workshop
version	1.0.0
description	KUMA 워크샵에서 수강생의 운영체제를 식별하고, Hermes Agent 설치, 프로바이더 인증, Discord 연결, 최종 동작 검증, 인증 만료 등 주요 엣지케이스 복구를 안내하는 실습용 스킬입니다.
metadata	{"hermes":{"tags":["hermes","discord","workshop","setup","automation"],"category":"automation","requires_toolsets":["terminal"]}}

Hermes Agent 워크샵 설치 스킬

언제 이 스킬을 쓰는가

이 스킬은 6시간만에 완성하는 나의 AI 비서 — 업무 자동화 에이전트 워크샵에서 수강생이 자기 노트북에 Hermes Agent를 설치하고, 모델 프로바이더를 인증하고, Discord에 연결해 실제로 메시지를 주고받는 상태까지 만드는 데 사용한다.

Claude Code, Hermes CLI, 또는 다른 CLI 기반 에이전트에서 로드해서 사용할 수 있다. 이 스킬을 사용하는 에이전트는 강의자가 아니라 수강생의 실습 코파일럿처럼 행동한다.

최종 목표

수업 종료 전까지 아래 상태를 만든다.

1. 수강생의 운영체제와 셸을 확인한다.
2. Hermes Agent가 설치되어 터미널에서 실행된다.
3. Hermes의 모델 프로바이더 인증이 완료되어 있다.
4. Discord 연결 전에 로컬 Hermes 채팅이 먼저 성공한다.
5. Discord Bot이 hermes gateway를 통해 Hermes에 연결된다.
6. Discord에서 보낸 테스트 메시지에 Hermes가 응답한다.
7. 프로바이더 인증 만료, Discord 권한 문제, gateway 실패 등 주요 문제의 복구 절차가 남아 있다.

로컬 Hermes 테스트와 Discord 테스트가 모두 끝나기 전에는 “완료”라고 말하지 않는다. 외부 요인 때문에 막힌 경우에는 정확한 blocker를 기록한다.

절대 규칙

• API 키, OAuth 토큰, Discord Bot Token, refresh token, .env 전체 내용을 채팅에 붙여넣게 하지 않는다.
• 비밀값을 출력하거나, 캡처하거나, 커밋하거나, 로그에 남기지 않는다.
• 비밀값은 Hermes 명령, ~/.hermes/.env, OS 키체인, 비밀번호 관리자, 또는 프로바이더별 안전한 로그인 절차에만 저장한다.
• 토큰이 채팅이나 화면에 노출되면 즉시 재발급/회전하라고 안내한다.
• 설치가 안 된다고 무작정 반복 재설치하지 않는다. 먼저 원인을 진단한다.
• 로컬 Hermes 채팅이 성공하기 전에는 Discord 설정으로 넘어가지 않는다.
• fallback provider는 만료된 primary provider 인증을 고치는 대체재가 아니다.
• 가능하면 Hermes 공식 명령과 공식 문서 흐름을 따른다.

작업 분담 원칙

• 코딩 CLI나 에이전트 도구가 직접 할 수 있는 확인, 파일 수정, 명령 실행, 설정 검증은 사용자의 손을 빌리지 말고 직접 수행한다.
• 사용자가 해야 하는 일은 브라우저 로그인, Discord Developer Portal 클릭, 2FA 입력, 토큰 복사처럼 사람의 권한이나 비밀값 입력이 필요한 절차로 제한한다.
• 사용자가 직접 해야 하는 절차를 안내할 때는 항상 “왜 필요한지”를 먼저 설명한다.
• 명령 실행 전에는 목적을 설명하고, 실행 후에는 결과가 무엇을 의미하는지 해석한다.
• 사용자가 복사해야 하는 값은 변수명과 위치만 알려준다. 실제 비밀값은 채팅에 쓰지 않게 한다.

자동화 우선 원칙

사용자 설정 부담을 최소화한다. 기본 방침은 에이전트가 할 수 있는 일은 에이전트가 논인터렉티브하게 처리하고, 사용자는 로그인·승인·비밀값 입력만 한다이다.

• 먼저 현재 상태를 자동 점검한다. 이미 설치·설정된 항목은 다시 시키지 않는다.
• hermes --version, hermes doctor, 설정 파일 존재 여부, 필요한 비밀키가 준비됐는지 여부는 에이전트가 직접 확인한다. 단, 비밀값 자체는 출력하지 않는다.
• 비밀값이 필요한 경우에도 사용자가 파일을 직접 열어 수정하게 하지 않는다. 에이전트가 로컬 입력 프롬프트나 Hermes 명령을 열고, 사용자는 거기에만 값을 붙여넣는다.
• Discord 설정은 가능하면 ~/.hermes/.env를 에이전트가 안전하게 갱신한다. 사용자는 Discord Developer Portal에서 토큰과 User ID를 복사해 로컬 프롬프트에 넣기만 한다.
• hermes gateway setup, hermes model 같은 대화형 명령은 자동 설정이 어렵거나 OAuth/브라우저 승인이 필요한 경우에만 사용한다.
• 수동 파일 편집은 최후의 수단이다. 수동 편집이 필요하면 어느 파일의 어느 변수명을 바꾸는지만 말하고, 비밀값은 채팅에 쓰지 않게 한다.

비밀번호 입력창 전략

비개발자에게 “환경변수 설정”을 시키지 않는다. 사용자에게는 “비밀번호 입력창에 비밀키를 한 번 붙여넣는다”고 설명하고, 저장·파일 수정·검증은 에이전트가 처리한다.

• 사용자-facing 표현에서 환경변수, .env 수정, export, PATH, config.yaml 편집 같은 말을 기본으로 쓰지 않는다.
• 대신 “비밀키 저장”, “AI 계정 연결”, “Discord 연결값 저장”, “건강검진”처럼 행동 중심 표현을 쓴다.
• API key나 Discord token이 필요하면 에이전트가 비밀번호 입력창을 연다. 입력한 글자가 화면에 보이지 않는 입력칸이며, 사용자는 거기에만 붙여넣는다.
• 저장은 hermes config set 또는 에이전트가 관리하는 안전한 .env 갱신 스크립트로 처리한다.
• 저장 후에는 키 값을 보여주지 말고 설정됨/없음만 보여준다.
• 가능하면 OAuth/브라우저 로그인 provider를 우선 추천한다. 이 경우 사용자는 키를 복사하지 않고 로그인 승인만 하면 된다.
• 워크샵 운영상 API key가 꼭 필요하면 사전 안내에서 “수업 전에 키를 발급해 비밀번호 관리자나 메모장에 보관”까지만 요청하고, 수업 중 저장은 에이전트가 한다.
• 수동 파일 편집은 문제 해결 최후 수단이다. 이 경우에도 강사 또는 에이전트가 같이 보고 처리한다.

비개발자 안내 원칙

이 워크샵의 기본 대상은 개발자가 아니다. 설명은 “기술 개념 설명”이 아니라 “지금 화면에서 무엇을 하면 되는지” 중심으로 한다.

• 전문 용어를 먼저 말하지 말고 쉬운 비유를 먼저 쓴다.
  • Hermes Agent: “내 노트북에서 돌아가는 AI 비서 본체”
  • Provider/model: “AI 비서의 두뇌를 빌려주는 계정과 모델”
  • Discord Bot: “Discord 안에 초대하는 AI 비서 계정”
  • Gateway: “Discord 메시지를 Hermes에게 전달하는 연결 통로”
  • Token/API key: “비밀번호와 같은 비밀 열쇠”
  • .env: “비밀 열쇠를 저장하는 개인 메모장 파일”
• 명령어를 보여줄 때는 “이걸 외울 필요 없습니다. 제가 실행하거나, 그대로 복사해서 붙여넣으면 됩니다.”라고 안심시킨다.
• 사용자가 직접 해야 하는 브라우저 작업은 최대 3~5개 하위 단계로 쪼갠다.
• 한 번에 여러 선택지를 던지지 않는다. 기본 추천안을 먼저 제시하고, 필요할 때만 대안을 설명한다.
• 실패 메시지는 겁주지 말고 “어느 연결 고리가 끊겼는지 알려주는 신호”라고 설명한다.
• “인증”, “권한”, “환경변수”, “gateway”, “intent” 같은 단어는 처음 등장할 때 쉬운 뜻을 함께 붙인다.
• 수강생에게 내부 파일 경로, 설정 파일, 명령어 의미를 길게 설명하지 않는다. 필요한 때에만 한 문장으로 설명한다.

응답 방식

기본 언어는 한국어다. 한 번에 한 단계씩 짧고 명확하게 안내한다. 각 단계마다 “왜 이 절차가 필요한지”를 비개발자가 이해할 수 있는 말로 설명한다.

각 단계는 가능한 한 아래 형식을 사용한다.

지금 할 일: ...
왜 필요한가: ...
제가 할 일: ...
수강생이 할 일: ...
완료 신호: ...
막히면: ...

수강생이 할 일이 없으면 수강생이 할 일: 없음이라고 쓴다. 브라우저에서 해야 하는 일은 정확한 클릭 경로로 안내한다. 터미널 명령은 확인된 운영체제에 맞는 것만 제시한다. 에이전트가 직접 실행할 수 있는 명령은 사용자가 따라 치게 하지 말고 직접 실행한 뒤 결과를 쉬운 말로 설명한다.

0단계 — 운영체제와 환경 확인

먼저 수강생의 운영체제와 셸을 확인한다. 터미널 도구를 사용할 수 있으면 직접 확인하고, 사용할 수 없으면 수강생에게 실행하게 한다.

macOS / Linux / WSL

uname -s
uname -m
echo "$SHELL"
command -v hermes || true

판단 기준:

• Darwin → macOS
• Linux이고 /proc/version에 Microsoft 또는 WSL 흔적이 있음 → WSL
• Linux이고 WSL 흔적이 없음 → Linux

Windows PowerShell

[System.Runtime.InteropServices.RuntimeInformation]::OSDescription
$PSVersionTable.PSVersion
Get-Command hermes -ErrorAction SilentlyContinue

환경 기록

대화 안에 아래 형태로 짧게 기록한다.

OS: macOS / Windows native / WSL / Linux
Shell: zsh / bash / PowerShell / unknown
Hermes 설치 여부: yes/no
Provider 선택 여부: 미확인
Discord Bot 준비 여부: yes/no

1단계 — Hermes Agent 설치

운영체제에 맞는 Hermes 공식 설치 경로를 사용한다.

macOS / Linux / WSL

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

설치 후 셸을 다시 로드한다.

source ~/.zshrc 2>/dev/null || source ~/.bashrc 2>/dev/null || true

검증한다.

hermes --version
hermes doctor

hermes 명령을 찾을 수 없으면:

1. 새 터미널을 연다.
2. command -v hermes를 다시 실행한다.
3. 설치 과정에서 PATH가 추가되었는지 확인한다.
4. PATH 확인 전에는 재설치를 반복하지 않는다.

Windows Native PowerShell

PowerShell에서 실행한다.

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

설치 후 새 PowerShell 창을 열고 검증한다.

hermes --version
hermes doctor

PowerShell이 원격 스크립트 실행을 막으면, 보안 정책을 전역으로 끄라고 안내하지 않는다. 대신 Hermes Desktop installer 또는 승인된 로컬 설치 방식을 사용한다.

Desktop Installer 대안

macOS 또는 Windows에서는 Hermes 공식 웹사이트의 Desktop installer를 사용해도 된다. Desktop 설치 후에도 CLI를 반드시 확인한다.

hermes --version
hermes doctor

Windows PowerShell에서는:

hermes --version
hermes doctor

2단계 — 프로바이더 인증 설정

Discord 연결 전에 Hermes가 로컬에서 먼저 동작해야 한다. 이 단계의 목표는 사용자가 설정 파일을 직접 만지지 않고, Hermes가 사용할 “AI 두뇌 계정”을 연결하는 것이다.

2-1. 현재 설정 자동 점검

먼저 에이전트가 아래를 직접 확인한다. 비밀값은 출력하지 않는다.

hermes doctor
hermes config check

가능하면 현재 설정 파일 존재 여부와 provider 관련 환경변수 이름만 확인한다.

python3 - <<'PY'
import os
from pathlib import Path
home = Path.home() / ".hermes"
print(f"Hermes 폴더: {'있음' if home.exists() else '없음'}")
print(f"config.yaml: {'있음' if (home / 'config.yaml').exists() else '없음'}")
print(f".env: {'있음' if (home / '.env').exists() else '없음'}")
for key in ["OPENROUTER_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GOOGLE_API_KEY", "GEMINI_API_KEY", "HF_TOKEN"]:
    print(f"{key}: {'설정됨' if os.environ.get(key) else '환경변수에는 없음'}")
PY

Windows PowerShell에서는 같은 목적의 확인을 PowerShell로 수행한다.

$homePath = Join-Path $HOME ".hermes"
"Hermes 폴더: " + (Test-Path $homePath)
"config.yaml: " + (Test-Path (Join-Path $homePath "config.yaml"))
".env: " + (Test-Path (Join-Path $homePath ".env"))
"OPENROUTER_API_KEY: " + [bool]$env:OPENROUTER_API_KEY
"ANTHROPIC_API_KEY: " + [bool]$env:ANTHROPIC_API_KEY
"GOOGLE_API_KEY: " + [bool]$env:GOOGLE_API_KEY
"GEMINI_API_KEY: " + [bool]$env:GEMINI_API_KEY

쉬운 설명:

• hermes doctor: Hermes가 아픈 곳이 있는지 보는 건강검진
• config.yaml: 일반 설정이 들어 있는 파일
• .env: 비밀번호 같은 비밀 열쇠가 들어 있는 파일

2-2. 기본 추천 경로

비개발자 수강생에게는 기본 추천안을 하나만 먼저 제시한다.

1. Nous Portal 계정이 있거나 워크샵에서 권장하는 경우: hermes setup --portal
2. 이미 OpenRouter/Anthropic/Gemini API key가 준비된 경우: 에이전트가 비밀번호 입력창을 열어 키를 저장
3. OAuth provider를 쓰는 경우: hermes model을 열고 브라우저 로그인만 사용자가 완료

Nous Portal을 쓰는 경우:

hermes setup --portal

특정 provider/model 선택이 필요한 경우:

hermes model

API key를 직접 저장해야 하는 경우에는 사용자가 파일을 열지 않게 하고, 에이전트가 로컬 입력 프롬프트를 제공한다. 예시는 OpenRouter다.

python3 - <<'PY'
import getpass
import subprocess
key = getpass.getpass("OpenRouter API Key를 붙여넣으세요. 화면에는 보이지 않습니다: ").strip()
if not key:
    raise SystemExit("키가 비어 있어 저장하지 않았습니다.")
subprocess.run(["hermes", "config", "set", "OPENROUTER_API_KEY", key], check=True)
subprocess.run(["hermes", "config", "set", "model", "openrouter/anthropic/claude-sonnet-4"], check=False)
print("OpenRouter 키 저장을 완료했습니다. 키 값은 출력하지 않았습니다.")
PY

다른 API key provider도 같은 방식으로 hermes config set KEY VALUE를 사용한다. 키 이름 예시는 ANTHROPIC_API_KEY, GOOGLE_API_KEY, GEMINI_API_KEY 등이다.

중요 조건:

• Hermes는 보통 64K 이상의 context window를 가진 모델을 요구한다. 모델이 거부되면 hermes model에서 더 큰 context 모델을 선택한다.
• 사용자는 명령어를 외울 필요가 없다. 에이전트가 실행하고, 사용자는 로그인 또는 비밀키 입력만 한다.

2-3. 로컬 Hermes 검증

다음으로 로컬 채팅을 검증한다.

hermes doctor
hermes

Hermes가 열리면 간단히 질문한다.

내 현재 Hermes 설정이 정상인지 한 문장으로 답해줘.

성공 기준:

• Hermes가 provider 인증 오류 없이 시작된다.
• 배너 또는 상태에서 선택된 provider/model을 확인할 수 있다.
• 일반 메시지에 모델이 정상 답변한다.

로컬 채팅이 실패하면 Discord 설정으로 넘어가지 말고 provider/model 문제부터 해결한다.

3단계 — Discord Bot 만들기

Discord Developer Portal에서 봇을 만든다.

1. Application 생성

1. https://discord.com/developers/applications 에 접속한다.
2. New Application을 클릭한다.
3. 이름을 입력한다. 예: Hermes Agent
4. Application ID를 복사해 둔다.

2. Bot 생성과 Token 발급

1. 왼쪽 메뉴에서 Bot을 클릭한다.
2. Authorization Flow에서:
   • Public Bot: Discord 기본 설치 링크를 쓸 경우 ON
   • Require OAuth2 Code Grant: OFF
3. Token 영역에서 Reset Token을 클릭한다.
4. 표시된 토큰을 한 번만 복사해서 안전하게 보관한다.

토큰을 채팅에 붙여넣지 않는다. 노출되면 즉시 Reset Token으로 재발급한다.

3. Privileged Gateway Intents 활성화

Bot → Privileged Gateway Intents에서 아래 두 항목을 켠다.

• Server Members Intent
• Message Content Intent

특히 Message Content Intent는 필수다. 이 항목이 꺼져 있으면 봇이 온라인이어도 메시지 내용을 읽지 못한다.

4. Invite URL 생성

권장 방식:

1. 왼쪽 메뉴에서 Installation 클릭
2. Guild Install 활성화
3. Install Link를 Discord Provided Link로 설정
4. Default Install Settings에서:
   • Scopes: bot, applications.commands
   • Permissions: View Channels, Send Messages, Embed Links, Attach Files, Read Message History, Send Messages in Threads, Add Reactions

수동 URL 방식:

https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274878286912

YOUR_APP_ID를 Application ID로 바꾼다.

5. 서버에 Bot 초대

1. Invite URL을 연다.
2. Bot을 추가할 Discord 서버를 선택한다.
3. Authorize를 누른다.
4. CAPTCHA가 나오면 완료한다.

hermes gateway를 실행하기 전까지 Bot은 오프라인으로 보일 수 있다.

6. Discord User ID 확인

1. Discord Settings → Advanced → Developer Mode ON
2. 본인 사용자 이름을 우클릭한다.
3. Copy User ID를 누른다.

이 값은 username이 아니라 긴 숫자 ID다. Hermes allowlist에 이 값을 사용한다.

4단계 — Hermes Discord Gateway 설정

이 단계의 목표는 사용자가 ~/.hermes/.env 파일을 직접 열지 않게 하는 것이다. 에이전트가 Discord 연결값을 안전하게 저장하고, 사용자는 Bot Token은 비밀번호 입력창에, User ID는 일반 입력창에 붙여넣는다.

4-1. 자동 저장 방식 우선

macOS / Linux / WSL에서는 아래 로컬 프롬프트를 사용한다. 토큰은 화면에 보이지 않는다.

python3 - <<'PY'
from pathlib import Path
import getpass

path = Path.home() / ".hermes" / ".env"
path.parent.mkdir(parents=True, exist_ok=True)

print("Discord Bot Token과 User ID를 Hermes에 저장합니다.")
print("토큰은 비밀번호처럼 화면에 보이지 않습니다. 채팅에 붙여넣지 마세요.")
token = getpass.getpass("Discord Bot Token: ").strip()
allowed = input("Discord User ID 숫자: ").strip()
home_channel = input("Home Channel ID (선택, 없으면 Enter): ").strip()
free_channels = input("Mention 없이 답할 Channel ID들 (선택, 쉼표 구분, 없으면 Enter): ").strip()

if not token:
    raise SystemExit("Discord Bot Token이 비어 있어 저장하지 않았습니다.")
if not allowed:
    raise SystemExit("Discord User ID가 비어 있어 저장하지 않았습니다.")

updates = {
    "DISCORD_BOT_TOKEN": token,
    "DISCORD_ALLOWED_USERS": allowed,
    "DISCORD_REQUIRE_MENTION": "true",
}
if home_channel:
    updates["DISCORD_HOME_CHANNEL"] = home_channel
if free_channels:
    updates["DISCORD_FREE_RESPONSE_CHANNELS"] = free_channels

existing = {}
if path.exists():
    for line in path.read_text().splitlines():
        if "=" in line and not line.lstrip().startswith("#"):
            k, v = line.split("=", 1)
            existing[k] = v
existing.update(updates)
path.write_text("\n".join(f"{k}={v}" for k, v in existing.items()) + "\n")
print(f"저장 완료: {path}")
print("토큰 값은 출력하지 않았습니다.")
PY

Windows PowerShell에서는 아래를 사용한다.

$hermesDir = Join-Path $HOME ".hermes"
$envPath = Join-Path $hermesDir ".env"
New-Item -ItemType Directory -Force -Path $hermesDir | Out-Null
Write-Host "Discord Bot Token과 User ID를 Hermes에 저장합니다. 토큰은 화면에 보이지 않습니다."
$secureToken = Read-Host "Discord Bot Token" -AsSecureString
$ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secureToken)
$token = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr)
[Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr)
$userId = Read-Host "Discord User ID 숫자"
$homeChannel = Read-Host "Home Channel ID (선택, 없으면 Enter)"
$freeChannels = Read-Host "Mention 없이 답할 Channel ID들 (선택, 쉼표 구분, 없으면 Enter)"
if (-not $token) { throw "Discord Bot Token이 비어 있어 저장하지 않았습니다." }
if (-not $userId) { throw "Discord User ID가 비어 있어 저장하지 않았습니다." }
$lines = @(
  "DISCORD_BOT_TOKEN=$token",
  "DISCORD_ALLOWED_USERS=$userId",
  "DISCORD_REQUIRE_MENTION=true"
)
if ($homeChannel) { $lines += "DISCORD_HOME_CHANNEL=$homeChannel" }
if ($freeChannels) { $lines += "DISCORD_FREE_RESPONSE_CHANNELS=$freeChannels" }
Set-Content -Path $envPath -Value $lines
Write-Host "저장 완료: $envPath"
Write-Host "토큰 값은 출력하지 않았습니다."

4-2. Hermes guided setup은 보조 수단

자동 저장이 실패하거나 Hermes가 추가 platform 설정을 요구할 때만 guided setup을 사용한다.

hermes gateway setup

프롬프트에서 Discord를 선택한다. Discord bot token과 allowed user ID는 로컬 터미널의 안전한 입력 흐름에 넣고, 채팅에는 쓰지 않는다.

4-3. Gateway 실행과 상태 확인

Gateway를 실행한다.

hermes gateway

가능하면 다른 터미널에서 상태를 확인한다.

hermes gateway status

5단계 — Discord end-to-end 검증

아래 순서대로 테스트한다.

DM 테스트

Bot에게 DM을 보낸다.

안녕. 한 문장으로 지금 연결 상태를 알려줘.

성공 기준:

• DM에서는 @mention 없이 Bot이 응답한다.
• Hermes gateway 로그에 메시지 수신과 응답 기록이 보인다.

서버 채널 테스트

Bot이 볼 수 있는 서버 채널에서 보낸다.

@HermesAgent 안녕. 지금 디스코드 연결 테스트 중이야.

성공 기준:

• Bot을 mention했을 때 응답한다.
• mention 없이 응답하지 않는 것은 기본 설정에서는 정상일 수 있다.

Mention 없이 응답하는 채널 설정

특정 채널에서 mention 없이 Hermes가 답하게 하려면 channel ID를 확인한 뒤 설정한다.

DISCORD_FREE_RESPONSE_CHANNELS=channel_id

설정 후 gateway를 재시작하고 해당 채널에서 일반 메시지를 테스트한다.

6단계 — 워크샵 MVP 선택

Hermes 설치와 Discord 연결이 끝난 뒤에만 업무 자동화 MVP를 고른다. 한 번에 여러 기능을 만들지 않는다.

빠른 완성 순서:

1. 리서치 알림 비서
2. 음성 회의록 비서 — 먼저 전사 텍스트로 시작
3. 오늘 일정 정리 — 먼저 일정 텍스트로 시작
4. DM·문의 분류 비서 — 복사한 샘플 메시지로 시작
5. 아침 메일 브리핑 — 내보낸 메일 텍스트나 샘플로 시작
6. 정기 실행 비서 — 수동 workflow 하나가 먼저 성공한 뒤 진행

첫 MVP에서는 Gmail, Calendar, Notion 같은 실시간 OAuth 연동보다 샘플 텍스트 또는 간단한 파일 입력을 우선한다. 실시간 연동은 선택 확장이다.

엣지케이스 대응 플레이북

문제가 생기면 아래 순서대로 진단한다. 한 번에 하나만 수정하고 같은 테스트로 재확인한다.

A. 프로바이더 인증이 만료되었거나 잘못됨

증상:

• Hermes CLI 또는 Discord 응답에서 provider auth failure가 난다.
• 401, 403, unauthorized, forbidden, invalid_api_key, expired token, authentication expired, OAuth refresh 실패가 보인다.
• Discord Bot은 온라인인데 실제 모델 응답이 모두 실패한다.

진단:

hermes doctor
hermes model

복구:

1. 현재 Hermes가 어떤 provider/model을 쓰는지 확인한다.
2. provider에 맞게 인증을 갱신한다.
   • API key provider: Hermes 설정 또는 ~/.hermes/.env에서 키를 교체한다.
   • OAuth provider: hermes model을 다시 실행하고 브라우저/device login을 완료한다.
   • Nous Portal: hermes setup --portal 또는 Hermes가 안내하는 Nous auth 경로를 사용한다.
3. hermes gateway를 재시작해 Discord가 새 인증 정보를 읽게 한다.
4. 먼저 로컬 Hermes 채팅을 테스트한다.
5. 그다음 Discord를 테스트한다.

이 문제는 Discord token 재발급으로 해결하지 않는다. Discord 로그에 Discord 인증 실패가 있을 때만 Discord token을 확인한다.

B. Provider가 가끔 rate limit 또는 outage로 실패함

증상:

• 429, rate limit, quota exceeded, server overloaded, 500, 502, 503, 연결 끊김이 보인다.

복구:

1. hermes doctor로 기본 provider 설정이 정상인지 확인한다.
2. 기본 provider가 정상인데 불안정하다면, base setup 성공 후 fallback을 설정한다.

hermes fallback

주의:

• Hermes fallback은 rate limit, server error, auth failure, not found, 반복되는 invalid response에서 작동할 수 있다.
• fallback은 turn 단위다. 다음 사용자 메시지에서는 primary provider를 다시 시도한다.
• fallback은 만료된 primary credential을 고치는 절차를 대체하지 않는다.

C. Discord Bot은 온라인인데 응답하지 않음

순서대로 확인한다.

1. hermes gateway가 실행 중인가?
2. 로컬 Hermes 채팅이 먼저 성공했는가?
3. 서버 채널에서 Bot을 mention했는가?
4. Message Content Intent가 켜져 있는가?
5. Server Members Intent가 켜져 있는가?
6. 수강생의 Discord User ID가 DISCORD_ALLOWED_USERS에 들어 있는가?
7. 역할 기반이면 DISCORD_ALLOWED_ROLES가 맞는가?
8. 채널에서 Bot에게 View Channel, Send Messages, Read Message History, Send Messages in Threads 권한이 있는가?
9. 채널이 DISCORD_IGNORED_CHANNELS에 들어 있거나 DISCORD_ALLOWED_CHANNELS에서 제외된 것은 아닌가?
10. 설정 변경 뒤 gateway를 재시작했는가?

가장 흔한 해결책:

• Message Content Intent 켜기
• username이 아니라 정확한 Discord User ID 넣기
• 서버 채널에서는 Bot mention하기
• hermes gateway 재시작하기

D. Discord Gateway가 모든 사용자를 거부함

가능한 원인:

• DISCORD_ALLOWED_USERS와 DISCORD_ALLOWED_ROLES가 비어 있거나 틀렸다.

해결:

1. Discord Developer Mode를 켠다.
2. 본인의 Discord User ID를 복사한다.
3. 수동으로 파일을 열지 말고, 4단계의 자동 저장 프롬프트를 다시 실행해 DISCORD_ALLOWED_USERS를 갱신한다.
4. hermes gateway를 재시작한다.

E. Discord Bot Token이 잘못되었거나 회전됨

증상:

• Gateway가 Discord에 로그인하지 못한다.
• Bot이 계속 오프라인이다.
• 로그에 invalid token 또는 Discord authentication failure가 보인다.

해결:

1. Discord Developer Portal → Application → Bot → Reset Token
2. 새 토큰을 채팅에 붙여넣지 않는다.
3. 4단계의 자동 저장 프롬프트를 다시 실행해 DISCORD_BOT_TOKEN을 갱신한다.
4. Gateway를 재시작한다.

토큰이 노출되었다면 무조건 재발급한다.

F. Bot이 메시지 내용을 읽지 못함

가능한 원인:

• Message Content Intent가 꺼져 있다.

해결:

1. Developer Portal → Application → Bot → Privileged Gateway Intents
2. Message Content Intent ON
3. Save Changes
4. hermes gateway 재시작

G. DM에서는 되는데 서버 채널에서는 안 됨

가능한 원인:

• 서버 채널에서 Bot을 mention하지 않았다.
• 채널 권한이 부족하다.
• Bot 초대 시 scopes/permissions가 부족했다.
• DISCORD_ALLOWED_USERS에 해당 사용자가 없다.

해결:

1. explicit mention으로 테스트한다.
2. 채널 권한을 확인한다.
3. scopes bot, applications.commands를 포함해 다시 초대한다.
4. 권장 permissions integer 274878286912를 사용한다.

H. .env 수정 후에도 옛 설정을 계속 씀

가능한 원인:

• 실행 중인 gateway 프로세스가 옛 환경변수를 들고 있다.

해결:

1. 실행 중인 hermes gateway를 중지한다.
2. 새 터미널에서 다시 시작한다.
3. DM 테스트를 다시 한다.

I. 설치 후 hermes 명령이 없음

해결:

1. 새 터미널을 연다.
2. macOS/Linux/WSL에서는 command -v hermes를 실행한다.
3. Windows에서는 Get-Command hermes를 실행한다.
4. 셸 설정 파일을 다시 로드한다.
5. 그래도 없으면 installer 출력과 PATH를 확인한 뒤 재설치 여부를 결정한다.

J. 선택한 모델이 context window 부족으로 거부됨

가능한 원인:

• 선택한 모델의 context window가 64K보다 작다.

해결:

hermes model

더 큰 context window를 가진 모델을 선택한다.

K. OAuth 브라우저 로그인을 끝냈는데 Hermes가 계속 실패함

해결:

1. hermes doctor를 실행한다.
2. hermes model을 실행해 같은 provider를 다시 선택한다.
3. hermes gateway가 같은 Hermes profile을 쓰는지 확인한다.
4. Gateway를 재시작한다.
5. 로컬 채팅을 먼저 테스트하고, 그다음 Discord를 테스트한다.

L. Discord Slash Commands가 보이지 않음

해결:

1. Bot 초대 scopes에 applications.commands가 포함되었는지 확인한다.
2. Gateway를 재시작한다.
3. DISCORD_COMMAND_SYNC_POLICY를 확인한다. 기본값 safe가 보통 적절하다.
4. scope가 빠졌다면 Bot을 다시 초대한다.

M. 여러 수강생이 같은 Discord 서버를 공유함

권장:

• ~/.hermes/config.yaml에서 group_sessions_per_user: true를 유지한다.
• 가능하면 수강생마다 자기 Bot 또는 자기 allowed user list를 사용한다.
• 협업 실습이 목적이 아니라면 shared session을 피한다.

shared session의 위험:

• context와 token cost가 공유된다.
• 한 명의 실행 중인 작업이 다른 사람의 대화에 영향을 줄 수 있다.

최소 문제 해결 순서

무엇이든 이상하면 아래 순서대로 확인한다.

hermes doctor
hermes model
hermes setup
hermes sessions list
hermes --continue
hermes gateway status

해석:

• hermes doctor가 실패하면 config/auth부터 고친다.
• hermes model이 실패하면 provider credential을 고친다.
• 로컬 채팅이 실패하면 Discord를 건드리지 않는다.
• 로컬 채팅은 되는데 Discord가 실패하면 gateway, Discord token, intents, allowlist, permission, mention rule을 본다.

완료 체크리스트

완료라고 말하기 전에 아래 항목을 확인하고 기록한다.

OS 확인: 완료/미완료
Hermes 설치: 완료/미완료
hermes --version: 확인/미확인
hermes doctor: 통과/경고/실패
Provider/model: 확인된 값 또는 미확인
Local Hermes chat: 성공/실패
Discord application 생성: 완료/미완료
Message Content Intent: ON/OFF/미확인
Server Members Intent: ON/OFF/미확인
DISCORD_ALLOWED_USERS 또는 ROLES: 설정/미설정
hermes gateway: 실행/실패
Discord DM test: 성공/실패
Discord server mention test: 성공/실패
주요 blocker: 없음 또는 구체적 원인

최종 보고 템플릿

작업이 끝나면 실제 확인한 사실만 한국어로 보고한다.

완료된 것:
- OS: ...
- Hermes 설치: ...
- Provider/model: ...
- 로컬 Hermes 테스트: ...
- Discord 연결: ...
- Discord 테스트: ...

실행 방법:
- 로컬 Hermes: hermes
- Discord Gateway: hermes gateway

문제 발생 시 우선순위:
1. hermes doctor
2. hermes model
3. hermes gateway status
4. Discord Intent / allowed user / mention 확인

미완료 또는 외부 blocker:
- ...

확인하지 않은 기능은 성공했다고 말하지 않는다.