WeCom 콜백 모드 — 사용자 지정 앱 | Easy Understand Hermes Agent

WeCom 콜백 모드 — 커스텀 앱

AI 비서 전용 사무실 사서함을 하나 만든다고 생각해 보세요. 단체 채팅방에 숨어 있지 않고, 사람들이 직접 와서 메시지를 남길 수 있는 자기 책상이 생기는 거죠.

뭐가 그렇게 다른데?

Hermes Agent는 WeCom(기업용 위챗)에 연결하는 두 가지 방법을 제공합니다. 봇(Bot) 모드는 단체 채팅방에 참여하는 친근한 어시스턴트 같아서 설정은 빠르지만 기능이 제한적이에요. 콜백(Callback) 모드는 다릅니다. 직원들의 WeCom 사이드바에 공식 앱처럼 표시되는 커스텀 앱을 직접 만드는 거예요. 네이티브한 느낌을 주고, 여러 회사를 지원하며, 암호화된 메시지를 안전하게 처리합니다.

대신 단점이 하나 있어요. 메시지를 받으려면 공개 서버가 필요합니다. 하지만 걱정 마세요. 테스트용으로는 ngrok 같은 간단한 터널이면 충분하니까요.

실제 동작 방식

동작 흐름을 쉽게 설명하면 이렇습니다.

누군가 WeCom에서 커스텀 앱으로 메시지를 보냅니다.
WeCom은 메시지를 암호화해서 서버의 HTTP 엔드포인트로 전송합니다.
Hermes가 메시지를 복호화하고, AI 에이전트를 위한 큐에 넣은 후, 즉시 WeCom에 “수신 완료” 응답을 보냅니다. (조용히요. 사용자는 아직 아무것도 볼 수 없어요.)
에이전트가 작업에 따라 3~30분 동안 생각합니다.
Hermes가 WeCom 메시지 API를 사용해 답변을 능동적으로 보냅니다.

폴링도, 지연도 없습니다. 깔끔하고 비동기적인 대화 방식이에요.

단계별 설정 가이드

1. WeCom 관리 콘솔에서 앱 만들기

WeCom 관리 콘솔에 로그인해서 애플리케이션 → 앱 생성으로 이동합니다.
콘솔 상단에 있는 Corp ID를 기록하고 Corp Secret을 생성하세요.
앱 개요 페이지에서 Agent ID를 확인합니다.

메시지 수신 섹션에서 다음을 설정하세요.

URL: http://YOUR_PUBLIC_IP:8645/wecom/callback
Token: 임의의 값 생성
EncodingAESKey: 43자리 키 생성

2. 환경 변수 설정

.env 파일에 다음 항목을 추가하세요.

WECOM_CALLBACK_CORP_ID = your-corp-id
WECOM_CALLBACK_CORP_SECRET = your-corp-secret
WECOM_CALLBACK_AGENT_ID = 1000002
WECOM_CALLBACK_TOKEN = your-callback-token
WECOM_CALLBACK_ENCODING_AES_KEY = your-43-char-aes-key

# 선택 사항
WECOM_CALLBACK_PORT = 8645
WECOM_CALLBACK_ALLOWED_USERS = user1,user2

3. 게이트웨이 시작

hermes gateway

참고: hermes gateway install로 서비스를 등록한 후에만 hermes gateway start를 사용하세요.

콜백 어댑터는 8645 포트에서 HTTP 서버를 시작합니다. WeCom은 GET 요청으로 URL을 검증한 후, POST 요청으로 메시지를 보내기 시작합니다.

설정 참조

config.yaml의 platforms.wecom_callback.extra에서도 설정할 수 있습니다.

설정 항목	기본값	설명
`corp_id`	—	필수. WeCom Corp ID
`corp_secret`	—	필수. 앱 시크릿
`agent_id`	—	필수. 앱의 Agent ID
`token`	—	필수. 콜백 검증 토큰
`encoding_aes_key`	—	필수. 43자리 AES 키
`host`	미설정 (듀얼 스택)	HTTP 서버 바인딩 주소
`port`	8645	콜백 서버 포트

마무리

WeCom 콜백 모드는 Hermes를 기업 워크플로우에 통합하는 “공식적인” 방법입니다. 봇 모드보다 설정이 더 필요하지만, 그만큼 사용자에게 세련되고 일급(first-class) 앱 경험을 제공합니다.

실용적인 팁: 실제 서버를 공개하기 전에 ngrok으로 시작해 보세요. ngrok http 8645를 실행하고, WeCom 콘솔에 해당 URL을 입력한 후, 단일 사용자로 테스트해 보세요. 정상 동작하면 프로덕션 서버로 전환하고 WECOM_CALLBACK_ALLOWED_USERS를 팀원으로 제한하세요. 즐거운 개발 되세요!