OpenClaw 다중 모델 장애 조치 및 자동 전환

장애 조치가 필요한 이유

프로덕션 환경에서 단일 모델 제공자에 의존하는 것은 큰 위험입니다. API 서비스는 서버 유지보수, 지역적 네트워크 장애, 속도 제한, 계정 잔액 부족, 심지어 제공자의 전면적 다운타임 등 여러 이유로 사용 불가능해질 수 있습니다. AI 애플리케이션에 장애 조치 메커니즘이 없다면, 어느 한 제공자의 문제가 서비스의 완전한 중단으로 직결됩니다.

OpenClaw은 다중 계정 인증 순환, 쿨다운 추적, 크로스 제공자 자동 전환의 세 가지 계층을 아우르는 성숙한 다중 모델 장애 조치 시스템을 내장하고 있습니다. 이 글에서는 이 메커니즘의 작동 원리와 설정 방법을 심층적으로 설명합니다.

1단계: 다중 계정 인증 순환

장애 조치의 첫 번째 방어선은 동일 제공자 내의 다중 계정 순환입니다. 각 제공자에 여러 API 키(profile)를 설정하면, OpenClaw이 문제를 만났을 때 자동으로 다음 사용 가능한 키로 전환합니다.

{
  "providers": {
    "anthropic": {
      "auth": [
        { "key": "sk-ant-key-001", "profile": "팀 기본 계정" },
        { "key": "sk-ant-key-002", "profile": "개인 백업" },
        { "key": "sk-ant-key-003", "profile": "비상 계정" }
      ]
    }
  }
}

작동 메커니즘

OpenClaw이 첫 번째 profile로 요청을 보낼 때, 인증 실패(401), 속도 제한(429), 서버 오류(500/502/503)를 만나면 시스템이:

현재 profile을 즉시 "쿨다운 중" 상태로 표시합니다.
실패 시간을 기록하고 쿨다운 타이머를 시작합니다.
auth 배열의 다음 profile로 자동 전환하여 요청을 재시도합니다.
모든 profile이 쿨다운 상태이면, 제공자 수준의 장애 조치를 트리거합니다.

쿨다운 추적 메커니즘

쿨다운 추적은 OpenClaw 장애 조치 시스템의 핵심 컴포넌트입니다. 시스템이 이미 문제가 있는 키를 반복 시도하는 것을 방지하면서도, 복구된 키가 다시 활성화되도록 보장합니다.

쿨다운 추적의 핵심 동작:

실패 기록: 요청 실패 시마다 실패 유형과 타임스탬프를 기록합니다.
점진적 쿨다운: 연속 실패 횟수가 많을수록 쿨다운 시간이 길어져, 이미 제한된 계정에 대한 빈번한 재시도를 방지합니다.
자동 복구: 쿨다운 기간이 끝나면 해당 profile이 자동으로 사용 가능 상태로 복구되어 정상 순환 스케줄링에 참여합니다.
오류 유형별 차별화: 인증 오류(401)의 쿨다운 시간은 보통 더 길고, 속도 제한(429)의 쿨다운 시간은 상대적으로 짧습니다.

2단계: 크로스 제공자 장애 조치

특정 제공자의 모든 키가 사용 불가능해지면, OpenClaw은 크로스 제공자 장애 조치를 수행하여 요청을 백업 모델로 라우팅합니다.

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-5",
        "fallback": "openai/gpt-4o"
      }
    }
  }
}

장애 조치 체인

다단계 장애 조치를 설정하여 완전한 장애 조치 체인을 구성할 수 있습니다:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-5",
        "fallback": "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
        "fallback2": "openai/gpt-4o",
        "fallback3": "openrouter/anthropic/claude-3.5-sonnet"
      }
    }
  }
}

이 설정은 4단계 장애 조치를 구성합니다:

Anthropic 직접 API를 우선 사용합니다.
Anthropic 직접 연결이 불가능하면, AWS Bedrock을 통해 Claude에 접근합니다.
Bedrock도 불가능하면, OpenAI의 GPT-4o로 전환합니다.
마지막으로 OpenRouter를 최종 백업으로 사용합니다.

3단계: OpenRouter를 메타 제공자로 활용

OpenRouter는 장애 조치 전략에서 특별한 역할을 합니다. 여러 모델 제공자를 집약하는 메타 플랫폼으로서, OpenRouter 자체가 라우팅과 장애 조치 능력을 갖추고 있습니다. 장애 조치 체인의 끝에 OpenRouter를 배치하면 최후의 안전망 역할을 합니다.

{
  "providers": {
    "openrouter": {
      "auth": [
        { "key": "OpenRouter 키" }
      ]
    }
  }
}

OpenRouter를 통해 xAI(Grok), Groq, Mistral 등 여러 제공자의 모델에 접근할 수 있어, 시스템의 탄력성을 더욱 높입니다.

실제 배포 권장사항

권장 장애 조치 전략

프로덕션 환경을 위한 권장 설정 템플릿:

{
  "providers": {
    "anthropic": {
      "auth": [
        { "key": "키A", "profile": "기본" },
        { "key": "키B", "profile": "백업" }
      ]
    },
    "openai": {
      "auth": [
        { "key": "키C", "profile": "기본" }
      ]
    },
    "openrouter": {
      "auth": [
        { "key": "키D", "profile": "기본" }
      ]
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-5",
        "fallback": "openai/gpt-4o",
        "fallback2": "openrouter/anthropic/claude-3.5-sonnet"
      }
    }
  }
}

핵심 원칙

동일 수준 백업 우선: 먼저 같은 제공자 내에서 키 순환을 하고, 그 다음에 크로스 제공자 전환을 합니다.
능력 매칭: 장애 조치 체인의 모델은 유사한 능력 수준이어야 하며, 사용자 경험의 급격한 변동을 방지합니다.
비용 인식: 백업 모델의 비용이 다를 수 있으므로, 각 모델의 가격을 파악해야 합니다.
테스트 검증: 장애 조치 체인의 각 모델이 사용 가능한지 정기적으로 테스트하여, 실제 장애 시 백업도 불가능한 상황을 방지합니다.

모니터링 및 알림

OpenClaw의 로그는 매번 장애 조치 이벤트를 기록합니다. 다음 핵심 지표를 모니터링하는 것을 권장합니다:

장애 조치 트리거 빈도.
각 profile의 쿨다운 상태.
요청의 평균 지연(장애 조치는 보통 지연을 증가시킴).

다중 계정 인증과 크로스 제공자 장애 조치를 적절히 설정하면, OpenClaw 배포가 거의 100%의 가용성을 달성할 수 있으며, 단일 제공자의 심각한 장애에도 서비스 연속성을 유지할 수 있습니다.