콘텐츠로 이동

Agent 운영 위키 (Hermes + Claude + ProjectFR)

최종 업데이트: 2026-05-27 (KST)

1) 목적

  • Hermes/Claude 설정 형상보존 (git)
  • ProjectFR 야간 자동화 안정 운영
  • 수동 작업 시간대 자동 pause/resume
  • no_agent 경로에서도 footer/관측성 유지

2) 저장소/브랜치

  • 원격: https://github.com/zooin22/agent.git
  • 백업 브랜치: config-backup
  • 로컬 백업 레포: /home/zooin/.config-backups/hermes-claude-config

3) 포함 범위 (형상보존)

  • hermes/config.yaml
  • hermes/scripts/
  • hermes/skills/
  • claude/settings.json, claude/settings.local.json, claude/CLAUDE.md
  • claude/commands/, claude/agents/, claude/rules/
  • projectfr/wiki/ (ProjectFR 운영 위키 스냅샷)
  • AGENT-WIKI.md (이 문서)

4) 제외 범위 (비밀/노이즈)

  • hermes/.env
  • hermes/auth.json
  • hermes/logs/, hermes/sessions/
  • claude/**/token*

5) 활성 크론잡 상태

  • deterministic-scheduler-watch (72ffc62b1370)
  • schedule: every 1m
  • script: deterministic_scheduler.py
  • mode: no_agent=true

  • deliver: origin

  • projectfr-night-review (c858ff94ec41)

  • schedule: */5 2-7 * * *
  • script: projectfr_night_review_claude.sh
  • mode: no_agent=true
  • workdir: /mnt/f/Agent/hermes/Godot/projects/ProjectFR

  • deliver: origin

  • projectfr-manual-mode-guard (963b927655bc)

  • schedule: every 1m
  • script: projectfr_cron_guard.py
  • mode: no_agent=true

  • deliver: local

  • hermes-claude-config-snapshot (8813d0bc5253)

  • schedule: 0 4 * * *
  • script: config_snapshot_runner.sh
  • mode: no_agent=true
  • deliver: origin

6) 핵심 설정 값 (운영 기준)

  • model/provider
  • model.provider: openai-codex
  • model.default: gpt-5.3-codex
  • network
  • network.force_ipv4: true
  • cron
  • cron.wrap_response: true
  • streaming
  • streaming.enabled: true
  • display.streaming: true
  • footer
  • display.runtime_footer.enabled: true
  • display.platforms.telegram.runtime_footer.enabled: true

7) ProjectFR night pass 동작 요약

스크립트: /home/zooin/.hermes/scripts/projectfr_night_review_claude.sh

실행 흐름: 1. 락(flock) 확보 실패 시 즉시 skip 2. TODO(persistent-todo.md) 오픈 항목 확인 3. 오픈 TODO 있으면 TODO 작업 우선 수행 4. docs 체크 ON이면 docs 기반 TODO 추가 여부 검사 (쿨다운 적용) 5. TODO가 비면 리뷰 단계 실행 6. 종료 시 실행로그(jsonl) 기록 + healthchecks ping 7. no_agent 경로 footer 직접 출력

안정화 장치: - lock file: .hermes/night-pass.lock - state file: .hermes/night-pass-state.json - run log: .hermes/night-pass-runs.jsonl - failure streak + circuit breaker (FAILURE_LIMIT=3) - 전체 타임아웃 (PROJECTFR_NIGHT_PASS_TIMEOUT_SEC, 기본 300s) - docs TODO 쿨다운 (DOCS_TODO_COOLDOWN_SEC=86400)

8) 수동 작업 모드 (자동 pause/resume)

파일: - ON: /home/zooin/.hermes/scripts/projectfr_manual_mode_on.sh - OFF: /home/zooin/.hermes/scripts/projectfr_manual_mode_off.sh - guard: /home/zooin/.hermes/scripts/projectfr_cron_guard.py - flag: /mnt/f/Agent/hermes/Godot/projects/ProjectFR/.hermes/manual-work.json

사용법: - 수동 작업 시작 (예: 120분) - bash /home/zooin/.hermes/scripts/projectfr_manual_mode_on.sh 120 "manual-work" - 수동 작업 종료 - bash /home/zooin/.hermes/scripts/projectfr_manual_mode_off.sh

guard가 대상 잡 2개를 강제로 제어: - pause 대상: 72ffc62b1370, c858ff94ec41 - manual flag 만료 시 자동 resume

9) deterministic scheduler 요약

스크립트: /home/zooin/.hermes/scripts/deterministic_scheduler.py

핵심: - Codex rate limit 스냅샷 폴링 - reset window 변화 감지 후 알림 - dedupe state 관리 (state.json) - footer append 경로 보강

10) 백업/스냅샷 운영

  • 실행 스크립트: /home/zooin/.config-backups/hermes-claude-config/scripts/snapshot.sh
  • 크론 래퍼: /home/zooin/.hermes/scripts/config_snapshot_runner.sh
  • 매일 04:00 자동 실행

수동 실행:

bash /home/zooin/.config-backups/hermes-claude-config/scripts/snapshot.sh

push:

cd /home/zooin/.config-backups/hermes-claude-config
git push origin config-backup

11) 복구 절차(빠른 버전)

  1. 백업 레포 checkout (config-backup)
  2. 필요한 파일만 역복사
  3. hermes/config.yaml -> ~/.hermes/config.yaml
  4. hermes/scripts/* -> ~/.hermes/scripts/
  5. claude/* -> ~/.claude/
  6. 스크립트 실행권한 복원
  7. chmod +x ~/.hermes/scripts/*.sh
  8. gateway 재시작
  9. systemctl --user restart hermes-gateway
  10. 크론 상태 점검
  11. hermes cron list

12) 참고 문서

  • ProjectFR 운영 위키:
  • projectfr/wiki/2026-05-27-night-automation-wiki.md

13) 다음 강화 후보

  • snapshot 후 자동 push 잡(옵션)
  • 민감정보 스캔(gitleaks/trufflehog) pre-push 훅

14) 변경 이력

  • 2026-05-27 03:xx KST — 초기 운영 위키 작성, cron/스크립트/복구 절차 정리
  • 2026-05-27 04:xx KST — 위키 스냅샷 범위를 projectfr/wiki까지 확장
  • 2026-05-27 04:xx KST — 변경 이력 자동 append 스크립트(scripts/wiki_changelog_append.sh) 추가

15) 장애 대응 플레이북

A. Timeout / 응답 정체

증상: - Non-streaming API call stale for 300s - TimeoutError 반복

즉시 조치: 1. gateway 상태 확인 - systemctl --user status hermes-gateway --no-pager 2. 운영 설정 확인 - model.provider=openai-codex - model.default=gpt-5.3-codex - network.force_ipv4=true - model.base_url='' 3. gateway 재시작 - systemctl --user restart hermes-gateway 4. 최소 ping 검증 - hermes chat -q "ping" --provider openai-codex -m gpt-5.3-codex -Q

재발 방지: - 장시간 작업은 timeout 여유값 확대 - no_agent 잡은 lock/timeout/circuit breaker 유지

B. GitHub Auth / Push 실패

증상: - could not read Username for 'https://github.com' - Host key verification failed

즉시 조치(HTTPS 권장): 1. PAT 발급 (repo scope) 2. git config --global credential.helper store 3. 첫 인증 트리거 - git ls-remote https://github.com/zooin22/agent.git 4. push 재시도 - git push -u origin config-backup

SSH 사용 시: - ~/.ssh 키/known_hosts/github host key 신뢰 설정 먼저 완료 후 사용

원인: - no_agent=true 경로는 gateway 최종응답 footer 자동부착 경로와 분리됨

즉시 조치: 1. 설정값 확인 - display.runtime_footer.enabled=true - display.platforms.telegram.runtime_footer.enabled=true 2. no_agent 스크립트에서 footer 직접 출력 - provider footer 스크립트 호출 후 본문 끝에 append 3. DRY_RUN/수동 실행으로 footer 실제 출력 검증

검증 기준: - cron 산출 메시지 하단에 provider usage footer 노출 - 실패/성공 분기 모두 footer 유지 - 2026-05-27 03:54 KST — snapshot 전 갱신 체크 (head=07018c8, pending=6) - 2026-05-27 04:00 KST — snapshot 전 갱신 체크 (head=3b28ec5, pending=3)