Hermes Agent 실전: 텔레그램/더페이스/중소기업 위챗 전 플랫폼 AI 비서 구축

난이도: 중급 · 소요 시간: 약 20분 · 얻는 것: Hermes 전 플랫폼 접속 핵심 설정을 익히기

한 AI 비서가 텔레그램, 더페이스, 중소기업 위챗(WeCom) 안에서 동시에 돌아가는데, 배포는 딱 한 번만 하면 되는 걸 생각해 본 적 있나요? Hermes Agent라면 가능합니다.

Hermes Agent는 Nous Research가 오픈소스로 공개한 ‘자가 학습형’ AI Agent입니다. 그중 가장 큰 장점 중 하나는 전 플랫폼 메시지 게이트웨이가 내장돼 있다는 점이에요. 서버에서 프로세스 하나만 실행하면 Telegram, Discord, Slack, 더페이스(Feishu), 기업 위챗(WeCom), Signal, WhatsApp 등 10+ 메시지 플랫폼에 동시에 연결됩니다. 메시지는 자동으로 라우팅되고, 기억(메모리)은 플랫폼 간 공유되며, 한 번만 설정하면 영구적으로 적용됩니다.

오늘 글에서는 가장 자주 쓰는 세 플랫폼—Telegram, 더페이스( Lark ), 기업 위챗(WeCom)—을 전부 연결해 보겠습니다.

---

대상 독자

이 글은 아래 개발자에게 적합합니다.

• 리눅스/커맨드라인에 어느 정도 익숙하고, 서버에 AI Agent를 직접 호스팅하고 싶은 개발자
• 여러 플랫폼 메시지 접속이 필요한 독립 개발자 또는 소규모 팀
• Hermes Agent를 OpenClaw의 대안으로 평가 중인 팀

---

핵심 의존성 및 환경

---

전체 프로젝트 구조

hermes-agent/
├── scripts/
│   └── install.sh              # 원클릭 설치 스크립트
└── ~/.hermes/                   # 메인 설정 디렉터리(설치 후 자동 생성)
    ├── config.yaml              # 핵심 설정(모델, 툴킷)
    ├── .env                     # API Keys( Git에 올리지 마세요! )
    ├── skills/                  # 스킬 디렉터리
    ├── memory/                  # 영속 메모리
    ├── sessions/                # 세션 히스토리(FTS5 전체 텍스트 검색)
    └── gateway/                 # 게이트웨이 설정(각 플랫폼별 독립 YAML)
        ├── telegram.yaml
        ├── feishu.yaml
        └── wecom.yaml

---

단계별 진행

1단계: Hermes Agent 원클릭 설치

Linux / macOS / WSL2에서 공식 설치 스크립트를 실행합니다.

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

설치 스크립트가 Python, Node.js 및 모든 의존성을 자동으로 처리하므로, 전체 과정에서 수동 개입이 필요 없습니다. 설치가 끝나면 쉘을 다시 로드합니다.

source ~/.bashrc    # bash 사용자
source ~/.zshrc     # zsh 사용자

설치가 성공했는지 확인합니다.

hermes doctor

2단계: LLM Provider 설정—Defapi 연동

이제 Hermes에게 대형 모델을 어디서 가져올지 알려줘야 합니다. .env 파일에 API Key를 입력합니다.

hermes config set ANTHROPIC_API_KEY <your-defapi-key>

Defapi는 Anthropic의 v1/messages 인터페이스 프로토콜과 호환되므로 Hermes는 그대로 연동할 수 있습니다. 또한 hermes model 명령으로 대화형(인터랙티브)으로 모델과 Provider를 선택할 수도 있습니다.

hermes model
# 인터랙티브 선택:
# 1. Nous Portal
# 2. OpenRouter (200+ 모델)
# 3. OpenAI
# 4. Defapi / 커스텀 엔드포인트
# 5. 기타...

Defapi를 사용한다면, 인터랙티브 메뉴에서 커스텀 엔드포인트(Custom)를 선택하고 아래를 입력합니다.

API Endpoint: https://api.defapi.org
Model: anthropic/claude-opus-4.6

3단계: 첫 번째 플랫폼 연결—Telegram Bot

Telegram은 Bot API가 공개되어 있어 기업 인증이 필요 없기 때문에, 가장 쉽게 검증할 수 있는 플랫폼입니다.

3.1 Bot 생성

텔레그램에서 @BotFather를 찾아 /newbot을 전송한 뒤, 안내에 따라 Bot 이름을 짓고 BOT_TOKEN을 발급받습니다. 형식은 123456789:ABCdefGHIjklMNOpqrsTUVwxyz처럼 생겼습니다.

3.2 Hermes 게이트웨이 설정

hermes gateway setup
# telegram 선택 후 인터랙티브 설정으로 진입

또는 ~/.hermes/gateway/telegram.yaml을 직접 생성합니다.

platform: telegram
enabled: true
bot_token: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

# 접근 제어: 특정 사용자만 허용
allowed_users:
  - your_telegram_username

# 보안 설정
require_approval_for_dangerous_tools: true

3.3 검증

게이트웨이를 시작한 뒤 Bot에게 메시지를 보냅니다.

hermes gateway start
# 또는 백그라운드 실행:
hermes gateway start --daemon

텔레그램에서 Bot에게 /new를 보내면 환영 메시지를 응답해야 합니다. 예를 들어 "안녕하세요" 같은 한국어 메시지를 보내보고, AI가 반응하는지 확인해 보세요.

4단계: 더페이스(Feishu/Lark) 연결—기업 앱

더페이스 연동은 조금 더 복잡합니다. 더페이스 오픈 플랫폼에서 ‘기업 자체 구축 앱’을 생성해야 합니다.

4.1 더페이스 오픈 플랫폼에서 앱 생성

1. 더페이스 오픈 플랫폼을 열고 ‘기업 자체 구축 앱’을 생성합니다.
2. 「자격증명 및 기본 정보」에서 App ID와 App Secret을 가져옵니다.
3. 「로봇」 기능을 활성화합니다.

4.2 이벤트 구독 설정

앱의 「이벤트 구독」에서 다음을 설정합니다.

• 요청 주소 URL: https://你的域名/gateway/feishu/webhook
• 이벤트 선택: im.message.receive_v1 (메시지 수신)

4.3 기업에 앱 설치

「버전 관리 및 배포」에서 버전을 생성하고 배포하세요. 그렇지 않으면 Bot이 메시지를 받을 수 없습니다.

4.4 Hermes 게이트웨이 설정

hermes gateway setup
# feishu 선택 후 인터랙티브로 App ID와 App Secret 입력

~/.hermes/gateway/feishu.yaml을 직접 편집합니다.

platform: feishu
enabled: true
app_id: "cli_xxxxxxxxxxxxxx"
app_secret: "xxxxxxxxxxxxxxxxxxxx"
verification_token: "your_verification_token"

# 메시지 암호화(선택이지만 권장)
encrypt_key: "your_encrypt_key"

# 허용되는 그룹/사용자
allowed_chats: []
require_mention: false

4.5 검증

더페이스에서 Bot에게 /new를 보내 반응이 있는지 확인합니다. 더페이스의 메시지 포맷은 Telegram과 다르지만, Bot은 리치 텍스트 메시지 카드를 지원하며 Hermes가 자동으로 맞춰줍니다.

5단계: 기업 위챗(WeCom) 연결

기업 위챗은 더페이스와 유사하게 콜백 Webhook 모드를 통해 연동합니다.

5.1 기업 위챗 관리 백오피스에서 앱 생성

1. 기업 위챗 관리 백오피스에 로그인합니다.
2. 「앱 관리」→「앱 생성」→ 「기업 자체 구축」을 선택합니다.
3. AgentId, Secret, 그리고 기업 CorpId를 가져옵니다.
4. 「기업 신뢰 IP」를 서버 IP로 설정합니다.

5.2 메시지 수신 설정

앱 설정에서 「메시지 수신」 모드를 활성화합니다.

• URL 입력: https://你的域名/gateway/wecom/webhook
• 「호환 모드」 또는 「이벤트 모드」 선택

5.3 Hermes 게이트웨이 설정

# ~/.hermes/gateway/wecom.yaml
platform: wecom
enabled: true
corp_id: "wwxxxxxxxxxxxxxx"
agent_id: "1000001"
corp_secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
encrypt_mode: "safe"    # 안전 모드는 encoding_aes_key 설정이 필요
encoding_aes_key: "your_32_char_aes_key"

5.4 검증

기업 위챗에서 앱을 찾아 메시지를 보내 테스트합니다.

6단계: 게이트웨이 시작—한 번에 세 플랫폼 모두 구동

모든 플랫폼 설정을 마쳤다면 한 가지 명령으로 게이트웨이를 시작합니다.

hermes gateway start

Hermes는 ~/.hermes/gateway/ 아래의 모든 활성화된 플랫폼 설정을 자동으로 불러오고, 모든 어댑터를 동시에 시작합니다. 특정 플랫폼이 실패하더라도(예: Token 오류) 다른 플랫폼의 정상 동작에는 영향을 주지 않습니다.

hermes gateway status로 각 플랫폼의 실행 상태를 확인합니다.

Platform  Status   Users   Messages
telegram  ● online   3         142
feishu    ● online   7          89
wecom     ● online   2          15

Ctrl+C로 게이트웨이를 중지하거나, --daemon 옵션으로 백그라운드 실행합니다.

hermes gateway start --daemon

7단계: 멀티 플랫폼 메시지 검증

이제 세 플랫폼 각각에서 Bot에게 메시지를 보내 테스트할 수 있습니다.

# Telegram
/new
안녕하세요, 자기소개를 해줄래요?

# 더페이스
/new
너는 누구야?

# 기업 위챗
/new
내가 도와줄 일이 있어?

세 곳의 응답은 완전히 일치하며, 메모리가 공유됩니다. Telegram에서 했던 이야기라면 더페이스와 기업 위챗에서도 모두 알게 됩니다. 이것이 Hermes의 가장 핵심 가치입니다: 한 번 구성, 전 플랫폼에서 동일한 통합 경험.

---

자주 묻는 문제 해결

1. Telegram Bot이 메시지를 받지 못함

증상: Bot이 전혀 응답하지 않으며, 로그에도 아무 기록이 없습니다.

확인 단계:

# 1. Token이 맞는지 확인
hermes config get telegram.bot_token

# 2. 포트가 점유 중이 아닌지 확인
ss -tlnp | grep 8080

# 3. webhook 모드를 사용했다면 Telegram Bot API 설정 확인
# Webhook URL은 공용으로 접근 가능해야 합니다. 로컬 개발에는 ngrok으로 터널링
ngrok http 8080

# 4. webhook 재설정(가끔 Bot이 이전 webhook에 걸려 있음)
curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/deleteWebhook"

2. 더페이스 콜백 검증 실패

증상: 더페이스 오픈 플랫폼에 「콜백 URL 검증 실패」가 표시됩니다.

확인 단계:

# 1. 공용 URL이 접근 가능한지 확인
curl -X GET "https://your-domain.com/gateway/feishu/webhook"

# 2. 더페이스 서명 검증 확인
# 더페이스는 AES 암호화를 사용하므로 encrypt_key는 백오피스 설정과 일치해야 합니다
# Hermes 로그 확인:
hermes logs --platform feishu

3. 기업 위챗 메시지 무응답

증상: 메시지를 보내도 아무 응답이 없고, 로그에도 기록이 없습니다.

확인 단계:

# 1. CorpId / AgentId / Secret이 정확한지 확인
# 2. 가장 중요: IP 화이트리스트 확인
# 기업 위챗은 API를 호출하는 서버 IP가 신뢰 IP 목록에 있어야 합니다

# 3. AccessToken 테스트
curl "https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=wwxxx&corpsecret=secret"

# 응답이 "errmsg": "ip not in whitelist"라면 IP가 화이트리스트에 없습니다

4. 모델이 응답하지 않음

증상: Bot이 메시지는 받았는데 AI가 답하지 않고 계속 thinking만 표시됩니다.

확인 단계:

# 1. API Key가 유효한지 테스트
curl -X POST "https://api.defapi.org/api/v1/messages" \
  -H "Authorization: Bearer <your-key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-opus-4.6","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'

# 2. 모델 설정 확인
hermes config get model

# 3. fallback_providers(권장 설정) 확인
# ~/.hermes/config.yaml에 백업 Provider를 추가합니다.
fallback_providers:
  - provider: openrouter
    api_key: "${OPENROUTER_API_KEY}"

5. 도구 실행 오류

증상: Bot이 특정 작업을 실행할 수 없다고 답합니다.

확인 단계:

# 1. 현재 활성화된 툴셋 확인
hermes tools

# 2. 필요한 툴셋 활성화
hermes tools enable web_search
hermes tools enable terminal

# 3. 위험 명령은 수동 확인 필요
# 설정 확인:
hermes config get approval_required
# true로 설정하면 모든 위험 명령에 대해 당신이 직접 승인해야 합니다

6. 멀티 플랫폼 동시성 충돌

증상: 어떤 플랫폼에서 메시지를 받으면 다른 플랫폼들은 응답하지 않습니다.

확인 단계:

Hermes v0.6.0의 token-lock 메커니즘은 두 플랫폼 인스턴스가 동일한 Bot Token을 사용하면서 충돌하는 것을 막아줍니다. 다만 여러 대의 머신에서 동일한 Bot의 여러 인스턴스를 돌리고 있다면 이 문제가 발생할 수 있습니다.

# Hermes 게이트웨이 인스턴스가 하나만 실행 중인지 확인
ps aux | grep hermes
pkill -f hermes-agent

# 그리고 다시 시작
hermes gateway start

---

추가 읽기 / 고급 방향

OpenClaw에서 마이그레이션

이미 OpenClaw을 사용 중이라면 Hermes는 공식 마이그레이션 도구를 제공합니다. SOUL.md, MEMORY.md, Skills, API Keys, 그리고 메시지 플랫폼 설정을 자동으로 가져올 수 있습니다.

hermes claw migrate              # 인터랙티브 전체 마이그레이션
hermes claw migrate --dry-run    # 먼저 미리보기
hermes claw migrate --preset user-data  # 민감 정보는 마이그레이션하지 않음

MCP Server 모드

Hermes v0.6.0에는 MCP Server 기능이 새로 추가되었습니다. 한 번의 명령으로 Hermes가 외부에 툴을 노출하게 만들 수 있습니다.

hermes mcp serve
# stdio와 Streamable HTTP 두 가지 전송 프로토콜을 지원

연결 후 Cursor, VS Code, Zed 같은 IDE가 MCP 프로토콜을 통해 Hermes의 모든 툴과 대화 기능을 호출할 수 있습니다.

커스텀 스킬 시스템

Hermes의 Skills 시스템은 자연어 설명만으로 스킬을 자동 생성할 수 있습니다. 직접 작성할 수도 있습니다.

# 기존 스킬 확인
hermes skills

# Skills Hub(커뮤니티 스킬 마켓) 둘러보기
/skills

# agentskills.io에서 커뮤니티 스킬 설치

Cron 정기 작업

자연어로 정기 작업을 설정하면 Hermes가 자동으로 실행하고 결과를 원하는 어떤 플랫폼이든 푸시합니다.

# 매일 오전 8시에 Telegram으로 날씨 리포트를 전송
/cron "Every day at 8am, summarize today's weather and send to me" --platform telegram

---

결론

Hermes Agent의 전 플랫폼 게이트웨이 설계는 매우 우아합니다. 한 가지만 설정을 관리하면, 동일한 Agent 인스턴스를 어떤 메시지 플랫폼에서든 돌릴 수 있습니다. 메모리는 플랫폼 간 공유되고, 설정은 한 번으로 끝나며, 여러 개의 독립 Bot을 따로 운영하는 것보다 리소스 점유도 훨씬 적습니다.

여전히 OpenClaw을 쓰고 있거나, 진짜 ‘제대로 하는’ 오픈소스 AI Agent를 찾고 있다면 Hermes에 20분만 투자해 볼 만합니다. Defapi의 반값 Claude Opus 4.6과 함께하면, 매월 비용을 기존의 50%까지 줄이면서도 체감 경험은 전혀 줄어들지 않습니다.