모델 장애 조치

OpenClaw는 실패를 두 단계로 처리합니다.

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

이 문서는 런타임 규칙과 그 규칙을 뒷받침하는 데이터를 설명합니다.

# 런타임 흐름

일반 텍스트 실행에서 OpenClaw는 다음 순서로 후보를 평가합니다.

이는 의도적으로 "전체 세션을 저장하고 복원"하는 것보다 더 좁은 범위입니다. 응답 실행기는 폴백을 위해 자신이 소유한 모델 선택 필드만 유지합니다.

• providerOverride
• modelOverride
• modelOverrideSource
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

이렇게 하면 실패한 폴백 재시도가 실행되는 동안 발생한 수동 /model 변경이나 세션 순환 업데이트 같은 더 새로운 관련 없는 세션 변경을 덮어쓰지 않습니다.

# 선택 소스 정책

OpenClaw는 선택된 제공자/모델과 그것이 선택된 이유를 분리합니다. 해당 소스가 폴백 체인 허용 여부를 제어합니다.

• 구성된 기본값: agents.defaults.model.primary는 agents.defaults.model.fallbacks를 사용합니다.
• 에이전트 기본 모델: agents.list[].model은 해당 에이전트 모델 객체에 자체 fallbacks가 포함되어 있지 않으면 엄격합니다. 엄격한 동작을 명시하려면 fallbacks: []를 사용하고, 해당 에이전트에 모델 폴백을 사용하려면 비어 있지 않은 목록을 제공합니다.
• 자동 폴백 오버라이드: 런타임 폴백은 재시도 전에 providerOverride, modelOverride, modelOverrideSource: "auto"를 기록합니다. 이 자동 오버라이드는 구성된 폴백 체인을 계속 따라갈 수 있으며 /new, /reset, sessions.reset으로 지워집니다.
• 사용자 세션 오버라이드: /model, 모델 선택기, session_status(model=...), sessions.patch는 modelOverrideSource: "user"를 기록합니다. 이는 정확한 세션 선택입니다. 선택된 제공자/모델이 응답을 생성하기 전에 실패하면, OpenClaw는 관련 없는 구성된 폴백에서 답변하는 대신 실패를 보고합니다.
• 레거시 세션 오버라이드: 이전 세션 항목에는 modelOverrideSource 없이 modelOverride가 있을 수 있습니다. OpenClaw는 명시적인 이전 선택이 조용히 폴백 동작으로 변환되지 않도록 이를 사용자 오버라이드로 처리합니다.
• Cron 페이로드 모델: cron 작업 payload.model / --model은 사용자 세션 오버라이드가 아니라 작업 기본 모델입니다. 작업이 payload.fallbacks를 제공하지 않는 한 구성된 폴백을 사용하며, payload.fallbacks: []는 cron 실행을 엄격하게 만듭니다.

# 인증 저장소(키 + OAuth)

OpenClaw는 API 키와 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으로 가져옴).

자세한 내용: OAuth

자격 증명 유형:

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? }(일부 제공자는 projectId/enterpriseUrl 추가)

# 프로필 ID

OAuth 로그인은 여러 계정이 공존할 수 있도록 별도의 프로필을 만듭니다.

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

프로필은 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json의 profiles 아래에 있습니다.

# 순환 순서

제공자에 여러 프로필이 있으면 OpenClaw는 다음과 같은 순서를 선택합니다.

명시적인 순서가 구성되어 있지 않으면 OpenClaw는 라운드 로빈 순서를 사용합니다.

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

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

OpenClaw는 제공자 캐시를 따뜻하게 유지하기 위해 선택된 인증 프로필을 세션별로 고정합니다. 매 요청마다 순환하지 않습니다. 고정된 프로필은 다음 중 하나가 발생할 때까지 재사용됩니다.

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

/model …@<profileId>를 통한 수동 선택은 해당 세션에 사용자 오버라이드를 설정하며, 새 세션이 시작될 때까지 자동 순환되지 않습니다.

# OAuth가 "사라진 것처럼 보일" 수 있는 이유

동일한 제공자에 OAuth 프로필과 API 키 프로필이 모두 있으면, 고정되지 않은 경우 라운드 로빈이 메시지 사이에서 둘을 전환할 수 있습니다. 단일 프로필을 강제하려면:

• auth.order[provider] = ["provider:profileId"]로 고정하거나,
• UI/채팅 표면에서 지원하는 경우 프로필 오버라이드와 함께 /model …을 사용해 세션별 오버라이드를 사용합니다.

# 쿨다운

인증/속도 제한 오류(또는 속도 제한처럼 보이는 타임아웃)로 프로필이 실패하면 OpenClaw는 해당 프로필을 쿨다운으로 표시하고 다음 프로필로 이동합니다.

쿨다운은 지수 백오프를 사용합니다.

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

상태는 auth-state.json의 usageStats 아래에 저장됩니다.

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

# 청구 비활성화

청구/크레딧 실패(예: "insufficient credits" / "credit balance too low")는 페일오버 대상으로 처리되지만, 일반적으로 일시적이지 않습니다. 짧은 쿨다운 대신 OpenClaw는 프로필을 비활성화됨으로 표시하고(더 긴 백오프와 함께) 다음 프로필/제공자로 순환합니다.

상태는 auth-state.json에 저장됩니다.

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

기본값:

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

# 모델 폴백

제공자의 모든 프로필이 실패하면 OpenClaw는 agents.defaults.model.fallbacks의 다음 모델로 이동합니다. 이는 프로필 순환을 모두 소진한 인증 실패, 속도 제한, 타임아웃에 적용됩니다(다른 오류는 폴백을 진행하지 않음). 충분한 세부 정보를 노출하지 않는 제공자 오류도 폴백 상태에서 정확히 레이블이 지정됩니다. empty_response는 제공자가 사용 가능한 메시지나 상태를 반환하지 않았음을 의미하고, no_error_details는 제공자가 명시적으로 Unknown error (no error details in response)를 반환했음을 의미하며, unclassified는 OpenClaw가 원시 미리 보기를 보존했지만 아직 일치하는 분류기가 없음을 의미합니다.

과부하 및 속도 제한 오류는 결제 쿨다운보다 더 적극적으로 처리됩니다. 기본적으로 OpenClaw는 동일 제공자의 인증 프로필 재시도를 한 번 허용한 뒤, 기다리지 않고 다음으로 구성된 모델 폴백으로 전환합니다. ModelNotReadyException 같은 제공자 사용 중 신호는 해당 과부하 범주에 들어갑니다. auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs, auth.cooldowns.rateLimitedProfileRotations로 이를 조정하세요.

실행이 구성된 기본 주 모델, Cron 작업 주 모델, 명시적 폴백이 있는 에이전트 주 모델, 또는 자동 선택된 폴백 재정의에서 시작되면 OpenClaw는 일치하는 구성된 폴백 체인을 따라갈 수 있습니다. 명시적 폴백이 없는 에이전트 주 모델과 명시적 사용자 선택(예: /model ollama/qwen3.5:27b, 모델 선택기, sessions.patch, 또는 일회성 CLI 제공자/모델 재정의)은 엄격합니다. 해당 제공자/모델에 접근할 수 없거나 응답을 생성하기 전에 실패하면, OpenClaw는 관련 없는 폴백으로 응답하는 대신 실패를 보고합니다.

# 후보 체인 규칙

OpenClaw는 현재 요청된 provider/model과 구성된 폴백을 기준으로 후보 목록을 만듭니다.

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

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

제공자의 모든 인증 프로필이 이미 쿨다운 상태여도 OpenClaw는 해당 제공자를 자동으로 영원히 건너뛰지 않습니다. 후보별로 결정을 내립니다.

# 세션 재정의 및 라이브 모델 전환

세션 모델 변경은 공유 상태입니다. 활성 실행기, /model 명령, Compaction/세션 업데이트, 라이브 세션 조정은 모두 동일한 세션 항목의 일부를 읽거나 씁니다.

즉, 폴백 재시도는 라이브 모델 전환과 조율해야 합니다.

• 명시적인 사용자 주도 모델 변경만 대기 중인 라이브 전환을 표시합니다. 여기에는 /model, session_status(model=...), sessions.patch가 포함됩니다.
• 폴백 회전, Heartbeat 재정의, Compaction 같은 시스템 주도 모델 변경은 그 자체로 대기 중인 라이브 전환을 표시하지 않습니다.
• 사용자 주도 모델 재정의는 폴백 정책에서 정확한 선택으로 처리되므로, 접근할 수 없는 선택된 제공자는 agents.defaults.model.fallbacks로 가려지는 대신 실패로 표시됩니다.
• 폴백 재시도가 시작되기 전에 응답 실행기는 선택된 폴백 재정의 필드를 세션 항목에 영속화합니다.
• 자동 폴백 재정의는 이후 턴에서도 선택된 상태로 유지되므로 OpenClaw가 모든 메시지마다 알려진 불량 주 모델을 프로브하지 않습니다. /new, /reset, sessions.reset은 자동 출처 재정의를 지우고 세션을 구성된 기본값으로 되돌립니다.
• /status는 선택된 모델을 표시하며, 폴백 상태가 다를 때는 활성 폴백 모델과 이유도 표시합니다.
• 라이브 세션 조정은 오래된 런타임 모델 필드보다 영속화된 세션 재정의를 우선합니다.
• 라이브 전환 오류가 활성 폴백 체인의 이후 후보를 가리키면 OpenClaw는 관련 없는 후보를 먼저 따라가지 않고 선택된 해당 모델로 바로 이동합니다.
• 폴백 시도가 실패하면 실행기는 자신이 쓴 재정의 필드만 롤백하며, 해당 필드가 여전히 실패한 후보와 일치할 때만 롤백합니다.

이는 전형적인 경쟁 상태를 방지합니다.

영속화된 폴백 재정의가 이 틈을 닫고, 좁은 범위의 롤백은 더 최신의 수동 또는 런타임 세션 변경을 그대로 유지합니다.

# 관측 가능성 및 실패 요약

runWithModelFallback(...)은 로그와 사용자 대상 쿨다운 메시지에 쓰이는 시도별 세부 정보를 기록합니다.

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

구조화된 model_fallback_decision 로그는 후보가 실패하거나 건너뛰어지거나 이후 폴백이 성공할 때 평면 fallbackStep* 필드도 포함합니다. 이 필드는 시도된 전환을 명시적으로 나타내므로(fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome) 로그 및 진단 내보내기 도구가 최종 폴백도 실패한 경우에도 주 모델 실패를 재구성할 수 있습니다.

모든 후보가 실패하면 OpenClaw는 FallbackSummaryError를 던집니다. 외부 응답 실행기는 이를 사용해 "모든 모델이 일시적으로 속도 제한 중입니다" 같은 더 구체적인 메시지를 만들고, 알려진 경우 가장 이른 쿨다운 만료 시각을 포함할 수 있습니다.

해당 쿨다운 요약은 모델을 인식합니다.

• 관련 없는 모델 범위 속도 제한은 시도된 제공자/모델 체인에서 무시됩니다.
• 남은 차단이 일치하는 모델 범위 속도 제한이면 OpenClaw는 해당 모델을 아직 차단하는 마지막 일치 만료 시각을 보고합니다.

# 관련 구성

다음 항목은 Gateway 구성을 참조하세요.

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

더 넓은 모델 선택 및 폴백 개요는 모델을 참조하세요.