먼저, 무엇을 만드는가
Telegram 자체에 AI가 들어가는 것이 아닙니다. MacBook에서 Hermes Gateway가 실행되면서 전용 봇의 메시지를 받아 모델과 로컬 도구를 호출합니다.
MacBook → Hermes Gateway(launchd) → 전용 Telegram 봇 → 본인 숫자 ID만 허용 → 이 DM을 홈 채널로 지정 → GitHub 저장소를 Claude Code와 Hermes가 함께 사용
이 방식이 좋은 이유
- 휴대폰에서 언제든 업무 요청 가능
- Mac의 파일과 개발도구를 그대로 사용
- Claude Code와 GitHub 작업을 이어받을 수 있음
- 대화·메모리·예약작업이 연결됨
알아둘 한계
- Mac이 꺼지거나 잠자기 상태면 봇이 멈춤
- 봇 토큰이 유출되면 즉시 폐기해야 함
- 허용 사용자 설정 없이 사용하면 안 됨
- 두 AI가 동시에 같은 파일을 수정하지 않게 역할을 나눠야 함
MacBook 준비
WSL이나 Ubuntu는 필요하지 않습니다. macOS의 기본 Terminal에서 바로 설치합니다.
Terminal 열기
Command + Space로 Spotlight를 열고 “Terminal”을 검색합니다.
uname -s uname -m
Darwin이면 macOS입니다. arm64는 Apple Silicon, x86_64는 Intel Mac입니다. 공식 설치 스크립트가 환경에 맞게 처리합니다.Git 준비
GitHub로 Claude Code와 Hermes 작업을 연결할 때 필요합니다.
git --version xcode-select --install
Mac에 Hermes Agent 설치
공식 문서는 macOS·Windows에서는 Hermes Desktop 설치를 권장합니다. 터미널 중심으로 사용할 경우 아래 CLI 설치도 공식 지원됩니다.
방법 A · Hermes Desktop
공식 사이트에서 macOS 설치 파일을 내려받아 실행합니다. 처음 설치하는 동생분에게 가장 쉬운 방법입니다.
방법 B · CLI 설치
Claude Code와 GitHub를 자주 오간다면 Terminal에서 CLI로 사용하는 방식이 편합니다.
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash source ~/.zshrc
hermes --version hermes doctor
GPT 모델 연결
우리가 사용하는 것처럼 OpenAI Codex OAuth를 선택하면 API 키를 채팅에 붙이지 않고 브라우저 기기 인증으로 로그인할 수 있습니다.
모델 선택기 실행
메뉴에서 OpenAI Codex를 선택하고 화면에 나온 인증 절차를 완료합니다.
hermes model
Telegram을 연결하기 전에 CLI부터 확인합니다.
hermes chat -q "현재 운영체제와 작업 폴더를 실제로 확인해줘"
Telegram 전용 봇 생성
기존 사람 계정을 연결하는 것이 아니라 Telegram 공식 @BotFather에서 동생분 전용 봇을 새로 만듭니다.
BotFather에서 /newbot
Telegram에서 아래 순서로 진행합니다.
| 순서 | 입력 | 설명 |
|---|---|---|
| 1 | @BotFather | 파란 인증 마크가 있는 공식 계정 확인 |
| 2 | /newbot | 새 봇 만들기 |
| 3 | 표시 이름 | 예: 동생 Hermes |
| 4 | 사용자 이름 | 반드시 bot으로 끝나야 함 |
| 5 | 발급 토큰 | 복사하되 누구에게도 전송하지 않음 |
/revoke로 폐기하고 새 토큰을 발급합니다.본인의 숫자 User ID 확인
Telegram 사용자 이름(@아이디)이 아니라 숫자로 된 고유 ID가 필요합니다. 이 값으로 동생분만 봇을 사용할 수 있게 막습니다.
@userinfobot에 메시지 보내기
@userinfobot이 돌려주는 숫자 ID를 메모합니다.
123456789를 그대로 쓰면 안 됩니다. 반드시 동생분 본인의 실제 숫자 ID를 입력하세요.Hermes Gateway에 Telegram 연결
우리가 사용한 핵심 설정은 TELEGRAM_BOT_TOKEN, TELEGRAM_ALLOWED_USERS, 그리고 이후 설정되는 TELEGRAM_HOME_CHANNEL입니다.
대화형 설정 마법사 사용
수동 편집보다 마법사를 권장합니다. Telegram을 선택하고 BotFather 토큰과 본인의 숫자 User ID를 입력합니다.
hermes gateway setup
~/.hermes/.env에 저장됩니다. 정상적인 결과는 아래 세 변수 구조이며 실제 값은 절대 공개하지 않습니다.TELEGRAM_BOT_TOKEN=[BotFather에서 받은 비밀 토큰] TELEGRAM_ALLOWED_USERS=[내 숫자 User ID] TELEGRAM_HOME_CHANNEL=[/sethome 후 저장되는 채널 ID]
비밀 파일 권한을 제한합니다.
chmod 600 ~/.hermes/.env
먼저 포그라운드로 연결 테스트
서비스 설치 전에 눈에 보이는 상태에서 테스트합니다.
hermes gateway run
터미널을 닫지 않은 상태에서 새 봇의 Telegram DM을 열고 /start 또는 “안녕”을 보냅니다.
Ctrl+C로 Gateway를 종료합니다.Mac에서 Gateway 상시 실행
Hermes의 공식 서비스 설치 명령은 macOS에서 LaunchAgent를 구성합니다. Linux의 systemd나 WSL 설정은 필요하지 않습니다.
LaunchAgent 설치·시작
포그라운드 테스트가 성공한 다음 실행합니다.
hermes gateway install hermes gateway start hermes gateway status
hermes gateway restart를 실행합니다.로그인·잠자기 조건 이해
LaunchAgent는 해당 Mac 사용자 로그인 세션에서 자동으로 실행됩니다. Mac을 재시동하면 로그인한 뒤 상태를 확인하세요.
hermes gateway status hermes gateway restart
형의 Windows 구성과 다른 점
형은 Windows 11 → WSL2 → systemd를 사용하지만, 동생분은 macOS → LaunchAgent를 사용합니다. Telegram·모델·Gateway 명령은 같고 상시 실행 방식만 다릅니다.
이 Telegram DM을 홈 채널로 지정
우리 방식에서는 예약작업과 자동 알림이 현재 DM으로 돌아오도록 홈 채널을 설정했습니다.
봇 DM에서 /sethome
동생분의 Hermes 봇과 1:1 대화방에서 아래 명령을 보냅니다.
/sethome
확인용 명령도 실행합니다.
/status
origin 또는 홈 채널로 설정하면 결과가 이 Telegram 대화로 옵니다.Claude Code · GitHub · Hermes를 오가는 법
세 도구를 경쟁시키지 말고 역할을 나눕니다. GitHub를 공통 기준점으로 두고 한 번에 한 AI만 같은 작업 브랜치를 수정하는 것이 핵심입니다.
| 도구 | 잘 맡는 일 | 산출물 |
|---|---|---|
| Claude Code | 긴 구현, 대규모 리팩터링, 여러 파일을 오가는 코딩 | 코드·테스트·커밋 |
| Hermes · GPT | 최신 조사, 요구사항 정리, 실행·검증, 브라우저 QA, 문서화, 운영 자동화 | 검증 결과·문서·자동화·리뷰 |
| GitHub | 두 AI가 공유하는 원본, 변경 이력, 이슈와 PR | 재현 가능한 상태 |
| Telegram | 밖에서 지시, 진행 확인, 결과·예약 알림 수신 | 모바일 업무 창구 |
공통 규칙을 저장소에 둔다
프로젝트 루트의 AGENTS.md와 CLAUDE.md에 실행법·금지사항·검증 기준을 기록합니다. 공통 내용은 docs/AI_WORKFLOW.md 한 곳에 두고 두 파일에서 참고하게 하면 기준이 덜 갈립니다.
# 작업 전 - git status와 최신 브랜치를 확인한다. - 기존 변경을 덮어쓰지 않는다. # 완료 기준 - 관련 테스트·빌드·린트를 실행한다. - 변경 파일과 검증 결과를 보고한다. - 비밀값과 .env는 커밋하지 않는다.
인계는 commit · push로 한다
한 AI의 작업이 끝난 뒤 검증하고 커밋·푸시한 다음 다른 AI가 이어받습니다.
git status # 변경이 없을 때만 다음 명령 실행 git pull --rebase git log -3 --oneline # AI 작업 및 테스트 후 git status git add [확인한 파일] git commit -m "type: 작업 요약" git push
실제 인계 요청 예시
“알아서 해줘”보다 저장소·기준·검증을 함께 말하면 결과가 훨씬 안정적입니다.
[저장소 경로]에서 최신 변경을 확인해줘. Claude Code가 방금 구현한 내용을 git diff와 최근 커밋으로 파악하고, 관련 테스트·빌드·브라우저 검증을 실제로 실행해. 문제가 있으면 수정 후 다시 검증하고, 변경점과 근거를 짧게 보고해줘.
먼저 CLAUDE.md와 docs/AI_WORKFLOW.md를 읽고 git status를 확인해. Hermes가 정리한 요구사항 문서를 기준으로 구현하되 기존 변경을 보존해. 관련 테스트를 실행하고 변경 파일·검증 결과를 보고해. 커밋은 확인 후 진행해.
Hermes를 실전에서 잘 쓰는 활용법
Hermes의 강점은 답변만 하는 것이 아니라 Mac의 도구를 사용해 조사 → 실행 → 검증 → 전달까지 이어가는 데 있습니다.
1. 최신 조사와 의사결정
공식 자료를 우선 확인하고 사실·추론·의견을 분리한 보고서를 만듭니다.
이 주제를 최신 공식 자료 중심으로 조사해. 확인된 사실과 불확실한 부분을 나누고, 선택지·장단점·추천안을 표로 정리해줘. 출처 링크와 확인 날짜도 포함해.
2. Claude Code 결과의 2차 검증
다른 모델이 만든 코드를 GPT 관점에서 리뷰하고 실제 테스트까지 맡깁니다.
최근 커밋을 리뷰해줘. 버그·보안·회귀 위험을 우선순위로 나누고, 관련 테스트를 실제 실행해. 문제가 확인된 경우에만 최소 수정 후 재검증해.
3. 이동 중 프로젝트 운영
Telegram에서 상태 확인, 로그 점검, 안전한 수정과 결과 수신을 할 수 있습니다.
[프로젝트 경로]의 git 상태와 실행 중인 서비스를 확인해줘. 오류 로그가 있으면 원인을 조사하되, 데이터 삭제·배포·push는 내 승인 전에는 하지 마. 확인 결과와 다음 행동만 간단히 알려줘.
4. 반복 업무 예약
뉴스 요약, 가격·사이트·대시보드 점검을 예약하고 결과를 Telegram으로 받습니다.
매주 월요일 오전 9시에 [주제]의 최신 소식을 조사해. 중복을 제외한 핵심 5개와 업무 영향만 요약하고, 출처 링크와 함께 이 Telegram 대화로 보내줘.
5. 문서·회의·콘텐츠 정리
자료를 읽고 세부사항과 숫자를 보존한 공유용 문서로 바꿉니다.
[파일 경로]의 회의 메모를 읽고 결정사항·근거·담당자·마감일·미해결 질문으로 정리해. 추측은 쓰지 말고 공유용 Markdown 파일로 저장한 뒤 다시 읽어 검증해.
6. 데이터·파일 일괄 처리
CSV 분석, 파일명 정리, 보고서 생성처럼 반복적인 로컬 작업을 실행합니다.
[CSV 경로]를 분석해 결측치와 이상치를 먼저 확인해. 핵심 지표와 변화 원인을 표·차트로 만들고, 계산은 코드로 검증해 결과 파일을 outputs 폴더에 저장해.
목표 + 입력 위치 + 반드시 지킬 조건 + 원하는 결과물 + 검증 방법. 위험한 변경은 “승인 전 실행 금지”를 명시합니다.
완료라고 판단하는 최종 테스트
단순히 봇이 “안녕”에 답하는 것만으로 끝내지 않고, Mac 도구와 GitHub 인계까지 확인합니다.
| 테스트 | Telegram에서 보낼 문장 | 성공 기준 |
|---|---|---|
| 일반 대화 | “너의 역할을 세 줄로 알려줘” | 정상 답변 |
| Mac 확인 | “현재 운영체제를 실제로 확인해줘” | macOS 확인 근거 제시 |
| 파일 작업 | “홈 폴더의 파일 하나를 읽고 요약해줘” | Mac 파일시스템 접근 |
| GitHub 인계 | “저장소의 최근 커밋과 현재 상태를 확인해줘” | Git 근거를 포함한 답변 |
| 세션 | /new 후 새 질문 | 새 대화가 분리됨 |
| 재시작 | Gateway 재시작 후 메시지 | 다시 정상 응답 |
| 접근제어 | 허용되지 않은 계정으로 DM | 실행되지 않음 |
hermes doctor hermes gateway status hermes status --all hermes sessions list
보안과 문제 해결
반드시 지킬 것
- Bot Token은
~/.hermes/.env에만 저장 TELEGRAM_ALLOWED_USERS는 반드시 설정.env를 GitHub에 커밋하지 않기- 위험 명령 승인은 내용을 읽고 결정
- 배포·삭제·push는 범위를 확인한 뒤 실행
평소 관리 명령
hermes update— 업데이트hermes doctor— 진단hermes gateway restart— 재시작hermes gateway status— 상태tail -n 100 ~/.hermes/logs/gateway.log— 최근 로그
| 증상 | 확인할 것 | 조치 |
|---|---|---|
| 봇이 완전히 무응답 | Gateway 상태·토큰·Mac 잠자기 | hermes gateway status → restart |
| unauthorized 표시 | 숫자 User ID | TELEGRAM_ALLOWED_USERS 수정 |
| 재시동 후 무응답 | Mac 로그인·LaunchAgent 상태 | 로그인 → Gateway restart |
| Git 충돌 | 두 AI의 동시 수정 여부 | 작업 중단 → 변경 보존 → 브랜치 분리 |
| 모델 오류 | OAuth·모델 선택 | hermes model 재인증 |
| 토큰 유출 | 노출 위치 | BotFather /revoke 후 새 토큰 입력·restart |
실제 Bot Token, 실제 API 키, OAuth 토큰,
~/.hermes/.env 전체 내용, 인증코드, 개인 Telegram 숫자 ID가 포함된 설정 파일.최종 완료 체크리스트
이제 동생분은 Telegram에서 MacBook의 Hermes에게 조사·파일·코드·자동화 작업을 요청하고, Claude Code 작업을 GitHub로 이어받을 수 있습니다.