【#8】Hermes Agent 분석하기

연재 「Hermes Agent 분석하기」 제8회.

지금까지 살펴본 코어(대화 루프, 기억, 도구, 병렬)는 그 자체로는 사용자의 눈에 띄지 않는다. 제1회에서 "하나의 코어를 다면적으로 노출한다"라고 썼던 그 "다면"을 이번에 정리하여 점검한다. 채팅 측면과 그 외를 합치면 40개가 넘는 노출면이 있다. 다만 세는 방식에 함정이 있으므로, 그 부분까지 포함하여 정리한다.

연결층의 중심은 Gateway (gateway/run.py, 19,741행)이다. 이것은 "소비자형"——외부에서 오는 메시지를 소비하고, 코어에 전달하며, 응답을 반환하는 루프다. 세 개의 입구를 가진다.

• 메시지 소비— 각 채팅 플랫폼으로부터의 수신
• OpenAI 호환 API— 127.0.0.1:8642 (루프백 바인딩. 실제 코드에서 확인 완료)
• Webhook— 0.0.0.0:8644, HMAC 서명 포함 (모든 인터페이스에 바인딩)

포트 바인딩 대상의 차이에 주목해 주길 바란다. API 서버는 127.0.0.1 (로컬호스트 한정)이며, Webhook은 0.0.0.0 (모든 NIC)이다. Webhook은 외부 서비스로부터의 콜백을 받는 성질상 외부로 개방할 필요가 있으며, 그 대신 HMAC 서명으로 정당성을 검증한다. OpenAI 호환 API는 로컬로 한정하여, 실수로 외부 공개를 하지 않도록 기본 설정되어 있다. 이는 제10회의 "공개 바인딩" 리스크와 직결되는 설계다.

Gateway는 추가로 128 세션 LRU (idle TTL 1시간)로 세션을 다중화하며, 신규 접속에는 페어링 (Pairing) (단말 인증. 코드 docstring 상으로는 OWASP / NIST 가이드라인을 참조, gateway/pairing.py:8)을 요구한다. 페어링에는 rate limit (10분당 1회)과 lockout (1시간 내 5회 실패 시 차단), 자격 증명 파일은 0600, TTL 1시간과 같은 보호 조치가 적용된다.

채팅 플랫폼은 크게 두 계통이다.

• 코어 표 15— telegram / slack / signal / wecom / matrix 등 코어 측에 정의된 15면
• plugins/platforms/의 8면— discord / teams / line 등 플러그인 측의 8면

합쳐서 23~24면 정도가 실제 수치에 가깝다.

여기서 세는 방식의 주의점. gateway/config.py의 Platform enum은 21개 항목이 있지만, 여기에는 LOCAL (로컬 실행)이나 API / Webhook 계열도 포함된다. 즉, enum의 항목 수를 "채팅 대응 수"라고 그대로 읽으면 오해하게 된다. enum은 "노출면의 후보 수"이지, 순수한 채팅 플랫폼 수가 아니다. 마찬가지로 gateway/platforms/ 직하의 파일 수도 보조 모듈을 포함하므로, 전부를 "어댑터"라고 세어서는 안 된다. 골자의 FACTCHECK에서도 반복해서 강조하고 있는 부분이다.

채팅 이외의 노출면도 풍부하다. 입구와 트랜스포트(Transport)로 정리한다.

인터페이스	입구 / 실체	트랜스포트 (Transport)	주요 용도
CLI	hermes (hermes_cli/main.py)	TTY	터미널에서의 대화 / 원샷 (One-shot)
TUI	hermes --tui / tui_gateway/	stdio JSON-RPC	리치 터미널 UI
Web / Desktop	hermes dashboard (127.0.0.1:9119) / Electron	HTTP/WS	브라우저 / 네이티브 창
ACP	acp_adapter/	stdio JSON-RPC	에디터 연동 (Zed 등)
MCP	mcp_serve.py	stdio (MCP)	Claude Code / Cursor로 대화·도구 공개
OpenAI 호환 API	gateway/platforms/api_server.py	HTTP 127.0.0.1:8642	Open WebUI 등의 프론트
Webhook	gateway/platforms/webhook.py	HTTP 0.0.0.0:8644 (HMAC)	GitHub/GitLab 등
Proxy	hermes proxy	HTTP 로컬	외부 앱의 OpenAI 요청 전달
Cron	cron/scheduler.py	시간 기반 실행	정기 실행 (제9회)
Voice	tools/voice_mode.py	음성 I/O	음성 입출력 루프
Computer-use	tools/computer_use_tool.py	cua-driver	macOS 데스크톱 조작 (제5회)

이것들을 합치면 비채팅 계열만 약 20개다. 채팅 23~24개를 더하면 Hermes의 노출면은 40개가 넘는다. "인간용 UI (CLI/TUI/Web/Desktop)", "프로그래매틱 (ACP/MCP/API/Webhook/Proxy)", "자율·트리거 (Cron/Voice/Computer-use)"의 3개 그룹으로 나누어 파악하면 전망이 좋다.

이 설계의 묘미는, 동일한 코어를 ACP·MCP·OpenAI 호환 API를 통해 동시에 공개할 수 있다는 점에 있다. 에디터에서는 ACP로, Claude Code에서는 MCP로, 자체 제작 앱에서는 OpenAI 호환 API로—모두 배후에서는 동일한 대화 루프, 동일한 기억, 동일한 도구군을 호출한다. 인터페이스마다 로직을 다시 작성할 필요가 없다. 코어와 노출면을 철저하게 분리한 결과다.

나 자신도 로컬의 Hermes를 MCP를 통해 Claude Code의 워커 레인(Worker Lane)에 포함시키는 구성을 시도해 본 적이 있는데, 그것이 성립하는 것 또한 이 "1 코어 다면" 아키텍처 덕분이라는 것을 코드를 읽으며 납득할 수 있었다.

다음 회차에서는 이 다면 코어를 더욱 확장하는 운용——플러그인, 스킬, 훅, 프로파일, Cron을 다룬다.

대응 맵 장: §5, §14, §15 / API·Webhook 기본 포트는 실제 코드 확인 완료 / 행 번호는 hermes update 시 어긋날 수 있음