팀 Telegram 어시스턴트

기준일: 2026-08-02
난이도: 중급
공식 기준: Team Telegram Assistant

개요

이 튜토리얼은 팀 전체가 DM으로 쓸 수 있는 Telegram 봇을 서버에 상시 띄우고, allowlist·pairing으로 접근을 통제하고, 예약 작업까지 붙이는 전 과정을 다룹니다.

핵심 개념

단계	내용
Bot 생성	@BotFather로 토큰 발급
Gateway	상시 실행되는 서비스로 설치
Allowlist / Pairing	정적 목록 또는 DM pairing으로 팀원 승인
Ops	홈 채널, tool progress 표시, SOUL.md, 컨텍스트 파일, cron, 로그 위치

선택 기준

이 튜토리얼로 만드는 봇은 다음과 같은 특성을 가집니다.

승인된 팀원 누구나 DM으로 코드 리뷰·리서치·셸 명령·디버깅을 요청할 수 있다
터미널·파일 편집·웹 검색·코드 실행까지 전체 도구 접근 권한을 갖고 서버에서 실행된다
사용자별로 독립된 세션을 가진다
기본적으로 안전하다 — 승인된 사용자만 상호작용할 수 있고 인증 방식은 두 가지다
매일 스탠드업, 헬스 체크 같은 예약 작업을 팀 채널로 전달한다

시작하기 전에 다음을 준비합니다.

서버나 VPS에 설치된 Hermes Agent (봇이 계속 떠 있어야 하므로 노트북이 아니라 서버·VPS를 씁니다. 설치가 안 됐다면 설치 가이드를 먼저 따릅니다.)
봇 소유자 본인의 Telegram 계정
~/.hermes/.env에 설정된 LLM provider API 키(OpenAI, Anthropic 등 최소 하나)

월 5달러짜리 VPS로도 게이트웨이를 충분히 운영할 수 있습니다. Hermes 자체는 가볍고, 비용이 드는 건 원격으로 호출되는 LLM API 쪽입니다.

실습

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.

봇 명령 설정(선택 — 사용자에게 명령 메뉴를 보여줌)

/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을 고르고 봇 토큰을 붙여넣은 뒤, 물어보면 사용자 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는 숫자 값입니다(사용자 이름이 아닙니다).

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 전용: 부팅 시 시스템 서비스

백그라운드 서비스가 만들어집니다 — 기본적으로 Linux에서는 사용자 단위 systemd 서비스, macOS에서는 launchd 서비스, --system을 넘기면 Linux 부팅 시 시스템 서비스입니다.

# Linux — 기본 사용자 서비스 관리
hermes gateway start
hermes gateway stop
hermes gateway status

# 실시간 로그 보기
journalctl --user -u hermes-gateway -f

# SSH 로그아웃 후에도 계속 실행
sudo loginctl enable-linger $USER

# Linux 서버 — 명시적 시스템 서비스 명령
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

# macOS — 서비스 관리
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: 정적 Allowlist

각 팀원의 Telegram 사용자 ID를 모아(@userinfobot에게 메시지를 보내게 하면 됩니다) 쉼표로 구분한 목록으로 추가합니다.

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

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

hermes gateway stop && hermes gateway start

방식 B: DM Pairing(팀에 권장)

DM pairing은 더 유연합니다. 사용자 ID를 미리 모을 필요가 없습니다. 동작 방식은 다음과 같습니다.

팀원이 봇에게 DM을 보냅니다. allowlist에 없으므로 봇은 1회용 pairing 코드로 응답합니다.

🔐 Pairing code: XKGH5N7P
Send this code to the bot owner for approval.

팀원이 그 코드를 (Slack, 이메일, 대면 등 아무 채널로나) 당신에게 보냅니다.
서버에서 승인합니다.

hermes pairing approve telegram XKGH5N7P

바로 사용 가능해집니다. 봇이 즉시 그 사람의 메시지에 응답하기 시작합니다.

Pairing 사용자 관리

# 대기 중/승인된 사용자 전체 보기
hermes pairing list

# 특정 사용자 접근 취소
hermes pairing revoke telegram 987654321

# 만료된 대기 코드 정리
hermes pairing clear-pending

DM pairing은 새 사용자를 추가할 때 게이트웨이를 재시작할 필요가 없어서 팀에 적합합니다. 승인은 즉시 반영됩니다.

보안 고려 사항

터미널 접근 권한이 있는 봇에는 GATEWAY_ALLOW_ALL_USERS=true를 절대 설정하지 않습니다. 봇을 찾은 누구나 서버에서 명령을 실행할 수 있게 됩니다.
Pairing 코드는 1시간 후 만료되며 암호학적으로 안전한 난수를 씁니다.
레이트 리밋으로 무차별 대입을 막습니다: 사용자당 10분에 1회, 플랫폼당 대기 코드 최대 3개.
승인 시도가 5회 실패하면 해당 플랫폼은 1시간 동안 잠깁니다.
모든 pairing 데이터는 chmod 0600 권한으로 저장됩니다.

5단계: 봇 설정

홈 채널 지정

홈 채널은 cron 작업 결과와 선제적 메시지가 전달되는 곳입니다. 지정하지 않으면 예약 작업이 보낼 곳이 없습니다.

옵션 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를 편집해 봇이 소통하는 방식을 바꿉니다. 자세한 내용은 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 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

컨텍스트 파일은 모든 세션의 system prompt에 주입됩니다. 글자 수 하나하나가 토큰 예산을 깎아먹으므로 간결하게 유지합니다.

6단계: 예약 작업 설정

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

일일 스탠드업 요약

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

매주 평일 오전 9시에 github.com/myorg/myproject 저장소를 확인해서
1. 지난 24시간 동안 열리거나 머지된 PR
2. 생성되거나 닫힌 이슈
3. main 브랜치의 CI/CD 실패 여부
를 짧은 스탠드업 형식으로 요약해줘.

에이전트가 자동으로 cron 작업을 만들고, 질문을 보낸 채팅(또는 홈 채널)에 결과를 전달합니다.

서버 헬스 체크

6시간마다 'df -h'로 디스크 사용량을, 'free -h'로 메모리를,
'docker ps'로 Docker 컨테이너 상태를 확인해줘. 파티션 사용량이 80%를 넘거나,
재시작된 컨테이너가 있거나, 메모리 사용량이 비정상적으로 높으면 알려줘.

예약 작업 관리

# CLI에서
hermes cron list          # 예약된 작업 전체 보기
hermes cron status        # 스케줄러 동작 여부 확인

# Telegram 채팅에서
/cron list                # 작업 보기
/cron remove <job_id>     # 작업 제거

Cron 작업 프롬프트는 이전 대화 기억이 전혀 없는 완전히 새로운 세션에서 실행됩니다. 파일 경로, URL, 서버 주소, 명확한 지시 등 에이전트에게 필요한 컨텍스트를 전부 프롬프트 안에 넣습니다.

프로덕션 팁

Docker로 안전하게

여러 명이 쓰는 팀 봇이라면 터미널 백엔드로 Docker를 써서 에이전트 명령이 호스트가 아니라 컨테이너 안에서 실행되게 합니다.

# In ~/.hermes/.env
TERMINAL_ENV=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

이렇게 하면 누군가 봇에게 파괴적인 명령을 요청해도 호스트 시스템은 보호됩니다.

게이트웨이 모니터링

# 게이트웨이가 실행 중인지 확인
hermes gateway status

# 실시간 로그 보기 (Linux)
journalctl --user -u hermes-gateway -f

# 실시간 로그 보기 (macOS)
tail -f ~/.hermes/logs/gateway.log

Hermes 최신 상태 유지

Telegram에서 봇에게 /update를 보내면 최신 버전을 받아 재시작합니다. 서버에서 직접 하려면,

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`
Pairing 데이터	`~/.hermes/pairing/`
세션 기록	`~/.hermes/sessions/`

Hermes에 입력할 프롬프트

지금 게이트웨이 설정을 점검해줘.
TELEGRAM_ALLOWED_USERS와 pairing 목록, 홈 채널, tool_progress 모드,
Docker 터미널 백엔드 사용 여부를 정리하고 보안상 허술한 부분이 있으면 알려줘.

체크리스트

봇 토큰을 .env에만 두고 노출하지 않았다.
GATEWAY_ALLOW_ALL_USERS=true를 쓰지 않았다.
정적 allowlist 또는 DM pairing 중 팀 규모에 맞는 방식을 골랐다.
게이트웨이를 서비스로 설치해 재부팅 후에도 살아남게 했다.
홈 채널과 tool progress 모드를 설정했다.
다중 사용자 환경이라면 Docker 터미널 백엔드로 격리했다.

다음 단계

팀 Telegram 어시스턴트

기준일: 2026-08-02
난이도: 중급
공식 기준: Team Telegram Assistant

개요

핵심 개념

단계	내용
Bot 생성	@BotFather로 토큰 발급
Gateway	상시 실행되는 서비스로 설치
Allowlist / Pairing	정적 목록 또는 DM pairing으로 팀원 승인
Ops	홈 채널, tool progress 표시, SOUL.md, 컨텍스트 파일, cron, 로그 위치

선택 기준

이 튜토리얼로 만드는 봇은 다음과 같은 특성을 가집니다.

승인된 팀원 누구나 DM으로 코드 리뷰·리서치·셸 명령·디버깅을 요청할 수 있다
터미널·파일 편집·웹 검색·코드 실행까지 전체 도구 접근 권한을 갖고 서버에서 실행된다
사용자별로 독립된 세션을 가진다
기본적으로 안전하다 — 승인된 사용자만 상호작용할 수 있고 인증 방식은 두 가지다
매일 스탠드업, 헬스 체크 같은 예약 작업을 팀 채널로 전달한다

시작하기 전에 다음을 준비합니다.

서버나 VPS에 설치된 Hermes Agent (봇이 계속 떠 있어야 하므로 노트북이 아니라 서버·VPS를 씁니다. 설치가 안 됐다면 설치 가이드를 먼저 따릅니다.)
봇 소유자 본인의 Telegram 계정
~/.hermes/.env에 설정된 LLM provider API 키(OpenAI, Anthropic 등 최소 하나)

월 5달러짜리 VPS로도 게이트웨이를 충분히 운영할 수 있습니다. Hermes 자체는 가볍고, 비용이 드는 건 원격으로 호출되는 LLM API 쪽입니다.

실습

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.

봇 명령 설정(선택 — 사용자에게 명령 메뉴를 보여줌)

/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을 고르고 봇 토큰을 붙여넣은 뒤, 물어보면 사용자 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는 숫자 값입니다(사용자 이름이 아닙니다).

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 전용: 부팅 시 시스템 서비스

# Linux — 기본 사용자 서비스 관리
hermes gateway start
hermes gateway stop
hermes gateway status

# 실시간 로그 보기
journalctl --user -u hermes-gateway -f

# SSH 로그아웃 후에도 계속 실행
sudo loginctl enable-linger $USER

# Linux 서버 — 명시적 시스템 서비스 명령
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

# macOS — 서비스 관리
hermes gateway start
hermes gateway stop
tail -f ~/.hermes/logs/gateway.log

동작 확인

hermes gateway status

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

4단계: 팀 접근 설정

팀원들에게 접근 권한을 주는 방법은 두 가지입니다.

방식 A: 정적 Allowlist

각 팀원의 Telegram 사용자 ID를 모아(@userinfobot에게 메시지를 보내게 하면 됩니다) 쉼표로 구분한 목록으로 추가합니다.

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

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

hermes gateway stop && hermes gateway start

방식 B: DM Pairing(팀에 권장)

DM pairing은 더 유연합니다. 사용자 ID를 미리 모을 필요가 없습니다. 동작 방식은 다음과 같습니다.

팀원이 봇에게 DM을 보냅니다. allowlist에 없으므로 봇은 1회용 pairing 코드로 응답합니다.

🔐 Pairing code: XKGH5N7P
Send this code to the bot owner for approval.

팀원이 그 코드를 (Slack, 이메일, 대면 등 아무 채널로나) 당신에게 보냅니다.
서버에서 승인합니다.

hermes pairing approve telegram XKGH5N7P

바로 사용 가능해집니다. 봇이 즉시 그 사람의 메시지에 응답하기 시작합니다.

Pairing 사용자 관리

# 대기 중/승인된 사용자 전체 보기
hermes pairing list

# 특정 사용자 접근 취소
hermes pairing revoke telegram 987654321

# 만료된 대기 코드 정리
hermes pairing clear-pending

DM pairing은 새 사용자를 추가할 때 게이트웨이를 재시작할 필요가 없어서 팀에 적합합니다. 승인은 즉시 반영됩니다.

보안 고려 사항

터미널 접근 권한이 있는 봇에는 GATEWAY_ALLOW_ALL_USERS=true를 절대 설정하지 않습니다. 봇을 찾은 누구나 서버에서 명령을 실행할 수 있게 됩니다.
Pairing 코드는 1시간 후 만료되며 암호학적으로 안전한 난수를 씁니다.
레이트 리밋으로 무차별 대입을 막습니다: 사용자당 10분에 1회, 플랫폼당 대기 코드 최대 3개.
승인 시도가 5회 실패하면 해당 플랫폼은 1시간 동안 잠깁니다.
모든 pairing 데이터는 chmod 0600 권한으로 저장됩니다.

5단계: 봇 설정

홈 채널 지정

홈 채널은 cron 작업 결과와 선제적 메시지가 전달되는 곳입니다. 지정하지 않으면 예약 작업이 보낼 곳이 없습니다.

옵션 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를 편집해 봇이 소통하는 방식을 바꿉니다. 자세한 내용은 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 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

컨텍스트 파일은 모든 세션의 system prompt에 주입됩니다. 글자 수 하나하나가 토큰 예산을 깎아먹으므로 간결하게 유지합니다.

6단계: 예약 작업 설정

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

일일 스탠드업 요약

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

매주 평일 오전 9시에 github.com/myorg/myproject 저장소를 확인해서
1. 지난 24시간 동안 열리거나 머지된 PR
2. 생성되거나 닫힌 이슈
3. main 브랜치의 CI/CD 실패 여부
를 짧은 스탠드업 형식으로 요약해줘.

에이전트가 자동으로 cron 작업을 만들고, 질문을 보낸 채팅(또는 홈 채널)에 결과를 전달합니다.

서버 헬스 체크

6시간마다 'df -h'로 디스크 사용량을, 'free -h'로 메모리를,
'docker ps'로 Docker 컨테이너 상태를 확인해줘. 파티션 사용량이 80%를 넘거나,
재시작된 컨테이너가 있거나, 메모리 사용량이 비정상적으로 높으면 알려줘.

예약 작업 관리

# CLI에서
hermes cron list          # 예약된 작업 전체 보기
hermes cron status        # 스케줄러 동작 여부 확인

# Telegram 채팅에서
/cron list                # 작업 보기
/cron remove <job_id>     # 작업 제거

프로덕션 팁

Docker로 안전하게

여러 명이 쓰는 팀 봇이라면 터미널 백엔드로 Docker를 써서 에이전트 명령이 호스트가 아니라 컨테이너 안에서 실행되게 합니다.

# In ~/.hermes/.env
TERMINAL_ENV=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

이렇게 하면 누군가 봇에게 파괴적인 명령을 요청해도 호스트 시스템은 보호됩니다.

게이트웨이 모니터링

# 게이트웨이가 실행 중인지 확인
hermes gateway status

# 실시간 로그 보기 (Linux)
journalctl --user -u hermes-gateway -f

# 실시간 로그 보기 (macOS)
tail -f ~/.hermes/logs/gateway.log

Hermes 최신 상태 유지

Telegram에서 봇에게 /update를 보내면 최신 버전을 받아 재시작합니다. 서버에서 직접 하려면,

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`
Pairing 데이터	`~/.hermes/pairing/`
세션 기록	`~/.hermes/sessions/`

Hermes에 입력할 프롬프트

지금 게이트웨이 설정을 점검해줘.
TELEGRAM_ALLOWED_USERS와 pairing 목록, 홈 채널, tool_progress 모드,
Docker 터미널 백엔드 사용 여부를 정리하고 보안상 허술한 부분이 있으면 알려줘.

체크리스트

봇 토큰을 .env에만 두고 노출하지 않았다.
GATEWAY_ALLOW_ALL_USERS=true를 쓰지 않았다.
정적 allowlist 또는 DM pairing 중 팀 규모에 맞는 방식을 골랐다.
게이트웨이를 서비스로 설치해 재부팅 후에도 살아남게 했다.
홈 채널과 tool progress 모드를 설정했다.
다중 사용자 환경이라면 Docker 터미널 백엔드로 격리했다.

팀 Telegram 어시스턴트

개요

핵심 개념

선택 기준

실습

1단계: Telegram 봇 만들기

2단계: 게이트웨이 설정

3단계: 게이트웨이 시작

4단계: 팀 접근 설정

5단계: 봇 설정

6단계: 예약 작업 설정

프로덕션 팁

Hermes에 입력할 프롬프트

체크리스트

다음 단계

관련 가이드

팀 Telegram 어시스턴트

개요

핵심 개념

선택 기준

실습

1단계: Telegram 봇 만들기

2단계: 게이트웨이 설정

3단계: 게이트웨이 시작

4단계: 팀 접근 설정

5단계: 봇 설정

6단계: 예약 작업 설정

프로덕션 팁

Hermes에 입력할 프롬프트

체크리스트

다음 단계

관련 가이드