외부 봇(2oolkit-bot) 및 내부 봇 프로세스를 감시·재시작하고 Telegram으로 운영하는 독립 모니터링 봇.
- 프로세스 감시 / 자동 재시작 —
TARGET_DIR하위 봇 디렉토리를 주기적으로 스캔하고 중단된 프로세스를 자동 재시작 - Telegram 대시보드 — 인라인 버튼 UI로 상태 확인·제어 (재시작 / 종료 / 상세 보기)
- ReplyKeyboard 퀵 메뉴 — 채팅 하단 고정 버튼 (대시보드 / 터미널 정렬 / 스크린샷 / 봇 업데이트)
- 경제지표 캘린더 (선택) —
ECONOMIC_CALENDAR_ENABLED=true시/economic명령어 활성화 - 메모리 경고 알림 — 메모리 임계치 초과 시 Telegram 알림 (
MEMORY_ALERT_ENABLED) - 키워드 알림 — 봇 로그(
monitor.log)에서 운영자가 지정한 문구를 감지해 Telegram으로 알림 - RAPID_ENTRY_GUARD — 봇 로그에서 빠른 반복 진입 징후(비정상적 변동성)를 감시해 강제종료·지연 재시작하는 Z-Pulse 운영 안전장치
- Z-Flow 연동 레이어 (선택 주입) —
Z_FLOW_ENABLED=true시 siblingz_flow를 자동 감지해ZFlowBridge를 통해 Z-Flow 슬롯 상태와 명령 표면을 노출
- Python 3.11 이상 (
run_all.sh자동 확인) + pip - 가상환경(uv venv)
중요: 배포 압축 파일은 애플리케이션 파일이
z_pulse디렉토리 안에 위치하도록 압축 해제하고, 설치와 실행 명령은 반드시 해당z_pulse디렉토리에서 실행합니다.
Z-Pulse는 uv로 Python 가상환경을 생성·관리합니다. 설치 전에 uv 사용 가능 여부를 확인합니다.
uv --versionuv가 없으면 아래 공식 명령으로 설치합니다.
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"# macOS / Linux
cd z_pulse
bash setup_bot.sh
# Windows
cd z_pulse
setup_bot.bat스크립트가 대화형으로 아래 항목을 설정하고 setting.env를 생성합니다.
| 섹션 | 내용 |
|---|---|
| Section 1/4: 필수 설정 | 텔레그램 봇 토큰·채팅 ID, TARGET_DIR, PROCESS_NAME |
| Section 2/4: 기능 토글 | 경제지표 캘린더(업데이트 시간 포함), 메모리 경고 |
| Section 3/4: Z-Flow 연동 설정 (선택) | 같은 상위 디렉토리의 sibling z_flow 자동 감지 → Z_FLOW_PATH·Z_FLOW_ENABLED 자동 설정. Enter 시 단독 모드 |
| Section 4/4: Python 환경 | 가상환경(uv venv) 생성 및 requirements.txt 패키지 설치 |
참고: Z-Flow 연동을 사용하려면
z_pulse와z_flow를 같은 상위 디렉토리에 배치합니다. Section 3에서 활성화하면 setup이 siblingz_flow를 자동 감지해Z_FLOW_PATH를 기록합니다. siblingz_flow가 없으면 연동은 비활성화됩니다. (기본값: Z-Pulse 단독 모드)
수동 설정은 setting.env.example을 setting.env로 복사한 뒤 편집합니다.
# macOS / Linux
cd z_pulse
./run_all.sh:: Windows
cd z_pulse
run_all.batrun_all.sh / run_all.bat는 다음을 자동 처리합니다:
- Python 3.11+ 가상환경 확인·생성 및 의존성 설치
setting.env로드- 기존 Z-Pulse 프로세스 정리
Z_FLOW_ENABLED=true시ZFlowBridge기반 Z-Flow 연동 활성화- Z-Pulse 실행 (
__main__.py)
직접 디버깅이 필요한 경우에만 python app.py를 사용합니다.
| 명령어 | 설명 |
|---|---|
/start |
봇 시작 및 환영 메시지 |
/status |
대시보드 열기 |
/restart <디렉토리> |
특정 프로세스 재시작 (DB유지) |
/restart_all |
모든 프로세스 재시작 |
/restart_clean <디렉토리> |
초기화 후 재시작 (DB삭제) |
/restart_running |
실행 중인 봇만 재시작 |
/restart_main |
메인 봇(Z-Pulse 자체) 전체 재시작 |
/kill <디렉토리> |
특정 프로세스 종료 |
/screenshot |
화면 스크린샷 전송 |
/log |
봇 로그 보기 |
/arrange_windows |
터미널 창 정렬 |
/update_bot |
2oolkit-bot 바이너리 업데이트 |
/rename <old> <new> |
디렉토리명 변경 |
/help |
전체 명령어 도움말 |
/update_bot 명령어(= ReplyKeyboard "봇 업데이트")는 감시 대상 프로세스(2oolkit-bot)의 바이너리를 업데이트합니다.
바이너리 배치: 최초 1회 .update 경로를 생성하고, 2oolkit-bot 바이너리를 미리 두어야 합니다.
동작 순서:
.update/<2oolkit-bot*>파일 존재 확인 (없으면 경고 후 중단).update/디렉토리에서 바이너리 실행 후 출력 파싱Already up to date.→ 최신 버전 안내Updated to ...→ 업데이트 확인
- 업데이트 확인 시: 전체 봇 정지·정리 후 각 봇 디렉토리로 바이너리 배포
| 명령어 | 설명 |
|---|---|
/economic |
경제지표 확인 |
/start 또는 /help 실행 시 하단에 고정됩니다.
| 버튼 | 기능 |
|---|---|
| 대시보드 | /status 와 동일 |
| 터미널 정렬 | /arrange_windows 와 동일 |
| 스크린샷 | /screenshot 와 동일 |
| 봇 업데이트 | /update_bot 와 동일 |
각 봇 디렉토리 행에 상태 버튼 + 액션 버튼 표시:
| 상태 아이콘 | 의미 |
|---|---|
🟢 <dir> |
실행 중 — 클릭 시 상세 보기 |
🔴 <dir> |
중단됨 — 클릭 시 상세 보기 |
⚪ <dir> |
무시(ignore) 상태 — 클릭 시 상세 보기 |
액션 버튼 (상태에 따라 동적 표시):
| 버튼 | 조건 |
|---|---|
종료 |
실행 중인 봇 |
시작 |
중단된 봇 |
하단 제어 버튼:
| 버튼 | 기능 |
|---|---|
🔥 재시작(전체) |
모든 프로세스 재시작 확인 |
▶️ 재시작(실행중) |
실행 중인 프로세스만 재시작 |
📜 운영봇 로그(전체) |
Z-Pulse 전체 로그 출력 |
📄 운영봇 로그(100줄) |
Z-Pulse 최근 100줄 출력 |
🔄 새로고침 |
대시보드 갱신 |
Ignore 상태가 아닌 봇 선택 시 아래 버튼이 표시됩니다:
| 버튼 | 기능 |
|---|---|
⚙️ 설정 변경 |
개별 봇 설정 편집 메뉴 |
🔔 키워드 알림 설정 |
봇별 키워드 알림 메뉴 |
✨ 재시작(DB삭제) |
JSON/DB 초기화 후 재시작 |
🔄 재시작(DB유지) |
DB를 유지하고 재시작 |
📜 로그(전체) |
해당 봇 전체 로그 출력 |
📄 로그(100줄) |
해당 봇 최근 100줄 출력 |
🔙 돌아가기 |
메인 대시보드로 복귀 |
키워드 알림은 Z-Pulse가 TARGET_DIR 하위 각 봇 디렉토리의 monitor.log를 감시하다가, 사용자가 봇별로 등록한 문구가 새 로그에 나타나면 Telegram으로 알리는 운영 알림 기능입니다. RAPID_ENTRY_GUARD와 같은 LogKeywordMonitor 안에서 동작하지만 목적이 다릅니다. 키워드 알림은 운영자가 지정한 일반 문구를 보고 알림을 보내는 기능이고, RAPID_ENTRY_GUARD는 추가 진입 같은 반복 진입 징후를 별도 정책으로 판정해 강제종료와 지연 재시작까지 수행하는 안전장치입니다.
동작 방식:
- Z-Pulse 시작 시 기존
monitor.log의 현재 파일 크기를 시작 위치로 저장해 시작 전 로그는 기본 감지 대상에서 제외합니다. - 실시간 감시 대상은
TARGET_DIR/*/monitor.log입니다. macOS에서는 폴링 observer를 사용하며, 주기 점검 경로에서도 새 로그를 읽습니다. - 설정은 봇 디렉토리 이름별로 관리합니다. 기본 설정 파일명은
log_keywords.json이고, 파일이 없으면{"bots": {}}구조로 생성합니다. - 키워드 항목은 검증된 기본 구조 기준으로
phrase,is_json_block,cooldown_seconds를 사용합니다. 예:{"bots": {"bot-a": [{"phrase": "ERROR", "is_json_block": false, "cooldown_seconds": 300}]}} - 매칭은 정규식 패턴 해석이 아니라
re.escape(phrase)기반의 정확한 부분 문자열 검색입니다. 대소문자 정규화가 없으므로 영문 문구는 대소문자를 구분합니다. - 같은 봇과 같은 문구는
cooldown_seconds동안 중복 알림을 억제합니다. 기본 쿨다운 값은 코드 상수 기준 3600초입니다. is_json_block=true이면 매칭 위치 주변의 완전한 JSON 블록은 포맷팅하고, 완전하지만 유효하지 않은 JSON은 원문 블록으로 보냅니다. 완전한 블록을 찾지 못하면 매칭된 한 줄 또는 텍스트 알림을 보냅니다.false이면 매칭된 한 줄을 보냅니다.- 알림 메시지는 봇 이름, 키워드, 매칭 라인 또는 JSON 블록을 MarkdownV2 형식으로 보냅니다. Telegram 메시지 길이 제한을 넘으면 안전 길이에서 잘라 보냅니다.
kill_on_match=true키워드는 감지 시 알림 후 해당 봇 프로세스를 종료하는 확장 필드입니다. Telegram 키워드 설정 UI 입력 흐름에는 포함되지 않으므로 수동 JSON 편집 시에만 사용합니다.- 외부에서
log_keywords.json이 변경되면 mtime 증가를 감지해 재로드하고, Telegram UI에서 추가·수정·삭제한 내용은 원자적 JSON 저장 헬퍼로 저장합니다.
키워드 설정 방법:
| 경로 | 설정 표면 |
|---|---|
| Telegram 대시보드 | /status → 봇 상세 보기 → 🔔 키워드 알림 설정 |
| 상세 보기 콜백 | keyword_menu:{target} |
| 메뉴 내부 콜백 | kw_add_start, kw_edit_start, kw_delete_start, kw_sel_{idx}, kw_json_yes, kw_json_no, kw_confirm, kw_back |
| 입력 흐름 | 문구 입력 → JSON 블록 여부 선택 → cooldown_seconds 초 입력 → 저장 |
운영자 설정 표면은 /status의 봇 상세 보기에서 여는 🔔 키워드 알림 설정 메뉴이며, 상세 보기 콜백은 keyword_menu:{target}입니다.
경계와 주의사항:
- 이 기능은 Z-Pulse 운영 알림 기능이며 Z-Flow 전략 기능이나 전략 설정이 아닙니다.
- 감시 소스는 봇별
monitor.log이므로, Z-Flow에서 나온 로그 문구도 해당 파일에 기록된 뒤에야 감지됩니다. - 정규식, 대소문자 무시, 다중 조건식은 기본 키워드 UI/매칭 경로에서 지원하지 않습니다.
- 시작 시점 이전 로그는 기본적으로 무시되므로, 재시작 직전 이미 기록된 문구는 새 알림으로 재전송되지 않을 수 있습니다.
- JSON 블록 추출은 매칭 위치 주변의 중괄호를 기준으로 하므로, 로그가 잘린 블록이거나 중괄호 구조가 깨져 있으면 원문 일부로 전송될 수 있습니다.
- 쿨다운은 같은 봇·같은 문구 기준으로 적용되므로, 짧게 설정하면 알림량이 늘고 길게 설정하면 반복 장애 신호가 늦게 보일 수 있습니다.
RAPID_ENTRY_GUARD는 Z-Pulse가 소유한 운영 감시/안전장치입니다. TARGET_DIR 하위 target/external bot의 monitor.log에서 발생한 문구를 감시하며, Z-Flow 로그 문구도 신호 소스가 될 수 있습니다. 정책 판단과 프로세스 제어는 Z-Pulse의 LogKeywordMonitor와 process_controller가 담당하므로 Z-Flow 전략 기능이나 전략 설정이 아닙니다.
동작 방식:
- Z-Pulse 시작 시
monitor.log실시간 모니터가 시작되며, 시작 이전 로그는 감지 대상에서 제외합니다. TARGET_DIR하위 봇 디렉토리마다 watchdog observer를 등록합니다. macOS에서는 polling observer를 사용하고, guard가 켜져 있으면 별도 라인 폴링 스레드도 함께 시작합니다.- 로그 문구 감지는 기본적으로
RAPID_ENTRY_GUARD_PHRASE값을 사용합니다. 기본 문구는추가 진입입니다. - 같은 봇에서
RAPID_ENTRY_GUARD_SEQUENCE_WINDOW_SEC안에RAPID_ENTRY_GUARD_SEQUENCE_COUNT회 이상 감지되면 폭주로 판단합니다. 현재 트리거 판정은 횟수와 시퀀스 윈도우만 사용하며,RAPID_ENTRY_GUARD_MIN_INTERVAL_SEC와RAPID_ENTRY_GUARD_MAX_INTERVAL_SEC는 호환성 유지와 향후 정책 확장을 위해 로드되는 예약 파라미터입니다. RAPID_ENTRY_GUARD_FORCE_CONSECUTIVE=true이면 새 로그 청크 안에서RAPID_ENTRY_GUARD_FORCE_PHRASES에 포함된 대표 배너형 문구 라인이 기준 횟수 이상 보일 때 즉시 연속 감지로 등록합니다.- 로그 타임스탬프 기준 감지 지연이
RAPID_ENTRY_GUARD_LAG_ALERT_THRESHOLD_SEC이상이면, lag alert가 켜진 경우 cooldown 범위 안에서 중복을 억제하고 Telegram으로 지연 경보를 보냅니다. - 트리거되면
process_controller.kill_specific_process()로 해당 봇 프로세스를 먼저 종료하고 Telegram에 결과를 알립니다. RAPID_ENTRY_GUARD_RESTART_DELAY_SEC동안 재시작 윈도우를 유지해 추가 감지를 무시한 뒤,process_controller.start_bot_process()로 지연 재기동을 예약합니다.
주요 설정:
| 키 | 기본값 | 설명 |
|---|---|---|
RAPID_ENTRY_GUARD_ENABLED |
true |
guard 활성화. 끄려면 false로 설정 |
RAPID_ENTRY_GUARD_PHRASE |
추가 진입 |
기본 감지 문구 |
RAPID_ENTRY_GUARD_SEQUENCE_COUNT |
3 |
트리거에 필요한 감지 횟수 |
RAPID_ENTRY_GUARD_SEQUENCE_WINDOW_SEC |
3.3 |
기준 횟수를 판단할 시간 윈도우 |
RAPID_ENTRY_GUARD_MIN_INTERVAL_SEC |
0.7 |
호환성/예약용 감지 간격 하한값. 현재 트리거 조건에는 미사용 |
RAPID_ENTRY_GUARD_MAX_INTERVAL_SEC |
1.4 |
호환성/예약용 감지 간격 상한값. 현재 트리거 조건에는 미사용 |
RAPID_ENTRY_GUARD_RESTART_DELAY_SEC |
180 |
강제종료 후 자동 재기동까지 대기할 초 |
RAPID_ENTRY_GUARD_POLL_INTERVAL_SEC |
0.2 |
라인 폴링 주기. 0 이하 값은 기본값으로 대체 |
RAPID_ENTRY_GUARD_FORCE_CONSECUTIVE |
false |
새 로그 청크의 강제 연속 감지 모드 |
RAPID_ENTRY_GUARD_FORCE_PHRASES |
최초 진입,추가 진입 |
강제 연속 감지에 사용할 쉼표 구분 문구 목록 |
RAPID_ENTRY_GUARD_LAG_ALERT_ENABLED |
false |
감지 지연 경보 활성화 |
RAPID_ENTRY_GUARD_LAG_ALERT_THRESHOLD_SEC |
5 |
지연 경보 기준 초 |
RAPID_ENTRY_GUARD_LAG_ALERT_COOLDOWN_SEC |
60 |
같은 봇 지연 경보 중복 억제 초 |
RAPID_ENTRY_GUARD_DEBUG |
true |
hit/ignore/no-trigger 디버그 로그 출력 |
KEYWORD_MONITOR_OBSERVER_TIMEOUT_SEC |
macOS 1.0, 기타 0.2 |
watchdog/polling observer timeout |
setup_bot.sh, setup_bot.bat, setting.env.example은 기본 예시로 RAPID_ENTRY_GUARD_FORCE_PHRASES="최초 진입,추가 진입"을 기록합니다. 다른 키를 조정하려면 setting.env에 직접 추가합니다. 트리거 문구는 target/external bot 로그에서 파생되며 Z-Flow 로그 문구도 신호 소스가 될 수 있지만, 감지 정책·알림·강제종료·지연 재시작은 Z-Pulse 운영 계층에서만 수행합니다.
| 키 | 기본값 | 반영 시점 | 설명 |
|---|---|---|---|
TELEGRAM_BOT_TOKEN |
— | 재시작 | 텔레그램 봇 토큰 (@BotFather에서 생성) |
TELEGRAM_CHAT_ID |
— | 재시작 | 허용할 텔레그램 채팅 ID |
TARGET_DIR |
~/Documents/toolkit |
재시작 | 모니터링 대상 봇 디렉토리 상위 경로 |
PROCESS_NAME |
2oolkit-bot-macos-arm64 |
재시작 | 감시할 프로세스 이름 |
ECONOMIC_CALENDAR_ENABLED |
true |
재시작 | 경제지표 캘린더 활성화 |
ECONOMIC_UPDATE_HOUR |
06 |
재시작 | 경제지표 일일 업데이트 시간 (0-23) |
Z_FLOW_PATH |
— | 재시작 | sibling z_flow 루트 경로 (setup_bot Section 3에서 자동 기록, 일반 운영 수동 설정 불필요) |
Z_FLOW_ENABLED |
false |
재시작 | Z-Flow 연동 활성화 |
MEMORY_ALERT_ENABLED |
true |
즉시 | 메모리 임계치 초과 시 알림 |
z_pulse와 z_flow를 같은 상위 디렉토리에 둔 뒤 setup에서 Z_FLOW_ENABLED=true를 선택하면, setup이 sibling z_flow를 감지해 Z_FLOW_PATH를 기록합니다. Z-Flow 런타임이 존재하는 경우 Z-Pulse가 ZFlowBridge 단일 주입점을 통해 Z-Flow를 오케스트레이션합니다. Z-Pulse는 Z-Flow 내부 전략 키나 market-data 스크립트를 직접 소유하지 않습니다.
활성화 시 추가되는 기능:
텔레그램 명령어 추가:
| 명령어 | 설명 |
|---|---|
/pair_trading |
페어 매매 현황 확인 |
/transfer <FROM> <TO> <금액> |
자산 이전 (현재는 GRVT 거래소만 지원) |
대시보드 액션 버튼 추가 (메인):
| 버튼 | 조건 |
|---|---|
🔄 종료 |
실행 중인 Z-Flow 슬롯 봇 |
🔄 시작 |
중단된 Z-Flow 슬롯 봇 |
⚠️ 재개 필요 |
Z-Flow 슬롯 — 비정상 상태 |
🔄 시그널 대기 |
Z-Flow 슬롯 — 신호 대기 중 |
대시보드 상세 보기 버튼 추가:
| 버튼 | 기능 |
|---|---|
🤖 자동 배정 ON (...) / ⏸️ 자동 배정 OFF |
페어 로테이션 토글 |
⚡ 자동 배정 재개 |
비정상 종료 후 자동 배정 재개 (조건부) |
시장 데이터 데몬:
- Z-Pulse는 bridge와 런타임 DI를 통해 필요한 상태와 제어 표면만 사용합니다.
Z-Flow가 없는 환경에서는 관련 UI가 완전히 숨겨지며, Z-Pulse는 단독으로 동작합니다.
z_pulse/
├── app.py # 진입점
├── __main__.py # run_all.sh 실행 진입점
├── run_all.sh # 통합 실행 스크립트 (권장)
├── run_all.bat # 통합 실행 스크립트 (Windows)
├── stop_all.sh # 프로세스 일괄 종료 (macOS/Linux)
├── stop_all.bat # 프로세스 일괄 종료 (Windows)
├── setup_bot.sh # 설정 스크립트 (macOS/Linux)
├── setup_bot.bat # 설정 스크립트 (Windows)
├── economic_scheduler.py # 경제지표 스케줄러
├── constants.py # 전역 상수
├── setting.env.example # 환경변수 예시
├── platforms/ # 플랫폼별 구현
├── bot/
│ ├── factory.py # Application 생성 및 핸들러 등록
│ ├── keyboard_helper.py # ReplyKeyboardMarkup 헬퍼
│ └── handlers/
│ ├── commands.py # 슬래시 명령어 처리
│ ├── dashboard.py # 대시보드 UI
│ ├── process_actions.py # 버튼 콜백 (시작/종료/재시작)
│ ├── callback_router.py # 콜백 라우팅
│ ├── settings.py # 설정 메뉴
│ └── keywords.py # 키워드 모니터링 메뉴
├── config/ # 환경변수 로드 및 런타임 설정
├── features/ # 프로세스 제어, 경제지표, 창 관리 등
├── integration/
│ ├── z_flow_bridge.py # Z-Flow 단일 주입점
│ ├── telegram_extensions.py # Z-Flow 활성 시 추가 명령어/콜백
│ ├── strategy_registry.py # 전략 타입 해석
│ ├── uptime_restart_scheduler.py # 업타임 기반 재시작 스케줄러
│ └── z_flow_runtime_di.py # Z-Flow 런타임 DI
├── monitoring/ # 프로세스 감시, 로그 키워드 모니터
├── scripts/ # Z-Pulse 소유 보조 유틸리티
│ ├── stop_processes.py # 기존 프로세스 정리
│ ├── daemon_watchdog.py # 데몬 워치독
│ ├── log_wrapper.sh
│ └── 기타 Z-Pulse 운영 유틸리티
└── utils/ # 공통 유틸리티