모델 장애 조치

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:[email protected]).

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

순환 순서

프로바이더에 여러 프로필이 있으면 OpenClaw는 다음과 같은 순서로 선택합니다:

명시적 설정: auth.order[provider] (설정된 경우).
설정된 프로필: auth.profiles에서 프로바이더로 필터링.
저장된 프로필: auth-profiles.json에서 해당 프로바이더의 항목.

명시적 순서가 설정되지 않으면 OpenClaw는 라운드 로빈 순서를 사용합니다:

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

세션 고정 (캐시 친화적)

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

세션 초기화 (/new / /reset)
압축 완료 (압축 카운트 증가)
프로필이 쿨다운/비활성 상태

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

자동 고정된 프로필(세션 라우터가 선택)은 선호로 처리됩니다: 먼저 시도하지만, 속도 제한/타임아웃 시 다른 프로필로 순환할 수 있습니다. 사용자가 고정한 프로필은 해당 프로필에 잠금됩니다. 실패하고 모델 폴백이 설정되어 있으면 프로필을 전환하는 대신 다음 모델로 이동합니다.

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

같은 프로바이더에 OAuth 프로필과 API 키 프로필이 모두 있으면, 고정하지 않는 한 라운드 로빈이 메시지 간에 전환할 수 있습니다. 단일 프로필을 강제하려면:

auth.order[provider] = ["provider:profileId"]로 고정하거나,
UI/채팅 환경이 지원하는 경우 /model …로 프로필 오버라이드와 함께 세션별 오버라이드를 사용하세요.

쿨다운

인증/속도 제한 오류(또는 속도 제한처럼 보이는 타임아웃)로 프로필이 실패하면 OpenClaw가 쿨다운으로 표시하고 다음 프로필로 이동합니다. 포맷/잘못된 요청 오류(예: Cloud Code Assist 도구 호출 ID 검증 실패)도 장애 조치 대상으로 처리되며 동일한 쿨다운을 사용합니다. Unhandled stop reason: error, stop reason: error, reason: error 같은 OpenAI 호환 중지 이유 오류는 타임아웃/장애 조치 신호로 분류됩니다.

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

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

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

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

과금 비활성화

과금/크레딧 실패(예: “insufficient credits” / “credit balance too low”)는 장애 조치 대상이지만 보통 일시적이지 않습니다. 짧은 쿨다운 대신 OpenClaw가 프로필을 비활성화(더 긴 백오프)로 표시하고 다음 프로필/프로바이더로 순환합니다.

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

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

기본값:

과금 백오프는 5시간에서 시작, 과금 실패마다 두 배, 24시간 상한.
프로필이 24시간 동안 실패하지 않으면 백오프 카운터 초기화 (설정 가능).

모델 폴백

프로바이더의 모든 프로필이 실패하면 OpenClaw가 agents.defaults.model.fallbacks의 다음 모델로 이동합니다. 이는 인증 실패, 속도 제한, 프로필 순환을 소진한 타임아웃에 적용됩니다 (다른 오류는 폴백을 진행하지 않음).

모델 오버라이드(훅 또는 CLI)로 실행이 시작된 경우에도 설정된 폴백을 시도한 후 agents.defaults.model.primary에서 폴백이 종료됩니다.