모델 장애 조치

OpenClaw는 두 단계로 오류를 처리합니다.

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

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

인증 저장소(키 + OAuth)

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

자세한 내용: /concepts/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).

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

회전 순서

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

명시적 구성: auth.order[provider] (설정된 경우).
구성된 프로필: auth.profiles 공급자별로 필터링됩니다.
저장된 프로필: 공급자에 대한 auth-profiles.json 항목입니다.

명시적인 순서가 구성되지 않은 경우 OpenClaw는 라운드 로빈 순서를 사용합니다.

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

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

OpenClaw는 세션당 선택한 인증 프로필을 고정하여 공급자 캐시를 따뜻하게 유지합니다. 모든 요청에 대해 회전하지 않습니다. 고정된 프로필은 다음 때까지 재사용됩니다.

세션이 재설정됩니다. (/new / /reset)
압축이 완료되었습니다(압축 횟수 증가).
프로필이 대기 중이거나 비활성화되었습니다.

/model …@<profileId>을 통한 수동 선택은 해당 세션에 대한 사용자 재정의를 설정합니다. 새 세션이 시작될 때까지 자동 순환되지 않습니다.

자동 고정 프로필(세션 라우터에 의해 선택됨)은 기본 설정으로 처리됩니다. 먼저 시도되지만 OpenClaw는 속도 제한/시간 초과로 인해 다른 프로필로 회전할 수 있습니다. 사용자가 고정한 프로필은 해당 프로필에 고정된 상태로 유지됩니다. 실패하고 모델이 대체되는 경우 구성되면 OpenClaw는 프로필을 전환하는 대신 다음 모델로 이동합니다.

OAuth가 "잃어버린 것처럼 보일" 수 있는 이유

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

auth.order[provider] = ["provider:profileId"]로 고정하거나
프로필 재정의와 함께 /model …를 통해 세션별 재정의를 사용합니다(UI/채팅 화면에서 지원하는 경우).

쿨다운

인증/비율 제한 오류(또는 다음과 같은 시간 초과로 인해 프로필이 실패하는 경우) 속도 제한과 마찬가지로 OpenClaw는 이를 쿨다운으로 표시하고 다음 프로필로 이동합니다. 형식/잘못된 요청 오류(예: Cloud Code Assist 도구 호출 ID) 검증 실패)은 장애 조치 가능한 것으로 간주되며 동일한 휴지 시간을 사용합니다.

휴지 시간은 지수 백오프를 사용합니다.

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

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

json

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

결제가 비활성화됩니다.

청구/크레딧 실패(예: "크레딧 부족"/ "크레딧 잔액 너무 낮음")는 장애 조치가 가능한 것으로 간주되지만 일반적으로 일시적이지 않습니다. 짧은 쿨다운 대신 OpenClaw는 프로필을 비활성화(더 긴 백오프 사용)로 표시하고 다음 프로필/공급자로 순환합니다.

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

json

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

기본값:

청구 백오프는 5시간에 시작되며, 청구 실패당 두 배로 증가하고 24시간으로 제한됩니다.
프로필이 24시간 동안 실패하지 않으면 백오프 카운터가 재설정됩니다(구성 가능).

모델 대체

공급자의 모든 프로필이 실패하면 OpenClaw는 다음 모델로 이동합니다. agents.defaults.model.fallbacks. 이는 인증 실패, 비율 제한 등에 적용됩니다. 프로필 회전을 소진한 시간 초과(다른 오류로 인해 대체가 진행되지 않음)

모델 재정의(후크 또는 CLI)로 실행이 시작되면 폴백은 계속해서 종료됩니다. agents.defaults.model.primary 구성된 폴백을 시도한 후.

모델 장애 조치 ​

인증 저장소(키 + OAuth) ​

프로필 ID ​

회전 순서 ​

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

OAuth가 "잃어버린 것처럼 보일" 수 있는 이유 ​

쿨다운 ​

결제가 비활성화됩니다. ​

모델 대체 ​

관련 구성 ​