팀 전보 도우미 설정
이 튜토리얼에서는 여러 팀 구성원이 사용할 수 있는 Hermes Agent 기반의 Telegram 봇을 설정하는 과정을 안내합니다. 결국 팀은 사용자별 인증으로 보호되는 코드, 연구, 시스템 관리 및 기타 사항에 대한 도움을 요청할 수 있는 공유 AI 도우미를 갖게 됩니다.
우리가 만들고 있는 것
A Telegram bot that:
- 승인된 팀 구성원은 DM으로 코드 검토, 연구, 셸 명령, 디버깅 등의 도움을 요청할 수 있습니다.
- 서버에서 실행 전체 도구 액세스(터미널, 파일 편집, 웹 검색, 코드 실행)
- 사용자별 세션 — 각 사용자는 자신만의 대화 컨텍스트를 얻습니다.
- 기본적으로 보안됨 — 승인된 사용자만 두 가지 인증 방법으로 상호 작용할 수 있습니다.
- 예약된 작업 — 일일 스탠드업, 상태 확인 및 팀 채널로 전달되는 알림
전제 조건
시작하기 전에 다음 사항을 확인하세요.
- Hermes 에이전트가 서버 또는 VPS에 설치되었습니다(노트북이 아님 - 봇이 계속 실행되어야 함). 아직 설치 가이드를 따르지 않았다면 따르세요.
- 본인(봇 소유자)을 위한 텔레그램 계정
- 구성된 LLM 제공자 — 최소한 OpenAI, Anthropic 또는
~/.hermes/.env의 다른 지원 제공자에 대한 API 키
월 5달러 VPS는 게이트웨이를 실행하는 데 충분합니다. Hermes 자체는 가볍습니다. LLM API 호출은 비용이 많이 들고 원격으로 발생합니다.
1단계: 텔레그램 봇 생성
모든 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.
- 봇 명령 설정(선택 사항 - 사용자에게 명령 메뉴 제공):
/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
화살표 키 선택을 통해 모든 과정을 안내합니다. 텔레그램을 선택하고 봇 토큰을 붙여넣은 후 메시지가 나타나면 사용자 ID를 입력하세요.
옵션 B: 수동 구성
~/.hermes/.env에 다음 줄을 추가합니다.
# Telegram bot token from BotFather
TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...
# Your Telegram user ID (numeric)
TELEGRAM_ALLOWED_USERS=123456789
사용자 ID 찾기
텔레그램 사용자 ID는 숫자 값입니다(사용자 이름이 아님). 그것을 찾으려면:
- 텔레그램에서 @userinfobot 메시지를 보내세요.
- 숫자로 된 사용자 ID로 즉시 응답합니다.
- 해당 번호를
TELEGRAM_ALLOWED_USERS에 복사하세요.
텔레그램 사용자 ID는 123456789과 같은 영구 번호입니다. 이는 사용자의 @username과 다르며 변경될 수 있습니다. 허용 목록에는 항상 숫자 ID를 사용하세요.
3단계: 게이트웨이 시작
빠른 테스트
모든 것이 작동하는지 확인하려면 먼저 포그라운드에서 게이트웨이를 실행하세요.
hermes gateway
다음과 같은 출력이 표시됩니다.
[Gateway] Starting Hermes Gateway...
[Gateway] Telegram adapter connected
[Gateway] Cron scheduler started (tick every 60s)
텔레그램을 열고 봇을 찾아 메시지를 보내세요. 응답하면 사업을 시작한 것입니다. 중지하려면 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
````bash
# macOS — manage the service
hermes gateway start
hermes gateway stop
tail -f ~/.hermes/logs/gateway.log
launchd plist는 설치 시 셸 PATH를 캡처하므로 게이트웨이 하위 프로세스가 Node.js 및 ffmpeg와 같은 도구를 찾을 수 있습니다. 나중에 새 도구를 설치하는 경우 hermes gateway install을 다시 실행하여 plist를 업데이트하세요.
실행 중인지 확인
hermes gateway status
그런 다음 Telegram의 봇에 테스트 메시지를 보냅니다. 몇 초 내에 응답을 받아야 합니다.
4단계: 팀 액세스 설정
이제 팀원에게 액세스 권한을 부여해 보겠습니다. 두 가지 접근 방식이 있습니다.
접근 방식 A: 정적 허용 목록
각 팀원의 텔레그램 사용자 ID를 수집하고(@userinfobot 메시지를 보내도록 함) 이를 쉼표로 구분된 목록으로 추가합니다.
# In ~/.hermes/.env
TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555
변경 후 게이트웨이를 다시 시작합니다.
hermes gateway stop && hermes gateway start
접근 방식 B: DM 페어링(팀에 권장)
DM 페어링은 더 유연합니다. 사용자 ID를 미리 수집할 필요가 없습니다. 작동 방식은 다음과 같습니다.
-
팀원이 봇에게 DM을 보냅니다 — 허용 목록에 없기 때문에 봇은 일회성 페어링 코드로 응답합니다.
🔐 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시간 후에 만료되며 암호화 임의성을 사용합니다.
- 속도 제한으로 무차별 대입 공격 방지: 사용자당 10분당 1개 요청, 플랫폼당 최대 3개의 보류 코드
- 승인 시도가 5번 실패하면 플랫폼은 1시간 동안 잠금 상태가 됩니다.
- 모든 페어링 데이터는
chmod 0600권한으로 저장됩니다.
5단계: 봇 구성
홈 채널 설정
홈 채널은 봇이 크론 작업 결과와 사전 메시지를 전달하는 곳입니다. 하나도 없으면 예약된 작업은 출력을 보낼 곳이 없습니다.
옵션 1: 봇이 구성원으로 속한 텔레그램 그룹이나 채팅에서 /sethome 명령을 사용하세요.
옵션 2: ~/.hermes/.env에서 수동으로 설정하세요.
TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"
채널 ID를 찾으려면 @userinfobot을 그룹에 추가하세요. 그러면 그룹의 채팅 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.
프로젝트 컨텍스트 추가
팀이 특정 프로젝트를 진행하는 경우 봇이 스택을 알 수 있도록 컨텍스트 파일을 생성하세요.
<!-- ~/.hermes/AGENTS.md -->
# Team 컨텍스트
- 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
컨텍스트 파일은 모든 세션의 시스템 프롬프트에 삽입됩니다. 간결하게 유지하세요. 모든 캐릭터는 토큰 예산에 포함됩니다.
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.
에이전트는 자동으로 크론 작업을 생성하고 요청한 채팅(또는 홈 채널)에 결과를 전달합니다.
서버 상태 점검
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 작업 프롬프트는 이전 대화를 기억하지 않고 완전히 새로운 세션에서 실행됩니다. 각 프롬프트에 파일 경로, 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
헤르메스를 최신 상태로 유지하세요
Telegram에서 /update을 봇으로 보내면 최신 버전을 가져오고 다시 시작됩니다. 또는 서버에서:
hermes update
hermes gateway stop && hermes gateway start
로그 위치
| 무엇 | 위치 |
|---|---|
| 게이트웨이 로그 | journalctl --user -u hermes-gateway(Linux) 또는 ~/.hermes/logs/gateway.log(macOS) |
| 크론 작업 출력 | ~/.hermes/cron/output/{job_id}/{timestamp}.md |
| 크론 작업 정의 | ~/.hermes/cron/jobs.json |
| 페어링 데이터 | ~/.hermes/pairing/ |
| 세션 기록 | ~/.hermes/sessions/ |
더 나아가
작업 팀 Telegram 도우미가 있습니다. 다음 단계는 다음과 같습니다.
- 보안 가이드 — 승인, 컨테이너 격리 및 명령 승인에 대한 심층 분석
- 메시징 게이트웨이 — 게이트웨이 아키텍처, 세션 관리 및 채팅 명령에 대한 전체 참조
- 텔레그램 설정 — 음성 메시지 및 TTS를 포함한 플랫폼별 세부 정보
- 예약된 작업 — 전달 옵션 및 크론 표현식을 갖춘 고급 크론 예약
- 컨텍스트 파일 — 프로젝트 지식을 위한 AGENTS.md, SOUL.md 및.cursorrules
- 성격 — 내장된 성격 사전 설정 및 사용자 정의 페르소나 정의
- 더 많은 플랫폼 추가 — 동일한 게이트웨이에서 Discord, Slack 및 WhatsApp을 동시에 실행할 수 있습니다.
질문이나 문제가 있나요? GitHub에서 이슈를 개설하세요. 기여를 환영합니다.