271 lines
6.2 KiB
Markdown
271 lines
6.2 KiB
Markdown
---
|
||
title: "OpenClaw 자가복구 시스템 Part 2 - Claude Code를 응급의사로 활용하기"
|
||
date: 2026-02-07
|
||
category: AI
|
||
tags: [OpenClaw, Claude, tmux, PTY, Automation]
|
||
draft: true
|
||
description: "tmux PTY에서 Claude Code를 실행하여 자율 진단/복구를 수행하는 Level 3 시스템의 구현 세부사항을 공유합니다."
|
||
---
|
||
|
||
## TL;DR
|
||
|
||
- **핵심**: Claude Code를 tmux PTY 세션에서 실행, 자율 진단/복구
|
||
- **구현**: bash 스크립트 ~150줄로 완성
|
||
- **트릭**: 워크스페이스 신뢰 자동 처리, 완료 감지 폴링
|
||
- **안전장치**: 30분 타임아웃, 락 파일, 권한 제한
|
||
- **결과**: 평균 복구 시간 5-10분 (최대 30분)
|
||
|
||
---
|
||
|
||
## Level 3의 핵심 아이디어
|
||
|
||
Level 2 (Health Check)가 3번 재시도해도 실패하면, 단순 재시작으로는 해결 안 되는 문제다.
|
||
|
||
이때 필요한 건:
|
||
1. **로그 분석** — 에러 메시지 확인
|
||
2. **설정 검증** — JSON 문법 오류, 포트 충돌 등
|
||
3. **의존성 체크** — Node.js 버전, npm 패키지 상태
|
||
4. **지능적 판단** — 어떤 조치를 취할지 결정
|
||
|
||
이걸 규칙 기반으로 하면? 새로운 에러 패턴마다 코드 수정 필요.
|
||
Claude에게 맡기면? **"이 로그 보고 알아서 고쳐"** 가 가능.
|
||
|
||
---
|
||
|
||
## tmux PTY가 필요한 이유
|
||
|
||
Claude Code는 단순 파이프(`echo "명령" | claude`)로는 제대로 작동 안 한다.
|
||
|
||
**이유:**
|
||
- 인터랙티브 모드 필요 (워크스페이스 신뢰 프롬프트)
|
||
- 실시간 출력 캡처
|
||
- 멀티턴 대화 지원
|
||
|
||
**해결책:** tmux PTY 세션
|
||
|
||
```bash
|
||
# PTY 세션 생성
|
||
tmux new-session -d -s "emergency_recovery_2026-02-06-1930"
|
||
|
||
# Claude 실행
|
||
tmux send-keys -t "$TMUX_SESSION" "claude" C-m
|
||
|
||
# 워크스페이스 신뢰 자동 처리
|
||
sleep 5
|
||
tmux send-keys -t "$TMUX_SESSION" "" C-m # Enter 키
|
||
|
||
# 복구 명령 전송
|
||
tmux send-keys -t "$TMUX_SESSION" "$recovery_command" C-m
|
||
```
|
||
|
||
---
|
||
|
||
## 완료 감지: 폴링 vs 고정 대기
|
||
|
||
### 초기 구현 (비효율)
|
||
|
||
```bash
|
||
sleep 1800 # 30분 무조건 대기
|
||
```
|
||
|
||
**문제:** Claude가 5분 만에 끝나도 30분 기다림
|
||
|
||
### 개선된 구현 (폴링)
|
||
|
||
```bash
|
||
local poll_interval=30
|
||
local elapsed=0
|
||
local idle_count=0
|
||
local max_idle=6 # 3분간 변화 없으면 완료
|
||
|
||
while [ $elapsed -lt "$RECOVERY_TIMEOUT" ]; do
|
||
sleep "$poll_interval"
|
||
elapsed=$((elapsed + poll_interval))
|
||
|
||
# 현재 출력 캡처
|
||
current_output=$(tmux capture-pane -t "$TMUX_SESSION" -p | tail -20)
|
||
|
||
# 완료 시그널 체크
|
||
if echo "$current_output" | grep -qiE "(recovery completed|gateway restored|http 200)"; then
|
||
break
|
||
fi
|
||
|
||
# 출력 변화 체크 (idle detection)
|
||
if [ "$current_output" = "$last_output" ]; then
|
||
idle_count=$((idle_count + 1))
|
||
if [ $idle_count -ge $max_idle ]; then
|
||
break # 3분간 출력 없음 = 완료
|
||
fi
|
||
else
|
||
idle_count=0
|
||
fi
|
||
done
|
||
```
|
||
|
||
**결과:** 평균 복구 시간 5-10분으로 단축
|
||
|
||
---
|
||
|
||
## 안전장치 설계
|
||
|
||
### 1. 타임아웃 (30분)
|
||
|
||
Claude가 무한 루프에 빠지거나 응답 없을 때 대비
|
||
|
||
```bash
|
||
RECOVERY_TIMEOUT="${EMERGENCY_RECOVERY_TIMEOUT:-1800}"
|
||
```
|
||
|
||
### 2. 락 파일
|
||
|
||
동시 실행 방지 (Health Check가 중복 호출할 때)
|
||
|
||
```bash
|
||
# 보안 경로 (다른 사용자 접근 불가)
|
||
LOCKFILE="$LOG_DIR/.emergency-recovery.lock"
|
||
|
||
if [ -f "$LOCKFILE" ]; then
|
||
exit 0 # 이미 실행 중
|
||
fi
|
||
touch "$LOCKFILE"
|
||
trap 'rm -f "$LOCKFILE"' EXIT
|
||
```
|
||
|
||
### 3. 클린업 트랩
|
||
|
||
스크립트 종료 시 tmux 세션 정리
|
||
|
||
```bash
|
||
cleanup() {
|
||
tmux kill-session -t "$TMUX_SESSION" 2>/dev/null || true
|
||
rm -f "$LOCKFILE"
|
||
}
|
||
trap cleanup EXIT INT TERM
|
||
```
|
||
|
||
### 4. 로그 권한
|
||
|
||
Claude 세션 로그에 민감한 정보 포함될 수 있음
|
||
|
||
```bash
|
||
touch "$SESSION_LOG"
|
||
chmod 600 "$SESSION_LOG"
|
||
```
|
||
|
||
---
|
||
|
||
## 복구 프롬프트 설계
|
||
|
||
Claude에게 전달하는 프롬프트가 핵심이다.
|
||
|
||
```bash
|
||
recovery_command="OpenClaw 게이트웨이가 5분간 재시작했으나 복구되지 않았습니다.
|
||
|
||
작업 순서:
|
||
1. openclaw status 체크
|
||
2. 로그 분석 (~/.openclaw/logs/*.log)
|
||
3. 설정 검증 (~/.openclaw/openclaw.json)
|
||
4. 포트 충돌 체크 (lsof -i :18789)
|
||
5. 의존성 체크 (npm list, node --version)
|
||
6. 복구 시도 (설정 수정, 프로세스 재시작)
|
||
7. 결과를 $REPORT_FILE 에 기록
|
||
|
||
작업 제한시간: ${RECOVERY_TIMEOUT}초 이내
|
||
목표: Gateway가 $GATEWAY_URL 에서 HTTP 200 응답하도록 복구"
|
||
```
|
||
|
||
**설계 원칙:**
|
||
- 명확한 목표 (HTTP 200)
|
||
- 순서가 있는 작업 목록
|
||
- 타임아웃 명시
|
||
- 결과 기록 요청
|
||
|
||
---
|
||
|
||
## 실제 복구 사례
|
||
|
||
### Case 1: 설정 파일 문법 오류 (2026-02-05)
|
||
|
||
**증상:** Gateway 시작 실패, 로그에 "JSON parse error"
|
||
|
||
**Claude 진단:**
|
||
```
|
||
[분석] ~/.openclaw/openclaw.json 열어봄
|
||
[발견] 라인 47: 쉼표 누락
|
||
[조치] jq로 포맷 후 저장
|
||
[확인] openclaw gateway restart → 성공
|
||
```
|
||
|
||
### Case 2: 포트 충돌 (2026-02-06)
|
||
|
||
**증상:** "EADDRINUSE: address already in use"
|
||
|
||
**Claude 진단:**
|
||
```
|
||
[분석] lsof -i :18789
|
||
[발견] 좀비 프로세스 PID 12345
|
||
[조치] kill -9 12345
|
||
[확인] 재시작 → HTTP 200
|
||
```
|
||
|
||
---
|
||
|
||
## Trade-off: Claude API 비용
|
||
|
||
30분 세션 비용 추정:
|
||
- Input: ~2,000 tokens × $0.003/1K = $0.006
|
||
- Output: ~5,000 tokens × $0.015/1K = $0.075
|
||
- **총 비용: ~$0.08/복구**
|
||
|
||
**월간 추정:**
|
||
- 복구 2회/월 × $0.08 = **$0.16/월**
|
||
|
||
야간 수동 대응 비용 대비 **무시할 수준**.
|
||
|
||
---
|
||
|
||
## 개선 아이디어
|
||
|
||
### 1. 복구 패턴 학습
|
||
|
||
성공한 복구 로그를 수집하여 다음 복구에 참조:
|
||
|
||
```bash
|
||
# 성공 시 패턴 저장
|
||
if [ "$SUCCESS" = "true" ]; then
|
||
cp "$SESSION_LOG" "$LOG_DIR/successful-recoveries/"
|
||
fi
|
||
```
|
||
|
||
### 2. 다른 LLM 지원
|
||
|
||
Claude 할당량 소진 시 GPT-4 또는 Gemini로 폴백:
|
||
|
||
```bash
|
||
if ! check_claude_quota; then
|
||
LLM_COMMAND="openai-cli" # 또는 gemini
|
||
fi
|
||
```
|
||
|
||
### 3. Slack/Telegram 알림
|
||
|
||
Discord 외 다른 채널 지원
|
||
|
||
---
|
||
|
||
## 마무리
|
||
|
||
Level 3 Claude Doctor는 **"규칙으로 정의할 수 없는 장애"**를 처리한다.
|
||
|
||
핵심 포인트:
|
||
1. tmux PTY로 인터랙티브 세션 제공
|
||
2. 폴링으로 조기 완료 감지
|
||
3. 안전장치로 무한 루프 방지
|
||
4. 명확한 프롬프트로 목표 전달
|
||
|
||
**다음 편 예고:** Level 4 Discord 알림과 전체 시스템 통합
|
||
|
||
---
|
||
|
||
#### 읽어주셔서 감사합니다.🖐
|