​

모델 폴백

1. 현재 제공자 내에서의 인증 프로필 순환
2. agents.defaults.model.fallbacks의 다음 모델로의 모델 폴백

​

런타임 흐름

1. 현재 선택된 세션 모델
2. 순서대로 구성된 agents.defaults.model.fallbacks
3. 실행이 오버라이드에서 시작된 경우 마지막에 구성된 기본 모델

1. 활성 세션 모델과 인증 프로필 기본 설정을 확인합니다.
2. 모델 후보 체인을 구성합니다.
3. 인증 프로필 순환/쿨다운 규칙으로 현재 제공자를 시도합니다.
4. 해당 제공자가 폴백할 가치가 있는 오류로 모두 소진되면 다음 모델 후보로 이동합니다.
5. 재시도가 시작되기 전에 선택된 폴백 오버라이드를 유지하여 다른 세션 리더가 러너가 곧 사용할 동일한 제공자/모델을 보도록 합니다.
6. 폴백 후보가 실패하면 여전히 해당 실패한 후보와 일치하는 경우에만 폴백이 소유한 세션 오버라이드 필드를 롤백합니다.
7. 모든 후보가 실패하면 각 시도별 세부 정보와, 알 수 있는 경우 가장 이른 쿨다운 만료 시점을 포함한 FallbackSummaryError를 발생시킵니다.

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

인증 저장소(키 + OAuth)

• 시크릿은 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json에 저장됩니다(레거시: ~/.openclaw/agent/auth-profiles.json).
• 런타임 인증 라우팅 상태는 ~/.openclaw/agents/<agentId>/agent/auth-state.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:user@gmail.com)

​

순환 순서

1. 명시적 구성: auth.order[provider](설정된 경우)
2. 구성된 프로필: 제공자로 필터링된 auth.profiles
3. 저장된 프로필: 해당 제공자의 auth-profiles.json 항목

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

​

세션 고정성(캐시 친화적)

• 세션이 재설정됨(/new / /reset)
• 컴팩션이 완료됨(컴팩션 카운트 증가)
• 프로필이 쿨다운/비활성화 상태임

​

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

• auth.order[provider] = ["provider:profileId"]로 고정하거나
• 세션별 오버라이드가 있는 /model …을 사용합니다(사용 중인 UI/채팅 표면에서 지원되는 경우).

​

쿨다운

• OpenClaw는 실패한 모델 ID를 알 수 있을 때 속도 제한 실패에 대해 cooldownModel을 기록합니다.
• 동일한 제공자에 있는 형제 모델은 쿨다운 범위가 다른 모델에 지정된 경우에도 여전히 시도할 수 있습니다.
• 과금/비활성화 기간은 모델 전반에서 전체 프로필을 계속 차단합니다.

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

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

​

과금 비활성화

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

• 과금 백오프는 5시간에서 시작하여 과금 실패마다 두 배가 되고 24시간에서 상한에 도달합니다.
• 프로필이 24시간 동안 실패하지 않으면 백오프 카운터가 재설정됩니다(구성 가능).
• 과부하 재시도는 모델 폴백 전에 동일 제공자 프로필 순환 1회를 허용합니다.
• 과부하 재시도는 기본적으로 0ms 백오프를 사용합니다.

​

모델 폴백

​

후보 체인 규칙

• 요청된 모델은 항상 첫 번째입니다.
• 명시적으로 구성된 폴백은 중복 제거되지만 모델 허용 목록에 따라 필터링되지는 않습니다. 이는 명시적인 운영자 의도로 취급됩니다.
• 현재 실행이 동일한 제공자 계열의 구성된 폴백 위에 이미 있는 경우, OpenClaw는 전체 구성 체인을 계속 사용합니다.
• 현재 실행이 구성과 다른 제공자에 있고, 해당 현재 모델이 구성된 폴백 체인의 일부가 아닌 경우, OpenClaw는 다른 제공자의 관련 없는 구성된 폴백을 추가하지 않습니다.
• 실행이 오버라이드에서 시작된 경우, 앞선 후보가 모두 소진되면 체인이 다시 일반 기본값으로 정착할 수 있도록 구성된 기본 모델이 끝에 추가됩니다.

​

어떤 오류가 폴백을 진행시키는가

• 인증 실패
• 속도 제한 및 쿨다운 소진
• 과부하/제공자 바쁨 오류
• 타임아웃 형태의 폴백 오류
• 과금 비활성화
• LiveSessionModelSwitchError는 폴백 경로로 정규화되어 오래된 유지 모델이 외부 재시도 루프를 만들지 않도록 합니다
• 다른 인식되지 않은 오류도 여전히 남은 후보가 있는 경우

• 타임아웃/폴백 형태가 아닌 명시적 중단
• 컴팩션/재시도 로직 내부에 머물러야 하는 컨텍스트 오버플로 오류 (예: request_too_large, INVALID_ARGUMENT: input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, The input is too long for the model, ollama error: context length exceeded)
• 남은 후보가 없을 때의 최종 알 수 없는 오류

​

쿨다운 건너뛰기 vs 프로브 동작

• 지속적인 인증 실패는 전체 제공자를 즉시 건너뜁니다.
• 과금 비활성화는 일반적으로 건너뛰지만, 기본 후보는 재시작 없이 복구할 수 있도록 스로틀을 두고 여전히 프로브될 수 있습니다.
• 기본 후보는 쿨다운 만료에 가까워지면 제공자별 스로틀을 두고 프로브될 수 있습니다.
• 동일 제공자 폴백 형제 모델은 실패가 일시적으로 보일 때(rate_limit, overloaded 또는 알 수 없음) 쿨다운 상태여도 시도될 수 있습니다. 이는 속도 제한이 모델 범위이고 형제 모델이 여전히 즉시 복구될 수 있는 경우에 특히 중요합니다.
• 일시적인 쿨다운 프로브는 폴백 실행당 제공자별로 하나로 제한되므로, 단일 제공자가 교차 제공자 폴백을 지연시키지 않습니다.

​

세션 오버라이드와 라이브 모델 전환

• 명시적인 사용자 주도 모델 변경만 보류 중인 라이브 전환을 표시합니다. 여기에는 /model, session_status(model=...), sessions.patch가 포함됩니다.
• 폴백 순환, 하트비트 오버라이드, 컴팩션 같은 시스템 주도 모델 변경은 자체적으로 보류 중인 라이브 전환을 표시하지 않습니다.
• 폴백 재시도가 시작되기 전에 응답 러너는 선택된 폴백 오버라이드 필드를 세션 항목에 유지합니다.
• 라이브 세션 조정은 오래된 런타임 모델 필드보다 유지된 세션 오버라이드를 우선합니다.
• 폴백 시도가 실패하면 러너는 자신이 쓴 오버라이드 필드만, 그리고 여전히 해당 실패한 후보와 일치하는 경우에만 롤백합니다.

1. 기본 모델이 실패합니다.
2. 메모리에서 폴백 후보가 선택됩니다.
3. 세션 저장소에는 여전히 이전 기본 모델이 기록되어 있습니다.
4. 라이브 세션 조정이 오래된 세션 상태를 읽습니다.
5. 재시도가 폴백 시도가 시작되기 전에 이전 모델로 되돌려집니다.

​

가시성과 실패 요약

• 시도한 제공자/모델
• 이유(rate_limit, overloaded, billing, auth, model_not_found 및 유사한 폴백 이유)
• 선택적 상태/코드
• 사람이 읽을 수 있는 오류 요약

• 시도된 제공자/모델 체인과 무관한 모델 범위 속도 제한은 무시됩니다.
• 남아 있는 차단이 일치하는 모델 범위 속도 제한인 경우, OpenClaw는 여전히 해당 모델을 차단하는 마지막 일치 만료 시점을 보고합니다.

​

관련 구성

• 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 라우팅