6.2 KiB
6.2 KiB
title, date, category, tags, draft, description
| title | date | category | tags | draft | description | |||||
|---|---|---|---|---|---|---|---|---|---|---|
| OpenClaw 자가복구 시스템 Part 2 - Claude Code를 응급의사로 활용하기 | 2026-02-07 | AI |
|
true | 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번 재시도해도 실패하면, 단순 재시작으로는 해결 안 되는 문제다.
이때 필요한 건:
- 로그 분석 — 에러 메시지 확인
- 설정 검증 — JSON 문법 오류, 포트 충돌 등
- 의존성 체크 — Node.js 버전, npm 패키지 상태
- 지능적 판단 — 어떤 조치를 취할지 결정
이걸 규칙 기반으로 하면? 새로운 에러 패턴마다 코드 수정 필요. Claude에게 맡기면? "이 로그 보고 알아서 고쳐" 가 가능.
tmux PTY가 필요한 이유
Claude Code는 단순 파이프(echo "명령" | claude)로는 제대로 작동 안 한다.
이유:
- 인터랙티브 모드 필요 (워크스페이스 신뢰 프롬프트)
- 실시간 출력 캡처
- 멀티턴 대화 지원
해결책: tmux PTY 세션
# 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 고정 대기
초기 구현 (비효율)
sleep 1800 # 30분 무조건 대기
문제: Claude가 5분 만에 끝나도 30분 기다림
개선된 구현 (폴링)
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가 무한 루프에 빠지거나 응답 없을 때 대비
RECOVERY_TIMEOUT="${EMERGENCY_RECOVERY_TIMEOUT:-1800}"
2. 락 파일
동시 실행 방지 (Health Check가 중복 호출할 때)
# 보안 경로 (다른 사용자 접근 불가)
LOCKFILE="$LOG_DIR/.emergency-recovery.lock"
if [ -f "$LOCKFILE" ]; then
exit 0 # 이미 실행 중
fi
touch "$LOCKFILE"
trap 'rm -f "$LOCKFILE"' EXIT
3. 클린업 트랩
스크립트 종료 시 tmux 세션 정리
cleanup() {
tmux kill-session -t "$TMUX_SESSION" 2>/dev/null || true
rm -f "$LOCKFILE"
}
trap cleanup EXIT INT TERM
4. 로그 권한
Claude 세션 로그에 민감한 정보 포함될 수 있음
touch "$SESSION_LOG"
chmod 600 "$SESSION_LOG"
복구 프롬프트 설계
Claude에게 전달하는 프롬프트가 핵심이다.
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. 복구 패턴 학습
성공한 복구 로그를 수집하여 다음 복구에 참조:
# 성공 시 패턴 저장
if [ "$SUCCESS" = "true" ]; then
cp "$SESSION_LOG" "$LOG_DIR/successful-recoveries/"
fi
2. 다른 LLM 지원
Claude 할당량 소진 시 GPT-4 또는 Gemini로 폴백:
if ! check_claude_quota; then
LLM_COMMAND="openai-cli" # 또는 gemini
fi
3. Slack/Telegram 알림
Discord 외 다른 채널 지원
마무리
Level 3 Claude Doctor는 **"규칙으로 정의할 수 없는 장애"**를 처리한다.
핵심 포인트:
- tmux PTY로 인터랙티브 세션 제공
- 폴링으로 조기 완료 감지
- 안전장치로 무한 루프 방지
- 명확한 프롬프트로 목표 전달
다음 편 예고: Level 4 Discord 알림과 전체 시스템 통합