🦞 25. 크론 서브에이전트 분산운영 (품질 동등성 설계)

크론을 watcher/builder/maintainer로 분산하면 토큰 병목은 줄고, 품질은 공통 지침(quality contract)으로 같은 수준을 유지할 수 있습니다.

“요즘 왜 이렇게 바쁜데도 체감이 안 나지?”라는 질문이 생기면, 대부분은 사람 문제가 아니라 크론 구조 문제입니다. 최근 운영 로그를 보면, 고빈도 잡 1개(교육요청 메일 알림)가 24시간 48회 실행 + 약 97만 토큰을 사용했고, 메인 에이전트 집중 구조에서는 이 부하가 그대로 누적됐습니다.

20편이 “운영 원칙”을 설명했다면, 이 문서는 그 원칙을 실제 크론 운영에 적용한 진화판 실행 가이드입니다.

안내: 본문은 생성형 AI를 활용해 작성·정리했으며, 실제 적용 로그를 바탕으로 구성했습니다.

문제 인식: 왜 25편이 필요했나

메인 에이전트에 크론이 몰리면, 사용자 직접 요청과 정기 잡이 같은 자원을 경쟁합니다.
고빈도 감시 잡은 no-op 응답만으로도 토큰이 크게 새고, 중요한 작업 응답 체감이 떨어집니다.
분산만 하면 해결될 것 같지만, 품질 지침이 없으면 에이전트마다 결과물이 흔들립니다.

flowchart LR
A[메인 에이전트 과부하] --> B[작업 성격 분해]
B --> C[Watcher 분산]
B --> D[Builder 분산]
B --> E[Maintainer 분산]
C --> F[공통 품질지침]
D --> F
E --> F
F --> G[토큰 병목 완화 + 품질 동등성]

핵심 요약

분산 포인트는 “사람 수”가 아니라 업무 성격 분리다.
품질을 유지하려면 에이전트마다 문체가 아니라 동일 품질 계약서를 깔아야 한다.
운영 성공 기준은 “잡이 많이 돈다”가 아니라 실패율/토큰/품질 3축으로 봐야 한다.

🧠 칠판 치트시트

메인은 최종 의사결정, 크론은 역할별 서브에이전트로 분산

watcher: 감시/수집, builder: 생성/초안, maintainer: 정리/점검

품질은 AGENTS/SOUL/USER/TOOLS/MEMORY 공통 구조로 고정

성능 평가는 토큰·실패율·품질동등성 3개로 관리

용어/비유 설명

Watcher: 센서(이상 감지/신규 이벤트 감시)
Builder: 제작팀(콘텐츠/초안 생성)
Maintainer: 운영팀(정리/검증/루틴 유지)

비유하면, 한 명이 감시·제작·청소를 동시에 하던 구조를 관제실 + 제작실 + 운영실로 나눈 겁니다.

실전 적용 5단계

1) 잡을 업무 성격으로 분류

왜 필요한가: 빈도 기준으로만 나누면 병목이 그대로 남습니다.
실전 적용:
- 감시성(고빈도): watcher
- 생성성(중~고토큰): builder
- 점검성(정기): maintainer
실패 신호: 분산했는데도 메인 토큰이 계속 급증
10초 체크: “이 잡은 감시/생성/점검 중 무엇인가?”
참고: https://docs.openclaw.ai/cli/cron

2) 품질 동등성 계약서(공통 지침) 배포

왜 필요한가: 분산하면 스타일/완성도 편차가 생기기 쉽습니다.
실전 적용:
- 각 워크스페이스에 AGENTS.md, SOUL.md, USER.md, TOOLS.md, MEMORY.md 공통 배치
- AGENTS.md에 Quality Contract(목표 잠금/근거/재현성/안전/품질게이트/종결) 명시
실패 신호: 에이전트별 결과 톤/구조가 들쭉날쭉함
10초 체크: “세 에이전트 모두 같은 품질 규칙 파일을 갖고 있는가?”
참고: https://docs.openclaw.ai/cli/agents

3) cron job을 agent 단위로 재배정

왜 필요한가: session=isolated만으로는 메인 의사결정 경합이 남을 수 있습니다.
실전 적용:
- openclaw cron edit <id> --agent cron-watcher
- openclaw cron edit <id> --agent cron-builder
- openclaw cron edit <id> --agent cron-maintainer
실패 신호: 잡은 분산됐는데 특정 에이전트에 다시 과부하 집중
10초 체크: jobs.json에서 잡별 agentId가 역할과 맞는가?
참고: https://docs.openclaw.ai/cli/cron

4) 고빈도 잡은 NO_REPLY + 변화기반 보고로 축소

왜 필요한가: 고빈도 잡은 “변화 없음” 응답이 누적되면 토큰이 새어 나갑니다.
실전 적용:
- no-op은 NO_REPLY 고정
- 신규 이벤트/에러/임계치 초과에만 보고
실패 신호: 알림은 많은데 실질 액션은 거의 없음
10초 체크: 최근 24h 보고 중 “의사결정이 필요한 보고” 비율이 높은가?

5) D+1 비교 리포트로 고정

왜 필요한가: 분산 직후 체감만으로는 개선 판단이 어렵습니다.
실전 적용:
- 분산 전/후 비교: 토큰 총량, 에러율, 산출물 품질(체크리스트 통과율)
- 병목 잡 1개를 우선 재튜닝
실패 신호: 분산했지만 개선 수치가 없음
10초 체크: “전/후 표 1장”이 있는가?

이 구조가 20편의 진화판인 이유

20편: 원칙(운영 시스템으로 써라)
25편: 실행(잡을 역할별로 쪼개고 품질 계약서까지 동기화)

즉, “좋은 철학”에서 끝나는 게 아니라 운영 아키텍처를 실제로 바꾼 단계입니다.

운영 체크리스트 (복붙용)

watcher / builder / maintainer 역할 정의 완료
각 에이전트 공통 품질 지침 파일 배포 완료
활성 크론의 agentId 재배정 완료
고빈도 잡 변화기반 보고 규칙 적용
D+1 성능·품질 비교 리포트 작성

2026-03 운영 업데이트: 누락 재발 방지 반영

최근 실제 장애를 통해, “크론이 돈 것처럼 보이는데 실은 핵심 스크립트가 안 돈다”는 유형을 운영 리스크 1순위로 재분류했습니다. 분산 운영 자체는 맞았지만, 경로 드리프트와 외부 crontab 리다이렉션 실패를 같이 잡아야 누락을 막을 수 있었습니다.

1) 운영 오너를 cron-maintainer로 고정

기존에는 watcher/builder/maintainer가 각자 잘 돌면 된다는 관점이 강했습니다. 지금은 cron-maintainer를 운영 오너로 두고, 상태를 정기적으로 한 번 더 모아 공유하는 구조로 바꿨습니다.

데일리 브리핑: 🧭 운영오너 데일리 브리핑 (09:30/14:30/20:30)
주간 업그레이드: 🛠 운영오너 주간 업그레이드 (월 09:40)

이렇게 하면 “개별 잡 정상”이 아니라 “전체 운영 정상”을 기준으로 의사결정할 수 있습니다.

2) 경로 드리프트 전용 가드 추가

실제 누락 원인은 watcher 잡이 옛 경로를 참조한 상태에서, run status는 ok로 찍히는 오인 패턴이었습니다. 이를 막기 위해 cron_payload_path_guard.py를 추가해, payload 경로 존재 여부와 hidden path error를 주기적으로 점검하게 했습니다.

가드 잡: 🛡️ Cron 경로 가드 (3시간 주기)
역할: 경로 누락 감지 + “ok인데 실은 경로 에러” 패턴 탐지

3) YouTube watcher 3종 하드닝

Maker Evan / Science ADAM / Code Factory watcher는 아래 규칙으로 보강했습니다.

payload 실행 경로를 프로젝트 기준 경로로 통일
STATE_PATH를 절대경로에서 Path(__file__).with_name(...)으로 전환
새 영상이 없어도 last_poll_at 갱신(점검 실행 여부 추적)
delivery를 announce로 고정해 실패 시 즉시 알림

미니 사례:

Before: 스크립트 파일 이동 후 옛 경로를 계속 참조해 누락 발생
After: 경로 가드 + 상대 state 경로 + poll 타임스탬프로 실행/감지 신뢰성 확보

4) 외부 crontab(정부지원)까지 동일 기준 적용

정부지원 작업은 OpenClaw cron이 아니라 OS crontab으로 돌고 있어, 리다이렉션 로그 경로가 없으면 명령이 시작도 못 하는 문제가 있었습니다.

적용한 보강:

crontab 라인에 mkdir -p logs 선행
실행 스크립트에 flock(중복실행 방지), timeout(장기 멈춤 방지), START/DONE/ERROR 로그 추가