팀 Telegram 어시스턴트 설정

이 튜토리얼에서는 여러 팀원이 함께 사용할 수 있는 Hermes Agent 기반 Telegram 봇을 설정합니다. 완료하면 팀원들이 DM으로 코드, 리서치, 시스템 관리 등 다양한 작업을 요청할 수 있는 공유 AI 어시스턴트를 갖게 됩니다. 접근 권한은 사용자별 인증으로 제한됩니다.

우리가 만들 것

다음과 같은 Telegram 봇을 만듭니다.

승인된 팀원 누구나 DM으로 코드 리뷰, 리서치, 셸 명령, 디버깅 도움을 요청할 수 있습니다.
서버에서 실행되어 터미널, 파일 편집, 웹 검색, 코드 실행 같은 도구에 접근할 수 있습니다.
사용자별 세션을 사용하므로 각 팀원은 서로 독립된 대화 context를 가집니다.
기본적으로 안전합니다. 승인된 사용자만 상호작용할 수 있고, 두 가지 인증 방식을 제공합니다.
예약 작업을 통해 일일 스탠드업, 상태 점검, 알림을 팀 채널로 전달할 수 있습니다.

사전 조건

시작하기 전에 다음을 준비하세요.

서버 또는 VPS에 설치된 Hermes Agent. 노트북이 아니라 계속 켜져 있을 머신이어야 합니다. 아직 설치하지 않았다면 설치 가이드를 먼저 진행하세요.
봇 소유자로 사용할 Telegram 계정
설정된 LLM provider. 최소한 OpenAI, Anthropic 또는 Hermes가 지원하는 다른 provider의 API key가 ~/.hermes/.env에 있어야 합니다.

팁

월 5달러 수준의 VPS면 게이트웨이를 실행하기에 충분합니다. Hermes 자체는 가볍고, 비용이 큰 LLM API 호출은 원격 provider에서 처리됩니다.

1단계: Telegram 봇 만들기

모든 Telegram 봇은 Telegram의 공식 봇 생성 도구인 @BotFather에서 시작합니다.

Telegram을 열고 @BotFather를 검색하거나 t.me/BotFather로 이동합니다.
/newbot을 보냅니다. BotFather가 두 가지를 묻습니다.
- 표시 이름: 사용자에게 보이는 이름입니다. 예: Team Hermes Assistant
- 사용자 이름: 반드시 bot으로 끝나야 합니다. 예: myteam_hermes_bot
봇 토큰을 복사합니다. BotFather는 다음과 같은 응답을 보냅니다.
```
Use this token to access the HTTP API:
7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...
```
이 토큰을 저장하세요. 다음 단계에서 필요합니다.
설명을 설정합니다(선택 사항이지만 권장).
```
/setdescription
```
봇을 선택한 뒤 다음과 같은 설명을 입력합니다.
```
Team AI assistant powered by Hermes Agent. DM me for help with code, research, debugging, and more.
```

봇 명령을 설정합니다(선택 사항). 사용자에게 Telegram 명령 메뉴를 제공합니다.

/setcommands

봇을 선택한 뒤 다음 내용을 붙여넣습니다.

new - Start a fresh conversation
model - Show or change the AI model
status - Show session info
help - Show available commands
stop - Stop the current task

경고

봇 토큰은 반드시 비밀로 유지하세요. 토큰을 가진 사람은 누구나 봇을 제어할 수 있습니다. 유출되었다면 BotFather에서 /revoke를 사용해 즉시 새 토큰을 발급하세요.

2단계: 게이트웨이 설정

대화형 설정 마법사를 사용하는 방법과 직접 설정 파일을 수정하는 방법이 있습니다.

옵션 A: 대화형 설정(권장)

hermes gateway setup

마법사가 화살표 키로 선택하는 흐름을 안내합니다. Telegram을 선택하고, BotFather에서 받은 봇 토큰을 붙여넣은 뒤, 프롬프트가 표시되면 사용자 ID를 입력하세요.

옵션 B: 수동 설정

~/.hermes/.env에 다음 줄을 추가합니다.

# Telegram bot token from BotFather
TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...

# Your Telegram user ID (numeric)
TELEGRAM_ALLOWED_USERS=123456789

사용자 ID 찾기

Telegram 사용자 ID는 @username이 아니라 숫자 값입니다. 다음 순서로 확인합니다.

Telegram에서 @userinfobot에게 메시지를 보냅니다.
봇이 숫자형 사용자 ID를 즉시 응답합니다.
그 숫자를 TELEGRAM_ALLOWED_USERS에 복사합니다.

정보

Telegram 사용자 ID는 123456789처럼 영구적인 숫자입니다. 변경 가능한 @username과 다르므로 allowlist에는 항상 숫자 ID를 사용하세요.

3단계: 게이트웨이 시작

빠른 테스트

먼저 포그라운드에서 게이트웨이를 실행해 모든 것이 정상인지 확인합니다.

hermes gateway

다음과 비슷한 출력이 보여야 합니다.

[Gateway] Starting Hermes Gateway...
[Gateway] Telegram adapter connected
[Gateway] Cron scheduler started (tick every 60s)

Telegram에서 봇을 찾아 메시지를 보내세요. 응답이 오면 설정이 정상입니다. 테스트를 중지하려면 Ctrl+C를 누릅니다.

프로덕션: 서비스로 설치

재부팅 후에도 계속 실행되는 배포가 필요하다면 게이트웨이를 서비스로 설치합니다.

hermes gateway install
sudo hermes gateway install --system   # Linux only: boot-time system service

기본적으로 Linux에서는 사용자 수준 systemd 서비스가, macOS에서는 launchd 서비스가 생성됩니다. --system을 전달하면 Linux에서 부팅 시 시작되는 시스템 서비스를 만듭니다.

# Linux — manage the default user service
hermes gateway start
hermes gateway stop
hermes gateway status

# View live logs
journalctl --user -u hermes-gateway -f

# Keep running after SSH logout
sudo loginctl enable-linger $USER

# Linux servers — explicit system-service commands
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

# macOS — manage the service
hermes gateway start
hermes gateway stop
tail -f ~/.hermes/logs/gateway.log

macOS PATH

launchd plist는 설치 시점의 셸 PATH를 캡처합니다. 그래야 게이트웨이 하위 프로세스가 Node.js, ffmpeg 같은 도구를 찾을 수 있습니다. 이후 새 도구를 설치했다면 hermes gateway install을 다시 실행해 plist를 업데이트하세요.

실행 여부 확인

hermes gateway status

그다음 Telegram에서 봇에게 테스트 메시지를 보냅니다. 몇 초 안에 응답이 와야 합니다.

4단계: 팀 접근 권한 설정

이제 팀원에게 접근 권한을 부여합니다. 두 가지 방식이 있습니다.

방식 A: 정적 allowlist

각 팀원의 Telegram 사용자 ID를 수집한 뒤, 쉼표로 구분해 추가합니다. 팀원에게 @userinfobot에 메시지를 보내 숫자 ID를 확인하라고 안내하면 됩니다.

# In ~/.hermes/.env
TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555

변경 후 게이트웨이를 다시 시작합니다.

hermes gateway stop && hermes gateway start

방식 B: DM 페어링(팀에 권장)

DM 페어링은 더 유연합니다. 사용자 ID를 미리 수집하지 않아도 됩니다.

팀원이 봇에게 DM을 보냅니다. Allowlist에 없으므로 봇은 일회성 페어링 코드로 응답합니다.
```
🔐 Pairing code: XKGH5N7P
Send this code to the bot owner for approval.
```
팀원이 코드를 전달합니다. Slack, 이메일, 직접 대화 등 어떤 채널이든 사용할 수 있습니다.

서버에서 코드를 승인합니다.

hermes pairing approve telegram XKGH5N7P

접근 권한이 즉시 활성화됩니다. 이후 봇이 해당 팀원의 메시지에 응답하기 시작합니다.

페어링된 사용자 관리:

# See all pending and approved users
hermes pairing list

# Revoke someone's access
hermes pairing revoke telegram 987654321

# Clear expired pending codes
hermes pairing clear-pending

팁

DM 페어링은 새 사용자를 추가할 때 게이트웨이를 다시 시작할 필요가 없기 때문에 팀 환경에 적합합니다. 승인은 즉시 반영됩니다.

보안 고려 사항

터미널 접근 권한이 있는 봇에는 절대 GATEWAY_ALLOW_ALL_USERS=true를 설정하지 마세요. 봇을 찾은 사람이 서버에서 명령을 실행할 수 있습니다.
페어링 코드는 1시간 후 만료되며 암호학적으로 안전한 난수를 사용합니다.
Rate limit이 brute-force 공격을 막습니다. 사용자당 10분에 1개 요청, 플랫폼당 최대 3개의 pending code만 허용됩니다.
승인 시도가 5번 실패하면 해당 플랫폼은 1시간 동안 잠깁니다.
모든 페어링 데이터는 chmod 0600 권한으로 저장됩니다.

5단계: 봇 구성

Home channel 설정

Home channel은 봇이 cron 작업 결과와 proactive message를 전달하는 채팅입니다. 설정하지 않으면 예약 작업이 출력을 보낼 곳이 없습니다.

옵션 1: 봇이 들어가 있는 Telegram 그룹이나 채팅에서 /sethome 명령을 사용합니다.

옵션 2: ~/.hermes/.env에서 수동으로 설정합니다.

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"

채널 ID를 찾으려면 @userinfobot을 그룹에 추가하세요. 그러면 그룹의 chat ID를 알려 줍니다.

도구 진행률 표시 설정

도구를 사용할 때 봇이 어느 정도의 진행 정보를 보여 줄지 제어합니다. ~/.hermes/config.yaml에 설정합니다.

display:
  tool_progress: new    # off | new | all | verbose

모드	표시 내용
`off`	최종 응답만 표시. 도구 활동은 보이지 않음
`new`	새 도구 호출마다 짧은 상태 표시. 메시징 환경에 권장
`all`	모든 도구 호출과 세부 정보 표시
`verbose`	명령 결과를 포함한 전체 도구 출력 표시

사용자는 채팅에서 /verbose 명령을 사용해 세션별로 표시 수준을 바꿀 수도 있습니다.

SOUL.md로 응답 스타일 설정

~/.hermes/SOUL.md를 편집해 봇의 말투와 응답 방식을 조정할 수 있습니다.

전체 가이드는 Hermes와 함께 SOUL.md 사용을 참고하세요.

# Soul
You are a helpful team assistant. Be concise and technical.
Use code blocks for any code. Skip pleasantries — the team
values directness. When debugging, always ask for error logs
before guessing at solutions.

프로젝트 context 추가

팀이 특정 프로젝트를 다룬다면 context 파일을 만들어 봇이 팀의 기술 스택을 알 수 있게 하세요.

<!-- ~/.hermes/AGENTS.md -->
# Team Context
- We use Python 3.12 with FastAPI and SQLAlchemy
- Frontend is React with TypeScript
- CI/CD runs on GitHub Actions
- Production deploys to AWS ECS
- Always suggest writing tests for new code

정보

Context 파일은 모든 세션의 system prompt에 삽입됩니다. 간결하게 유지하세요. 모든 문자는 token budget을 사용합니다.

6단계: 예약 작업 설정

게이트웨이가 실행 중이면 팀 채널로 결과를 전달하는 반복 작업을 예약할 수 있습니다.

일일 스탠드업 요약

Telegram에서 봇에게 다음처럼 메시지를 보냅니다.

Every weekday at 9am, check the GitHub repository at
github.com/myorg/myproject for:
1. Pull requests opened/merged in the last 24 hours
2. Issues created or closed
3. Any CI/CD failures on the main branch
Format as a brief standup-style summary.

에이전트가 자동으로 cron job을 만들고, 요청한 채팅 또는 home channel로 결과를 전달합니다.

서버 상태 점검

Every 6 hours, check disk usage with 'df -h', memory with 'free -h',
and Docker container status with 'docker ps'. Report anything unusual —
partitions above 80%, containers that have restarted, or high memory usage.

예약 작업 관리

# From the CLI
hermes cron list          # View all scheduled jobs
hermes cron status        # Check if scheduler is running

# From Telegram chat
/cron list                # View jobs
/cron remove <job_id>     # Remove a job

경고

Cron 작업 프롬프트는 이전 대화를 기억하지 않는 완전히 새로운 세션에서 실행됩니다. 각 프롬프트에는 에이전트가 필요한 모든 context를 넣으세요. 파일 경로, URL, 서버 주소, 원하는 출력 형식, 명확한 지시가 포함되어야 합니다.

운영 팁

안전을 위해 Docker 사용

공유 팀 봇에서는 Docker를 터미널 백엔드로 사용해 에이전트 명령이 호스트가 아니라 컨테이너 안에서 실행되도록 하는 것이 좋습니다.

# In ~/.hermes/.env
TERMINAL_BACKEND=docker
TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20

또는 ~/.hermes/config.yaml에 설정합니다.

terminal:
  backend: docker
  container_cpu: 1
  container_memory: 5120
  container_persistent: true

이렇게 하면 누군가 봇에게 파괴적인 작업을 요청하더라도 호스트 시스템을 보호할 수 있습니다.

게이트웨이 모니터링

# Check if the gateway is running
hermes gateway status

# Watch live logs (Linux)
journalctl --user -u hermes-gateway -f

# Watch live logs (macOS)
tail -f ~/.hermes/logs/gateway.log

Hermes 최신 상태 유지

Telegram에서 봇에게 /update를 보내면 Hermes가 최신 버전을 가져오고 다시 시작합니다. 서버에서 직접 실행할 수도 있습니다.

hermes update
hermes gateway stop && hermes gateway start

로그 위치

항목	위치
게이트웨이 로그	`journalctl --user -u hermes-gateway`(Linux) 또는 `~/.hermes/logs/gateway.log`(macOS)
Cron 작업 출력	`~/.hermes/cron/output/{job_id}/{timestamp}.md`
Cron 작업 정의	`~/.hermes/cron/jobs.json`
페어링 데이터	`~/.hermes/pairing/`
세션 기록	`~/.hermes/sessions/`

더 나아가기

이제 동작하는 팀 Telegram 어시스턴트가 준비되었습니다. 다음 문서를 이어서 보면 운영 품질을 더 높일 수 있습니다.

보안 가이드: 인증, 컨테이너 격리, 명령 승인 심화 설명
메시징 게이트웨이: 게이트웨이 아키텍처, 세션 관리, 채팅 명령 전체 참조
Telegram 설정: 음성 메시지와 TTS를 포함한 Telegram 플랫폼 세부 사항
예약 작업: 전달 옵션과 cron 표현식을 포함한 고급 cron scheduling
Context 파일: 프로젝트 지식을 위한 AGENTS.md, SOUL.md, .cursorrules
성격: 내장 personality preset과 custom persona 정의
더 많은 플랫폼 추가: 같은 게이트웨이에서 Discord, Slack, WhatsApp을 동시에 실행할 수 있습니다.

질문이나 문제가 있나요? GitHub에서 이슈를 열어 주세요. 기여를 환영합니다.

우리가 만들 것​

사전 조건​

1단계: Telegram 봇 만들기​

2단계: 게이트웨이 설정​

옵션 A: 대화형 설정(권장)​

옵션 B: 수동 설정​

사용자 ID 찾기​

3단계: 게이트웨이 시작​

빠른 테스트​

프로덕션: 서비스로 설치​

실행 여부 확인​

4단계: 팀 접근 권한 설정​

방식 A: 정적 allowlist​

방식 B: DM 페어링(팀에 권장)​

보안 고려 사항​

5단계: 봇 구성​

Home channel 설정​

도구 진행률 표시 설정​

SOUL.md로 응답 스타일 설정​

프로젝트 context 추가​

6단계: 예약 작업 설정​

일일 스탠드업 요약​

서버 상태 점검​

예약 작업 관리​

운영 팁​

안전을 위해 Docker 사용​

게이트웨이 모니터링​

Hermes 최신 상태 유지​

로그 위치​

더 나아가기​