​

모델 페일오버

1. 현재 프로바이더 내에서의 인증 프로필 회전.
2. agents.defaults.model.fallbacks 에서 다음 모델로의 모델 폴백.

​

인증 스토리지 (키 + OAuth)

• 시크릿은 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 에 저장됩니다 (레거시: ~/.openclaw/agent/auth-profiles.json).
• 구성 auth.profiles / auth.order 는 메타데이터 + 라우팅 전용입니다 (시크릿 없음).
• 레거시 가져오기 전용 OAuth 파일: ~/.openclaw/credentials/oauth.json (첫 사용 시 auth-profiles.json 로 가져와짐).

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (일부 프로바이더의 경우 projectId/enterpriseUrl 포함)

​

프로필 ID

• 기본값: 이메일을 사용할 수 없는 경우 provider:default.
• 이메일이 있는 OAuth: provider:<email> (예: google-antigravity:[email protected]).

​

회전 순서

1. 명시적 구성: auth.order[provider] (설정된 경우).
2. 구성된 프로필: 프로바이더로 필터링된 auth.profiles.
3. 저장된 프로필: 해당 프로바이더에 대한 auth-profiles.json 항목.

• 기본 키: 프로필 유형 (OAuth 가 API 키보다 우선).
• 보조 키: usageStats.lastUsed (각 유형 내에서 오래된 것부터).
• 쿨다운/비활성화된 프로필은 만료가 가장 빠른 순으로 정렬되어 맨 뒤로 이동합니다.

​

세션 고정 (캐시 친화적)

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

​

OAuth 가 “사라진 것처럼 보일 수 있는” 이유

• auth.order[provider] = ["provider:profileId"] 으로 고정, 또는
• 지원되는 UI/채팅 환경에서 프로필 오버라이드를 사용하여 /model … 를 통한 세션별 오버라이드

​

쿨다운

• 1분
• 5분
• 25분
• 1시간 (상한)

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

​

결제 비활성화

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

• 결제 백오프는 5시간에서 시작하여 결제 실패마다 두 배로 증가하며 24시간에서 상한을 가집니다.
• 프로필이 24시간 동안 실패하지 않으면 백오프 카운터가 리셋됩니다 (구성 가능).

​

모델 폴백

​

관련 구성

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