# Hermes Agent 텔레그램 연결 통합 가이드 대상: Hermes 설치와 모델 연결을 마친 Windows 사용자 목표: 나만 사용할 텔레그램 봇을 만들고, Hermes와 메시지가 오가는지 확인하기 > 이 문서는 휴대폰과 PC의 PowerShell을 번갈아 사용합니다. `PowerShell`에 입력할 명령과 `텔레그램`에서 입력할 메시지를 구분해 주세요. --- ## 0. 시작 전 확인 - Windows PC에서 `hermes`를 실행했을 때 AI의 답변이 오는지 먼저 확인합니다. - 텔레그램 앱을 설치하고 본인 계정으로 로그인합니다. - PC가 켜져 있고 인터넷에 연결되어 있어야 합니다. PC가 꺼지거나 절전 상태가 되면 보통 메시지를 처리할 수 없습니다. - 설치된 Hermes 버전이나 사용하는 프로필에 따라 경로와 화면이 다를 수 있습니다. 아래는 **Windows 기본 프로필**을 기준으로 합니다. **보안:** 봇 토큰은 비밀번호처럼 취급합니다. 화면 공유 중이거나 주위 사람들이 볼 수 있다면 토큰이 보이는 화면을 가리세요. 토큰, 비밀번호, 인증 코드는 다른 사람·단체방·AI 대화창에 보내지 않습니다. --- ## 1. 텔레그램에서 내 봇 만들기 1. 텔레그램 검색창에서 공식 `@BotFather`를 찾아 채팅을 엽니다. 2. 채팅창에 다음을 입력합니다. ```text /newbot ``` 3. 봇의 **표시 이름**을 정합니다. 한글 이름도 가능합니다. 예: `내 개인비서` 4. 봇의 **username**을 정합니다. 영문·숫자·밑줄을 사용하며 `bot`으로 끝나야 합니다. 예: `my_hermes_helper_bot` 5. 이미 사용 중인 username이라면 숫자 등을 더해 다시 입력합니다. 6. BotFather가 발급한 **봇 토큰**을 본인만 볼 수 있게 복사합니다. 다음 단계에서 설정 파일에 직접 입력합니다. 토큰을 이 가이드, 강의용 채팅방, AI 대화창이나 공개 문서에 붙여넣지 마세요. --- ## 2. 내 텔레그램 숫자 ID 확인 허용된 사람만 봇을 사용할 수 있도록 본인의 숫자 ID가 필요합니다. 1. 텔레그램에서 `@userinfobot`을 검색합니다. 이 봇은 제3자 서비스이므로 이용 시 본인의 텔레그램 계정 정보가 해당 봇에 전달될 수 있습니다. 2. 채팅을 열고 `Start`를 누릅니다. 3. 표시되는 `Id`의 **숫자**를 확인합니다. 이것은 username과 다릅니다. 개인 1:1 대화에서는 본인 숫자 ID를 홈 채널 ID로도 사용할 수 있습니다. 단체방 ID는 다를 수 있으므로 이 강의에서는 개인 대화만 사용합니다. --- ## 3. PC에서 텔레그램 설정 파일 열기 Windows 시작 메뉴에서 **PowerShell**을 열고 아래 한 줄을 붙여넣습니다. ```powershell notepad "$env:LOCALAPPDATA\hermes\.env" ``` 이 경로는 기본 설치·기본 프로필을 가정합니다. 별도 프로필 또는 `HERMES_HOME`을 사용하는 경우 해당 프로필의 `.env`를 확인하세요. 파일이 없다는 질문이 나오면 경로가 맞는지 확인한 뒤 생성할 수 있습니다. 저장할 때 이름이 `.env.txt`가 아니라 `.env`인지 확인합니다. 메모장에서 다음 세 항목을 찾습니다. **이미 같은 항목이 있으면 기존 값을 수정하고, 없으면 새 줄로 추가**합니다. 다른 설정은 지우지 마세요. ```text TELEGRAM_BOT_TOKEN=여기에_BotFather_토큰 TELEGRAM_ALLOWED_USERS=여기에_본인_숫자ID TELEGRAM_HOME_CHANNEL=여기에_본인_숫자ID ``` - 위 예시의 `여기에_...` 부분을 실제 값으로 바꿉니다. `< >`나 설명 문구를 그대로 넣지 않습니다. - `TELEGRAM_ALLOWED_USERS`와 `TELEGRAM_HOME_CHANNEL`에는 개인 1:1 대화 기준으로 본인 숫자 ID를 넣습니다. - `TELEGRAM_ALLOWED_USERS`는 본인만 허용하도록 설정합니다. 비워 둔 상태에서 접근이 안전하다고 가정하지 마세요. - 저장은 `Ctrl + S`입니다. 저장한 `.env`에는 토큰이 들어 있으므로 공유하거나 강의 화면에 띄우지 마세요. --- ## 4. Gateway 실행 Gateway는 텔레그램 메시지를 받아 Hermes로 연결하는 프로그램입니다. **설정 저장 후** 실행하세요. ### 처음 강의 실습: 화면에서 직접 실행 PowerShell에서 아래 명령을 입력합니다. ```powershell hermes gateway run ``` 실행 중인 창은 닫지 마세요. 창을 닫거나 `Ctrl + C`로 중지하면 연결도 중단될 수 있습니다. 오류가 뜨면 토큰이나 개인 정보가 보이지 않도록 가린 뒤 강사에게 보여주세요. 이미 같은 프로필의 Gateway가 실행 중이면 중복 실행하지 말고 상태를 확인하세요. `.env`를 바꾸기 전부터 실행 중이었다면 **별도의 PowerShell 창**에서 아래 명령으로 재시작합니다. ```powershell hermes gateway restart ``` 다른 PowerShell 창에서 상태를 확인하려면: ```powershell hermes gateway status ``` 상태가 실행 중으로 표시되더라도 그것만으로 텔레그램 연결 성공은 아닙니다. 다음 단계에서 **실제로 답장이 오는지** 확인해야 합니다. --- ## 5. 텔레그램에서 첫 대화 확인 1. 텔레그램에서 1단계에 만든 **내 봇 username**을 검색합니다. 2. 봇 채팅방을 열고 `Start` 또는 `시작`을 누릅니다. 3. 아래 메시지를 보냅니다. ```text 안녕 ``` 4. 내 Hermes에서 보낸 답장이 텔레그램에 도착하면 기본 연결 성공입니다. 필요하면 개인 채팅방에서 아래 명령을 보내 현재 대화방을 홈 채널로 지정할 수 있습니다. ```text /sethome ``` 홈 채널 지정은 기본 메시지 왕복과 구분해서 확인하세요. 예약 보고가 실제로 도착하는지는 예약 설정 후 별도로 테스트해야 합니다. --- ## 6. 답장이 오지 않을 때 1. **봇 확인:** 내가 만든 봇이 맞는지, 채팅방에서 `Start`를 눌렀는지 확인합니다. 2. **Gateway 확인:** 별도의 PowerShell 창에서 실행합니다. ```powershell hermes gateway status ``` 3. **설정 확인:** `.env`의 토큰과 `TELEGRAM_ALLOWED_USERS` 숫자 ID를 본인이 직접 확인합니다. 화면을 다른 사람에게 보여주거나 설정 파일을 보내지 마세요. 4. **설정 변경 후 재시작:** 변경 내용을 저장했다면 별도 PowerShell에서 실행합니다. ```powershell hermes gateway restart ``` 5. **모델·인터넷 확인:** PC의 Hermes 대화에서 AI 답변이 오는지, 인터넷이 연결되어 있는지 확인합니다. 6. **로그 확인:** 필요할 때 아래 명령으로 로그를 살펴보되, 오류 화면이나 로그에 토큰·개인정보가 포함될 수 있으므로 공유하기 전에 가립니다. ```powershell Get-Content "$env:LOCALAPPDATA\hermes\logs\gateway.log" -Tail 50 ``` 여전히 해결되지 않으면 오류 메시지를 확인하세요. 무조건 토큰을 재발급하거나 보안 설정을 끄지 않습니다. --- ## 7. 선택: PC 로그인 후 자동 실행 이 단계는 **강의 중 필수가 아닙니다.** 자동 실행은 PC의 시작 동작을 바꾸므로, 개인 PC에서 필요성과 권한을 확인한 뒤 진행하세요. 회사·기관 PC는 관리자 정책을 따릅니다. 현재 설치된 Hermes의 안내를 확인합니다. ```powershell hermes gateway install ``` 이후 설치 안내에 따라 시작하고 상태를 확인합니다. ```powershell hermes gateway start ``` ```powershell hermes gateway status ``` Windows에서는 설치 방식과 작업 스케줄러의 로그인 조건에 따라 시작 시점이 달라질 수 있습니다. **등록되었다는 메시지만으로 재부팅 후 자동 복구가 보장되는 것은 아닙니다.** 적절한 시점에 실제 로그인 후 실행 여부와 텔레그램 메시지 왕복을 확인하세요. 재부팅 전에는 작업을 저장합니다. 기존 문서에 있던 별도 watchdog·작업 스케줄러 스크립트는 설치 환경에 따라 충돌하거나 오래되었을 수 있어 이 기본 가이드에는 포함하지 않았습니다. 필요하면 현재 설치 환경을 확인한 후 별도로 검토합니다. --- ## 8. 토큰이 노출된 경우 1. `@BotFather`에서 해당 봇의 토큰을 즉시 폐기하고 새 토큰을 발급합니다. 메뉴는 시점에 따라 달라질 수 있습니다. 2. 본인 PC의 `.env`에서 `TELEGRAM_BOT_TOKEN` 값을 새 토큰으로 교체하고 저장합니다. 3. 별도 PowerShell에서 `hermes gateway restart`를 실행합니다. 4. 텔레그램에서 다시 메시지를 주고받아 확인합니다. `.env`, `auth.json`, API 키, OAuth 토큰을 다른 사람의 PC로 복사하지 않습니다. 각자 자기 계정과 자기 봇을 사용하세요. 강의 실습에는 실제 환자정보나 병원 내부 자료를 사용하지 않습니다. --- ## 9. 최종 체크리스트 - [ ] PC의 Hermes에서 먼저 AI 답변을 확인했다. - [ ] BotFather에서 나만의 봇을 만들었다. - [ ] 본인 텔레그램 숫자 ID를 확인했다. - [ ] `.env`에 봇 토큰과 본인 허용 ID를 넣고 저장했다. - [ ] Gateway를 실행했다. - [ ] 내 봇에서 `Start`를 누르고 `안녕`을 보냈다. - [ ] 텔레그램으로 실제 답장을 받았다. 공식 참고: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram 이 문서는 기존 텔레그램 연결 가이드 두 개를 중복 없이 합친 강의용 문서입니다. 실제 화면과 명령은 설치 버전·프로필에 따라 다를 수 있습니다.