4분 읽기

스케줄러 에이전트 관리 가이드

프로젝트(CSN)별로 등록된 자동화 실행기(gissue 스케줄러 등 백그라운드 에이전트)의 온라인/오프라인 상태, 실행 상태·이력, 실시간 로그를 한 화면에서 관리합니다.

🕐 스케줄러 에이전트 관리 페이지로 이동 →

📋 개요

스케줄러 에이전트 관리는 현재 선택된 프로젝트(CSN)에 등록된 모든 자동화 에이전트 — 예를 들어 gissue의 매시간 스케줄러, 대화형 Claude Code 세션 등을 보여줍니다. giip 이슈를 고양이로 시각화하는 /admin/catquest와 달리, 이 화면은 자동화 작업을 실행하는 에이전트 자체를 관리하는 운영 대시보드입니다: 각 에이전트가 살아있는지, 현재 실행이 정상인지, 로그는 어디서 볼 수 있는지를 확인합니다.

🎨 상태 색상

에이전트마다 서로 독립적인 두 가지 상태 신호가 표시됩니다 — 혼동하지 마세요.

Identity 상태 (에이전트 이름 옆 작은 점)

개별 실행(run)과 무관하게, 에이전트 프로세스 자체에 접근 가능한지를 나타냅니다(tSchedulerAgent.status).

색상	상태	의미
🟢 초록	online	에이전트에 접근 가능하며 정상 보고 중
🔴 빨강	error	에이전트가 오류 상태를 보고함
⚪ 회색(slate-400)	offline	현재 에이전트에 접근할 수 없음
⚪ 연한 회색(slate-300)	unknown	아직 상태가 보고되지 않음

실행 상태 (Status 컬럼의 배지)

가장 최근 스케줄러 *실행(run)*의 상태(currentStatus)와 stale(정체) 탐지 결과를 반영합니다.

색상	표시 라벨	조건	의미
🟢 초록	RUNNING	`currentStatus = RUNNING`이고 stale 아님	정상적으로 실행 중
🔴 빨강	STALE	`currentStatus = RUNNING` 이면서 `isStale = true`	실행 중으로 표시돼 있지만 heartbeat가 너무 오래 끊김 — 멈춰버린/좀비 실행으로 보임
🟠 주황	STALE	`currentStatus = STALE`(명시적 값)	백엔드가 실행 자체를 stale로 판정함
⚪ 회색	ENDED	`currentStatus = ENDED`	종료됨(정상 완료 또는 정상적인 중지)
⚪ 회색	(원본 값)	그 외 / 실행 이력 없음	알 수 없음 / 데이터 없음

아래 실행이력 모달에서는 완료된 실행이 빨간색 FAILED로도 표시될 수 있습니다 — ENDED(정상 종료)나 stale/타임아웃과는 구분되는, 오류로 종료된 실행입니다.

🔍 화면 구성

1. 상단 헤더

/admin/catquest로 돌아가는 뒤로가기 화살표(←).
Refresh: 현재 CSN의 에이전트 목록을 다시 불러옵니다.

2. Open Interactive Sessions

활성 상태인 claude_interactive_session 에이전트 — 즉 현재 호스트에서 실행 중으로 등록된 대화형 Claude Code 세션 — 이 하나 이상 있을 때만 별도 카드로 표시됩니다. 각 행은 세션 이름, 호스트, 마지막 통신 시각, 그리고 에이전트의 capabilities에 세션 URL이 등록돼 있을 때 표시되는 "Open session" 링크를 보여줍니다.

3. 에이전트 목록 (표)

스케줄러 에이전트당 한 행씩 표시되며, 다음 정보를 담습니다.

Name — identity 상태 점, 에이전트 이름, OS/에이전트 유형/버전 배지, lssn(연결된 서버), 잘린 capabilities 요약, 마지막 오류(있는 경우).
Host — hostIdentifier.
Windows Task — 해당되는 경우, 이 에이전트를 실행하는 Windows 작업 스케줄러 작업 이름.
Project — 프로젝트 이름.
Active — ON/OFF 배지(isActive).
Last Comm — 마지막 heartbeat/통신 시각.
Status — 위에서 설명한 실행 상태 배지와, 보고된 경우 현재 단계(phase) 텍스트.

하단 통계 푸터는 목록에 표시된 모든 에이전트의 처리(Processed) / 스킵(Skipped) / 실패(Failed) 건수 합계를 보여줍니다.

4. 실행이력 (Run History)

표 아래 "View History" 카드에 모든 에이전트가 다시 나열되며, 행의 History 버튼을 클릭하면 해당 에이전트의 최근 실행 목록을 모달로 보여줍니다 — 실행 모드, 상태(FAILED 포함), 시작/종료 시각, 소요 시간, 처리/스킵/실패 건수, 단계, 요약.

5. 실시간 로그 뷰어 (Live Log Viewer)

두 영역으로 구성된 실시간 tailing 화면입니다.

좌측(에이전트 → 스트림 트리): 에이전트별로 그룹화되며, 각 에이전트를 펼치면 알려진 로그 스트림 목록이 나옵니다(스트림은 streamKey로 식별되며 streamType과 로테이션 세대 번호를 가집니다). 에이전트는 마지막 통신 시각을 기준으로 online/offline이 표시됩니다.
우측(로그 스트림 카드): 스트림을 선택하면 최근 로그 라인이 표시되고, 실시간 tailing을 위해 계속 갱신됩니다.

💡 유의 사항

이 화면은 관리자 전용입니다. AdminGuard(uLevel ≥ 70) 접근 권한이 필요합니다.
에이전트 목록, 실행이력, 로그 카탈로그는 모두 세션의 현재 CSN을 기준으로 조회됩니다 — 다른 프로젝트의 에이전트를 확인하려면 상단 내비게이션에서 프로젝트를 전환하세요.
데이터 조회에는 인증된 세션(AK 토큰)이 필요합니다. 요청이 인증 오류로 실패하기 시작하면 다시 로그인 후 Refresh를 누르세요.
이 페이지는 /admin/catquest와는 별개의 도구입니다 — CatQuest 화면의 내비게이션을 통해 진입했다고 해서 CatQuest의 고양이 시각화 데이터나 대상 사용자를 공유하는 것은 아닙니다.

문제 해결

증상	원인	해결
"Authentication required" 오류	AK/세션 토큰을 찾을 수 없음	다시 로그인한 뒤 페이지를 새로고침하세요.
에이전트 목록이 비어 있음	이 CSN에 등록된 스케줄러 에이전트가 없거나, 프로젝트가 잘못 선택됨	상단 내비게이션에서 올바른 프로젝트(CSN)가 선택돼 있는지 확인하세요.
작업이 유휴 상태인 걸 아는데도 행이 빨간색 STALE로 표시됨	에이전트가 ENDED로 전이되지 않은 채 실행 도중 heartbeat 전송이 멈춤(`isStale = true`) — 프로세스가 크래시했거나 강제 종료됐을 가능성	에이전트 호스트를 직접 확인하세요. 재시작 후 다시 보고를 시작하면 배지가 갱신됩니다.
Live Log Viewer에 "No streams yet."이 표시됨	에이전트가 아직 로그 스트림을 등록하지 않았거나, 카탈로그가 마지막으로 갱신된 이후 출력이 없음	에이전트의 다음 실행을 기다리거나, 에이전트 프로세스가 실제로 로그를 쓰고 있는지 확인하세요.
Open Interactive Sessions에 "Open session" 링크가 없음	해당 에이전트의 등록된 capabilities에 `sessionUrl`이 포함돼 있지 않음	열 수 있는 항목이 없습니다 — 해당 대화형 세션이 접근 가능한 URL을 등록하지 않았습니다.

버전: 1.0 최종 업데이트: 2026-08-29 소스 파일: giipv3/public/help/catquest-schedulers.ko.md