​

모델 대체

1. 현재 provider 내부에서 인증 프로필 순환
2. agents.defaults.model.fallbacks의 다음 모델로 모델 대체

​

런타임 흐름

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

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

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

인증 저장소(키 + OAuth)

• 비밀 정보는 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json에 저장됩니다(레거시: ~/.openclaw/agent/auth-profiles.json).
• config auth.profiles / auth.order는 메타데이터 + 라우팅 전용입니다(비밀 정보 없음).
• 레거시 가져오기 전용 OAuth 파일: ~/.openclaw/credentials/oauth.json(첫 사용 시 auth-profiles.json으로 가져옴).

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? }(+ 일부 provider용 projectId/enterpriseUrl)

​

프로필 ID

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

​

순환 순서

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

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

​

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

• 세션이 재설정될 때(/new / /reset)
• compaction이 완료될 때(compaction count 증가)
• 프로필이 쿨다운/비활성화 상태일 때

​

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

• auth.order[provider] = ["provider:profileId"]로 고정하거나
• 세션별 재정의가 가능한 UI/채팅 표면에서는 프로필 재정의를 포함한 /model …로 세션별 재정의를 사용합니다.

​

쿨다운

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

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

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

​

과금 비활성화

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

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

​

모델 대체

​

후보 체인 규칙

• 요청된 모델은 항상 첫 번째입니다.
• 명시적으로 구성된 대체 모델은 중복 제거되지만 모델 허용 목록으로 필터링되지는 않습니다. 이는 명시적인 운영자 의도로 취급됩니다.
• 현재 실행이 동일 provider 패밀리의 구성된 대체 모델 위에 이미 있는 경우, OpenClaw는 전체 구성 체인을 계속 사용합니다.
• 현재 실행이 config와 다른 provider에 있고 그 현재 모델이 구성된 대체 체인의 일부가 아니라면, OpenClaw는 다른 provider의 관련 없는 구성된 대체 모델을 추가하지 않습니다.
• 실행이 재정의에서 시작된 경우, 이전 후보가 모두 소진되면 체인이 일반 기본값으로 다시 안정화될 수 있도록 구성된 기본 모델이 마지막에 추가됩니다.

​

어떤 오류가 대체를 진행시키는가

• 인증 실패
• 속도 제한 및 쿨다운 소진
• 과부하/provider-busy 오류
• 타임아웃 형태의 대체 오류
• 과금 비활성화
• LiveSessionModelSwitchError(정규화되어 대체 경로로 처리되므로 오래된 유지 모델이 외부 재시도 루프를 만들지 않음)
• 남은 후보가 있을 때의 기타 인식되지 않은 오류

• 타임아웃/대체 형태가 아닌 명시적 중단
• compaction/재시도 로직 내부에 남아 있어야 하는 컨텍스트 오버플로 오류 (예: 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 프로브 동작

• 지속적인 인증 실패는 전체 provider를 즉시 건너뜁니다.
• 과금 비활성화는 보통 건너뛰지만, 재시작 없이 복구가 가능하도록 기본 후보는 throttling 하에서 여전히 프로브될 수 있습니다.
• 기본 후보는 provider별 throttling과 함께 쿨다운 만료 시점 근처에서 프로브될 수 있습니다.
• 실패가 일시적(rate_limit, overloaded 또는 unknown)으로 보이면 동일 provider의 대체 형제 모델은 쿨다운에도 불구하고 시도될 수 있습니다. 이는 속도 제한이 모델 범위이고 형제 모델이 즉시 복구될 수 있는 경우 특히 중요합니다.
• 일시적 쿨다운 프로브는 대체 실행당 provider별 1회로 제한되어 단일 provider가 교차 provider 대체를 지연시키지 않도록 합니다.

​

세션 재정의와 실시간 모델 전환

• 명시적인 사용자 주도 모델 변경만 보류 중인 실시간 전환으로 표시됩니다. 여기에는 /model, session_status(model=...), sessions.patch가 포함됩니다.
• 대체 순환, heartbeat 재정의, compaction 같은 시스템 주도 모델 변경은 자체적으로 보류 중인 실시간 전환을 표시하지 않습니다.
• 대체 재시도가 시작되기 전에 답장 러너는 선택된 대체 재정의 필드를 세션 항목에 유지합니다.
• 실시간 세션 조정은 오래된 런타임 모델 필드보다 유지된 세션 재정의를 우선합니다.
• 대체 시도가 실패하면 러너는 자신이 쓴 재정의 필드만 롤백하며, 그것도 여전히 실패한 후보와 일치할 때만 수행합니다.

1. 기본 모델 실패
2. 메모리에서 대체 후보 선택
3. 세션 저장소에는 여전히 이전 기본 모델이 기록됨
4. 실시간 세션 조정이 오래된 세션 상태를 읽음
5. 대체 시도가 시작되기 전에 재시도가 이전 모델로 되돌아감

​

관측 가능성 및 실패 요약

• 시도한 provider/model
• 이유(rate_limit, overloaded, billing, auth, model_not_found 및 유사한 대체 이유)
• 선택적 status/code
• 사람이 읽을 수 있는 오류 요약

• 시도한 provider/model 체인과 관련 없는 모델 범위 속도 제한은 무시됩니다
• 남은 차단이 일치하는 모델 범위 속도 제한인 경우, OpenClaw는 여전히 해당 모델을 차단하는 마지막 일치 만료 시각을 보고합니다

​

관련 config

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