소개
Hermes Agent를 최신 버전으로 업그레이드하고, 텔레그램에서 한국어로 말하면 → 일레븐랩스 목소리로 대답하고 → 내 Google 캘린더까지 몇 초 만에 읽어주는 음성 비서를 완성했습니다.
무엇을 만들고 싶었나요?
지난번 사례(Hermes + 텔레그 램 에이전트 만들기, SOUL.md 설정기)에 이어, 이번에는 텍스트 봇을 음성 비서로 발전시키고 싶었습니다. 목표는 세 가지였습니다.
텔레그램에 음성으로 말하면 음성으로 대답하는 봇 (시니어에게는 타이핑보다 말이 편합니다)
매일 받는 AI 브리핑 MP3의 목소리를 일레븐랩스의 자연스러운 목소리로 교체
"내일 일정 알려줘"라고 물으면 몇 초 만에 캘린더를 읽어주는 기능
핵심 흐름은 이렇습니다.
텔레그램 음성메시지
↓ STT (로컬 Whisper, 한국어)
Hermes: 의도 파악 · 캘린더 조회
↓ TTS (일레븐랩스)
텔레그램 음성 버블 + 핵심 텍스트사용한 도구
Hermes Agent v0.20.0 (NousResearch, "The Herald Release" — 2026.8.3)
텔레그램 (게이트웨이 연동,
/voice모드)일레븐랩스 (TTS,
eleven_multilingual_v2모델)로컬 Whisper (STT, faster-whisper
small모델 — 민감한 내용이 밖으로 안 나갑니다)Google Calendar API (Google Workspace 스킬 + OAuth)
Claude Code (전 과정을 옆에서 화면 보며 단계별 코치 역할)
1단계. Hermes v0.20.0 업그레이드
터미널에서 버전 확인 후 업데이트를 실행했습니다.
hermes --version # 현재 버전 확인
hermes gateway stop # 게이트웨이 먼저 정지 (중요!)
hermes update
hermes doctor # 업데이트 후 건강 체크
막혔던 부분 ①: 처음에 텔레그램에서 /update로 시도했다가 "exit code 2" 실패가 났습니다. 원인은 Hermes Desktop 앱과 게이트웨이가 켜져 있어서 윈도우가 파일을 못 바꾼 것. → 모든 Hermes 프로그램을 닫고 hermes gateway stop 후 터미널에서 업데이트하니 해결됐습니다.
막혔던 부분 ②: 업데이트 중 npm 에러(EBADENGINE). Node.js가 구버전(v22.14.0 < 요구 22.22.0)이라 웹 대시보드 설치만 실패한 것이었습니다. → nodejs.org에서 LTS 재설치 → PowerShell 새로 열기 → hermes update 재실행으로 해결. (텔레그램 봇 자체는 Node와 무관하게 이미 정상 작동했습니다.)
2단계. 일레븐랩스 목소리 연결
.env에 API 키, config.yaml에 목소리 설정 — 두 파일 이면 끝입니다. (윈도우 기준 위치: C:\Users\사용자명\AppData\Local\hermes\)
# .env
ELEVENLABS_API_KEY=sk_발급받은키
# config.yaml
tts:
provider: "elevenlabs"
elevenlabs:
voice_id: "내가 고른 Voice ID"
model_id: "eleven_multilingual_v2"
팁: ① API 키 만들 때 Restrict Key를 켰다면 Text to Speech 권한을 Access로 켜야 합니다. ② 라이브러리에서 목소리를 듣기만 하면 안 되고 "My Voices"에 추가해야 API로 쓸 수 있습니다. ③ 한국어는 반드시 eleven_multilingual_v2 — 기본 영어 모델은 한국어 발음이 어색합니다.
3단계. 음성 입력(STT) + 접근 제한 + /voice 켜기
# config.yaml
stt:
provider: "local"
local:
model: "small"
language: "ko" # ← 이 줄이 핵심!
# .env — 내 텔레그램 숫자 ID만 허용 (@userinfobot으로 확인)
TELEGRAM_ALLOWED_USERS=내숫자ID
설정 후 hermes gateway restart, 텔레그램에서 /voice on.
막혔던 부분 ③: 처음엔 language 설정 없이 테스트했더니, 한국어로 "오늘 날씨 알려줘"라고 말했는데 Whisper가 영어로 번역해서 전사("Today, let me tell you about the weather")했고, 봇은 그 영어 문장으로 MP3를 만들어달라는 요청으로 오해했습니다. → language: "ko" 한 줄 추가로 완벽 해결. 이후 "내일 내 일정 알려줘."라고 정확히 전사됩니다.
알아두면 좋은 것: /voice on은 "음성으로 물으면 음성으로 답" 모드입니다. 텍스트로 물으면 텍스트로 답하므로 설정 작업은 텍스트로, 일상 질문은 음성으로 자연스럽게 나뉩니다. 모든 답을 음성으로 받으려면 /voice tts.
4단계. Google 캘린더 직접 연동
연동 전에는 "내일 일정 알려줘"를 물으면 봇이 컴퓨터의 Outlook 화면을 직접 열어 읽느라 3분 이상 걸렸습니다. Google Workspace 스킬로 직접 연동하면 몇 초로 줄어듭니다.
구글 클라우드 콘솔(console.cloud.google.com)에서 한 일 — 약 20분:
새 프로젝트 생성 (
hermes-calendar)Google Calendar API 검색 → 사용 설정
OAuth 동의 화면 구성 (외부 / 앱 이름·이메일 입력)
앱을 "프로덕션"으로 게시 ← 중요 팁!
클라이언트 만들기 → 데스크톱 앱 → JSON 다운로드
막혔던 부분 ④: 테스트 사용자에 내 지메일을 추가하려니 "부적격 계정" 오류. → 테스트 사용자를 포기하고 앱을 프로덕션으로 게시하니 테스트 사용자 자체가 불필요해졌습니다. 보너스로, 테스트 모드였다면 7일마다 재인증해야 했는데 프로덕션은 한 번 인증으로 계속 갑니다. 개인용이라면 처음부터 프로덕션 게시를 추천합니다.
나머지는 텔레그램에서 봇에게 맡겼습니다. "JSON 파일을 다운로드 폴더에 받았어. 다음 단계 안내해줘"라고 하니 봇이 알아서:
JSON 파일을 제 위치로 복사하고
권한을 캘린더만 접근하도록 최소로 설정하고 (Gmail·Drive는 접근 불가)
인증 링크를 만들어 줬습니다
링크 클릭 → 계정 선택 → "인증하지 않은 앱" 경고에서 계속(내가 직접 만든 앱이라 안전) → 허용 → "localhost에 연결할 수 없음" 오류 페이지가 뜨는 게 정상 → 그 페이지의 주소 전체를 복사해 봇에게 붙여넣기 → 연동 완료.
5단계. 중간에 봇이 멈췄을 때 배운 명령어들
긴 하루 동안 몇 번 봇이 멈추거나 느려졌는데, 이때 배운 것들이 실전에서 유용했습니다.
/stop— 진행 중인 작업 즉시 중단 (3분씩 Outlook을 뒤질 때 썼습니다)hermes gateway restart— /stop이 안 먹을 때 PowerShell에서 확실하게 재시작"Compressing context" 메시지 — 고장이 아니라 긴 대화 기록을 정리하는 중. 기다리면 됩니다
/new— 대화가 너무 무거워졌을 때 새 대화 시작 (장기 기억·설정은 유지됨)큰 작업 전에
/new로 시작하면 지연 없이 가볍게 진행됩니다
결과
Before: 텍스트로만 대화, 기계적인 TTS 목소리, 일정 확인에 3분+
After:
마이크 버튼 누르고 "오늘 일정 알려줘" → 몇 초 만에 일레븐랩스 목소리의 음성 버블 + 핵심 텍스트 요약이 함께 도착
봇이 일정 제목("오후 8~9시")과 실제 등록 시간(오전 7~8시)이 다른 것까지 짚어줌
겹치는 일정 경고, "확인할 것 3가지"까지 SOUL.md 형식 그대로
배운 점
에러 메시지를 그대로 읽으면 답이 있다 — "프로세스를 닫고 재시도하라", "Node >=22.22.0 필요" 등 모든 실패가 해결책을 함께 알려줬습니다.
한국어 STT는
language: "ko"를 명시해야 합니다. 자동 감지에 맡기면 영어로 번역되는 사고가 납니다.개인용 OAuth 앱은 프로덕션 게시가 정답 — 테스트 모드의 7일 재인증 굴레를 피할 수 있습니다.
권한은 최소로, 한 번에 하나씩 — 캘린더만 먼저 연동했고, Gmail·Drive는 며칠 써본 뒤 읽기 전용부터 추가할 예정입니다.
음성 비서는 "음성 + 텍스트 동시 전송"이 정답 — 들을 수도 있고, 나중에 찾을 수도 있습니다.
다음 계획
SOUL.md에 음성 규칙 고정 (40초 이내 답변, 실행 전 "예" 확인 등)
아침 브리핑에 오늘 일정 자동 포함
아침 묵상,복약 기록,사기 문자 점검스킬을 하나씩 추가Gmail 읽기 전용 연동
전 과정은 Claude Code와 화면을 공유하며 한 단계씩 진행했습니다. 막힐 때마다 스크린샷을 보여주면 다음 클릭할 버튼을 알려주는 방식이라, 시니어도 충분히 따라할 수 있습니다.
