모델 장애 조치

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", 선택된 원본 모델을 기록합니다. 이 자동 오버라이드는 모든 메시지에서 기본 모델을 탐색하지 않고도 구성된 대체 체인을 계속 따라갈 수 있지만, OpenClaw는 구성된 원본을 주기적으로 다시 탐색하고 복구되면 자동 오버라이드를 지웁니다. /new, /reset, sessions.reset도 자동 소스 오버라이드를 지웁니다. 명시적인 heartbeat.model 없이 실행되는 Heartbeat는 원본이 현재 구성된 기본값과 더 이상 일치하지 않을 때 직접 자동 오버라이드를 지웁니다.
• 사용자 세션 오버라이드: /model, 모델 선택기, session_status(model=...), sessions.patch는 modelOverrideSource: "user"를 기록합니다. 이는 정확한 세션 선택입니다. 선택된 제공자/모델이 응답을 생성하기 전에 실패하면, OpenClaw는 관련 없는 구성된 대체 모델로 답변하는 대신 실패를 보고합니다.
• 레거시 세션 오버라이드: 오래된 세션 항목에는 modelOverrideSource 없이 modelOverride가 있을 수 있습니다. OpenClaw는 명시적인 이전 선택이 조용히 대체 동작으로 변환되지 않도록 이를 사용자 오버라이드로 취급합니다.
• Cron 페이로드 모델: cron 작업 payload.model / --model은 작업 기본 모델이지 사용자 세션 오버라이드가 아닙니다. 작업이 payload.fallbacks를 제공하지 않는 한 구성된 대체 모델을 사용하며, payload.fallbacks: []는 cron 실행을 엄격하게 만듭니다.

자동 대체 기본 모델 탐색 간격은 5분이며 구성할 수 없습니다. OpenClaw는 실패 중인 기본 모델을 매 턴마다 재시도하지 않도록 세션 및 기본 모델별 최근 탐색을 기억합니다. OpenClaw는 세션이 대체 모델로 이동할 때 표시되는 알림을 보내고, 선택된 기본 모델로 돌아올 때 또 다른 알림을 보냅니다. 고정된 대체 턴마다 알림을 반복하지는 않습니다.

인증 실패 건너뛰기 캐시

기본적으로 모든 새 턴은 기존 대체 재시도 동작을 유지합니다. OpenClaw는 최근에 auth 또는 auth_permanent로 실패한 비기본 후보를 포함해 구성된 각 대체 후보를 다시 시도합니다.

반복되는 인증 실패를 억제하고 싶은 운영자는 다음으로 옵트인할 수 있습니다.

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

활성화되면 OpenClaw는 인증 클래스 실패 후 비기본 대체 후보에 대해 메모리 내 세션 범위 건너뛰기 마커를 기록합니다. 마커는 세션 ID, 제공자, 모델을 기준으로 키가 지정됩니다. 기본 후보는 절대 건너뛰지 않으므로 명시적인 사용자 모델 선택은 실제 인증 오류를 계속 드러냅니다. 캐시는 프로세스 로컬이며 Gateway 재시작 시 지워집니다.

값은 밀리초 단위 TTL입니다. 0 또는 설정되지 않은 값은 캐시를 비활성화합니다. 양수 값은 1초에서 10분 사이로 제한됩니다.

사용자에게 표시되는 대체 알림

세션이 자동 선택된 대체 모델로 이동하면 OpenClaw는 동일한 응답 표면에 상태 알림을 보냅니다.

↪️ Model Fallback: <fallback> (selected <primary>; <reason>)

나중 탐색이 성공하고 세션이 선택된 기본 모델로 돌아오면 OpenClaw는 다음을 보냅니다.

↪️ Model Fallback cleared: <primary> (was <fallback>)

이 알림은 어시스턴트 콘텐츠가 아니라 운영 메시지입니다. 가능한 경우 부작용만 있는 턴을 포함해 상태 변경마다 한 번 전달되지만, 고정된 대체 턴에서는 반복되지 않습니다. 전달은 일반 소스 응답 억제를 우회하며, 알림은 스레드형 채널의 첫 번째 어시스턴트 응답 슬롯을 소비하지 않고, 텍스트 음성 변환 및 커밋 추출에서 제외됩니다.

인증 저장소(키 + OAuth)

OpenClaw는 API 키와 OAuth 토큰 모두에 인증 프로필을 사용합니다.

• 비밀 정보와 런타임 인증 라우팅 상태는 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite에 있습니다.
• 구성 auth.profiles / auth.order는 메타데이터 + 라우팅 전용입니다(비밀 정보 없음).
• 레거시 가져오기 전용 OAuth 파일: ~/.openclaw/credentials/oauth.json(첫 사용 시 에이전트별 인증 저장소로 가져옴).
• 레거시 auth-profiles.json, auth-state.json, 에이전트별 auth.json 파일은 openclaw doctor --fix로 가져옵니다.

자세한 내용: OAuth

자격 증명 유형:

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

프로필 ID

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

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

프로필은 에이전트별 openclaw-agent.sqlite 인증 프로필 저장소에 있습니다.

순환 순서

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

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

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

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

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

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

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

OpenAI Codex 구독과 API 키 백업

OpenAI 에이전트 모델의 경우 인증과 런타임은 분리됩니다. openai/gpt-*는 Codex 하네스에 유지되며, 인증은 Codex 구독 프로필과 OpenAI API 키 백업 사이에서 순환할 수 있습니다.

사용자에게 표시되는 순서에는 auth.order.openai를 사용합니다.

{  auth: {    order: {      openai: ["openai:user@example.com", "openai:api-key-backup"],    },  },}

ChatGPT/Codex OAuth 프로필과 OpenAI API 키 프로필 모두에 openai:*를 사용합니다. 구독이 Codex 사용량 제한에 도달하면, OpenClaw는 Codex가 제공하는 경우 정확한 재설정 시간을 기록하고, 순서상 다음 인증 프로필을 시도하며, 실행은 Codex 하네스 내부에 유지합니다. 재설정 시간이 지나면 구독 프로필은 다시 적격 상태가 되고 다음 자동 선택에서 다시 돌아갈 수 있습니다.

해당 세션에서 한 계정/키를 강제로 사용하려는 경우에만 사용자 고정 프로필을 사용합니다. 사용자 고정 프로필은 의도적으로 엄격하며 조용히 다른 프로필로 이동하지 않습니다.

쿨다운

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

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

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

상태는 에이전트별 SQLite 인증 상태의 usageStats 아래에 저장됩니다.

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

결제 비활성화

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

상태는 에이전트별 SQLite 인증 상태에 저장됩니다.

{  "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로 이를 조정할 수 있습니다.

실행이 구성된 기본 primary, cron 작업 primary, 명시적 폴백이 있는 에이전트 primary, 또는 자동 선택된 폴백 오버라이드에서 시작되면 OpenClaw는 일치하는 구성된 폴백 체인을 따라갈 수 있습니다. 명시적 폴백이 없는 에이전트 primary와 명시적 사용자 선택(예: /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가 모든 메시지마다 알려진 불량 primary를 프로브하지 않게 합니다. 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). 따라서 로그 및 진단 내보내기 도구는 최종 폴백도 실패한 경우에도 primary 실패를 재구성할 수 있습니다.

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

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

• 관련 없는 모델 범위 속도 제한은 시도된 공급자/모델 체인에서 무시됩니다.
• 남은 차단이 일치하는 모델 범위 속도 제한인 경우, 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 라우팅

더 광범위한 모델 선택 및 폴백 개요는 모델을 참조하세요.