HHermes × Telegram
실제 운영 구성 · 비밀정보 제거본

우리가 설정한
Telegram 속 Hermes

Windows 11의 WSL2 안에서 Hermes Gateway를 상시 실행하고, Telegram DM을 홈 채널로 지정한 방식입니다. 동생분이 같은 구조를 처음부터 재현할 수 있도록 순서대로 정리했습니다.

Windows 11 + WSL2Hermes AgentTelegram BotOpenAI Codex OAuthsystemd 상시 실행
📱 Telegram 앱동생이 메시지·파일·음성을 전송
↓
🤖 BotFather에서 만든 전용 봇토큰은 공개하지 않고 Hermes의 .env에만 저장
↓
⚙️ Hermes Gateway · WSL2허용 사용자 확인 → 모델·도구 호출 → 답변 전송
↓
🧠 OpenAI Codex + 로컬 도구파일·터미널·웹·메모리·예약작업
현재 방식Telegram long polling
접근 제어본인 User ID만 허용
자동 시작systemd user service
예약 결과DM을 Home Channel로
00 · Overview

먼저, 무엇을 만드는가

Telegram 자체에 AI가 들어가는 것이 아닙니다. PC의 WSL2에서 Hermes Gateway가 계속 실행되면서 Telegram 봇 메시지를 받아 처리합니다.

우리가 실제로 쓰는 핵심 구조
전용 Telegram 봇 1개 → 허용된 내 Telegram 숫자 ID만 접근 → Hermes Gateway가 WSL2에서 상시 실행 → 이 DM을 홈 채널로 지정 → 예약작업 결과도 같은 DM으로 수신

이 방식이 좋은 이유

  • 휴대폰에서 언제든 업무 요청 가능
  • PC 파일과 개발도구를 그대로 사용
  • 대화·메모리·예약작업이 연결됨
  • Telegram 토큰만 별도 관리하면 됨

알아둘 한계

  • PC와 WSL이 꺼지면 봇도 멈춤
  • 봇 토큰이 유출되면 즉시 폐기해야 함
  • 허용 사용자 설정 없이는 사용하면 안 됨
  • 위험 명령은 승인 여부를 직접 판단해야 함
01 · Windows foundation

Windows에 WSL2 준비

우리 구성은 Windows 11 위의 Ubuntu WSL2입니다. 이미 Ubuntu 터미널이 정상 실행된다면 이 단계는 건너뜁니다.

1

관리자 PowerShell에서 WSL 설치

Windows 시작 메뉴에서 PowerShell을 관리자 권한으로 열고 실행합니다.

PowerShell
wsl --install -d Ubuntu
설치 후 Windows를 재부팅하고 Ubuntu를 열어 Linux 사용자 이름과 비밀번호를 만듭니다. 비밀번호 입력 중에는 글자가 화면에 보이지 않는 것이 정상입니다.
2

systemd 활성화

상시 Gateway 서비스를 사용하려면 WSL의 systemd를 켭니다.

Ubuntu · /etc/wsl.conf
sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true

[user]
default=내_LINUX_사용자명
EOF

그다음 PowerShell에서 WSL을 완전히 종료하고 다시 엽니다.

PowerShell
wsl --shutdown
02 · Hermes

Hermes Agent 설치

아래 명령은 반드시 Ubuntu/WSL 터미널에서 실행합니다. Windows PowerShell 명령과 섞지 마세요.

3

공식 설치 스크립트 실행

Hermes 공식 사이트의 설치 스크립트를 사용합니다.

Ubuntu / WSL2
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
설치 확인
hermes --version
hermes doctor
03 · Model login

우리가 사용한 모델 연결

우리 설정은 OpenAI Codex OAuth 방식입니다. API 키를 채팅에 붙이지 않고 브라우저의 기기 인증으로 로그인했습니다.

4

모델 선택기 실행

메뉴에서 OpenAI Codex를 선택하고 화면에 나온 기기 인증 절차를 완료합니다.

Ubuntu / WSL2
hermes model
동생분 계정에서 사용 가능한 모델을 선택하면 됩니다. 모델 이름은 시점에 따라 달라질 수 있으므로 이 문서에 특정 모델명을 고정하지 않습니다. Hermes는 64K 이상 컨텍스트 모델을 요구합니다.

CLI가 먼저 작동하는지 반드시 확인합니다.

첫 대화 테스트
hermes chat -q "현재 작업 폴더를 확인하고 한 문장으로 알려줘"
04 · BotFather

Telegram 전용 봇 생성

기존 사람 계정을 연결하는 것이 아니라 Telegram 공식 @BotFather에서 동생분 전용 봇을 새로 만듭니다.

5

BotFather에서 /newbot

Telegram에서 아래 순서로 진행합니다.

순서입력설명
1@BotFather파란 인증 마크가 있는 공식 계정 확인
2/newbot새 봇 만들기
3표시 이름예: 동생 Hermes
4사용자 이름반드시 bot으로 끝나야 함
5발급 토큰복사하되 누구에게도 전송하지 않음
토큰은 비밀번호입니다. Telegram 채팅, 카카오톡, GitHub, 공유 문서에 붙여넣지 마세요. 유출되면 BotFather의 /revoke로 폐기하고 새 토큰을 발급합니다.
05 · Access control

본인의 숫자 User ID 확인

Telegram 사용자 이름(@아이디)이 아니라 숫자로 된 고유 ID가 필요합니다. 이 값으로 동생분만 봇을 사용할 수 있게 막습니다.

6

@userinfobot에 메시지 보내기

@userinfobot이 돌려주는 숫자 ID를 메모합니다.

가이드 예시의 123456789를 그대로 쓰면 안 됩니다. 반드시 동생분 본인의 실제 숫자 ID를 입력하세요.
06 · Connect

Hermes Gateway에 Telegram 연결

우리가 사용한 핵심 설정은 TELEGRAM_BOT_TOKEN, TELEGRAM_ALLOWED_USERS, 그리고 이후 설정되는 TELEGRAM_HOME_CHANNEL입니다.

7

대화형 설정 마법사 사용

수동 편집보다 마법사를 권장합니다. Telegram을 선택하고 BotFather 토큰과 본인의 숫자 User ID를 입력합니다.

Ubuntu / WSL2
hermes gateway setup
설정값은 일반적으로 ~/.hermes/.env에 저장됩니다. 정상적인 결과는 아래 세 변수 구조이며 실제 값은 절대 공개하지 않습니다.
구조 예시 · 실제 값을 공유하지 말 것
TELEGRAM_BOT_TOKEN=[BotFather에서 받은 비밀 토큰]
TELEGRAM_ALLOWED_USERS=[내 숫자 User ID]
TELEGRAM_HOME_CHANNEL=[/sethome 후 저장되는 채널 ID]

비밀 파일 권한을 제한합니다.

보안 권한
chmod 600 ~/.hermes/.env
8

먼저 포그라운드로 연결 테스트

서비스 설치 전에 눈에 보이는 상태에서 테스트합니다.

Ubuntu / WSL2
hermes gateway run

터미널을 닫지 않은 상태에서 새 봇의 Telegram DM을 열고 /start 또는 “안녕”을 보냅니다.

답변이 오면 연결 성공입니다. 테스트를 끝낼 때는 Ubuntu 터미널에서 Ctrl+C로 Gateway를 종료합니다.
07 · Always on

Gateway를 상시 서비스로 실행

우리 PC에서는 Hermes가 생성한 systemd 사용자 서비스가 enabled + active 상태이며, 사용자 로그아웃 후에도 유지되도록 linger를 켰습니다.

9

서비스 설치·시작

포그라운드 테스트가 성공한 다음에만 실행합니다.

Ubuntu / WSL2
hermes gateway install
hermes gateway start
hermes gateway status
로그아웃 후에도 서비스 유지
sudo loginctl enable-linger "$USER"
loginctl show-user "$USER" -p Linger
정상이라면 Gateway 상태에 running, linger 상태에 Linger=yes가 표시됩니다.
10

Windows 재부팅 이후 주의

systemd 서비스는 WSL 안에서는 자동 실행되지만, Windows 재부팅 후 WSL 배포판 자체가 시작되지 않았다면 Ubuntu를 한 번 열어야 할 수 있습니다.

상태 복구 순서
wsl -d Ubuntu
# Ubuntu 안에서
hermes gateway status
hermes gateway start
PC가 꺼지거나 절전·네트워크 단절 상태면 Telegram 봇은 응답할 수 없습니다. 24시간 운영이 필요하면 항상 켜진 서버/VPS에 같은 Gateway 구조를 설치해야 합니다.
08 · Home channel

이 Telegram DM을 홈 채널로 지정

우리 방식에서는 예약작업과 자동 알림이 현재 DM으로 돌아오도록 홈 채널을 설정했습니다.

11

봇 DM에서 /sethome

동생분의 Hermes 봇과 1:1 대화방에서 아래 명령을 보냅니다.

Telegram 메시지
/sethome

확인용 명령도 실행합니다.

Telegram 메시지
/status
이후 cron 예약작업을 만들 때 전달 대상을 origin 또는 홈 채널로 설정하면 결과가 이 Telegram 대화로 옵니다.
09 · Verification

완료라고 판단하는 최종 테스트

단순히 봇이 “안녕”에 답하는 것만으로 끝내지 않고, 실제 업무에 필요한 연결을 하나씩 확인합니다.

테스트Telegram에서 보낼 문장성공 기준
일반 대화“너의 역할을 세 줄로 알려줘”정상 답변
시스템 도구“현재 운영체제를 실제로 확인해줘”도구 실행 후 근거 있는 답변
파일 작업“홈 폴더에 test 폴더가 있는지 확인해줘”WSL 파일시스템 확인
세션/new 후 새 질문새 대화가 분리됨
재시작Gateway 재시작 후 메시지다시 정상 응답
접근제어허용되지 않은 계정으로 DM실행되지 않음
Gateway 점검 명령
hermes doctor
hermes gateway status
hermes status --all
hermes sessions list
10 · Security & recovery

보안과 문제 해결

반드시 지킬 것

  • Bot Token은 ~/.hermes/.env에만 저장
  • TELEGRAM_ALLOWED_USERS는 반드시 설정
  • .env를 GitHub에 커밋하지 않기
  • 위험 명령 승인은 내용을 읽고 결정
  • 다른 프로젝트에는 별도 봇 토큰 사용

평소 관리 명령

  • hermes update — 업데이트
  • hermes doctor — 진단
  • hermes gateway restart — 재시작
  • hermes gateway status — 상태
  • journalctl --user -u hermes-gateway -n 100 — 로그
증상확인할 것조치
봇이 완전히 무응답Gateway 상태·토큰hermes gateway status → restart
unauthorized 표시숫자 User IDTELEGRAM_ALLOWED_USERS 수정
재부팅 후 무응답WSL·systemd 시작 여부Ubuntu 실행 → Gateway start
그룹에서만 무응답BotFather Privacy Mode끄거나 봇을 관리자 지정 후 재초대
모델 오류OAuth·모델 선택hermes model 재인증
토큰 유출노출 위치BotFather /revoke 후 새 토큰 입력·restart
절대 공유하지 않을 정보
실제 Bot Token, 실제 API 키, OAuth 토큰, ~/.hermes/.env 전체 내용, 인증코드, 개인 Telegram 숫자 ID가 포함된 설정 파일.
Done

최종 완료 체크리스트

이 항목이 모두 체크되면 완료입니다.
이제 동생분은 Telegram에서 메시지를 보내 Windows PC의 Hermes에게 조사·파일·코드·자동화 작업을 요청할 수 있습니다.