OpenClaw 모델 Failover 및 인증 프로필 최적화 가이드

개발을 하다 보면 API 할당량이 갑자기 다 차거나, 인증 오류 때문에 작업이 흐름이 끊기는 상황을 자주 겪게 되죠. 특히 여러 모델을 복합적으로 사용할 때 이런 예외 상황을 일일이 대응하는 것은 무척 번거로운 일이에요.

OpenClaw는 이런 문제를 해결하기 위해 두 단계로 장애 조치(failover)를 처리해요. 먼저 현재 사용 중인 Provider 내에서 Auth profile을 교체하고, 그래도 해결되지 않으면 agents.defaults.model.fallbacks에 정의된 다음 모델로 Model fallback을 시도합니다. 이 문서에서는 이러한 런타임 규칙과 이를 뒷받침하는 데이터 구조를 살펴볼게요.

Auth storage (keys + OAuth)

OpenClaw는 API key와 OAuth 토큰 모두에 auth profiles를 사용해요.

• 보안 정보(Secrets)는 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json에 저장됩니다. (이전 버전: ~/.openclaw/agent/auth-profiles.json)
• 설정 파일의 auth.profiles와 auth.order는 메타데이터와 라우팅 용도로만 쓰이며, 실제 보안 정보는 포함하지 않아요.
• 레거시 OAuth 파일인 ~/.openclaw/credentials/oauth.json은 처음 실행될 때 auth-profiles.json으로 자동 임포트됩니다.

더 자세한 내용은 /concepts/oauth에서 확인할 수 있어요.

자격 증명 유형은 다음과 같아요:

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (일부 Provider는 projectId나 enterpriseUrl이 추가될 수 있음)

Profile IDs

OAuth 로그인을 하면 여러 계정을 동시에 사용할 수 있도록 별도의 프로필이 생성돼요.

• 기본값: 이메일 정보가 없을 때 provider:default
• 이메일이 있는 OAuth: provider:<email> (예: google-antigravity:user@gmail.com)

이 프로필들은 auth-profiles.json 파일의 profiles 항목 아래에 저장됩니다.

Rotation order

하나의 Provider에 여러 프로필이 있을 때, OpenClaw는 다음 순서에 따라 프로필을 선택해요:

1. 명시적 설정: auth.order[provider]가 설정되어 있는 경우
2. 설정된 프로필: Provider로 필터링된 auth.profiles
3. 저장된 프로필: auth-profiles.json에 있는 해당 Provider의 항목들

명시적인 순서가 지정되지 않았다면 라운드 로빈(round-robin) 방식을 사용합니다:

• 1순위 기준: 프로필 유형 (OAuth가 API key보다 우선)
• 2순위 기준: usageStats.lastUsed (각 유형 내에서 가장 오래전에 사용된 것부터)
• 쿨다운/비활성화된 프로필: 가장 빨리 만료되는 순서대로 정렬하여 맨 뒤로 이동

Session stickiness (캐시 친화적 동작)

OpenClaw는 Provider 캐시를 효율적으로 활용하기 위해 **세션당 선택된 인증 프로필을 고정(pin)**해요. 모든 요청마다 프로필을 바꾸지 않는다는 뜻이죠. 고정된 프로필은 다음 상황이 오기 전까지 계속 재사용됩니다:

• 세션이 리셋될 때 (/new 또는 /reset)
• Compaction이 완료될 때 (Compaction 카운트 증가)
• 프로필이 쿨다운 상태이거나 비활성화되었을 때

/model …@<profileId> 명령어를 통해 수동으로 선택하면 해당 세션에 대해 사용자 오버라이드가 설정되며, 새 세션이 시작되기 전까지는 자동으로 교체되지 않아요.

세션 라우터가 자동으로 고정한 프로필은 일종의 선호도로 취급됩니다. 우선적으로 시도하되, Rate limit이나 Timeout이 발생하면 다른 프로필로 교체할 수 있어요. 반면 사용자가 직접 고정한 프로필은 해당 프로필에 완전히 잠깁니다. 만약 실패하더라도 프로필을 바꾸지 않고, 설정된 Model fallback이 있다면 바로 다음 모델로 넘어갑니다.

OAuth 프로필이 사라진 것처럼 보일 때

동일한 Provider에 OAuth 프로필과 API key 프로필이 모두 있는 경우, 고정되지 않은 상태에서는 라운드 로빈 방식 때문에 메시지마다 프로필이 바뀔 수 있어요. 특정 프로필만 강제로 사용하려면 다음 방법을 쓰세요:

• auth.order[provider] = ["provider:profileId"]로 순서를 고정하세요.
• UI나 채팅 인터페이스에서 지원한다면 /model … 명령어로 세션 오버라이드를 사용하세요.

Cooldowns

인증 오류나 Rate limit 오류(또는 Rate limit처럼 보이는 Timeout)가 발생하면, OpenClaw는 해당 프로필을 쿨다운 상태로 표시하고 다음 프로필로 이동해요. Cloud Code Assist의 도구 호출 ID 검증 실패 같은 잘못된 요청 오류도 장애 조치 대상으로 간주하여 동일한 쿨다운을 적용합니다. OpenAI 호환 오류 중 Unhandled stop reason: error, stop reason: error, reason: error 등도 Timeout이나 장애 조치 신호로 분류됩니다.

쿨다운은 지수 백오프(Exponential backoff) 방식을 사용해요:

• 1분
• 5분
• 25분
• 1시간 (최대치)

상태 정보는 auth-profiles.json의 usageStats에 저장됩니다:

{
  "usageStats": {
    "provider:profile": {
      "lastUsed": 1736160000000,
      "cooldownUntil": 1736160600000,
      "errorCount": 2
    }
  }
}

Billing disables

결제나 크레딧 문제(예: “잔액 부족”)도 장애 조치 대상이지만, 보통 일시적인 문제가 아니죠. 그래서 OpenClaw는 짧은 쿨다운 대신 해당 프로필을 비활성화(disabled) 상태로 만들고 더 긴 백오프 시간을 적용한 뒤 다음 프로필이나 Provider로 넘어갑니다.

이 상태 역시 auth-profiles.json에 저장돼요:

{
  "usageStats": {
    "provider:profile": {
      "disabledUntil": 1736178000000,
      "disabledReason": "billing"
    }
  }
}

기본 설정값은 다음과 같아요:

• 결제 백오프는 5시간부터 시작하며, 실패할 때마다 두 배로 늘어나 최대 24시간까지 적용됩니다.
• 프로필이 24시간(설정 가능) 동안 실패하지 않으면 백오프 카운터가 초기화됩니다.
• Overloaded(과부하) 재시도의 경우, 모델 폴백 전 동일 Provider 내에서 1번의 프로필 교체를 허용합니다.
• Overloaded 재시도는 기본적으로 0 ms 백오프를 사용합니다.

Model fallback

특정 Provider의 모든 프로필이 실패하면, OpenClaw는 agents.defaults.model.fallbacks에 설정된 다음 모델로 이동해요. 이는 인증 실패, Rate limit, 프로필 로테이션을 모두 소진한 Timeout 상황에 적용됩니다. (그 외의 일반적인 오류는 폴백을 실행하지 않아요.)

Overloaded 및 Rate limit 오류는 결제 관련 쿨다운보다 더 공격적으로 처리됩니다. 기본적으로 동일 Provider 내에서 인증 프로필 재시도를 한 번 허용하고, 그 후에는 대기 시간 없이 바로 다음 모델 폴백으로 전환해요. 이 동작은 auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs, auth.cooldowns.rateLimitedProfileRotations 설정을 통해 튜닝할 수 있습니다.

Hook이나 CLI를 통해 모델 오버라이드로 실행을 시작한 경우에도, 설정된 폴백을 모두 시도한 후에는 최종적으로 agents.defaults.model.primary에서 폴백이 종료됩니다.

Related config

다음 항목들에 대한 자세한 내용은 Gateway configuration 문서를 확인해 보세요:

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel 라우팅

모델 선택과 폴백에 대한 전반적인 개요는 Models 문서에서 볼 수 있습니다.

---

다음 단계:

• Gateway 설정 가이드
• OAuth 개념 이해하기

도움이 필요하신가요? AI Setup Assistant에게 물어보세요!