← 리포트 목록
시스템 청사진 — Hermes 이전 완료 (v3)
2026-04-12
claude
["system", "blueprint", "hermes", "migration", "architecture"]
시스템 청사진 v3 — Hermes 이전 완료
2026-04-12 기준. OpenClaw Node.js 게이트웨이에서 Hermes Python 게이트웨이로 전환 완료.
1. 이전 요약 (Before → After)
| 항목 | Before (OpenClaw 중심) | After (Hermes 중심) |
|---|---|---|
| 게이트웨이 | Node.js (openclaw-gateway), 734MB~4GB RSS | Hermes Python (hermes_cli), 74MB RSS |
| 크론 관리 | Node 게이트웨이 내장 (jobs.json 294개) | Hermes 네이티브 크론 (150개, 활성 149 + 기존 1) |
| 에이전트 큐 | 9개 별도 프로세스 (agent-queue-*) | Hermes task-queue 플러그인 (1개 프로세스 내) |
| 대시보드 데이터 | Gateway API 의존 (/api/*) | Anthropic API 직접 연결 |
| LaunchAgent | 54개 (전부 활성) | 26개 활성, 23개 비활성화 |
| 텔레그램 | telegram-bridge (별도 프로세스) | Hermes 네이티브 어댑터 |
| 메모리 감시 | Node 프로세스 감시 (2GB 임계) | Hermes 프로세스 감시 (500MB 임계) |
| 총 메모리 | 게이트웨이+큐+브릿지 합산 ~2GB+ | Hermes 단일 ~74MB |
2. 현재 시스템 구조
flowchart LR
H[해리]
X[cmux]
C1[Claude Code]
C2[Codex]
HM[Hermes v0.8.0]
HMG[Hermes Gateway<br/>port 18789]
HMC[Hermes Cron<br/>150 jobs]
HMT[Hermes Telegram<br/>어댑터]
HMP[task-queue<br/>플러그인]
P[파이프라인 스크립트<br/>~/.openclaw/workspace/scripts/pipeline/]
DB[(ops_multiagent.db)]
K1[knowledge<br/>해리 볼트]
K2[knowledge-agent<br/>에이전트 볼트]
W[virtual-insanity.net<br/>Flask 웹앱 :8080]
D[Ops 대시보드 :3344]
CF[Cloudflare 터널]
MG[Memory Guardian v2]
OT[OTel 수집기]
H --> X
X --> C1
X --> C2
H --> HMT
HMT --> HM
HM --> HMG
HM --> HMC
HM --> HMP
HMC --> P
HMP --> DB
C1 --> P
C2 --> P
P --> DB
P --> K2
P --> W
C1 --> K2
C2 --> K2
HM --> K2
W --> CF
D --> CF
MG -.->|감시| HMG
MG -.->|감시| OT
style HM fill:#2d6a4f,color:#fff
style HMG fill:#2d6a4f,color:#fff
style HMC fill:#2d6a4f,color:#fff
style HMT fill:#2d6a4f,color:#fff
style HMP fill:#2d6a4f,color:#fff
3. 컴포넌트 상세
3-1. Hermes (운영 중심축)
Hermes v0.8.0이 OpenClaw Node.js 게이트웨이를 대체하여 운영 중심축 역할 수행.
| 기능 | 구현 | 비고 |
|---|---|---|
| 게이트웨이 | hermes_cli.main gateway |
LaunchAgent ai.hermes.gateway, port 18789 |
| 크론 | ~/.hermes/cron/jobs.json |
150개 (OpenClaw 149개 이전 + 기존 1개) |
| 태스크 큐 | task-queue 플러그인 | SQLite bus_commands, 원자적 클레임, WAL, 300초 stale 복구 |
| 텔레그램 | 네이티브 어댑터 | @openclaw_harybot (해리 DM), @RONforMAC_Bot (알림) |
| 플러그인 | ~/.hermes/plugins/ |
plugin.yaml + register(ctx) 패턴 |
3-2. Claude Code & Codex (실행축)
| 에이전트 | 역할 | 실행 환경 |
|---|---|---|
| Claude Code (Opus 4.6) | 기획, 검토, 오케스트레이션 | cmux surface 1-2 |
| Codex (GPT-5.4) | 구현, 코드 작업 | cmux surface 3-4 |
cmux가 다중 세션 관리. Claude/Codex 모두 파이프라인 스크립트와 볼트에 직접 접근.
3-3. 파이프라인
경로 변경 없음. 모든 스크립트는 ~/.openclaw/workspace/scripts/pipeline/에 그대로 유지.
Hermes 크론이 기존 OpenClaw 크론과 동일한 명령으로 실행.
- PYTHONPATH:
shared/+pipeline/모듈 의존 - 공용 모듈:
shared/llm.py,shared/db.py,shared/telegram.py,shared/cycle_base.py
3-4. 저장소
| 저장소 | 경로 | 용도 |
|---|---|---|
| knowledge | ~/knowledge/ |
해리 고유 지식 (읽기 전용) |
| knowledge-agent | ~/knowledge-agent/ |
AI 작업 공간 (양방향 공유) |
| ops_multiagent.db | ~/.openclaw/data/ |
큐, 할일, 이벤트, KPI |
| 웹앱 | ~/.openclaw/workspace/mission-control/ |
Flask, port 8080 |
| 대시보드 | port 3344 | Ops 모니터링 |
3-5. Memory Guardian v2
| 항목 | 설정 |
|---|---|
| 감시 대상 | hermes_cli.main gateway (pgrep 패턴) |
| RSS 임계 | 500MB |
| 재시작 | launchctl kickstart gui/501/ai.hermes.gateway |
| 추가 감시 | chroma-mcp (1GB 임계) |
| 실행 주기 | 매분 (LaunchAgent ai.openclaw.memory-guardian) |
| 누수 감지 | 1시간 50% 증가 연속 3회 시 자동 재시작 |
| 정리 단계 | L1(3GB이하 purge) → L2(1.5GB이하 ollama/stealth 종료) → L3(500MB이하 Node MCP 종료) |
4. 네트워크 포트
| 포트 | 서비스 | 비고 |
|---|---|---|
| 8080 | Flask 웹앱 | virtual-insanity.net |
| 3344 | Ops 대시보드 | |
| 18789 | Hermes 게이트웨이 | 이전: OpenClaw Node 게이트웨이 |
| 4317 | OTel gRPC | 수집기 |
| 4318 | OTel HTTP | 수집기 |
5. LaunchAgent 현황
활성 26개, 비활성화 23개.
| 비활성화된 서비스 | 이유 |
|---|---|
| ai.openclaw.gateway | Hermes 대체 |
| ai.openclaw.node | Hermes 대체 |
| ai.openclaw.agent-queue-* (9개) | task-queue 플러그인 대체 |
| ai.openclaw.telegram-bridge | Hermes 네이티브 어댑터 대체 |
| 기타 레거시 | 통합 또는 미사용 |
6. 데이터 흐름
해리 메시지 (텔레그램)
→ Hermes 텔레그램 어댑터
→ Hermes 세션 처리
→ 필요 시 파이프라인 스크립트 실행
→ ops_multiagent.db 기록
→ knowledge-agent/ 노트 생성
→ 텔레그램 응답
Hermes 크론 (150개)
→ 매 스케줄마다 파이프라인 스크립트 실행
→ 결과 → DB / 볼트 / 텔레그램 알림
Claude/Codex (cmux)
→ 해리 직접 지시 또는 자율 작업
→ 파이프라인 스크립트 / 볼트 / DB 접근
→ 결과 보고 (텔레그램 또는 대화)
7. 모니터링 계층 (유지)
이전 청사진(v2)에서 설계한 OTel 기반 통합 모니터링 계층은 그대로 유지.
| 계층 | 현황 |
|---|---|
| OTel 수집기 | 가동 중 (4317/4318) |
| Claude Code 텔레메트리 | 연결 대기 (Phase 4) |
| Codex 로그 수집 | 연결 대기 |
| Hermes 로그 수집 | filelog receiver 기반 계획 |
| cmux 스냅샷 | exporter 계획 |
| Knowledge Graph Live | graphify 패널 가동 중 |
8. 롤백 경로
Hermes 이전에 문제 발생 시 OpenClaw 게이트웨이로 복원하는 절차.
8-1. 크론 롤백
# Hermes 크론 백업에서 이전 상태 복원
cp ~/.hermes/cron/backups/jobs_pre_migration_20260412_193115.json \
~/.hermes/cron/jobs.json
# 또는 OpenClaw 크론으로 완전 복귀
launchctl kickstart -k gui/501/ai.openclaw.gateway
8-2. 게이트웨이 롤백
# 1. Hermes 게이트웨이 중지
launchctl bootout gui/501/ai.hermes.gateway
# 2. OpenClaw Node 게이트웨이 재활성화
launchctl bootstrap gui/501 ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl kickstart gui/501/ai.openclaw.gateway
# 3. Memory Guardian을 Node 감시로 되돌리기
# memory_guardian.py의 GATEWAY_PGREP_PATTERN을 "openclaw-gateway"로,
# GATEWAY_RSS_THRESHOLD_MB를 2000으로 변경
8-3. 에이전트 큐 롤백
# agent-queue LaunchAgent 9개 재활성화
for plist in ~/Library/LaunchAgents/com.openclaw.agent-queue-*.plist; do
launchctl bootstrap gui/501 "$plist"
done
8-4. 텔레그램 롤백
# telegram-bridge 프로세스 재시작
launchctl kickstart gui/501/ai.openclaw.telegram-bridge
9. 유지된 컴포넌트 (변경 없음)
- Flask 웹앱 (port 8080, virtual-insanity.net)
- Ops 대시보드 (port 3344)
- Cloudflare 터널
- OTel 수집기 (4317/4318)
- 스마트홈 알림
- 볼트 이중 구조 (~/knowledge, ~/knowledge-agent)
- cmux 세션 관리
- 파이프라인 스크립트 경로 및 공용 모듈
- ops_multiagent.db 스키마
10. 다음 단계
| 우선순위 | 작업 | 상태 |
|---|---|---|
| 1 | Hermes 크론 150개 실행 안정성 모니터링 (1주) | 진행 중 |
| 2 | OTel → Hermes filelog receiver 연결 | 미착수 |
| 3 | Codex log ingestion 연결 | 미착수 |
| 4 | cmux snapshot exporter | 미착수 |
| 5 | 비활성화된 LaunchAgent 정리 (plist 삭제) | 대기 |
| 6 | OpenClaw 레거시 코드 정리 | 대기 |