게이트웨이 장애를 견디는 탄력적인 분산 AI 에이전트 시스템 구축 방법

Source: Dev.to

TL;DR

게이트웨이가 WebSocket 또는 네트워크 장애를 겪어도 스킬이 계속 실행되도록 분산 AI‑에이전트 설계를 구현했습니다. 세션 관리는 실행 인프라와 분리되어 자동(크론‑기반) 스킬에 대해 100 % 가동 시간을 보장합니다.

Architecture Overview

OpenClaw은 세 개의 독립적인 구성 요소로 이루어져 있습니다:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Session Layer  │    │  Gateway Core    │    │  Skill Runtime  │
│  (WebSocket)    │◄──►│  (HTTP/REST)     │◄──►│  (File/Process)│
└─────────────────┘    └──────────────────┘    └─────────────────┘
      ↕ ERROR                  ↕ OK                 ↕ OK
  History/State            API Calls         Skill Execution/FileIO

• Session Layer – WebSocket 연결을 처리하고 세션 히스토리를 유지합니다.
• Gateway Core – 스킬 오케스트레이션을 위한 HTTP/REST API를 제공합니다.
• Skill Runtime – 파일 기반 프로세스로 스킬을 실행하며, 세션 레이어와는 독립적입니다.

Key insight: WebSocket 오류는 Session Layer에만 영향을 미치며, Core와 Runtime은 계속 작동합니다.

코드 예시

❌ 나쁨: 모든 로직이 게이트웨이에 의존

// runSkill blocks if the gateway is unavailable
async function runSkill() {
  const session = await gateway.getSession(); // Failure stops skill
  const result = await executeSkill(session);
  await gateway.updateStatus(result);
}

✅ 좋음: 세션과 독립적인 실행

// Skill execution proceeds even if session updates fail
async function runSkillIndependent() {
  // Skill execution is independent (file‑based)
  const result = await executeSkillFromFile();

  // Session updates are best‑effort
  try {
    await gateway.updateStatus(result);
  } catch (error) {
    console.log('Session update failed, but skill succeeded');
  }
}

스킬 상태 영구 저장 (Bash)

# Store status of the daily‑memory skill
echo "status=success,timestamp=$(date)" > ~/.openclaw/skills/status/daily-memory.txt

# Store status of the TikTok poster skill
echo "posts=4,account=en,last_run=$(date)" > ~/.openclaw/skills/status/tiktok-poster.txt

헬스 체크 스크립트 (Bash)

#!/bin/bash
GATEWAY_STATUS=$(curl -s http://localhost:3019/health || echo "FAIL")
SKILL_STATUS=$(find ~/.openclaw/skills/status -name "*.txt" -mmin -60 | wc -l)

if [[ "$GATEWAY_STATUS" == "FAIL" && "$SKILL_STATUS" -gt 0 ]]; then
  echo "⚠️ Gateway down but skills running - Graceful degradation mode"
else
  echo "✅ All systems operational"
fi

Failure Scenarios

Metrics (observed on a Mac Mini / VPS)

• Uptime: 100 % (no skill downtime)
• Gateway connection issues: 3 occurrences
• Skill execution success rate: 100 % (including during failures)
• Auto‑recovery time: average 30 seconds

교훈

관심사의 분리

세션 관리를 비즈니스 로직과 분리하여 연쇄적인 실패를 방지합니다.

파일 기반 상태

상태를 파일 시스템에 영구 저장하여 네트워크 의존성을 피하고 빠른 복구를 가능하게 합니다.

우아한 감소

전체 중단보다 제한된 기능을 제공하여 더 나은 사용자 경험을 유지합니다.

분산 모니터링

각 레이어에 독립적인 상태 검사를 배치하여 단일 실패 지점을 방지합니다.

분산 시스템에서는 “실패 시 부분적인 기능 제공”이 “전부 혹은 전무”보다 낫습니다. OpenClaw의 설계는 회복력 있는 패턴이 모든 AI‑에이전트 아키텍처에 실용적이고 효과적임을 보여줍니다.